arkgate 3.0.4 → 3.0.5

package/CHANGELOG.md

@@ -4,7 +4,42 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
-No changes are scheduled after 3.0.4.
+No changes are scheduled after 3.0.5.
+
+## 3.0.5 — 2026-07-14
+
+Codex host skill catalog + residual honesty. **No breaking** CLI or `ark.config.json`
+changes. **No gate weaken.**
+
+### Fixed
+
+- **Codex `/ark-*` skills not invocable:** install wrote flat `.codex/prompts/*.md`, which
+  Codex does not load as skills. Repo catalog is now `.agents/skills/<name>/SKILL.md`
+  (Agent Skills REPO scope); optional home catalog is `$CODEX_HOME/skills/<name>/SKILL.md`
+  via `--codex-home`. Post-install verifies AGENTS.md `/ark-*` refs against each selected
+  host catalog.
+- **Temp-root MCP footgun:** `--codex-home` no longer rebinds primary `[mcp_servers.ark]` in
+  the default `~/.codex/config.toml` when the project root is a temp/upgrade path (skills may
+  still refresh under an isolated or real home).
+- **Multi-host skill hints:** Codex legacy-prompts-only debt no longer suppresses missing/stale
+  skill reports for Claude/Cursor/other hosts in doctor and `ark-check` human output.
+- **Deferred Codex home debt severity:** outside a Codex session, home skill gaps are dim/info
+  (not warn) and are not Top actions; when the session host is Codex they stay warn + fix.
+
+### Added
+
+- **Skill parity sensors:** missing / stale / legacy-prompts-only for repo and home catalogs,
+  with package `arkVersion` stamps; doctor and JSON expose concrete refresh fixes
+  (`--skills-only --tools codex` and/or `--codex-home`).
+- **CI fail-closed detection:** workflows with ark-check but only `--strict-config` (or no
+  strict flags) surface `enforcement-ci-not-fail-closed` (warn) with a `--strict-merge` fix.
+  `--strict` / `--strict-merge` / `--require-gates` count as fail-closed. Merge-gate inventory
+  evidence requires that fail-closed profile.
+- **Codex write-path honesty:** install and doctor state local Codex write is advisory (MCP +
+  best-effort hooks; not Claude/Grok hard-write + repair); CI `--strict-merge` + required
+  status is the hard merge backstop.
+
+Release note: `docs/releases/3.0.5.md`.
 
 ## 3.0.4 — 2026-07-14
 

package/bin/ark-check.mjs

