arkgate 3.6.0 → 3.7.0

package/bin/lib/codex-home.mjs

@@ -47,6 +47,7 @@ export function isTempOrUpgradeRoot(p) {
     /\/tmp\//i.test(n) ||
     /\/Temp\//i.test(n) ||
     /ark-upgrade/i.test(n) ||
+    /\/(?:\.claude|\.codex|\.grok)\/worktrees\//i.test(n) ||
     /\/T\/(?:ark-|grok-)/i.test(n) ||
     /[\\/]AppData[\\/]Local[\\/]Temp[\\/]/i.test(n)
   );
@@ -144,6 +145,23 @@ export function codexScopedTableForRoot(tomlText, absRoot) {
   return null;
 }
 
+/** True when project TOML owns the primary Ark MCP binding for that project. */
+export function codexProjectMcpIsValid(tomlText, projectRoot) {
+  const resolvedRoot = path.resolve(projectRoot);
+  const primary = codexPrimaryTable(tomlText);
+  if (!primary?.root || !/\b(ark|arkgate)-mcp\b/.test(primary.block)) return false;
+  const config = primary.block.match(/"--config"\s*,\s*"([^"]+)"/)?.[1];
+  if (!config) return false;
+  try {
+    return (
+      path.resolve(resolvedRoot, primary.root) === resolvedRoot &&
+      path.resolve(resolvedRoot, config) === path.join(resolvedRoot, 'ark.config.json')
+    );
+  } catch {
+    return false;
+  }
+}
+
 /** Extract --root from primary [mcp_servers.ark]. */
 export function extractCodexArkRootFromToml(tomlText) {
   return codexPrimaryTable(tomlText)?.root ?? null;
@@ -236,14 +254,11 @@ export function assessCodexHomeMcp(tomlText, absRoot) {
       message: scopedTable
         ? `Codex primary [mcp_servers.ark] is bound to another project (${rootArg}); ` +
           `this project is registered as [mcp_servers.${scopedTable}]. ` +
-          `Codex may still prefer the primary binding for ark://manifest — rebind if this repo should own it.`
+          `Install the project-scoped binding so this repo owns ark://manifest when active.`
         : `Codex home primary MCP --root is another permanent project ` +
           `(${rootArg || 'missing'} ≠ ${resolvedRoot}). ` +
-          `Install without --force adds a scoped [mcp_servers.ark_<slug>] table and leaves primary unchanged; ` +
-          `--force rebinds primary to this project.`,
-      fixArgs: scopedTable
-        ? '--install-agent-gates --tools codex --force'
-        : '--install-agent-gates --tools codex',
+          `Install the project-scoped binding for this repo; the global primary can remain unchanged.`,
+      fixArgs: '--install-agent-gates --tools codex',
     };
   }
 

package/bin/lib/design-smells.mjs

