arkgate 3.0.4 → 3.1.0

package/bin/lib/prepare-change.mjs

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadArchitectureChangeMap, loadContract, preflightChange } from './analysis-engine.mjs';
+import { createAdapterResult } from './adapter-contract.mjs';
+import { collectGovernedFiles, isGovernableSourceFile, normalize } from './scan-files.mjs';
+import { isScanExcludedRelative, layerForRelativePath } from '../ark-shared.mjs';
+
+function candidatePath(value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error('Every change requires a non-empty project-relative path.');
+  }
+  const portable = value.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  if (path.posix.isAbsolute(portable) || /^[A-Za-z]:\//.test(portable)) {
+    throw new Error(`Change path must be project-relative: ${value}`);
+  }
+  const normalized = path.posix.normalize(portable);
+  if (normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized.includes('\0')) {
+    throw new Error(`Change path escapes the project root: ${value}`);
+  }
+  return normalized;
+}
+
+function isIncluded(relativePath, include) {
+  return (include ?? []).some((entry) => {
+    const root = String(entry).replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '');
+    return root === '.' || relativePath === root || relativePath.startsWith(`${root}/`);
+  });
+}
+
+function assertGovernedSource(config, relativePath) {
+  if (!isGovernableSourceFile(path.basename(relativePath))) {
+    throw new Error(`Atomic preflight only accepts governed production source files: ${relativePath}`);
+  }
+  if (!isIncluded(relativePath, config.include) || isScanExcludedRelative(relativePath, config)) {
+    throw new Error(`Change path is outside the configured source scope: ${relativePath}`);
+  }
+  if (!layerForRelativePath(relativePath, config.layers)) {
+    throw new Error(`Change path is not assigned to an architecture layer: ${relativePath}`);
+  }
+}
+
+function assertInsideProject(root, relativePath) {
+  const canonicalRoot = fs.realpathSync(root);
+  let existing = path.join(root, relativePath);
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) break;
+    existing = parent;
+  }
+  const canonicalExisting = fs.realpathSync(existing);
+  const relative = path.relative(canonicalRoot, canonicalExisting);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Change path resolves outside the project root: ${relativePath}`);
+  }
+}
+
+export function normalizeChangeSet(input) {
+  if (!Array.isArray(input)) throw new Error('changes must be an array.');
+  return input.map((change, index) => {
+    if (!change || typeof change !== 'object' || Array.isArray(change)) {
+      throw new Error(`changes[${index}] must be an object.`);
+    }
+    const normalizedPath = candidatePath(change.path);
+    if (change.delete === true && change.content === undefined) {
+      return { path: normalizedPath, delete: true };
+    }
+    if (typeof change.content === 'string' && change.delete === undefined) {
+      return { path: normalizedPath, content: change.content };
+    }
+    throw new Error(
+      `changes[${index}] must contain either content (string) or delete: true, but not both.`
+    );
+  });
+}
+
+function baseFilesForChange(root, config, changes) {
+  const byPath = new Map(
+    collectGovernedFiles(root, config).map((absolute) => [
+      normalize(path.relative(root, absolute)),
+      { path: normalize(path.relative(root, absolute)), content: fs.readFileSync(absolute, 'utf8') },
+    ])
+  );
+  for (const change of changes) {
+    if (byPath.has(change.path) || !isGovernableSourceFile(path.basename(change.path))) continue;
+    const absolute = path.join(root, change.path);
+    if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) continue;
+    byPath.set(change.path, { path: change.path, content: fs.readFileSync(absolute, 'utf8') });
+  }
+  return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export function prepareChangeFromRoot({
+  root,
+  config,
+  configSource,
+  changes,
+  changeMap,
+  changeMapSource,
+  compilerOptions,
+}) {
+  const normalizedChanges = normalizeChangeSet(changes);
+  for (const change of normalizedChanges) {
+    assertInsideProject(root, change.path);
+    assertGovernedSource(config, change.path);
+  }
+  const contract = loadContract(config, configSource ?? path.join(root, 'ark.config.json'));
+  const loadedChangeMap =
+    changeMap === undefined
+      ? undefined
+      : loadArchitectureChangeMap(changeMap, contract.config, changeMapSource);
+  const result = preflightChange({
+    contract,
+    files: baseFilesForChange(root, config, normalizedChanges),
+    changes: normalizedChanges,
+    ...(loadedChangeMap ? { changeMap: loadedChangeMap } : {}),
+    ...(compilerOptions ? { compilerOptions } : {}),
+  });
+  return {
+    ...createAdapterResult({
+      valid: result.valid,
+      violations: result.violations,
+      warnings: result.warnings,
+    }),
+    ...result,
+  };
+}
+
+export function renderChangePreflight(result) {
+  const convergence = result.convergence;
+  if (result.valid) {
+    console.log(`✔ Atomic preflight passed for ${result.changes.length} change(s).`);
+    console.log(`  candidate ${result.candidateTreeHash} · policy ${result.policyHash}`);
+  } else {
+    const structuralFindings = convergence
+      ? convergence.summary.missing + convergence.summary.contradictory + convergence.summary.unplanned
+      : 0;
+    console.error(
+      `Atomic preflight rejected ${result.violations.length + structuralFindings} finding(s):`
+    );
+    for (const finding of result.diagnostics.filter(({ severity }) => severity === 'error')) {
+      console.error(
+        `  - ${finding.ruleId} ${finding.location.file}:${finding.location.line} — ${finding.message}`
+      );
+      console.error(`    Next action: ${finding.nextAction}`);
+    }
+    for (const finding of convergence?.findings ?? []) {
+      if (finding.classification !== 'satisfied') {
+        console.error(`  - ${finding.id} — ${finding.message}`);
+        console.error(`    Next action: ${finding.nextAction}`);
+      }
+    }
+    console.error('No project file was written. Fix the complete change set and preflight again.');
+  }
+  if (convergence) {
+    const { satisfied, missing, contradictory, unplanned } = convergence.summary;
+    const write = convergence.structurallyConverged ? console.log : console.error;
+    write(
+      `Structural convergence: ${convergence.structurallyConverged ? 'passed' : 'failed'} · satisfied ${satisfied} · missing ${missing} · contradictory ${contradictory} · unplanned ${unplanned}.`
+    );
+    write('Behavioral completion: not evaluated; run the feature acceptance tests separately.');
+  }
+}
+
+export function readChangeSetFile(root, requestPath) {
+  const absolute = path.isAbsolute(requestPath) ? requestPath : path.join(root, requestPath);
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(absolute, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `Cannot read atomic change set ${absolute}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  return Array.isArray(parsed) ? parsed : parsed?.changes;
+}
+
+export function readChangeMapFile(root, requestPath) {
+  const absolute = path.isAbsolute(requestPath) ? requestPath : path.join(root, requestPath);
+  try {
+    return { source: absolute, input: JSON.parse(fs.readFileSync(absolute, 'utf8')) };
+  } catch (error) {
+    throw new Error(
+      `Cannot read architecture change map ${absolute}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}

package/bin/lib/remediation.mjs

@@ -41,6 +41,29 @@ export const KNOWN_FIX_CLASSES = [
     'break-cycle',
     'review-contract',
 ];
+/** One deterministic re-entry action shared by human and machine denial surfaces. */
+export function deterministicNextAction(violation) {
+    switch (violation.ruleId) {
+        case 'LAYER_IMPORT_VIOLATION':
+            if (violation.typeOnly || violation.targetTypeOnlyExports || violation.namedBindingsTypeOnly) {
+                return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
+            }
+            if (violation.peerIsolation) {
+                return 'Extract the shared dependency to a shared layer, then preflight again.';
+            }
+            return `Define a port in ${violation.fromLayer ?? 'the source layer'}, inject the ${violation.toLayer ?? 'outer-layer'} implementation, then preflight again.`;
+        case 'FORBIDDEN_GLOBAL':
+            return `Inject ${violation.target ?? 'the capability'} through a port, then preflight again.`;
+        case 'CIRCULAR_DEPENDENCY':
+            return 'Extract the shared dependency into a third module, then preflight again.';
+        case 'RAW_EVENT_PUBLISH':
+            return 'Publish through a registered intent creator, then run Ark again.';
+        case 'PUBLISH_MISSING_SOURCE':
+            return 'Add metadata.source to the publish call, then run Ark again.';
+        default:
+            return `Resolve ${typeof violation.ruleId === 'string' && violation.ruleId.length > 0 ? violation.ruleId : 'ARK_UNKNOWN'} without weakening ark.config.json, then run Ark again.`;
+    }
+}
 /**
  * Co-pilot work classifier — the TRUST BOUNDARY for auto-apply.
  * Biased toward 'judgment': false mechanical-safe is worse than an extra human approval.
@@ -214,5 +237,6 @@ export function enrichViolationWithFixClass(violation) {
             enriched.enthusiastHint =
                 'Read the violation message and the layer rules in ark.config.json, then adjust imports or move code to the correct layer.';
     }
+    enriched.nextAction = deterministicNextAction(violation);
     return enriched;
 }

package/bin/lib/skill-install.mjs

@@ -3,7 +3,8 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { codexPromptsDir } from './codex-home.mjs';
+import { arkCommand } from '../ark-shared.mjs';
+import { codexPromptsDir, codexSkillsDir } from './codex-home.mjs';
 import { __packageRoot, isCompactRouterAgentsContent, readJson } from './gate-files.mjs';
 
 export function normalizeToolsList(tools) {
@@ -144,13 +145,19 @@ export const KNOWN_TOOLS = [
 ];
 
 // One canonical markdown per skill (templates/skills/*.md, shipped in the npm
-// package); installed into each tool's slash-command location. The YAML
-// frontmatter (name/description) is understood or harmlessly ignored by every
-// host. Kiro has no command mechanism — its steering rule file is the only gate.
+// package); installed into each tool's slash-command / skill-catalog location.
+// The YAML frontmatter (name/description) is understood or harmlessly ignored
+// by every host. Kiro has no command mechanism — its steering rule file is the
+// only gate.
+//
+// Codex: discovers Agent Skills directories with SKILL.md — repo path is the
+// official `.agents/skills/<name>/SKILL.md` (not dead `.codex/prompts/*.md`).
+// Home install uses `$CODEX_HOME/skills/<name>/SKILL.md` via --codex-home.
 export const SKILL_TOOL_TARGETS = {
   claude: (name) => `.claude/skills/${name}/SKILL.md`,
   cursor: (name) => `.cursor/commands/${name}.md`,
-  codex: (name) => `.codex/prompts/${name}.md`,
+  // Official Codex REPO skill scope (Agent Skills standard).
+  codex: (name) => `.agents/skills/${name}/SKILL.md`,
   // Grok Build: project skills at .grok/skills/<name>/SKILL.md (slash-invocable).
   grok: (name) => `.grok/skills/${name}/SKILL.md`,
   windsurf: (name) => `.windsurf/workflows/${name}.md`,
@@ -254,6 +261,122 @@ export function skillTemplateNames() {
     .map((entry) => path.basename(entry.name, '.md'));
 }
 
+/**
+ * Count present / stale / legacy-only skill files for one catalog root.
+ * @param {string[]} skillNames
+ * @param {(name: string) => string} skillFile path builder
+ * @param {string|null} packageVersion
+ * @param {{ legacyFile?: (name: string) => string }} [opts]
+ */
+export function assessSkillCatalogParity(skillNames, skillFile, packageVersion, opts = {}) {
+  const expectedCount = skillNames.length;
+  const present = [];
+  let stale = 0;
+  for (const name of skillNames) {
+    const file = skillFile(name);
+    if (!fs.existsSync(file)) continue;
+    present.push(name);
+    if (packageVersion) {
+      const installed = installedSkillVersion(file);
+      if (installed === null || isVersionOlder(installed, packageVersion)) stale += 1;
+    }
+  }
+  let legacyCount = 0;
+  if (typeof opts.legacyFile === 'function') {
+    for (const name of skillNames) {
+      if (fs.existsSync(opts.legacyFile(name))) legacyCount += 1;
+    }
+  }
+  const presentCount = present.length;
+  const missing = expectedCount - presentCount;
+  const legacyPromptsOnly = presentCount === 0 && legacyCount > 0;
+  const hasLegacyPrompts = legacyCount > 0;
+  const ok = missing === 0 && stale === 0 && !legacyPromptsOnly;
+  return {
+    ok,
+    missing,
+    stale,
+    presentCount,
+    expectedCount,
+    packageVersion: packageVersion ?? null,
+    legacyPromptsOnly,
+    hasLegacyPrompts,
+    legacyCount,
+  };
+}
+
+/**
+ * Repo + home Codex skill parity against the shipping package skill set.
+ * Producer trees (templates/skills) and projects without AGENTS.md return null.
+ *
+ * @param {string} root
+ * @returns {null | {
+ *   packageVersion: string|null,
+ *   expectedCount: number,
+ *   repo: object,
+ *   home: object,
+ *   skillsDir: string,
+ *   promptsDir: string,
+ *   needsAttention: boolean,
+ *   homeNeedsAttention: boolean,
+ *   repoNeedsAttention: boolean,
+ * }}
+ */
+export function assessCodexSkillParity(root) {
+  if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return null;
+  if (fs.existsSync(path.join(root, 'templates', 'skills'))) return null;
+  const skillNames = skillTemplateNames();
+  if (skillNames.length === 0) return null;
+
+  const packageVersion = arkPackageVersion();
+  const skillsDir = codexSkillsDir();
+  const promptsDir = codexPromptsDir();
+  const repoSkill = (name) => path.join(root, SKILL_TOOL_TARGETS.codex(name));
+  const repoLegacy = (name) => path.join(root, '.codex', 'prompts', `${name}.md`);
+  const homeSkill = (name) => path.join(skillsDir, name, 'SKILL.md');
+  const homeLegacy = (name) => path.join(promptsDir, `${name}.md`);
+
+  const repo = assessSkillCatalogParity(skillNames, repoSkill, packageVersion, {
+    legacyFile: repoLegacy,
+  });
+  const home = assessSkillCatalogParity(skillNames, homeSkill, packageVersion, {
+    legacyFile: homeLegacy,
+  });
+
+  // Repo catalog matters when .codex is present (Codex host adopted) or repo skills/prompts exist.
+  const repoInPlay =
+    fs.existsSync(path.join(root, '.codex')) ||
+    repo.presentCount > 0 ||
+    repo.hasLegacyPrompts;
+  // Home is "in play" only when ark skills or legacy prompts were actually installed there
+  // (empty $CODEX_HOME/skills is optional multi-project — not debt).
+  const homeInPlay = home.presentCount > 0 || home.hasLegacyPrompts;
+
+  if (!repoInPlay && !homeInPlay) return null;
+
+  const repoNeedsAttention =
+    repoInPlay && (repo.missing > 0 || repo.stale > 0 || repo.legacyPromptsOnly);
+  const homeNeedsAttention =
+    homeInPlay && (home.missing > 0 || home.stale > 0 || home.legacyPromptsOnly);
+
+  return {
+    packageVersion,
+    expectedCount: skillNames.length,
+    repo: { ...repo, inPlay: repoInPlay },
+    home: {
+      ...home,
+      inPlay: homeInPlay,
+      skillsDir,
+      promptsDir,
+    },
+    skillsDir,
+    promptsDir,
+    repoNeedsAttention,
+    homeNeedsAttention,
+    needsAttention: repoNeedsAttention || homeNeedsAttention,
+  };
+}
+
 // A normal ark-check run is the reliable discovery point for new /ark-* skills.
 // Ark ships no install lifecycle script (a postinstall banner would be blocked by
 // modern package managers' script-approval policy anyway, so careful users never
@@ -263,24 +386,94 @@ export function skillTemplateNames() {
 // Advisory only — never affects the exit code. Copilot has no reliable directory
 // signal, so it is not auto-detected (explicit --tools only), matching resolveTools.
 export function detectCodexHomeGap(root) {
-  if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return null;
-  if (fs.existsSync(path.join(root, 'templates', 'skills'))) return null;
-  const skillNames = skillTemplateNames();
-  if (skillNames.length === 0) return null;
-  const dir = codexPromptsDir();
-  if (!fs.existsSync(dir)) return null;
-  const present = skillNames.filter((name) => fs.existsSync(path.join(dir, `${name}.md`)));
-  if (present.length === 0) return null; // Codex home never set up for Ark — don't nag.
-  const version = arkPackageVersion();
-  const missing = skillNames.length - present.length;
-  let stale = 0;
-  if (version) {
-    for (const name of present) {
-      const installed = installedSkillVersion(path.join(dir, `${name}.md`));
-      if (installed === null || isVersionOlder(installed, version)) stale += 1;
+  const parity = assessCodexSkillParity(root);
+  if (!parity || !parity.homeNeedsAttention) return null;
+  const { home, packageVersion, expectedCount, skillsDir } = parity;
+  return {
+    missing: home.missing,
+    stale: home.stale,
+    legacyPromptsOnly: Boolean(home.legacyPromptsOnly),
+    hasLegacyPrompts: Boolean(home.hasLegacyPrompts),
+    presentCount: home.presentCount,
+    expectedCount,
+    packageVersion,
+    skillsDir,
+  };
+}
+
+/**
+ * Repo-side Codex gaps: missing/stale .agents/skills or legacy .codex/prompts only.
+ * @param {string} root
+ * @returns {null | { missing: number, stale: number, legacyPromptsOnly: boolean, hasLegacyPrompts: boolean, presentCount: number, expectedCount: number, packageVersion: string|null }}
+ */
+export function detectCodexRepoSkillGap(root) {
+  const parity = assessCodexSkillParity(root);
+  if (!parity || !parity.repoNeedsAttention) return null;
+  const { repo, packageVersion, expectedCount } = parity;
+  return {
+    missing: repo.missing,
+    stale: repo.stale,
+    legacyPromptsOnly: Boolean(repo.legacyPromptsOnly),
+    hasLegacyPrompts: Boolean(repo.hasLegacyPrompts),
+    presentCount: repo.presentCount,
+    expectedCount,
+    packageVersion,
+  };
+}
+
+/**
+ * Skill names referenced as `/ark-*` in AGENTS.md (or any instruction text).
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function agentsMdSkillRefs(text) {
+  if (!text || typeof text !== 'string') return [];
+  const refs = new Set();
+  const re = /\/(ark-[a-z0-9-]+)/g;
+  let match;
+  while ((match = re.exec(text)) !== null) refs.add(match[1]);
+  return [...refs].sort();
+}
+
+/**
+ * Verify that every `/ark-*` skill referenced by AGENTS.md (and known to this
+ * package) is present in each selected host's skill catalog path.
+ *
+ * Compact routers intentionally omit `/ark-*` — they verify as ok with no checks.
+ *
+ * @param {string} root
+ * @param {Iterable<string>} tools
+ * @param {{ skillNames?: string[], agentsText?: string }} [options]
+ * @returns {{ ok: boolean, missing: Array<{ tool: string, name: string, path: string }>, referenced: string[], checkedTools: string[], compact?: boolean }}
+ */
+export function verifyHostSkillCatalog(root, tools, options = {}) {
+  const skillNames = new Set(options.skillNames ?? skillTemplateNames());
+  let agentsText = options.agentsText;
+  if (agentsText == null) {
+    try {
+      agentsText = fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8');
+    } catch {
+      return { ok: true, missing: [], referenced: [], checkedTools: [] };
+    }
+  }
+  if (isCompactRouterAgentsContent(agentsText)) {
+    return { ok: true, missing: [], referenced: [], checkedTools: [], compact: true };
+  }
+  const referenced = agentsMdSkillRefs(agentsText).filter((name) => skillNames.has(name));
+  const missing = [];
+  const checkedTools = [];
+  for (const tool of tools) {
+    const target = SKILL_TOOL_TARGETS[tool];
+    if (!target) continue;
+    checkedTools.push(tool);
+    for (const name of referenced) {
+      const relativePath = target(name);
+      if (!fs.existsSync(path.join(root, relativePath))) {
+        missing.push({ tool, name, path: relativePath });
+      }
     }
   }
-  return missing > 0 || stale > 0 ? { missing, stale } : null;
+  return { ok: missing.length === 0, missing, referenced, checkedTools };
 }
 
 export function detectSkillGaps(root) {
@@ -325,7 +518,94 @@ export function detectSkillGaps(root) {
         if (installed === null || isVersionOlder(installed, version)) stale += 1;
       }
     }
-    if (missing > 0 || stale > 0) gaps.push({ tool, missing, stale });
+    let legacyPromptsOnly = false;
+    let hasLegacyPrompts = false;
+    if (tool === 'codex') {
+      const legacyCount = skillNames.filter((name) =>
+        fs.existsSync(path.join(root, '.codex', 'prompts', `${name}.md`))
+      ).length;
+      hasLegacyPrompts = legacyCount > 0;
+      // Flat prompts without any SKILL.md catalog entries are not loadable.
+      legacyPromptsOnly = hasLegacyPrompts && missing === skillNames.length;
+    }
+    if (missing > 0 || stale > 0 || legacyPromptsOnly) {
+      gaps.push({
+        tool,
+        missing,
+        stale,
+        ...(legacyPromptsOnly ? { legacyPromptsOnly: true } : {}),
+        ...(hasLegacyPrompts ? { hasLegacyPrompts: true } : {}),
+      });
+    }
   }
   return gaps;
 }
+
+/**
+ * Human-facing skill / Codex catalog gap lines for ark-check (non-JSON).
+ * @param {string} root
+ * @param {{ skillGaps: object[], codexHomeGap: object|null, codexRepoSkillGap: object|null, codexSessionActive: boolean, color: { dim: Function, yellow: Function } }} opts
+ */
+export function printSkillAndCodexGapHints(root, opts) {
+  const { skillGaps, codexHomeGap, codexRepoSkillGap, codexSessionActive, color } = opts;
+  if (skillGaps?.length > 0) {
+    const legacyCodex = skillGaps.some((gap) => gap.tool === 'codex' && gap.legacyPromptsOnly);
+    // Report Codex legacy separately; never suppress missing/stale for other hosts.
+    const remaining = skillGaps.filter((gap) => !(gap.tool === 'codex' && gap.legacyPromptsOnly));
+    const missingTotal = remaining.reduce((sum, gap) => sum + gap.missing, 0);
+    const staleTotal = remaining.reduce((sum, gap) => sum + gap.stale, 0);
+    const tools = remaining.map((gap) => gap.tool).join(', ');
+    if (legacyCodex) {
+      console.log(
+        color.yellow(
+          'Codex has legacy flat .codex/prompts/ark-*.md only — those are not loadable as skills. ' +
+            `Install the real catalog: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --tools codex --force')}`
+        )
+      );
+    }
+    if (missingTotal > 0) {
+      console.log(
+        color.dim(
+          `${missingTotal} /ark-* skill(s) not installed for ${tools} (this Ark version ships them). ` +
+            `Install: ${arkCommand(root, 'ark-check', '--install-agent-gates')}`
+        )
+      );
+    }
+    if (staleTotal > 0) {
+      console.log(
+        color.dim(
+          `${staleTotal} /ark-* skill(s) outdated for ${tools} (this Ark ships newer versions). ` +
+            `Refresh: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
+        )
+      );
+    }
+  }
+  if (codexHomeGap) {
+    const parts = [];
+    if (codexHomeGap.legacyPromptsOnly) parts.push('legacy-prompts-only');
+    if (codexHomeGap.missing > 0) parts.push(`${codexHomeGap.missing} missing`);
+    if (codexHomeGap.stale > 0) parts.push(`${codexHomeGap.stale} outdated`);
+    const deferred = !codexSessionActive;
+    const deferredNote = deferred
+      ? ' Deferred unless you use Codex — not a blocker for Grok/Claude/Cursor. '
+      : ' ';
+    const msg =
+      `Codex home skill catalog (${codexSkillsDir()}) behind this Ark (${parts.join(', ')}).` +
+      deferredNote +
+      `Catalog is $CODEX_HOME/skills/<name>/SKILL.md (not flat prompts). ` +
+      `When using Codex: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --codex-home --force')}`;
+    console.log(deferred ? color.dim(msg) : color.yellow(msg));
+  }
+  if (codexRepoSkillGap && codexSessionActive) {
+    const parts = [];
+    if (codexRepoSkillGap.legacyPromptsOnly) parts.push('legacy-prompts-only');
+    if (codexRepoSkillGap.missing > 0) parts.push(`${codexRepoSkillGap.missing} missing`);
+    if (codexRepoSkillGap.stale > 0) parts.push(`${codexRepoSkillGap.stale} outdated`);
+    console.log(
+      color.yellow(
+        `Codex repo skill catalog (.agents/skills) needs refresh (${parts.join(', ')}). ` +
+          `Fix: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --tools codex --force')}`
+      )
+    );
+  }
+}

package/bin/lib/violations.mjs

@@ -12,6 +12,7 @@ const color = {
 
 /** Canonical: src/domain/baselineKey.ts → bin/lib/baseline-key.mjs (R4). */
 import { baselineKey, baselineOccurrenceKeys } from './baseline-key.mjs';
+import { toAdapterDiagnostic } from './adapter-contract.mjs';
 export { baselineKey, baselineOccurrenceKeys };
 
 export function readBaseline(root, baselinePath) {
@@ -56,8 +57,7 @@ export function printViolation(violation) {
     console.error(`  ${violation.fromLayer} → ${violation.toLayer}${target}`);
   }
   console.error(`  ${violation.message}`);
-  const hint = FIX_HINTS[violation.ruleId];
-  if (hint) console.error(`  ${color.dim(`fix: ${hint}`)}`);
+  console.error(`  ${color.dim(`Next action: ${toAdapterDiagnostic(violation).nextAction}`)}`);
   console.error('');
 }