sinapse-ai 1.19.2 → 1.20.1

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
 
@@ -752,8 +752,7 @@ outputs/                               # Runtime outputs (gitignored)
 │   ├── engine/                        # Core WIS engines
 │   │   ├── confidence-scorer.js       # Pattern confidence scoring
 │   │   ├── output-formatter.js        # Output formatting
-│   │   ├── suggestion-engine.js       # Intelligent suggestions
-│   │   └── wave-analyzer.js           # Wave pattern analysis
+│   │   └── suggestion-engine.js       # Intelligent suggestions
 │   ├── learning/                      # Machine learning components
 │   │   ├── capture-hook.js            # Pattern capture hooks
 │   │   ├── index.js                   # Learning module entry

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.1",
   "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

@@ -23,6 +23,7 @@ const {
   sanitizeInput,
 } = require('./validation/config-validator');
 const { getMergeStrategy, hasMergeStrategy } = require('../merger/index.js');
+const { atomicWriteFileSync } = require('../utils/atomic-write');
 
 /**
  * Configure environment files (.env and core-config.yaml)
@@ -110,7 +111,8 @@ async function configureEnvironment(options = {}) {
       const merger = getMergeStrategy(envPath);
       const mergeResult = await merger.merge(existingContent, envContent);
 
-      await fs.writeFile(envPath, mergeResult.content, { encoding: 'utf8' });
+      // Atomic (tmp+rename): .env carries user secrets — never leave it torn
+      atomicWriteFileSync(envPath, mergeResult.content, 'utf8');
       results.envCreated = true;
 
       console.log('✅ Merged .env file');
@@ -119,8 +121,8 @@ async function configureEnvironment(options = {}) {
         console.log(`   ⚠️  Suggestions: ${mergeResult.stats.conflicts} (see comments in file)`);
       }
     } else {
-      // Create new or overwrite
-      await fs.writeFile(envPath, envContent, { encoding: 'utf8' });
+      // Create new or overwrite — atomic (tmp+rename)
+      atomicWriteFileSync(envPath, envContent, 'utf8');
       results.envCreated = true;
       console.log('✅ Created .env file');
     }
@@ -133,7 +135,7 @@ async function configureEnvironment(options = {}) {
     // Step 4: Generate and write .env.example
     const envExamplePath = path.join(targetDir, '.env.example');
     const envExampleContent = generateEnvExample();
-    await fs.writeFile(envExamplePath, envExampleContent, { encoding: 'utf8' });
+    atomicWriteFileSync(envExamplePath, envExampleContent, 'utf8');
     results.envExampleCreated = true;
     console.log('✅ Created .env.example file');
 
@@ -187,7 +189,7 @@ async function configureEnvironment(options = {}) {
       throw new Error('Generated core-config.yaml has invalid structure');
     }
 
-    await fs.writeFile(coreConfigPath, coreConfigContent, { encoding: 'utf8' });
+    atomicWriteFileSync(coreConfigPath, coreConfigContent, 'utf8');
     results.coreConfigCreated = true;
     console.log('✅ Created .sinapse-ai/core-config.yaml');
 
@@ -321,6 +323,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());
@@ -353,7 +361,7 @@ async function updateGitignore(targetDir) {
 
     newContent += '\n';
 
-    await fs.writeFile(gitignorePath, newContent, { encoding: 'utf8' });
+    atomicWriteFileSync(gitignorePath, newContent, 'utf8');
   }
 }
 

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/brownfield-upgrader.js

@@ -12,6 +12,7 @@ const yaml = require('js-yaml');
 const semver = require('semver');
 const { hashFile, hashesMatch } = require('./file-hasher');
 const { YamlMerger } = require('../merger/strategies/yaml-merger.js');
+const { atomicWriteFileSync } = require('../utils/atomic-write');
 
 /**
  * Upgrade report structure
@@ -278,8 +279,8 @@ async function applyUpgrade(report, sourceDir, targetDir, options = {}) {
           const merger = new YamlMerger();
           const mergeResult = await merger.merge(sourceContent, targetContent);
 
-          // Write merged content
-          fs.writeFileSync(targetPath, mergeResult.content, 'utf8');
+          // Write merged content — atomic (tmp+rename); backup taken above
+          atomicWriteFileSync(targetPath, mergeResult.content, 'utf8');
 
           // Log conflict warnings
           const conflicts = mergeResult.changes.filter(c => c.type === 'conflict');
@@ -379,7 +380,8 @@ function updateInstalledManifest(targetDir, sourceManifest, sourcePackage) {
 `;
 
   fs.ensureDirSync(path.dirname(installedManifestPath));
-  fs.writeFileSync(installedManifestPath, header + yamlContent, 'utf8');
+  // Atomic (tmp+rename): the installed manifest drives future upgrades
+  atomicWriteFileSync(installedManifestPath, header + yamlContent, 'utf8');
 
   return installedManifestPath;
 }