sinapse-ai 1.25.1 → 1.25.3

package/.sinapse-ai/data/entity-registry.yaml

@@ -1,7 +1,7 @@
 metadata:
   version: 1.0.0
-  lastUpdated: '2026-07-15T08:35:27.084Z'
-  entityCount: 817
+  lastUpdated: '2026-07-15T14:30:07.448Z'
+  entityCount: 818
   checksumAlgorithm: sha256
   resolutionRate: 100
 entities:
@@ -166,8 +166,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:1f385982ca84a8232f3f6b1fce4257ca3971a5fd24830b5389477f9a5a8e943a
-      lastVerified: '2026-07-15T08:12:47.676Z'
+      checksum: sha256:86db5a2578b6a0b4849fde4e0f4a197a41560a3a213b247f0edd8522d857ffea
+      lastVerified: '2026-07-15T13:41:11.702Z'
     local:
       path: bin/commands/local.js
       layer: L1
@@ -276,8 +276,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:b51998a172a91e134330847185c078d317ed9be2da6746de3af18d209b7e08d9
-      lastVerified: '2026-07-15T08:12:47.677Z'
+      checksum: sha256:05056e197ecb29e6f63a1d86d9d77d944e3083021bf632b48a76eb4cb2223b95
+      lastVerified: '2026-07-15T13:41:11.703Z'
     command-generator:
       path: bin/lib/command-generator.js
       layer: L1
@@ -299,6 +299,7 @@ entities:
         - constants
         - squads
         - fs-utils
+        - provider-contract
       externalDeps: []
       plannedDeps: []
       lifecycle: production
@@ -306,8 +307,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:ed3f86d0349e4a709240728c0872bf44c3ebb2f1b8f3522c83e2f43c9b8c5647
-      lastVerified: '2026-07-15T02:37:43.455Z'
+      checksum: sha256:837f10f3ce227b1f3ff9b3d4c9e824e8928cd67ec07b0dcebd78e85468eed003
+      lastVerified: '2026-07-15T13:41:11.703Z'
     constants:
       path: bin/lib/constants.js
       layer: L1
@@ -413,7 +414,8 @@ entities:
       usedBy:
         - install
         - update
-      dependencies: []
+      dependencies:
+        - provider-contract
       externalDeps: []
       plannedDeps: []
       lifecycle: production
@@ -421,8 +423,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:d28b19935a9c75408df9da7430fc3ca9568bdea0cfc1ae3c01d0025ad19fc2a3
-      lastVerified: '2026-07-15T07:09:56.286Z'
+      checksum: sha256:898fbe5a00cf1bb77bc8e8a34ee40337145912374a2e809789a02d5345fdd679
+      lastVerified: '2026-07-15T14:30:07.273Z'
     header:
       path: bin/lib/header.js
       layer: L1
@@ -475,6 +477,28 @@ entities:
         extensionPoints: []
       checksum: sha256:dc7cc1109f2bbdb7b3c5927df0de2418925842bdacdc0ba82815bfa2783d0b42
       lastVerified: '2026-06-22T02:41:18.152Z'
+    provider-contract:
+      path: bin/lib/provider-contract.js
+      layer: L1
+      type: script
+      purpose: Entity at bin\lib\provider-contract.js
+      keywords:
+        - provider
+        - contract
+      usedBy:
+        - command-generator
+        - global-provider-adapters
+        - provider-parity
+      dependencies: []
+      externalDeps: []
+      plannedDeps: []
+      lifecycle: production
+      adaptability:
+        score: 0.7
+        constraints: []
+        extensionPoints: []
+      checksum: sha256:a18d271a73b2f371213af4d9503e302e9237920057afd521b723c96efd28fda0
+      lastVerified: '2026-07-15T13:41:11.704Z'
     provider-parity:
       path: bin/lib/provider-parity.js
       layer: L1
@@ -486,7 +510,8 @@ entities:
       usedBy:
         - install
         - update
