sinapse-ai 1.9.0 → 1.10.0

package/README.en.md

@@ -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**: 19 active hooks intercept operations at runtime, a Constitution with 10 articles governs the framework, and 6 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**: 19 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.**
 
 ---
 
@@ -174,7 +174,7 @@ Deny rules in `.claude/settings.json` enforce this deterministically. **Framewor
 
 ### Constitution
 
-SINAPSE is governed by a formal Constitution with 10 articles and 19 enforcement hooks:
+SINAPSE is governed by a formal Constitution with 11 articles and 19 enforcement hooks:
 
 | Article | Principle | Severity |
 |---------|-----------|----------|
@@ -188,8 +188,9 @@ SINAPSE is governed by a formal Constitution with 10 articles and 19 enforcement
 | VIII | Mandatory Delegation | NON-NEGOTIABLE |
 | IX | Safe Collaboration | NON-NEGOTIABLE |
 | X | Security & Data Protection | NON-NEGOTIABLE |
+| XI | Conservative Default | MUST |
 
-6 articles are NON-NEGOTIABLE -- violations are automatically blocked before execution.
+7 articles are NON-NEGOTIABLE -- violations are automatically blocked before execution.
 
 ---
 

package/README.md

@@ -3,7 +3,7 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
 [![CI](https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml)
 [![Tests](https://img.shields.io/badge/tests-11014%20passed-success)](https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml)
-[![Constitution](https://img.shields.io/badge/Constitution-10%20articles-blueviolet)](.sinapse-ai/constitution.md)
+[![Constitution](https://img.shields.io/badge/Constitution-11%20articles-blueviolet)](.sinapse-ai/constitution.md)
 
 ```
  ____  ___ _   _    _    ____  ____  _____
@@ -35,7 +35,7 @@ IA generativa tem um problema conhecido: quanto mais voce pede, pior fica. Um un
 
 SINAPSE resolve isso do jeito que times humanos resolvem: **especializacao coordenada**. Em vez de um generalista cansado, voce tem 172 agentes em 17 squads, cada um com papel definido, knowledge base propria e tasks executaveis. Um orquestrador roteia seu pedido para quem realmente sabe resolver — automaticamente, sem voce precisar decorar agent names ou comandos.
 
-O diferencial nao e apenas quantidade de agentes. E **governanca real**: 13 hooks ativos interceptam operacoes em tempo de execucao, uma Constitution com 10 artigos rege o framework, e 6 desses artigos sao NON-NEGOTIABLE — violacoes sao bloqueadas antes de executar, nao detectadas depois. **Velocidade com rigor, sem escolher entre os dois.**
+O diferencial nao e apenas quantidade de agentes. E **governanca real**: 13 hooks ativos interceptam operacoes em tempo de execucao, uma Constitution com 11 artigos rege o framework, e 7 desses artigos sao NON-NEGOTIABLE — violacoes sao bloqueadas antes de executar, nao detectadas depois. **Velocidade com rigor, sem escolher entre os dois.**
 
 ---
 
@@ -137,8 +137,6 @@ Cada release passa por uma matriz de instalacao de 27 combinacoes (3 OSes x 3 pa
 
 **Sobre Yarn v1 no Windows:** Yarn v1 (Classic) esta em modo manutencao desde 2020, com Yarn v2+ (Berry) como sucessor oficial. A combinacao Windows + Yarn v1 apresenta falhas de resolucao de wrapper que nao compensam investigar por ser ecossistema em declinio. Usuarios Windows em Yarn v1 devem migrar para Yarn v2+ (recomendado) ou usar npm/pnpm. macOS e Linux em Yarn v1 continuam suportados.
 
-Registro completo da decisao e resultados: [docs/audits/install-matrix-2026-04-16.md](docs/audits/install-matrix-2026-04-16.md).
-
 ### "Como atualizar sem perder minhas customizacoes?"
 
 ```bash
@@ -215,7 +213,7 @@ Deny rules em `.claude/settings.json` reforcam isso deterministicamente. **Updat
 
 ### Constitution
 
-O SINAPSE e governado por uma Constitution formal com 10 artigos e 13 hooks de enforcement:
+O SINAPSE e governado por uma Constitution formal com 11 artigos e 13 hooks de enforcement:
 
 | Artigo | Principio | Severidade |
 |--------|-----------|------------|
@@ -229,8 +227,9 @@ O SINAPSE e governado por uma Constitution formal com 10 artigos e 13 hooks de e
 | VIII | Mandatory Delegation | NON-NEGOTIABLE |
 | IX | Safe Collaboration | NON-NEGOTIABLE |
 | X | Security & Data Protection | NON-NEGOTIABLE |
+| XI | Conservative Default | MUST |
 
-6 artigos sao NON-NEGOTIABLE — violacoes sao bloqueadas automaticamente antes de executar.
+7 artigos sao NON-NEGOTIABLE — violacoes sao bloqueadas automaticamente antes de executar.
 
 ---
 

package/bin/commands/install.js

@@ -1,7 +1,7 @@
 // bin/commands/install.js — `sinapse-ai install` (global) command + helpers.
 // Story GA-1.2 — extracted from bin/cli.js.
 
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const { getLogger } = require('../../.sinapse-ai/core/logger');
@@ -893,11 +893,14 @@ function ensurePathWindows() {
       return;
     }
 
-    execSync(`setx PATH "${newPath}"`, { encoding: 'utf8', stdio: 'pipe' });
+    // execFileSync (no shell) — never interpolate the current PATH into a
+    // shell command string. A PATH value containing `"`/`&`/`^` would break
+    // the command or allow injection; passing args as an array avoids it.
+    execFileSync('setx', ['PATH', newPath], { encoding: 'utf8', stdio: 'pipe' });
     logger.always(`  ${GREEN}OK${NC} Added ~/bin to Windows User PATH`);
   } catch {
     try {
-      execSync(`setx PATH "%USERPROFILE%\\bin"`, { encoding: 'utf8', stdio: 'pipe' });
+      execFileSync('setx', ['PATH', '%USERPROFILE%\\bin'], { encoding: 'utf8', stdio: 'pipe' });
       logger.always(`  ${GREEN}OK${NC} Created Windows User PATH with ~/bin`);
     } catch {
       logger.always(`  ${YELLOW}WARN${NC} Could not modify PATH. Add manually: ${BIN_DIR}`);

package/bin/commands/uninstall.js

@@ -51,8 +51,8 @@ async function removeGitHooksConfig(projectDir = process.cwd()) {
 // Story 10.40 — Remove SINAPSE-authored orqx agents from a global agents dir.
 // Returns { removed: N } for reporting. Only touches files matching *-orqx.md
 // so we don't accidentally remove user-authored agents.
-// Audit 1 P0 (UN-1) — install writes ~200 agent files to ~/.claude/agents/ +
-// ~/.codex/agents/ but uninstall historically removed only `*-orqx.md` (~21
+// Audit 1 P0 (UN-1) — install writes ~170 agent files to ~/.claude/agents/ +
+// ~/.codex/agents/ but uninstall historically removed only `*-orqx.md` (~18
 // files). Files were left orphaned. Fix: install records every authored
 // filename in ~/.sinapse/installed-agents.json; uninstall reads that manifest
 // and removes only those files (preserving anything the user added by hand).

package/bin/sinapse.js

@@ -73,6 +73,7 @@ USAGE:
   sinapse install                     # Install SINAPSE in current project
   sinapse init <name>                 # Create new project
   sinapse update                      # Update to latest version
+  sinapse uninstall                   # Remove SINAPSE from the project (--keep-data)
   sinapse brand                       # Re-apply SINAPSE branding (after Claude update)
   sinapse validate                    # Validate installation integrity
   sinapse info                        # Show system info
@@ -119,6 +120,25 @@ SERVICE DISCOVERY:
   sinapse workers search "transform" --tags=etl,data
   sinapse workers search "api" --format=json
 
+GENERATE & CREATE:
+  sinapse generate <prd|adr|story|epic|task>  # Generate a document from a template
+  sinapse create <agent|task|workflow>        # Scaffold a new framework component
+
+ORCHESTRATION:
+  sinapse orchestrate <story-id>            # Run the autonomous dev pipeline for a story
+  sinapse orchestrate --status              # Show / --stop / --resume a running pipeline
+  sinapse mode [explore|ask|auto]           # Show or set the agent permission mode (--cycle)
+
+INTELLIGENCE & HEALTH:
+  sinapse health                            # Framework health analytics (--deep for full scan)
+  sinapse graph --deps                      # Dependency & stats dashboard (--format, --watch)
+  sinapse performance                       # Squad & agent performance ranking (--top N)
+  sinapse routing-intel analyze             # Routing intelligence analysis
+
+INTEGRATIONS & LICENSE:
+  sinapse mcp setup                         # Configure global MCP servers (setup/link/status/add)
+  sinapse pro status                        # SINAPSE Pro license (activate/status/deactivate/features)
+
 EXAMPLES:
   # Install in current directory
   npx sinapse-ai@latest

package/bin/utils/secret-scanner-core.js

@@ -72,6 +72,17 @@ const NAMED_PATTERNS = [
   { name: 'Hardcoded Password', pattern: /(?:password|passwd|pwd)\s*[=:]\s*['"][^'"]{8,}['"]/i, lowConfidence: true },
   { name: 'Bearer Token', pattern: /[Bb]earer\s+[A-Za-z0-9_\-.]{20,}/, entropyGated: true, lowConfidence: true },
   { name: 'Basic Auth', pattern: /[Bb]asic\s+[A-Za-z0-9+/=]{20,}/, lowConfidence: true },
+
+  // Long pure-hex runs (32–64 chars). The 16-symbol hex alphabet caps Shannon
+  // entropy at ~4.0, BELOW ENTROPY_THRESHOLD (4.5), so the generic entropy
+  // backstop never sees them — Twilio auth tokens (32-hex), webhook signing
+  // secrets and SHA-style 64-hex digests slip through. This explicit rule closes
+  // that gap. It is `hashContextGated`: a hex run sitting in an integrity /
+  // checksum / lockfile / git-sha context (covered by HASH_CONTEXT_PATTERN) is a
+  // legitimate hash, NOT a secret, and is allowlisted. `lowConfidence` keeps it
+  // OUT of the release publish gate (entropy:false there would otherwise match
+  // every documented digest); the diff-scoped commit hook still enforces it.
+  { name: 'Long Hex Token', pattern: /\b[a-f0-9]{32,64}\b/i, hashContextGated: true, lowConfidence: true },
 ];
 
 const PLACEHOLDER_TOKENS = [
@@ -100,19 +111,48 @@ const PLACEHOLDER_PATTERNS = [
 
 const EXAMPLE_HOST_PATTERN = /(?:example\.(?:com|org|net)|localhost|127\.0\.0\.1|host\b|your-host|placeholder)/i;
 
+// A keyword placeholder only allowlists when it DOMINATES the value: once every
+// placeholder occurrence is removed, the TOTAL alphanumeric length that remains
+// is too short to be a secret on its own (< ENTROPY_MIN_LEN). A bare
+// `lower.includes(token)` was a trivial bypass — ANY real secret that happened to
+// contain "abcdef" / "123456" / "example" anywhere in its body got silently
+// allowlisted (e.g. Xq9Zk2…abcdef…Fg5 passed). Measuring the *total* remainder
+// (not just the longest contiguous run) closes that hole even when the buried
+// placeholder splits the secret into two sub-threshold runs: the legitimate
+// cases (your-key-here, placeholder123456, test-key-example, CHANGEME) strip down
+// to nothing, while a 35-char random token minus a 6-char placeholder still has
+// ~29 alphanumeric chars left and is NOT allowlisted.
+function placeholderDominates(lower) {
+  let stripped = lower;
+  let matchedAny = false;
+  for (const token of PLACEHOLDER_TOKENS) {
+    if (stripped.includes(token)) {
+      matchedAny = true;
+      // Replace with a separator so adjacent runs aren't fused into a longer one.
+      stripped = stripped.split(token).join(' ');
+    }
+  }
+  if (!matchedAny) return false;
+  // Total alphanumeric chars left after removing every placeholder occurrence.
+  const remaining = (stripped.match(/[a-z0-9]/g) || []).length;
+  return remaining < ENTROPY_MIN_LEN;
+}
+
 function isAllowlistPlaceholder(value) {
   if (value === null || value === undefined) return false;
   const v = String(value).trim();
   if (v.length === 0) return true;
 
-  const lower = v.toLowerCase();
-  for (const token of PLACEHOLDER_TOKENS) {
-    if (lower.includes(token)) return true;
-  }
+  // Structural placeholders are always safe: <...>, [...], {token}, ${VAR},
+  // SCREAMING_SNAKE env-var names, and repeated single-symbol fillers.
   for (const re of PLACEHOLDER_PATTERNS) {
     if (re.test(v)) return true;
   }
   if (/^(.)\1{5,}$/.test(v)) return true; // repeated single char
+
+  // Keyword placeholders: word-boundary anchored + dominance, NOT raw includes().
+  if (placeholderDominates(v.toLowerCase())) return true;
+
   return false;
 }
 
@@ -204,6 +244,38 @@ function scanContent(content, options = {}) {
       if (shannonEntropy(tail) < 2.0) continue; // clearly non-random
     }
 
+    if (descriptor.hashContextGated) {
+      // Long hex runs are flagged as suspected secrets (Twilio token, webhook
+      // signing secret, SHA-style digest) EXCEPT when they sit in an integrity /
+      // checksum / lockfile / git-sha context — those are legitimate hashes, not
+      // leaked credentials. Reuse HASH_CONTEXT_PATTERN over a window around the
+      // match so package-lock integrity:, "resolved" tarball #sha, "checksum",
+      // and 40/64-hex git shas are NOT false-positived. A fully repeated/obvious
+      // placeholder hex (deadbeef…, 000…) is also allowlisted.
+      if (isAllowlistPlaceholder(matched)) continue;
+      if (isLockfilePath(filePath)) continue;
+      // Canonical digest lengths — git SHA-1 (40) and SHA-256 (64) — are
+      // overwhelmingly legitimate hashes (commit refs, file checksums, content
+      // digests) and appear bare in changelogs/docs/lockfiles. Treating every
+      // isolated 40/64-hex run as a leak would false-positive on the entire git
+      // ecosystem, so these exact lengths are hash-shaped by default. The
+      // headline real-secret case (Twilio auth token = 32-hex) and other
+      // non-digest lengths (33–39, 41–63) are NOT standard digests and stay
+      // flagged. A leaked literal hash secret of EXACTLY 40/64 hex is the
+      // accepted blind spot of this length-based heuristic (documented tradeoff
+      // favouring zero false-positives on git/checksum hashes).
+      const hexLen = matched.length;
+      if (hexLen === 40 || hexLen === 64) continue;
+      // For non-canonical lengths, allowlist only when the SURROUNDING context
+      // carries a hash marker (integrity:, sha256-, "resolved", "checksum"). The
+      // window is widened on the left so a marker earlier on the line
+      // (e.g. `"resolved": "https://…/x.tgz#<hex>"`) is still seen.
+      const mIdx = text.indexOf(matched);
+      const before = text.slice(Math.max(0, mIdx - 64), mIdx);
+      const after = text.slice(mIdx + matched.length, mIdx + matched.length + 4);
+      if (HASH_CONTEXT_PATTERN.test(before + ' ' + after)) continue;
+    }
+
     findings.push({ name: descriptor.name, redacted: redactMatch(matched), kind: 'pattern' });
   }
 

package/docs/agent-reference-guide.md

@@ -53,7 +53,7 @@ Localização: `.sinapse-ai/development/agents/`
 | squad-courses | `@courses-orqx` | Cursos, mentorias, lançamento |
 | squad-storytelling | `@storytelling-orqx` | Pitch, narrativa |
 | squad-council | `@council-orqx` | Conselho estratégico (mental models) |
-| claude-code-mastery | `@claude-orqx` | Claude Code mastery (hooks, MCP, skills) |
+| claude-code-mastery | `@swarm-orqx` | Claude Code mastery (hooks, MCP, skills) |
 
 ## Como descobrir agentes de um squad
 

package/docs/framework/architecture-overview.md

@@ -27,13 +27,13 @@
 |  +------------------------------------------------------------+  |
 |  |                    Agent Ecosystem                          |  |
 |  |                                                              |  |
-|  |  Core (12 agentes)          Squads (18 dominios)            |  |
+|  |  Core (12 agentes)          Squads (17 dominios)            |  |
 |  |  +--------+  +--------+    +--------+  +--------+          |  |
 |  |  | Pixel  |  | Litmus |    | Brand  |  | Growth |  ...     |  |
 |  |  | (dev)  |  | (qa)   |    | Squad  |  | Squad  |          |  |
 |  |  +--------+  +--------+    +--------+  +--------+          |  |
-|  |  +--------+  +--------+    163 especialistas               |  |
-|  |  |Stratum |  |Pipeline|    em 18 squads tematicos           |  |
+|  |  +--------+  +--------+    160 especialistas               |  |
+|  |  |Stratum |  |Pipeline|    em 17 squads tematicos           |  |
 |  |  | (arch) |  |(devops)|                                     |  |
 |  |  +--------+  +--------+                                     |  |
 |  +------------------------------------------------------------+  |
@@ -54,7 +54,7 @@
 Agentes sao personas especializadas com expertise, comandos e responsabilidades definidas. Cada agente opera dentro de um escopo de autoridade exclusivo.
 
 - **12 agentes core** cobrem o ciclo completo de desenvolvimento de software
-- **163 agentes em 18 squads** expandem para dominios especializados
+- **160 agentes em 17 squads** expandem para dominios especializados
 - Cada agente tem persona (nome, estilo), comandos (`*help`, `*task`) e dependencias
 
 Ativacao: `@agent-name` ou `/SINAPSE:agents:agent-name`

package/docs/framework/guiding-principles.md

@@ -22,9 +22,9 @@ Essa decisao nao e estetica --- e estrutural. Agentes de IA operam em terminais.
 
 **Por que artigos formais com enforcement automatico?**
 
-O SINAPSE possui 10 artigos constitucionais que governam o comportamento de todos os 186 agentes. Cada artigo tem severidade definida (NON-NEGOTIABLE ou MUST) e gates automaticos que bloqueiam violacoes deterministicamente.
+O SINAPSE possui 10 artigos constitucionais que governam o comportamento de todos os 172 agentes. Cada artigo tem severidade definida (NON-NEGOTIABLE ou MUST) e gates automaticos que bloqueiam violacoes deterministicamente.
 
-A alternativa --- guidelines aspiracionais --- falha em escala. Quando 186 agentes operam em 18 dominios, regras que dependem de "boa vontade" sao violadas silenciosamente. Gates automaticos (hooks pre-commit, pre-push, validacoes de story) garantem que violacoes sao detectadas e bloqueadas antes de causar dano.
+A alternativa --- guidelines aspiracionais --- falha em escala. Quando 172 agentes operam em 17 dominios, regras que dependem de "boa vontade" sao violadas silenciosamente. Gates automaticos (hooks pre-commit, pre-push, validacoes de story) garantem que violacoes sao detectadas e bloqueadas antes de causar dano.
 
 **Exemplo:** o hook `enforce-git-push-authority.sh` bloqueia qualquer agente que nao seja @devops (Pipeline) de executar `git push`. Nao e uma sugestao --- e um bloqueio deterministico.
 
@@ -66,9 +66,9 @@ A razao e separacao de responsabilidades em escala. Um orquestrador que "faz tud
 
 ## 5. Escala do Ecossistema de Agentes
 
-**Por que 186 agentes em 18 dominios?**
+**Por que 172 agentes em 17 dominios?**
 
-O SINAPSE nao e um agente generalista. E um ecossistema de 175 especialistas organizados em 18 squads tematicos. Cada agente tem persona, expertise e comandos especificos para seu dominio.
+O SINAPSE nao e um agente generalista. E um ecossistema de 160 especialistas organizados em 17 squads tematicos. Cada agente tem persona, expertise e comandos especificos para seu dominio.
 
 Essa arquitetura permite:
 
@@ -76,13 +76,13 @@ Essa arquitetura permite:
 - **Contexto otimizado:** cada agente carrega apenas as dependencias necessarias para seu dominio, preservando a janela de contexto para o trabalho real.
 - **Escalabilidade horizontal:** novos dominios sao adicionados como squads independentes, sem impactar o core.
 
-Os 12 agentes core cobrem o ciclo completo de desenvolvimento de software. Os 18 squads expandem para dominios como branding, growth, financeiro, cybersecurity e mais.
+Os 12 agentes core cobrem o ciclo completo de desenvolvimento de software. Os 17 squads expandem para dominios como branding, growth, financeiro, cybersecurity e mais.
 
 | Camada | Agentes | Funcao |
 |--------|---------|--------|
 | Core | 12 agentes | Desenvolvimento de software completo |
-| Squads | 163 agentes em 18 dominios | Especializacao por dominio |
-| Total | 186 agentes | Ecossistema completo |
+| Squads | 160 agentes em 17 dominios | Especializacao por dominio |
+| Total | 172 agentes | Ecossistema completo |
 
 > Constitution Art. VII --- metricas exatas, sempre sincronizadas
 
@@ -178,10 +178,10 @@ Isso garante que o framework mantem coerencia e qualidade mesmo com contribuicoe
 | Principio | Por que existe | Enforcement |
 |-----------|---------------|-------------|
 | CLI First | Agentes operam em terminais | Hook WARN |
-| Governanca Constitucional | 186 agentes precisam de regras deterministicas | 10 artigos + gates |
+| Governanca Constitucional | 172 agentes precisam de regras deterministicas | 10 artigos + gates |
 | Documentation-First | Codigo sem spec gera retrabalho | Hook BLOCK |
 | Delegacao Obrigatoria | Separacao de responsabilidades em escala | Hook BLOCK |
-| Ecossistema 175 Agentes | Especializacao profunda por dominio | Art. VII metricas |
+| Ecossistema 172 Agentes | Especializacao profunda por dominio | Art. VII metricas |
 | Hooks Deterministicos | Guidelines aspiracionais falham em escala | 5+ hooks ativos |
 | Colaboracao Segura | Usuarios nao sao git experts | Auto-branch/sync/PR |
 | Seguranca por Default | Licoes de vazamentos reais | 25 blockers |

package/docs/getting-started.md

@@ -65,4 +65,4 @@ npx sinapse-ai uninstall               # remove tudo
 
 ---
 
-*Próxima leitura sugerida: [Agent Reference Guide](agent-reference-guide.md) pra ver todos os 200 agentes disponíveis.*
+*Próxima leitura sugerida: [Agent Reference Guide](agent-reference-guide.md) pra ver todos os 172 agentes disponíveis.*

package/docs/guides/agent-reference.md

@@ -1,7 +1,7 @@
 # Agent Reference — SINAPSE-AI
 
 > Reference for the **10 framework agents** ship-loaded by SINAPSE-AI.
-> For the wider squad agent universe (200 agents across 19 squads), see
+> For the wider squad agent universe (172 agents across 17 squads), see
 > the squads source-of-truth at `squads/` or run
 > `npx sinapse-ai list` after install.
 

package/docs/guides/codex-config.md

@@ -101,7 +101,7 @@ Resposta esperada ao ativar atalho:
 2. Mostrar 3-6 comandos principais (`*help`, etc.)
 3. Seguir na persona do agente
 
-## Orquestradores (19 orqx: 18 squad + 1 master)
+## Orquestradores (18 orqx: 17 squad + 1 master)
 
 Cada orqx coordena um squad completo de agentes especializados. Ative via `/skills` > `sinapse-<orqx>` ou `@<orqx>`:
 
@@ -124,14 +124,13 @@ Cada orqx coordena um squad completo de agentes especializados. Ative via `/skil
 | `courses-orqx` | Courses | Curriculos, assessments, launch |
 | `cloning-orqx` | Cloning | Clonagem cognitiva, mind synthesis |
 | `council-orqx` | Council | Advisors estrategicos (Munger, Dalio, Thiel) |
-| `claude-orqx` | Claude | Claude Code, MCP, integracao avancada |
-| `swarm-orqx` | Mastery | Dominio avancado do Claude Code |
+| `swarm-orqx` | Mastery | Claude Code, MCP, integracao avancada |
 
 Agents de arquivo: `.codex/agents/<orqx>.md` ou `.claude/agents/<orqx>.md`
 
-## Agentes Especializados (175)
+## Agentes Especializados (160)
 
-Existem 186 agentes especializados organizados por 18 squads (174 em squads + 1 master orchestrator). Eles sao acessiveis via:
+Existem 172 agentes organizados em 17 squads (160 em squads + 12 framework agents, incluindo o master orchestrator). Eles sao acessiveis via:
 - `.codex/agents/<agent-name>.md` - arquivo direto
 - Chamada interna pelo orqx do squad
 

package/docs/pt/architecture/sub-orqx-pattern.md

@@ -1,7 +1,14 @@
 # Sub-Orqx 3-Level Pattern
 
-> **Status:** Documented pattern — intentional architectural choice.
-> **Scope:** Currently only `claude-code-mastery`. Do NOT normalize elsewhere without justification.
+> **Status:** SUPERSEDED (2026-05-15 squad rename). This document describes the
+> historical 3-level topology that existed BEFORE `claude-code-mastery` was
+> flattened. The former parent layer `claude-orqx` was retired (see
+> `squads/claude-code-mastery/_deprecated/`) and `swarm-orqx` (Nexus) was
+> promoted to be the squad orchestrator itself. The current topology for
+> `claude-code-mastery` is the standard 2-level model: `sinapse-orqx` →
+> `swarm-orqx` → specialists. The `tools-orqx` sub-layer and `db-sage` were
+> also deprecated. Retained for historical/architectural context only — do NOT
+> treat the diagrams below as current routing truth.
 > **Related:** Constitution Article XI (Conservative Default)
 
 ## Overview
@@ -21,18 +28,14 @@ sinapse-orqx (Imperator)
 ```
 sinapse-orqx (Imperator)
     |
-    +-- claude-orqx (squad orchestrator)
+    +-- swarm-orqx (squad orchestrator)   # historically: claude-orqx (retired)
             |
-            +-- swarm-orqx (sub-orchestrator for orchestration specialists)
-            |       |
-            |       +-- hooks-architect, mcp-integrator, config-engineer,
-            |           project-integrator, roadmap-sentinel
+            +-- (in the historical 3-level model, sub-orchestrators sat here:
+            |    swarm-orqx for orchestration specialists, tools-orqx for
+            |    tool-crafters — both since collapsed/retired)
             |
-            +-- tools-orqx (sub-orchestrator for tool-crafters)
-            |       |
-            |       +-- skill-craftsman, db-sage
-            |
-            +-- (direct specialists, when domain is narrow enough to skip sub-orqx)
+            +-- hooks-architect, mcp-integrator, config-engineer,
+                project-integrator, roadmap-sentinel, skill-craftsman
 ```
 
 ## Why This Exists
@@ -66,10 +69,9 @@ Only add a sub-orqx layer when ALL of these hold:
 ```
 User: "Configure hooks + MCP servers + settings for this project"
   -> sinapse-orqx
-  -> claude-orqx
-  -> swarm-orqx (detects multi-specialist parallel work)
+  -> swarm-orqx (squad orchestrator; detects multi-specialist parallel work)
   -> hooks-architect | mcp-integrator | config-engineer (parallel)
-  -> results merged back through swarm-orqx -> claude-orqx -> user
+  -> results merged back through swarm-orqx -> user
 ```
 
 ### tools-orqx routing
@@ -77,9 +79,9 @@ User: "Configure hooks + MCP servers + settings for this project"
 ```
 User: "Create a reusable skill for X and document the DB access pattern"
   -> sinapse-orqx
-  -> claude-orqx
-  -> tools-orqx (detects tool-crafting work)
-  -> skill-craftsman | db-sage (parallel or sequential depending on dependency)
+  -> swarm-orqx (squad orchestrator)
+  -> skill-craftsman (skill authoring; the former tools-orqx sub-layer and
+     db-sage are retired — DB work now routes via @data-engineer)
 ```
 
 ## Non-Normalization Rule

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 17 squads, 172 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",
@@ -53,7 +53,13 @@
     "docs/agent-reference-guide.md",
     "docs/TELEMETRY.md",
     "README.md",
-    "LICENSE"
+    "CHANGELOG.md",
+    "LICENSE",
+    "!**/__tests__/**",
+    "!**/tests/**",
+    "!**/*.test.js",
+    "!**/*.spec.js",
+    ".sinapse-ai/development/templates/**"
   ],
   "scripts": {
     "format": "prettier --write \"**/*.md\"",

package/packages/installer/src/installer/git-hooks-installer.js

@@ -331,7 +331,9 @@ function pickValidateScript() {
 const script = pickValidateScript();
 if (script) {
   const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const res = spawnSync(npmCmd, ['run', '--silent', script], { stdio: 'inherit', cwd: projectRoot });
+  // shell:true on Windows — spawning npm.cmd without it throws EINVAL (CVE-2024-27980 /
+  // Node DEP0190). Args are fixed/literal here, so there is no shell-injection surface.
+  const res = spawnSync(npmCmd, ['run', '--silent', script], { stdio: 'inherit', cwd: projectRoot, shell: process.platform === 'win32' });
   if (res.error) {
     process.stderr.write('SINAPSE pre-push: could not run "npm run ' + script + '" — blocking push (fail-closed).\\n');
     process.stderr.write('  ' + res.error.message + '\\n');

package/packages/installer/src/installer/sinapse-ai-installer.js

@@ -141,8 +141,29 @@ async function generateVersionJson(options) {
  * @param {boolean} replaceRoot - Whether to replace {root} placeholders
  * @returns {Promise<boolean>} Success status
  */
-async function copyFileWithRootReplacement(sourcePath, destPath, replaceRoot = true) {
+/**
+ * Predicate: is this destination a user-owned L3 file that must survive a
+ * re-install? Matches the boundary contract (core-config.yaml + agent
+ * MEMORY.md are L3 "mutable / user-owned") and the README promise that
+ * re-running install is an idempotent upsert that preserves customizations.
+ * @param {string} destPath - Absolute destination path
+ * @returns {boolean}
+ */
+function isUserOwnedL3(destPath) {
+  const norm = String(destPath).replace(/\\/g, '/');
+  if (norm.endsWith('/.sinapse-ai/core-config.yaml')) return true;
+  if (/\/\.sinapse-ai\/development\/agents\/[^/]+\/MEMORY\.md$/.test(norm)) return true;
+  return false;
+}
+
+async function copyFileWithRootReplacement(sourcePath, destPath, replaceRoot = true, preserveExisting = null) {
   try {
+    // Preserve user-owned L3 files (core-config.yaml, agent MEMORY.md) when they
+    // already exist — a re-install must not silently wipe the user's config.
+    if (preserveExisting && preserveExisting(destPath) && await fs.pathExists(destPath)) {
+      return 'preserved';
+    }
+
     await fs.ensureDir(path.dirname(destPath));
 
     // Check if file needs {root} replacement (.md, .yaml, .yml)
@@ -171,7 +192,7 @@ async function copyFileWithRootReplacement(sourcePath, destPath, replaceRoot = t
  * @param {Function} onProgress - Progress callback
  * @returns {Promise<string[]>} List of copied files (relative paths)
  */
-async function copyDirectoryWithRootReplacement(sourceDir, destDir, onProgress = null) {
+async function copyDirectoryWithRootReplacement(sourceDir, destDir, onProgress = null, preserveExisting = null) {
   const copiedFiles = [];
 
   if (!await fs.pathExists(sourceDir)) {
@@ -193,11 +214,13 @@ async function copyDirectoryWithRootReplacement(sourceDir, destDir, onProgress =
     }
 
     if (item.isDirectory()) {
-      const subFiles = await copyDirectoryWithRootReplacement(sourcePath, destPath, onProgress);
+      const subFiles = await copyDirectoryWithRootReplacement(sourcePath, destPath, onProgress, preserveExisting);
       copiedFiles.push(...subFiles);
     } else {
-      const success = await copyFileWithRootReplacement(sourcePath, destPath);
-      if (success) {
+      const success = await copyFileWithRootReplacement(sourcePath, destPath, true, preserveExisting);
+      // Only count files actually written; 'preserved' (existing user-owned L3)
+      // and false (error) must not inflate the installed-files manifest.
+      if (success === true) {
         copiedFiles.push(path.relative(destDir, destPath));
         if (onProgress) {
           onProgress({ file: item.name, copied: true });
@@ -290,6 +313,7 @@ async function installSinapseCore(options = {}) {
           folderSource,
           folderDest,
           onProgress,
+          isUserOwnedL3,
         );
 
         if (copiedFiles.length > 0) {
@@ -306,8 +330,8 @@ async function installSinapseCore(options = {}) {
 
       if (await fs.pathExists(fileSource)) {
         spinner.text = `Copying ${file}...`;
-        const success = await copyFileWithRootReplacement(fileSource, fileDest);
-        if (success) {
+        const success = await copyFileWithRootReplacement(fileSource, fileDest, true, isUserOwnedL3);
+        if (success === true) {
           result.installedFiles.push(file);
         }
       }
@@ -495,6 +519,7 @@ module.exports = {
   getSinapseCoreSourcePath,
   copyFileWithRootReplacement,
   copyDirectoryWithRootReplacement,
+  isUserOwnedL3,
   generateVersionJson,
   generateFileHashes,
   deliverCodexRootFiles,

package/packages/installer/src/wizard/ide-config-generator.js

@@ -929,7 +929,12 @@ async function linkGeminiExtension(projectRoot) {
     return { status: 'skipped', reason: 'manifest-not-found' };
   }
 
-  const versionCheck = spawnSync('gemini', ['--version'], { encoding: 'utf8' });
+  // On Windows, `gemini` is a .cmd/.ps1 shim — spawnSync without a shell throws
+  // EINVAL. Run through the shell on win32 so the shim resolves.
+  const versionCheck = spawnSync('gemini', ['--version'], {
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
   if (versionCheck.status !== 0) {
     return { status: 'skipped', reason: 'gemini-cli-not-available' };
   }
@@ -938,6 +943,7 @@ async function linkGeminiExtension(projectRoot) {
     cwd: projectRoot,
     encoding: 'utf8',
     timeout: 30000,
+    shell: process.platform === 'win32',
   });
 
   if (linkResult.status === 0) {
@@ -952,6 +958,7 @@ async function linkGeminiExtension(projectRoot) {
       cwd: projectRoot,
       encoding: 'utf8',
       timeout: 30000,
+      shell: process.platform === 'win32',
     });
 
     if (uninstall.status !== 0) {
@@ -962,6 +969,7 @@ async function linkGeminiExtension(projectRoot) {
       cwd: projectRoot,
       encoding: 'utf8',
       timeout: 30000,
+      shell: process.platform === 'win32',
     });
 
     if (linkResult.status === 0) {