sinapse-ai 1.25.0 → 1.25.2

package/scripts/validate-article-vii.js

@@ -5,8 +5,9 @@
  * @story GA-1.5 (Article gates VII/VIII/XI automated)
  *
  * Verifica que TODOS os documentos publicos referem aos MESMOS numeros de
- * squads/agentes/orqx/tasks que `.sinapse-ai/constitution.md` (canonico,
- * gerado por `npm run sync:counts`).
+ * squads/agentes/orqx/tasks medidos pelas fontes canonicas em disco. Contagens
+ * gerais reutilizam `sync-counts`; o detalhamento resolvivel usa o ativador
+ * parametrico do Codex.
  *
  * Documentos verificados:
  *   - README.md
@@ -27,11 +28,14 @@
 
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 
 const { collectCounts } = require('./sync-counts.js');
+const { validateProviderAdapters } = require('./validate-provider-adapters.js');
 
 const ROOT = path.resolve(__dirname, '..');
 const CONSTITUTION = path.join(ROOT, '.sinapse-ai', 'constitution.md');
+const CODEX_RESOLVER = path.join(ROOT, '.codex', 'scripts', 'resolve-codex-agent.js');
 
 /**
  * Count Constitution articles + NON-NEGOTIABLE ones from the canonical source.
@@ -56,37 +60,189 @@ function collectConstitutionCounts() {
 }
 
 const TARGETS = [
-  { file: 'README.md', label: 'README PT' },
-  { file: 'README.en.md', label: 'README EN' },
+  { file: 'README.md', label: 'README PT', requireTaskBreakdown: true },
+  { file: 'README.en.md', label: 'README EN', requireTaskBreakdown: true },
   { file: 'AGENTS.md', label: 'AGENTS guide' },
+  { file: 'docs/getting-started.md', label: 'Getting started' },
+  { file: 'docs/troubleshooting.md', label: 'Troubleshooting' },
+  { file: 'docs/guides/user-guide.md', label: 'User guide EN', requireAgentTotal: true },
+  { file: 'docs/pt/guides/user-guide.md', label: 'User guide PT', requireAgentTotal: true },
+  { file: 'docs/guides/codex-config.md', label: 'Codex configuration guide' },
+  { file: 'docs/guides/ide-integration.md', label: 'IDE integration guide', requireProviderBreakdown: true },
+  { file: 'docs/guides/project-status-feature.md', label: 'Project status guide EN', requireAgentTotal: true },
+  { file: 'docs/pt/guides/project-status-feature.md', label: 'Project status guide PT', requireAgentTotal: true },
+  { file: 'docs/installation/README.md', label: 'Installation index' },
+  { file: 'docs/installation/faq.md', label: 'Installation FAQ' },
+  { file: 'docs/installation/troubleshooting.md', label: 'Installation troubleshooting' },
+  { file: 'docs/installation/v4-quick-start.md', label: 'Installation quick start' },
+  { file: 'docs/pt/installation/README.md', label: 'Installation index PT' },
+  { file: 'docs/pt/installation/faq.md', label: 'Installation FAQ PT' },
+  { file: 'docs/pt/installation/troubleshooting.md', label: 'Installation troubleshooting PT' },
+  { file: 'docs/pt/installation/v4-quick-start.md', label: 'Installation quick start PT' },
   { file: 'package.json', label: 'package.json description', jsonField: 'description' },
   { file: 'packages/installer/src/wizard/feedback.js', label: 'wizard feedback' },
 ];
 
+function collectRuntimeTaskCounts(options = {}) {
+  const execute = options.execFileSync || execFileSync;
+  const resolverPath = options.resolverPath || CODEX_RESOLVER;
+  const timeout = options.timeoutMs ?? 10_000;
+  if (!Number.isInteger(timeout) || timeout <= 0) {
+    throw new Error('parametric resolver timeout must be a positive integer');
+  }
+  let raw;
+  try {
+    raw = execute(process.execPath, [resolverPath, '--stats'], {
+      cwd: ROOT,
+      encoding: 'utf8',
+      timeout,
+    });
+  } catch (error) {
+    throw new Error(`cannot execute the parametric resolver: ${error.message}`);
+  }
+
+  let stats;
+  try {
+    stats = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`parametric resolver returned malformed JSON: ${error.message}`);
+  }
+
+  const fields = {
+    squadTasks: stats.squadTaskFiles,
+    developmentTasks: stats.devTaskFiles,
+    totalTasks: stats.totalTaskFiles,
+    resolvableTasks: stats.resolvableTaskPointers,
+  };
+  for (const [name, value] of Object.entries(fields)) {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error(`parametric resolver field ${name} must be a positive integer`);
+    }
+  }
+  if (fields.totalTasks !== fields.squadTasks + fields.developmentTasks) {
+    throw new Error('parametric resolver totalTaskFiles does not equal squadTaskFiles + devTaskFiles');
+  }
+  if (fields.resolvableTasks > fields.totalTasks) {
+    throw new Error('parametric resolver resolvableTaskPointers exceeds totalTaskFiles');
+  }
+  if (
+    options.expectedSquadTasks !== undefined &&
+    fields.squadTasks !== options.expectedSquadTasks
+  ) {
+    throw new Error(
+      `parametric resolver squadTaskFiles ${fields.squadTasks} does not match ` +
+      `sync-counts tasks ${options.expectedSquadTasks}`,
+    );
+  }
+  return fields;
+}
+
+function countHookRegistrations(settings, label) {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new Error(`${label} hook settings must be an object`);
+  }
+  const hooks = settings.hooks;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) {
+    throw new Error(`${label} hook settings are missing hooks`);
+  }
+  let count = 0;
+  for (const groups of Object.values(hooks)) {
+    if (!Array.isArray(groups)) throw new Error(`${label} hook groups must be arrays`);
+    for (const group of groups) {
+      if (!group || !Array.isArray(group.hooks)) {
+        throw new Error(`${label} hook registration is malformed`);
+      }
+      count += group.hooks.length;
+    }
+  }
+  if (count === 0) throw new Error(`${label} hook settings contain no registrations`);
+  return count;
+}
+
+function collectProviderSurfaceCounts(options = {}) {
+  const validateProviders = options.validateProviderAdapters || validateProviderAdapters;
+  const readJson = options.readJson || ((filePath) => JSON.parse(fs.readFileSync(filePath, 'utf8')));
+  const result = validateProviders(ROOT);
+  if (!result || result.ok !== true || !result.metrics) {
+    const detail = result && Array.isArray(result.errors) ? result.errors.join('; ') : 'invalid result';
+    throw new Error(`provider adapter validation failed: ${detail}`);
+  }
+  const claudeSkills = result.metrics.claudeSkills;
+  const codexSkills = result.metrics.codexSkills;
+  for (const [name, value] of Object.entries({ claudeSkills, codexSkills })) {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error(`provider metric ${name} must be a positive integer`);
+    }
+  }
+  const claudeHooks = countHookRegistrations(
+    readJson(path.join(ROOT, '.claude', 'settings.json')),
+    'Claude',
+  );
+  const codexSettings = readJson(path.join(ROOT, '.codex', 'hooks.json'));
+  if (
+    !codexSettings ||
+    typeof codexSettings !== 'object' ||
+    !codexSettings.hooks ||
+    typeof codexSettings.hooks !== 'object' ||
+    Array.isArray(codexSettings.hooks) ||
+    Object.values(codexSettings.hooks).some((groups) => !Array.isArray(groups))
+  ) {
+    throw new Error('Codex hook settings are malformed');
+  }
+  const codexHookEvents = Object.keys(codexSettings.hooks).length;
+  if (codexHookEvents === 0) {
+    throw new Error('Codex hook settings contain no lifecycle events');
+  }
+  return { claudeSkills, codexSkills, claudeHooks, codexHookEvents };
+}
+
 /**
  * Build the set of expected numeric tokens that MUST appear consistently.
  * Returns an object describing canonical counts and a regex helper.
  */
