sinapse-ai 7.7.3 → 7.7.4

package/.sinapse-ai/data/registry-update-log.jsonl

@@ -557,3 +557,13 @@
 {"timestamp":"2026-04-02T01:18:15.933Z","action":"change","path":".sinapse-ai/core/doctor/checks/constitution-consistency.js","trigger":"watcher"}
 {"timestamp":"2026-04-02T01:18:15.934Z","action":"change","path":".sinapse-ai/core/health-check/checks/project/constitution-consistency.js","trigger":"watcher"}
 {"timestamp":"2026-04-02T01:18:15.934Z","action":"change","path":".sinapse-ai/product/templates/ide-rules/claude-rules.md","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.329Z","action":"change","path":".sinapse-ai/core-config.yaml","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.331Z","action":"add","path":".sinapse-ai/infrastructure/scripts/codex-parity/catalog.js","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.331Z","action":"change","path":".sinapse-ai/infrastructure/scripts/codex-skills-sync/index.js","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.331Z","action":"change","path":".sinapse-ai/infrastructure/scripts/codex-skills-sync/validate.js","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.332Z","action":"add","path":".sinapse-ai/infrastructure/scripts/sync-codex-local-first.js","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.332Z","action":"add","path":".sinapse-ai/infrastructure/scripts/validate-codex-command-registry.js","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.333Z","action":"change","path":".sinapse-ai/infrastructure/scripts/validate-codex-integration.js","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.333Z","action":"add","path":".sinapse-ai/infrastructure/scripts/validate-codex-sync.js","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.333Z","action":"change","path":".sinapse-ai/infrastructure/scripts/validate-parity.js","trigger":"watcher"}
