sinapse-ai 1.19.2 → 1.20.0

package/docs/framework/source-tree.md

@@ -741,7 +741,7 @@ outputs/                               # Runtime outputs (gitignored)
 
 ## Autonomous Development Engine (ADE)
 
-> **NEW in v3.0** - The ADE provides autonomous development capabilities through intelligent workflows, pattern learning, and self-healing loops.
+> **Added in v3.0** - The ADE provides structured workflows, pattern learning, and self-healing loops for development. **Measured scope:** reliable as a single-story assistant (spec + plan + build); autonomous multi-story orchestration was measured and abandoned in favor of the native flow — see [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
 
 ### ADE Architecture Overview
 

package/docs/framework/workflow-engine-status.md

@@ -0,0 +1,70 @@
+# Workflow Engine Status — o que os 15 YAMLs de workflow realmente fazem
+
+> **Fonte:** `audits/AF-20260702-fable5-upgrade.md` §3 Onda 2, item 2.17 (verificado por leitura direta de código nesta story).
+> **Story:** `docs/stories/story-o2p5-enforcement-honesto.md` (Onda2-P5).
+> **Data:** 2026-07-02.
+
+## Por que este documento existe
+
+`.sinapse-ai/development/workflows/*.yaml` descreve 15 fluxos de trabalho. Isso NÃO significa que existem 15 fluxos executados por um engine — cada YAML tem um nível de "vivência" no código diferente, e a documentação pública nunca distinguiu isso explicitamente. Este documento é a fonte da verdade sobre o que cada YAML É de fato, verificado por leitura de código (não por inferência).
+
+## Contagem
+
+`Glob(.sinapse-ai/development/workflows/*.yaml)` retorna exatamente **15 arquivos** (confirmado em 2026-07-02) — bate com a contagem do relatório de auditoria.
+
+## Classificação verificada
+
+| # | Workflow | Classe | Evidência (lida diretamente) |
+|---|---|---|---|
+| 1 | `development-cycle.yaml` | **(a) Engine real, in-process** | `workflow-executor.js:104` — único YAML cujo path é carregado e cujas fases o `WorkflowExecutor` de fato interpreta e avança em código. |
+| 2 | `greenfield-ui.yaml` | **(b) Handler + prosa** | `greenfield-handler.js:144-150` resolve o YAML pelo `project_type` (`resolveGreenfieldWorkflow`) e monta `workflowPath`; o handler chama `WorkflowExecutor`, mas os `steps` do YAML são instrução em linguagem natural — o executor carrega/valida o arquivo e devolve handoff, não interpreta os steps como programa. |
+| 3 | `greenfield-fullstack.yaml` | **(b) Handler + prosa** | Idem (mesmo `greenfield-handler.js`, variante `fullstack`). |
+| 4 | `greenfield-service.yaml` | **(b) Handler + prosa** | Idem (mesmo `greenfield-handler.js`, variante `service`). |
+| 5 | `brownfield-ui.yaml` | **(b) Handler + prosa** | `brownfield-handler.js:78-84` mapeia `project_type` → `brownfield-ui`/`fullstack`/`service` (`resolveBrownfieldWorkflow`, mesmo padrão do greenfield); `:135-138` monta `workflowPath`; `:360` chama `workflowExecutor.executeWorkflow(this.workflowPath, ...)`. |
+| 6 | `brownfield-fullstack.yaml` | **(b) Handler + prosa** | Idem. |
+| 7 | `brownfield-service.yaml` | **(b) Handler + prosa** | Idem. |
+| 8 | `brownfield-discovery.yaml` | **(b) Handler + prosa** | `brownfield-handler.js:13,326-360` — entry point específico da descoberta; o próprio YAML declara em `metadata.action_types.workflow-action` (linha ~23): "Action is a workflow orchestration step executed via **manual prompt**". |
+| 9 | `qa-loop.yaml` | **(c) Citado, quebrado/parcial** | `epic-6-executor.js` reimplementa o loop review→fix→re-review direto em JS (`_runReview`/`_applyFixes`/contagem de iteração), sem nunca ler o YAML. O comentário do próprio arquivo (linhas 40-45) diz que o caminho antigo que citava o YAML via `qa-loop-orchestrator.js` era "triple-broken theater" e foi substituído por invocação direta de agente. `qa-loop-orchestrator.js` (que guarda `workflowPath: '.../qa-loop.yaml'` como constante) não tem nenhum call site fora de si mesmo — está órfão. |
+| 10 | `spec-pipeline.yaml` | **(c) Citado, quebrado/parcial** | `epic-3-executor.js:36-41` guarda `this.pipelinePath` apontando pro YAML — mas essa é a **única** ocorrência da variável no arquivo inteiro (grep confirma), nunca é lida (`fs.readFileSync` nunca chamado sobre ela). As fases rodam de um array JS hardcoded (`SPEC_PHASES`), não do conteúdo do YAML. |
+| 11 | `story-development-cycle.yaml` | **(d) Catálogo puro** | Só existe como entrada em `service-registry.json:11941-11972` (`path` na linha 11956). Nenhum executor em `.sinapse-ai/core/` referencia esse path. |
+| 12 | `epic-orchestration.yaml` | **(d) Catálogo puro** | Só existe em `service-registry.json:11739` (`maxConcurrency: 4` nunca teve executor). Nenhum código carrega o arquivo. |
+| 13 | `fast-track.yaml` | **(d) Catálogo puro** | Só existe em `service-registry.json:11770`. Nenhum código carrega o arquivo. |
+| 14 | `auto-worktree.yaml` | **(d) Catálogo puro** | `triggers` declara `event: story_started` (linha 24) — nenhum engine do repo escuta esse evento. Os blocos `script:` dentro de cada step (JS embutido em YAML) nunca são interpretados/executados por nenhum runtime; é só entrada de catálogo em `service-registry.json`. |
+| 15 | `design-system-build-quality.yaml` | **(d) Catálogo puro** | Só existe em `service-registry.json:11677`. Nenhum código carrega o arquivo. |
+
+**Total: 1 (a) + 7 (b) + 2 (c) + 5 (d) = 15.**
+
+## O que cada classe significa na prática
+
+- **(a) Engine real (1/15)** — o único caso em que o YAML é literalmente a fonte de execução: `WorkflowExecutor` lê o arquivo e avança fase a fase em código.
+- **(b) Handler + prosa (7/15)** — existe código real e vivo (`greenfield-handler.js`, `brownfield-handler.js`) que resolve qual YAML usar por tipo de projeto e invoca `WorkflowExecutor.executeWorkflow()` — mas isso carrega/valida o arquivo e devolve um handoff para o humano/agente seguir manualmente. Os `steps` descritos no YAML são instrução em linguagem natural, não um programa interpretado.
+- **(c) Citado mas quebrado/parcial (2/15)** — em algum ponto do histórico o código apontava para o YAML (variável de path guardada, ou um script satélite), mas o caminho vivo de hoje contorna o arquivo por completo: ou porque foi reescrito para chamar um agente real diretamente (`qa-loop`), ou porque a variável do path nunca chega a ser lida (`spec-pipeline`).
+- **(d) Catálogo puro (5/15)** — existem apenas como entrada em `service-registry.json` (id, nome, tags, path). Nenhuma linha de código em `.sinapse-ai/core/` carrega ou executa o arquivo.
+
+## Decisão
+
+O YAML continua sendo a **especificação / fonte da verdade** de cada workflow — é o contrato que a documentação em `docs/sinapse-workflows/` deriva e que humanos/agentes seguem manualmente hoje. Construir uma camada executável (`.workflow.js`) para os 15 não é a aposta certa: o veredito HÍBRIDO medido em 30/06/2026 mostrou que orquestração multi-agente sem gate determinístico tende a piorar (coordenação sabotou 1/3 vs 3/3 do caminho nativo — ver `docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md`).
+
+A decisão é: **camada executável real só para os 3-5 fluxos de maior valor**, cada um condicionado a um gate de medição antes de virar produto (repetir o protocolo do checkpoint de 30/06 — comparar contra o caminho nativo em custo e resultado). Candidatos, escopados para a Onda 3 (`audits/AF-20260702-fable5-upgrade.md` §3 Onda 3, itens 3.3-3.5):
+
+1. **Brownfield Discovery (TOP 3)** — fan-out real (`parallel()`) na fase de coleta (arquiteto/dados/UX em paralelo) + gate de QA em código (APPROVED/NEEDS_WORK com retorno automático, máx. 2 voltas).
+2. **Greenfield Discovery Phase 1 (TOP 4)** — pipeline com gate determinístico por artefato ("arquivo existe e não está vazio", reaproveitando `doc-first-resolver.js::fileHasContent`) + checkpoint humano honrando `confirmation_required`.
+3. **Epic waves multi-story (TOP 5)** — wrapper fino no harness, fan-out por story em worktree isolado (zero estado compartilhado) — **gate inegociável de adoção:** repetir a medição de 30/06 (3 stories dependentes vs. nativo puro); só vira produto se empatar ou vencer em custo.
+
+Sem essas 3, os outros 12 YAMLs continuam sendo espec, não motor — e está tudo bem, contanto que nenhum documento afirme o contrário.
+
+## Docs shipped verificados (busca dirigida, sem correção necessária)
+
+Busca em 2026-07-02 por afirmações de que os 15 YAMLs seriam executados automaticamente por um engine:
+
+- `docs/framework/source-tree.md` (seção "Autonomous Development Engine") — já escopado por uma Onda 2 anterior: "**Measured scope:** reliable as a single-story assistant", com link para `KNOWN-LIMITATIONS.md`. Não overclaima.
+- `docs/framework/atlas/OPERATING-ATLAS.md` §6 ("Workflow catalog") — lista os 15 com nome/tipo/descrição; é um catálogo neutro gerado do `service-registry.json`, não afirma execução automática.
+- `docs/sinapse-workflows/README.md` — descreve o uso como algo que humano/agente "segue" ("Siga os Steps na ordem"), consistente com a realidade de handler+prosa.
+
+Nenhuma correção adicional foi necessária além do que a Onda 2 anterior (itens 2.1/2.4 do relatório) já cobriu.
+
+## Links
+
+- Épico-mãe: [`docs/epics/epic-ultra-optimization/README.md`](../epics/epic-ultra-optimization/README.md) §0.5 (Estado).
+- Evidência completa: `audits/AF-20260702-fable5-upgrade.md`, item 2.17 e §3 Onda 3 (itens 3.3-3.5).
+- Limitação medida do motor: [`docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md`](../epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).

package/docs/guides/ade-guide.md

@@ -2,7 +2,7 @@
 
 > **Versão:** 1.0.0
 > **Data:** 2026-01-29
-> **Status:** Production Ready ✅
+> **Status:** Assistente confiável de 1 story (medido) ⚠️ — multi-story não suportado
 
 ---
 
@@ -10,6 +10,8 @@
 
 O **SINAPSE Autonomous Development Engine (ADE)** é um sistema de desenvolvimento autônomo que transforma requisitos vagos em código funcional através de pipelines estruturados e agentes especializados.
 
+> **Escopo real (medido em 2026-06-30):** confiável para **1 story isolada** — gera spec (Epic 3) e plano (Epic 4) reais, e produz código correto para essa story. Orquestração autônoma de **múltiplas stories encadeadas** foi medida e **abandonada** (o caminho nativo venceu 3/3 stories vs 1/3 do motor). Detalhes: [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
 ### Características Principais
 
 - **Spec Pipeline** - Transforma ideias em especificações executáveis
@@ -443,5 +445,5 @@ cat docs/stories/STORY-42/spec-critique.json
 
 ---
 
-_SINAPSE Autonomous Development Engine - Turning Ideas into Code Autonomously_
+_SINAPSE Autonomous Development Engine - Assistente confiável de spec a código, 1 story por vez_
 

package/docs/guides/api-reference.md

@@ -200,6 +200,8 @@ Task execution with arguments: { story: "story-1.2.3" }
 | `*build-status`     | `[--all]`    | Show build status                  |
 | `*build-log`        | `{story-id}` | View build attempt log             |
 
+> **Scope:** build commands run **one `{story-id}` at a time** — a reliable single-story pipeline. Multi-story chaining is not supported; see [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
 **Quality & Debt:**
 
 | Command           | Arguments | Description                   |

package/docs/guides/permission-modes.md

@@ -205,6 +205,8 @@ The Autonomous Development Engine (ADE) respects permission modes:
 | **Ask**     | Batches operations for approval |
 | **Auto**    | Full autonomous execution       |
 
+> **Scope:** "Full autonomous execution" applies per story. Chained multi-story autonomy is not supported — see [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
 ### Batch Approval in Ask Mode
 
 When running autonomous workflows, operations are grouped:

package/docs/guides/user-guide.md

@@ -6,8 +6,8 @@
 
 Complete guide for using SINAPSE - the AI-Orchestrated System for Full Stack Development.
 
-**Version:** 2.1.0
-**Last Updated:** 2026-01-28
+**Version:** 1.19.2
+**Last Updated:** 2026-07-02
 
 ---
 
@@ -18,7 +18,7 @@ Complete guide for using SINAPSE - the AI-Orchestrated System for Full Stack Dev
 Before using SINAPSE, ensure you have:
 
 - **Node.js** version 18.0.0 or higher
-- **npm** version 8.0.0 or higher
+- **npm** version 9.0.0 or higher
 - **Git** for version control
 - An AI provider API key (Anthropic, OpenAI, or compatible)
 
@@ -40,10 +40,10 @@ npx sinapse-ai install
 cd my-project
 
 # List available agents
-sinapse agents list
+npx sinapse-ai agents list
 
 # Activate an agent
-@dev
+@developer
 
 # Get help
 *help
@@ -224,6 +224,20 @@ sinapse route "add dark mode to the platform"
 sinapse orchestrate <story-id>
 ```
 
+### Orchestrate — Supported Scope (Measured)
+
+`sinapse orchestrate` is reliable for **one story at a time**. Sequential
+multi-story orchestration in the same working directory is **not supported** —
+this was measured directly (native flow: 3/3 stories, 64s, 1 call; the
+orchestrate pipeline: 1/3 stories, ~13.5min, state leaked across stories) and
+the autonomous multi-story path was abandoned in favor of the native flow.
+Full write-up: [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
+| Use                                                   | Supported?                  |
+| ------------------------------------------------------ | ---------------------------- |
+| `orchestrate` for **1 story** (spec + plan + build)     | ✅ Yes, reliable              |
+| `orchestrate` for **multiple chained stories**          | ❌ No — use the native flow   |
+
 ---
 
 ## Squads
@@ -341,7 +355,7 @@ features:
 
 ai:
   provider: anthropic
-  model: claude-3-opus
+  model: opus # family alias (opus | sonnet | haiku) — the CLI resolves the current version; never hardcode a dated snapshot id
 
 environment: development
 ```
@@ -490,4 +504,4 @@ before building a new agent from scratch.
 
 ---
 
-_SINAPSE User Guide v4.2.11_
+_SINAPSE User Guide v1.19.2_

package/docs/guides/workflows/AUTO-WORKTREE-WORKFLOW.md

@@ -9,14 +9,14 @@
 
 ## Visao Geral
 
-O **Auto-Worktree** e um workflow de automacao que cria e gerencia worktrees Git isoladas para desenvolvimento de stories. Faz parte da infraestrutura **Auto-Claude ADE** (Autonomous Development Engine), permitindo desenvolvimento paralelo de multiplas stories sem conflitos entre branches.
+O **Auto-Worktree** e um workflow de automacao que cria e gerencia worktrees Git isoladas para desenvolvimento de stories (isolamento real de branch por story, um recurso generico do Git). Faz parte da infraestrutura **Auto-Claude ADE** (Autonomous Development Engine). Nota de escopo: isso NAO e o mesmo que orquestracao autonoma multi-story — essa foi medida e abandonada (o pipeline `sinapse orchestrate` hoje nao usa esse isolamento). Detalhes: KNOWN-LIMITATIONS.md (https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
 
 ### Principais Beneficios
 
 | Beneficio | Descricao |
 |-----------|-----------|
 | **Isolamento** | Cada story trabalha em um diretorio e branch separados |
-| **Paralelismo** | Multiplas stories podem ser desenvolvidas simultaneamente |
+| **Paralelismo** | Multiplas stories podem ter worktrees isoladas ao mesmo tempo (isolamento manual/nativo — nao e orquestracao autonoma multi-story) |
 | **Automacao** | Worktrees sao criadas automaticamente ao iniciar uma story |
 | **Limpeza** | Worktrees obsoletas podem ser removidas automaticamente |
 

package/docs/pt/architecture/ade-architecture.md

@@ -26,6 +26,8 @@
 
 O **Motor de Desenvolvimento Autônomo (ADE)** é a infraestrutura do SINAPSE para workflows de desenvolvimento autônomo. Ele permite que agentes de IA trabalhem de forma independente através de pipelines inteligentes, loops auto-recuperáveis e aprendizado persistente.
 
+> **Escopo real (medido em 2026-06-30):** confiável para **1 story isolada** (spec + plano + build). Orquestração autônoma de múltiplas stories encadeadas foi medida e abandonada em favor do caminho nativo — ver [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
 ### Capacidades Principais
 
 | Capacidade                   | Descrição                                | Épica |

package/docs/pt/architecture/high-level-architecture.md

@@ -54,7 +54,7 @@
 │                                                                         │
 │   ┌─────────────────────────────────────────────────────────────────┐   │
 │   │                        CLI / FERRAMENTAS                        │   │
-│   │  (sinapse agents, sinapse tasks, sinapse squads, sinapse workflow)          │   │
+│   │  (sinapse-ai agents, sinapse tasks, sinapse squads, sinapse workflow)       │   │
 │   └─────────────────────────────────────────────────────────────────┘   │
 │                                │                                        │
 │          ┌────────────────────┼────────────────────┐                   │

package/docs/pt/guides/ade-guide.md

@@ -8,7 +8,7 @@
 
 > **Versão:** 1.0.0
 > **Data:** 2026-01-29
-> **Status:** Pronto para Produção
+> **Status:** Assistente confiável de 1 story (medido) ⚠️ — multi-story não suportado
 
 ---
 
@@ -16,6 +16,8 @@
 
 O **SINAPSE Autonomous Development Engine (ADE)** é um sistema de desenvolvimento autônomo que transforma requisitos vagos em código funcional através de pipelines estruturados e agentes especializados.
 
+> **Escopo real (medido em 2026-06-30):** confiável para **1 story isolada** — gera spec (Epic 3) e plano (Epic 4) reais, e produz código correto para essa story. Orquestração autônoma de **múltiplas stories encadeadas** foi medida e **abandonada** (o caminho nativo venceu 3/3 stories vs 1/3 do motor). Detalhes: [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
 ### Características Principais
 
 - **Spec Pipeline** - Transforma ideias em especificações executáveis
@@ -449,5 +451,5 @@ cat docs/stories/STORY-42/spec-critique.json
 
 ---
 
-_SINAPSE Autonomous Development Engine - Transformando Ideias em Código de Forma Autônoma_
+_SINAPSE Autonomous Development Engine - Assistente confiável de spec a código, 1 story por vez_
 

package/docs/pt/guides/api-reference.md

@@ -200,6 +200,8 @@ Execução de task com argumentos: { story: "story-1.2.3" }
 | `*build-status`     | `[--all]`    | Mostrar status do build                  |
 | `*build-log`        | `{story-id}` | Visualizar log de tentativas de build    |
 
+> **Escopo:** os comandos de build rodam **1 `{story-id}` por vez** — pipeline confiável de 1 story. Encadeamento multi-story não é suportado; ver [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
 **Qualidade & Débito:**
 
 | Comando           | Argumentos | Descrição                          |

package/docs/pt/guides/permission-modes.md

@@ -211,6 +211,8 @@ O Autonomous Development Engine (ADE) respeita os modos de permissão:
 | **Perguntar** | Agrupa operações para aprovação   |
 | **Auto**      | Execução totalmente autônoma      |
 
+> **Escopo:** "Execução totalmente autônoma" vale por story. Orquestração autônoma de múltiplas stories encadeadas não é suportada — ver [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
 ### Aprovação em Lote no Modo Perguntar
 
 Ao executar workflows autônomos, operações são agrupadas:

package/docs/pt/guides/user-guide.md

@@ -12,8 +12,8 @@
 
 Guia completo para usar o SINAPSE - o Sistema Orquestrado por IA para Desenvolvimento Full Stack.
 
-**Versão:** 2.1.0
-**Última Atualização:** 2026-01-28
+**Versão:** 1.19.2
+**Última Atualização:** 2026-07-02
 
 ---
 
@@ -24,7 +24,7 @@ Guia completo para usar o SINAPSE - o Sistema Orquestrado por IA para Desenvolvi
 Antes de usar o SINAPSE, certifique-se de ter:
 
 - **Node.js** versão 18.0.0 ou superior
-- **npm** versão 8.0.0 ou superior
+- **npm** versão 9.0.0 ou superior
 - **Git** para controle de versão
 - Uma chave de API de provedor de IA (Anthropic, OpenAI ou compatível)
 
@@ -46,10 +46,10 @@ npx sinapse-ai install
 cd my-project
 
 # Liste agentes disponíveis
-sinapse agents list
+npx sinapse-ai agents list
 
 # Ative um agente
-@dev
+@developer
 
 # Obtenha ajuda
 *help
@@ -189,6 +189,20 @@ sinapse route "adicionar dark mode na plataforma"
 sinapse orchestrate <story-id>
 ```
 
+### Orchestrate — Escopo Suportado (Medido)
+
+O `sinapse orchestrate` é confiável para **1 story por vez**. Orquestração
+autônoma de múltiplas stories encadeadas no mesmo diretório de trabalho **não é
+suportada** — isso foi medido diretamente (fluxo nativo: 3/3 stories, 64s, 1
+chamada; o pipeline orchestrate: 1/3 stories, ~13,5min, com contaminação de
+estado entre stories) e o caminho multi-story autônomo foi abandonado em favor
+do fluxo nativo. Detalhes completos: [KNOWN-LIMITATIONS.md](https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
+| Uso                                                  | Suportado?                  |
+| ------------------------------------------------------ | ---------------------------- |
+| `orchestrate` de **1 story** (spec + plano + build)     | ✅ Sim, confiável             |
+| `orchestrate` de **múltiplas stories** encadeadas       | ❌ Não — use o caminho nativo |
+
 ---
 
 ## Squads
@@ -304,7 +318,7 @@ features:
 
 ai:
   provider: anthropic
-  model: claude-3-opus
+  model: opus # alias de família (opus | sonnet | haiku) — o CLI resolve a versão atual; nunca fixe um id datado
 
 environment: development
 ```
@@ -453,5 +467,5 @@ construir um agente novo do zero.
 
 ---
 
-_Guia do Usuário SINAPSE v4.0_
+_Guia do Usuário SINAPSE v1.19.2_
 

package/docs/pt/platforms/claude-code.md

@@ -151,7 +151,7 @@ Este arquivo contém:
 export ANTHROPIC_API_KEY="sk-ant-..."
 
 # Opcional
-export CLAUDE_MODEL="claude-sonnet-4-20250514"  # Modelo padrão
+export CLAUDE_MODEL="sonnet"  # Alias de família — o CLI resolve a versão atual (nunca fixe um id datado)
 export CLAUDE_MAX_TOKENS="8192"                 # Máximo de tokens de resposta
 export SINAPSE_DEBUG="true"                        # Habilitar log de debug
 ```
@@ -162,7 +162,7 @@ export SINAPSE_DEBUG="true"                        # Habilitar log de debug
 
 ```json
 {
-  "model": "claude-sonnet-4-20250514",
+  "model": "sonnet",
   "maxTokens": 8192,
   "permissions": {
     "allowedTools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],

package/docs/sinapse-workflows/auto-worktree-workflow.md

@@ -9,14 +9,14 @@
 
 ## Visão Geral
 
-O **Auto-Worktree** é um workflow de automação que cria e gerencia worktrees Git isoladas para desenvolvimento de stories. Faz parte da infraestrutura **Auto-Claude ADE** (Autonomous Development Engine), permitindo desenvolvimento paralelo de multiplas stories sem conflitos entre branches.
+O **Auto-Worktree** é um workflow de automação que cria e gerencia worktrees Git isoladas para desenvolvimento de stories (isolamento real de branch por story, um recurso genérico do Git). Faz parte da infraestrutura **Auto-Claude ADE** (Autonomous Development Engine). Nota de escopo: isso NÃO é o mesmo que orquestração autônoma multi-story — essa foi medida e abandonada (o pipeline `sinapse orchestrate` hoje não usa esse isolamento). Detalhes: KNOWN-LIMITATIONS.md (https://github.com/caioimori/sinapse-ai/blob/main/docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
 
 ### Principais Beneficios
 
 | Benefício | Descrição |
 |-----------|-----------|
 | **Isolamento** | Cada story trabalha em um diretório e branch separados |
-| **Paralelismo** | Multiplas stories podem ser desenvolvidas simultaneamente |
+| **Paralelismo** | Multiplas stories podem ter worktrees isoladas ao mesmo tempo (isolamento manual/nativo — não é orquestração autônoma multi-story) |
 | **Automação** | Worktrees são criadas automaticamente ao iniciar uma story |
 | **Limpeza** | Worktrees obsoletas podem ser removidas automaticamente |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.19.2",
+  "version": "1.20.0",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 17 squads, 172 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",

package/packages/installer/src/config/configure-environment.js

@@ -321,6 +321,12 @@ async function updateGitignore(targetDir) {
     'Build & Logs': ['dist/', 'build/', '*.log', 'logs/'],
     'IDE & OS': ['.DS_Store', 'Thumbs.db', '.idea/', '*.swp'],
     'SINAPSE Local': ['.sinapse-ai/local/', '.claude/settings.local.json', '.sinapse/install-log.txt'],
+    // Story onda2-p9 — context-engine runtime. The framework repo ignores the
+    // WHOLE .synapse/ (see its .gitignore): the constitution is regenerated
+    // from .sinapse-ai/constitution.md on every install, and sessions/ +
+    // metrics/ are per-machine runtime state. Installed projects replicate
+    // that intent — nothing under .synapse/ is meant to be versioned.
+    'SINAPSE Context Engine': ['.synapse/'],
   };
 
   const lines = gitignoreContent.split('\n').map(line => line.trim());

package/packages/installer/src/config/templates/core-config-template.js

@@ -210,13 +210,55 @@ function generateCoreConfig(options = {}) {
   };
 
   // Convert to YAML with proper formatting
-  return yaml.dump(config, {
+  const dumped = yaml.dump(config, {
     indent: 2,
     lineWidth: 120,
     noRefs: true,
   });
+
+  // Story onda2-p9 (closes the P4/DEC-01 loose end): the `models` section is
+  // appended as a raw block (yaml.dump cannot emit comments) so installed
+  // projects stop falling back to the conservative 200000-token window when
+  // the active model actually has a 1M window. Values MIRROR the framework
+  // repo's core-config.yaml `models` section — never invent context windows.
+  return dumped + MODELS_SECTION;
 }
 
+/**
+ * `models` registry block for installed projects (Story onda2-p9, AC2).
+ *
+ * Consumed by .sinapse-ai/core/synapse/context/context-tracker.js
+ * (getModelConfig): `active` selects which registry entry drives
+ * estimateContextPercent/shouldCompact.
+ *
+ * MAINTENANCE: keep in sync with the framework repo's core-config.yaml
+ * `models:` section (source of truth). When the frontier model changes,
+ * update `active` + add the entry THERE first, then mirror here.
+ * Windows below are copied verbatim from that source — do not invent values.
+ *
+ * @constant {string}
+ */
+const MODELS_SECTION = `
+# Context-tracker dynamic model registry (mirrors the framework core-config.yaml).
+# Consumed by .sinapse-ai/core/synapse/context/context-tracker.js (getModelConfig):
+# 'active' selects which registry entry drives context estimation.
+# MAINTENANCE: keep in sync with the framework repo's core-config.yaml models
+# section. If this section (or the active entry) is missing/invalid, the
+# tracker falls back to a conservative 200000-token window (documented in
+# context-tracker.js DEFAULTS) — safe, but wrong for 1M-window models.
+models:
+  active: claude-fable-5
+  registry:
+    claude-fable-5:
+      contextWindow: 1000000
+      avgTokensPerPrompt: 2000
+    claude-sonnet-5:
+      # conservative default — verify against official docs before relying on 1M
+      contextWindow: 200000
+      avgTokensPerPrompt: 1500
+`;
+
 module.exports = {
   generateCoreConfig,
+  MODELS_SECTION,
 };

package/packages/installer/src/installer/synapse-runtime-installer.js

@@ -0,0 +1,148 @@
+/**
+ * SYNAPSE Context-Engine Runtime Installer
+ *
+ * Story onda2-p9 (DEC-01 option A) — activates the context engine for every
+ * installed project. The synapse-engine.cjs hook is ALREADY copied + registered
+ * by every install (wizard/ide-config-generator.js HOOKS_TO_COPY + HOOK_EVENT_MAP),
+ * but it dies on an early-return when `<project>/.synapse/` does not exist
+ * (.sinapse-ai/core/synapse/runtime/hook-runtime.js — `if (!fs.existsSync(synapsePath)) return null;`).
+ * This module closes that gap on the CANONICAL install path (install + init)
+ * by generating the `.synapse/` runtime in the target project:
+ *
+ *   .synapse/constitution   — L0 domain (KEY=VALUE), generated from the target's
+ *                             own .sinapse-ai/constitution.md by the EXISTING
+ *                             generator (core/synapse/scripts/generate-constitution.js
+ *                             — reused via main({ projectRoot }), never duplicated)
+ *   .synapse/sessions/      — per-session state (session-manager also auto-creates)
+ *   .synapse/metrics/       — engine injection metrics
+ *
+ * FAIL-OPEN CONTRACT (NON-NEGOTIABLE for this step): any error here must NEVER
+ * break the installation. The function never throws — it returns
+ * { success: false, error } and the caller logs a warning and continues.
+ * This is safe because the hook itself is fail-safe by design: in the absence
+ * of .synapse/ (or of a readable constitution) hook-runtime.js returns null and
+ * NOTHING is injected — the engine simply stays dormant, exactly the pre-P9
+ * behavior. Worst case of a generation failure = status quo ante.
+ *
+ * @module installer/synapse-runtime-installer
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Relative path (from a project root) to the constitution generator that ships
+ * inside the framework core.
+ * @constant {string[]}
+ */
+const GENERATOR_REL_PATH = [
+  '.sinapse-ai', 'core', 'synapse', 'scripts', 'generate-constitution.js',
+];
+
+/**
+ * Resolve the generate-constitution.js module to use for a given target.
+ *
+ * Preference order:
+ *   1. The TARGET's own copy (installed by installSinapseCore just before this
+ *      step) — version-matched with the .sinapse-ai/ payload the project got.
+ *      In framework-dev mode (target === package root) this IS the source copy.
+ *   2. The package's own copy — fallback for partial copies.
+ *
+ * @param {string} targetDir - Target project root
+ * @returns {string|null} Absolute path to the generator, or null if none found
+ */
+function resolveGeneratorPath(targetDir) {
+  const targetCopy = path.join(targetDir, ...GENERATOR_REL_PATH);
+  if (fs.existsSync(targetCopy)) return targetCopy;
+
+  // packages/installer/src/installer/ → package root
+  const packageCopy = path.join(__dirname, '..', '..', '..', '..', ...GENERATOR_REL_PATH);
+  if (fs.existsSync(packageCopy)) return packageCopy;
+
+  return null;
+}
+
+/**
+ * Generate the `.synapse/` context-engine runtime in the target project.
+ *
+ * Never throws. Silences the generator's own console.log and preserves
+ * process.exitCode (the underlying generator sets exitCode=1 on a miss, which
+ * must not leak into the installer's exit semantics — same protection the
+ * repo-source wrapper scripts/generate-synapse-runtime.js applies).
+ *
+ * @param {Object} [options]
+ * @param {string} [options.targetDir=process.cwd()] - Target project root
+ * @param {string} [options.generatorPath] - Override generator module (tests)
+ * @returns {{success: boolean, articles?: number, rules?: number, outputPath?: string, error?: string, sessionsDir?: string, metricsDir?: string}}
+ */
+function installSynapseRuntime(options = {}) {
+  const { targetDir = process.cwd() } = options;
+  const savedExitCode = process.exitCode;
+  const origLog = console.log;
+  const origError = console.error;
+
+  try {
+    const generatorPath = options.generatorPath || resolveGeneratorPath(targetDir);
+    if (!generatorPath) {
+      return {
+        success: false,
+        error: 'generate-constitution.js not found (target and package copies missing)',
+      };
+    }
+
+    // Silence the generator's console output ("Constitution generated…" /
+    // "Constitution not found…") — the wizard prints its own summary line.
+    console.log = () => {};
+    console.error = () => {};
+
+    let result;
+    try {
+      const { main } = require(generatorPath);
+      if (typeof main !== 'function') {
+        return { success: false, error: 'generator module has no main() export' };
+      }
+      result = main({ projectRoot: targetDir });
+    } finally {
+      console.log = origLog;
+      console.error = origError;
+    }
+
+    if (!result || !result.success) {
+      return {
+        success: false,
+        error: (result && result.error) || 'constitution generation failed',
+      };
+    }
+
+    // sessions/ + metrics/ — mirrors the repo-source .synapse/ layout. The
+    // session-manager also mkdir -p's sessions/ lazily, but creating them here
+    // gives the installed project the complete structure from prompt zero.
+    const sessionsDir = path.join(targetDir, '.synapse', 'sessions');
+    const metricsDir = path.join(targetDir, '.synapse', 'metrics');
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    fs.mkdirSync(metricsDir, { recursive: true });
+
+    return {
+      success: true,
+      articles: result.articles,
+      rules: result.rules,
+      outputPath: result.outputPath,
+      sessionsDir,
+      metricsDir,
+    };
+  } catch (err) {
+    return { success: false, error: (err && err.message) || String(err) };
+  } finally {
+    // The generator sets process.exitCode = 1 on a miss; restore whatever the
+    // installer process had (fail-open: a dormant engine is not an install error).
+    process.exitCode = savedExitCode;
+    console.log = origLog;
+    console.error = origError;
+  }
+}
+
+module.exports = {
+  installSynapseRuntime,
+  resolveGeneratorPath,
+  GENERATOR_REL_PATH,
+};