-function buildExpectations(counts, constitution = { articles: 0, nonNegotiable: 0 }) {
+function buildExpectations(
+  counts,
+  constitution = { articles: 0, nonNegotiable: 0 },
+  runtimeTasks = {},
+  providerSurfaces = {},
+) {
   return {
     squads: counts.squads,
     agents: counts.totalAgents,
     orqx: counts.totalOrqx,
     tasks: counts.tasks,
+    squadTasks: runtimeTasks.squadTasks ?? counts.tasks,
+    developmentTasks: runtimeTasks.developmentTasks ?? 0,
+    totalTasks: runtimeTasks.totalTasks ?? counts.tasks,
+    resolvableTasks: runtimeTasks.resolvableTasks ?? 0,
+    claudeSkills: providerSurfaces.claudeSkills ?? 0,
+    codexSkills: providerSurfaces.codexSkills ?? 0,
+    claudeHooks: providerSurfaces.claudeHooks ?? 0,
+    codexHookEvents: providerSurfaces.codexHookEvents ?? 0,
     articles: constitution.articles,
     nonNegotiable: constitution.nonNegotiable,
   };
 }
 
+function parseMetric(raw) {
+  return parseInt(String(raw).replace(/[.,]/g, ''), 10);
+}
+
+function metricPattern(value) {
+  const digits = String(value);
+  if (digits.length <= 3) return digits;
+  return `${digits}|${digits.slice(0, -3)}[.,]${digits.slice(-3)}`;
+}
+
 /**
  * Extract numeric counts that look like squads/agents/orqx/tasks claims.
  * Returns drift findings (what the doc claims vs what is canonical).
  */
-function findDrift(content, expected) {
+function findDrift(content, expected, options = {}) {
   const findings = [];
 
   // Squads: "<N> squads" or "<N> squad"
-  const squadsRe = /\b(\d{1,4})\s+squads?\b/gi;
+  const squadsRe = /(?<![\d.,])(\d{1,4})\s+squads?\b/gi;
   for (const m of content.matchAll(squadsRe)) {
     const n = parseInt(m[1], 10);
     if (n !== expected.squads && n >= 5) {
@@ -96,7 +252,7 @@ function findDrift(content, expected) {
   }
 
   // Agents/agentes: "<N> agentes" or "<N> agents"
-  const agentsRe = /\b(\d{1,4})\s+(agentes|agents)\b/gi;
+  const agentsRe = /(?<![\d.,])(\d{1,4})\s+(agentes|agents)\b/gi;
   for (const m of content.matchAll(agentsRe)) {
     const n = parseInt(m[1], 10);
     if (n !== expected.agents && n >= 50) {
@@ -104,13 +260,115 @@ function findDrift(content, expected) {
     }
   }
 
-  // Tasks (com ou sem separador de milhar): "1.237 tasks", "1,237 tasks", "1237 tasks"
-  const tasksRe = /\b(\d{1,3}(?:[.,]\d{3})?|\d{4,5})\s+tasks\b/gi;
+  const scopedTaskPatterns = [
+    { kind: 'squad tasks', expected: expected.squadTasks, re: /(?<![\d.,])(\d{1,3}(?:[.,]\d{3})?|\d{4,5})\s+squad\s+tasks\b/gi },
+    { kind: 'development tasks', expected: expected.developmentTasks, re: /(?<![\d.,])(\d{1,3}(?:[.,]\d{3})?|\d{4,5})\s+development\s+tasks\b/gi },
+    { kind: 'total task files', expected: expected.totalTasks, re: /(?<![\d.,])(\d{1,3}(?:[.,]\d{3})?|\d{4,5})\s+task\s+files\b/gi },
+    { kind: 'resolvable task pointers', expected: expected.resolvableTasks, re: /(?<![\d.,])(\d{1,3}(?:[.,]\d{3})?|\d{4,5})\s+(?:ponteiros|pointers)[^.\n]{0,30}resolv/gi },
+  ];
+  for (const metric of scopedTaskPatterns) {
+    if (!metric.expected) continue;
+    for (const m of content.matchAll(metric.re)) {
+      const n = parseMetric(m[1]);
+      if (n !== metric.expected) {
+        findings.push({ kind: metric.kind, found: n, expected: metric.expected, snippet: m[0].trim() });
+      }
+    }
+  }
+
+  // Generic task claims may refer to squad, development, total, or resolvable
+  // files. Scoped phrases above enforce the meaning of each metric.
+  const tasksRe = /(?<![\d.,])(\d{1,3}(?:[.,]\d{3})?|\d{4,5})\s+tasks\b/gi;
+  const acceptedTaskCounts = new Set([
+    expected.squadTasks,
+    expected.developmentTasks,
+    expected.totalTasks,
+    expected.resolvableTasks,
+  ].filter(Boolean));
   for (const m of content.matchAll(tasksRe)) {
-    const raw = m[1].replace(/[.,]/g, '');
-    const n = parseInt(raw, 10);
-    if (n !== expected.tasks && n >= 100) {
-      findings.push({ kind: 'tasks', found: n, expected: expected.tasks, snippet: m[0] });
+    const n = parseMetric(m[1]);
+    if (!acceptedTaskCounts.has(n) && n >= 100) {
+      findings.push({ kind: 'tasks', found: n, expected: expected.totalTasks, snippet: m[0] });
+    }
+  }
+
+  if (options.requireTaskBreakdown) {
+    const required = [
+      ['squad tasks', expected.squadTasks, 'squad\\s+tasks'],
+      ['development tasks', expected.developmentTasks, 'development\\s+tasks'],
+      ['total task files', expected.totalTasks, 'task\\s+files'],
+      ['resolvable task pointers', expected.resolvableTasks, '(?:ponteiros|pointers)[^.\\n]{0,30}resolv'],
+    ];
+    for (const [kind, value, suffix] of required) {
+      if (!value) continue;
+      const re = new RegExp(`\\b(?:${metricPattern(value)})\\s+${suffix}`, 'i');
+      if (!re.test(content)) {
+        findings.push({ kind: `${kind} (missing)`, found: null, expected: value, snippet: 'claim ausente' });
+      }
+    }
+  }
+
+  const skillsClaim = content.match(/(?:Skills\s+instaladas|Installed\s+skills)\s*\|\s*(\d+)\s*\|\s*(\d+)/i);
+  if (skillsClaim) {
+    for (const [kind, found, wanted] of [
+      ['Claude skills', Number(skillsClaim[1]), expected.claudeSkills],
+      ['Codex skills', Number(skillsClaim[2]), expected.codexSkills],
+    ]) {
+      if (wanted && found !== wanted) findings.push({ kind, found, expected: wanted, snippet: skillsClaim[0] });
+    }
+  }
+  const hooksClaim = content.match(/(?:Hooks\s+registrados|Registered\s+hooks)\s*\|\s*(\d+)\s+(?:registros|native\s+registrations)[^|]*\|\s*(\d+)\s+(?:eventos|lifecycle\s+events)/i);
+  if (hooksClaim) {
+    for (const [kind, found, wanted] of [
+      ['Claude hook registrations', Number(hooksClaim[1]), expected.claudeHooks],
+      ['Codex hook events', Number(hooksClaim[2]), expected.codexHookEvents],
+    ]) {
+      if (wanted && found !== wanted) findings.push({ kind, found, expected: wanted, snippet: hooksClaim[0] });
+    }
+  }
+  const hookProseRe = /(?<![\d.,])(\d{1,3})\s+(?:Claude\s+Code\s+hook\s+registrations?|hooks?\s+(?:registrados?|ativos?)|(?:(?:active|registered|enforcement)\s+)(?:(?:Claude(?:\s+Code)?|native(?:\s+Claude(?:\s+Code)?)?)\s+)?hooks|hooks)\b/gi;
+  for (const claim of content.matchAll(hookProseRe)) {
+    const found = Number(claim[1]);
+    if (expected.claudeHooks && found !== expected.claudeHooks) {
+      findings.push({
+        kind: 'Claude hook registrations',
+        found,
+        expected: expected.claudeHooks,
+        snippet: claim[0],
+      });
+    }
+  }
+  const codexLifecycleProseRe = /(?<![\d.,])(\d{1,3})\s+(?:(?:Codex\s+)?lifecycle\s+events?|eventos\s+de\s+lifecycle)\b/gi;
+  for (const claim of content.matchAll(codexLifecycleProseRe)) {
+    const found = Number(claim[1]);
+    if (expected.codexHookEvents && found !== expected.codexHookEvents) {
+      findings.push({
+        kind: 'Codex hook events',
+        found,
+        expected: expected.codexHookEvents,
+        snippet: claim[0],
+      });
+    }
+  }
+  if (options.requireProviderBreakdown) {
+    if (!skillsClaim) findings.push({ kind: 'provider skills (missing)', found: null, expected: `${expected.claudeSkills}/${expected.codexSkills}`, snippet: 'claim ausente' });
+    if (!hooksClaim) findings.push({ kind: 'provider hooks (missing)', found: null, expected: `${expected.claudeHooks}/${expected.codexHookEvents}`, snippet: 'claim ausente' });
+  }
+
+  if (options.requireAgentTotal) {
+    const expectedAgentPattern = metricPattern(expected.agents);
+    const agentClaim = new RegExp(
+      '(?:SINAPSE\\s+(?:includes|inclui)|O\\s+SINAPSE\\s+inclui)[^.\\n]{0,40}' +
+      `\\b(?:${expectedAgentPattern})\\s+(?:specialized\\s+agents|agentes\\s+especializados)`,
+      'i',
+    );
+    if (!agentClaim.test(content)) {
+      findings.push({
+        kind: 'global agent total (missing)',
+        found: null,
+        expected: expected.agents,
+        snippet: 'claim ausente',
+      });
     }
   }
 
@@ -171,14 +429,28 @@ function main() {
 
   const counts = collectCounts();
   const constitution = collectConstitutionCounts();
-  const expected = buildExpectations(counts, constitution);
+  let runtimeTasks;
+  let providerSurfaces;
+  try {
+    runtimeTasks = collectRuntimeTaskCounts({ expectedSquadTasks: counts.tasks });
+    providerSurfaces = collectProviderSurfaceCounts();
+  } catch (error) {
+    console.error(`FALHA - nao foi possivel medir as metricas canonicas: ${error.message}`);
+    process.exit(1);
+  }
+  const expected = buildExpectations(counts, constitution, runtimeTasks, providerSurfaces);
 
   console.log('Article VII (Metrics Accuracy) — validacao de drift');
-  console.log('Numeros canonicos (de .sinapse-ai/constitution.md):');
+  console.log('Numeros canonicos (medidos das fontes em disco):');
   console.log(`  squads          ${expected.squads}`);
   console.log(`  agentes         ${expected.agents}`);
   console.log(`  orqx            ${expected.orqx}`);
-  console.log(`  tasks           ${expected.tasks}`);
+  console.log(`  squad tasks     ${expected.squadTasks}`);
+  console.log(`  dev tasks       ${expected.developmentTasks}`);
+  console.log(`  task files      ${expected.totalTasks}`);
+  console.log(`  resolvable      ${expected.resolvableTasks}`);
+  console.log(`  skills C/Codex  ${expected.claudeSkills}/${expected.codexSkills}`);
+  console.log(`  hooks C/Codex   ${expected.claudeHooks}/${expected.codexHookEvents}`);
   console.log(`  artigos         ${expected.articles}`);
   console.log(`  NON-NEGOTIABLE  ${expected.nonNegotiable}`);
   console.log('');
@@ -191,7 +463,12 @@ function main() {
       console.log(`  [skip] ${target.file} nao encontrado`);
       continue;
     }
-    const drift = findDrift(content, expected);
+    const drift = findDrift(content, expected, {
+      requireTaskBreakdown: target.requireTaskBreakdown === true,
+      requireProviderBreakdown:
+        target.requireTaskBreakdown === true || target.requireProviderBreakdown === true,
+      requireAgentTotal: target.requireAgentTotal === true,
+    });
     if (drift.length === 0) {
       console.log(`  [ok]   ${target.file}`);
     } else {
@@ -214,7 +491,7 @@ function main() {
   console.log('');
   console.log('Acao corretiva (Article VII NON-NEGOTIABLE):');
   console.log('  1. Atualize cada arquivo listado acima com os numeros canonicos.');
-  console.log('  2. Rode `npm run sync:counts` para regenerar a constitution.');
+  console.log('  2. Se o inventario mudou, rode `npm run sync:counts`.');
   console.log('  3. Rode `npm run validate:article-vii` novamente para confirmar.');
 
   if (fixMode) {
@@ -234,4 +511,12 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { findDrift, buildExpectations, collectConstitutionCounts, TARGETS };
+module.exports = {
+  findDrift,
+  buildExpectations,
+  collectConstitutionCounts,
+  collectRuntimeTaskCounts,
+  collectProviderSurfaceCounts,
+  countHookRegistrations,
+  TARGETS,
+};

package/scripts/validate-codex-command-registry.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const legacy = require('../.sinapse-ai/infrastructure/scripts/validate-codex-command-registry');
+
+function resolveRegistryPath(projectRoot, declaredPath) {
+  if (typeof declaredPath !== 'string' || !declaredPath.trim() || path.isAbsolute(declaredPath)) return null;
+  const resolved = path.resolve(projectRoot, declaredPath);
+  const relative = path.relative(path.resolve(projectRoot), resolved);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+  return resolved;
+}
+
+function validateCodexCommandRegistry(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const { registryPath, registry, error } = legacy.loadRegistry(projectRoot);
+  const errors = [];
+  const requiredCoverage = options.requiredCoverage === false
+    ? null
+    : options.requiredCoverage || legacy.REQUIRED_COMMAND_COVERAGE;
+
+  if (error) return { ok: false, errors: [error], 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, '.agents', 'skills', agentSpec.skillId || agentId, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+      errors.push(`${agentId}: missing skill file ${path.relative(projectRoot, skillPath)}`);
+    }
+
+    const sourceOfTruth = resolveRegistryPath(projectRoot, agentSpec.sourceOfTruth);
+    if (!sourceOfTruth) {
+      errors.push(`${agentId}: invalid or missing source of truth`);
+    } else if (!fs.existsSync(sourceOfTruth)) {
+      errors.push(`${agentId}: missing source of truth ${path.relative(projectRoot, sourceOfTruth)}`);
+    }
+
+    for (const alias of legacy.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 = resolveRegistryPath(projectRoot, commandSpec.target);
+      if (!targetPath) {
+        errors.push(`${agentId}.${commandId}: invalid or missing target`);
+      } else if (!fs.existsSync(targetPath)) {
+        errors.push(`${agentId}.${commandId}: missing target ${path.relative(projectRoot, targetPath)}`);
+      }
+      for (const resource of commandSpec.resources || []) {
+        const resourcePath = resolveRegistryPath(projectRoot, resource);
+        if (!resourcePath) {
+          errors.push(`${agentId}.${commandId}: invalid or missing resource`);
+        } else if (!fs.existsSync(resourcePath)) {
+          errors.push(`${agentId}.${commandId}: missing resource ${path.relative(projectRoot, resourcePath)}`);
+        }
+      }
+      for (const alias of legacy.collectCommandAliases(commandId, commandSpec)) {
+        const owner = seenCommandAliases.get(alias);
+        if (owner && owner !== commandId) errors.push(`duplicate command alias "${alias}" claimed by ${owner} and ${commandId}`);
+        else seenCommandAliases.set(alias, commandId);
+      }
+    }
+  }
+
+  legacy.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 main() {
+  const args = legacy.parseArgs();
+  const result = validateCodexCommandRegistry(args);
+  if (!args.quiet) {
+    console.log(args.json ? JSON.stringify(result, null, 2) : legacy.formatHumanReport(result));
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  ...legacy,
+  resolveRegistryPath,
+  validateCodexCommandRegistry,
+};

package/scripts/validate-install-docs.js

@@ -116,6 +116,76 @@ const FORBIDDEN_PATTERNS = [
     reason:
       'Internal script — must be invoked internally by `npx sinapse-ai install`, never shown as a user-facing command.',
   },
+  {
+    id: 'legacy-codex-skills-flow',
+    regex: /(?:(?<![.:\w])codex\b[^\n]{0,80}(?<![A-Za-z0-9._-])\/skills\b|(?<![A-Za-z0-9._-])\/skills\b[^\n]{0,40}(?:flow|activation|ativacao|ativação|activate|ativar|agent))/i,
+    reason: 'Codex activation uses `$snps` or `$sinapse-agent <id>`, not `/skills`.',
+  },
+  {
+    id: 'legacy-custom-agent-slash-command',
+    regex: /\/my-agent\b/,
+    reason: 'Do not document `/my-agent`; use the provider-native SINAPSE activator.',
+  },
+  {
+    id: 'legacy-dev-slash-activation',
+    regex: /(?:^\s*\/dev\s*$|(?:activate|ativar|activation|ativacao|ativação|agent commands?|comandos? de agentes)[^\n]{0,80}\/dev\b)/i,
+    reason: 'Use `@developer` in Claude Code or `$sinapse-agent developer` in Codex.',
+  },
+  {
+    id: 'legacy-dev-at-activation',
+    regex: /(?:^\s*(?:\|\s*)?`?@dev\b|(?:activate|ativar|activation|ativacao|ativação|agent commands?|comandos? de agentes)[^\n]{0,80}@dev\b)/i,
+    reason: 'Use `@developer`; the short `@dev` activation is obsolete.',
+  },
+  {
+    id: 'legacy-codex-at-activation',
+    regex: /codex[^\n]{0,100}(?:activate|ativar|activation|ativacao|ativação|shortcut|atalho|use)[^\n]{0,50}@(?:<[^>]+>|[a-z][\w-]*)/i,
+    reason: 'Codex activation uses `$snps` or `$sinapse-agent <id>`, not `@agent`.',
+  },
+  {
+    id: 'unresolvable-init-project-status',
+    regex: /\*init-project-status\b/i,
+    reason: '`init-project-status` has no public resolvable task pointer; project status loads automatically.',
+  },
+  {
+    id: 'legacy-sinapse-fullstack-name',
+    regex: /\bSINAPSE-FullStack\b/i,
+    reason: 'The current public framework name is SINAPSE AI.',
+  },
+  {
+    id: 'legacy-developer-codename',
+    regex: /(?:\bDex\s*(?:\(|the\s+)Builder\b|\b(?:developer agent|agente desenvolvedor)\s*\(\s*Dex\s*\)|@developer\s*\(\s*Dex\s*\))/i,
+    reason: 'The current developer persona is Pixel the Builder.',
+  },
+  {
+    id: 'unsupported-provider-full-support',
+    regex: /\b(?:Gemini\s+CLI|GitHub\s+Copilot)\b/i,
+    reason: 'Current public installation support is limited to Claude Code and Codex.',
+  },
+  {
+    id: 'unsupported-cursor-provider',
+    regex: /\bCursor\b/i,
+    reason: 'Current public installation support is limited to Claude Code and Codex.',
+  },
+  {
+    id: 'legacy-cursor-install-option',
+    regex: /--ide\s+cursor\b/i,
+    reason: 'The current installer generates Claude Code and Codex adapters; do not document the retired Cursor selector.',
+  },
+  {
+    id: 'legacy-cursor-rules-path',
+    regex: /\.cursor[\\/]rules[\\/]/i,
+    reason: 'Current provider adapter paths are `.claude/agents/`, `.codex/agents/`, and `.agents/skills/`.',
+  },
+  {
+    id: 'claude-commands-as-agent-config',
+    regex: /(?:\.claude[\\/]commands[\\/](?:SINAPSE[\\/]|[^\n]{0,60}(?:agent\s+configuration|configura(?:ç|c)ão\s+de\s+agentes|para\s+Claude\s+Code))|Claude\s+Code\s+(?:uses|usa)[^\n]{0,60}\.claude[\\/]commands[\\/])/i,
+    reason: 'Claude Code agent adapters live in `.claude/agents/`; `.claude/commands/` is not the agent configuration path.',
+  },
+  {
+    id: 'legacy-agent-name-slash-activation',
+    regex: /\/(?:agent-name|nome-do-agente)\b/i,
+    reason: 'Use `@agent-id` in Claude Code or `$sinapse-agent <id>` in Codex.',
+  },
 ];
 
 // ── Paths ────────────────────────────────────────────────────────────────────
@@ -124,7 +194,7 @@ const FORBIDDEN_PATTERNS = [
  * Directories whose `.md` files are public user-facing installation docs.
  * Everything in these trees is scanned.
  */
-const PUBLIC_DOC_DIRS = ['docs/installation'];
+const PUBLIC_DOC_DIRS = ['docs/installation', 'docs/pt/installation'];
 
 /**
  * Additional top-level public doc files (relative to root).
@@ -133,7 +203,18 @@ const PUBLIC_DOC_DIRS = ['docs/installation'];
  * Quick Start commands (including `agents`/`ideate`) and are exactly where
  * the drift was found; bring them under the same guard as README.
  */
-const PUBLIC_DOC_FILES = ['README.md', 'docs/guides/user-guide.md', 'docs/pt/guides/user-guide.md'];
+const PUBLIC_DOC_FILES = [
+  'README.md',
+  'README.en.md',
+  'docs/getting-started.md',
+  'docs/troubleshooting.md',
+  'docs/guides/user-guide.md',
+  'docs/pt/guides/user-guide.md',
+  'docs/guides/codex-config.md',
+  'docs/guides/ide-integration.md',
+  'docs/guides/project-status-feature.md',
+  'docs/pt/guides/project-status-feature.md',
+];
 
 /**
  * Path fragments that identify historical / release notes. Any file whose
@@ -276,7 +357,10 @@ function scanFile(rootDir, relPath) {
     if (allowed.has(i)) continue;
     const line = lines[i];
     for (const rule of FORBIDDEN_PATTERNS) {
-      const match = line.match(rule.regex);
+      const candidate = rule.id === 'legacy-codex-skills-flow'
+        ? line.replace(/https?:\/\/[^\s)>]+/gi, (url) => ' '.repeat(url.length))
+        : line;
+      const match = candidate.match(rule.regex);
       if (match) {
         violations.push({
           file: relPath,