@@ -33,7 +33,9 @@ import {
   loadTypeScript,
   detectSkillGaps,
   detectCodexHomeGap,
-  detectActiveAgentHost,
+  detectCodexRepoSkillGap,
+  codexConcernIsActive,
+  printSkillAndCodexGapHints,
   missingGates,
   staleRunnerGateFiles,
   brokenMcpGateFiles,
@@ -44,7 +46,6 @@ import {
   arkPackageVersion,
   compactRouterHost,
   REQUIRED_GATE_FILES,
-  codexPromptsDir,
   detectWritePathCapabilities,
 } from './lib/agent-gates.mjs';
 import { syncBaselineIntoCheckSurfaces } from './lib/field-install.mjs';
@@ -301,8 +302,8 @@ function usage() {
     '(instruction-tier rule files derived from the same contract).',
     'It also installs the /ark-* skills shipped in templates/skills/ into each',
     'detected tool\'s command location (.claude/skills/, .cursor/commands/,',
-    '.codex/prompts/, .grok/skills/, .windsurf/workflows/, .clinerules/workflows/,',
-    '.github/prompts/).',
+    '.agents/skills/ (Codex REPO catalog), .grok/skills/, .windsurf/workflows/,',
+    '.clinerules/workflows/, .github/prompts/).',
     'Kiro, Roo, Continue, and Gemini have no command mechanism and receive only their',
     'rule file. Existing files are never overwritten without --force, so re-running',
     'after an update only adds what is missing. --skills-only restricts the write to',
@@ -1229,6 +1230,8 @@ async function main() {
 
   const skillGaps = detectSkillGaps(root);
   const codexHomeGap = detectCodexHomeGap(root);
+  const codexRepoSkillGap = detectCodexRepoSkillGap(root);
+  const codexSessionActive = codexConcernIsActive();
 
   if (args.report) {
     const exampleByLayer = new Map();
@@ -1372,7 +1375,15 @@ async function main() {
       warnings,
       ...(activeViolations.length > 0 ? { summary: summarizeViolations(activeViolations) } : {}),
       ...(skillGaps.length > 0 ? { skillGaps } : {}),
-      ...(codexHomeGap ? { codexHomeGap } : {}),
+      ...(codexHomeGap
+        ? {
+            codexHomeGap: {
+              ...codexHomeGap,
+              deferred: !codexSessionActive,
+            },
+          }
+        : {}),
+      ...(codexRepoSkillGap ? { codexRepoSkillGap } : {}),
     }, null, 2));
   } else {
     for (const warning of warnings) {
@@ -1420,30 +1431,13 @@ async function main() {
       printViolationBreakdown(summarizeViolations(activeViolations), { toStderr: true });
     }
 
-    if (skillGaps.length > 0) {
-      const missingTotal = skillGaps.reduce((sum, gap) => sum + gap.missing, 0);
-      const staleTotal = skillGaps.reduce((sum, gap) => sum + gap.stale, 0);
-      const tools = skillGaps.map((gap) => gap.tool).join(', ');
-      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) {
-        // Stale skills already exist, so refreshing needs --force. --skills-only
-        // scopes the overwrite to the canonical skills, leaving a customized
-        // AGENTS.md / settings / CI untouched (a bare --force would clobber them).
-        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')}`
-          )
-        );
-      }
-    }
+    printSkillAndCodexGapHints(root, {
+      skillGaps,
+      codexHomeGap,
+      codexRepoSkillGap,
+      codexSessionActive,
+      color,
+    });
 
     const staleRunners = staleRunnerGateFiles(root);
     if (staleRunners.length > 0) {
@@ -1464,27 +1458,6 @@ async function main() {
         )
       );
     }