-      dependencies: []
+      dependencies:
+        - provider-contract
       externalDeps: []
       plannedDeps: []
       lifecycle: production
@@ -494,8 +519,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:592206326a2a3c5a3d89068d9ef065d698562aef40e6096d971fb793cea11c97
-      lastVerified: '2026-07-15T08:35:26.859Z'
+      checksum: sha256:5f0ff4517425fef01683f035afef1d139aede2fe47956773a398e7c761ace42d
+      lastVerified: '2026-07-15T13:41:11.704Z'
     setup-statusline:
       path: bin/lib/setup-statusline.js
       layer: L1

package/.sinapse-ai/install-manifest.yaml

@@ -7,7 +7,7 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 1.25.1
+version: 1.25.3
 generator: scripts/generate-install-manifest.js
 file_count: 1156
 files:
@@ -1368,9 +1368,9 @@ files:
     type: data
     size: 9671
   - path: data/entity-registry.yaml
-    hash: sha256:ed0919b2bc3479beb4e46d3ccfbbbda66e46161c7eebc9018b9f0c8e5278d7f1
+    hash: sha256:08edc9d3cde1bf956cce462004670a3d2924a691a16c27bdfd2bf1ce4de037f8
     type: data
-    size: 559991
+    size: 560701
   - path: data/learned-patterns.yaml
     hash: sha256:1a4cd045c087b9dfd7046ff1464a9d2edb85fba77cf0b6fba14f4bb9004c741e
     type: data

package/CHANGELOG.md

@@ -1,14 +1,8 @@
-## [1.25.1](https://github.com/caioimori/sinapse-ai/compare/1.25.0...1.25.1) (2026-07-15)
+## [1.25.3](https://github.com/caioimori/sinapse-ai/compare/1.25.2...1.25.3) (2026-07-15)
 
 ### Bug Fixes
 
