arkgate 2.6.0 → 2.6.1

package/bin/lib/agent-gates.mjs

@@ -83,9 +83,48 @@ 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 (fs.existsSync(fullPath) && !force) {
+  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 {
@@ -224,10 +263,18 @@ export function packageManager(root) {
       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: fs.existsSync(path.join(root, 'package-lock.json')) ? 'npm ci' : 'npm install',
+    install,
     run: `npx ark-check ${checkArgs}`,
   };
 }
@@ -268,12 +315,27 @@ ${rows}`;
 }
 
 export function agentInstructions(root) {
-  const steps = AGENT_CONTRACT.steps(arkCheckCommand(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
 
-Before editing TypeScript or JavaScript source files:
+## 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 parallel workflow
+   from the long skill list.
+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).
+
+Other \`/ark-*\` skills are optional escapes (adopt, coverage, runtime, …), not required steps.
+
+## Before editing TypeScript or JavaScript source files
 
 ${steps}
 
@@ -286,7 +348,8 @@ an ungoverned location:
 
 ${layerPlacementTable()}
 
-The project is only considered Ark-enforced when the write gate, CI gate, and runtime path all pass.
+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).
 `;
 }
 
@@ -517,9 +580,28 @@ export function grokHooks(root) {
   }, 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) {
-  if (args.tools && args.tools.length > 0) {
-    return { tools: new Set(args.tools), source: 'explicit' };
+  const explicit = normalizeToolsList(args.tools);
+  if (explicit.length > 0) {
+    return { tools: new Set(explicit), source: 'explicit' };
   }
   const root = args.root;
   const detected = new Set();
@@ -722,7 +804,8 @@ export function wireCodexMcp(root, force) {
     esc(absConfig),
   ]);
   const argsToml = args.map((value) => `"${value}"`).join(', ');
-  const block = `[mcp_servers.ark]
+  const makeBlock = (table) =>
+    `[mcp_servers.${table}]
 command = "${command}"
 args = [${argsToml}]`;
   let existing = '';
@@ -733,11 +816,58 @@ args = [${argsToml}]`;
   }
   const tableRe = /(^|\n)\[mcp_servers\.ark\][^\n]*\n(?:(?!\[)[^\n]*\n?)*/;
   const hasTable = tableRe.test(existing);
+  const existingRoot = hasTable ? extractCodexArkRootFromToml(existing) : null;
+  let differentProject = false;
+  try {
+    differentProject = Boolean(
+      existingRoot && path.resolve(existingRoot) !== absRoot
+    );
+  } catch {
+    differentProject = Boolean(existingRoot);
+  }
   // Fail-closed: rewrite temp/upgrade roots and dual/wrong bins even without --force.
   const mustRewrite = hasTable && codexArkBlockNeedsRewrite(existing, absRoot);
+
+  // Multi-project: another project's [mcp_servers.ark] is present. Without --force,
+  // add a project-scoped table so we do not steal the primary binding.
+  if (hasTable && differentProject && !force && !mustRewrite) {
+    const slug =
+      path
+        .basename(absRoot)
+        .replace(/[^a-zA-Z0-9_-]/g, '_')
+        .slice(0, 48) || 'project';
+    const table = `ark_${slug}`;
+    const multiRe = new RegExp(
+      `(^|\\n)\\[mcp_servers\\.${table.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\][^\\n]*\\n(?:(?!\\[)[^\\n]*\\n?)*`
+    );
+    const block = makeBlock(table);
+    let next;
+    if (multiRe.test(existing)) {
+      next = existing.replace(multiRe, (match) => `${match.startsWith('\n') ? '\n' : ''}${block}\n`);
+    } else {
+      const sep =
+        existing.length === 0
+          ? ''
+          : existing.endsWith('\n\n')
+            ? ''
+            : existing.endsWith('\n')
+              ? '\n'
+              : '\n\n';
+      next = `${existing}${sep}${block}\n`;
+    }
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, next);
+    } catch (error) {
+      return { status: 'failed', file, message: error.message };
+    }
+    return { status: 'written-multi', file, table, primaryUnchanged: true };
+  }
+
   if (hasTable && !force && !mustRewrite) {
     return { status: 'skipped', file };
   }
