sinapse-ai 7.7.3 → 7.7.5

package/.sinapse-ai/infrastructure/scripts/validate-codex-command-registry.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRED_COMMAND_COVERAGE = Object.freeze({
+  'sinapse-orqx': ['onboard', 'route', 'plan', 'status', 'brief', 'resolve', 'council'],
+  'sinapse-pm': [
+    'create-prd',
+    'create-brownfield-prd',
+    'create-epic',
+    'create-story',
+    'research',
+    'execute-epic',
+    'gather-requirements',
+    'write-spec',
+    'shard-prd',
+  ],
+  'sinapse-po': [
+    'validate-story',
+    'validate-story-draft',
+    'backlog-review',
+    'backlog-prioritize',
+    'backlog-schedule',
+    'close-story',
+    'sync-story',
+    'pull-story',
+    'stories-index',
+  ],
+  'sinapse-sm': ['draft', 'story-checklist'],
+  'sinapse-dev': [
+    'develop',
+    'run-tests',
+    'apply-qa-fixes',
+    'execute-subtask',
+    'verify-subtask',
+    'build-autonomous',
+    'build-resume',
+    'build-status',
+    'build',
+  ],
+  'sinapse-qa': [
+    'review',
+    'review-story',
+    'code-review',
+    'gate',
+    'review-build',
+    'create-fix-request',
+    'test-design',
+    'generate-tests',
+    'run-tests',
+    'nfr-assess',
+    'validate-libraries',
+    'security-check',
+    'validate-migrations',
+    'evidence-check',
+    'false-positive-check',
+    'console-check',
+  ],
+});
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  return {
+    quiet: args.has('--quiet') || args.has('-q'),
+    json: args.has('--json'),
+  };
+}
+
+function normalizeAgentAlias(value) {
+  return String(value || '').trim().replace(/^@/, '').toLowerCase();
+}
+
+function normalizeCommandAlias(value) {
+  return String(value || '').trim().replace(/^\*/, '').toLowerCase();
+}
+
+function collectAgentAliases(agentId, agentSpec) {
+  return [agentId, ...(agentSpec.aliases || [])]
+    .map((alias) => normalizeAgentAlias(alias))
+    .filter(Boolean);
+}
+
+function collectCommandAliases(commandId, commandSpec) {
+  return [commandId, ...(commandSpec.aliases || [])]
+    .map((alias) => normalizeCommandAlias(alias))
+    .filter(Boolean);
+}
+
+function loadRegistry(projectRoot) {
+  const registryPath = path.join(projectRoot, '.codex', 'command-registry.json');
+  if (!fs.existsSync(registryPath)) {
+    return {
+      registryPath,
+      registry: null,
+      error: `Missing Codex command registry: ${path.relative(projectRoot, registryPath)}`,
+    };
+  }
+
+  try {
+    return {
+      registryPath,
+      registry: JSON.parse(fs.readFileSync(registryPath, 'utf8')),
+      error: null,
+    };
+  } catch (error) {
+    return {
+      registryPath,
+      registry: null,
+      error: `Unable to parse Codex command registry: ${error.message}`,
+    };
+  }
+}
+
+function validateRequiredCoverage(registry, requiredCoverage, errors) {
+  for (const [agentId, requiredCommands] of Object.entries(requiredCoverage || {})) {
+    const agentSpec = (registry.agents || {})[agentId];
+    if (!agentSpec) {
+      errors.push(`missing required agent coverage: ${agentId}`);
+      continue;
+    }
+
+    const availableCommands = new Set();
+    for (const [commandId, commandSpec] of Object.entries(agentSpec.commands || {})) {
+      for (const alias of collectCommandAliases(commandId, commandSpec)) {
+        availableCommands.add(alias);
+      }
+    }
+
+    for (const requiredCommand of requiredCommands) {
+      if (!availableCommands.has(normalizeCommandAlias(requiredCommand))) {
+        errors.push(`${agentId}: missing required command coverage for ${requiredCommand}`);
+      }
+    }
+  }
+}
+
+function validateCodexCommandRegistry(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const { registryPath, registry, error } = loadRegistry(projectRoot);
+  const errors = [];
+  const requiredCoverage =
+    options.requiredCoverage === false
+      ? null
+      : options.requiredCoverage || REQUIRED_COMMAND_COVERAGE;
+
+  if (error) {
+    errors.push(error);
+    return {
+      ok: false,
+      errors,
+      warnings: [],
+      metrics: { agents: 0, commands: 0 },
+    };
+  }
+
+  let commandCount = 0;
+  const seenAgentAliases = new Map();
+  for (const [agentId, agentSpec] of Object.entries(registry.agents || {})) {
+    const skillPath = path.join(projectRoot, '.codex', 'skills', agentSpec.skillId || agentId, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+      errors.push(`${agentId}: missing skill file ${path.relative(projectRoot, skillPath)}`);
+    }
+
+    const sourceOfTruth = path.join(projectRoot, agentSpec.sourceOfTruth || '');
+    if (!fs.existsSync(sourceOfTruth)) {
+      errors.push(`${agentId}: missing source of truth ${path.relative(projectRoot, sourceOfTruth)}`);
+    }
+
+    for (const alias of collectAgentAliases(agentId, agentSpec)) {
+      const owner = seenAgentAliases.get(alias);
+      if (owner && owner !== agentId) {
+        errors.push(`duplicate agent alias "${alias}" claimed by ${owner} and ${agentId}`);
+      } else {
+        seenAgentAliases.set(alias, agentId);
+      }
+    }
+
+    const seenCommandAliases = new Map();
+    for (const [commandId, commandSpec] of Object.entries(agentSpec.commands || {})) {
+      commandCount += 1;
+
+      const targetPath = path.join(projectRoot, commandSpec.target || '');
+      if (!fs.existsSync(targetPath)) {
+        errors.push(`${agentId}.${commandId}: missing target ${path.relative(projectRoot, targetPath)}`);
+      }
+
+      for (const resource of commandSpec.resources || []) {
+        const resourcePath = path.join(projectRoot, resource);
+        if (!fs.existsSync(resourcePath)) {
+          errors.push(`${agentId}.${commandId}: missing resource ${path.relative(projectRoot, resourcePath)}`);
+        }
+      }
+
+      for (const alias of collectCommandAliases(commandId, commandSpec)) {
+        const owner = seenCommandAliases.get(alias);
+        if (owner && owner !== commandId) {
+          errors.push(`${agentId}: duplicate command alias "${alias}" claimed by ${owner} and ${commandId}`);
+        } else {
+          seenCommandAliases.set(alias, commandId);
+        }
+      }
+    }
+  }
+
+  validateRequiredCoverage(registry, requiredCoverage, errors);
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings: [],
+    metrics: {
+      agents: Object.keys(registry.agents || {}).length,
+      commands: commandCount,
+      registryPath: path.relative(projectRoot, registryPath),
+    },
+  };
+}
+
+function formatHumanReport(result) {
+  if (result.ok) {
+    return `OK Codex command registry validation passed (agents: ${result.metrics.agents}, commands: ${result.metrics.commands})`;
+  }
+
+  return [
+    `X Codex command registry validation failed (${result.errors.length} issue(s))`,
+    ...result.errors.map((error) => `- ${error}`),
+  ].join('\n');
+}
+
+function main() {
+  const args = parseArgs();
+  const result = validateCodexCommandRegistry(args);
+
+  if (!args.quiet) {
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatHumanReport(result));
+    }
+  }
+
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parseArgs,
+  loadRegistry,
+  normalizeAgentAlias,
+  normalizeCommandAlias,
+  collectAgentAliases,
+  collectCommandAliases,
+  validateRequiredCoverage,
+  validateCodexCommandRegistry,
+  formatHumanReport,
+  REQUIRED_COMMAND_COVERAGE,
+};

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

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const Ajv2020 = require('ajv/dist/2020');
+const {
+  buildHandoffPacket,
+  loadDelegationMatrix,
+} = require(path.join(__dirname, '..', '..', '..', '.codex', 'scripts', 'resolve-codex-delegation'));
+const {
+  loadRegistry: loadCommandRegistryFile,
+} = require('./validate-codex-command-registry');
+
+const REQUIRED_ORCHESTRATORS = Object.freeze([
+  'sinapse-orqx',
+  'brand-orqx',
+  'commercial-orqx',
+  'content-orqx',
+  'copy-orqx',
+  'animations-orqx',
+  'design-orqx',
+  'finance-orqx',
+  'growth-orqx',
+  'paidmedia-orqx',
+  'product-orqx',
+  'research-orqx',
+  'claude-orqx',
+  'council-orqx',
+  'storytelling-orqx',
+  'cyber-orqx',
+  'cloning-orqx',
+  'courses-orqx',
+  'swarm-orqx',
+]);
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  return {
+    quiet: args.has('--quiet') || args.has('-q'),
+    json: args.has('--json'),
+  };
+}
+
+function validateCodexDelegation(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const errors = [];
+  const warnings = [];
+  const requiredOrchestrators =
+    options.requiredOrchestrators === false
+      ? null
+      : options.requiredOrchestrators || REQUIRED_ORCHESTRATORS;
+
+  let matrix;
+  try {
+    matrix = loadDelegationMatrix(projectRoot);
+  } catch (error) {
+    errors.push(`Unable to load Codex delegation matrix: ${error.message}`);
+    return {
+      ok: false,
+      errors,
+      warnings,
+      metrics: { orchestrators: 0, routes: 0 },
+    };
+  }
+
+  const matrixPath = path.join(projectRoot, '.codex', 'delegation-matrix.json');
+  const schemaPath = path.join(projectRoot, matrix.handoffSchema || '.codex/handoff-packet.schema.json');
+  if (!fs.existsSync(schemaPath)) {
+    errors.push(`Missing handoff schema ${path.relative(projectRoot, schemaPath)}`);
+  }
+
+  let schema = null;
+  if (fs.existsSync(schemaPath)) {
+    try {
+      schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+    } catch (error) {
+      errors.push(`Unable to parse handoff schema: ${error.message}`);
+    }
+  }
+
+  const { registry: commandRegistry, error: commandRegistryError } = loadCommandRegistryFile(projectRoot);
+  if (commandRegistryError) {
+    errors.push(commandRegistryError);
+  }
+
+  const orchestrators = matrix.orchestrators || {};
+  const frameworkAgents = matrix.frameworkAgents || {};
+  const routes = matrix.routes || {};
+
+  if (requiredOrchestrators) {
+    for (const orchestratorId of requiredOrchestrators) {
+      if (!orchestrators[orchestratorId]) {
+        errors.push(`missing required orchestrator coverage: ${orchestratorId}`);
+      }
+    }
+  }
+
+  for (const [orchestratorId, orchestratorSpec] of Object.entries(orchestrators)) {
+    const sourceOfTruth = path.join(projectRoot, orchestratorSpec.sourceOfTruth || '');
+    if (!fs.existsSync(sourceOfTruth)) {
+      errors.push(`${orchestratorId}: missing source of truth ${path.relative(projectRoot, sourceOfTruth)}`);
+    }
+
+    if (orchestratorSpec.squadDir) {
+      const squadDir = path.join(projectRoot, orchestratorSpec.squadDir);
+      if (!fs.existsSync(squadDir)) {
+        errors.push(`${orchestratorId}: missing squad dir ${path.relative(projectRoot, squadDir)}`);
+      }
+    }
+
+    if (orchestratorSpec.tasksDir) {
+      const tasksDir = path.join(projectRoot, orchestratorSpec.tasksDir);
+      if (!fs.existsSync(tasksDir)) {
+        errors.push(`${orchestratorId}: missing tasks dir ${path.relative(projectRoot, tasksDir)}`);
+      }
+    }
+
+    for (const routeId of orchestratorSpec.approvedRoutes || []) {
+      if (!routes[routeId]) {
+        errors.push(`${orchestratorId}: missing approved route ${routeId}`);
+      }
+    }
+  }
+
+  const routeAliases = new Map();
+  const ajv = schema ? new Ajv2020({ allErrors: true, strict: false }) : null;
+  const validatePacket = schema ? ajv.compile(schema) : null;
+  let routeCount = 0;
+  let validatorBackedCount = 0;
+  let shimCount = 0;
+  let exploratoryCount = 0;
+
+  for (const [routeId, routeSpec] of Object.entries(routes)) {
+    routeCount += 1;
+    if (routeSpec.classification === 'validator-backed') validatorBackedCount += 1;
+    if (routeSpec.classification === 'codex-only-shim') shimCount += 1;
+    if (routeSpec.classification === 'exploratory') exploratoryCount += 1;
+
+    if (!orchestrators[routeSpec.owner]) {
+      errors.push(`${routeId}: unknown route owner ${routeSpec.owner}`);
+    }
+
+    if (!(matrix.routingClasses || []).includes(routeSpec.classification)) {
+      errors.push(`${routeId}: invalid classification ${routeSpec.classification}`);
+    }
+
+    if (!(matrix.requestTypes || []).includes(routeSpec.requestType)) {
+      errors.push(`${routeId}: invalid request type ${routeSpec.requestType}`);
+    }
+
+    for (const alias of [routeId, ...(routeSpec.aliases || [])]) {
+      const normalized = String(alias || '').trim().toLowerCase();
+      const owner = routeAliases.get(normalized);
+      if (owner && owner !== routeId) {
+        errors.push(`duplicate delegation route alias "${normalized}" claimed by ${owner} and ${routeId}`);
+      } else {
+        routeAliases.set(normalized, routeId);
+      }
+    }
+
+    for (const resource of routeSpec.resources || []) {
+      const resourcePath = path.join(projectRoot, resource);
+      if (!fs.existsSync(resourcePath)) {
+        errors.push(`${routeId}: missing resource ${path.relative(projectRoot, resourcePath)}`);
+      }
+    }
+
+    if (!Array.isArray(routeSpec.delegationChain) || routeSpec.delegationChain.length === 0) {
+      errors.push(`${routeId}: missing delegation chain`);
+      continue;
+    }
+
+    if (routeSpec.delegationChain[0].from !== routeSpec.owner) {
+      errors.push(`${routeId}: first delegation step must start from the route owner`);
+    }
+
+    for (const [index, step] of routeSpec.delegationChain.entries()) {
+      const stepLabel = `${routeId}.step${index + 1}`;
+
+      if (step.fromType === 'orqx' && !orchestrators[step.from]) {
+        errors.push(`${stepLabel}: unknown from orchestrator ${step.from}`);
+      }
+      if (step.fromType === 'framework-agent' && !frameworkAgents[step.from]) {
+        errors.push(`${stepLabel}: unknown from framework agent ${step.from}`);
+      }
+
+      if (step.toType === 'orqx') {
+        if (!orchestrators[step.to]) {
+          errors.push(`${stepLabel}: unknown target orchestrator ${step.to}`);
+        }
+      } else if (step.toType === 'framework-agent') {
+        if (!frameworkAgents[step.to]) {
+          errors.push(`${stepLabel}: unknown target framework agent ${step.to}`);
+        }
+        if (step.resolver !== 'command-registry') {
+          errors.push(`${stepLabel}: framework-agent steps must use resolver "command-registry"`);
+        }
+        const registryAgent = commandRegistry?.agents?.[frameworkAgents[step.to]?.registryAgentId || step.to];
+        if (!registryAgent) {
+          errors.push(`${stepLabel}: missing command registry entry for ${step.to}`);
+        } else if (!registryAgent.commands?.[step.command]) {
+          errors.push(`${stepLabel}: missing command registry command ${step.to}.${step.command}`);
+        }
+      } else if (step.toType === 'specialist') {
+        const specialistPath = step.path
+          ? path.join(projectRoot, step.path)
+          : path.join(projectRoot, '.codex', 'agents', `${step.to}.md`);
+        if (!fs.existsSync(specialistPath)) {
+          errors.push(`${stepLabel}: missing specialist path ${path.relative(projectRoot, specialistPath)}`);
+        }
+      }
+
+      if (step.path) {
+        const stepPath = path.join(projectRoot, step.path);
+        if (!fs.existsSync(stepPath)) {
+          errors.push(`${stepLabel}: missing path ${path.relative(projectRoot, stepPath)}`);
+        }
+      }
+
+      if (step.task) {
+        const taskPath = path.join(projectRoot, step.task);
+        if (!fs.existsSync(taskPath)) {
+          errors.push(`${stepLabel}: missing task ${path.relative(projectRoot, taskPath)}`);
+        }
+      }
+    }
+
+    if (validatePacket) {
+      const packet = buildHandoffPacket(routeId, projectRoot, matrix);
+      const valid = validatePacket(packet);
+      if (!valid) {
+        errors.push(
+          `${routeId}: handoff packet failed schema validation ${ajv.errorsText(validatePacket.errors, { separator: '; ' })}`,
+        );
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    metrics: {
+      matrixPath: path.relative(projectRoot, matrixPath),
+      orchestrators: Object.keys(orchestrators).length,
+      routes: routeCount,
+      validatorBackedRoutes: validatorBackedCount,
+      codexOnlyShimRoutes: shimCount,
+      exploratoryRoutes: exploratoryCount,
+    },
+  };
+}
+
+function formatHumanReport(result) {
+  if (result.ok) {
+    return `OK Codex delegation validation passed (orchestrators: ${result.metrics.orchestrators}, routes: ${result.metrics.routes})`;
+  }
+
+  return [
+    `X Codex delegation validation failed (${result.errors.length} issue(s))`,
+    ...result.errors.map((error) => `- ${error}`),
+  ].join('\n');
+}
+
+function main() {
+  const args = parseArgs();
+  const result = validateCodexDelegation(args);
+
+  if (!args.quiet) {
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatHumanReport(result));
+    }
+  }
+
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parseArgs,
+  validateCodexDelegation,
+  formatHumanReport,
+  REQUIRED_ORCHESTRATORS,
+};

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