-* **ci:** derive Codex skill count from payload [Story sinapse-only-catalog-cleanup] ([e371a0d](https://github.com/caioimori/sinapse-ai/commit/e371a0ddf9daf944ca803a75dac9807b89d8e257))
-* **installer:** enforce conservative provider ownership [Story sinapse-only-catalog-cleanup] ([1b4f896](https://github.com/caioimori/sinapse-ai/commit/1b4f896d520a02124dc3107c604106f8ba8c8fae))
-* **installer:** harden ownership and hook validation [Story sinapse-only-catalog-cleanup] ([4575a84](https://github.com/caioimori/sinapse-ai/commit/4575a84d6062feb8198e9480f15365e6218b7e61))
-* **installer:** preserve provider-owned state [Story sinapse-only-catalog-cleanup] ([df67e88](https://github.com/caioimori/sinapse-ai/commit/df67e8836e4f2f42a2cb075d6063a01e0b8ad4c6))
-* **installer:** reconcile provider-native catalogs [Story sinapse-only-catalog-cleanup] ([830b36c](https://github.com/caioimori/sinapse-ai/commit/830b36c8108610de2067d09426bfd7e13d315672))
-* **security:** harden managed file reconciliation [Story sinapse-only-catalog-cleanup] ([3899921](https://github.com/caioimori/sinapse-ai/commit/3899921579851a6490e4866e7284ed88afe67c92))
-* **test:** resolve Bash paths across Windows runtimes [Story sinapse-only-catalog-cleanup] ([a788b04](https://github.com/caioimori/sinapse-ai/commit/a788b0434f9718eb74c1caa6dc0ae091ea4dac65))
+* **installer:** restore provider adapter parity ([#385](https://github.com/caioimori/sinapse-ai/issues/385)) ([4c5c9fb](https://github.com/caioimori/sinapse-ai/commit/4c5c9fb1a60e5d8610da08f25f6f01a67a85a063))
 
 # Changelog
 

package/README.en.md

@@ -19,9 +19,9 @@
 
 ## What is SINAPSE?
 
-SINAPSE is an open-source meta-framework that organizes **172 AI agents into 17 specialized squads**, operating directly in the terminal via Claude Code or Codex CLI. Each agent has a defined role, each squad masters a discipline, and the entire system is governed by a **Constitution with real enforcement** -- 17 active hooks that block violations at runtime.
+SINAPSE is an open-source meta-framework that organizes **172 AI agents into 17 specialized squads**, operating directly in the terminal via Claude Code or Codex CLI. Each agent has a defined role, each squad masters a discipline, and the entire system is governed by a **Constitution with real enforcement** -- 20 registered Claude Code hooks and 9 Codex lifecycle events through the compatibility bridge.
 
-The core concept is simple: instead of a single AI assistant trying to do everything, SINAPSE structures work into specialized teams. A branding squad handles visual identity. A cybersecurity squad handles compliance and pentesting. A copywriting squad handles persuasion and conversion. Each with its own knowledge base, workflows, and tasks -- totaling **1,200 executable tasks** ready to use.
+The core concept is simple: instead of a single AI assistant trying to do everything, SINAPSE structures work into specialized teams. A branding squad handles visual identity. A cybersecurity squad handles compliance and pentesting. A copywriting squad handles persuasion and conversion. The runtime measures **1,412 task files**: **1,201 squad tasks** and **211 development tasks**. Of those files, **1,348 pointers are resolvable** by real agents.
 
 Unlike tools that just chat with AI, SINAPSE enforces discipline. The **Documentation-First** pipeline requires a story to be created and validated before any code is written. Quality gates run automatically before merge. Unauthorized agents are blocked from pushing. All via hooks that intercept operations in real time -- not after the fact.
 
@@ -33,7 +33,7 @@ Generative AI has a known problem: the more you ask of it, the worse it gets. A
 
 SINAPSE solves this the way human teams solve it: **coordinated specialization**. Instead of one tired generalist, you have 172 agents in 17 squads, each with a defined role, its own knowledge base, and executable tasks. An orchestrator routes your request to whoever actually knows how to solve it -- automatically, without you needing to memorize agent names or commands.
 
-The differential isn't just the quantity of agents. It's **real governance**: 17 active hooks intercept operations at runtime, a Constitution with 11 articles governs the framework, and 7 of those articles are NON-NEGOTIABLE -- violations are blocked before execution, not detected afterwards. **Speed with rigor, without choosing between the two.**
+The differential isn't just the quantity of agents. It's **real governance**: 20 Claude Code hook registrations and 9 Codex lifecycle events intercept operations at runtime, a Constitution with 11 articles governs the framework, and 7 of those articles are NON-NEGOTIABLE -- violations are blocked before execution, not detected afterwards. **Speed with rigor, without choosing between the two.**
 
 ---
 
@@ -55,9 +55,18 @@ npx sinapse-ai doctor
 
 ### 3. Activate your first agent
 
+Claude Code:
+
+```text
+@developer
+*help
 ```
-@developer          # Activate the development agent
-*help               # List available commands
+
+Codex:
+
+```text
+$snps
+$sinapse-agent developer
 ```
 
 Done. You have 17 squads operating in your terminal.
@@ -174,7 +183,7 @@ Deny rules in `.claude/settings.json` enforce this deterministically. **Framewor
 
 ### Constitution
 
-SINAPSE is governed by a formal Constitution with 11 articles and 17 enforcement hooks:
+SINAPSE is governed by a formal Constitution with 11 articles and provider-specific enforcement surfaces: 20 Claude Code hook registrations and 9 Codex lifecycle events.
 
 | Article | Principle | Severity |
 |---------|-----------|----------|
@@ -213,7 +222,7 @@ SINAPSE includes 12 core agents covering the complete development cycle:
 | `devops` | **Pipeline** | CI/CD, git push (exclusive), releases |
 | `squad-creator` | **Loom** | New squad creation |
 
-Activate any agent with `@agent-name` and use `*help` to see its commands.
+In Claude Code, activate an agent with `@agent-name` and use `*help` to see its commands. In Codex, start with `$snps` for routing or use `$sinapse-agent agent-id` for direct activation.
 
 ### Development Workflow
 
@@ -263,15 +272,19 @@ Each squad is an autonomous team with its own orchestrator, specialist agents, k
 | **squad-growth** | Analytics, CRO, SEO, growth hacking | 7 |
 | **squad-finance** | Budget, pricing, profitability analysis | 8 |
 
-**Total: 17 squads, 172 specialized agents, 1,201 tasks**
+**Total: 17 squads, 172 specialized agents, and 1,412 task files** (**1,201 squad tasks + 211 development tasks; 1,348 resolvable pointers**)
 
-Activate any squad via its orchestrator:
+Activate any squad via its orchestrator using the provider-native syntax:
 
-```
+```text
+# Claude Code
 @brand-orqx         # Brand squad
 @copy-orqx          # Copy squad
-@cyber-orqx         # Cybersecurity squad
-@research-orqx      # Research squad
+
+# Codex
+$sinapse-agent brand-orqx
+$sinapse-agent copy-orqx
+$snps               # Route through the primary orchestrator
 ```
 
 The orchestrator receives your request and automatically delegates to the right specialist within the squad.
@@ -285,27 +298,22 @@ SINAPSE supports two IDEs with deep integrations:
 | IDE | Activation | Highlights |
 |-----|------------|------------|
 | **Claude Code** | `@agent-name` | Hooks, contextual rules, deny/allow, Chrome Brain |
-| **Codex CLI** | `/skills` or `$skill-name` | Native skills, multi-model, `codex exec` for CI/CD |
+| **Codex CLI** | `$snps` or `$sinapse-agent agent-id` | Native skills, multi-model, `codex exec` for CI/CD |
 
 Both IDEs have access to all 17 squads, 172 agents, workflows, and knowledge bases. The installer detects and configures automatically.
 
 ### Parity Table
 
-| Feature | Claude Code | Codex CLI |
-|---------|:-----------:|:---------:|
-| Agent activation (@agent) | Full | Full |
-| Constitutional hooks (20) | Full | Partial (5) |
-| Story-driven development | Full | Full |
-| Quality gates | Full | Full |
-| Delegation enforcement | Full | Partial |
-| Secret scanning | Full | Manual |
-| CodeRabbit integration | Full | N/A |
-| Skills system | Full | Commands |
-| MCP servers | Full | N/A |
-| Terminal Bus | Full | N/A |
-
-**Claude Code** for the most integrated and automated experience.
-**Codex CLI** for model flexibility and CI/CD automation.
+| Measured surface | Claude Code | Codex CLI |
+|------------------|:-----------:|:---------:|
+| Native agents | 172 | 172 |
+| Direct activation | `@agent-name` | `$sinapse-agent agent-id` |
+| Primary routing | `@sinapse-orqx` | `$snps` |
+| Installed skills | 36 | 37 |
+| Registered hooks | 20 native registrations | 9 lifecycle events through the bridge |
+| Validation source | `npm run validate:providers` | `npm run validate:codex-native` |
+
+Both providers resolve the same agents, tasks, workflows, and knowledge bases. Their activation and hook surfaces are different native adapters validated independently by the parity gate.
 
 ---
 
@@ -335,7 +343,7 @@ If you identify with the first group, you're in the right place.
 
 ### Constitutional Enforcement
 
-SINAPSE doesn't just document rules -- it enforces them with **17 active hooks**:
+SINAPSE doesn't just document rules -- Claude Code uses **20 registered hooks**, while Codex exposes **9 lifecycle events** through the compatibility bridge:
 
 - `enforce-git-push-authority.sh` -- blocks push by unauthorized agents
 - `enforce-story-gate.cjs` -- blocks code without a validated story
@@ -400,7 +408,7 @@ npx sinapse-ai doctor --dry-run  # Show what `--fix` would do without applying
 npx sinapse-ai chrome-brain install   # Install browser automation
 ```
 
-All commands are safe to re-run. To list active agents after installing, open Claude Code or Codex CLI and type `@` to autocomplete.
+All commands are safe to re-run. After installing, use `@agent-name` in Claude Code or `$snps` / `$sinapse-agent agent-id` in Codex.
 
 ---
 

package/README.md

@@ -23,7 +23,7 @@
 
 SINAPSE é um meta-framework open source que organiza **172 agentes de IA em 17 squads especializados**, operando direto no terminal via Claude Code ou Codex CLI. Cada agente tem um papel definido, cada squad domina uma disciplina, e o sistema inteiro é governado por uma **Constitution com enforcement real** — 20 hooks registrados que bloqueiam violações em tempo de execução.
 
-O conceito central é simples: em vez de um único assistente de IA tentando fazer tudo, o SINAPSE estrutura o trabalho em equipes especializadas. Um squad de branding cuida da identidade visual. Um squad de cybersecurity cuida de compliance e pentest. Um squad de copywriting cuida de persuasão e conversão. Cada um com sua própria knowledge base, workflows e tasks — totalizando **1.201 tasks executáveis** prontas para uso, distribuídas pelos 17 squads.
+O conceito central é simples: em vez de um único assistente de IA tentando fazer tudo, o SINAPSE estrutura o trabalho em equipes especializadas. Um squad de branding cuida da identidade visual. Um squad de cybersecurity cuida de compliance e pentest. Um squad de copywriting cuida de persuasão e conversão. Cada um com sua própria knowledge base, workflows e tasks. O runtime mede **1.412 task files**: **1.201 squad tasks** nos 17 squads e **211 development tasks**. Desses arquivos, **1.348 são resolvíveis** pelos ponteiros reais dos agentes.
 
 Diferente de ferramentas que apenas conversam com IA, o SINAPSE impõe disciplina. O pipeline **Documentation-First** exige que uma story seja criada e validada antes de qualquer linha de código. Quality gates rodam automaticamente antes de merge. Agentes não autorizados são bloqueados de fazer push. Tudo isso via hooks que interceptam operações em tempo real — não depois.
 
@@ -63,9 +63,18 @@ Se algo estiver fora do lugar, `doctor --fix` corrige automaticamente.
 
 ### 3. Ative seu primeiro agente
 
+Claude Code:
+
+```text
+@developer
+*help
 ```
-@developer          # Ativa o agente de desenvolvimento
-*help               # Lista comandos disponíveis
+
+Codex:
+
+```text
+$snps
+$sinapse-agent developer
 ```
 
 Pronto. Você tem 17 squads operando no seu terminal.
@@ -235,7 +244,7 @@ O SINAPSE inclui 12 agentes core que cobrem o ciclo completo de desenvolvimento:
 | `devops` | **Pipeline** | CI/CD, git push (exclusivo), releases |
 | `squad-creator` | **Loom** | Criação de novos squads |
 
-Ative qualquer agente com `@agent-name` e use `*help` para ver seus comandos.
+No Claude Code, ative um agente com `@agent-name` e use `*help` para ver seus comandos. No Codex, comece com `$snps` para roteamento ou use `$sinapse-agent agent-id` para ativação direta.
 
 ### Workflow de Desenvolvimento
 
@@ -285,15 +294,19 @@ Cada squad é uma equipe autônoma com orquestrador, agentes especialistas, know
 | **squad-growth** | Analytics, CRO, SEO, growth hacking | 7 |
 | **squad-finance** | Budget, pricing, profitability analysis | 8 |
 
-**Total: 17 squads, 172 agentes especializados, 1.201 tasks**
+**Total: 17 squads, 172 agentes especializados e 1.412 task files** (**1.201 squad tasks + 211 development tasks; 1.348 ponteiros resolvíveis**)
 
-Cada squad é ativado via seu orquestrador:
+Cada squad é ativado via seu orquestrador, com a sintaxe nativa do provedor:
 
-```
+```text
+# Claude Code
 @brand-orqx         # Squad de brand
 @copy-orqx          # Squad de copy
-@cyber-orqx         # Squad de cybersecurity
-@research-orqx      # Squad de research
+
+# Codex
+$sinapse-agent brand-orqx
+$sinapse-agent copy-orqx
+$snps               # Roteamento pelo orquestrador principal
 ```
 
 O orquestrador recebe seu pedido e delega automaticamente ao especialista correto dentro do squad.
@@ -306,28 +319,23 @@ O SINAPSE suporta duas IDEs com integrações profundas:
 
 | IDE | Ativação | Destaques |
 |-----|----------|-----------|
-| **Claude Code** | `@agent-name` ou `/skill-name` | Subagentes e skills nativos, hooks e rules contextuais |
+| **Claude Code** | `@agent-name` | Subagentes e skills nativos, hooks e rules contextuais |
 | **Codex CLI** | `$snps` ou `$sinapse-agent agent-id` | Agentes TOML, skills nativas e `codex exec` para CI/CD |
 
 Ambas as IDEs têm acesso a todos os 17 squads, 172 agentes, workflows e knowledge bases. O installer detecta e configura automaticamente.
 
 ### Tabela de Paridade
 
-| Funcionalidade | Claude Code | Codex CLI |
-|---------------|:-----------:|:---------:|
-| Ativação dos 172 agentes | `@agent-name` | `$sinapse-agent agent-id` |
-| Hooks constitucionais (20) | Completo | Parcial (5) |
-| Story-driven development | Completo | Completo |
-| Quality gates | Completo | Completo |
-| Enforcement de delegação | Completo | Parcial |
-| Secret scanning | Completo | Manual |
-| Integração CodeRabbit | Completo | N/A |
-| Sistema de skills | Completo | Comandos |
-| MCP servers | Completo | N/A |
-| Terminal Bus | Completo | N/A |
-
-**Claude Code** para a experiência mais integrada e automatizada.
-**Codex CLI** para flexibilidade de modelo e automação CI/CD.
+| Superfície medida | Claude Code | Codex CLI |
+|-------------------|:-----------:|:---------:|
+| Agentes nativos | 172 | 172 |
+| Ativação direta | `@agent-name` | `$sinapse-agent agent-id` |
+| Roteamento principal | `@sinapse-orqx` | `$snps` |
+| Skills instaladas | 36 | 37 |
+| Hooks registrados | 20 registros nativos | 9 eventos de lifecycle via bridge |
+| Fonte de validação | `npm run validate:providers` | `npm run validate:codex-native` |
+
+Os dois providers resolvem os mesmos agents, tasks, workflows e knowledge bases. As superfícies de ativação e hooks são adapters nativos diferentes e são validadas separadamente pelo gate de paridade.
 
 ---
 

package/bin/commands/install.js

@@ -560,7 +560,7 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
   // Phase 2: Generate agent commands (shared with `update` via command-generator).
   logger.always(`\n${CYAN}Phase 2:${NC} Generating agent commands`);
   const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
-  const { writtenAgents, totalAgents } = regenerateAgentCommands({
+  const { writtenAgents, canonicalAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
     commandsDir: commandStagingDir,
     squads,
@@ -571,7 +571,11 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
 
   // Phase 2b: Install global agents based on LLM choice
   const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
-  const activeAgentCount = assertProviderAdapterParity(llmChoice, globalAdapters, totalAgents);
+  const activeAgentCount = assertProviderAdapterParity(
+    llmChoice,
+    globalAdapters,
+    canonicalAgents,
+  );
   const installedAgentFilenames = new Set([...globalAdapters.claude, ...globalAdapters.codex]);
   const installedIdes = [];
   if (globalAdapters.claude.length) installedIdes.push('claude-code');

package/bin/commands/update.js

@@ -170,7 +170,7 @@ async function cmdUpdateGlobal() {
   logger.always(`\n${CYAN}Phase 2:${NC} Regenerating commands`);
   const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
   rmDirSync(commandStagingDir);
-  const { writtenAgents, totalAgents } = regenerateAgentCommands({
+  const { writtenAgents, canonicalAgents, totalAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
     commandsDir: commandStagingDir,
     squads,
@@ -181,7 +181,11 @@ async function cmdUpdateGlobal() {
 
   // Phase 2b: Install global agents based on LLM choice
   const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
-  const activeAgentCount = assertProviderAdapterParity(llmChoice, globalAdapters, totalAgents);
+  const activeAgentCount = assertProviderAdapterParity(
+    llmChoice,
+    globalAdapters,
+    canonicalAgents,
+  );
   if (globalAdapters.claude.length) logger.always(`  ${GREEN}OK${NC} Claude Code global agents (${globalAdapters.claude.length})`);
   if (globalAdapters.codex.length) logger.always(`  ${GREEN}OK${NC} Codex global agents (${globalAdapters.codex.length} TOML, ${globalAdapters.skills.length} skills)`);
 

package/bin/lib/command-generator.js

@@ -20,6 +20,7 @@ const { toForwardSlash, atomicWriteFileSync } = require('./fs-utils');
 // sync-counts uses so the master-stub headline can never drift from README/persona
 // (Constitution Article VII). Fails open to 0 if the dir is unavailable.
 const CORE_AGENTS_DIR = path.join(ROOT, '.sinapse-ai', 'development', 'agents');
+const { MASTER_ALIAS_ENTRY_POINTS } = require('./provider-contract');
 
 function countCoreAgents(dir = CORE_AGENTS_DIR) {
   try {
@@ -207,7 +208,7 @@ If the task requires expertise outside this squad:
  * @param {string} [deps.commandsDir] - Target commands dir.
  * @param {Array}  deps.squads - Squad descriptors ({ name, agents, ... }).
  * @param {string} [deps.sinapseMasterDest] - Path to the installed sinapse/ master squad.
- * @returns {{ writtenAgents: Set<string>, totalAgents: number }}
+ * @returns {{ writtenAgents: Set<string>, canonicalAgents: Array<{ id: string, file: string, origin: string }>, aliasEntryPoints: string[], totalAgents: number }}
  */
 function regenerateAgentCommands(deps = {}) {
   const {
@@ -222,20 +223,21 @@ function regenerateAgentCommands(deps = {}) {
     throw new Error('regenerateAgentCommands: `squads` array is required');
   }
 
-  fs.mkdirSync(commandsDir, { recursive: true });
-
-  // Clear old commands (dir may not exist on a fresh install — guarded).
-  try {
-    for (const f of fs.readdirSync(commandsDir)) {
-      fs.unlinkSync(path.join(commandsDir, f));
-    }
-  } catch { /* dir may not exist yet */ }
-
   const sinapseBase = toForwardSlash(sinapseHome);
   const writtenAgents = new Set();
+  const catalogById = new Map();
+  const definitions = [];
+
+  function registerDefinition(definition) {
+    const previous = catalogById.get(definition.id);
+    if (previous) {
+      throw new Error(`Duplicate canonical agent ID "${definition.id}" from ${previous.origin} and ${definition.origin}`);
+    }
+    catalogById.set(definition.id, definition);
+    definitions.push(definition);
+  }
 
-  // 1. A command/subagent for EVERY agent (not only -orqx), so every specialist
-  //    is invokable via @agent and /SINAPSE:agents:agent.
+  // Inventory every canonical definition before clearing or writing commands.
   for (const squad of squads) {
     const squadPath = `${sinapseBase}/${squad.name}`;
     const agentsDir = path.join(sinapseHome, squad.name, 'agents');
@@ -244,10 +246,14 @@ function regenerateAgentCommands(deps = {}) {
     const squadAgents = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
     for (const file of squadAgents) {
       const agentId = file.replace('.md', '');
-      const meta = extractAgentMeta(path.join(agentsDir, file));
-      const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, squad.name, squadPath, file);
-      atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
-      writtenAgents.add(file);
+      registerDefinition({
+        id: agentId,
+        file,
+        origin: path.join(agentsDir, file),
+        squadName: squad.name,
+        squadPath,
+        hasManifest: true,
+      });
     }
   }
 
@@ -257,29 +263,37 @@ function regenerateAgentCommands(deps = {}) {
   if (fs.existsSync(coreAgentsDir)) {
     const coreBase = toForwardSlash(coreDevelopmentDest);
     for (const file of fs.readdirSync(coreAgentsDir).filter(f => f.endsWith('.md'))) {
-      if (file === 'README.md' || file === 'MEMORY.md' || file.startsWith('_') || writtenAgents.has(file)) continue;
+      if (file === 'README.md' || file === 'MEMORY.md' || file.startsWith('_')) continue;
       const agentId = file.replace('.md', '');
-      const meta = extractAgentMeta(path.join(coreAgentsDir, file));
-      const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, 'core', coreBase, file, { hasManifest: false });
-      atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
-      writtenAgents.add(file);
+      registerDefinition({
+        id: agentId,
+        file,
+        origin: path.join(coreAgentsDir, file),
+        squadName: 'core',
+        squadPath: coreBase,
+        hasManifest: false,
+      });
     }
   }
 
-  // 2. Commands for sinapse/ master squad agents.
-  if (fs.existsSync(sinapseMasterDest)) {
-    const masterAgentsDir = path.join(sinapseMasterDest, 'agents');
-    if (fs.existsSync(masterAgentsDir)) {
-      for (const file of fs.readdirSync(masterAgentsDir).filter(f => f.endsWith('.md'))) {
-        if (writtenAgents.has(file)) continue;
-        const agentId = file.replace('.md', '');
-        const meta = extractAgentMeta(path.join(masterAgentsDir, file));
-        const squadPath = `${sinapseBase}/sinapse`;
-        const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, 'sinapse', squadPath, file);
-        atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
-        writtenAgents.add(file);
-      }
-    }
+  fs.mkdirSync(commandsDir, { recursive: true });
+  for (const file of fs.readdirSync(commandsDir)) {
+    fs.unlinkSync(path.join(commandsDir, file));
+  }
+
+  for (const definition of definitions) {
+    const meta = extractAgentMeta(definition.origin);
+    const cmdContent = generateCommandMd(
+      definition.id,
+      meta.name,
+      meta.icon,
+      definition.squadName,
+      definition.squadPath,
+      definition.file,
+      { hasManifest: definition.hasManifest },
+    );
+    atomicWriteFileSync(path.join(commandsDir, definition.file), cmdContent);
+    writtenAgents.add(definition.file);
   }
 
   // 3. Master entry points (@sinapse, @snps, @sinapse-orqx, @snps-orqx) → rich
@@ -301,7 +315,16 @@ function regenerateAgentCommands(deps = {}) {
     }
   }
 
-  return { writtenAgents, totalAgents: writtenAgents.size };
+  const aliasEntryPoints = [...MASTER_ALIAS_ENTRY_POINTS]
+    .filter((id) => writtenAgents.has(`${id}.md`));
+  const canonicalAgents = definitions.map(({ id, file, origin }) => ({ id, file, origin }));
+
+  return {
+    writtenAgents,
+    canonicalAgents,
+    aliasEntryPoints,
+    totalAgents: canonicalAgents.length,
+  };
 }
 
 module.exports = {
@@ -309,4 +332,5 @@ module.exports = {
   generateMasterStub,
   regenerateAgentCommands,
   countCoreAgents,
+  MASTER_ALIAS_ENTRY_POINTS,
 };