arkgate 2.12.0 → 3.0.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/config-warnings.mjs

@@ -5,12 +5,10 @@
 import path from 'node:path';
 import {
   DEFAULT_INTENT_PREFIXES,
-  globToRegExp,
-  layerForFile,
-  patternSpecificity,
   resolveIntentLayer,
 } from '../ark-shared.mjs';
 import { findDeniedEdgeRule } from '../ark-layer-match.mjs';
+import { collectAnalysisConfigWarnings } from './analysis-engine.mjs';
 import { normalize } from './scan-files.mjs';
 
 export function intentLayersFromManifest(manifest) {
@@ -54,206 +52,10 @@ export function configWarning(ruleId, message, extra = {}) {
 }
 
 export function collectConfigWarnings(root, config, files, rules, manifest) {
-  const warnings = [];
-  if (
-    config.dynamicImportAllowlist !== undefined &&
-    (!Array.isArray(config.dynamicImportAllowlist) ||
-      config.dynamicImportAllowlist.some((entry) => typeof entry !== 'string'))
-  ) {
-    warnings.push(
-      configWarning(
-        'CONFIG_INVALID_DYNAMIC_IMPORT_ALLOWLIST',
-        'dynamicImportAllowlist must be an array of file globs.'
-      )
-    );
-  }
-  if (config.safety !== undefined && (config.safety === null || typeof config.safety !== 'object' || Array.isArray(config.safety))) {
-    warnings.push(configWarning('CONFIG_INVALID_SAFETY', 'safety must be an object.'));
-  } else if (config.safety) {
-    for (const key of ['maxTsSuppressions', 'maxAnyCasts']) {
-      const value = config.safety[key];
-      if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
-        warnings.push(configWarning('CONFIG_INVALID_SAFETY_THRESHOLD', `safety.${key} must be a non-negative integer.`));
-      }
-    }
-  }
-  const layers = Array.isArray(config.layers) ? config.layers : [];
-  const manifestLayers = Array.isArray(manifest?.architecture?.layers)
-    ? manifest.architecture.layers
-    : [];
-  const knownLayers = new Set([
-    ...layers.map((layer) => layer.name).filter(Boolean),
-    ...manifestLayers.map((layer) => layer.name).filter(Boolean),
-  ]);
-
-  if (layers.length === 0) {
-    warnings.push(
-      configWarning(
-        'CONFIG_NO_LAYERS',
-        'No file layers are configured; ark-check cannot classify files for import-boundary enforcement.'
-      )
-    );
-  }
-
-  const seenLayers = new Set();
-  const duplicateLayers = new Set();
-  for (const layer of layers) {
-    if (!layer.name) {
-      warnings.push(
-        configWarning('CONFIG_LAYER_WITHOUT_NAME', 'A configured layer is missing a name.')
-      );
-      continue;
-    }
-    if (seenLayers.has(layer.name)) duplicateLayers.add(layer.name);
-    seenLayers.add(layer.name);
-
-    if (
-      layer.forbiddenGlobals !== undefined &&
-      (!Array.isArray(layer.forbiddenGlobals) ||
-        layer.forbiddenGlobals.some((entry) => typeof entry !== 'string'))
-    ) {
-      warnings.push(
-        configWarning(
-          'CONFIG_INVALID_FORBIDDEN_GLOBALS',
-          `Layer "${layer.name}" has an invalid forbiddenGlobals value; expected an array of strings (e.g. ["fetch", "Date.now"]). The entry is ignored.`,
-          { layer: layer.name }
-        )
-      );
-    }
-
-    const patterns = Array.isArray(layer.patterns) ? layer.patterns : [];
-    if (patterns.length === 0) {
-      warnings.push(
-        configWarning(
-          'CONFIG_LAYER_WITHOUT_PATTERNS',
-          `Layer "${layer.name}" has no file patterns and will never classify files.`,
-          { layer: layer.name }
-        )
-      );
-      continue;
-    }
-
-    for (const pattern of patterns) {
-      let re;
-      try {
-        re = globToRegExp(pattern);
-      } catch (err) {
-        warnings.push(
-          configWarning(
-            'CONFIG_INVALID_LAYER_PATTERN',
-            `Layer "${layer.name}" has an invalid pattern "${pattern}": ${
-              err instanceof Error ? err.message : String(err)
-            }`,
-            { layer: layer.name, pattern }
-          )
-        );
-        continue;
-      }
-
-      const matched = files.some((file) => {
-        const rel = normalize(path.relative(root, file));
-        return re.test(rel);
-      });
-      if (!matched && !layer.optional) {
-        // Advisory only under --strict-config: monorepo/Next presets ship many optional-looking
-        // globs (e.g. src/layouts/**, app/**) that never match when include is ["frontend"].
-        // Failing the release gate on dead preset globs caused false CI red while architecture
-        // edges were clean on multi-package hosts. Real safety is import violations +
-        // CONFIG_UNCLASSIFIED_FILES / invalid patterns.
-        warnings.push(
-          configWarning(
-            'CONFIG_LAYER_PATTERN_NO_MATCHES',
-            `Layer "${layer.name}" pattern "${pattern}" matched no included files.`,
-            { layer: layer.name, pattern, failsStrict: false }
-          )
-        );
-      }
-    }
-  }
-
-  for (const name of duplicateLayers) {
-    warnings.push(
-      configWarning(
-        'CONFIG_DUPLICATE_LAYER',
-        `Layer "${name}" is configured more than once.`,
-        { layer: name }
-      )
-    );
-  }
-
-  if (knownLayers.size > 0) {
-    for (const rule of rules ?? []) {
-      if (rule.from && !knownLayers.has(rule.from)) {
-        warnings.push(
-          configWarning(
-            'CONFIG_RULE_UNKNOWN_FROM_LAYER',
-            `Rule references unknown source layer "${rule.from}".`,
-            { fromLayer: rule.from, toLayer: rule.to }
-          )
-        );
-      }
-      if (rule.to && !knownLayers.has(rule.to)) {
-        warnings.push(
-          configWarning(
-            'CONFIG_RULE_UNKNOWN_TO_LAYER',
-            `Rule references unknown target layer "${rule.to}".`,
-            { fromLayer: rule.from, toLayer: rule.to }
-          )
-        );
-      }
-    }
-  }
-
-  // Ambiguous overlap: a file matched by two different layers at the SAME top specificity.
-  // layerForFile breaks the tie by declaration order, but the config is genuinely undecided
-  // (unlike a facade split, where the surface pattern is strictly more specific and wins
-  // cleanly). Surface the layer pairs so the author disambiguates instead of relying on order.
-  const ambiguousPairs = new Set();
-  if (layers.length > 1) {
-    for (const file of files) {
-      const rel = normalize(path.relative(root, file));
-      let topScore = -1;
-      let topLayers = [];
-      for (const layer of layers) {
-        for (const pattern of layer.patterns ?? []) {
-          if (!globToRegExp(pattern).test(rel)) continue;
-          const score = patternSpecificity(pattern);
-          if (score > topScore) {
-            topScore = score;
-            topLayers = [layer.name];
-          } else if (score === topScore && !topLayers.includes(layer.name)) {
-            topLayers.push(layer.name);
-          }
-        }
-      }
-      if (topLayers.length > 1) {
-        ambiguousPairs.add([...topLayers].sort().join(' + '));
-      }
-    }
-  }
-  if (ambiguousPairs.size > 0) {
-    warnings.push(
-      configWarning(
-        'CONFIG_AMBIGUOUS_LAYERS',
-        `Some files match multiple layers at equal specificity; classification falls back to declaration order. Disambiguate the overlapping patterns: ${[...ambiguousPairs].join(', ')}.`,
-        { pairs: [...ambiguousPairs] }
-      )
-    );
-  }
-
-  const unclassified = files.filter((file) => !layerForFile(root, file, layers));
-  if (unclassified.length > 0) {
-    warnings.push(
-      configWarning(
-        'CONFIG_UNCLASSIFIED_FILES',
-        `${unclassified.length} included source file(s) are not matched by any configured layer; ark-check will not enforce import rules for those source files.`,
-        {
-          count: unclassified.length,
-          samples: unclassified.slice(0, 5).map((file) => normalize(path.relative(root, file))),
-        }
-      )
-    );
-  }
-
-  return warnings;
+  return collectAnalysisConfigWarnings({
+    config,
+    rules,
+    manifest,
+    files: files.map((file) => normalize(path.relative(root, file))),
+  });
 }

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],