arkgate 2.11.0 → 2.12.0

package/bin/lib/agent-gates.mjs

@@ -1,30 +1,8 @@
 /**
- * Agent gate install, migrate, Codex, skills, adoption (roadmap #11).
+ * Agent gate install, migrate, Codex, skills, adoption — public surface.
+ * Implementation lives in focused modules under bin/lib/.
  */
-import { createRequire } from 'node:module';
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import {
-  arkCommand,
-  detectPackageManager,
-  execCommandParts,
-  execRunner,
-  presentLockfiles,
-  usableTypescript,
-  typescriptUsabilityHint,
-  DEFAULT_INTENT_PREFIXES,
-  DEFAULT_LAYER_DIRECTORIES,
-  DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
-  DEFAULT_RULES,
-  createElevenLayerConfig,
-  applyFrameworkLayoutOverlays,
-} from '../ark-shared.mjs';
-import { CORE_LAYER_NAMES } from './core-layers.mjs';
-import { falseGreenAdoptionGap } from './field-install.mjs';
-import {
+export {
   assessCodexHomeMcp,
   codexArkBlockHasPreferredBin,
   codexArkBlockNeedsRewrite,
@@ -41,337 +19,15 @@ import {
   wireCodexMcp,
 } from './codex-home.mjs';
 
-// Re-export Codex home API for existing consumers (ark-check, tests).
 export {
-  assessCodexHomeMcp,
-  codexArkBlockHasPreferredBin,
-  codexArkBlockNeedsRewrite,
-  codexConfigPath,
-  codexPrimaryTable,
-  codexProjectSlug,
-  codexPromptsDir,
-  codexScopedTableForRoot,
-  extractCodexArkRootFromToml,
-  extractCodexRootFromBlock,
-  isTempOrUpgradeRoot,
-  listCodexArkServerTables,
-  upsertCodexMcpTable,
-  wireCodexMcp,
-};
-
-/** Package root (parent of bin/). All modules live under bin/lib/. */
-const __packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-const __arkCheckCli = path.join(__packageRoot, 'bin', 'ark-check.mjs');
-
-export function readJson(file) {
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
-}
-
-export function readPackageJson(root) {
-  const file = path.join(root, 'package.json');
-  if (!fs.existsSync(file)) return null;
-  return readJson(file);
-}
-
-export function hasCheckArchitectureScript(root) {
-  const pkg = readPackageJson(root);
-  return Boolean(pkg?.scripts?.['check:architecture']);
-}
-
-/**
- * Whether package.json scripts already expose a typecheck-like command.
- * Shared by deploy-path quality + typecheck bootstrap (single definition).
- * @param {Record<string, unknown>|null|undefined} scripts
- */
-export function packageScriptsHaveTypecheck(scripts) {
-  if (!scripts || typeof scripts !== 'object') return false;
-  return Boolean(
-    (typeof scripts.typecheck === 'string' && scripts.typecheck.trim()) ||
-      (typeof scripts['type-check'] === 'string' && scripts['type-check'].trim()) ||
-      (typeof scripts['check:types'] === 'string' && scripts['check:types'].trim()) ||
-      (typeof scripts.tsc === 'string' && /\btsc\b/.test(scripts.tsc))
-  );
-}
-
-/**
- * Root package (and shallow nested packages) already have a typecheck script.
- * Does not scan CI or framework configs — only package.json scripts.
- * @param {string} root
- */
-export function treeHasTypecheckScript(root) {
-  const pkg = readPackageJson(root);
-  if (packageScriptsHaveTypecheck(pkg?.scripts)) return true;
-  try {
-    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
-      const candidates = [path.join(root, entry.name)];
-      try {
-        for (const child of fs.readdirSync(path.join(root, entry.name), { withFileTypes: true })) {
-          if (child.isDirectory() && !child.name.startsWith('.')) {
-            candidates.push(path.join(root, entry.name, child.name));
-          }
-        }
-      } catch {
-        /* ignore */
-      }
-      for (const dir of candidates) {
-        const pj = path.join(dir, 'package.json');
-        if (!fs.existsSync(pj)) continue;
-        try {
-          const nested = JSON.parse(fs.readFileSync(pj, 'utf8'));
-          if (packageScriptsHaveTypecheck(nested.scripts)) return true;
-        } catch {
-          /* ignore */
-        }
-      }
-    }
-  } catch {
-    /* ignore */
-  }
-  return false;
-}
-
-/**
- * Add a conservative `typecheck` script when the host has a TS/JS project config
- * but no typecheck-like script yet. Never overwrites an existing script.
- *
- * @param {string} root
- * @param {{ write?: boolean }} [opts]
- * @returns {{
- *   changed: boolean,
- *   reason: 'added' | 'already' | 'no-tsconfig' | 'no-package-json',
- *   script?: string,
- * }}
- */
-export function ensureTypecheckScript(root, opts = {}) {
-  const write = opts.write !== false;
-  const hasTsconfig =
-    fs.existsSync(path.join(root, 'tsconfig.json')) ||
-    fs.existsSync(path.join(root, 'jsconfig.json'));
-  if (!hasTsconfig) return { changed: false, reason: 'no-tsconfig' };
-
-  const pkgPath = path.join(root, 'package.json');
-  if (!fs.existsSync(pkgPath)) return { changed: false, reason: 'no-package-json' };
-
-  if (treeHasTypecheckScript(root)) {
-    return { changed: false, reason: 'already' };
-  }
-
-  const pkg = readPackageJson(root) || {};
-  const scripts =
-    pkg.scripts && typeof pkg.scripts === 'object' ? { ...pkg.scripts } : {};
-  const script = 'tsc --noEmit';
-  scripts.typecheck = script;
-  if (write) {
-    const next = { ...pkg, scripts };
-    fs.writeFileSync(pkgPath, `${JSON.stringify(next, null, 2)}\n`);
-  }
-  return { changed: true, reason: 'added', script };
-}
-
-export const REQUIRED_GATE_FILES = [
-  'AGENTS.md',
-  '.mcp.json',
-];
-const REQUIRED_GATE_WORKFLOW = '.github/workflows/*.yml running ark-check';
-
-export function hasArkWorkflow(root) {
-  const workflowsDir = path.join(root, '.github', 'workflows');
-  if (!fs.existsSync(workflowsDir)) return false;
-  return fs
-    .readdirSync(workflowsDir)
-    .filter((file) => /\.ya?ml$/i.test(file))
-    .some((file) => {
-      try {
-        const content = fs.readFileSync(path.join(workflowsDir, file), 'utf8');
-        return (
-          /\bark-check\b/.test(content) ||
-          /\bcheck:architecture\b/.test(content) ||
-          /\buses\s*:\s*['"]?[^'"\s#]+\/arkgate@/i.test(content)
-        );
-      } catch {
-        return false;
-      }
-    });
-}
-
-export function missingGates(root) {
-  const missing = REQUIRED_GATE_FILES.filter(
-    (relativePath) => !fs.existsSync(path.join(root, relativePath))
-  );
-  if (!hasArkWorkflow(root)) missing.push(REQUIRED_GATE_WORKFLOW);
-  return missing;
-}
-
-export function checkArchitectureScriptSnippet(root) {
-  // The package manager's runner resolves the installed binary; `node bin/ark-check.mjs`
-  // only works inside Ark's own repo. Package-manager aware so a pnpm/yarn repo isn't
-  // handed an `npx` alias that violates its "never npx" policy.
-  return `"check:architecture": "${arkCheckCommand(root)}"`;
-}
-export function ensureDirForFile(file) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-}
-
-/**
- * True when AGENTS.md is wholly Ark-owned (header is Ark Enforcement).
- * Project guides that merely append an Ark section must remain non-Ark so --force
- * never wipes them.
- */
-export function isArkAgentsContent(text) {
-  if (typeof text !== 'string' || !text.trim()) return false;
-  const head = text.trimStart().slice(0, 120);
-  return /^#\s*Ark(Gate)?\s+Enforcement\b/.test(head);
-}
-
-export function writeTemplate(root, relativePath, content, force) {
-  const fullPath = path.join(root, relativePath);
-  if (relativePath === 'AGENTS.md' && fs.existsSync(fullPath)) {
-    let existing = '';
-    try {
-      existing = fs.readFileSync(fullPath, 'utf8');
-    } catch {
-      existing = '';
-    }
-    if (existing && !isArkAgentsContent(existing)) {
-      // Never clobber a project-owned AGENTS.md — even with --force.
-      // If Ark section not present yet, merge once; subsequent runs leave it alone.
-      const hasArkSection =
-        /#\s*Ark(Gate)?\s+Enforcement\b/.test(existing) ||
-        /ark\.config\.json is authoritative/i.test(existing);
-      if (force && isArkAgentsContent(content) && !hasArkSection) {
-        try {
-          const merged = `${existing.replace(/\s*$/, '')}\n\n---\n\n${content}`;
-          ensureDirForFile(fullPath);
-          fs.writeFileSync(fullPath, merged);
-          return { relativePath, status: 'merged' };
-        } catch {
-          return { relativePath, status: 'failed' };
-        }
-      }
-      return { relativePath, status: 'skipped-non-ark' };
-    }
-    if (!force && isArkAgentsContent(existing)) {
-      return { relativePath, status: 'skipped' };
-    }
-  } else if (fs.existsSync(fullPath) && !force) {
-    return { relativePath, status: 'skipped' };
-  }
-  try {
-    ensureDirForFile(fullPath);
-    fs.writeFileSync(fullPath, content);
-    return { relativePath, status: 'written' };
-  } catch {
-    return { relativePath, status: 'failed' };
-  }
-}
-
-/**
- * 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.
- */
-export async function loadTypeScript(root) {
-  const { createRequire } = await import('node:module');
-  const loaders = [];
-  try {
-    const req = createRequire(path.join(root, 'package.json'));
-    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 req = createRequire(__arkCheckCli);
-    loaders.push({
-      label: 'arkgate',
-      load: () => req('typescript'),
-      resolvePath: () => {
-        try {
-          return req.resolve('typescript');
-        } catch {
-          return null;
-        }
-      },
-    });
-  } catch {
-    /* ark install tree unavailable */
-  }
-  loaders.push({
-    label: 'import',
-    load: async () => {
-      const m = await import('typescript');
-      return m;
-    },
-    resolvePath: () => null,
-  });
+  PREFERRED_MCP_BIN,
+  claudeSettings,
+  grokHooks,
+  grokProjectConfig,
+} from './hook-templates.mjs';
 
-  let projectRejected = null;
-  const triedPaths = new Set();
-  for (const { label, load, resolvePath } of loaders) {
-    try {
-      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);
+export { detectWritePathCapabilities } from './write-path-detect.mjs';
 
-      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 */
-    }
-  }
-  return null;
-}
-
-/**
- * Args for every emitted `ark-check` (AGENTS.md, package.json, Cursor rule, CI).
- * If `.ark-baseline.json` exists, include `--baseline` so agent/local/CI paths
- * match the ratchet — otherwise agents re-fail on frozen debt (field-test bug).
- */
-export function checkArgsForRoot(root, { requireGates = false } = {}) {
-  const baselineFlag = fs.existsSync(path.join(root, '.ark-baseline.json'))
-    ? ' --baseline .ark-baseline.json'
-    : '';
-  const profile = requireGates ? '--strict' : '--strict-config';
-  return `--root . --config ark.config.json ${profile}${baselineFlag}`;
-}
-
-// Field-install helpers live in field-install.mjs (keep agent-gates scannable).
-// Re-export for callers that already import from this module.
 export {
   ensureBaselineFlagInCheckCommand,
   syncBaselineIntoCheckSurfaces,
@@ -382,1748 +38,66 @@ export {
   falseGreenAdoptionGap,
 } from './field-install.mjs';
 
-export function packageManager(root) {
-  // CI always require-gates; baseline follows checkArgsForRoot.
-  const checkArgs = checkArgsForRoot(root, { requireGates: true });
-  // Same detection as every emitted command (execRunner): honors the packageManager field and
-  // won't let a stray pnpm-lock.yaml hijack an npm project (package-lock.json wins the tie).
-  const pm = detectPackageManager(root);
-  if (pm === 'pnpm') {
-    return {
-      cache: 'pnpm',
-      setup: ['corepack enable'],
-      install: 'pnpm install --frozen-lockfile',
-      // Same runner as execRunner(): skip pnpm's verify-deps gate (ERR_PNPM_IGNORED_BUILDS).
-      run: `pnpm --config.verify-deps-before-run=false exec ark-check ${checkArgs}`,
-    };
-  }
-  if (pm === 'yarn') {
-    return {
-      cache: 'yarn',
-      setup: ['corepack enable'],
-      install: 'yarn install --frozen-lockfile',
-      run: `yarn ark-check ${checkArgs}`,
-    };
-  }
-  // Monorepo hosts (e.g. Next app under frontend/) often have a root package.json only for
-  // arkgate while real app deps live in frontend/package.json. Install both so CI can resolve
-  // the tree; ark-check itself only needs the root arkgate install.
-  const frontendPkg = fs.existsSync(path.join(root, 'frontend', 'package.json'));
-  const rootInstall = fs.existsSync(path.join(root, 'package-lock.json')) ? 'npm ci' : 'npm install';
-  const install = frontendPkg
-    ? `${rootInstall} && (cd frontend && ${fs.existsSync(path.join(root, 'frontend', 'package-lock.json')) ? 'npm ci' : 'npm install'})`
-    : rootInstall;
-  return {
-    cache: 'npm',
-    setup: [],
-    install,
-    run: `npx ark-check ${checkArgs}`,
-  };
-}
-
-// The runner prefix (npx / pnpm exec / yarn) is added per project by arkCheckCommand
-// so a pnpm-only repo never gets an `npx` instruction — see execRunner() in ark-shared.mjs.
-export function arkCheckCommand(root) {
-  return arkCommand(root, 'ark-check', checkArgsForRoot(root));
-}
-
-// Canonical agent contract. AGENTS.md and the Cursor rule both derive from this single
-// source so the steps can never drift out of sync between the two files. `steps(checkCommand)`
-// is a builder because the check command's runner prefix varies with the package manager.
-const AGENT_CONTRACT = {
-  manifestResource: 'ark://manifest',
-  steps: (checkCommand) => [
-    `Read the Ark contract from \`ark://manifest\` when the MCP server is available.`,
-    `Keep source files inside the layer boundaries declared in \`ark.config.json\`.`,
-    `Do not bypass Ark publishers, event contracts, or source metadata for runtime mutations.`,
-    `After edits, run \`${checkCommand}\`.`,
-    `If Ark reports violations, fix the architecture instead of weakening the gate.`,
-  ],
-  // Cursor-only guidance: the write-time validate_code tool is available in
-  // Cursor's runtime but has no equivalent in a plain AGENTS.md read.
-  cursorValidateStep: `Validate the full post-edit file content with the \`validate_code\` tool before writing whenever your runtime supports it.`,
-};
-
-export function layerPlacementTable() {
-  const rows = DEFAULT_INTENT_PREFIXES.map((entry) => {
-    const dirs = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? [])
-      .map((directory) => `\`${directory}/\``)
-      .join(', ');
-    return `| ${entry.layer} | ${dirs} | ${entry.prefixes.map((p) => `\`${p}\``).join(', ')} |`;
-  }).join('\n');
-  return `| Layer | Conventional directories (under the source root) | Intent prefixes |
-|-------|---------------------------------------------------|-----------------|
-${rows}`;
-}
-
-export function agentInstructions(root) {
-  const checkCmd = arkCheckCommand(root);
-  const startCmd = arkCommand(root, 'ark', 'start');
-  const doctorCmd = arkCommand(root, 'ark-check', '--doctor');
-  const steps = AGENT_CONTRACT.steps(checkCmd)
-    .map((step, index) => `${index + 1}. ${step}`)
-    .join('\n');
-  return `# Ark Enforcement
-
-## Default agent flow (if unsure, do only this)
-
-1. If \`ark.config.json\` is missing: run \`${startCmd}\` once.
-2. For adoption / cleanup / “make architecture sound”: run the **\`/ark-autopilot\`** skill
-   (origin report → adopt → plan → safe fixes → gates). Do **not** invent a second
-   architecture curriculum outside the routing table below — when a trigger matches, use
-   that skill; when unsure, stay on autopilot.
-3. Status anytime: \`${doctorCmd}\` (status light + next action — not a mode picker).
-4. After ordinary feature edits: run \`${checkCmd}\`. On violations → **\`/ark-fix\`** (or
-   \`/ark-place\` for new files, \`/ark-contract\` only if the contract itself is wrong).
-
-Skills are **dual-engine**: deterministic CLI sensors + exploratory read of *this* repo — not JSON-only wrappers.
-When a skill says **STOP — do not continue this skill as complete**, stop and invoke the named handoff skill.
-
-### Subagent fan-out
-If the host supports **parallel subagents**, skills may ask you to fan out **read-only**
-scouts (disjoint path scopes) and merge in the parent. If the host does **not**,
-**fall back to sequential** — one cluster/step at a time. Never parallel-write the same
-files; never weaken the gate via subagents.
-
-## Skill routing (triggers → skill)
-
-| When | Invoke |
-|------|--------|
-| Unsure / make architecture sound | **/ark-autopilot** (default) |
-| Need map / opportunities only (no apply) | \`/ark-explore\` |
-| Greenfield shape / empty tree | \`/ark-architect\` |
-| Brownfield / wrong contract / false-green | \`/ark-adopt\` then \`/ark-contract\` if globs wrong |
-| Edit \`ark.config.json\` layers/rules/intents | \`/ark-contract\` |
-| New file “where does this go?” | \`/ark-place\` |
-| Gate violation on a change | \`/ark-fix\` |
-| Drive plan to goal.met | \`/ark-loop\` |
-| Deep coverage + ranked audit | \`/ark-coverage\` |
-| Design trade-offs (no package LLM) | \`/ark-think\` |
-| Explain / HTML report tour | \`/ark-explain\` |
-| Bump arkgate + refresh hosts | \`/ark-upgrade\` |
-| Optional runtime kernel migrate | \`/ark-runtime\` |
-
-## Before editing TypeScript or JavaScript source files
-
-${steps}
-
-## Where new code belongs
-
-\`ark.config.json\` is authoritative for this project. When creating a NEW kind of code
-that no existing layer covers (a saga, a background job, a read model, ...), use the
-default 11-layer placement below and add the layer to \`ark.config.json\` — do not invent
-an ungoverned location:
-
-${layerPlacementTable()}
-
-The project is only considered Ark-enforced when the write gate and CI gate pass
-(runtime path only if this project opted into the kernel).
-`;
-}
-
-export function mcpJson(root) {
-  return `${JSON.stringify({
-    mcpServers: {
-      ark: {
-        type: 'stdio',
-        // Prefer arkgate-mcp; ark-mcp alias still works for one major.
-        ...execCommandParts(root, PREFERRED_MCP_BIN, ['--root', '.', '--config', 'ark.config.json']),
-      },
-    },
-  }, null, 2)}\n`;
-}
-
-// Sample for docs/ — `ark-check --install-agent-gates --tools codex` auto-merges the real
-// block (with absolute paths) into ~/.codex/config.toml. This copy is a reference only, so
-// 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.
-export function codexTomlSnippet(root) {
-  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
-    '--root',
-    '/absolute/path/to/project',
-    '--config',
-    '/absolute/path/to/project/ark.config.json',
-  ]);
-  const argsToml = args.map((value) => `"${value}"`).join(', ');
-  return `# Add to ~/.codex/config.toml (or $CODEX_HOME/config.toml), then RESTART Codex —
-# it does not hot-load MCP servers. Use ABSOLUTE paths: config.toml is global, so
-# "." would resolve against Codex's launch dir, not this project. Prefer:
-#   ark-check --install-agent-gates --tools codex   (auto-merges the absolute paths)
-[mcp_servers.ark]
-command = "${command}"
-args = [${argsToml}]
-`;
-}
-
-/**
- * Compact always-on rule for instruction-tier hosts (Windsurf, Cline, GitHub Copilot,
- * Kiro, ...): agents that read a project rule file but have no MCP tools or hooks.
- * Derived from the same AGENT_CONTRACT as AGENTS.md and the Cursor rule so the steps
- * can never drift; points at AGENTS.md for the full placement table.
- */
-export function instructionRule(root) {
-  const steps = AGENT_CONTRACT.steps(arkCheckCommand(root))
-    .map((step, index) => `${index + 1}. ${step}`)
-    .join('\n');
-  return `# Ark architecture contract
-
-This project's architecture is governed by Ark (\`ark.config.json\` is authoritative).
-Before writing or editing TypeScript or JavaScript source files:
-
-${steps}
-
-See \`AGENTS.md\` for the full contract and the layer placement table.
-`;
-}
-
-export function cursorRule(root) {
-  return `---
-description: Ark architecture contract
-alwaysApply: true
----
-
-Before writing or editing TypeScript or JavaScript source files, read the
-\`${AGENT_CONTRACT.manifestResource}\` resource from the \`ark\` MCP server when available.
-
-${AGENT_CONTRACT.cursorValidateStep} After edits, run:
-
-\`\`\`bash
-${arkCheckCommand(root)}
-\`\`\`
-
-If Ark reports violations, fix the architecture instead of bypassing the gate.
-`;
-}
-
-// Default CI Node when the project declares nothing. A current LTS, NOT the
-// oldest supported: the npm-ci-lockfile-mismatch failure only happens when CI's
-// npm is OLDER than the npm that wrote the lockfile, so defaulting high is safer.
-const DEFAULT_CI_NODE_VERSION = '22';
-
-// Decide the Node the generated CI should use, preferring the project's own
-// declaration so CI's npm matches the dev's (a mismatch makes `npm ci` fail with
-// "missing from lock file" — a red gate unrelated to architecture). In order:
-//   1. .nvmrc / .node-version → setup-node's node-version-file (exact, best)
-//   2. package.json engines.node → its concrete major
-//   3. a current-LTS default
-export function detectCiNode(root) {
-  for (const file of ['.nvmrc', '.node-version']) {
-    if (fs.existsSync(path.join(root, file))) return { kind: 'file', value: file };
-  }
-  const enginesNode = readPackageJson(root)?.engines?.node;
-  if (typeof enginesNode === 'string') {
-    const major = enginesNode.match(/\d+/)?.[0];
-    if (major) return { kind: 'version', value: major };
-  }
-  return { kind: 'default', value: DEFAULT_CI_NODE_VERSION };
-}
-
-/**
- * @param {{ name: string, install: string, run: string, cache: string, setup: string[] }} pm
- * @param {{ kind: string, value: string }} ciNode
- * @param {{ hasLintScript?: boolean, hasTypecheckScript?: boolean }} [quality]
- */
-export function githubWorkflow(pm, ciNode, quality = {}) {
-  // pnpm/yarn setup (corepack enable) MUST run before actions/setup-node so the package
-  // manager is on PATH when setup-node's `cache: pnpm|yarn` tries to resolve the store —
-  // otherwise the cache step fails on a fresh runner ("Unable to locate executable file: pnpm").
-  const setupSteps = pm.setup.map((command) => `      - run: ${command}`).join('\n');
-  // node-version-file keeps CI locked to the dev's exact toolchain; an explicit
-  // version comes from engines.node; the default carries a hint for the mismatch
-  // symptom since we can't know which npm wrote the lockfile.
-  const nodeSetup =
-    ciNode.kind === 'file'
-      ? `          node-version-file: ${ciNode.value}`
-      : ciNode.kind === 'version'
-        ? `          node-version: '${ciNode.value}'`
-        : `          # If the install step fails with "missing from lock file" / lockfile out
-          # of sync, your local package manager is newer than this Node's — add a
-          # .nvmrc with your Node version so CI matches the dev environment.
-          node-version: '${ciNode.value}'`;
-  // When package.json already has lint/typecheck, emit CI steps so deploy-path
-  // honesty matches local scripts (Next/CRA often run these in production build).
-  const install = pm.install || '';
-  const runPrefix = install.startsWith('pnpm')
-    ? 'pnpm run'
-    : install.startsWith('yarn')
-      ? 'yarn'
-      : install.startsWith('bun')
-        ? 'bun run'
-        : 'npm run';
-  const qualityBlock = [
-    quality.hasTypecheckScript
-      ? `      - name: Typecheck\n        run: ${runPrefix} typecheck`
-      : '',
-    quality.hasLintScript ? `      - name: Lint\n        run: ${runPrefix} lint` : '',
-  ]
-    .filter(Boolean)
-    .join('\n');
-  return `name: Ark architecture gate
-
-on:
-  pull_request:
-  push:
-    branches: [main, master]
-
-jobs:
-  ark-check:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-${setupSteps ? `${setupSteps}\n` : ''}      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-${nodeSetup}
-          cache: ${pm.cache}
-      - name: Install dependencies
-        run: ${pm.install}
-${qualityBlock ? `${qualityBlock}\n` : ''}      - name: Ark architecture check
-        run: ${pm.run}
-`;
-}
-
-export function claudeSettings(root) {
-  const runner = execRunner(root);
-  return `${JSON.stringify({
-    hooks: {
-      // Inject the contract at session start so the agent knows the architecture from
-      // the first token. Project-scoped by design; --session-context is also a silent
-      // no-op when no ark.config.json exists, so it can never leak into other projects.
-      SessionStart: [
-        {
-          hooks: [
-            {
-              type: 'command',
-              command: `${runner} ${PREFERRED_MCP_BIN} --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
-            },
-          ],
-        },
-      ],
-      PreToolUse: [
-        {
-          matcher: 'Write|Edit|MultiEdit',
-          hooks: [
-            {
-              type: 'command',
-              // W4: --hook-repair emits ARK_REPAIR_JSON / ARK_AUTOPATCH_JSON on deny
-              // (still exit 2 — never silent write). Omit --hook-repair for reject-only prose.
-              command: `${runner} ${PREFERRED_MCP_BIN} --hook --hook-repair --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
-            },
-          ],
-        },
-      ],
-    },
-  }, null, 2)}\n`;
-}
-
-// Grok Build project config: MCP registration (commit-friendly relative paths — unlike
-// Codex's global config.toml, Grok loads .grok/config.toml from the project).
-export function grokProjectConfig(root) {
-  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
-    '--root',
-    '.',
-    '--config',
-    'ark.config.json',
-  ]);
-  const argsToml = args.map((value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).join(', ');
-  return `# Generated by ark-check --install-agent-gates (Grok Build project scope).
-# Restart Grok (or /mcps → refresh) after changes. Also loads repo-root .mcp.json.
-[mcp_servers.ark]
-command = "${command.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"
-args = [${argsToml}]
-`;
-}
-
-// Grok Build hooks: same arkgate-mcp contracts as Claude. Grok sets both
-// GROK_WORKSPACE_ROOT and CLAUDE_PROJECT_DIR (Claude-compatible alias). Prefer
-// GROK_* with fallback so hooks still work if only one is present.
-// Matcher keeps Claude names (Write|Edit|MultiEdit) and Grok natives
-// (write|search_replace) — Grok aliases both directions.
-export function grokHooks(root) {
-  const runner = execRunner(root);
-  // Nested defaults: Grok native → Claude alias → project cwd (hook cwd is the workspace).
-  const grokRoot = '${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}';
-  return `${JSON.stringify({
-    hooks: {
-      SessionStart: [
-        {
-          hooks: [
-            {
-              type: 'command',
-              timeout: 30,
-              command: `${runner} ${PREFERRED_MCP_BIN} --session-context --root "${grokRoot}" --config ark.config.json`,
-            },
-          ],
-        },
-      ],
-      PreToolUse: [
-        {
-          matcher: 'Write|Edit|MultiEdit|write|search_replace',
-          hooks: [
-            {
-              type: 'command',
-              timeout: 30,
-              // W4: --hook-repair → structured autoPatch on deny (hard block still).
-              command: `${runner} ${PREFERRED_MCP_BIN} --hook --hook-repair --root "${grokRoot}" --config ark.config.json`,
-            },
-          ],
-        },
-      ],
-    },
-  }, null, 2)}\n`;
-}
-
-/** Normalize --tools from array or comma-separated string (never character-split a string). */
-export function normalizeToolsList(tools) {
-  if (tools == null) return [];
-  if (Array.isArray(tools)) {
-    return tools
-      .flatMap((t) => String(t).split(','))
-      .map((t) => t.trim().toLowerCase())
-      .filter(Boolean);
-  }
-  if (typeof tools === 'string') {
-    return tools
-      .split(',')
-      .map((t) => t.trim().toLowerCase())
-      .filter(Boolean);
-  }
-  return [];
-}
-
-export function resolveTools(args) {
-  const explicit = normalizeToolsList(args.tools);
-  if (explicit.length > 0) {
-    return { tools: new Set(explicit), source: 'explicit' };
-  }
-  const root = args.root;
-  const detected = new Set();
-  if (fs.existsSync(path.join(root, '.claude'))) detected.add('claude');
-  if (fs.existsSync(path.join(root, '.cursor'))) detected.add('cursor');
-  if (fs.existsSync(path.join(root, '.codex'))) detected.add('codex');
-  if (fs.existsSync(path.join(root, '.grok'))) detected.add('grok');
-  if (fs.existsSync(path.join(root, '.windsurf'))) detected.add('windsurf');
-  // .clinerules can also be a single FILE (older Cline convention); only a directory
-  // can receive .clinerules/ark.md, so a file must not trigger detection.
-  if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
-    detected.add('cline');
-  }
-  if (fs.existsSync(path.join(root, '.kiro'))) detected.add('kiro');
-  if (fs.existsSync(path.join(root, '.roo'))) detected.add('roo');
-  if (fs.existsSync(path.join(root, '.continue'))) detected.add('continue');
-  if (fs.existsSync(path.join(root, '.gemini'))) detected.add('gemini');
-  // copilot has no reliable directory signal (.github exists in most repos),
-  // so it is explicit-only via --tools.
-  // Host signals: Grok Build / xAI agents often have no project `.grok/` yet but
-  // set an env marker (or run with GROK_*). Include Grok so skills install there.
-  if (
-    process.env.GROK_BUILD === '1' ||
-    process.env.GROK_BUILD === 'true' ||
-    process.env.XAI_GROK === '1' ||
-    process.env.XAI_GROK === 'true'
-  ) {
-    detected.add('grok');
-  }
-  // No signal at all: fall back to a complete starter set including Grok (field
-  // log: default claude+cursor+codex silently omitted Grok skills for Grok hosts).
-  if (detected.size === 0) {
-    return { tools: new Set(['claude', 'cursor', 'codex', 'grok']), source: 'default' };
-  }
-  return { tools: detected, source: 'detected' };
-}
-
-const KNOWN_TOOLS = [
-  'claude',
-  'cursor',
-  'codex',
-  'grok',
-  'windsurf',
-  'cline',
-  'copilot',
-  'kiro',
-  'roo',
-  'continue',
-  'gemini',
-];
-
-// One canonical markdown per skill (templates/skills/*.md, shipped in the npm
-// package); installed into each tool's slash-command location. The YAML
-// frontmatter (name/description) is understood or harmlessly ignored by every
-// host. Kiro has no command mechanism — its steering rule file is the only gate.
-const SKILL_TOOL_TARGETS = {
-  claude: (name) => `.claude/skills/${name}/SKILL.md`,
-  cursor: (name) => `.cursor/commands/${name}.md`,
-  codex: (name) => `.codex/prompts/${name}.md`,
-  // Grok Build: project skills at .grok/skills/<name>/SKILL.md (slash-invocable).
-  grok: (name) => `.grok/skills/${name}/SKILL.md`,
-  windsurf: (name) => `.windsurf/workflows/${name}.md`,
-  cline: (name) => `.clinerules/workflows/${name}.md`,
-  copilot: (name) => `.github/prompts/${name}.prompt.md`,
-};
-
-// The version of the arkgate package these bins ship with. Used to
-// stamp installed skills so a normal ark-check can tell "outdated skill from an
-// older Ark" apart from "user-customized skill" — the stamp moves with the
-// package, editing the body doesn't.
-export function arkPackageVersion() {
-  try {
-    const pkg = readJson(path.join(__packageRoot, 'package.json'));
-    return typeof pkg.version === 'string' ? pkg.version : null;
-  } catch {
-    return null;
-  }
-}
-
-// Insert `arkVersion: <v>` into a skill's YAML frontmatter (before its closing
-// `---`). No frontmatter → returned unchanged. Idempotent for a given version.
-export function stampSkill(content, version) {
-  if (!version) return content;
-  const lines = content.split('\n');
-  if (lines[0] !== '---') return content;
-  const closeIdx = lines.indexOf('---', 1);
-  if (closeIdx === -1) return content;
-  const existing = lines.findIndex(
-    (line, i) => i > 0 && i < closeIdx && /^arkVersion:/.test(line)
-  );
-  if (existing !== -1) {
-    lines[existing] = `arkVersion: ${version}`;
-  } else {
-    lines.splice(closeIdx, 0, `arkVersion: ${version}`);
-  }
-  return lines.join('\n');
-}
-
-// Read the `arkVersion:` stamp from an installed skill file. Returns null when
-// the file is absent or has no stamp (installed by a pre-stamp Ark, or hand-authored).
-export function installedSkillVersion(filePath) {
-  let content;
-  try {
-    content = fs.readFileSync(filePath, 'utf8');
-  } catch {
-    return null;
-  }
-  const match = content.match(/^arkVersion:\s*(.+)$/m);
-  return match ? match[1].trim() : null;
-}
-
-// Numeric-tuple compare of dotted versions; true when `a` is strictly older than
-// `b`. Non-numeric/absent segments compare as 0, so "1.7" < "1.7.5".
-export function isVersionOlder(a, b) {
-  const parse = (v) => String(v).split('.').map((n) => Number.parseInt(n, 10) || 0);
-  const av = parse(a);
-  const bv = parse(b);
-  const len = Math.max(av.length, bv.length);
-  for (let i = 0; i < len; i += 1) {
-    const x = av[i] ?? 0;
-    const y = bv[i] ?? 0;
-    if (x !== y) return x < y;
-  }
-  return false;
-}
-
-export function skillTemplates() {
-  const dir = path.join(__packageRoot, 'templates', 'skills');
-  // A missing/mispackaged templates dir would otherwise install zero skills with
-  // exit 0 — warn so a packaging regression (e.g. "templates" dropped from the
-  // package.json files array) is visible instead of a silent no-op.
-  let entries;
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    console.error(
-      `Warning: skill templates directory not found (${dir}); no /ark-* skills installed.`
-    );
-    return [];
-  }
-  return entries
-    .filter((entry) => entry.isFile() && /^[a-z0-9-]+\.md$/.test(entry.name))
-    .map((entry) => entry.name)
-    .sort()
-    .map((name) => [path.basename(name, '.md'), fs.readFileSync(path.join(dir, name), 'utf8')]);
-}
-
-// Skill names only, silent on a missing templates dir — for the freshness
-// advisory below, which must not print packaging warnings on every check run.
-export function skillTemplateNames() {
-  const dir = path.join(__packageRoot, 'templates', 'skills');
-  let entries;
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((entry) => entry.isFile() && /^[a-z0-9-]+\.md$/.test(entry.name))
-    .map((entry) => path.basename(entry.name, '.md'));
-}
-
-// A normal ark-check run is the reliable discovery point for new /ark-* skills.
-// Ark ships no install lifecycle script (a postinstall banner would be blocked by
-// modern package managers' script-approval policy anyway, so careful users never
-// saw it — and it broke hardened installs). When a project has adopted Ark agent
-// gates (AGENTS.md present) but a detected tool is missing
-// skills this version ships, surface it here so agents and CI actually notice.
-// Advisory only — never affects the exit code. Copilot has no reliable directory
-// signal, so it is not auto-detected (explicit --tools only), matching resolveTools.
-export function detectCodexHomeGap(root) {
-  if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return null;
-  if (fs.existsSync(path.join(root, 'templates', 'skills'))) return null;
-  const skillNames = skillTemplateNames();
-  if (skillNames.length === 0) return null;
-  const dir = codexPromptsDir();
-  if (!fs.existsSync(dir)) return null;
-  const present = skillNames.filter((name) => fs.existsSync(path.join(dir, `${name}.md`)));
-  if (present.length === 0) return null; // Codex home never set up for Ark — don't nag.
-  const version = arkPackageVersion();
-  const missing = skillNames.length - present.length;
-  let stale = 0;
-  if (version) {
-    for (const name of present) {
-      const installed = installedSkillVersion(path.join(dir, `${name}.md`));
-      if (installed === null || isVersionOlder(installed, version)) stale += 1;
-    }
-  }
-  return missing > 0 || stale > 0 ? { missing, stale } : null;
-}
-
-export function detectSkillGaps(root) {
-  if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return [];
-  // The Ark source tree keeps the skill templates at templates/skills/ — it's the
-  // producer, not a consumer, so it must not nag itself to "install" its own skills.
-  if (fs.existsSync(path.join(root, 'templates', 'skills'))) return [];
-  const skillNames = skillTemplateNames();
-  if (skillNames.length === 0) return [];
-  const detected = [];
-  if (fs.existsSync(path.join(root, '.claude'))) detected.push('claude');
-  if (fs.existsSync(path.join(root, '.cursor'))) detected.push('cursor');
-  if (fs.existsSync(path.join(root, '.codex'))) detected.push('codex');
-  if (fs.existsSync(path.join(root, '.grok'))) detected.push('grok');
-  if (fs.existsSync(path.join(root, '.windsurf'))) detected.push('windsurf');
-  if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
-    detected.push('cline');
-  }
-  const version = arkPackageVersion();
-  const gaps = [];
-  for (const tool of detected) {
-    const target = SKILL_TOOL_TARGETS[tool];
-    if (!target) continue;
-    let missing = 0;
-    let stale = 0;
-    for (const name of skillNames) {
-      const file = path.join(root, target(name));
-      if (!fs.existsSync(file)) {
-        missing += 1;
-      } else if (version) {
-        // An installed skill with no stamp predates stamping (older Ark), or one
-        // stamped behind the current version is left over from an older install.
-        // Either way the shipped skill has moved on — offer a --force refresh.
-        const installed = installedSkillVersion(file);
-        if (installed === null || isVersionOlder(installed, version)) stale += 1;
-      }
-    }
-    if (missing > 0 || stale > 0) gaps.push({ tool, missing, stale });
-  }
-  return gaps;
-}
-
-// Files carrying an emitted Ark command whose runner (npx / pnpm exec / yarn) should match
-// the project's package manager. .mcp.json / .cursor/mcp.json hold it structurally
-// (command/args); the rest hold it as text ("npx ark-check …", incl. .claude/settings.json
-// hook strings and the package.json check:architecture script).
-const COMMAND_GATE_TEXT_FILES = [
-  '.claude/settings.json', 'AGENTS.md', '.cursor/rules/ark.mdc', '.windsurf/rules/ark.md',
-  '.clinerules/ark.md', '.github/copilot-instructions.md', '.kiro/steering/ark.md',
-  '.roo/rules/ark.md', '.continue/rules/ark.md', 'GEMINI.md', 'package.json',
-  '.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)(?= (?: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). */
-export 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). */
-export 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]));
-}
-
-export 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;
-}
-
-/**
- * Production deploy path quality (universal — any consumer repo).
- * Detects when the production build host runs ESLint / typecheck as part of
- * `build` (e.g. Next.js "Linting and checking validity of types") so failures
- * surface first on Vercel/Netlify/etc. unless CI/pre-merge runs the same checks.
- * Framework signals only (deps + scripts + config) — never project-specific.
- *
- * @returns {{
- *   embedsLintInBuild: boolean,
- *   embedsTypecheckInBuild: boolean,
- *   engines: string[],
- *   hasLintScript: boolean,
- *   hasTypecheckScript: boolean,
- *   ciRunsLint: boolean,
- *   ciRunsTypecheck: boolean,
- *   eslintIgnoreDuringBuilds: boolean,
- * }}
- */
-export function detectDeployPathQuality(root) {
-  const pkg = readPackageJson(root) || {};
-  const deps = {
-    ...(pkg.dependencies && typeof pkg.dependencies === 'object' ? pkg.dependencies : {}),
-    ...(pkg.devDependencies && typeof pkg.devDependencies === 'object' ? pkg.devDependencies : {}),
-    ...(pkg.peerDependencies && typeof pkg.peerDependencies === 'object' ? pkg.peerDependencies : {}),
-  };
-  const scripts =
-    pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
-  const buildScript = typeof scripts.build === 'string' ? scripts.build : '';
-
-  const engines = [];
-  // Next.js production build runs ESLint + typecheck by default (unless opted out).
-  if (deps.next || /\bnext\s+build\b/.test(buildScript)) engines.push('next');
-  // Nuxt 3+ can lint via modules; only flag when build clearly invokes nuxt build + eslint tooling present.
-  if ((deps.nuxt || deps['nuxt3'] || /\bnuxt\s+build\b/.test(buildScript)) && (deps.eslint || hasEslintConfig(root))) {
-    engines.push('nuxt');
-  }
-  // Create React App historically failed build on ESLint errors.
-  if (deps['react-scripts'] || /\breact-scripts\s+build\b/.test(buildScript)) engines.push('cra');
-
-  const eslintIgnoreDuringBuilds = engines.includes('next') && nextIgnoresEslintDuringBuilds(root);
-  const embedsLintInBuild = engines.length > 0 && !eslintIgnoreDuringBuilds;
-  // Next still typechecks during build even when eslint.ignoreDuringBuilds is true.
-  const embedsTypecheckInBuild = engines.includes('next') || engines.includes('nuxt');
-
-  const scriptHasLint = (s) =>
-    Boolean(
-      s &&
-        ((typeof s.lint === 'string' && s.lint.trim()) ||
-          (typeof s.eslint === 'string' && s.eslint.trim()) ||
-          (typeof s['lint:ci'] === 'string' && s['lint:ci'].trim()) ||
-          (typeof s['check:lint'] === 'string' && s['check:lint'].trim()))
-    );
-
-  let hasLintScript = scriptHasLint(scripts);
-  let hasTypecheckScript = packageScriptsHaveTypecheck(scripts);
-  const packageLintScripts = [];
-  // Monorepo: package-level scripts count (apps/web, packages/ui, …).
-  try {
-    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
-      const candidates = [path.join(root, entry.name)];
-      // one more level: packages/foo
-      try {
-        for (const child of fs.readdirSync(path.join(root, entry.name), { withFileTypes: true })) {
-          if (child.isDirectory() && !child.name.startsWith('.')) {
-            candidates.push(path.join(root, entry.name, child.name));
-          }
-        }
-      } catch {
-        /* ignore */
-      }
-      for (const dir of candidates) {
-        const pj = path.join(dir, 'package.json');
-        if (!fs.existsSync(pj)) continue;
-        try {
-          const nested = JSON.parse(fs.readFileSync(pj, 'utf8'));
-          const ns = nested.scripts && typeof nested.scripts === 'object' ? nested.scripts : {};
-          if (scriptHasLint(ns)) {
-            hasLintScript = true;
-            packageLintScripts.push(path.relative(root, dir).split(path.sep).join('/'));
-          }
-          if (packageScriptsHaveTypecheck(ns)) hasTypecheckScript = true;
-          const nd = {
-            ...(nested.dependencies || {}),
-            ...(nested.devDependencies || {}),
-          };
-          if (nd.next && !engines.includes('next')) engines.push('next');
-        } catch {
-          /* ignore */
-        }
-      }
-    }
-  } catch {
-    /* ignore */
-  }
-
-  const ciTexts = collectCiWorkflowTexts(root);
-  const ciJoined = ciTexts.join('\n');
-  const ciRunsLint =
-    ciTexts.length > 0 &&
-    (/\bnpm\s+run\s+lint\b/i.test(ciJoined) ||
-      /\bpnpm\s+(?:run\s+)?lint\b/i.test(ciJoined) ||
-      /\byarn\s+(?:run\s+)?lint\b/i.test(ciJoined) ||
-      /\bbun\s+run\s+lint\b/i.test(ciJoined) ||
-      /\beslint\b/i.test(ciJoined) ||
-      /\blint:ci\b/i.test(ciJoined) ||
-      /\bcheck:lint\b/i.test(ciJoined) ||
-      // package-level: working-directory + lint, or path/filter lint
-      (packageLintScripts.length > 0 &&
-        packageLintScripts.some((p) => ciJoined.includes(p) && /lint/i.test(ciJoined))));
-  const ciRunsTypecheck =
-    ciTexts.length > 0 &&
-    (/\btypecheck\b/i.test(ciJoined) ||
-      /\btype-check\b/i.test(ciJoined) ||
-      /\bcheck:types\b/i.test(ciJoined) ||
-      /\btsc\s+--noEmit\b/i.test(ciJoined));
-
-  return {
-    embedsLintInBuild,
-    embedsTypecheckInBuild,
-    engines,
-    hasLintScript,
-    hasTypecheckScript,
-    ciRunsLint,
-    ciRunsTypecheck,
-    eslintIgnoreDuringBuilds,
-    hasCiWorkflows: ciTexts.length > 0,
-    packageLintScripts,
-  };
-}
-
-function hasEslintConfig(root) {
-  return [
-    'eslint.config.mjs',
-    'eslint.config.js',
-    'eslint.config.cjs',
-    'eslint.config.ts',
-    '.eslintrc.json',
-    '.eslintrc.cjs',
-    '.eslintrc.js',
-    '.eslintrc.yml',
-    '.eslintrc.yaml',
-  ].some((f) => fs.existsSync(path.join(root, f)));
-}
-
-/** next.config.* eslint.ignoreDuringBuilds: true → production build will not fail on ESLint. */
-function nextIgnoresEslintDuringBuilds(root) {
-  const names = [
-    'next.config.ts',
-    'next.config.mts',
-    'next.config.js',
-    'next.config.mjs',
-    'next.config.cjs',
-  ];
-  for (const name of names) {
-    const file = path.join(root, name);
-    if (!fs.existsSync(file)) continue;
-    try {
-      const text = fs.readFileSync(file, 'utf8');
-      // Common patterns: ignoreDuringBuilds: true | ignoreDuringBuilds: true,
-      if (/ignoreDuringBuilds\s*:\s*true/.test(text)) return true;
-    } catch {
-      /* ignore */
-    }
-  }
-  return false;
-}
-
-function collectCiWorkflowTexts(root) {
-  const texts = [];
-  const pushFile = (rel) => {
-    try {
-      const full = path.join(root, rel);
-      if (fs.existsSync(full) && fs.statSync(full).isFile()) {
-        texts.push(fs.readFileSync(full, 'utf8'));
-      }
-    } catch {
-      /* ignore */
-    }
-  };
-  pushFile('.gitlab-ci.yml');
-  pushFile('bitbucket-pipelines.yml');
-  pushFile('azure-pipelines.yml');
-  pushFile('.circleci/config.yml');
-  const wfDir = path.join(root, '.github', 'workflows');
-  try {
-    if (fs.existsSync(wfDir)) {
-      for (const f of fs.readdirSync(wfDir)) {
-        if (!/\.ya?ml$/i.test(f)) continue;
-        pushFile(path.join('.github', 'workflows', f));
-      }
-    }
-  } catch {
-    /* ignore */
-  }
-  return texts;
-}
-
-/**
- * W5 — Write-path capability surface for doctor (stable additive JSON).
- *
- * Detects whether installed agent gates expose:
- *   - MCP prepare-write / validate_code (autoPatch) tools
- *   - PreToolUse hook in reject-only vs repair mode (--hook-repair / ARK_HOOK_REPAIR)
- *
- * Never claims silent apply; "repair" means host can re-inject a patch after hard deny.
- *
- * @returns {{
- *   mode: 'repair' | 'reject-only' | 'mcp-only' | 'none',
- *   prepareWrite: boolean,
- *   autoPatch: boolean,
- *   hookPresent: boolean,
- *   hookRepair: boolean,
- *   mcpPresent: boolean,
- *   evidence: string[],
- *   gap: null | { id: string, severity: string, message: string, fix: string },
- * }}
- */
-export function detectWritePathCapabilities(root) {
-  const evidence = [];
-  let hookPresent = false;
-  let hookRepair = false;
-
-  const hookFiles = [
-    '.claude/settings.json',
-    '.grok/hooks/ark-write-gate.json',
-  ];
-  for (const rel of hookFiles) {
-    const abs = path.join(root, rel);
-    if (!fs.existsSync(abs)) continue;
-    let text = '';
-    try {
-      text = fs.readFileSync(abs, 'utf8');
-    } catch {
-      continue;
-    }
-    // PreToolUse / write-gate command referencing ark(-gate)?-mcp --hook
-    if (
-      /--hook\b/.test(text) ||
-      /\b(ark|arkgate)-mcp\b[\s\S]{0,80}--hook\b/.test(text) ||
-      /\b--hook\b[\s\S]{0,80}\b(ark|arkgate)-mcp\b/.test(text)
-    ) {
-      hookPresent = true;
-      evidence.push(rel);
-    }
-    if (
-      /--hook-repair\b/.test(text) ||
-      /ARK_HOOK_REPAIR\s*=\s*['"]?(1|true|yes|on)/i.test(text)
-    ) {
-      hookRepair = true;
-      if (!evidence.includes(rel)) evidence.push(rel);
-    }
-  }
-
-  let mcpPresent = false;
-  const mcpFiles = ['.mcp.json', '.cursor/mcp.json', '.grok/config.toml'];
-  for (const rel of mcpFiles) {
-    const abs = path.join(root, rel);
-    if (!fs.existsSync(abs)) continue;
-    let text = '';
-    try {
-      text = fs.readFileSync(abs, 'utf8');
-    } catch {
-      continue;
-    }
-    if (
-      /\b(ark|arkgate)-mcp\b/.test(text) ||
-      /mcp_servers\.ark\b/.test(text) ||
-      /"ark"\s*:\s*\{/.test(text) ||
-      /mcpServers[\s\S]*\bark\b/.test(text)
-    ) {
-      mcpPresent = true;
-      evidence.push(rel);
-    }
-  }
-
-  // Package tools when MCP is wired: ark_prepare_write + validate_code(autoPatch).
-  // Hook repair emits machine-readable autoPatch without silent write.
-  const prepareWrite = mcpPresent;
-  const autoPatch = mcpPresent || hookRepair;
-
-  /** @type {'repair' | 'reject-only' | 'mcp-only' | 'none'} */
-  let mode = 'none';
-  if (hookPresent && hookRepair) mode = 'repair';
-  else if (hookPresent && !hookRepair) mode = 'reject-only';
-  else if (mcpPresent) mode = 'mcp-only';
-
-  let gap = null;
-  if (mode === 'none') {
-    gap = {
-      id: 'write-path-none',
-      severity: 'warn',
-      message:
-        'Write path is not installed — no PreToolUse hook and no Ark MCP. Agents write without architecture gate or prepare-write.',
-      fix: arkCommand(root, 'ark-check', '--install-agent-gates'),
-    };
-  } else if (mode === 'reject-only') {
-    gap = {
-      id: 'write-path-reject-only',
-      severity: 'info',
-      message: mcpPresent
-        ? 'PreToolUse hook is reject-only (hard block, no ARK_REPAIR_JSON). MCP still exposes prepare-write/autoPatch — enable --hook-repair so the write boundary itself can re-inject patches.'
-        : 'Write path is reject-only (hard block with prose; no repair payload). Enable --hook-repair or ARK_HOOK_REPAIR=1 so hosts can re-inject patches without full re-draft.',
-      fix: arkCommand(
-        root,
-        'ark-check',
-        '--install-agent-gates --tools claude,grok --force'
-      ),
-    };
-  } else if (mode === 'mcp-only') {
-    gap = {
-      id: 'write-path-mcp-only',
-      severity: 'info',
-      message:
-        'MCP exposes prepare-write / autoPatch tools, but no PreToolUse write hook is installed — enforcement is advisory unless the agent calls tools.',
-      fix: arkCommand(root, 'ark-check', '--install-agent-gates --tools claude,grok'),
-    };
-  }
-
-  return {
-    mode,
-    prepareWrite,
-    autoPatch,
-    hookPresent,
-    hookRepair,
-    mcpPresent,
-    evidence: [...new Set(evidence)],
-    gap,
-  };
-}
-
-/**
- * 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, deployPath: object|null, writePath: object }}
- */
-export 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'));
-
-  // --- Write path: prepare-write / autoPatch / reject-only (W5) ---
-  const writePath = detectWritePathCapabilities(root);
-  // Only surface write-path gaps when the project has adopted gates (or has partial install).
-  // Producer package tree always has templates — still report capability for dogfood honesty.
-  if (writePath.gap && (adopted || writePath.hookPresent || writePath.mcpPresent || isProducer)) {
-    // Producer may be repair-capable via own templates; still useful. Skip "none" on pure
-    // consumer repos with zero Ark files? missingGates already covers that.
-    if (!(writePath.mode === 'none' && !adopted && !isProducer)) {
-      gaps.push(writePath.gap);
-    }
-  }
-
-  // --- 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 / multi-project) ---
-  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 assessed = assessCodexHomeMcp(toml, root);
-      codexHome = {
-        file: codexFile,
-        root: assessed.root,
-        tempPath: assessed.tempPath,
-        wrongRoot: assessed.wrongRoot,
-        preferredBin: assessed.preferredBin,
-        needsRewrite: assessed.needsRewrite,
-        multiProject: assessed.multiProject,
-        scopedTable: assessed.scopedTable,
-      };
-      if (assessed.gap) {
-        gaps.push({
-          id: assessed.gap.id,
-          severity: assessed.gap.severity,
-          message: assessed.gap.message,
-          fix: arkCommand(root, 'ark-check', assessed.gap.fixArgs),
-        });
-      }
-    }
-  }
-
-  // --- 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: `${arkCommand(root, 'ark-check', '--ratchet-cores')} (when architecture is green: 0 active violations)`,
-      });
-    }
-  }
-
-  // --- 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).',
-        };
-      }
-    }
-  }
-
-  // --- Empty scope: contract matches no TS/JS ---
-  if (!isProducer && (coverage?.governed?.totalFiles ?? coverage?.totalFiles) === 0) {
-    gaps.push({
-      id: 'empty-scope',
-      severity: 'warn',
-      message:
-        'Empty scope: include paths match 0 TypeScript/JS files — checks are not governing this tree',
-      fix: `${arkCommand(root, 'ark-check', '--suggest-include')} then ${arkCommand(root, 'ark-check', '--adopt-contract --write')}`,
-    });
-  }
-
-  // --- Deploy-path quality (ESLint/types that production build hosts run) ---
-  // Universal: any Next/CRA/Nuxt (etc.) consumer. Not architecture — still adoption.
-  // Skip pure library producer (this monorepo) to avoid self-noise.
-  let deployPath = null;
-  if (!isProducer) {
-    deployPath = detectDeployPathQuality(root);
-    const eng =
-      deployPath.engines.length > 0 ? deployPath.engines.join('/') : 'production';
-    if (deployPath.embedsLintInBuild && !deployPath.hasLintScript) {
-      gaps.push({
-        id: 'deploy-path-lint-script-missing',
-        severity: 'warn',
-        message: `${eng} production build runs ESLint — no package.json lint script, so failures often surface first on the deploy host`,
-        fix: 'Add a package.json "lint" script (e.g. eslint .) matching production ESLint config; run it in CI and before merge',
-      });
-    } else if (
-      deployPath.embedsLintInBuild &&
-      deployPath.hasLintScript &&
-      deployPath.hasCiWorkflows &&
-      !deployPath.ciRunsLint
-    ) {
-      gaps.push({
-        id: 'deploy-path-lint-not-in-ci',
-        severity: 'warn',
-        message: `${eng} production build runs ESLint — CI workflows exist but do not run lint, so deploy hosts may be the first fail`,
-        fix: 'Add a CI step that runs your package.json lint script (npm run lint / pnpm lint / yarn lint) and require it before deploy',
-      });
-    } else if (
-      deployPath.embedsLintInBuild &&
-      deployPath.hasLintScript &&
-      !deployPath.hasCiWorkflows
-    ) {
-      gaps.push({
-        id: 'deploy-path-lint-no-ci',
-        severity: 'info',
-        message: `${eng} production build runs ESLint — no CI workflows detected; push-to-host builds may be the first lint fail`,
-        fix: 'Add CI (or a pre-push hook) that runs lint before the deploy host builds; keep branch protection required when using GitHub',
-      });
-    }
-
-    if (deployPath.embedsTypecheckInBuild && !deployPath.hasTypecheckScript) {
-      gaps.push({
-        id: 'deploy-path-typecheck-script-missing',
-        severity: 'info',
-        message: `${eng} production build typechecks — no package.json typecheck script for local/CI parity`,
-        fix: 'Add "typecheck": "tsc --noEmit" (or framework equivalent) and run it in CI alongside lint',
-      });
-    } else if (
-      deployPath.embedsTypecheckInBuild &&
-      deployPath.hasTypecheckScript &&
-      deployPath.hasCiWorkflows &&
-      !deployPath.ciRunsTypecheck
-    ) {
-      gaps.push({
-        id: 'deploy-path-typecheck-not-in-ci',
-        severity: 'info',
-        message: `${eng} production build typechecks — CI does not run typecheck; type errors may appear first on the deploy host`,
-        fix: 'Add a CI step for npm run typecheck (or your typecheck script) and require it before deploy',
-      });
-    }
-  }
-
-  // --- False-green contract (field-install detector; doctor skillGaps already cover missing skills) ---
-  let contractFalseGreen = null;
-  if (!isProducer && config) {
-    const gap = falseGreenAdoptionGap(root, config, coverage);
-    if (gap) {
-      contractFalseGreen = { risk: true, message: gap.message, fix: gap.fix };
-      gaps.push(gap);
-    }
-  }
-
-  return {
-    gaps,
-    hosts,
-    mcp,
-    codexHome,
-    coreOptional,
-    originReport,
-    baseline,
-    layerBalance,
-    deployPath,
-    contractFalseGreen,
-    writePath,
-  };
-}
-
-// 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)
-// so the check is silent unless there's a real mismatch.
-export function staleRunnerGateFiles(root) {
-  const want = execRunner(root);
-  if (want === 'npx') return [];
-  const stale = [];
-  for (const rel of COMMAND_GATE_TEXT_FILES) {
-    let text;
-    try {
-      text = fs.readFileSync(path.join(root, rel), 'utf8');
-    } catch {
-      continue;
-    }
-    RUNNER_BEFORE_ARK.lastIndex = 0;
-    let match;
-    while ((match = RUNNER_BEFORE_ARK.exec(text))) {
-      if (match[0] !== want) {
-        stale.push(rel);
-        break;
-      }
-    }
-  }
-  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 && ark.command && ark.command !== want.split(' ')[0]) stale.push(rel);
-  }
-  return stale;
-}
-
-// When more than one lockfile is present the project is ambiguous. detectPackageManager()
-// resolves it (package-lock.json wins so a stray pnpm-lock.yaml can't hijack an npm project),
-// but the user should know it happened and how to make it explicit — otherwise a leftover
-// lockfile silently steers which runner every emitted command uses.
-export function warnLockfileConflict(root) {
-  const locks = presentLockfiles(root);
-  if (locks.length <= 1) return;
-  const chosen = detectPackageManager(root);
-  const files = { pnpm: 'pnpm-lock.yaml', yarn: 'yarn.lock', npm: 'package-lock.json' };
-  console.log('');
-  console.log(
-    `Note: multiple lockfiles present (${locks.map((pm) => files[pm]).join(', ')}). Treating this`
-  );
-  console.log(
-    `as a ${chosen} project — Ark commands use "${execRunner(root)}". If that's wrong, set`
-  );
-  console.log(
-    '"packageManager" in package.json (e.g. "pnpm@9") to declare it, or remove the stray lockfile.'
-  );
-}
-
-// --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.
-export function runMigrateCommands(root) {
-  const runner = execRunner(root);
-  const changed = [];
-  for (const rel of COMMAND_GATE_TEXT_FILES) {
-    const full = path.join(root, rel);
-    let text;
-    try {
-      text = fs.readFileSync(full, 'utf8');
-    } catch {
-      continue;
-    }
-    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);
-    }
-  }
-  for (const rel of COMMAND_GATE_JSON_FILES) {
-    const full = path.join(root, rel);
-    let json;
-    try {
-      json = JSON.parse(fs.readFileSync(full, 'utf8'));
-    } catch {
-      continue;
-    }
-    const ark = json?.mcpServers?.ark;
-    if (!ark) continue;
-    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' || 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 — runners and MCP bins already look correct.');
-  } else {
-    for (const rel of changed) console.log(`  updated ${rel}`);
-    console.log(
-      `  (runner + single MCP bin \`${PREFERRED_MCP_BIN}\`; customized non-command content is untouched.)`
-    );
-  }
-  warnLockfileConflict(root);
-}
-
-export function runInstallAgentGates(args) {
-  const root = args.root;
-  if (args.migrateCommands) {
-    runMigrateCommands(root);
-    return;
-  }
-  if (args.tools != null) {
-    const list = normalizeToolsList(args.tools);
-    args.tools = list;
-    const unknown = list.filter((tool) => !KNOWN_TOOLS.includes(tool));
-    if (list.length === 0 || unknown.length > 0) {
-      console.error(
-        `--tools expects a comma-separated subset of: ${KNOWN_TOOLS.join(', ')}` +
-          (unknown.length > 0 ? ` (unknown: ${unknown.join(', ')})` : '')
-      );
-      process.exitCode = 2;
-      return;
-    }
-  }
-  const pm = packageManager(root);
-  const hasCheckScript = hasCheckArchitectureScript(root);
-  const { tools, source } = resolveTools(args);
-  const toolSource =
-    source === 'explicit'
-      ? 'from --tools'
-      : source === 'detected'
-        ? 'auto-detected from config dirs'
-        : 'default set — no agent config dirs found';
-  console.log(`Agent gates for: ${[...tools].sort().join(', ')} (${toolSource})`);
-  const templates = [];
-  // --skills-only refreshes just the canonical /ark-* skills, which are safe to
-  // overwrite (they track the package). The gate/instruction files (AGENTS.md,
-  // settings.json, CI workflow, rules) are the ones users customize, so a plain
-  // `--force` clobbers them — this is the safe way to pick up new skill versions.
-  // Do not mutate package.json under --skills-only (typecheck bootstrap is gates/CI).
-  if (!args.skillsOnly) {
-    // Bootstrap typecheck before CI template so generated workflow includes the step.
-    const typecheckBootstrap = ensureTypecheckScript(root, { write: true });
-    if (typecheckBootstrap.changed && !args.json) {
-      console.log(
-        `Added package.json script "typecheck": "${typecheckBootstrap.script}" (tsconfig present; local/CI parity).`
-      );
-    }
-    // Base gates: tool-agnostic contract + CI backstop, always written.
-    templates.push(['AGENTS.md', agentInstructions(root)]);
-    templates.push(['.mcp.json', mcpJson(root)]);
-    templates.push([
-      '.github/workflows/ark-check.yml',
-      (() => {
-        const deploy = detectDeployPathQuality(root);
-        return githubWorkflow(pm, detectCiNode(root), {
-          hasLintScript: deploy.hasLintScript,
-          hasTypecheckScript: deploy.hasTypecheckScript,
-        });
-      })(),
-    ]);
-    if (tools.has('cursor')) {
-      templates.push(['.cursor/mcp.json', mcpJson(root)]);
-      templates.push(['.cursor/rules/ark.mdc', cursorRule(root)]);
-    }
-    if (tools.has('claude')) {
-      templates.push(['.claude/settings.json', claudeSettings(root)]);
-    }
-    if (tools.has('codex')) {
-      templates.push(['docs/ark-codex-config.toml', codexTomlSnippet(root)]);
-    }
-    if (tools.has('grok')) {
-      templates.push(['.grok/config.toml', grokProjectConfig(root)]);
-      templates.push(['.grok/hooks/ark-write-gate.json', grokHooks(root)]);
-    }
-    // Instruction-tier hosts: one shared rule text, host-specific path.
-    if (tools.has('windsurf')) {
-      templates.push(['.windsurf/rules/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('cline')) {
-      templates.push(['.clinerules/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('copilot')) {
-      templates.push(['.github/copilot-instructions.md', instructionRule(root)]);
-    }
-    if (tools.has('kiro')) {
-      templates.push(['.kiro/steering/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('roo')) {
-      templates.push(['.roo/rules/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('continue')) {
-      templates.push(['.continue/rules/ark.md', instructionRule(root)]);
-    }
-    // Gemini CLI reads GEMINI.md as its primary project context (it also reads
-    // AGENTS.md, but GEMINI.md wins when both are present), so the rule lives there.
-    if (tools.has('gemini')) {
-      templates.push(['GEMINI.md', instructionRule(root)]);
-    }
-  }
-  // /ark-* skills for every detected tool that supports project-level commands.
-  // Stamp each with the shipping version so a later ark-check can flag skills
-  // left behind by an older Ark (see detectSkillGaps) without nagging about
-  // user edits to the body.
-  const version = arkPackageVersion();
-  const skills = skillTemplates().map(([name, content]) => [name, stampSkill(content, version)]);
-  const skillPaths = new Set();
-  for (const tool of tools) {
-    const target = SKILL_TOOL_TARGETS[tool];
-    if (!target) continue;
-    for (const [name, content] of skills) {
-      const relativePath = target(name);
-      skillPaths.add(relativePath);
-      templates.push([relativePath, content]);
-    }
-  }
-
-  const results = templates.map(([relativePath, content]) =>
-    writeTemplate(root, relativePath, content, args.force)
-  );
+export {
+  readJson,
+  readPackageJson,
+  hasCheckArchitectureScript,
+  packageScriptsHaveTypecheck,
+  treeHasTypecheckScript,
+  ensureTypecheckScript,
+  REQUIRED_GATE_FILES,
+  hasArkWorkflow,
+  missingGates,
+  ensureDirForFile,
+  isArkAgentsContent,
+  isSelfHostedLibraryAgents,
+  writeTemplate,
+} from './gate-files.mjs';
+
+export { loadTypeScript } from './typescript-host.mjs';
 
-  console.log('Ark agent gate templates:');
-  let staleSkipped = 0;
-  for (const result of results) {
-    const marker =
-      result.status === 'written'
-        ? 'wrote'
-        : result.status === 'merged'
-          ? 'merged'
-          : result.status === 'skipped-non-ark'
-            ? 'kept'
-            : result.status === 'failed'
-              ? 'FAILED'
-              : 'skipped';
-    // A skipped skill reads as "you're fine" — but it may be a version behind.
-    // Say which, so the user isn't left guessing (and knows the safe refresh cmd).
-    let note = '';
-    if (result.status === 'skipped' && skillPaths.has(result.relativePath) && version) {
-      const installed = installedSkillVersion(path.join(root, result.relativePath));
-      if (installed === null || isVersionOlder(installed, version)) {
-        staleSkipped += 1;
-        note = `  (stale: ${installed ?? 'no stamp'} < ${version})`;
-      } else {
-        note = '  (up to date)';
-      }
-    }
-    console.log(`  ${marker.padEnd(7)} ${result.relativePath}${note}`);
-  }
-  if (staleSkipped > 0 && !args.skillsOnly) {
-    console.log('');
-    console.log(
-      `  ${staleSkipped} skill(s) are outdated but were left untouched. Refresh them with:`
-    );
-    console.log(`    ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`);
-  }
+export {
+  checkArgsForRoot,
+  packageManager,
+  arkCheckCommand,
+  checkArchitectureScriptSnippet,
+  layerPlacementTable,
+  agentInstructions,
+  mcpJson,
+  codexTomlSnippet,
+  instructionRule,
+  cursorRule,
+  detectNodeMajorFromWorkflows,
+  detectCiNode,
+  githubWorkflow,
+} from './ci-and-commands.mjs';
 
-  // --codex-home writes the canonical skills straight to $CODEX_HOME/prompts.
-  // Codex reads prompts from there (not the repo), so this is the only way to
-  // refresh them for a repo that isn't itself configured for Codex. It writes to
-  // the user's home dir, hence explicit opt-in rather than part of a normal run.
-  const homeResults = [];
-  if (args.codexHome) {
-    const dir = codexPromptsDir();
-    console.log('');
-    console.log(`Codex home skills (${dir}):`);
-    try {
-      fs.mkdirSync(dir, { recursive: true });
-    } catch (error) {
-      console.error(`  FAILED to create ${dir} (${error.message})`);
-      homeResults.push({ status: 'failed' });
-    }
-    if (homeResults.length === 0) {
-      for (const [name, content] of skills) {
-        const file = path.join(dir, `${name}.md`);
-        if (fs.existsSync(file) && !args.force) {
-          const installed = installedSkillVersion(file);
-          const behind = installed === null || (version && isVersionOlder(installed, version));
-          const note = behind
-            ? `  (stale: ${installed ?? 'no stamp'} < ${version}; use --force)`
-            : '  (up to date)';
-          console.log(`  ${'skipped'.padEnd(7)} ${name}.md${note}`);
-          homeResults.push({ status: 'skipped' });
-          continue;
-        }
-        try {
-          fs.writeFileSync(file, content);
-          console.log(`  ${'wrote'.padEnd(7)} ${name}.md`);
-          homeResults.push({ status: 'written' });
-        } catch (error) {
-          console.log(`  ${'FAILED'.padEnd(7)} ${name}.md (${error.message})`);
-          homeResults.push({ status: 'failed' });
-        }
-      }
-    }
-  }
+export {
+  normalizeToolsList,
+  resolveTools,
+  KNOWN_TOOLS,
+  arkPackageVersion,
+  stampSkill,
+  installedSkillVersion,
+  isVersionOlder,
+  skillTemplates,
+  skillTemplateNames,
+  detectCodexHomeGap,
+  detectSkillGaps,
+} from './skill-install.mjs';
+
+export { detectDeployPathQuality } from './deploy-path.mjs';
 
-  // Auto-wire the ark MCP server into Codex's home config.toml. Claude and Cursor get
-  // machine-readable registrations (.claude/settings.json, .cursor/mcp.json) written as repo
-  // templates above; Codex reads MCP servers only from ~/.codex/config.toml, so it needs a
-  // home-dir merge instead. Fires whenever Codex is in play so `ark://manifest` is live
-  // without a manual copy step.
-  let codexMcp = null;
-  if (tools.has('codex') || args.codexHome) {
-    codexMcp = wireCodexMcp(root, args.force);
-    console.log('');
-    console.log(`Codex MCP registration (${codexMcp.file}):`);
-    if (codexMcp.status === 'written-multi') {
-      console.log(
-        `  ${'wrote'.padEnd(7)} [mcp_servers.${codexMcp.table}] (multi-project — primary [mcp_servers.ark] left unchanged; --force rebinds primary)`
-      );
-    } else if (codexMcp.status === 'skipped') {
-      console.log(`  ${'skipped'.padEnd(7)} [mcp_servers.ark] already present (use --force to overwrite)`);
-    } else if (codexMcp.status === 'failed') {
-      console.log(`  ${'FAILED'.padEnd(7)} [mcp_servers.ark] (${codexMcp.message})`);
-    } else {
-      const verb = codexMcp.status === 'updated' ? 'updated' : 'wrote';
-      console.log(`  ${verb.padEnd(7)} [mcp_servers.ark] with absolute paths`);
-      console.log('          RESTART Codex — it does not hot-load MCP servers.');
-      console.log('          Then expect: resource ark://manifest + tools validate_code, ark_check, ark_coverage, ark_place.');
-    }
-  }
+export {
+  stripMcpServerArgs,
+  mcpArgsHaveDuplicateBins,
+  brokenMcpGateFiles,
+  collectAdoptionGaps,
+} from './mcp-adoption.mjs';
 
-  const failed = [...results, ...homeResults, ...(codexMcp ? [codexMcp] : [])].filter((result) => result.status === 'failed');
-  if (failed.length > 0) {
-    console.error(`\nFailed to write ${failed.length} template(s).`);
-    process.exitCode = 1;
-    return;
-  }
-  console.log('');
-  console.log('Next steps:');
-  console.log('  1. Review the generated files and commit the ones that match your tools.');
-  console.log(`  2. Run: ${arkCheckCommand(root)}`);
-  if (!hasCheckScript) {
-    console.log('  3. Add the package.json alias if you want `run check:architecture`:');
-    console.log(`     ${checkArchitectureScriptSnippet(root)}`);
-  }
-  if ((tools.has('codex') || args.codexHome)) {
-    console.log('');
-    if (codexMcp && codexMcp.status !== 'failed') {
-      console.log(`  Codex: ark MCP registered in ${codexMcp.file} — restart Codex so \`ark://manifest\` loads.`);
-    }
-    if (args.codexHome) {
-      console.log(`  Codex: refreshed the /ark-* skills in ${codexPromptsDir()} — Codex loads them from there.`);
-    } else if (skills.length > 0) {
-      console.log('  Codex loads slash-command prompts from $CODEX_HOME/prompts (~/.codex/prompts),');
-      console.log('  not the repo. Install the /ark-* skills there with:');
-      console.log(`    ${arkCommand(root, 'ark-check', '--install-agent-gates --codex-home')}`);
-      console.log('  (writes to your home dir; agents driving this setup should offer to run it).');
-    }
-  }
-  warnLockfileConflict(root);
-}
+export {
+  staleRunnerGateFiles,
+  warnLockfileConflict,
+  runMigrateCommands,
+  runInstallAgentGates,
+} from './install-migrate.mjs';