arkgate 2.11.0 → 2.13.0

package/bin/lib/config-contract.mjs

@@ -0,0 +1,331 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/configContract.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/config-contract.mjs). Zero Node I/O.
+ */
+
+export const ARK_CONFIG_SCHEMA_VERSION = '1.0';
+export const ARK_CONFIG_SCHEMA_URL = 'https://unpkg.com/arkgate@2/schemas/ark.config.schema.json';
+const DEFAULT_LAYER_NAMES = [
+    'DomainModel',
+    'ApplicationOrchestration',
+    'PersistenceAdapters',
+    'IntegrationAdapters',
+    'WorkflowSagaEngine',
+    'BackgroundJobsScheduling',
+    'PresentationAdapters',
+    'ReportingReadModels',
+    'ExtensibilityMetadata',
+    'SecurityAuditObservability',
+    'Kernel',
+];
+const DEFAULT_ALLOWED_FLOWS = new Set([
+    'PresentationAdapters->ApplicationOrchestration',
+    'ApplicationOrchestration->DomainModel',
+    'WorkflowSagaEngine->ApplicationOrchestration',
+    'WorkflowSagaEngine->DomainModel',
+    'BackgroundJobsScheduling->ApplicationOrchestration',
+]);
+function createDefaultRules() {
+    const rules = [];
+    for (const from of DEFAULT_LAYER_NAMES) {
+        for (const to of DEFAULT_LAYER_NAMES) {
+            if (from === to || DEFAULT_ALLOWED_FLOWS.has(`${from}->${to}`))
+                continue;
+            rules.push({ from, to, allowed: false });
+        }
+    }
+    return rules;
+}
+export const DEFAULT_ARK_CONFIG_RULES = createDefaultRules();
+export const ARK_CONFIG_MIGRATIONS = [
+    { from: 'unversioned', to: ARK_CONFIG_SCHEMA_VERSION },
+];
+const stringArraySchema = {
+    type: 'array',
+    items: { type: 'string', minLength: 1 },
+    uniqueItems: true,
+};
+export const ARK_CONFIG_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: ARK_CONFIG_SCHEMA_URL,
+    title: 'ArkGate architecture contract',
+    description: 'Versioned contract consumed identically by ArkGate CLI, MCP, and ESLint surfaces.',
+    type: 'object',
+    additionalProperties: false,
+    required: ['$schema', 'schemaVersion', 'include', 'layers', 'rules'],
+    properties: {
+        $schema: {
+            type: 'string',
+            minLength: 1,
+            default: ARK_CONFIG_SCHEMA_URL,
+            description: 'Editor-facing URL or local path for this JSON Schema.',
+        },
+        schemaVersion: {
+            type: 'string',
+            const: ARK_CONFIG_SCHEMA_VERSION,
+            default: ARK_CONFIG_SCHEMA_VERSION,
+        },
+        name: { type: 'string', minLength: 1 },
+        include: { ...stringArraySchema, minItems: 1, default: ['src'] },
+        exclude: { ...stringArraySchema, default: [] },
+        excludeGenerated: { type: 'boolean', default: true },
+        frameworkOverlay: { type: 'string', minLength: 1 },
+        layers: {
+            type: 'array',
+            default: [],
+            items: { $ref: '#/$defs/layer' },
+        },
+        rules: {
+            type: 'array',
+            default: DEFAULT_ARK_CONFIG_RULES,
+            items: { $ref: '#/$defs/rule' },
+        },
+        cyclePolicy: {
+            type: 'string',
+            enum: ['strict', 'soft', 'framework-soft', 'off'],
+            default: 'strict',
+        },
+        dynamicImportAllowlist: { ...stringArraySchema, default: [] },
+        safety: {
+            $ref: '#/$defs/safety',
+            default: {
+                maxTsSuppressions: 0,
+                maxAnyCasts: 0,
+                allowInMemory: false,
+                allowDisabledPeerIsolation: false,
+            },
+        },
+    },
+    $defs: {
+        layer: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['name', 'patterns'],
+            properties: {
+                name: { type: 'string', minLength: 1 },
+                patterns: { ...stringArraySchema, minItems: 1 },
+                exclude: stringArraySchema,
+                intentPrefixes: stringArraySchema,
+                description: { type: 'string', minLength: 1 },
+                forbiddenGlobals: stringArraySchema,
+                mayImportInfrastructure: { type: 'boolean' },
+                optional: { type: 'boolean' },
+            },
+        },
+        rule: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['from', 'to', 'allowed'],
+            properties: {
+                from: { type: 'string', minLength: 1 },
+                to: { type: 'string', minLength: 1 },
+                allowed: { type: 'boolean' },
+                message: { type: 'string', minLength: 1 },
+                peerIsolation: { type: 'boolean' },
+                sliceFolders: { ...stringArraySchema, minItems: 1 },
+            },
+        },
+        safety: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                maxTsSuppressions: { type: 'integer', minimum: 0, default: 0 },
+                maxAnyCasts: { type: 'integer', minimum: 0, default: 0 },
+                allowInMemory: { type: 'boolean', default: false },
+                allowDisabledPeerIsolation: { type: 'boolean', default: false },
+            },
+        },
+    },
+};
+export class ArkConfigValidationError extends Error {
+    issues;
+    source;
+    constructor(source, issues) {
+        super(`Invalid ArkGate config (${source}):\n${issues
+            .map((issue) => `- ${issue.path}: ${issue.message}`)
+            .join('\n')}`);
+        this.name = 'ArkConfigValidationError';
+        this.source = source;
+        this.issues = issues;
+    }
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function propertyPath(parent, key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+        ? `${parent}.${key}`
+        : `${parent}[${JSON.stringify(key)}]`;
+}
+function valueType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function resolveSchemaRef(ref, root) {
+    const prefix = '#/$defs/';
+    if (!ref.startsWith(prefix))
+        return undefined;
+    return root.$defs[ref.slice(prefix.length)];
+}
+function validateNode(value, schema, path, root, issues) {
+    if (schema.$ref) {
+        const referenced = resolveSchemaRef(schema.$ref, root);
+        if (!referenced) {
+            issues.push({ path, message: `schema reference ${schema.$ref} cannot be resolved` });
+            return;
+        }
+        validateNode(value, referenced, path, root, issues);
+        return;
+    }
+    if (schema.const !== undefined && !Object.is(value, schema.const)) {
+        issues.push({ path, message: `must equal ${JSON.stringify(schema.const)}` });
+        return;
+    }
+    if (schema.enum && !schema.enum.some((candidate) => Object.is(candidate, value))) {
+        issues.push({ path, message: `must be one of ${schema.enum.map(String).join(', ')}` });
+        return;
+    }
+    if (schema.type === 'object') {
+        if (!isObject(value)) {
+            issues.push({ path, message: `must be an object; received ${valueType(value)}` });
+            return;
+        }
+        const properties = schema.properties ?? {};
+        for (const key of schema.required ?? []) {
+            if (value[key] === undefined) {
+                issues.push({ path: propertyPath(path, key), message: 'is required' });
+            }
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(value)) {
+                if (!(key in properties)) {
+                    issues.push({ path: propertyPath(path, key), message: 'unknown field' });
+                }
+            }
+        }
+        for (const [key, childSchema] of Object.entries(properties)) {
+            if (value[key] !== undefined) {
+                validateNode(value[key], childSchema, propertyPath(path, key), root, issues);
+            }
+        }
+        return;
+    }
+    if (schema.type === 'array') {
+        if (!Array.isArray(value)) {
+            issues.push({ path, message: `must be an array; received ${valueType(value)}` });
+            return;
+        }
+        if (schema.minItems !== undefined && value.length < schema.minItems) {
+            issues.push({ path, message: `must contain at least ${schema.minItems} item(s)` });
+        }
+        if (schema.uniqueItems) {
+            const serialized = value.map((entry) => JSON.stringify(entry));
+            if (new Set(serialized).size !== serialized.length) {
+                issues.push({ path, message: 'must not contain duplicate items' });
+            }
+        }
+        if (schema.items) {
+            value.forEach((entry, index) => validateNode(entry, schema.items, `${path}[${index}]`, root, issues));
+        }
+        return;
+    }
+    if (schema.type === 'string') {
+        if (typeof value !== 'string') {
+            issues.push({ path, message: `must be a string; received ${valueType(value)}` });
+            return;
+        }
+        if (schema.minLength !== undefined && value.length < schema.minLength) {
+            issues.push({ path, message: `must contain at least ${schema.minLength} character(s)` });
+        }
+        return;
+    }
+    if (schema.type === 'boolean') {
+        if (typeof value !== 'boolean') {
+            issues.push({ path, message: `must be a boolean; received ${valueType(value)}` });
+        }
+        return;
+    }
+    if (schema.type === 'integer') {
+        if (!Number.isInteger(value)) {
+            issues.push({ path, message: `must be an integer; received ${valueType(value)}` });
+            return;
+        }
+        if (schema.minimum !== undefined && value < schema.minimum) {
+            issues.push({ path, message: `must be at least ${schema.minimum}` });
+        }
+    }
+}
+function defaultedConfig(input) {
+    return {
+        ...input,
+        $schema: input.$schema === undefined ? ARK_CONFIG_SCHEMA_URL : input.$schema,
+        schemaVersion: input.schemaVersion === undefined ? ARK_CONFIG_SCHEMA_VERSION : input.schemaVersion,
+        include: input.include === undefined ? ['src'] : input.include,
+        layers: input.layers === undefined ? [] : input.layers,
+        rules: input.rules === undefined
+            ? DEFAULT_ARK_CONFIG_RULES.map((rule) => ({ ...rule }))
+            : input.rules,
+    };
+}
+export function migrateArkConfig(input, source = 'ark.config.json') {
+    if (!isObject(input)) {
+        throw new ArkConfigValidationError(source, [
+            { path: '$', message: `must be an object; received ${valueType(input)}` },
+        ]);
+    }
+    const migratedFrom = input.schemaVersion === undefined ? 'unversioned' : null;
+    if (input.schemaVersion !== undefined &&
+        input.schemaVersion !== ARK_CONFIG_SCHEMA_VERSION) {
+        throw new ArkConfigValidationError(source, [
+            {
+                path: '$.schemaVersion',
+                message: `unsupported version ${JSON.stringify(input.schemaVersion)}; expected ${ARK_CONFIG_SCHEMA_VERSION}`,
+            },
+        ]);
+    }
+    return { candidate: defaultedConfig(input), migratedFrom };
+}
+export function loadArkConfigContract(input, source = 'ark.config.json') {
+    const { candidate, migratedFrom } = migrateArkConfig(input, source);
+    const issues = [];
+    validateNode(candidate, ARK_CONFIG_SCHEMA, '$', ARK_CONFIG_SCHEMA, issues);
+    if (issues.length > 0)
+        throw new ArkConfigValidationError(source, issues);
+    return { config: candidate, migratedFrom };
+}
+export function parseArkConfigJson(json, source = 'ark.config.json') {
+    let input;
+    try {
+        input = JSON.parse(json);
+    }
+    catch (error) {
+        throw new ArkConfigValidationError(source, [
+            {
+                path: '$',
+                message: `invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+            },
+        ]);
+    }
+    return loadArkConfigContract(input, source);
+}
+export function withArkConfigMetadata(config) {
+    const result = {
+        $schema: typeof config.$schema === 'string' && config.$schema.length > 0
+            ? config.$schema
+            : ARK_CONFIG_SCHEMA_URL,
+        schemaVersion: ARK_CONFIG_SCHEMA_VERSION,
+    };
+    for (const [key, value] of Object.entries(config)) {
+        if (key !== '$schema' && key !== 'schemaVersion')
+            result[key] = value;
+    }
+    return result;
+}

package/bin/lib/deploy-path.mjs

@@ -0,0 +1,205 @@
+/**
+ * Production deploy-path quality signals (install modularization).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readPackageJson, packageScriptsHaveTypecheck } from './gate-files.mjs';
+
+/**
+ * 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;
+}
+

package/bin/lib/doctor-plan.mjs

@@ -327,8 +327,14 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             gatesMissing,
             skillGaps,
             staleRunnerFiles: staleRunners,
-            // W5 — prepare-write / autoPatch / reject-only awareness (stable additive)
+            // Active-host guarantees plus separate repo-wide inventory.
             writePath: {
+              activeHost: writePath.activeHost,
+              support: writePath.support,
+              supportSummary: writePath.supportSummary,
+              capabilities: writePath.capabilities,
+              capabilityEvidence: writePath.capabilityEvidence,
+              inventory: writePath.inventory,
               mode: writePath.mode,
               prepareWrite: writePath.prepareWrite,
               autoPatch: writePath.autoPatch,
@@ -404,7 +410,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     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.',
+      'Guard — contract coverage is honest and checked edges are clean. You do not pick this mode; you arrived here. Next: keep the host-appropriate write path and CI check on; only NEW violations should fail.',
   };
   line(modeMark, `${mode.toUpperCase()} — ${modeHelp[mode]}`);
   if (emptyScope) {
@@ -496,26 +502,37 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
 
   console.log('');
   console.log(color.bold('Write path (agent)'));
+  const capabilities = writePath.capabilities;
   const writePathLabels = {
     repair: 'repair-capable — hard block + machine-readable autoPatch / ARK_REPAIR_JSON',
     'reject-only': 'reject-only — hard block with prose; no repair payload',
     'mcp-only': 'MCP tools only — prepare-write/autoPatch available; no PreToolUse hook',
-    none: 'none — no write gate hook and no Ark MCP',
+    none: 'no write gate hook and no Ark MCP',
   };
   const wpMark =
-    writePath.mode === 'repair'
+    capabilities['hard-write']
       ? ok
-      : writePath.mode === 'none'
-        ? bad
-        : warn;
+      : capabilities['advisory-write'] || capabilities['merge-gate']
+        ? warn
+        : bad;
+  line(' ', `Active host: ${writePath.activeHost}`);
+  line(' ', `Supported profile: ${writePath.supportSummary}`);
   line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
   line(
-    writePath.prepareWrite ? ok : warn,
-    `prepare-write (MCP): ${writePath.prepareWrite ? 'yes' : 'no'}`
+    capabilities['hard-write'] ? ok : warn,
+    `Hard write boundary: ${capabilities['hard-write'] ? 'yes' : 'no'}`
+  );
+  line(
+    warn,
+    `Advisory write tools (MCP): ${capabilities['advisory-write'] ? 'yes' : 'no'}`
   );
   line(
-    writePath.autoPatch ? ok : warn,
-    `autoPatch surface: ${writePath.autoPatch ? 'yes' : 'no'}`
+    capabilities['merge-gate'] ? ok : bad,
+    `CI check (--strict-merge): ${capabilities['merge-gate'] ? 'yes' : 'no'} (merge blocking requires a required status)`
+  );
+  line(
+    capabilities['repair-payload'] ? ok : warn,
+    `Repair payload at hard boundary: ${capabilities['repair-payload'] ? 'yes' : 'no'}`
   );
   if (writePath.gap) {
     line(writePath.gap.severity === 'warn' ? warn : warn, writePath.gap.message);
@@ -527,7 +544,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
 
   console.log('');
   console.log(color.bold('Gates & skills'));
-  if (gatesMissing.length === 0) line(ok, 'Gate files present (AGENTS.md, .mcp.json, CI, write gate)');
+  if (gatesMissing.length === 0) line(ok, 'Shared gate files present (AGENTS.md, .mcp.json, CI)');
   else {
     line(bad, `Missing gates: ${gatesMissing.join(', ')}`);
     actions.push(`install gates (${arkCommand(root, 'ark-check', '--install-agent-gates')})`);
@@ -570,10 +587,20 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     );
   } else {
     for (const gap of adoption.gaps) {
-      const mark = gap.severity === 'warn' ? warn : gap.severity === 'info' ? warn : bad;
+      // Deferred Codex-home debt (non-temp) is annotated, not a top action, when the
+      // session host is not Codex — fix when that host is used.
+      const mark = gap.deferred
+        ? color.dim('·')
+        : gap.severity === 'warn'
+          ? warn
+          : gap.severity === 'info'
+            ? warn
+            : bad;
       line(mark, gap.message);
-      if (gap.fix) line(' ', color.dim(`Fix: ${gap.fix}`));
-      actions.push(gap.fix || gap.message);
+      if (gap.fix) {
+        line(' ', color.dim(gap.deferred ? `When using Codex: ${gap.fix}` : `Fix: ${gap.fix}`));
+      }
+      if (!gap.deferred) actions.push(gap.fix || gap.message);
     }
     if (adoption.layerBalance) {
       line(warn, color.dim(adoption.layerBalance.educational));
@@ -601,7 +628,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     line(warn, 'Safety diagnostics unavailable');
   } else {
     const rows = [
-      ['Non-literal dynamic imports', safety.nonLiteralDynamicImports],
+      ['Non-literal dynamic dependencies', safety.nonLiteralDynamicImports],
       ['@ts-ignore / @ts-nocheck', safety.tsSuppressions],
       ['Explicit any casts', safety.anyCasts],
       ['InMemory stores in production source', safety.inMemoryProductionStores],