arkgate 3.0.3 → 3.0.5

package/bin/lib/html-report.mjs

@@ -11,6 +11,13 @@ import {
   resolveOperatingMode,
 } from '../ark-shared.mjs';
 import { collectAdoptionGaps, arkCheckCommand } from './agent-gates.mjs';
+import { CORE_LAYER_NAMES } from './core-layers.mjs';
+import {
+  renderBaselineSignalLegend,
+  renderDesignCleanNote,
+  renderDesignDepthStrip,
+  renderWritePathAdoptionBlock,
+} from './html-report-depth.mjs';
 import { FIX_HINTS } from './violations.mjs';
 
 export function detectEnforcement(root) {
@@ -58,6 +65,53 @@ export function htmlEscape(value) {
     .replace(/"/g, '"');
 }
 
+/**
+ * KPI tile with plain-language hint (visible micro-copy + native tooltip).
+ * Helps newcomers read the showcase without memorizing Ark jargon.
+ *
+ * @param {string|number} value
+ * @param {string} label short metric name
+ * @param {string} hint one-sentence meaning
+ */
+export function metricKpi(value, label, hint) {
+  const v = htmlEscape(String(value));
+  const l = htmlEscape(label);
+  const h = htmlEscape(hint);
+  return `<div class="kpi" title="${h}" aria-label="${l}: ${v}. ${h}">
+        <b>${v}</b>
+        <span>${l}</span>
+        <em class="kpi-hint">${h}</em>
+      </div>`;
+}
+
+/** Baseline policy signal → human meaning (adoption card). */
+export function baselineSignalHint(signal) {
+  switch (String(signal || '')) {
+    case 'keep-empty':
+      return 'Baseline file exists and freezes 0 keys — every violation is active (honest green).';
+    case 'active-ratchet':
+      return 'Baseline freezes known debt keys; new distinct violations still fail the check.';
+    case 'absent':
+      return 'No .ark-baseline.json — all findings are active (or you have not adopted a freeze file).';
+    default:
+      return 'How frozen debt is handled relative to active architecture violations.';
+  }
+}
+
+/** Operating mode badge tooltip. */
+export function modeBadgeHint(mode) {
+  switch (String(mode || '').toLowerCase()) {
+    case 'enforce':
+      return 'Contract matches the tree: cores are required where populated, coverage is honest, gates can hold the line.';
+    case 'adapt':
+      return 'Contract is live but still aligning (optional cores with files, empty cores, or presentation-bag false green).';
+    case 'suggest':
+      return 'Starter shape — expand layers and raise governed coverage as the codebase grows.';
+    default:
+      return 'Operating mode for co-pilot surfaces (suggest · adapt · enforce).';
+  }
+}
+
 /** Directory for origin / latest / history architecture report snapshots. */
 const ARK_REPORTS_DIR = path.join('.ark', 'reports');
 const ARK_REPORT_HISTORY_MAX = 20;
@@ -159,7 +213,10 @@ export function computeReportFitness({ coverage, violations, ok, enforcement, co
   const presentationRow = (coverage?.layers ?? []).find(
     (r) => r.name === 'PresentationAdapters'
   );
+  // Same honesty gate as doctor (`mcp-adoption` coreOptional): only the four cores
+  // matter. Secondary optional layers with files must not force ADAPT on the HTML report.
   const coreOptionalWithFiles = (config?.layers ?? []).filter((layer) => {
+    if (!CORE_LAYER_NAMES.has(layer.name)) return false;
     if (layer.optional !== true) return false;
     const row = (coverage?.layers ?? []).find((r) => r.name === layer.name);
     return (row?.files ?? 0) > 0;
@@ -396,6 +453,8 @@ export function renderHtmlReport({
   currentSnapshot = null,
   originJustCreated = false,
   adoption = null,
+  /** Optional design-depth (doctor parity): designFitness, designSmells, pilotLoop, postGreenPath, goldenPattern */
+  designDepth = null,
 }) {
   const layers = Array.isArray(config.layers) ? config.layers : [];
   const rules = Array.isArray(config.rules) ? config.rules : [];
@@ -448,6 +507,29 @@ export function renderHtmlReport({
   } = fitness;
 
   const adoptionView = adoption || collectAdoptionGaps(root, config, coverage);
+  const depth = designDepth && typeof designDepth === 'object' ? designDepth : {};
+  const designFitness = depth.designFitness ?? null;
+  const designSmells = Array.isArray(depth.designSmells) ? depth.designSmells : [];
+  const designWeakBadge =
+    designFitness?.designWeak === true
+      ? ` <span class="badge design" title="Edges can be green while lived design residual remains (Shape). Not a FAIL.">design-weak</span>`
+      : '';
+  const designStripHtml =
+    renderDesignDepthStrip({
+      designFitness,
+      designSmells,
+      pilotLoop: depth.pilotLoop,
+      postGreenPath: depth.postGreenPath,
+      goldenPattern: depth.goldenPattern,
+      mode,
+    }) ||
+    renderDesignCleanNote({
+      designFitness,
+      ok,
+      mode,
+    });
+  const writePathHtml = renderWritePathAdoptionBlock(adoptionView.writePath);
+  const baselineLegendHtml = renderBaselineSignalLegend();
 
   // ── Senior diagnostics (coupling, purity, contract density) ──────────────
   const layerNames = ordered.map((l) => l.name);
@@ -818,9 +900,33 @@ export function renderHtmlReport({
   .score-cap { color: var(--dim); font-size: .85rem; margin: 0; }
   .kpis { display: grid; grid-template-columns: repeat(4, 1fr); gap: .65rem; margin: 1rem 0 0; }
   @media (max-width: 720px) { .kpis { grid-template-columns: repeat(2, 1fr); } }
-  .kpi { background: var(--panel2); border: 1px solid var(--line); border-radius: 12px; padding: .7rem .8rem; }
+  .kpi { background: var(--panel2); border: 1px solid var(--line); border-radius: 12px; padding: .7rem .8rem; cursor: help; }
   .kpi b { display: block; font-size: 1.25rem; letter-spacing: -0.02em; }
   .kpi span { color: var(--dim); font-size: .75rem; text-transform: uppercase; letter-spacing: .05em; }
+  .kpi-hint {
+    display: block; margin-top: .4rem; color: var(--dim); font-size: .68rem; font-style: normal;
+    font-weight: 450; line-height: 1.35; letter-spacing: 0; text-transform: none; max-width: 16rem;
+  }
+  .score-parts span { cursor: help; border-bottom: 1px dotted color-mix(in srgb, var(--dim) 55%, transparent); }
+  .badge[title] { cursor: help; }
+  .badge.design {
+    background: color-mix(in srgb, var(--gold) 18%, transparent); color: var(--gold);
+    border-color: color-mix(in srgb, var(--gold) 40%, transparent);
+  }
+  .badge.design-ok {
+    background: color-mix(in srgb, var(--green) 16%, transparent); color: var(--green);
+    border-color: color-mix(in srgb, var(--green) 35%, transparent);
+  }
+  .design-strip { border-left: 3px solid var(--gold); }
+  .design-strip.is-clean { border-left-color: var(--green); }
+  .design-strip.has-smells { border-left-color: var(--gold); }
+  .design-head { display: flex; flex-wrap: wrap; gap: .5rem; align-items: center; }
+  .pilot-card {
+    margin-top: .35rem; padding: .75rem .9rem; border-radius: 12px;
+    background: var(--panel2); border: 1px solid var(--line);
+  }
+  .write-path-block { margin-top: .15rem; }
+  .baseline-legend summary { cursor: pointer; color: var(--dim); font-size: .84rem; }
   .section { margin-top: 1.35rem; }
   .grid-2 { display: grid; grid-template-columns: 1.1fr 0.9fr; gap: 1rem; }
   @media (max-width: 900px) { .grid-2 { grid-template-columns: 1fr; } }
@@ -936,34 +1042,79 @@ export function renderHtmlReport({
   <div class="hero">
     <div class="card">
       <div class="brand"><i></i> Ark architecture report</div>
-      <h1>${esc(project)} <span class="badge ${status}">${status}</span> <span class="badge mode">${esc(modeLabel)}</span></h1>
-      <p class="lede">${esc(modeBlurb)} One machine-readable contract · write gate · CI · optional runtime.</p>
+      <h1>${esc(project)} <span class="badge ${status}" title="${status === 'PASS' ? 'Architecture check is green: 0 active violations against the contract.' : 'Architecture check failed: active violations remain (or the scan could not complete cleanly).'}">${status}</span> <span class="badge mode" title="${esc(modeBadgeHint(mode))}">${esc(modeLabel)}</span>${designWeakBadge}</h1>
+      <p class="lede">${esc(modeBlurb)}${designFitness?.designWeak ? ' Design residual remains (see strip below) — not a FAIL.' : ''} One machine-readable contract · write gate · CI · optional runtime.</p>
       <div class="kpis">
-        <div class="kpi"><b>${esc(govLabel)}</b><span>Governed</span></div>
-        <div class="kpi"><b>${layers.length}</b><span>Layers</span></div>
-        <div class="kpi"><b>${gatesOn}/${enforcement.length}</b><span>Gates live</span></div>
-        <div class="kpi"><b>${violations.length}${suppressed ? ` · ${suppressed}Δ` : ''}</b><span>Violations${suppressed ? ' · frozen' : ''}</span></div>
+        ${metricKpi(
+          govLabel,
+          'Governed',
+          'Share of scanned files assigned to a contract layer. 100% means every in-scope file has a home.'
+        )}
+        ${metricKpi(
+          layers.length,
+          'Layers',
+          'How many architecture layers the contract defines (cores + optional product layers).'
+        )}
+        ${metricKpi(
+          `${gatesOn}/${enforcement.length}`,
+          'Gates live',
+          'Write hook, CI workflow, ESLint plugin, and baseline file — how many enforcement points are actually present.'
+        )}
+        ${metricKpi(
+          `${violations.length}${suppressed ? ` · ${suppressed}Δ` : ''}`,
+          `Violations${suppressed ? ' · frozen' : ''}`,
+          suppressed
+            ? 'Active contract breaks right now; Δ = keys frozen in baseline (not failing until ratchet).'
+            : 'Active contract breaks (layer imports, purity, etc.). Zero means edges match the rules.'
+        )}
       </div>
       <p class="meta">${meta}</p>
       ${skillsNote}
     </div>
-    <div class="card score-card">
+    <div class="card score-card" title="Human fitness signal only — not a CI gate. Weighted blend of coverage, cleanliness, live gates, and rule density.">
       <div class="score-ring ${scoreTone}"><div><div class="score-n">${score}</div><div class="dim" style="font-size:.72rem;letter-spacing:.08em;text-transform:uppercase">Ark score</div></div></div>
       <p class="score-cap">${esc(scoreCaption)}</p>
-      <p class="meta" style="margin-top:.65rem">Coverage ${scoreCoverage} · Clean ${scoreClean} · Gates ${scoreGates} · Rules ${scoreRules}</p>
+      <p class="meta score-parts" style="margin-top:.65rem">
+        <span title="0.4 weight — governed file percent (or 50 if coverage unknown).">${esc(`Coverage ${scoreCoverage}`)}</span>
+        · <span title="0.3 weight — 100 with zero active violations; drops as violations pile up.">${esc(`Clean ${scoreClean}`)}</span>
+        · <span title="0.2 weight — share of enforcement points that are present on disk (hook, CI, ESLint, baseline).">${esc(`Gates ${scoreGates}`)}</span>
+        · <span title="0.1 weight — how dense the deny matrix is relative to layer pairs (stricter inward architecture scores higher).">${esc(`Rules ${scoreRules}`)}</span>
+      </p>
     </div>
   </div>
 
+  ${designStripHtml}
+
   <div class="section card" id="adoption">
     <h2>Adoption</h2>
     <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
       Co-pilot completeness — separate from the 0–100 fitness score above. Hosts, MCP health, origin snapshot, core optionality, baseline policy.
     </p>
     <div class="kpis" style="margin-bottom:.75rem">
-      <div class="kpi"><b>${adoptionView.gaps.length === 0 ? 'OK' : adoptionView.gaps.length}</b><span>${adoptionView.gaps.length === 0 ? 'No adoption gaps' : 'Adoption gap(s)'}</span></div>
-      <div class="kpi"><b>${adoptionView.originReport.present ? 'yes' : 'no'}</b><span>Origin report</span></div>
-      <div class="kpi"><b>${esc(adoptionView.baseline.signal)}</b><span>Baseline policy</span></div>
-      <div class="kpi"><b>${adoptionView.mcp.ok ? 'ok' : 'fix'}</b><span>Repo MCP argv</span></div>
+      ${metricKpi(
+        adoptionView.gaps.length === 0 ? 'OK' : adoptionView.gaps.length,
+        adoptionView.gaps.length === 0 ? 'No adoption gaps' : 'Adoption gap(s)',
+        adoptionView.gaps.length === 0
+          ? 'Hosts, MCP argv, origin snapshot, and core optionality look complete for co-pilot use.'
+          : 'Install or fix the listed gaps so agents get write gates, MCP, and honest cores.'
+      )}
+      ${metricKpi(
+        adoptionView.originReport.present ? 'yes' : 'no',
+        'Origin report',
+        'First architecture snapshot under .ark/reports/origin.* — future reports show evolution deltas against it.'
+      )}
+      ${metricKpi(
+        adoptionView.baseline.signal,
+        'Baseline policy',
+        baselineSignalHint(adoptionView.baseline.signal)
+      )}
+      ${metricKpi(
+        adoptionView.mcp.ok ? 'ok' : 'fix',
+        'Repo MCP argv',
+        adoptionView.mcp.ok
+          ? 'Repo MCP config points at a single ark/arkgate MCP bin (no dual-bin conflict).'
+          : 'Broken MCP argv: more than one of ark-mcp/arkgate-mcp — migrate with --install-agent-gates --migrate-commands.'
+      )}
     </div>
     ${
       adoptionView.gaps.length
@@ -991,6 +1142,8 @@ export function renderHtmlReport({
             .join(' · ')}</p>`
         : ''
     }
+    ${writePathHtml}
+    ${baselineLegendHtml}
   </div>
 
   <div class="section grid-2">
@@ -1138,10 +1291,26 @@ export function renderHtmlReport({
 
     <h3>Contract density</h3>
     <div class="kpis" style="margin-top:.35rem">
-      <div class="kpi"><b>${denyRatio}%</b><span>Edges denied</span></div>
-      <div class="kpi"><b>${deniedCount}</b><span>Deny rules</span></div>
-      <div class="kpi"><b>${allowedCount}</b><span>Explicit allows</span></div>
-      <div class="kpi"><b>${pairCount}</b><span>Directed pairs</span></div>
+      ${metricKpi(
+        `${denyRatio}%`,
+        'Edges denied',
+        'Denied directed layer pairs ÷ all possible pairs. Higher = stricter inward dependency rules.'
+      )}
+      ${metricKpi(
+        deniedCount,
+        'Deny rules',
+        'Explicit allowed:false rules in ark.config.json (row may not import column).'
+      )}
+      ${metricKpi(
+        allowedCount,
+        'Explicit allows',
+        'Explicit allowed:true edges. Most opens are implicit (no rule) unless you document them.'
+      )}
+      ${metricKpi(
+        pairCount,
+        'Directed pairs',
+        'layers × (layers − 1) — every ordered from→to pair the matrix can constrain.'
+      )}
     </div>
     <p class="dim" style="margin:.55rem 0 0;font-size:.84rem">
       Deny ratio = denied ÷ (layers × (layers−1)). High ratio = strict inward architecture.
@@ -1270,10 +1439,26 @@ export function renderHtmlReport({
 
     <h3>Debt &amp; violation taxonomy</h3>
     <div class="kpis" style="margin-top:.35rem">
-      <div class="kpi"><b>${violations.length}</b><span>Active</span></div>
-      <div class="kpi"><b>${valueN}</b><span>Value edges</span></div>
-      <div class="kpi"><b>${typeOnlyN}</b><span>Type-only</span></div>
-      <div class="kpi"><b>${suppressed || baselineKeys}</b><span>Baseline keys</span></div>
+      ${metricKpi(
+        violations.length,
+        'Active',
+        'Violations that fail the check right now (not frozen by baseline).'
+      )}
+      ${metricKpi(
+        valueN,
+        'Value edges',
+        'Runtime import edges that cross a deny rule (stronger debt than type-only).'
+      )}
+      ${metricKpi(
+        typeOnlyN,
+        'Type-only',
+        'Type-only imports across a deny edge — often mechanical-safe to rewrite as import type.'
+      )}
+      ${metricKpi(
+        suppressed || baselineKeys,
+        'Baseline keys',
+        'Distinct frozen debt keys in .ark-baseline.json (or suppressed count for this run).'
+      )}
     </div>
     ${
       topEdges.length
@@ -1291,6 +1476,14 @@ export function renderHtmlReport({
         Coverage=${scoreCoverage}, clean=${scoreClean}, gates=${scoreGates}, rules=${scoreRules} → <b>${score}</b>.
         This is a fitness signal for humans, not a CI gate.
       </p>
+      <ul class="senior-list" style="margin-top:.45rem">
+        <li><b>Coverage</b> — % of in-scope files that match a layer pattern.</li>
+        <li><b>Clean</b> — 100 with zero active violations; falls as breaks accumulate.</li>
+        <li><b>Gates</b> — share of write / CI / ESLint / baseline enforcement points present.</li>
+        <li><b>Rules</b> — deny-matrix density (more inward denies → higher component).</li>
+        <li><b>PASS / FAIL</b> — binary edge honesty (active violations), independent of the 0–100 score.</li>
+        <li><b>SUGGEST / ADAPT / ENFORCE</b> — whether the contract is honest enough to protect the tree (not a skill grade).</li>
+      </ul>
     </details>
   </div>
 

package/bin/lib/install-migrate.mjs

@@ -12,6 +12,7 @@ import {
 } from '../ark-shared.mjs';
 import {
   codexPromptsDir,
+  codexSkillsDir,
   codexConfigPath,
   isTempOrUpgradeRoot,
   usesDefaultCodexHome,
@@ -52,6 +53,7 @@ import {
   isVersionOlder,
   detectSkillGaps,
   arkPackageVersion,
+  verifyHostSkillCatalog,
 } from './skill-install.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
 import {
@@ -383,15 +385,15 @@ export function runInstallAgentGates(args) {
     console.log(`    ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`);
   }
 
-  // --codex-home writes the canonical skills straight to $CODEX_HOME/prompts.
-  // Codex reads prompts from there (not the repo), so this is the only way to
-  // refresh them for a repo that isn't itself configured for Codex. It writes to
-  // the user's home dir, hence explicit opt-in rather than part of a normal run.
+  // --codex-home writes SKILL.md skills to $CODEX_HOME/skills/<name>/SKILL.md.
+  // Codex's real catalog loads skill directories (not flat $CODEX_HOME/prompts).
+  // Repo installs already write `.agents/skills/<name>/SKILL.md` when `codex` is
+  // selected; home install is for multi-project / non-repo-local refresh.
   const homeResults = [];
   if (args.codexHome) {
-    const dir = codexPromptsDir();
+    const dir = codexSkillsDir();
     console.log('');
-    console.log(`Codex home skills (${dir}):`);
+    console.log(`Codex home skills (${dir}/<name>/SKILL.md):`);
     try {
       fs.mkdirSync(dir, { recursive: true });
     } catch (error) {
@@ -400,23 +402,25 @@ export function runInstallAgentGates(args) {
     }
     if (homeResults.length === 0) {
       for (const [name, content] of skills) {
-        const file = path.join(dir, `${name}.md`);
+        const skillDir = path.join(dir, name);
+        const file = path.join(skillDir, 'SKILL.md');
         if (fs.existsSync(file) && !args.force) {
           const installed = installedSkillVersion(file);
           const behind = installed === null || (version && isVersionOlder(installed, version));
           const note = behind
             ? `  (stale: ${installed ?? 'no stamp'} < ${version}; use --force)`
             : '  (up to date)';
-          console.log(`  ${'skipped'.padEnd(7)} ${name}.md${note}`);
+          console.log(`  ${'skipped'.padEnd(7)} ${name}/SKILL.md${note}`);
           homeResults.push({ status: 'skipped' });
           continue;
         }
         try {
+          fs.mkdirSync(skillDir, { recursive: true });
           fs.writeFileSync(file, content);
-          console.log(`  ${'wrote'.padEnd(7)} ${name}.md`);
+          console.log(`  ${'wrote'.padEnd(7)} ${name}/SKILL.md`);
           homeResults.push({ status: 'written' });
         } catch (error) {
-          console.log(`  ${'FAILED'.padEnd(7)} ${name}.md (${error.message})`);
+          console.log(`  ${'FAILED'.padEnd(7)} ${name}/SKILL.md (${error.message})`);
           homeResults.push({ status: 'failed' });
         }
       }
@@ -429,18 +433,15 @@ export function runInstallAgentGates(args) {
   // home-dir merge instead. Fires whenever Codex is in play so `ark://manifest` is live
   // without a manual copy step.
   //
-  // Skip home-dir mutation when the project root is a temp/upgrade scratch *and*
-  // 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.
+  // Skip home MCP mutation when the project root is a temp/upgrade scratch *and*
+  // CODEX_HOME is the default (~/.codex). Fixtures and agent smokes must not rewrite
+  // the developer's real config.toml with a temp --root. --codex-home still refreshes
+  // home *skills* below; MCP binding of a temp root into default home is never safe.
+  // A redirected CODEX_HOME (tests/isolation) may still wire as requested.
   let codexMcp = null;
   const wantCodexWire = !args.compact && (tools.has('codex') || args.codexHome);
   const skipHomeWire =
-    wantCodexWire &&
-    isTempOrUpgradeRoot(root) &&
-    !args.codexHome &&
-    usesDefaultCodexHome();
+    wantCodexWire && isTempOrUpgradeRoot(root) && usesDefaultCodexHome();
   if (wantCodexWire && !skipHomeWire) {
     codexMcp = wireCodexMcp(root, args.force);
     console.log('');
@@ -498,13 +499,68 @@ export function runInstallAgentGates(args) {
     if (codexMcp && codexMcp.status !== 'failed') {
       console.log(`  Codex: ark MCP registered in ${codexMcp.file} — restart Codex so \`ark://manifest\` loads.`);
     }
+    if (tools.has('codex') && !args.compact) {
+      console.log('  Codex write path (honest):');
+      console.log('    - Local: advisory MCP + best-effort .codex/hooks.json (not a hard boundary).');
+      console.log('    - Hard merge backstop: CI --strict-merge + required status check.');
+      console.log('    - Not equivalent to Claude/Grok PreToolUse hard-write + repair.');
+    }
     if (args.codexHome) {
-      console.log(`  Codex: refreshed the /ark-* skills in ${codexPromptsDir()} — Codex loads them from there.`);
-    } else if (skills.length > 0) {
-      console.log('  Codex loads slash-command prompts from $CODEX_HOME/prompts (~/.codex/prompts),');
-      console.log('  not the repo. Install the /ark-* skills there with:');
-      console.log(`    ${arkCommand(root, 'ark-check', '--install-agent-gates --codex-home')}`);
-      console.log('  (writes to your home dir; agents driving this setup should offer to run it).');
+      console.log(
+        `  Codex: refreshed home skills under ${codexSkillsDir()}/<name>/SKILL.md (Codex skill catalog).`
+      );
+    } else if (tools.has('codex') && skills.length > 0 && !args.compact) {
+      console.log(
+        '  Codex: project skills at `.agents/skills/<name>/SKILL.md` (Agent Skills REPO scope).'
+      );
+      console.log(
+        `  Optional multi-project home copy: ${arkCommand(root, 'ark-check', '--install-agent-gates --codex-home')}`
+      );
+      console.log(
+        `  (writes $CODEX_HOME/skills; legacy flat prompts at ${codexPromptsDir()} are not the skill catalog).`
+      );
+      // Best-effort note when dead prompts still sit under the repo.
+      try {
+        const promptDir = path.join(root, '.codex', 'prompts');
+        if (fs.existsSync(promptDir)) {
+          const legacy = fs.readdirSync(promptDir).filter((n) => /^ark-[a-z0-9-]+\.md$/.test(n));
+          if (legacy.length > 0) {
+            console.log(
+              `  Note: ignoring ${legacy.length} legacy .codex/prompts/ark-*.md file(s) — not loadable as Codex skills.`
+            );
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  // Post-install: AGENTS.md /ark-* refs must exist in each selected host catalog.
+  // Compact routers intentionally omit those refs (package/MCP is the router).
+  if (!args.compact && skills.length > 0) {
+    const catalog = verifyHostSkillCatalog(root, tools, {
+      skillNames: skills.map(([name]) => name),
+    });
+    if (!catalog.ok) {
+      console.log('');
+      console.error(
+        `Skill catalog verification failed: ${catalog.missing.length} AGENTS.md /ark-* reference(s) missing from host catalogs.`
+      );
+      for (const miss of catalog.missing.slice(0, 12)) {
+        console.error(`  missing ${miss.tool}: ${miss.path}`);
+      }
+      if (catalog.missing.length > 12) {
+        console.error(`  …and ${catalog.missing.length - 12} more`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    if (catalog.checkedTools.length > 0 && catalog.referenced.length > 0) {
+      console.log('');
+      console.log(
+        `Skill catalog verified: ${catalog.referenced.length} AGENTS.md /ark-* skill(s) present for ${catalog.checkedTools.join(', ')}.`
+      );
     }
   }
   warnLockfileConflict(root);

package/bin/lib/mcp-adoption.mjs

@@ -143,6 +143,14 @@ export function collectAdoptionGaps(root, config, coverage) {
         extras: [['.cursor/mcp.json', 'MCP config']],
         toolsFlag: 'cursor',
       },
+      {
+        host: 'codex',
+        dir: '.codex',
+        // Official Codex REPO skill catalog (Agent Skills standard) — not .codex/prompts.
+        skill: (n) => path.join(root, '.agents', 'skills', n, 'SKILL.md'),
+        extras: [['.codex/hooks.json', 'hooks']],
+        toolsFlag: 'codex',
+      },
     ];
     for (const h of hostChecks) {
       if (!fs.existsSync(path.join(root, h.dir))) continue;