sinapse-ai 1.8.0 → 1.9.1

package/.sinapse-ai/infrastructure/scripts/codex-parity/resolve.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Behavioral pointer/orphan resolver for the Codex catalog (anti-fachada).
+ *
+ * The legacy integration validator only COUNTED markdown files: a green check
+ * meant "file present", never "file resolves". This module OPENS each Codex
+ * agent pointer and RESOLVES it against the real source-of-truth set:
+ *
+ *   - Core/dev agents:  `.sinapse-ai/development/agents/{id}.md`
+ *   - Squad agents:     `squads/{squad}/agents/{id}.md`
+ *
+ * It detects two failure classes the count-based check is blind to:
+ *
+ *   1. BROKEN POINTER — a `.codex/agents/*.md` whose "Read the agent definition
+ *      at: {path}" target does NOT exist on disk (the squad-claude →
+ *      claude-code-mastery rename class), OR a core agent with no pointer line
+ *      and no `{id}.md` in the dev agents dir.
+ *
+ *   2. ORPHAN — a `.codex/agents/*.md` whose stem has no corresponding source
+ *      agent anywhere (retired chiefs, brad-frost/dan-mall, etc.). An orphan is
+ *      a catalog entry that can never resolve to a real agent.
+ *
+ * It is intentionally dependency-light (fs only) so the validator never needs
+ * the heavier activator wiring to answer "is this catalog honest?".
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const POINTER_RE = /Read the agent definition at:\s*(\S+)/i;
+
+function listMarkdown(dirAbs) {
+  try {
+    return fs.readdirSync(dirAbs).filter((f) => f.endsWith('.md'));
+  } catch {
+    return [];
+  }
+}
+
+function fileExists(absPath) {
+  try {
+    return fs.statSync(absPath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build the canonical source set: every agent that actually has a definition
+ * on disk, keyed by its file stem.
+ *   stem -> { stem, sourcePath, squad|null }
+ */
+function buildSourceIndex(projectRoot, config = {}) {
+  const index = new Map();
+
+  const devAgentsRel = config.canonicalAgentsDir || '.sinapse-ai/development/agents';
+  for (const file of listMarkdown(path.join(projectRoot, devAgentsRel))) {
+    const stem = file.replace(/\.md$/, '');
+    index.set(stem, { stem, sourcePath: `${devAgentsRel}/${file}`, squad: null });
+  }
+
+  const squadsRel = config.squadsDir || 'squads';
+  const squadsAbs = path.join(projectRoot, squadsRel);
+  let squadDirs = [];
+  try {
+    squadDirs = fs
+      .readdirSync(squadsAbs)
+      .filter((d) => {
+        try {
+          return fs.statSync(path.join(squadsAbs, d)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+  } catch {
+    squadDirs = [];
+  }
+  for (const squad of squadDirs) {
+    const agentsRel = `${squadsRel}/${squad}/agents`;
+    for (const file of listMarkdown(path.join(projectRoot, agentsRel))) {
+      const stem = file.replace(/\.md$/, '');
+      // First squad wins; a later duplicate stem is still a real source.
+      if (!index.has(stem)) {
+        index.set(stem, { stem, sourcePath: `${agentsRel}/${file}`, squad });
+      }
+    }
+  }
+
+  return index;
+}
+
+/**
+ * Resolve every Codex agent pointer against the source index.
+ * Returns { brokenPointers[], orphans[], resolved[], total }.
+ */
+function resolveCatalog(projectRoot = process.cwd(), config = {}) {
+  const codexAgentsRel = config.codexAgentsDir || '.codex/agents';
+  const codexAgentsAbs = path.join(projectRoot, codexAgentsRel);
+  const devAgentsRel = config.canonicalAgentsDir || '.sinapse-ai/development/agents';
+
+  const sourceIndex = buildSourceIndex(projectRoot, config);
+
+  const brokenPointers = [];
+  const orphans = [];
+  const resolved = [];
+
+  const codexFiles = listMarkdown(codexAgentsAbs);
+
+  for (const file of codexFiles) {
+    const stem = file.replace(/\.md$/, '');
+    const pointerRel = `${codexAgentsRel}/${file}`;
+    let raw = '';
+    try {
+      raw = fs.readFileSync(path.join(codexAgentsAbs, file), 'utf8');
+    } catch {
+      raw = '';
+    }
+
+    const m = raw.match(POINTER_RE);
+    let target = m ? m[1].trim().replace(/\r$/, '') : null;
+
+    // Core/dev agents may omit the pointer line and resolve by id convention.
+    if (!target && fileExists(path.join(projectRoot, `${devAgentsRel}/${stem}.md`))) {
+      target = `${devAgentsRel}/${stem}.md`;
+    }
+
+    // ORPHAN: stem has no source agent anywhere in the ecosystem.
+    if (!sourceIndex.has(stem)) {
+      orphans.push({ id: stem, pointer: pointerRel, target });
+      continue;
+    }
+
+    // BROKEN: no pointer target at all, or the declared target file is missing.
+    if (!target) {
+      brokenPointers.push({ id: stem, pointer: pointerRel, target: null, reason: 'no pointer line' });
+      continue;
+    }
+    if (!fileExists(path.join(projectRoot, target))) {
+      brokenPointers.push({ id: stem, pointer: pointerRel, target, reason: 'target missing' });
+      continue;
+    }
+
+    resolved.push({ id: stem, pointer: pointerRel, target });
+  }
+
+  return {
+    brokenPointers,
+    orphans,
+    resolved,
+    total: codexFiles.length,
+    sourceCount: sourceIndex.size,
+  };
+}
+
+module.exports = {
+  buildSourceIndex,
+  resolveCatalog,
+  POINTER_RE,
+};

package/.sinapse-ai/infrastructure/scripts/dashboard-status-writer.js

@@ -1,8 +1,12 @@
 /**
  * Dashboard Status Writer
  *
- * Writes the current SINAPSE agent status to .sinapse/dashboard/status.json
- * This file is watched by the dashboard via SSE for real-time updates.
+ * Writes the current SINAPSE agent status to .sinapse/dashboard/status.json.
+ *
+ * Note: this file is a plain on-disk status snapshot. The CLI observability
+ * panel (`sinapse status --watch`) tails it. The old web dashboard that
+ * consumed it over SSE was the localhost:4001 monitor, which was ARCHIVED
+ * (16/06/2026, Etapa 7 / D6) — there is no SSE stream anymore, just the file.
  *
  * Usage:
  *   const statusWriter = require('./dashboard-status-writer');

package/.sinapse-ai/infrastructure/scripts/ide-sync/index.js

@@ -21,17 +21,12 @@ const fs = require('fs-extra');
 const path = require('path');
 const yaml = require('js-yaml');
 
-const { parseAllAgents } = require('./agent-parser');
+const { parseAllAgents, parseAgentFile } = require('./agent-parser');
 const { generateAllRedirects, writeRedirects } = require('./redirect-generator');
 const { validateAllIdes, formatValidationReport } = require('./validator');
-const { syncGeminiCommands, buildGeminiCommandFiles } = require('./gemini-commands');
 
-// Transformers
+// Transformers (Claude Code + Codex only — secondary IDE adapters removed)
 const claudeCodeTransformer = require('./transformers/claude-code');
-const cursorTransformer = require('./transformers/cursor');
-const antigravityTransformer = require('./transformers/antigravity');
-const githubCopilotTransformer = require('./transformers/github-copilot');
-const kimiTransformer = require(path.resolve(__dirname, 'transformers', 'kimi'));
 
 // ANSI colors for output
 const colors = {
@@ -63,36 +58,16 @@ function loadConfig(projectRoot) {
         path: '.claude/commands/SINAPSE/agents',
         format: 'full-markdown-yaml',
       },
+      // Post-E8: .codex is owned by the canonical Codex sync
+      // (sync-codex-local-first.js), which writes thin runtime pointers
+      // resolved at runtime by resolve-codex-agent.js. ide-sync drives
+      // claude-code only now; leaving this enabled would clobber those
+      // pointers with full agent bodies on a bare `sync:ide`.
       codex: {
-        enabled: true,
+        enabled: false,
         path: '.codex/agents',
         format: 'full-markdown-yaml',
       },
-      gemini: {
-        enabled: true,
-        path: '.gemini/rules/SINAPSE/agents',
-        format: 'full-markdown-yaml',
-      },
-      'github-copilot': {
-        enabled: true,
-        path: '.github/agents',
-        format: 'github-copilot',
-      },
-      cursor: {
-        enabled: true,
-        path: '.cursor/rules/agents',
-        format: 'condensed-rules',
-      },
-      antigravity: {
-        enabled: true,
-        path: '.antigravity/rules/agents',
-        format: 'cursor-style',
-      },
-      kimi: {
-        enabled: true,
-        path: '.kimi/skills',
-        format: 'kimi-skill',
-      },
     },
     redirects: {
       'sinapse-developer': 'sinapse-orqx',
@@ -131,10 +106,6 @@ function loadConfig(projectRoot) {
 function getTransformer(format) {
   const transformers = {
     'full-markdown-yaml': claudeCodeTransformer,
-    'condensed-rules': cursorTransformer,
-    'cursor-style': antigravityTransformer,
-    'github-copilot': githubCopilotTransformer,
-    'kimi-skill': kimiTransformer,
   };
 
   const transformer = transformers[format];
@@ -212,15 +183,13 @@ function syncIde(agents, ideConfig, ideName, projectRoot, options) {
 
   // Transform and write each agent
   for (const agent of agents) {
-    // Skip agents with fatal errors (no YAML block found or failed parse with no fallback)
-    if (agent.error && agent.error === 'Failed to parse YAML') {
-      result.errors.push({
-        agent: agent.id,
-        error: agent.error,
-      });
-      continue;
-    }
-    if (agent.error && agent.error === 'No YAML block found') {
+    // Skip only when there is no content at all to mirror. The claude-code
+    // transform is an identity copy of the raw file body, so an agent whose
+    // YAML block is missing/malformed but whose body exists can still be
+    // synced verbatim — e.g. the prose-format squad orqx
+    // (commercial/finance/paidmedia) pending standardization to the canonical
+    // fenced yaml block (E6). Genuinely empty/unreadable files are skipped.
+    if (agent.error && !agent.raw) {
       result.errors.push({
         agent: agent.id,
         error: agent.error,
@@ -275,6 +244,52 @@ function syncIde(agents, ideConfig, ideName, projectRoot, options) {
   return result;
 }
 
+/**
+ * Collect squad orchestrator agents (squads/SQUAD/agents/*-orqx.md).
+ *
+ * Framework-core agents come from config.source
+ * (.sinapse-ai/development/agents). The 17 squad orchestrators live under
+ * squads/** and were never enumerated here — so the Claude IDE dir only ever
+ * received the 12 core agents, and the doctor ide-sync check (which expects
+ * core + orqx) rightly WARNed. This mirrors the discovery logic in
+ * core/doctor/checks/ide-sync.js so the two always agree. Filenames are the
+ * flat basename (e.g. brand-orqx.md), via the claude-code transformer's
+ * getFilename, even though the YAML id is "squad-brand/brand-orqx".
+ *
+ * @param {string} projectRoot - Project root directory
+ * @returns {object[]} - Parsed orqx agent data
+ */
+function collectSquadOrqxAgents(projectRoot) {
+  const squadsRoot = path.join(projectRoot, 'squads');
+  const out = [];
+  if (!fs.existsSync(squadsRoot)) return out;
+
+  let squadDirs = [];
+  try {
+    squadDirs = fs
+      .readdirSync(squadsRoot, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return out;
+  }
+
+  for (const squadName of squadDirs) {
+    const agentsDir = path.join(squadsRoot, squadName, 'agents');
+    if (!fs.existsSync(agentsDir)) continue;
+    let files = [];
+    try {
+      files = fs.readdirSync(agentsDir).filter((f) => f.endsWith('-orqx.md'));
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      out.push(parseAgentFile(path.join(agentsDir, file)));
+    }
+  }
+  return out;
+}
+
 /**
  * Execute sync command
  * @param {object} options - Command options
@@ -301,7 +316,7 @@ async function commandSync(options) {
     console.log(`${colors.dim}Source: ${agentsDir}${colors.reset}`);
   }
 
-  const agents = parseAllAgents(agentsDir);
+  const agents = [...parseAllAgents(agentsDir), ...collectSquadOrqxAgents(projectRoot)];
   if (!options.quiet) {
     console.log(`${colors.dim}Found ${agents.length} agents${colors.reset}`);
     console.log('');
@@ -334,13 +349,7 @@ async function commandSync(options) {
 
     const result = syncIde(agents, ideConfig, ideName, projectRoot, options);
 
-    // Gemini CLI: also sync slash launcher command files (.gemini/commands/*.toml)
-    if (ideName === 'gemini') {
-      const geminiCommands = syncGeminiCommands(agents, projectRoot, options);
-      result.commandFiles = geminiCommands.files;
-    } else {
-      result.commandFiles = [];
-    }
+    result.commandFiles = [];
 
     results.push(result);
 
@@ -416,9 +425,9 @@ async function commandValidate(options) {
   console.log(`${colors.bright}${colors.blue}🔍 IDE Sync Validation${colors.reset}`);
   console.log('');
 
-  // Parse all agents
+  // Parse all agents (framework core + squad orchestrators)
   const agentsDir = path.join(projectRoot, config.source);
-  const agents = parseAllAgents(agentsDir);
+  const agents = [...parseAllAgents(agentsDir), ...collectSquadOrqxAgents(projectRoot)];
 
   // Build expected files for each IDE
   const ideConfigs = {};
@@ -473,18 +482,6 @@ async function commandValidate(options) {
       expectedFiles,
       targetDir: path.join(projectRoot, ideConfig.path),
     };
-
-    // Gemini CLI command launcher files are synced under .gemini/commands/*.toml
-    if (ideName === 'gemini') {
-      const commandFiles = buildGeminiCommandFiles(agents).map((entry) => ({
-        filename: entry.filename,
-        content: entry.content,
-      }));
-      ideConfigs['gemini-commands'] = {
-        expectedFiles: commandFiles,
-        targetDir: path.join(projectRoot, '.gemini', 'commands'),
-      };
-    }
   }
 
   // Validate

package/.sinapse-ai/infrastructure/scripts/sync-codex-local-first.js

@@ -21,6 +21,135 @@ function countMarkdownFiles(dirPath) {
   return fs.readdirSync(dirPath).filter((entry) => entry.endsWith('.md')).length;
 }
 
+/**
+ * Build the canonical agent source map.
+ * Source of truth = framework core agents (canonicalAgentsDir, flat *.md)
+ * + every squad specialist/orchestrator under squads/<squad>/agents/*.md.
+ *
+ * The result keys agents by id (filename without .md). When the same id exists
+ * in more than one place, core wins, then the first squad alphabetically — but in
+ * practice ids are unique across the ecosystem. Deprecated folders (e.g.
+ * squads/<squad>/_deprecated) are intentionally NOT scanned, so retired agents
+ * never re-enter the catalog.
+ *
+ * @param {string} projectRoot
+ * @param {string} canonicalAgentsDir - relative path to core agents dir
+ * @param {string} squadsDir - relative path to squads root (default 'squads')
+ * @returns {Map<string, {id: string, squad: string, sourcePath: string}>}
+ */
+function buildAgentSourceMap(projectRoot, canonicalAgentsDir, squadsDir = 'squads') {
+  const map = new Map();
+
+  const addAgent = (filePath, squad) => {
+    if (!filePath.endsWith('.md')) return;
+    const id = path.basename(filePath, '.md');
+    if (map.has(id)) return; // first writer wins (core scanned first)
+    map.set(id, {
+      id,
+      squad,
+      sourcePath: path.relative(projectRoot, filePath).split(path.sep).join('/'),
+    });
+  };
+
+  // 1. Framework core agents (flat *.md only — ignore persona subfolders)
+  const coreDir = path.join(projectRoot, canonicalAgentsDir);
+  if (fs.existsSync(coreDir)) {
+    for (const entry of fs.readdirSync(coreDir, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        addAgent(path.join(coreDir, entry.name), 'core');
+      }
+    }
+  }
+
+  // 2. Squad specialists + orchestrators
+  const squadsRoot = path.join(projectRoot, squadsDir);
+  if (fs.existsSync(squadsRoot)) {
+    for (const squadEntry of fs.readdirSync(squadsRoot, { withFileTypes: true })) {
+      if (!squadEntry.isDirectory()) continue;
+      const squadName = squadEntry.name;
+      const agentsDir = path.join(squadsRoot, squadName, 'agents');
+      if (!fs.existsSync(agentsDir)) continue;
+      for (const agentEntry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+        // Only top-level *.md — skip _deprecated/ and persona subfolders
+        if (agentEntry.isFile() && agentEntry.name.endsWith('.md')) {
+          addAgent(path.join(agentsDir, agentEntry.name), squadName);
+        }
+      }
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Render the Codex activator pointer for an agent. Thin by design (D7):
+ * Codex reads the real persona/tasks from the canonical source, so the pointer
+ * never copies content — it only routes to the source of truth.
+ *
+ * @param {{id: string, squad: string, sourcePath: string}} agent
+ * @returns {string}
+ */
+function renderCodexActivator(agent) {
+  return [
+    `Activate agent: ${agent.id}`,
+    `Squad: ${agent.squad}`,
+    `Read the agent definition at: ${agent.sourcePath}`,
+    'Follow ALL instructions in the agent file. Adopt the persona, use the frameworks, and respond as that agent.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Regenerate .codex/agents from the canonical source map, idempotently.
+ * - Writes/updates one activator per source agent (pointers always valid,
+ *   because the target path is derived from where the file actually lives).
+ * - Prunes any .codex agent whose id is not in the source set (removes orphans
+ *   such as retired chiefs and squad-artdir personas).
+ *
+ * @returns {{written: string[], pruned: string[], total: number}}
+ */
+function regenerateCodexAgents(agentsDir, sourceMap, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const written = [];
+  const pruned = [];
+
+  if (!dryRun) {
+    fs.mkdirSync(agentsDir, { recursive: true });
+  }
+
+  // 1. Write/refresh pointers for every canonical agent
+  for (const agent of sourceMap.values()) {
+    const target = path.join(agentsDir, `${agent.id}.md`);
+    const next = renderCodexActivator(agent);
+    let current = null;
+    if (fs.existsSync(target)) {
+      current = fs.readFileSync(target, 'utf8');
+    }
+    if (current !== next) {
+      if (!dryRun) fs.writeFileSync(target, next, 'utf8');
+      written.push(`${agent.id}.md`);
+    }
+  }
+
+  // 2. Prune orphans (present in .codex but absent from source)
+  if (fs.existsSync(agentsDir)) {
+    for (const entry of fs.readdirSync(agentsDir)) {
+      if (!entry.endsWith('.md')) continue;
+      const id = entry.slice(0, -'.md'.length);
+      if (!sourceMap.has(id)) {
+        if (!dryRun) fs.rmSync(path.join(agentsDir, entry), { force: true });
+        pruned.push(entry);
+      }
+    }
+  }
+
+  return {
+    written,
+    pruned,
+    total: sourceMap.size,
+  };
+}
+
 function countSkillFiles(skillsDir) {
   if (!fs.existsSync(skillsDir)) return 0;
   return fs.readdirSync(skillsDir, { withFileTypes: true })
@@ -88,6 +217,20 @@ function syncCodexLocalFirst(options = {}, deps = {}) {
     };
   }
 
+  // Regenerate the agent catalog from the canonical source of truth.
+  // This replaces the old "preserve whatever is on disk" behaviour that froze
+  // the snapshot and perpetuated broken pointers + retired orphans.
+  const sourceMap = (deps.buildAgentSourceMap || buildAgentSourceMap)(
+    projectRoot,
+    config.canonicalAgentsDir || '.sinapse-ai/development/agents',
+    config.squadsDir || 'squads',
+  );
+  const regen = (deps.regenerateCodexAgents || regenerateCodexAgents)(
+    agentsDir,
+    sourceMap,
+    { dryRun: Boolean(options.dryRun) },
+  );
+
   const syncResult = runSyncSkills({
     projectRoot,
     sourceDir,
@@ -104,6 +247,8 @@ function syncCodexLocalFirst(options = {}, deps = {}) {
     errors: [],
     metrics: {
       codexAgents: countMarkdownFiles(agentsDir),
+      agentsRegenerated: regen.written.length,
+      agentsPruned: regen.pruned.length,
       codexSkills: countSkillFiles(skillsDir),
       generatedSkills: syncResult.generated,
     },
@@ -122,7 +267,14 @@ function formatHumanReport(result) {
     ].join('\n');
   }
 
-  return `OK Codex local-first sync complete (agents preserved: ${result.metrics.codexAgents}, total skills: ${result.metrics.codexSkills}, skills regenerated: ${result.metrics.generatedSkills})`;
+  return (
+    `OK Codex local-first sync complete ` +
+    `(agents: ${result.metrics.codexAgents}, ` +
+    `regenerated: ${result.metrics.agentsRegenerated ?? 0}, ` +
+    `pruned: ${result.metrics.agentsPruned ?? 0}, ` +
+    `total skills: ${result.metrics.codexSkills}, ` +
+    `skills regenerated: ${result.metrics.generatedSkills})`
+  );
 }
 
 function main() {
@@ -153,4 +305,7 @@ module.exports = {
   runLegacyCodexSync,
   countMarkdownFiles,
   countSkillFiles,
+  buildAgentSourceMap,
+  renderCodexActivator,
+  regenerateCodexAgents,
 };

package/.sinapse-ai/infrastructure/scripts/validate-codex-delegation.js

@@ -6,10 +6,8 @@ const path = require('path');
 const Ajv2020 = require('ajv/dist/2020');
 const {
   loadDelegationMatrix,
-} = require(path.join(__dirname, '..', '..', '..', '.codex', 'scripts', 'resolve-codex-delegation'));
-const {
   buildHandoffPacket,
-} = require(path.join(__dirname, '..', '..', '..', '.codex', 'scripts', 'resolve-codex-delegation-parity'));
+} = require(path.join(__dirname, '..', '..', '..', '.codex', 'scripts', 'resolve-codex-delegation'));
 const {
   loadRegistry: loadCommandRegistryFile,
 } = require('./validate-codex-command-registry');
@@ -27,7 +25,6 @@ const REQUIRED_ORCHESTRATORS = Object.freeze([
   'paidmedia-orqx',
   'product-orqx',
   'research-orqx',
-  'claude-orqx',
   'council-orqx',
   'storytelling-orqx',
   'cyber-orqx',

package/.sinapse-ai/infrastructure/scripts/validate-codex-integration.js

@@ -7,6 +7,7 @@ const {
   loadCodexCatalogConfig,
   getConfiguredSkillIds,
 } = require('./codex-parity/catalog');
+const { resolveCatalog } = require('./codex-parity/resolve');
 
 function getDefaultOptions() {
   const projectRoot = process.cwd();
@@ -77,14 +78,45 @@ function validateCodexIntegration(options = {}) {
   const codexSkillsCount = countSkillFiles(resolved.skillsDir);
   const expectedSkillIds = getConfiguredSkillIds(config);
 
-  if (config.catalogMode !== 'expanded' && sourceCount > 0 && codexAgentsCount !== sourceCount) {
-    warnings.push(`Codex agent count differs from source (${codexAgentsCount}/${sourceCount})`);
+  // --- Behavioral resolution (anti-fachada) --------------------------------
+  // Open every Codex agent pointer and RESOLVE it against the real
+  // source-of-truth set. A present file is not parity; a resolving pointer is.
+  const catalog = resolveCatalog(resolved.projectRoot, {
+    canonicalAgentsDir: config.canonicalAgentsDir || '.sinapse-ai/development/agents',
+    codexAgentsDir: config.codexAgentsDir || '.codex/agents',
+    squadsDir: config.squadsDir || 'squads',
+  });
+
+  for (const broken of catalog.brokenPointers) {
+    errors.push(
+      `Broken Codex pointer: ${broken.id} -> ${broken.target || '(no target)'} (${broken.reason})`,
+    );
+  }
+
+  for (const orphan of catalog.orphans) {
+    errors.push(
+      `Orphan Codex agent: ${orphan.id} has no source-of-truth in the canonical agent set`,
+    );
+  }
+
+  // --- Count parity: MISMATCH is now an ERROR, not a soft warning ----------
+  // In expanded mode the Codex catalog is the full ecosystem (172), which is
+  // intentionally larger than the dev/core agents dir. Parity is measured
+  // against the resolvable source set, not the dev dir.
+  if (config.catalogMode === 'expanded') {
+    if (codexAgentsCount !== catalog.resolved.length) {
+      errors.push(
+        `Codex agent count mismatch: ${codexAgentsCount} catalog file(s) but only ${catalog.resolved.length} resolve cleanly`,
+      );
+    }
+  } else if (sourceCount > 0 && codexAgentsCount !== sourceCount) {
+    errors.push(`Codex agent count differs from source (${codexAgentsCount}/${sourceCount})`);
   }
 
   if (expectedSkillIds && codexSkillsCount !== expectedSkillIds.length) {
-    warnings.push(`Codex skill count differs from configured catalog (${codexSkillsCount}/${expectedSkillIds.length})`);
+    errors.push(`Codex skill count differs from configured catalog (${codexSkillsCount}/${expectedSkillIds.length})`);
   } else if (!expectedSkillIds && sourceCount > 0 && codexSkillsCount !== sourceCount) {
-    warnings.push(`Codex skill count differs from source (${codexSkillsCount}/${sourceCount})`);
+    errors.push(`Codex skill count differs from source (${codexSkillsCount}/${sourceCount})`);
   }
 
   return {
@@ -96,6 +128,10 @@ function validateCodexIntegration(options = {}) {
       codexAgents: codexAgentsCount,
       codexSkills: codexSkillsCount,
       expectedSkills: expectedSkillIds ? expectedSkillIds.length : sourceCount,
+      resolvedPointers: catalog.resolved.length,
+      brokenPointers: catalog.brokenPointers.length,
+      orphans: catalog.orphans.length,
+      sourceAgents: catalog.sourceCount,
     },
   };
 }
@@ -103,7 +139,7 @@ function validateCodexIntegration(options = {}) {
 function formatHumanReport(result) {
   if (result.ok) {
     const lines = [
-      `✅ Codex integration validation passed (agents: ${result.metrics.codexAgents}, skills: ${result.metrics.codexSkills})`,
+      `✅ Codex integration validation passed (agents: ${result.metrics.codexAgents} resolve, ${result.metrics.orphans} orphans, ${result.metrics.brokenPointers} broken pointers, skills: ${result.metrics.codexSkills})`,
     ];
     if (result.warnings.length > 0) {
       lines.push(...result.warnings.map((w) => `⚠️ ${w}`));