+  const block = makeBlock('ark');
   let next;
   if (hasTable) {
     next = existing.replace(tableRe, (match) => `${match.startsWith('\n') ? '\n' : ''}${block}\n`);
@@ -942,12 +1072,21 @@ export function codexArkBlockHasPreferredBin(tomlText) {
   return bins.length === 1 && bins[0] === PREFERRED_MCP_BIN;
 }
 
+/**
+ * True when the primary [mcp_servers.ark] block is broken (temp root / dual bin)
+ * and should be rewritten fail-closed. Different permanent project roots are NOT
+ * "broken" — multi-project wiring uses a secondary table instead.
+ */
 export function codexArkBlockNeedsRewrite(tomlText, absRoot) {
   if (!tomlText || !tomlText.includes('[mcp_servers.ark]')) return true;
   const rootArg = extractCodexArkRootFromToml(tomlText);
   if (!rootArg || isTempOrUpgradeRoot(rootArg)) return true;
+  // Permanent different project: multi-project path handles this (do not steal primary).
   try {
-    if (path.resolve(rootArg) !== path.resolve(absRoot)) return true;
+    if (path.resolve(rootArg) !== path.resolve(absRoot)) {
+      if (!isTempOrUpgradeRoot(rootArg)) return false;
+      return true;
+    }
   } catch {
     return true;
   }
@@ -955,9 +1094,215 @@ export function codexArkBlockNeedsRewrite(tomlText, absRoot) {
   return false;
 }
 
+/**
+ * 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()))
+    );
+  const scriptHasTypecheck = (s) =>
+    Boolean(
+      s &&
+        ((typeof s.typecheck === 'string' && s.typecheck.trim()) ||
+          (typeof s['type-check'] === 'string' && s['type-check'].trim()) ||
+          (typeof s['check:types'] === 'string' && s['check:types'].trim()) ||
+          (typeof s.tsc === 'string' && /\btsc\b/.test(s.tsc)))
+    );
+
+  let hasLintScript = scriptHasLint(scripts);
+  let hasTypecheckScript = scriptHasTypecheck(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 (scriptHasTypecheck(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;
+}
+
 /**
  * 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 }}
+ * @returns {{ gaps: object[], hosts: object[], mcp: object, codexHome: object|null, coreOptional: object[], originReport: object, baseline: object, layerBalance: object|null, deployPath: object|null }}
  */
 export function collectAdoptionGaps(root, config, coverage) {
   const gaps = [];
@@ -1202,6 +1547,79 @@ export function collectAdoptionGaps(root, config, coverage) {
     }
   }
 
+  // --- 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',
+      });
+    }
+  }
+
   return {
     gaps,
     hosts,
@@ -1211,6 +1629,7 @@ export function collectAdoptionGaps(root, config, coverage) {
     originReport,
     baseline,
     layerBalance,
+    deployPath,
   };
 }
 
@@ -1335,9 +1754,11 @@ export function runInstallAgentGates(args) {
     runMigrateCommands(root);
     return;
   }
-  if (args.tools) {
-    const unknown = args.tools.filter((tool) => !KNOWN_TOOLS.includes(tool));
-    if (args.tools.length === 0 || unknown.length > 0) {
+  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(', ')})` : '')
@@ -1433,7 +1854,15 @@ export function runInstallAgentGates(args) {
   let staleSkipped = 0;
   for (const result of results) {
     const marker =
-      result.status === 'written' ? 'wrote' : result.status === 'failed' ? 'FAILED' : 'skipped';
+      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 = '';
@@ -1506,7 +1935,11 @@ export function runInstallAgentGates(args) {
     codexMcp = wireCodexMcp(root, args.force);
     console.log('');
     console.log(`Codex MCP registration (${codexMcp.file}):`);
-    if (codexMcp.status === 'skipped') {
+    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})`);

package/bin/lib/doctor-plan.mjs

@@ -351,11 +351,15 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   });
   console.log('');
   console.log(color.bold('Operating mode'));
+  // Modes are detected states, not user-picked settings. Plain-language "what you do next".
   const modeMark = mode === 'enforce' ? ok : mode === 'adapt' ? warn : warn;
   const modeHelp = {
-    suggest: 'starter shape / thin tree — expand layers as you grow',
-    adapt: 'contract still needs to match real layout or raise coverage',
-    enforce: 'contract governs enough code; gates can honestly hold the line',
+    suggest:
+      'Setup — Ark proposes a starting architecture shape. You do not pick this mode; it means the tree is thin or new. Next: accept the shape (ark start / ark init) and add real layers as you grow.',
+    adapt:
+      'Align — contract and folders still disagree, or coverage is weak / debt is open. You do not pick this mode. Next: classify ungoverned dirs (/ark-contract, /ark-adopt), run the plan (/ark-autopilot or /ark-loop). Gates do not fully protect you yet.',
+    enforce:
+      'Guard — contract governs enough real code and edges are clean enough for gates to protect you. You do not pick this mode; you arrived here. Next: keep CI/write gates on; only NEW violations should fail.',
   };
   line(modeMark, `${mode.toUpperCase()} — ${modeHelp[mode]}`);
   if (emptyScope) {
@@ -466,7 +470,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   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');
+    line(
+      ok,
+      'Hosts, MCP argv, core optionality, origin report, baseline policy, and deploy-path lint/types look complete'
+    );
   } else {
     for (const gap of adoption.gaps) {
       const mark = gap.severity === 'warn' ? warn : gap.severity === 'info' ? warn : bad;