-
-    if (codexHomeGap) {
-      const parts = [];
-      if (codexHomeGap.missing > 0) parts.push(`${codexHomeGap.missing} missing`);
-      if (codexHomeGap.stale > 0) parts.push(`${codexHomeGap.stale} outdated`);
-      // Advisory always; when session host is known and not Codex, say so so
-      // /ark-upgrade does not chase home prompts as Incomplete.
-      const activeHost = detectActiveAgentHost();
-      const deferredNote =
-        activeHost != null && activeHost !== 'codex'
-          ? ' Deferred unless you use Codex — not a blocker for Grok/Claude/Cursor. '
-          : ' ';
-      console.log(
-        color.dim(
-          `/ark-* skills in ${codexPromptsDir()} are behind this Ark (${parts.join(', ')}).` +
-            deferredNote +
-            `Codex loads them from $CODEX_HOME/prompts, not the repo. ` +
-            `When using Codex: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --codex-home --force')}`
-        )
-      );
-    }
   }
 
   if (args.watch) {

package/bin/ark.mjs

@@ -213,9 +213,9 @@ async function upgrade(args) {
   let status = runArkCheck(['--root', root, '--install-agent-gates'], { cwd: root });
   if (status !== 0) return status;
 
-  // Codex loads slash-command prompts from $CODEX_HOME/prompts, not the repo — refresh those
-  // when a Codex home exists. --force rewrites temp/upgrade MCP roots to this project + arkgate-mcp.
-  // Non-fatal: a permission error (e.g. sandbox) shouldn't fail the whole upgrade.
+  // Codex home skill catalog is $CODEX_HOME/skills/<name>/SKILL.md (repo uses .agents/skills/).
+  // Refresh home when a Codex home exists. --force rewrites temp/upgrade MCP roots to this
+  // project + arkgate-mcp. Non-fatal: a permission error (e.g. sandbox) shouldn't fail upgrade.
   const codexHomeBase = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
   if (fs.existsSync(codexHomeBase)) {
     console.log(`\n     Refreshing Codex home (${codexHomeBase})…`);

package/bin/lib/agent-gates.mjs

@@ -10,6 +10,7 @@ export {
   codexPrimaryTable,
   codexProjectSlug,
   codexPromptsDir,
+  codexSkillsDir,
   codexScopedTableForRoot,
   extractCodexArkRootFromToml,
   extractCodexRootFromBlock,
@@ -77,6 +78,7 @@ export {
   normalizeToolsList,
   resolveTools,
   KNOWN_TOOLS,
+  SKILL_TOOL_TARGETS,
   detectActiveAgentHost,
   codexConcernIsActive,
   arkPackageVersion,
@@ -86,7 +88,13 @@ export {
   skillTemplates,
   skillTemplateNames,
   detectCodexHomeGap,
+  detectCodexRepoSkillGap,
+  assessCodexSkillParity,
+  assessSkillCatalogParity,
   detectSkillGaps,
+  agentsMdSkillRefs,
+  verifyHostSkillCatalog,
+  printSkillAndCodexGapHints,
 } from './skill-install.mjs';
 
 export { detectDeployPathQuality } from './deploy-path.mjs';
@@ -101,6 +109,7 @@ export {
 export {
   detectPreCommitArk,
   detectCiEnforcement,
+  classifyArkCheckFlags,
   detectConfigGateDrift,
   jobIdsThatRunArkCheck,
   isArkRequiredStatusCheck,

package/bin/lib/codex-home.mjs

@@ -10,12 +10,21 @@ import { execCommandParts } from '../ark-shared.mjs';
 
 export const PREFERRED_CODEX_MCP_BIN = 'arkgate-mcp';
 
-/** Where Codex loads slash-command prompts ($CODEX_HOME/prompts). */
+/** Where Codex loads slash-command prompts ($CODEX_HOME/prompts) — legacy, not the skill catalog. */
 export function codexPromptsDir() {
   const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
   return path.join(base, 'prompts');
 }
 
+/**
+ * Where Codex loads user/home SKILL.md skills ($CODEX_HOME/skills/<name>/SKILL.md).
+ * Repo-scoped skills live at `.agents/skills/<name>/SKILL.md` (Agent Skills standard).
+ */
+export function codexSkillsDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
 /** Where Codex loads MCP servers ($CODEX_HOME/config.toml) — global, not project-local. */
 export function codexConfigPath() {
   const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');

package/bin/lib/doctor-plan.mjs

@@ -14,6 +14,8 @@ import {
 import {
   collectAdoptionGaps,
   detectSkillGaps,
+  detectCodexHomeGap,
+  codexConcernIsActive,
   detectWritePathCapabilities,
   missingGates,
   staleRunnerGateFiles,
@@ -405,8 +407,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     ? [...baseline.keys].filter((key) => !currentKeys.has(key)).length
     : 0;
   const activeCount = violations.length - suppressed;
-  const missingSkills = skillGaps.reduce((sum, gap) => sum + gap.missing, 0);
-  const staleSkills = skillGaps.reduce((sum, gap) => sum + gap.stale, 0);
   const designSmells = detectDesignSmells(root, config, files, cov);
   const designFitness = summarizeDesignFitness(designSmells, {
     activeViolations: activeCount,
@@ -769,11 +769,36 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     line(bad, `Missing gates: ${gatesMissing.join(', ')}`);
     actions.push(`install gates (${arkCommand(root, 'ark-check', '--install-agent-gates')})`);
   }
-  if (missingSkills + staleSkills === 0) line(ok, '/ark-* skills current for detected tools');
-  else {
-    line(warn, `${missingSkills} missing / ${staleSkills} outdated /ark-* skill(s) for ${skillGaps.map((g) => g.tool).join(', ')}`);
+  // Report Codex legacy prompts and other-host missing/stale independently (never exclusive).
+  const legacyCodex = skillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
+  const remainingGaps = skillGaps.filter((g) => !(g.tool === 'codex' && g.legacyPromptsOnly));
+  const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
+  const remStale = remainingGaps.reduce((s, g) => s + g.stale, 0);
+  if (remMiss + remStale === 0 && !legacyCodex) line(ok, '/ark-* skills current for detected tools');
+  if (legacyCodex) {
+    line(warn, 'Codex: legacy flat .codex/prompts only (not a loadable skill catalog)');
+    actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
+  }
+  if (remMiss + remStale > 0) {
+    line(warn, `${remMiss} missing / ${remStale} outdated /ark-* skill(s) for ${remainingGaps.map((g) => g.tool).join(', ')}`);
     actions.push('refresh /ark-* skills (--install-agent-gates --skills-only --force)');
   }
+  const codexHomeGap = detectCodexHomeGap(root);
+  if (codexHomeGap) {
+    const parts = [
+      codexHomeGap.legacyPromptsOnly ? 'legacy-prompts-only' : null,
+      codexHomeGap.missing > 0 ? `${codexHomeGap.missing} missing` : null,
+      codexHomeGap.stale > 0 ? `${codexHomeGap.stale} outdated` : null,
+    ].filter(Boolean);
+    const deferred = !codexConcernIsActive();
+    // Deferred home debt is dim/info (not warn) so non-Codex sessions are not "incomplete".
+    if (deferred) {
+      line(color.dim('·'), color.dim(`Codex home skills ${parts.join(', ')} (deferred — not on Codex session)`));
+    } else {
+      line(warn, `Codex home skills ${parts.join(', ')}`);
+      actions.push('refresh Codex home skills (--install-agent-gates --skills-only --codex-home --force)');
+    }
+  }
 
   console.log('');
   console.log(color.bold('Baseline'));

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;

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/weakest-link.mjs

@@ -48,6 +48,30 @@ export function detectPreCommitArk(root) {
   return { present, arkAware, path: hit };
 }
 
+/**
+ * Classify ark-check flags in a workflow or package script body.
+ * CLI: `--strict` and `--strict-merge` both set strictConfig + requireGates (fail-closed).
+ * `--strict-config` alone does not require gate files.
+ *
+ * @param {string} text
+ * @returns {{ hasFailClosedFlag: boolean, hasStrictConfigOnly: boolean, hasStrictFlag: boolean }}
+ */
+export function classifyArkCheckFlags(text) {
+  if (!text || typeof text !== 'string') {
+    return { hasFailClosedFlag: false, hasStrictConfigOnly: false, hasStrictFlag: false };
+  }
+  const hasStrictMerge = /--strict-merge\b/.test(text);
+  const hasRequireGates = /--require-gates\b/.test(text);
+  // Bare --strict (alias of --strict-merge), not --strict-config / already-matched merge.
+  const withoutLong = text.replace(/--strict-merge\b/g, ' ').replace(/--strict-config\b/g, ' ');
+  const hasBareStrict = /--strict\b/.test(withoutLong);
+  const hasFailClosedFlag = hasStrictMerge || hasRequireGates || hasBareStrict;
+  const hasStrictConfig = /--strict-config\b/.test(text);
+  const hasStrictConfigOnly = hasStrictConfig && !hasFailClosedFlag;
+  const hasStrictFlag = hasFailClosedFlag || hasStrictConfigOnly;
+  return { hasFailClosedFlag, hasStrictConfigOnly, hasStrictFlag };
+}
+
 /**
  * @param {string} root
  * @returns {{
@@ -56,6 +80,9 @@ export function detectPreCommitArk(root) {
  *   arkWorkflowFiles: string[],
  *   hasArkCheckWorkflow: boolean,
  *   hasStrictFlag: boolean,
+ *   hasFailClosedFlag: boolean,
+ *   hasStrictConfigOnly: boolean,
+ *   failClosed: boolean,
  *   hasArchitectureJobName: boolean,
  * }}
  */
@@ -67,6 +94,9 @@ export function detectCiEnforcement(root) {
     arkWorkflowFiles: [],
     hasArkCheckWorkflow: false,
     hasStrictFlag: false,
+    hasFailClosedFlag: false,
+    hasStrictConfigOnly: false,
+    failClosed: false,
     hasArchitectureJobName: false,
   };
   if (!out.hasWorkflowsDir) return out;
@@ -77,6 +107,19 @@ export function detectCiEnforcement(root) {
     return out;
   }
   out.workflowFiles = files;
+
+  let checkArchScript = '';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    checkArchScript =
+      typeof pkg?.scripts?.['check:architecture'] === 'string'
+        ? pkg.scripts['check:architecture']
+        : '';
+  } catch {
+    checkArchScript = '';
+  }
+  const scriptFlags = classifyArkCheckFlags(checkArchScript);
+
   for (const f of files) {
     let text = '';
     try {
@@ -92,9 +135,19 @@ export function detectCiEnforcement(root) {
     if (mentionsArk) {
       out.hasArkCheckWorkflow = true;
       out.arkWorkflowFiles.push(`.github/workflows/${f}`);
-      if (/--strict\b/.test(text) || /check:architecture/.test(text)) {
+      const flags = classifyArkCheckFlags(text);
+      const viaScript = /check:architecture/.test(text) && scriptFlags.hasFailClosedFlag;
+      if (flags.hasFailClosedFlag || viaScript) {
+        out.hasFailClosedFlag = true;
+        out.failClosed = true;
+        out.hasStrictFlag = true;
+      } else if (flags.hasStrictConfigOnly) {
+        out.hasStrictConfigOnly = true;
+        out.hasStrictFlag = true;
+      } else if (flags.hasStrictFlag) {
         out.hasStrictFlag = true;
       }
+      // check:architecture without fail-closed flags in the script is NOT fail-closed.
       if (/architecture|ark-check|arkgate-check/i.test(f) || /name:\s*.*ark/i.test(text)) {
         out.hasArchitectureJobName = true;
       }
@@ -339,18 +392,14 @@ export function collectWeakestLinkGaps(root, opts = {}) {
         'CI workflows exist but none run ark-check / arkgate-check / check:architecture',
       fix: arkCommand(root, 'ark-check', '--install-agent-gates'),
     });
-  } else if (
-    adopted &&
-    !isProducer &&
-    ci.hasArkCheckWorkflow &&
-    !ci.hasStrictFlag
-  ) {
+  } else if (adopted && !isProducer && ci.hasArkCheckWorkflow && !ci.failClosed) {
     gaps.push({
-      id: 'enforcement-ci-not-strict',
-      severity: 'info',
-      message:
-        'Architecture CI job found but does not pass --strict / check:architecture (weaker than recommended)',
-      fix: 'Add --strict (or npm run check:architecture) to the architecture workflow step',
+      id: 'enforcement-ci-not-fail-closed',
+      severity: 'warn',
+      message: ci.hasStrictConfigOnly
+        ? 'Architecture CI uses --strict-config only (config coverage without gate-file presence). Prefer the fail-closed profile.'
+        : 'Architecture CI job found but does not use the fail-closed profile (--strict-merge / --strict / --require-gates)',
+      fix: 'ark-check --root . --config ark.config.json --strict-merge --baseline .ark-baseline.json',
     });
   }
 

package/bin/lib/write-path-capabilities.mjs

@@ -121,7 +121,9 @@ function hostRecord(hard, advisory, repair, merge) {
 }
 
 export function detectWritePathInventory(root) {
-  const merge = detectCiEnforcement(root).arkWorkflowFiles;
+  // Merge-gate evidence only when CI uses the fail-closed profile (not bare ark-check).
+  const ci = detectCiEnforcement(root);
+  const merge = ci.failClosed ? ci.arkWorkflowFiles : [];
   const claudeHook = hookEvidence(root, '.claude/settings.json');
   const grokHook = hookEvidence(root, '.grok/hooks/ark-write-gate.json');
   const hosts = {

package/bin/lib/write-path-detect.mjs

@@ -72,17 +72,23 @@ export function detectWritePathCapabilities(root, explicitHost) {
       ),
     };
   } else if (mode === 'mcp-only') {
+    const codexHonesty =
+      activeHost === 'codex'
+        ? 'Codex local write is advisory (MCP + best-effort hooks.json — not a hard boundary; ' +
+          'not equivalent to Claude/Grok PreToolUse hard-write + repair). ' +
+          'The hard merge backstop is CI --strict-merge plus a required status check.'
+        : `Active host ${activeHost} has advisory prepare-write/autoPatch tools, ` +
+          'but no hard write boundary; the CI check can still reject the change before merge.';
     gap = {
       id: 'write-path-mcp-only',
       severity: 'info',
-      message:
-        `Active host ${activeHost} has advisory prepare-write/autoPatch tools, ` +
-        'but no hard write boundary; the CI check can still reject the change before merge.',
-      fix: arkCommand(
-        root,
-        'ark-check',
-        `--install-agent-gates --tools ${tools}`
-      ),
+      host: activeHost,
+      message: codexHonesty,
+      fix:
+        activeHost === 'codex'
+          ? 'Keep CI on --strict-merge and require the ark-check status on the default branch; ' +
+            `refresh Codex MCP/skills with ${arkCommand(root, 'ark-check', '--install-agent-gates --tools codex')}`
+          : arkCommand(root, 'ark-check', `--install-agent-gates --tools ${tools}`),
     };
   }
 

package/dist/index.cjs

@@ -50,7 +50,7 @@ __export(gate_exports, {
 module.exports = __toCommonJS(gate_exports);
 
 // src/version.ts
-var version = "3.0.4";
+var version = "3.0.5";
 
 // src/domain/adapterContract.ts
 var ARK_ANALYSIS_RESULT_SCHEMA_VERSION = "1.0";

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig, c as ArkConfig
 export { d as ARK_CONFIG_SCHEMA, e as ARK_CONFIG_SCHEMA_VERSION, l as loadArkConfigContract, p as parseArkConfigJson } from './configContract-BxSIwVRo.cjs';
 
 /** ArkGate library version — single source of truth. */
-declare const version = "3.0.4";
+declare const version = "3.0.5";
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
 declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.0";

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig, c as ArkConfig
 export { d as ARK_CONFIG_SCHEMA, e as ARK_CONFIG_SCHEMA_VERSION, l as loadArkConfigContract, p as parseArkConfigJson } from './configContract-BxSIwVRo.js';
 
 /** ArkGate library version — single source of truth. */
-declare const version = "3.0.4";
+declare const version = "3.0.5";
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
 declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.0";

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var version = "3.0.4";
+var version = "3.0.5";
 
 // src/domain/adapterContract.ts
 var ARK_ANALYSIS_RESULT_SCHEMA_VERSION = "1.0";

package/docs/agent-guide.md

@@ -307,7 +307,7 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 |------|-----------------|-------------|
 | Claude Code | `.claude/settings.json` hook + `.mcp.json` / `claude mcp add` | `.claude/skills/<name>/SKILL.md` |
 | Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | `.cursor/commands/` |
-| OpenAI Codex | `$CODEX_HOME/config.toml` (global; absolute `--root`; multi-project → secondary `ark_<slug>` unless `--force`; doctor defers non-temp home gaps when session host ≠ Codex — see [ai-gates.md](ai-gates.md)) | `$CODEX_HOME/prompts` (`--codex-home`; fix when using Codex) |
+| OpenAI Codex | `$CODEX_HOME/config.toml` (global; absolute `--root`; multi-project → secondary `ark_<slug>` unless `--force`; doctor defers non-temp home gaps when session host ≠ Codex — see [ai-gates.md](ai-gates.md)) | **Repo:** `.agents/skills/<name>/SKILL.md`; **home:** `$CODEX_HOME/skills/<name>/SKILL.md` (`--codex-home`) |
 | **Grok Build** | `.grok/hooks/ark-write-gate.json` + `.grok/config.toml` / `.mcp.json` | `.grok/skills/<name>/SKILL.md` |
 
 This is a path reference, not a guarantee table. Full copy-paste setups:

package/docs/ai-gates.md

@@ -268,7 +268,7 @@ Hand-editing with relative `--root .` is wrong: Codex does not use the project a
 
 ```bash
 npx ark-check --install-agent-gates --tools codex
-# optional: install /ark-* slash prompts into $CODEX_HOME/prompts
+# optional: install /ark-* skills into $CODEX_HOME/skills/<name>/SKILL.md
 npx ark-check --install-agent-gates --codex-home
 ```
 
@@ -309,11 +309,36 @@ primary A. It writes a **scoped secondary** table:
 
 `ark-check --doctor` surfaces the multi-project state so you are not left thinking B owns
 `ark://manifest` when only a secondary table exists. **Deferred (fix when using Codex):**
-non-temp Codex-home gaps (`codex-home-multi-project`, stale `$CODEX_HOME/prompts`) are
+non-temp Codex-home gaps (`codex-home-multi-project`, stale `$CODEX_HOME/skills`) are
 severity **info**, marked `deferred: true`, and omitted from Top actions when the session
 host is known and not Codex — `/ark-upgrade` on Grok/Claude is not Incomplete because of
 them. **Temp/upgrade primary roots** stay fail-closed urgent (rewritten, not multi-project).
 
+### Codex skill catalog (SKILL.md, not flat prompts)
+
+Codex discovers skills as directories containing `SKILL.md` (Agent Skills standard):
+
+| Scope | Path |
+|-------|------|
+| **Repo** (written by `--tools codex`) | `.agents/skills/<name>/SKILL.md` |
+| **Home** (optional `--codex-home`) | `$CODEX_HOME/skills/<name>/SKILL.md` |
+
+Flat `.codex/prompts/*.md` files are **not** the invocable skill catalog. Install writes the
+repo catalog above so AGENTS.md `/ark-*` references match what Codex can load. After install,
+Ark verifies those references against each selected host catalog.
+
+**Parity & honesty (doctor / install):**
+
+- Doctor distinguishes **missing / stale / legacy-prompts-only** for repo (`.agents/skills`) and
+  home (`$CODEX_HOME/skills`). Home debt is **deferred** when the session host is not Codex.
+- Legacy flat prompts alone are reported as non-loadable skill debt with a
+  `--skills-only --tools codex --force` (repo) or `--codex-home --force` (home) fix.
+- Codex **write path is advisory**: MCP + best-effort `.codex/hooks.json` is **not** a hard
+  write boundary and is **not** equivalent to Claude/Grok PreToolUse hard-write + repair.
+  The hard merge backstop is CI `--strict-merge` (or `--strict`) plus a required status check.
+- CI workflows that run ark-check without the fail-closed profile (or with only
+  `--strict-config`) surface gap `enforcement-ci-not-fail-closed`.
+
 ## Grok Build (xAI)
 
 Grok reads project rules from **`AGENTS.md`**, project MCP from **`.grok/config.toml`**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "3.0.4",
+  "version": "3.0.5",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "3.0.4",
+      "version": "3.0.5",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/skills/ark-upgrade.md

@@ -123,11 +123,15 @@ npx arkgate-check --install-agent-gates --skills-only --force
    **Active host first.** Refresh skills for the host running this skill (e.g.
    `.grok/skills/`, `.claude/skills/`, `.cursor/commands/`). Repo-local copies for
    other detected hosts are fine to refresh in the same pass when cheap.
-   **Codex is deferred when you are not on Codex.** Prompts live in
-   `$CODEX_HOME/prompts` (`~/.codex/prompts`), not the repo. `ark upgrade` may
-   best-effort refresh that home when it exists; still list Codex under
-   **Deferred hosts** and do **not** chase MCP multi-project / stale home skills
-   until the user is on Codex (or asks). Fix command when needed:
+   **Codex is deferred when you are not on Codex.** Repo skills live in
+   `.agents/skills/<name>/SKILL.md`; optional home skills in
+   `$CODEX_HOME/skills/<name>/SKILL.md` (not legacy flat `$CODEX_HOME/prompts`).
+   When **on Codex**, refresh **both** repo catalog and home if doctor reports
+   missing/stale/legacy-prompts-only parity gaps. `ark upgrade` may best-effort
+   refresh home when it exists; still list Codex under **Deferred hosts** when
+   not on Codex and do **not** chase MCP multi-project / stale home skills until
+   the user is on Codex (or asks). Fix when needed:
+   `ark-check --install-agent-gates --skills-only --tools codex --force` and/or
    `ark-check --install-agent-gates --skills-only --codex-home --force`
    (and `--tools codex` / `--force` for primary MCP rebind). Exception: temp or
    `ark-upgrade` MCP `--root` paths — leave fail-closed rewrite to the CLI; do not