+{"timestamp":"2026-04-02T23:48:52.333Z","action":"change","path":".sinapse-ai/infrastructure/scripts/validate-paths.js","trigger":"watcher"}

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

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_CONFIG = {
+  version: 1,
+  catalogMode: 'canonical',
+  canonicalAgentsDir: '.sinapse-ai/development/agents',
+  codexAgentsDir: '.codex/agents',
+  skillsDir: '.codex/skills',
+  expectedSkillIds: null,
+  generatedSkillMap: {},
+  canonicalSkillMap: {},
+  pathConventions: {
+    allowedSourcePrefixes: ['.sinapse-ai/development/agents/'],
+    allowedGreetingScriptPrefixes: ['.sinapse-ai/development/scripts/generate-greeting.js'],
+    greetingOptionalSourcePrefixes: [],
+    requiredFallbackBySourcePrefix: {},
+  },
+};
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeConfig(base, override) {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override || {})) {
+    if (Array.isArray(value)) {
+      result[key] = [...value];
+      continue;
+    }
+    if (isPlainObject(value) && isPlainObject(base[key])) {
+      result[key] = mergeConfig(base[key], value);
+      continue;
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+function getCatalogConfigPath(projectRoot = process.cwd()) {
+  return path.join(projectRoot, '.codex', 'catalog.json');
+}
+
+function loadCodexCatalogConfig(projectRoot = process.cwd()) {
+  const configPath = getCatalogConfigPath(projectRoot);
+  if (!fs.existsSync(configPath)) {
+    return mergeConfig(DEFAULT_CONFIG, {});
+  }
+
+  const raw = fs.readFileSync(configPath, 'utf8');
+  const parsed = JSON.parse(raw);
+  return mergeConfig(DEFAULT_CONFIG, parsed);
+}
+
+function getConfiguredSkillIds(config) {
+  if (!Array.isArray(config.expectedSkillIds) || config.expectedSkillIds.length === 0) {
+    return null;
+  }
+  return [...config.expectedSkillIds].sort();
+}
+
+function getGeneratedSkillSpec(agentId, config) {
+  return config.generatedSkillMap?.[agentId] || null;
+}
+
+function hasAllowedPrefix(content, prefixes = []) {
+  return prefixes.some((prefix) => content.includes(prefix));
+}
+
+function detectMatchedSourcePrefix(content, prefixes = []) {
+  let matchedPrefix = null;
+  let matchedIndex = Number.POSITIVE_INFINITY;
+
+  for (const prefix of prefixes) {
+    const index = content.indexOf(prefix);
+    if (index === -1) continue;
+    if (index < matchedIndex) {
+      matchedIndex = index;
+      matchedPrefix = prefix;
+    }
+  }
+
+  return matchedPrefix;
+}
+
+function validateSkillActivationPaths(content, filePath, config) {
+  const rules = config.pathConventions || DEFAULT_CONFIG.pathConventions;
+  const errors = [];
+
+  const matchedSourcePrefix = detectMatchedSourcePrefix(content, rules.allowedSourcePrefixes);
+  if (!matchedSourcePrefix) {
+    errors.push(`${filePath} missing approved source path`);
+    return errors;
+  }
+
+  const requiredFallback = rules.requiredFallbackBySourcePrefix?.[matchedSourcePrefix];
+  if (requiredFallback && !content.includes(requiredFallback)) {
+    errors.push(`${filePath} missing fallback activation path "${requiredFallback}"`);
+  }
+
+  const greetingOptional = (rules.greetingOptionalSourcePrefixes || [])
+    .some((prefix) => matchedSourcePrefix.startsWith(prefix));
+
+  if (!greetingOptional && !hasAllowedPrefix(content, rules.allowedGreetingScriptPrefixes)) {
+    errors.push(`${filePath} missing approved greeting script path`);
+  }
+
+  return errors;
+}
+
+module.exports = {
+  DEFAULT_CONFIG,
+  mergeConfig,
+  getCatalogConfigPath,
+  loadCodexCatalogConfig,
+  getConfiguredSkillIds,
+  getGeneratedSkillSpec,
+  validateSkillActivationPaths,
+};

package/.sinapse-ai/infrastructure/scripts/codex-skills-sync/index.js

@@ -10,6 +10,10 @@ const {
   normalizeCommands,
   getVisibleCommands,
 } = require('../ide-sync/agent-parser');
+const {
+  loadCodexCatalogConfig,
+  getGeneratedSkillSpec,
+} = require('../codex-parity/catalog');
 
 function getCodexHome() {
   return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
@@ -43,7 +47,28 @@ function getSkillId(agentId) {
   return `sinapse-${id}`;
 }
 
-function buildSkillContent(agentData) {
+function resolveSkillSpec(agentData, config) {
+  const override = getGeneratedSkillSpec(agentData.id, config) || {};
+  const sourceOfTruth = override.sourceOfTruth || `.sinapse-ai/development/agents/${agentData.filename}`;
+  const fallbackSource = override.fallbackSource || (
+    sourceOfTruth === `.sinapse-ai/development/agents/${agentData.filename}`
+      ? `.codex/agents/${agentData.filename}`
+      : null
+  );
+
+  return {
+    skillId: override.skillId || getSkillId(agentData.id),
+    sourceOfTruth,
+    fallbackSource,
+    canonicalReference: override.canonicalReference || null,
+    greetingScript: override.greetingScript || '.sinapse-ai/development/scripts/generate-greeting.js',
+    greetingAgentId: override.greetingAgentId || agentData.id,
+  };
+}
+
+function buildSkillContent(agentData, options = {}) {
+  const config = options.config || loadCodexCatalogConfig(options.projectRoot || process.cwd());
+  const spec = resolveSkillSpec(agentData, config);
   const agent = agentData.agent || {};
   const name = agent.name || agentData.id;
   const title = agent.title || 'SINAPSE Agent';
@@ -57,8 +82,26 @@ function buildSkillContent(agentData) {
     .map(c => `- \`*${c.name}\` - ${c.description || 'No description'}`)
     .join('\n');
 
-  const skillName = getSkillId(agentData.id);
+  const skillName = spec.skillId;
   const description = trimText(`${title} (${name}). ${whenToUse}`, 180);
+  const sourceOfTruthLine = spec.fallbackSource
+    ? `1. Load \`${spec.sourceOfTruth}\` as source of truth (fallback: \`${spec.fallbackSource}\`)`
+    : `1. Load \`${spec.sourceOfTruth}\` as source of truth`;
+  const canonicalReferenceLine = spec.canonicalReference
+    ? `2. Keep \`${spec.canonicalReference}\` as the shared parity reference.`
+    : null;
+  const greetingStepNumber = canonicalReferenceLine ? 3 : 2;
+  const personaStepNumber = canonicalReferenceLine ? 4 : 3;
+  const stayInPersonaStepNumber = canonicalReferenceLine ? 5 : 4;
+
+  const activationLines = [
+    `${sourceOfTruthLine}.`,
+    canonicalReferenceLine,
+    `${greetingStepNumber}. Generate greeting via \`node ${spec.greetingScript} ${spec.greetingAgentId}\` and show it first.`,
+    `${personaStepNumber}. Adopt this agent persona and command system.`,
+    `${stayInPersonaStepNumber}. If a starred command is invoked in Codex, resolve it via \`node .codex/scripts/resolve-codex-command.js ${skillName} <command>\` when a registry mapping exists.`,
+    `${stayInPersonaStepNumber + 1}. Stay in this persona until the user asks to switch or exit.`,
+  ].filter(Boolean);
 
   return `---
 name: ${skillName}
@@ -71,10 +114,7 @@ description: ${description}
 ${whenToUse}
 
 ## Activation Protocol
-1. Load \`.sinapse-ai/development/agents/${agentData.filename}\` as source of truth (fallback: \`.codex/agents/${agentData.filename}\`).
-2. Adopt this agent persona and command system.
-3. Generate greeting via \`node .sinapse-ai/development/scripts/generate-greeting.js ${agentData.id}\` and show it first.
-4. Stay in this persona until the user asks to switch or exit.
+${activationLines.join('\n')}
 
 ## Starter Commands
 ${commands || '- `*help` - List available commands'}
@@ -86,11 +126,13 @@ ${commands || '- `*help` - List available commands'}
 `;
 }
 
-function buildSkillPlan(agents, skillsDir) {
+function buildSkillPlan(agents, skillsDir, options = {}) {
+  const config = options.config || loadCodexCatalogConfig(options.projectRoot || process.cwd());
   return agents
     .filter(a => !a.error || a.error === 'YAML parse failed, using fallback extraction')
     .map(agentData => {
-      const skillId = getSkillId(agentData.id);
+      const spec = resolveSkillSpec(agentData, config);
+      const skillId = spec.skillId;
       const targetDir = path.join(skillsDir, skillId);
       const targetFile = path.join(targetDir, 'SKILL.md');
       return {
@@ -98,7 +140,7 @@ function buildSkillPlan(agents, skillsDir) {
         skillId,
         targetDir,
         targetFile,
-        content: buildSkillContent(agentData),
+        content: buildSkillContent(agentData, { config, projectRoot: options.projectRoot }),
       };
     });
 }
@@ -121,15 +163,22 @@ function syncSkills(options = {}) {
   if (resolved.globalOnly) {
     resolved.global = true;
   }
+  const config = resolved.config || loadCodexCatalogConfig(resolved.projectRoot);
   const agents = parseAllAgents(resolved.sourceDir);
-  const plan = buildSkillPlan(agents, resolved.localSkillsDir);
+  const plan = buildSkillPlan(agents, resolved.localSkillsDir, {
+    config,
+    projectRoot: resolved.projectRoot,
+  });
 
   if (!resolved.globalOnly) {
     writeSkillPlan(plan, resolved);
   }
 
   if (resolved.global) {
-    const globalPlan = buildSkillPlan(agents, resolved.globalSkillsDir);
+    const globalPlan = buildSkillPlan(agents, resolved.globalSkillsDir, {
+      config,
+      projectRoot: resolved.projectRoot,
+    });
     writeSkillPlan(globalPlan, resolved);
   }
 

package/.sinapse-ai/infrastructure/scripts/codex-skills-sync/validate.js

@@ -6,6 +6,11 @@ const path = require('path');
 
 const { parseAllAgents } = require('../ide-sync/agent-parser');
 const { getSkillId } = require('./index');
+const {
+  loadCodexCatalogConfig,
+  getConfiguredSkillIds,
+  validateSkillActivationPaths,
+} = require('../codex-parity/catalog');
 
 function getDefaultOptions() {
   const projectRoot = process.cwd();
@@ -32,30 +37,38 @@ function isParsableAgent(agent) {
   return !agent.error || agent.error === 'YAML parse failed, using fallback extraction';
 }
 
-function validateSkillContent(content, expected) {
+function validateSkillContent(content, expected, config) {
   const issues = [];
   const requiredChecks = [
     { ok: content.includes(`name: ${expected.skillId}`), reason: `missing frontmatter name "${expected.skillId}"` },
-    {
-      ok: content.includes(`.sinapse-ai/development/agents/${expected.filename}`),
-      reason: `missing canonical agent path "${expected.filename}"`,
-    },
-    {
-      ok: content.includes(`generate-greeting.js ${expected.agentId}`),
-      reason: `missing canonical greeting command for "${expected.agentId}"`,
-    },
     {
       ok: content.includes('source of truth'),
       reason: 'missing source-of-truth activation note',
     },
   ];
 
+  if (expected.filename) {
+    requiredChecks.push({
+      ok: content.includes(`.sinapse-ai/development/agents/${expected.filename}`) || content.includes(expected.filename),
+      reason: `missing canonical agent path "${expected.filename}"`,
+    });
+  }
+
+  if (expected.greetingAgentId && content.includes('.sinapse-ai/development/scripts/generate-greeting.js')) {
+    requiredChecks.push({
+      ok: content.includes(`generate-greeting.js ${expected.greetingAgentId}`),
+      reason: `missing canonical greeting command for "${expected.greetingAgentId}"`,
+    });
+  }
+
   for (const check of requiredChecks) {
     if (!check.ok) {
       issues.push(check.reason);
     }
   }
 
+  issues.push(...validateSkillActivationPaths(content, expected.skillId, config));
+
   return issues;
 }
 
@@ -63,18 +76,33 @@ function validateCodexSkills(options = {}) {
   const resolved = { ...getDefaultOptions(), ...options };
   const errors = [];
   const warnings = [];
+  const config = loadCodexCatalogConfig(resolved.projectRoot);
 
   if (!fs.existsSync(resolved.skillsDir)) {
     errors.push(`Skills directory not found: ${resolved.skillsDir}`);
     return { ok: false, checked: 0, expected: 0, errors, warnings, missing: [], orphaned: [] };
   }
 
-  const agents = parseAllAgents(resolved.sourceDir).filter(isParsableAgent);
-  const expected = agents.map(agent => ({
-    agentId: agent.id,
-    filename: agent.filename,
-    skillId: getSkillId(agent.id),
-  }));
+  const configuredSkillIds = getConfiguredSkillIds(config);
+  let expected;
+
+  if (configuredSkillIds) {
+    const canonicalMap = config.canonicalSkillMap || {};
+    expected = configuredSkillIds.map((skillId) => ({
+      skillId,
+      agentId: canonicalMap[skillId]?.agentId || null,
+      greetingAgentId: canonicalMap[skillId]?.greetingAgentId || canonicalMap[skillId]?.agentId || null,
+      filename: canonicalMap[skillId]?.filename || null,
+    }));
+  } else {
+    const agents = parseAllAgents(resolved.sourceDir).filter(isParsableAgent);
+    expected = agents.map(agent => ({
+      agentId: agent.id,
+      greetingAgentId: agent.id,
+      filename: agent.filename,
+      skillId: getSkillId(agent.id),
+    }));
+  }
 
   const missing = [];
   for (const item of expected) {
@@ -92,7 +120,7 @@ function validateCodexSkills(options = {}) {
       errors.push(`${item.skillId}: unable to read skill file (${error.message})`);
       continue;
     }
-    const issues = validateSkillContent(content, item);
+    const issues = validateSkillContent(content, item, config);
     for (const issue of issues) {
       errors.push(`${item.skillId}: ${issue}`);
     }

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

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { syncSkills } = require('./codex-skills-sync/index');
+const { loadCodexCatalogConfig } = require('./codex-parity/catalog');
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  return {
+    dryRun: args.has('--dry-run'),
+    quiet: args.has('--quiet') || args.has('-q'),
+    json: args.has('--json'),
+  };
+}
+
+function countMarkdownFiles(dirPath) {
+  if (!fs.existsSync(dirPath)) return 0;
+  return fs.readdirSync(dirPath).filter((entry) => entry.endsWith('.md')).length;
+}
+
+function countSkillFiles(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return 0;
+  return fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith('sinapse-'))
+    .filter((entry) => fs.existsSync(path.join(skillsDir, entry.name, 'SKILL.md')))
+    .length;
+}
+
+function runLegacyCodexSync(projectRoot, options = {}) {
+  const args = [
+    path.join('.sinapse-ai', 'infrastructure', 'scripts', 'ide-sync', 'index.js'),
+    'sync',
+    '--ide',
+    'codex',
+  ];
+
+  if (options.dryRun) args.push('--dry-run');
+  if (options.quiet) args.push('--quiet');
+
+  const result = spawnSync(process.execPath, args, {
+    cwd: projectRoot,
+    encoding: 'utf8',
+  });
+
+  return {
+    ok: result.status === 0,
+    mode: 'canonical',
+    delegated: true,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    status: result.status || 0,
+  };
+}
+
+function syncCodexLocalFirst(options = {}, deps = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const config = loadCodexCatalogConfig(projectRoot);
+  const runLegacySync = deps.runLegacyCodexSync || runLegacyCodexSync;
+  const runSyncSkills = deps.syncSkills || syncSkills;
+  const errors = [];
+
+  if (config.catalogMode !== 'expanded') {
+    return runLegacySync(projectRoot, options);
+  }
+
+  const agentsDir = path.join(projectRoot, config.codexAgentsDir || '.codex/agents');
+  const skillsDir = path.join(projectRoot, config.skillsDir || '.codex/skills');
+  const sourceDir = path.join(projectRoot, config.canonicalAgentsDir || '.sinapse-ai/development/agents');
+
+  if (!fs.existsSync(agentsDir)) {
+    errors.push(`Missing Codex agents dir: ${path.relative(projectRoot, agentsDir)}`);
+  }
+
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      mode: 'expanded',
+      delegated: false,
+      errors,
+      metrics: {
+        codexAgents: countMarkdownFiles(agentsDir),
+        codexSkills: 0,
+        generatedSkills: 0,
+      },
+    };
+  }
+
+  const syncResult = runSyncSkills({
+    projectRoot,
+    sourceDir,
+    localSkillsDir: skillsDir,
+    dryRun: Boolean(options.dryRun),
+    quiet: true,
+    config,
+  });
+
+  return {
+    ok: true,
+    mode: 'expanded',
+    delegated: false,
+    errors: [],
+    metrics: {
+      codexAgents: countMarkdownFiles(agentsDir),
+      codexSkills: countSkillFiles(skillsDir),
+      generatedSkills: syncResult.generated,
+    },
+  };
+}
+
+function formatHumanReport(result) {
+  if (result.delegated) {
+    return [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+  }
+
+  if (!result.ok) {
+    return [
+      `X Codex local-first sync failed (${result.errors.length} issue(s))`,
+      ...result.errors.map((error) => `- ${error}`),
+    ].join('\n');
+  }
+
+  return `OK Codex local-first sync complete (agents preserved: ${result.metrics.codexAgents}, total skills: ${result.metrics.codexSkills}, skills regenerated: ${result.metrics.generatedSkills})`;
+}
+
+function main() {
+  const args = parseArgs();
+  const result = syncCodexLocalFirst(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,
+  syncCodexLocalFirst,
+  formatHumanReport,
+  runLegacyCodexSync,
+  countMarkdownFiles,
+  countSkillFiles,
+};