@@ -3,6 +3,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const {
+  loadCodexCatalogConfig,
+  getConfiguredSkillIds,
+} = require('./codex-parity/catalog');
 
 function getDefaultOptions() {
   const projectRoot = process.cwd();
@@ -41,14 +45,15 @@ function countSkillFiles(skillsDir) {
 
 function validateCodexIntegration(options = {}) {
   const projectRoot = options.projectRoot || process.cwd();
+  const config = loadCodexCatalogConfig(projectRoot);
   const resolved = {
     ...getDefaultOptions(),
     ...options,
     projectRoot,
     instructionsFile: options.instructionsFile || path.join(projectRoot, 'AGENTS.md'),
-    agentsDir: options.agentsDir || path.join(projectRoot, '.codex', 'agents'),
-    skillsDir: options.skillsDir || path.join(projectRoot, '.codex', 'skills'),
-    sourceAgentsDir: options.sourceAgentsDir || path.join(projectRoot, '.sinapse-ai', 'development', 'agents'),
+    agentsDir: options.agentsDir || path.join(projectRoot, config.codexAgentsDir || '.codex/agents'),
+    skillsDir: options.skillsDir || path.join(projectRoot, config.skillsDir || '.codex/skills'),
+    sourceAgentsDir: options.sourceAgentsDir || path.join(projectRoot, config.canonicalAgentsDir || '.sinapse-ai/development/agents'),
   };
   const errors = [];
   const warnings = [];
@@ -70,12 +75,15 @@ function validateCodexIntegration(options = {}) {
   const sourceCount = countMarkdownFiles(resolved.sourceAgentsDir);
   const codexAgentsCount = countMarkdownFiles(resolved.agentsDir);
   const codexSkillsCount = countSkillFiles(resolved.skillsDir);
+  const expectedSkillIds = getConfiguredSkillIds(config);
 
-  if (sourceCount > 0 && codexAgentsCount !== sourceCount) {
+  if (config.catalogMode !== 'expanded' && sourceCount > 0 && codexAgentsCount !== sourceCount) {
     warnings.push(`Codex agent count differs from source (${codexAgentsCount}/${sourceCount})`);
   }
 
-  if (sourceCount > 0 && codexSkillsCount !== sourceCount) {
+  if (expectedSkillIds && codexSkillsCount !== expectedSkillIds.length) {
+    warnings.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})`);
   }
 
@@ -84,9 +92,10 @@ function validateCodexIntegration(options = {}) {
     errors,
     warnings,
     metrics: {
-      sourceAgents: sourceCount,
+      canonicalAgents: sourceCount,
       codexAgents: codexAgentsCount,
       codexSkills: codexSkillsCount,
+      expectedSkills: expectedSkillIds ? expectedSkillIds.length : sourceCount,
     },
   };
 }