arkgate 2.12.0 → 3.0.0

package/bin/lib/enforcement-profiles.mjs

@@ -0,0 +1,97 @@
+/**
+ * Static host support plus preflight validation for requested write guarantees.
+ * Installed evidence remains authoritative in write-path-capabilities.mjs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectWritePathCapabilities } from './write-path-detect.mjs';
+import {
+  HOST_SUPPORT_HOSTS,
+  HOST_SUPPORT_MATRIX,
+} from './host-support-matrix.mjs';
+import { KNOWN_TOOLS, normalizeToolsList } from './skill-install.mjs';
+
+export const HOST_ENFORCEMENT_SUPPORT = Object.freeze(
+  Object.fromEntries(
+    HOST_SUPPORT_HOSTS.map((host) => {
+      const profile = HOST_SUPPORT_MATRIX[host];
+      return [
+        host,
+        Object.freeze({
+          hardWrite: profile.capabilities['hard-write'],
+          advisoryWrite: profile.capabilities['advisory-write'],
+          hookPath: profile.hookPath,
+        }),
+      ];
+    })
+  )
+);
+
+export const WRITE_PROFILE_HOSTS = HOST_SUPPORT_HOSTS;
+
+export function validateSelectedTools(tools) {
+  if (tools == null) return { ok: true, tools: null };
+  const selected = normalizeToolsList(tools);
+  const unknown = selected.filter((tool) => !KNOWN_TOOLS.includes(tool));
+  if (selected.length === 0 || unknown.length > 0) {
+    return {
+      ok: false,
+      error:
+        `--tools expects a comma-separated subset of: ${KNOWN_TOOLS.join(', ')}` +
+        (unknown.length > 0 ? ` (unknown: ${unknown.join(', ')})` : ''),
+    };
+  }
+  return { ok: true, tools: selected };
+}
+
+export function hasHardWriteHook(root, host) {
+  return detectWritePathCapabilities(root, host).capabilities['hard-write'];
+}
+
+export function validateHardWriteRequest({ root, host, tools, force = false }) {
+  const toolSelection = validateSelectedTools(tools);
+  if (!toolSelection.ok) return toolSelection;
+  if (host == null) return { ok: true, host: null, tools: toolSelection.tools };
+
+  const normalizedHost = String(host).trim().toLowerCase();
+  const support = HOST_ENFORCEMENT_SUPPORT[normalizedHost];
+  if (!support) {
+    return {
+      ok: false,
+      error: `Unknown write host "${normalizedHost}". Expected: ${WRITE_PROFILE_HOSTS.join(', ')}.`,
+    };
+  }
+  if (!support.hardWrite) {
+    return {
+      ok: false,
+      error:
+        `${normalizedHost} supports advisory-write plus the shared CI check, not a hard local write hook. ` +
+        'Omit --require-write-hook, keep --strict-merge in CI, and require that status to block merges.',
+    };
+  }
+
+  const selectedTools = toolSelection.tools ?? [normalizedHost];
+  if (!selectedTools.includes(normalizedHost)) {
+    return {
+      ok: false,
+      error: `--require-write-hook ${normalizedHost} requires --tools to include ${normalizedHost}.`,
+    };
+  }
+
+  const hookFile = path.join(root, support.hookPath);
+  if (fs.existsSync(hookFile) && !force && !hasHardWriteHook(root, normalizedHost)) {
+    return {
+      ok: false,
+      error:
+        `${support.hookPath} already exists without an Ark hard-write hook and would be preserved. ` +
+        'Use --force to replace that host file, or omit --require-write-hook for merge-only enforcement.',
+    };
+  }
+
+  return {
+    ok: true,
+    host: normalizedHost,
+    tools: selectedTools,
+    support,
+  };
+}

package/bin/lib/field-install.mjs

@@ -21,6 +21,68 @@ function arkPackageVersion() {
   }
 }
 
+function matchingBrace(text, openIndex) {
+  let depth = 0;
+  let quoted = false;
+  let escaped = false;
+  for (let index = openIndex; index < text.length; index += 1) {
+    const char = text[index];
+    if (quoted) {
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === '"') quoted = false;
+      continue;
+    }
+    if (char === '"') quoted = true;
+    else if (char === '{') depth += 1;
+    else if (char === '}' && --depth === 0) return index;
+  }
+  return -1;
+}
+
+function addDevDependencyPreservingFormat(source, version) {
+  const multiline = /\r?\n/.test(source);
+  const eol = source.includes('\r\n') ? '\r\n' : '\n';
+  const rootPropertyIndent = source.match(/\r?\n([ \t]+)"[^"\n]+"\s*:/)?.[1] ?? '  ';
+  const indentUnit = rootPropertyIndent;
+  const encoded = JSON.stringify(version);
+  const devMatch = /"devDependencies"\s*:\s*\{/.exec(source);
+
+  if (devMatch) {
+    const open = source.indexOf('{', devMatch.index);
+    const close = matchingBrace(source, open);
+    if (close === -1) throw new Error('Unbalanced devDependencies object');
+    const body = source.slice(open + 1, close);
+    if (!multiline) {
+      const addition = body.trim() ? `,"arkgate":${encoded}` : `"arkgate":${encoded}`;
+      return `${source.slice(0, close)}${addition}${source.slice(close)}`;
+    }
+    const beforeClose = source.slice(0, close);
+    const trailing = beforeClose.match(/\s*$/)?.[0] ?? '';
+    const contentEnd = close - trailing.length;
+    const closingIndent = trailing.slice(trailing.lastIndexOf('\n') + 1);
+    const propertyIndent = `${closingIndent}${indentUnit}`;
+    const addition = body.trim()
+      ? `,${eol}${propertyIndent}"arkgate": ${encoded}`
+      : `${propertyIndent}"arkgate": ${encoded}`;
+    return `${source.slice(0, contentEnd)}${addition}${eol}${closingIndent}${source.slice(close)}`;
+  }
+
+  const rootClose = source.lastIndexOf('}');
+  if (rootClose === -1) throw new Error('Unbalanced package.json object');
+  const rootBody = source.slice(0, rootClose);
+  if (!multiline) {
+    const separator = rootBody.trim().endsWith('{') ? '' : ',';
+    return `${rootBody}${separator}"devDependencies":{"arkgate":${encoded}}${source.slice(rootClose)}`;
+  }
+  const trailing = rootBody.match(/\s*$/)?.[0] ?? '';
+  const contentEnd = rootClose - trailing.length;
+  const rootClosingIndent = trailing.slice(trailing.lastIndexOf('\n') + 1);
+  const separator = source.slice(0, contentEnd).trimEnd().endsWith('{') ? '' : ',';
+  const addition = `${separator}${eol}${rootPropertyIndent}"devDependencies": {${eol}${rootPropertyIndent}${indentUnit}"arkgate": ${encoded}${eol}${rootPropertyIndent}}`;
+  return `${source.slice(0, contentEnd)}${addition}${eol}${rootClosingIndent}${source.slice(rootClose)}`;
+}
+
 /**
  * Ensure a check command string includes `--baseline <file>`.
  * Only touches strings that already invoke ark-check / arkgate-check.
@@ -150,16 +212,15 @@ export function pinArkgateDevDependency(root, opts = {}) {
     return { changed: false, reason: 'no-package-json' };
   }
   let pkg;
+  let source;
   try {
-    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    source = fs.readFileSync(pkgPath, 'utf8');
+    pkg = JSON.parse(source);
   } catch {
     return { changed: false, reason: 'unreadable-package-json' };
   }
   const deps = pkg.dependencies && typeof pkg.dependencies === 'object' ? pkg.dependencies : {};
-  const dev =
-    pkg.devDependencies && typeof pkg.devDependencies === 'object'
-      ? { ...pkg.devDependencies }
-      : {};
+  const dev = pkg.devDependencies && typeof pkg.devDependencies === 'object' ? pkg.devDependencies : {};
   if (typeof deps.arkgate === 'string' || typeof dev.arkgate === 'string') {
     return {
       changed: false,
@@ -174,12 +235,8 @@ export function pinArkgateDevDependency(root, opts = {}) {
       : shipped
         ? `^${shipped}`
         : 'latest';
-  dev.arkgate = version;
   if (opts.write !== false) {
-    fs.writeFileSync(
-      pkgPath,
-      `${JSON.stringify({ ...pkg, devDependencies: dev }, null, 2)}\n`
-    );
+    fs.writeFileSync(pkgPath, addDevDependencyPreservingFormat(source, version));
   }
   return { changed: true, reason: 'added', version };
 }

package/bin/lib/gate-files.mjs

@@ -119,6 +119,40 @@ export const REQUIRED_GATE_FILES = [
   '.mcp.json',
 ];
 const REQUIRED_GATE_WORKFLOW = '.github/workflows/*.yml running ark-check';
+const COMPACT_ROUTER = /<!--\s*arkgate:compact-router host=([a-z]+)\s*-->/;
+
+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'],
+  windsurf: ['.windsurf/rules/ark.md'],
+  cline: ['.clinerules/ark.md'],
+  copilot: ['.github/copilot-instructions.md'],
+  kiro: ['.kiro/steering/ark.md'],
+  roo: ['.roo/rules/ark.md'],
+  continue: ['.continue/rules/ark.md'],
+  gemini: ['GEMINI.md'],
+};
+
+export function compactRouterHost(root) {
+  try {
+    const agents = fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8');
+    return agents.match(COMPACT_ROUTER)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function isCompactRouterAgentsContent(text) {
+  return typeof text === 'string' && COMPACT_ROUTER.test(text);
+}
+
+function hasCompactHostRegistration(root, host) {
+  if (host === 'none') return fs.existsSync(path.join(root, '.mcp.json'));
+  const files = COMPACT_HOST_FILES[host];
+  return Boolean(files) && files.every((relativePath) => fs.existsSync(path.join(root, relativePath)));
+}
 
 export function hasArkWorkflow(root) {
   const workflowsDir = path.join(root, '.github', 'workflows');
@@ -141,9 +175,14 @@ export function hasArkWorkflow(root) {
 }
 
 export function missingGates(root) {
-  const missing = REQUIRED_GATE_FILES.filter(
-    (relativePath) => !fs.existsSync(path.join(root, relativePath))
-  );
+  const compactHost = compactRouterHost(root);
+  const required = compactHost
+    ? REQUIRED_GATE_FILES.filter((relativePath) => relativePath !== '.mcp.json')
+    : REQUIRED_GATE_FILES;
+  const missing = required.filter((relativePath) => !fs.existsSync(path.join(root, relativePath)));
+  if (compactHost && !hasCompactHostRegistration(root, compactHost)) {
+    missing.push(`compact host registration (${compactHost})`);
+  }
   if (!hasArkWorkflow(root)) missing.push(REQUIRED_GATE_WORKFLOW);
   return missing;
 }

package/bin/lib/graph-cycles.mjs

@@ -1,56 +1,6 @@
-/**
- * Import-graph cycle detection (Tarjan) for ark-check.
- * Extracted from ark-check entry (R3).
- */
-export function detectCycles(graph) {
-  let index = 0;
-  const indices = new Map();
-  const low = new Map();
-  const onStack = new Set();
-  const stack = [];
-  const components = [];
-
-  // ponytail: recursive Tarjan; make it iterative only if a real repo blows the stack.
-  const strongconnect = (v) => {
-    indices.set(v, index);
-    low.set(v, index);
-    index += 1;
-    stack.push(v);
-    onStack.add(v);
-    for (const w of [...(graph.get(v) ?? [])].sort()) {
-      if (!graph.has(w)) continue;
-      if (!indices.has(w)) {
-        strongconnect(w);
-        low.set(v, Math.min(low.get(v), low.get(w)));
-      } else if (onStack.has(w)) {
-        low.set(v, Math.min(low.get(v), indices.get(w)));
-      }
-    }
-    if (low.get(v) === indices.get(v)) {
-      const comp = [];
-      let w;
-      do {
-        w = stack.pop();
-        onStack.delete(w);
-        comp.push(w);
-      } while (w !== v);
-      if (comp.length > 1) components.push(comp.sort());
-    }
-  };
+/** Compatibility adapter; canonical Tarjan evaluation lives in the bundled Kernel engine. */
+import { detectArchitectureCycles } from './analysis-engine.mjs';
 
-  for (const v of [...graph.keys()].sort()) {
-    if (!indices.has(v)) strongconnect(v);
-  }
-
-  return components
-    .sort((a, b) => a[0].localeCompare(b[0]))
-    .map((members) => ({
-      ruleId: 'CIRCULAR_DEPENDENCY',
-      file: members[0],
-      line: 1,
-      target: members.join(' → '),
-      message: `Circular dependency among ${members.length} files: ${members.join(' → ')} → ${members[0]}.`,
-      // Graph is value/runtime edges only (type-only imports omitted).
-      cycleKind: 'value',
-    }));
+export function detectCycles(graph) {
+  return detectArchitectureCycles(graph);
 }

package/bin/lib/hook-templates.mjs

@@ -1,5 +1,5 @@
 /**
- * Host hook / MCP project templates for agent-gate install (Claude, Grok).
+ * Host hook / MCP project templates for agent-gate install (Claude, Grok, Codex).
  * Kept out of agent-gates.mjs so install orchestration stays scannable (explore gap #5).
  */
 import { execCommandParts, execRunner } from '../ark-shared.mjs';
@@ -41,6 +41,38 @@ export function claudeSettings(root) {
   }, null, 2)}\n`;
 }
 
+export function codexHooks(root) {
+  const runner = execRunner(root);
+  const codexRoot = '${CODEX_PROJECT_DIR:-${PWD:-.}}';
+  return `${JSON.stringify({
+    hooks: {
+      SessionStart: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              timeout: 30,
+              command: `${runner} ${PREFERRED_MCP_BIN} --session-context --root "${codexRoot}" --config ark.config.json`,
+            },
+          ],
+        },
+      ],
+      PreToolUse: [
+        {
+          matcher: 'ApplyPatch|apply_patch|Write|Edit|MultiEdit',
+          hooks: [
+            {
+              type: 'command',
+              timeout: 30,
+              command: `${runner} ${PREFERRED_MCP_BIN} --hook --hook-repair --root "${codexRoot}" --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) {

package/bin/lib/host-support-matrix.mjs

@@ -0,0 +1,83 @@
+/**
+ * Canonical host support promises.
+ *
+ * These records describe what ArkGate can install for each supported host.
+ * Installed evidence remains authoritative for a specific repository and is
+ * reported separately by write-path-capabilities.mjs.
+ */
+
+function hostProfile(label, hookPath, hookSurface, hardWrite, repairPayload) {
+  return Object.freeze({
+    label,
+    hookPath,
+    hookSurface,
+    capabilities: Object.freeze({
+      'hard-write': hardWrite,
+      'advisory-write': true,
+      'merge-gate': true,
+      'repair-payload': repairPayload,
+    }),
+  });
+}
+
+export const HOST_SUPPORT_MATRIX = Object.freeze({
+  claude: hostProfile(
+    'Claude Code',
+    '.claude/settings.json',
+    'PreToolUse `Write` / `Edit` / `MultiEdit`',
+    true,
+    true
+  ),
+  grok: hostProfile(
+    'Grok Build',
+    '.grok/hooks/ark-write-gate.json',
+    'PreToolUse `write` / `search_replace` (plus aliases)',
+    true,
+    true
+  ),
+  cursor: hostProfile('Cursor', null, null, false, false),
+  codex: hostProfile(
+    'OpenAI Codex',
+    '.codex/hooks.json',
+    'Best-effort PreToolUse `apply_patch`; Code Mode hosts may bypass the event',
+    false,
+    false
+  ),
+});
+
+export const HOST_SUPPORT_HOSTS = Object.freeze(Object.keys(HOST_SUPPORT_MATRIX));
+
+export function getHostSupportProfile(host) {
+  const normalized = typeof host === 'string' ? host.trim().toLowerCase() : '';
+  return HOST_SUPPORT_MATRIX[normalized] ?? null;
+}
+
+export function formatHostSupportSummary(profile) {
+  if (!profile) return 'unknown host; no local write guarantee';
+  const capabilities = profile.capabilities;
+  const write = capabilities['hard-write']
+    ? 'hard local write boundary'
+    : 'no hard local write boundary';
+  const repair = capabilities['repair-payload'] ? 'repair payload' : 'no hard-boundary repair';
+  return `${write} + advisory MCP + CI check + ${repair}`;
+}
+
+export function renderHostSupportMatrixMarkdown() {
+  const rows = HOST_SUPPORT_HOSTS.map((host) => {
+    const profile = HOST_SUPPORT_MATRIX[host];
+    const capabilities = profile.capabilities;
+    const local = capabilities['hard-write']
+      ? `Hard block for ${profile.hookSurface}`
+      : 'No hard hook; MCP/rules are advisory';
+    const repair = capabilities['repair-payload']
+      ? 'Emitted on hook deny; host must re-inject'
+      : 'No hard-boundary payload';
+    return `| ${profile.label} | ${local} | Advisory; the agent must call it | Available \`arkgate-check --strict-merge\` check | ${repair} |`;
+  }).join('\n');
+
+  return `| Host | Local write boundary | MCP validation | CI / merge path | Repair payload |
+|------|----------------------|----------------|-----------------|----------------|
+${rows}
+
+This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair payloads never write code silently: the host must re-inject the candidate and ArkGate revalidates it. Run \`arkgate-check --doctor\` for the evidence actually detected in the current repository.`;
+}

package/bin/lib/install-migrate.mjs

@@ -14,17 +14,20 @@ import {
   codexPromptsDir,
   codexConfigPath,
   isTempOrUpgradeRoot,
+  usesDefaultCodexHome,
   wireCodexMcp,
 } from './codex-home.mjs';
 import {
   PREFERRED_MCP_BIN,
   claudeSettings,
+  codexHooks,
   grokHooks,
   grokProjectConfig,
 } from './hook-templates.mjs';
 import {
   hasCheckArchitectureScript,
   ensureTypecheckScript,
+  compactRouterHost,
   writeTemplate,
 } from './gate-files.mjs';
 import {
@@ -35,14 +38,13 @@ import {
   detectCiNode,
   cursorRule,
   instructionRule,
+  compactAgentInstructions,
   codexTomlSnippet,
   arkCheckCommand,
   checkArchitectureScriptSnippet,
 } from './ci-and-commands.mjs';
 import {
-  normalizeToolsList,
   resolveTools,
-  KNOWN_TOOLS,
   SKILL_TOOL_TARGETS,
   skillTemplates,
   stampSkill,
@@ -59,6 +61,11 @@ import {
   PREFERRED_CHECK_BIN,
   RUNNER_BEFORE_ARK,
 } from './mcp-adoption.mjs';
+import {
+  hasHardWriteHook,
+  validateHardWriteRequest,
+  validateSelectedTools,
+} from './enforcement-profiles.mjs';
 
 export function staleRunnerGateFiles(root) {
   const want = execRunner(root);
@@ -179,26 +186,53 @@ export function runInstallAgentGates(args) {
     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(', ')})` : '')
-      );
+    const selection = validateSelectedTools(args.tools);
+    if (!selection.ok) {
+      console.error(selection.error);
       process.exitCode = 2;
       return;
     }
+    args.tools = selection.tools;
+  }
+  const writeRequest = validateHardWriteRequest({
+    root,
+    host: args.requireWriteHook,
+    tools: args.tools,
+    force: args.force,
+  });
+  if (!writeRequest.ok) {
+    console.error(writeRequest.error);
+    process.exitCode = 2;
+    return;
+  }
+  if (writeRequest.host && args.tools == null) {
+    args.tools = writeRequest.tools;
+  }
+  if (writeRequest.host && args.skillsOnly && !hasHardWriteHook(root, writeRequest.host)) {
+    console.error(
+      `--skills-only cannot install the requested ${writeRequest.host} hard-write hook. ` +
+      'Remove --skills-only or omit --require-write-hook.'
+    );
+    process.exitCode = 2;
+    return;
   }
   const pm = packageManager(root);
   const hasCheckScript = hasCheckArchitectureScript(root);
-  const { tools, source } = resolveTools(args);
+  const { tools, source } = args.compact && args.tools == null
+    ? { tools: new Set(), source: 'compact-none' }
+    : resolveTools(args);
+  if (args.compact && tools.size > 1) {
+    console.error('--compact accepts exactly one selected host. Pass --tools <host>.');
+    process.exitCode = 2;
+    return;
+  }
   const toolSource =
     source === 'explicit'
       ? 'from --tools'
       : source === 'detected'
         ? 'auto-detected from config dirs'
+        : source === 'compact-none'
+          ? 'no active host detected'
         : 'default set — no agent config dirs found';
   console.log(`Agent gates for: ${[...tools].sort().join(', ')} (${toolSource})`);
   const templates = [];
@@ -209,15 +243,21 @@ export function runInstallAgentGates(args) {
   // 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) {
+    const typecheckBootstrap = ensureTypecheckScript(root, { write: !args.compact });
+    if (typecheckBootstrap.changed && !args.compact && !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)]);
+    const compactHost = args.compact ? [...tools][0] ?? null : null;
+    templates.push([
+      'AGENTS.md',
+      args.compact ? compactAgentInstructions(root, compactHost) : agentInstructions(root),
+    ]);
+    if (!args.compact || !compactHost || compactHost === 'claude') {
+      templates.push(['.mcp.json', mcpJson(root)]);
+    }
     templates.push([
       '.github/workflows/ark-check.yml',
       (() => {
@@ -230,13 +270,14 @@ export function runInstallAgentGates(args) {
     ]);
     if (tools.has('cursor')) {
       templates.push(['.cursor/mcp.json', mcpJson(root)]);
-      templates.push(['.cursor/rules/ark.mdc', cursorRule(root)]);
+      if (!args.compact) 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)]);
+      templates.push(['.codex/hooks.json', codexHooks(root)]);
+      if (!args.compact) templates.push(['docs/ark-codex-config.toml', codexTomlSnippet(root)]);
     }
     if (tools.has('grok')) {
       templates.push(['.grok/config.toml', grokProjectConfig(root)]);
@@ -274,18 +315,37 @@ export function runInstallAgentGates(args) {
   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]);
+  if (!args.compact) {
+    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]);
+      }
+    }
+  }
+
+  // A compact router can be moved back from an explicit host removal. Delete the
+  // generic MCP file only when it exactly matches Ark's generated artifact.
+  const priorCompactHost = compactRouterHost(root);
+  if (args.compact && priorCompactHost === 'none' && [...tools][0]) {
+    const genericMcp = path.join(root, '.mcp.json');
+    try {
+      if (fs.readFileSync(genericMcp, 'utf8') === mcpJson(root)) fs.rmSync(genericMcp);
+    } catch {
+      // Missing or customized user MCP configuration is deliberately retained.
     }
   }
 
   const results = templates.map(([relativePath, content]) =>
-    writeTemplate(root, relativePath, content, args.force)
+    writeTemplate(
+      root,
+      relativePath,
+      content,
+      args.force || (args.compact && relativePath === 'AGENTS.md' && priorCompactHost !== null)
+    )
   );
 
   console.log('Ark agent gate templates:');
@@ -370,16 +430,17 @@ export function runInstallAgentGates(args) {
   // without a manual copy step.
   //
   // Skip home-dir mutation when the project root is a temp/upgrade scratch *and*
-  // CODEX_HOME is the default (~/.codex). Fixtures must not rewrite the developer's
-  // real Codex config. When CODEX_HOME is redirected (unit tests set a temp home) or
-  // --codex-home is explicit, wire as usual.
+  // CODEX_HOME resolves to the default (~/.codex). Codex itself may export that exact
+  // path, so presence alone does not prove isolation. Fixtures must not rewrite the
+  // developer's real config. A genuinely redirected CODEX_HOME or explicit
+  // --codex-home still wires as requested.
   let codexMcp = null;
-  const wantCodexWire = tools.has('codex') || args.codexHome;
+  const wantCodexWire = !args.compact && (tools.has('codex') || args.codexHome);
   const skipHomeWire =
     wantCodexWire &&
     isTempOrUpgradeRoot(root) &&
     !args.codexHome &&
-    !process.env.CODEX_HOME;
+    usesDefaultCodexHome();
   if (wantCodexWire && !skipHomeWire) {
     codexMcp = wireCodexMcp(root, args.force);
     console.log('');
@@ -416,6 +477,14 @@ export function runInstallAgentGates(args) {
       `\nWarning: Codex home MCP registration failed (${codexMcp.message}). Repo gates were written; fix ~/.codex access or re-run with --tools codex --force.`
     );
   }
+  if (writeRequest.host) {
+    if (!hasHardWriteHook(root, writeRequest.host)) {
+      console.error(`\nFailed to verify the ${writeRequest.host} hard-write hook after install.`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`\nHard-write hook verified for ${writeRequest.host}.`);
+  }
   console.log('');
   console.log('Next steps:');
   console.log('  1. Review the generated files and commit the ones that match your tools.');