@@ -29,7 +29,7 @@ export const DESIGN_SMELL_OUTCOMES = Object.freeze({
   'io-under-application':
     'Business/application code reaches the database or external APIs directly — the AI will keep pasting I/O into the wrong place. Put data access behind a port/adapter.',
   'handler-in-persistence':
-    'HTTP handlers live under data/repository folders — names look like “storage” but they are routes. Move handlers to the API/UI layer so the AI stops mixing transport and storage.',
+    'Static framework HTTP imports or route definitions live under data/repository folders — names look like “storage” but the code still owns transport. Move HTTP handling to the API/UI layer so the AI stops mixing transport and storage.',
   'god-module':
     'A few huge files own too many responsibilities — the AI cannot safely edit one concern without breaking others. Split the pilot file by job (one export surface per concern).',
   'domain-logic-in-ui':
@@ -70,6 +70,12 @@ const IO_IMPORT_RE =
   /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm|typeorm|knex|mongodb|pg|mysql2|better-sqlite3|ioredis|redis)['"]|require\(\s*['"](?:@?prisma\/client|pg|knex|typeorm)/;
 const HANDLER_CONTENT_RE =
   /\b(?:@Controller|@Get|@Post|@Put|@Delete|Router\(\)|createRouter|express\.Router|fastify\.(?:get|post)|export\s+(?:async\s+)?function\s+(?:GET|POST|PUT|DELETE|PATCH)\b|export\s+const\s+(?:GET|POST|PUT|DELETE|PATCH)\s*=)/;
+const FRAMEWORK_HTTP_IMPORT_RE =
+  /(?:^|[;\n])\s*(?:import\s+(?:type\s+)?(?:[^;]{0,512}?\s+from\s+)?|export\s+(?:type\s+)?[^;]{0,512}?\s+from\s+)['"]next\/server(?:\.js)?['"]/;
+const ROUTE_DEFINITION_CALL_RE =
+  /\bdefineRoute\s*(?:<[\s\S]{1,512}?>)?\s*\(/;
+const ROUTE_DEFINITION_DECLARATION_RE =
+  /\b(?:export\s+)?(?:declare\s+)?(?:async\s+)?function\s+defineRoute\s*(?:<[\s\S]{1,512}?>)?\s*\(/g;
 const DOMAIN_LOGIC_UI_RE =
   /\b(?:export\s+)?(?:async\s+)?function\s+(?:can|calculate|compute|should)[A-Z]\w*|\b(?:export\s+)?const\s+(?:can|calculate|compute|should)[A-Z]\w*\s*=/;
 const EXPORT_RE =
@@ -139,7 +145,33 @@ function isPresentationLayer(name) {
 function isPersistenceLayer(name) {
   return (
     typeof name === 'string' &&
-    (/persist|repository|infra|data.?access/i.test(name) || name === 'PersistenceAdapters')
+    /persist|repository|data.?access/i.test(name)
+  );
+}
+
+function stripObviousCommentsAndTemplates(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/\/\/[^\n]*/g, ' ')
+    .replace(/`(?:\\[\s\S]|[^\\`])*`/g, ' ');
+}
+
+function hasFrameworkHttpImport(source) {
+  return FRAMEWORK_HTTP_IMPORT_RE.test(stripObviousCommentsAndTemplates(source));
+}
+
+function hasRouteDefinitionCall(source) {
+  const code = stripObviousCommentsAndTemplates(source)
+    .replace(/(["'])(?:\\.|(?!\1)[^\\\r\n])*\1/g, ' ')
+    .replace(ROUTE_DEFINITION_DECLARATION_RE, 'function __ark_defineRoute_declaration__(');
+  return ROUTE_DEFINITION_CALL_RE.test(code);
+}
+
+function hasHollowPersistenceShape(source) {
+  return (
+    hasFrameworkHttpImport(source) ||
+    hasRouteDefinitionCall(source) ||
+    HANDLER_CONTENT_RE.test(source)
   );
 }
 
@@ -172,6 +204,24 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) continue;
     relFiles.push(rel);
   }
+  // Y02: the general scan cap must not hide Persistence candidates in large
+  // trees. Filter by the stable role/path heuristics first, then bound reads.
+  const persistenceUniverse = [];
+  for (const f of files) {
+    const rel = normalizeRel(resolvedRoot, f);
+    if (!rel || rel.startsWith('..')) continue;
+    if (!/\.(ts|tsx|js|jsx|mts|cts)$/.test(rel)) continue;
+    if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) continue;
+    persistenceUniverse.push(rel);
+  }
+  const allPersistenceCandidates = [...new Set(persistenceUniverse)].sort().filter(
+    (rel) =>
+      PERSISTENCE_PATH_RE.test(rel) ||
+      isPersistenceLayer(layerNameFor(resolvedRoot, rel, config))
+  );
+  const persistenceCandidates = allPersistenceCandidates.slice(0, MAX_SCAN_FILES);
+  const persistenceCandidatesTruncated =
+    allPersistenceCandidates.length - persistenceCandidates.length;
 
   // soft-contract: layers with files but no rule edges
   const withoutRules = Array.isArray(coverage?.layersWithoutRules)
@@ -220,8 +270,7 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     }
     if (/\/(?:domain|application|infrastructure|adapters)\//.test(rel)) hasHexPorts = true;
 
-    const abs = path.join(resolvedRoot, rel);
-    const source = readTextLimited(abs);
+    const source = readTextLimited(path.join(resolvedRoot, rel));
     if (source == null) continue;
 
     const layer = layerNameFor(resolvedRoot, rel, config);
@@ -232,13 +281,6 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
       godEvidence.push(rel);
     }
 
-    if (
-      (PERSISTENCE_PATH_RE.test(rel) || isPersistenceLayer(layer)) &&
-      HANDLER_CONTENT_RE.test(source)
-    ) {
-      handlerInPersist.push(rel);
-    }
-
     if ((UI_PATH_RE.test(rel) || isPresentationLayer(layer)) && DOMAIN_LOGIC_UI_RE.test(source)) {
       domainInUi.push(rel);
     }
@@ -257,6 +299,13 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     }
   }
 
+  for (const rel of persistenceCandidates) {
+    const source = readTextLimited(path.join(resolvedRoot, rel));
+    if (source != null && hasHollowPersistenceShape(source)) {
+      handlerInPersist.push(rel);
+    }
+  }
+
   if (!falseGreen?.risk && ioUnderAppFiles.length > 0) {
     smells.push(
       makeDesignSmell({
@@ -270,13 +319,17 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
   }
 
   if (handlerInPersist.length > 0) {
+    const capNote =
+      persistenceCandidatesTruncated > 0
+        ? `; ${persistenceCandidatesTruncated} more Persistence candidate(s) were not inspected by the bounded scan`
+        : '';
     smells.push(
       makeDesignSmell({
         id: 'handler-in-persistence',
         severity: 'warn',
-        message: `HTTP/route handler shape found under persistence/repository paths (${handlerInPersist.length} file(s)) — semantic false-green risk.`,
+        message: `Static framework HTTP import or route-definition/handler shape found in Persistence-role modules (${handlerInPersist.length} file(s)${capNote}) — semantic false-green risk.`,
         evidence: handlerInPersist.slice(0, 12),
-        fix: 'Move handlers to Presentation/API; keep Persistence as data access only (/ark-explore shape-focus).',
+        fix: 'Move HTTP imports and route definitions to Presentation/API; keep Persistence as data access only (/ark-explore shape-focus).',
       })
     );
   }
@@ -414,7 +467,7 @@ function successSignalFor(id) {
     case 'io-under-application':
       return '0 Application-layer files import prisma/supabase/drizzle/pg clients; I/O behind ports';
     case 'handler-in-persistence':
-      return '0 HTTP handler shapes under persistence/repository globs';
+      return '0 static framework HTTP imports or route-definition/handler shapes in Persistence-role modules';
     case 'god-module':
       return 'Pilot god module split; fan-in and export surface reduced without new edge violations';
     case 'domain-logic-in-ui':

package/bin/lib/doctor-advisories.mjs

@@ -1,6 +1,6 @@
 /**
- * Doctor's advisory sensors, aggregated (W01 contract health + U05 ambient
- * state + X04 physical cohesion). Advisory only: nothing here feeds a
+ * Doctor's advisory sensors, aggregated (W01 contract health, U05 ambient
+ * state, X04 physical cohesion, Y03 parse health). Nothing here feeds a
  * verdict, designFitness, or an exit code. One seam keeps doctor-plan.mjs
  * inside its module budget as new advisory surfaces land.
  */
@@ -8,17 +8,30 @@ import { computeAmbientState, printAmbientStateSection } from './ambient-state.m
 import { computeContractHealth, printContractHealthSection } from './contract-smells.mjs';
 import {
   computePhysicalCohesion,
-  computeReshapePilot,
   printPhysicalCohesionSection,
 } from './physical-cohesion.mjs';
+import {
+  computeDecisionAwareReshapePilot,
+  computeReshapeDecisionMemory,
+  printReshapeDecisionsSection,
+} from './reshape-decisions.mjs';
+import { printParseHealthSection, summarizeParseHealth } from './parse-health.mjs';
 
-export function computeDoctorAdvisories(root, config, cov, rules, files, ts) {
+export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth) {
   const physicalCohesion = computePhysicalCohesion(root, files);
-  physicalCohesion.reshapePilot = computeReshapePilot(physicalCohesion, files, root);
+  const decisionMemory = computeReshapeDecisionMemory(root, files);
+  physicalCohesion.reshapeDecisions = decisionMemory.summary;
+  physicalCohesion.reshapePilot = computeDecisionAwareReshapePilot(
+    physicalCohesion,
+    files,
+    root,
+    decisionMemory
+  );
   return {
     contractHealth: computeContractHealth(root, config, cov, rules),
     ambientState: computeAmbientState(ts, root, config, files),
     physicalCohesion,
+    parseHealth: parseHealth ?? summarizeParseHealth(),
   };
 }
 
@@ -30,4 +43,6 @@ export function printDoctorAdvisories(advisories, io) {
     advisories.physicalCohesion?.reshapePilot,
     io
   );
+  printReshapeDecisionsSection(advisories.physicalCohesion?.reshapeDecisions, io);
+  printParseHealthSection(advisories.parseHealth, io);
 }

package/bin/lib/doctor-plan.mjs

@@ -424,7 +424,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     patternBets: patternBetsForLoop,
     designSmells,
   });
-  const { contractHealth, ambientState, physicalCohesion } = computeDoctorAdvisories(root, config, cov, rules, files, options.ts); // W01+U05+X04 advisories — never a verdict
+  const doctorAdvisories = computeDoctorAdvisories(root, config, cov, rules, files, options.ts, options.parseHealth); // advisory only — never a verdict
 
   if (asJson) {
     console.log(
@@ -461,11 +461,9 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             goldenPattern,
             // Q04: one-pilot loop (extraction card → re-doctor).
             pilotLoop,
-            // Advisories, never a verdict: W01 contract health, U05 ambient
-            // state (opt-in), X04 physical cohesion + proposed reshape pilot.
-            contractHealth,
-            ambientState,
-            physicalCohesion,
+            // Advisories, never a verdict: W01 contract health, U05 ambient state,
+            // X04 physical cohesion/reshape pilot, Y03 parse health.
+            ...doctorAdvisories,
             governed: cov.governed,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
@@ -647,7 +645,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     );
   }
 
-  printDoctorAdvisories({ contractHealth, ambientState, physicalCohesion }, { line, warn, color }); // advisory sections
+  printDoctorAdvisories(doctorAdvisories, { line, warn, color }); // advisory sections
 
   console.log('');
   console.log(color.bold('Coverage'));

package/bin/lib/gate-files.mjs

@@ -125,7 +125,7 @@ const COMPACT_HOST_FILES = {
   claude: ['.claude/settings.json'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json'],
   cursor: ['.cursor/mcp.json'],
-  codex: ['.codex/hooks.json'],
+  codex: ['.codex/hooks.json', '.codex/config.toml'],
   windsurf: ['.windsurf/rules/ark.md'],
   cline: ['.clinerules/ark.md'],
   copilot: ['.github/copilot-instructions.md'],

package/bin/lib/hook-templates.mjs

@@ -73,8 +73,28 @@ export function codexHooks(root) {
   }, null, 2)}\n`;
 }
 
+// Codex project config: modern Codex resolves .codex/config.toml from the active
+// project, so the primary `ark` binding can stay local instead of competing in
+// the user's global $CODEX_HOME across every adopted repository.
+export function codexProjectConfig(root) {
+  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
+    '--root',
+    '.',
+    '--config',
+    'ark.config.json',
+  ]);
+  const esc = (value) => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const argsToml = args.map((value) => `"${esc(value)}"`).join(', ');
+  return `# Generated by ark-check --install-agent-gates (Codex project scope).
+# Restart Codex after changes; MCP servers are loaded when the project session starts.
+[mcp_servers.ark]
+command = "${esc(command)}"
+args = [${argsToml}]
+`;
+}
+
 // Grok Build project config: MCP registration (commit-friendly relative paths — unlike
-// Codex's global config.toml, Grok loads .grok/config.toml from the project).
+// the optional Codex home fallback, Grok loads .grok/config.toml from the project).
 export function grokProjectConfig(root) {
   const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
     '--root',

package/bin/lib/html-report-advisories.mjs

@@ -152,6 +152,46 @@ function ambientStateHtml(state) {
   </section>`;
 }
 
+function reshapeDecisionsHtml(memory) {
+  if (!memory) return '';
+  const lifecycle = memory.lifecycle ?? {};
+  const rows = [];
+  if (memory.decisionFile?.invalid) {
+    rows.push(
+      `<p><span class="tag warn">invalid</span> ${esc(memory.decisionFile.path)} is ignored; no reshape decision suppresses a pilot.</p>`
+    );
+  }
+  for (const decision of memory.current ?? []) {
+    const tag = decision.verdict === 'accepted' ? 'ok' : 'warn';
+    const review = decision.reviewBy ? ` · review-by ${esc(decision.reviewBy)}` : '';
+    rows.push(
+      `<p><span class="tag ${tag}">${esc(decision.verdict)}</span> <b>${esc(decision.concept)}</b>${review} — ${esc(decision.reason)}${decision.suppressesPilot ? ' Pilot pressure suppressed; mirror facts remain visible.' : ' Pilot remains available.'}</p>`
+    );
+  }
+  if ((memory.currentCount ?? 0) > (memory.current?.length ?? 0)) {
+    rows.push(`<p class="muted">…(+${memory.currentCount - memory.current.length} more current decision(s))</p>`);
+  }
+  if ((lifecycle.expiredCount ?? 0) > 0) {
+    rows.push(`<p><span class="tag warn">expired</span> ${lifecycle.expiredCount} decision(s) no longer apply; pilot pressure is active again.</p>`);
+  }
+  if ((lifecycle.malformedCount ?? 0) > 0) {
+    rows.push(`<p><span class="tag warn">malformed</span> ${lifecycle.malformedCount} review-by date(s) are invalid; those decisions are ignored.</p>`);
+  }
+  if ((lifecycle.staleCount ?? 0) > 0) {
+    const stale = (lifecycle.stale ?? [])
+      .slice(0, 4)
+      .map((decision) => `<code>${esc(decision.concept)}</code>`)
+      .join(' · ');
+    const more = lifecycle.staleCount > 4 ? ` …(+${lifecycle.staleCount - 4} more)` : '';
+    rows.push(`<p><span class="tag warn">stale</span> ${lifecycle.staleCount} decision(s) have a changed anchor set and no longer apply: ${stale}${more}</p>`);
+  }
+  if ((lifecycle.undated ?? 0) > 0) {
+    rows.push(`<p class="muted">${lifecycle.undated} current decision(s) have no review-by date.</p>`);
+  }
+  if (rows.length === 0) return '';
+  return `<div data-advisory="reshapeDecisions"><h3>Reshape decisions <span class="muted">(explicit; pilot pressure only)</span></h3>${rows.join('\n')}</div>`;
+}
+
 function physicalCohesionHtml(pc) {
   if (!pc) return '';
   const findings = Array.isArray(pc.findings) ? pc.findings : [];
@@ -173,10 +213,28 @@ function physicalCohesionHtml(pc) {
   <section data-advisory="physicalCohesion">
     <h2>Physical cohesion <span class="muted">(advisory — facts, not a score; the verdict is unchanged)</span></h2>
     ${body}
+    ${reshapeDecisionsHtml(pc.reshapeDecisions)}
     ${pilot}
   </section>`;
 }
 
+function parseHealthHtml(health) {
+  if (!health) return '';
+  const files = Array.isArray(health.files) ? health.files : [];
+  const body = health.available === false
+    ? '<p class="muted">Parse health was not available for this rendering — no clean claim is made.</p>'
+    : health.affectedFiles === 0
+    ? `<p class="muted">No parse diagnostics found across ${health.scannedFiles ?? 0} governed file(s) scanned.</p>`
+    : `<p><span class="tag warn">${health.affectedFiles} affected</span> ${health.diagnosticCount} parse diagnostic(s) across ${health.scannedFiles} governed file(s).</p>` +
+      `<ul>${files.map((f) => `<li><code>${esc(f.file)}</code> — ${f.diagnosticCount} parse diagnostic(s)</li>`).join('')}</ul>` +
+      (health.truncated > 0 ? `<p class="muted">…(+${health.truncated} more affected file(s); doctor list capped)</p>` : '');
+  return `
+  <section data-advisory="parseHealth">
+    <h2>Parse health <span class="muted">(advisory — unreadable syntax is never silently called clean)</span></h2>
+    ${body}
+  </section>`;
+}
+
 /**
  * Render every doctor advisory as report sections. Keys must cover everything
  * `computeDoctorAdvisories` returns — the parity guard enforces it.
@@ -189,6 +247,7 @@ export function renderAdvisorySections(advisories, escape) {
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),
+    parseHealthHtml(advisories.parseHealth),
   ]
     .filter(Boolean)
     .join('\n');

package/bin/lib/install-migrate.mjs

@@ -15,6 +15,7 @@ import {
   codexSkillsDir,
   codexConfigPath,
   isTempOrUpgradeRoot,
+  upsertCodexMcpTable,
   usesDefaultCodexHome,
   wireCodexMcp,
 } from './codex-home.mjs';
@@ -22,6 +23,7 @@ import {
   PREFERRED_MCP_BIN,
   claudeSettings,
   codexHooks,
+  codexProjectConfig,
   grokHooks,
   grokProjectConfig,
 } from './hook-templates.mjs';
@@ -279,6 +281,7 @@ export function runInstallAgentGates(args) {
     }
     if (tools.has('codex')) {
       templates.push(['.codex/hooks.json', codexHooks(root)]);
+      templates.push(['.codex/config.toml', codexProjectConfig(root)]);
       if (!args.compact) templates.push(['docs/ark-codex-config.toml', codexTomlSnippet(root)]);
     }
     if (tools.has('grok')) {
@@ -341,14 +344,29 @@ export function runInstallAgentGates(args) {
     }
   }
 
-  const results = templates.map(([relativePath, content]) =>
-    writeTemplate(
+  const results = templates.map(([relativePath, content]) => {
+    if (relativePath === '.codex/config.toml') {
+      const fullPath = path.join(root, relativePath);
+      let existing = '';
+      try {
+        existing = fs.readFileSync(fullPath, 'utf8');
+      } catch {
+        // A missing project config starts from the generated Ark table.
+      }
+      const tableStart = content.indexOf('[mcp_servers.ark]');
+      const generatedPrelude = tableStart > 0 ? content.slice(0, tableStart) : '';
+      const mergeBase = generatedPrelude ? existing.replace(generatedPrelude, '') : existing;
+      const merged = upsertCodexMcpTable(mergeBase, 'ark', content);
+      if (merged === existing) return { relativePath, status: 'skipped' };
+      return writeTemplate(root, relativePath, merged, true);
+    }
+    return writeTemplate(
       root,
       relativePath,
       content,
       args.force || (args.compact && relativePath === 'AGENTS.md' && priorCompactHost !== null)
-    )
-  );
+    );
+  });
 
   console.log('Ark agent gate templates:');
   let staleSkipped = 0;
@@ -427,11 +445,8 @@ export function runInstallAgentGates(args) {
     }
   }
 
-  // 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.
+  // Optional legacy/home fallback. Normal Codex installs use the project-scoped
+  // .codex/config.toml above, avoiding cross-project primary binding conflicts.
   //
   // Skip home MCP mutation when the project root is a temp/upgrade scratch *and*
   // CODEX_HOME is the default (~/.codex). Fixtures and agent smokes must not rewrite
@@ -439,7 +454,7 @@ export function runInstallAgentGates(args) {
   // home *skills* below; MCP binding of a temp root into default home is never safe.
   // A redirected CODEX_HOME (tests/isolation) may still wire as requested.
   let codexMcp = null;
-  const wantCodexWire = !args.compact && (tools.has('codex') || args.codexHome);
+  const wantCodexWire = !args.compact && !args.skillsOnly && args.codexHome;
   const skipHomeWire =
     wantCodexWire && isTempOrUpgradeRoot(root) && usesDefaultCodexHome();
   if (wantCodexWire && !skipHomeWire) {
@@ -475,7 +490,7 @@ export function runInstallAgentGates(args) {
   }
   if (codexMcp?.status === 'failed') {
     console.error(
-      `\nWarning: Codex home MCP registration failed (${codexMcp.message}). Repo gates were written; fix ~/.codex access or re-run with --tools codex --force.`
+      `\nWarning: Codex home MCP registration failed (${codexMcp.message}). Repo gates were written; fix ~/.codex access or re-run with --codex-home --force.`
     );
   }
   if (writeRequest.host) {

package/bin/lib/mcp-adoption.mjs

@@ -7,7 +7,11 @@ import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
 import { CORE_LAYER_NAMES } from './core-layers.mjs';
 import { falseGreenAdoptionGap } from './field-install.mjs';
-import { assessCodexHomeMcp, codexConfigPath } from './codex-home.mjs';
+import {
+  assessCodexHomeMcp,
+  codexConfigPath,
+  codexProjectMcpIsValid,
+} from './codex-home.mjs';
 import { detectWritePathCapabilities } from './write-path-detect.mjs';
 import { detectActiveAgentHost, skillTemplateNames } from './skill-install.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
@@ -19,7 +23,7 @@ export 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',
+  '.grok/hooks/ark-write-gate.json', '.grok/config.toml', '.codex/config.toml',
 ];
 export const COMMAND_GATE_JSON_FILES = ['.mcp.json', '.cursor/mcp.json'];
 // Primary CLI names (product) + one-major aliases. migrate-commands must strip ALL of these
@@ -148,7 +152,10 @@ export function collectAdoptionGaps(root, config, coverage) {
         dir: '.codex',
         // Official Codex REPO skill catalog (Agent Skills standard) — not .codex/prompts.
         skill: (n) => path.join(root, '.agents', 'skills', n, 'SKILL.md'),
-        extras: [['.codex/hooks.json', 'hooks']],
+        extras: [
+          ['.codex/hooks.json', 'hooks'],
+          ['.codex/config.toml', 'project MCP config'],
+        ],
         toolsFlag: 'codex',
       },
     ];
@@ -183,7 +190,17 @@ export function collectAdoptionGaps(root, config, coverage) {
 
   // --- Codex home MCP (temp path / wrong root / multi-project) ---
   let codexHome = null;
-  if (adopted && !isProducer) {
+  const codexProjectMcp = (() => {
+    try {
+      return codexProjectMcpIsValid(
+        fs.readFileSync(path.join(root, '.codex', 'config.toml'), 'utf8'),
+        root
+      );
+    } catch {
+      return false;
+    }
+  })();
+  if (adopted && !isProducer && !codexProjectMcp) {
     const codexFile = codexConfigPath();
     let toml = '';
     try {

package/bin/lib/parse-health.mjs

@@ -0,0 +1,74 @@
+/**
+ * Y03 — parse honesty over the ASTs already created by architecture-scan.
+ * Advisory only: counts are transported, never raw TypeScript diagnostics.
+ */
+
+export const PARSE_HEALTH_FILE_CAP = 12;
+
+function unavailableParseHealth(scannedFiles = 0) {
+  return {
+    advisory: true,
+    available: false,
+    status: 'unavailable',
+    scannedFiles,
+    affectedFiles: 0,
+    diagnosticCount: 0,
+    files: [],
+    truncated: 0,
+    overflow: false,
+  };
+}
+
+/** Aggregate cached/per-file parse counts into a deterministic doctor surface. */
+export function summarizeParseHealth(scanned) {
+  if (!Array.isArray(scanned)) return unavailableParseHealth();
+  const rows = scanned
+    .map(({ relFile, entry }) => ({
+      file: relFile,
+      diagnosticCount: entry?.parseDiagnosticCount,
+    }));
+  if (rows.some(({ file, diagnosticCount }) =>
+    typeof file !== 'string' || file.length === 0 ||
+    !Number.isSafeInteger(diagnosticCount) || diagnosticCount < 0
+  )) return unavailableParseHealth(rows.length);
+  const affected = rows
+    .filter(({ diagnosticCount }) => diagnosticCount > 0)
+    .sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  let diagnosticCount = 0;
+  for (const row of affected) {
+    if (!Number.isSafeInteger(diagnosticCount + row.diagnosticCount)) {
+      return unavailableParseHealth(rows.length);
+    }
+    diagnosticCount += row.diagnosticCount;
+  }
+  const truncated = Math.max(0, affected.length - PARSE_HEALTH_FILE_CAP);
+  return {
+    advisory: true,
+    available: true,
+    status: affected.length > 0 ? 'parse-diagnostics' : 'ok',
+    scannedFiles: rows.length,
+    affectedFiles: affected.length,
+    diagnosticCount,
+    files: affected.slice(0, PARSE_HEALTH_FILE_CAP),
+    truncated,
+    overflow: truncated > 0,
+  };
+}
+
+/** Human doctor section; clean parse health stays quiet. */
+export function printParseHealthSection(health, io) {
+  if (!health || health.affectedFiles === 0) return;
+  console.log('');
+  console.log(io.color.bold('Parse health (advisory)'));
+  io.line(
+    io.warn,
+    `${health.affectedFiles} governed file(s) carry ${health.diagnosticCount} parse diagnostic(s) across ${health.scannedFiles} scanned file(s).`
+  );
+  for (const finding of health.files ?? []) {
+    io.line(io.warn, `${finding.file} — ${finding.diagnosticCount} parse diagnostic(s)`);
+  }
+  if (health.truncated > 0) {
+    io.line(' ', io.color.dim(`…(+${health.truncated} more affected file(s); list capped)`));
+  }
+  io.line(' ', io.color.dim('advisory only — the gate verdict, design fitness, and pattern bets are unchanged'));
+}