@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

package/README.md

@@ -1,6 +1,6 @@
 # CodeSDD
 
-CodeSDD e uma evolucao do OpenSpec focada em memoria operacional, planejamento rastreavel e handoff entre agentes.
+CodeSDD e uma plataforma de memoria operacional, planejamento rastreavel e handoff entre agentes.
 
 O objetivo nao e apenas criar specs. O objetivo e permitir que um projeto grande continue compreensivel ao longo do tempo, mesmo quando:
 - novas ideias aparecem no meio da implementacao;
@@ -9,6 +9,30 @@ O objetivo nao e apenas criar specs. O objetivo e permitir que um projeto grande
 - um agente novo entra no repositorio sem contexto previo;
 - o sistema ja existe e precisa ser absorvido sem reler todo o codigo.
 
+## Identidade canonica
+
+CodeSDD e a nomenclatura canonica do produto, do pacote npm e da CLI. O binario
+oficial publicado e `codesdd`. Estruturas historicas de especificacao devem ser
+tratadas como corpus importavel por `codesdd sdd import-legacy-spec`, nunca como
+fonte operacional paralela ao estado `.sdd`.
+
+O relatorio formal de revisao, mapa de referencias, plano de migracao,
+excecoes e exemplos por tipo de comando ficam em
+[docs/codesdd-formal-review.md](docs/codesdd-formal-review.md).
+
+Backlog provider integration is documented as a projection-only boundary in
+[docs/backlog-provider-integration.md](docs/backlog-provider-integration.md):
+Azure DevOps is the first provider target, and `.sdd/state/*.yaml` remains the
+canonical operational state.
+
+## Creditos, notices e posicionamento
+
+Os documentos canonicos desta fronteira ficam em `docs/`:
+
+- [docs/CREDITS.md](docs/CREDITS.md): reconhecimento conceitual e fronteira clean-room (fora do fluxo operacional).
+- [docs/THIRD_PARTY_NOTICES.md](docs/THIRD_PARTY_NOTICES.md): notices tecnicos/licencas para dependencias runtime.
+- [positioning.md](positioning.md): narrativa de posicionamento enterprise do CodeSDD.
+
 ## O que o CodeSDD faz
 
 O CodeSDD organiza o desenvolvimento em 4 camadas:
@@ -42,11 +66,96 @@ O CodeSDD organiza o desenvolvimento em 4 camadas:
 - Artefatos tecnicos de compatibilidade, historicos ou produto nao substituem o estado CodeSDD.
 - Se uma anotacao legada tiver informacao util, migre a decisao para CodeSDD e remova ou depreque o legado.
 
+## Arquitetura DeepAgents governada (FEAT-0240)
+
+Para a iniciativa EPIC-0065, o projeto formaliza a seguinte fronteira canonica:
+
+- CodeSDD e o control plane soberano: estado canonico (`.sdd/state/*.yaml`), lifecycle, EPIC/FEAT, ADR, politicas, qualidade, evidencia e finalize.
+- DeepAgents e execution plane governado: planejamento tatico, delegacao de subagentes, execucao em sandbox, memoria tatica controlada e coleta de evidencia estruturada.
+- Plugins operam como plano de construcao deterministico via broker e envelopes; Reversa opera como pipeline especializado de engenharia reversa.
+- Planos de plugin standalone validam `package_governance`, runtime de linguagem e fronteira de storage antes de qualquer adaptador tratar a operacao como executavel.
+- O core agora possui uma casca Foundation-like incremental em `src/domains`, `src/applications`, `src/infrastructures`, `src/presentations` e `src/shared`; detalhes em `docs/codesdd-foundation-layer-migration.md`.
+- Gates de qualidade para SDK/agentes/plugins agregam governanca de pacote, runtime de linguagem, artifact map, planos DeepAgents/Codex/OpenCode, compliance de plugin e cobertura por escopo em `src/core/sdd/sdk-agent-plugin-quality-gates.ts`.
+- Nenhum runtime de agente pode virar fonte paralela de verdade para o estado operacional do projeto.
+
+Pacote ADR obrigatorio da iniciativa:
+
+1. Adocao oficial do runtime DeepAgents governado.
+2. Fronteira control plane (CodeSDD) vs execution plane (DeepAgents).
+3. Autoridade de filesystem/memoria e regra sem fonte paralela de estado.
+4. Politica de sandbox e worktree isolada.
+5. Politica HITL e mapeamento de `interrupt_on`.
+6. Interoperabilidade com plugin broker.
+7. Interoperabilidade MCP e exposicao de ferramentas.
+8. Interoperabilidade Reversa e evidencia de engenharia reversa.
+9. Politica de execucao autonoma por tiers de risco.
+10. Politica de `.env`, segredos e fingerprint de configuracao.
+11. Contratos de evidencia estruturada e retencao.
+
+O ADR charter desta formalizacao esta em `.sdd/core/adrs/ADR-FEAT-0240.md`.
+
+O runtime DeepAgents e opt-in. A configuracao segura permanece desligada por
+padrao (`CODESDD_DEEPAGENTS_ENABLED=false` e
+`CODESDD_DEEPAGENTS_RUNTIME=disabled`), com modo `fake` para testes
+deterministicos sem credenciais e modo `deepagents-js` para a implementacao
+nativa Node/TypeScript carregada sob politica, HITL e contrato de modelo.
+O pacote npm `deepagents` e carregado de forma dinamica, apenas quando esse
+modo real passa nos checks de prontidao.
+A fronteira Node/TypeScript passa pela factory
+`src/core/sdd/deepagents/runtime-factory.ts`, que entrega adapters separados
+para `disabled`, `fake` e `deepagents-js` sem transformar DeepAgents em fonte
+canonica de estado.
+As tools CodeSDD para DeepAgents sao uma projecao governada do registro MCP em
+`src/core/sdd/deepagents/codesdd-tools.ts`, e o enforcement de env, rede, HITL e
+writes planejados passa por `src/core/sdd/deepagents/policy-enforcement.ts`
+antes de qualquer instanciacao real.
+As saidas do runtime sao normalizadas por
+`src/core/sdd/deepagents/evidence-mapper.ts` para os contratos
+`deepagent-run-*`, `deepagent-tool-call-*`, `deepagent-subagent-*`,
+`deepagent-decision-*` e `deepagent-quality-*`.
+O comando `codesdd sdd agent run <FEAT-ID> --provider deepagents` ja consome
+essa fronteira TypeScript: no modo `disabled`, ele registra evidencia de runtime
+bloqueado sem instanciar agente; no modo `fake`, executa o adapter
+deterministico sem credenciais; e no modo `deepagents-js`, so materializa o
+adapter nativo quando os feature toggles, modelo, credencial de launcher e
+politicas passam. Falhas de prontidao viram evidencia estruturada fail-closed.
+Para validar uma mudanca antes de invocar runtime, use
+`codesdd sdd preflight <FEAT-ID> --intent-operation <op> --write-scope <glob> --planned-writes <path> --json`.
+Esse comando executa os mesmos guardrails de mutacao com `runtime_skipped: true`
+e emite telemetria segura em `evidence.guardrail_telemetry`, contendo apenas
+decisao, status por gate, nivel de risco e classificacoes agregadas, sem paths
+brutos, texto de objetivo ou valores de override. Os cenarios golden de
+EPIC-0078 cobrem catalogo aditivo permitido, substituicao bloqueada, override
+valido, override invalido e refactor amplo legitimo.
+O smoke operacional padrao esta em `pnpm run test:deepagents-smoke`, cobrindo
+`disabled` e `fake` sem segredos nem rede; o smoke real de provedor so roda com
+`CODESDD_DEEPAGENTS_PROVIDER_SMOKE=1`, modelo, chave de launcher e dominio de
+rede explicitamente liberado.
+Para diagnostico local, `codesdd config doctor --json` executa preflight
+operacional e reporta status `disabled|ready|blocked` para runtime/provider,
+modelo, variaveis obrigatorias, endpoint e politica de rede sem imprimir
+credenciais.
+Modelos hospedados na Azure e endpoints OpenAI-compatible usam provider
+profiles governados (`azure-openai:`, `azure-ai:`, `openai-compatible:`,
+`xai:`/`grok:`, `moonshot:`/`kimi:` e `cohere:`/`coyers:`). Credenciais e
+endpoints podem vir de variaveis nomeadas por
+`CODESDD_DEEPAGENTS_CREDENTIAL_ENV` e `CODESDD_DEEPAGENTS_ENDPOINT_ENV`; o
+CodeSDD registra apenas nomes, presenca e fingerprints, nunca valores de
+segredo.
+Saidas de diagnostico/configuracao tambem aplicam redaction por chave sensivel
+(`*key*`, `*secret*`, `*token*`, `*password*`, `*credential*`, `*private*`,
+`*auth*`) para evitar leakage acidental em stdout, JSON e contratos de
+evidencia.
+Para Azure OpenAI, aliases de deployment divergentes (`AZURE_OPENAI_DEPLOYMENT`
+vs `AZURE_OPENAI_DEPLOYMENT_NAME`) entram em fail-fast e bloqueiam o runtime;
+a precedencia valida usa `AZURE_OPENAI_DEPLOYMENT_NAME`, depois
+`AZURE_OPENAI_DEPLOYMENT`, depois `AZURE_OPENAI_API_DEPLOYMENT_NAME`.
+
 ## Coordenacao opcional com Redis
 
 Redis e uma fronteira opcional para coordenacao tecnica de locks, cache, filas e eventos. Ele nao substitui a autoridade operacional de `.sdd/state/*.yaml`.
 
-Por padrao, CodeSDD usa locks em filesystem e adaptadores em memoria para cache, filas e eventos. A fabrica `createFilesystemFirstCoordinationAdapters` em `src/core/sdd/coordination/` mantem esse comportamento mesmo quando Redis e solicitado, ate que um adaptador Redis real seja instalado.
+Por padrao, CodeSDD usa locks em filesystem, cache L1 em memoria e cache L2 em `~/.codesdd/cache/projects/<fingerprint>/coordination`. Quando Redis esta configurado e responde a ping, o runtime usa o cliente oficial `redis` para operar em modo `hybrid`: L1 em memoria, Redis como acelerador/coordenador distribuido e filesystem como fallback descartavel.
 
 Variaveis reconhecidas:
 
@@ -54,14 +163,47 @@ Variaveis reconhecidas:
 - `REDIS_URL`: fallback quando `CODESDD_REDIS_URL` nao estiver definida.
 - `CODESDD_REDIS_ENABLED=true`: marca Redis como solicitado mesmo sem URL.
 - `CODESDD_REDIS_NAMESPACE`: namespace logico; padrao `codesdd`.
+- `CODESDD_REDIS_TLS=true`: ativa TLS quando a URL nao usar `rediss://`.
+- `CODESDD_REDIS_FALLBACK=filesystem|none`: controla degradacao quando Redis falha.
+- `CODESDD_REDIS_CONNECT_TIMEOUT_MS`, `CODESDD_REDIS_COMMAND_TIMEOUT_MS`, `CODESDD_REDIS_MAX_RETRIES`, `CODESDD_REDIS_CACHE_TTL_MS`, `CODESDD_REDIS_LOCK_TTL_MS`.
+
+Exemplo seguro em `~/.codesdd/config.toml`:
+
+```toml
+[redis]
+enabled = true
+url_env = "CODESDD_REDIS_URL"
+namespace = "codesdd"
+fallback = "filesystem"
+connect_timeout_ms = 500
+command_timeout_ms = 1000
+max_retries = 2
+cache_default_ttl_ms = 300000
+lock_ttl_ms = 30000
+stream_max_len = 10000
+```
 
-Enquanto o cliente Redis nao existir no runtime, o status exposto e `requested-unavailable` e os defaults filesystem-first continuam autoritativos.
+Mantenha a URL real no shell, password manager ou secret store do CI:
+
+```bash
+export CODESDD_REDIS_URL="redis://localhost:6379"
+```
+
+`codesdd config doctor --json` e `codesdd config redis status --json` reportam `disabled`, `requested-unavailable`, `ready`, `degraded` ou `blocked` sem imprimir usuario, senha ou token da URL. Operacoes adicionais:
+
+- `codesdd config redis ping`
+- `codesdd config redis bench --iterations 20`
+- `codesdd config redis flush-namespace --yes`
+
+Redis nunca deve armazenar estado canonico do projeto, chaves de API, tokens, senhas, respostas cruas de providers ou dados pessoais. Use `docs/redis-operations.md` para o runbook completo.
 
 ## Contrato de nomenclatura
 
-O contrato canonico de identidade do produto vive em `.sdd/state/naming-contract.yaml`.
-Ele declara a identidade atual, a identidade alvo, as regras de rename por fase e
-o gate de residuo zero usado por `codesdd sdd scan-naming`.
+O contrato canonico de identidade do produto vive em `.sdd/state/naming-contract.yaml`
+quando persistido no projeto; se o arquivo ainda nao existir, a CLI usa o
+contrato padrao de CodeSDD definido em `src/core/sdd/state.ts`. Ele declara a
+identidade atual, a identidade alvo, as regras de rename por fase e o gate de
+residuo zero usado por `codesdd sdd scan-naming`.
 
 Durante a migracao para CodeSDD, esse contrato permite manter uma janela de
 compatibilidade rastreavel sem perder o objetivo final: remover termos legados
@@ -92,18 +234,18 @@ Depois do bootstrap, o projeto passa a ter:
 - `.sdd/planning/`
 - `.sdd/active/`
 - `.sdd/archived/`
-- `.sdd/templates/`
+- `.sdd/templates/` (YAML workspace templates)
 - `.sdd/skills/curated/`
 - `.sdd/sources/`
 - `.sdd/prompts/`
 
-Projetos CodeSDD-native nao devem criar `openspec/` como estrutura operacional.
-Quando um projeto legado ainda tiver `openspec/`, importe o corpus para
-`.sdd/sources/legacy/spec-corpus` com `codesdd sdd import-openspec` antes de
+Projetos CodeSDD-native nao devem criar `legacy-spec/` como estrutura operacional.
+Quando um projeto legado ainda tiver `legacy-spec/`, importe o corpus para
+`.sdd/sources/legacy/spec-corpus` com `codesdd sdd import-legacy-spec` antes de
 remover a pasta antiga. O acesso de compatibilidade a esse corpus deve passar
 pelo servico CodeSDD de legacy capability em
 `src/core/sdd/services/legacy-capability.service.ts`; utilitarios antigos, como
-`src/utils/openspec-compat.ts`, existem apenas como shim.
+`src/utils/legacy-spec-compat.ts`, existem apenas como shim.
 
 Dentro de `.sdd/` ficam:
 
@@ -127,8 +269,7 @@ A instalacao global oficial e feita via npm:
 npm install -g @devtrack-solution/codesdd
 ```
 
-O binario oficial publicado pelo pacote e `codesdd`. Durante a janela de
-compatibilidade, `codesdd` continua publicado como shim. Depois de instalar,
+O binario principal publicado pelo pacote e `codesdd`. Depois de instalar,
 confira:
 
 ```bash
@@ -137,6 +278,39 @@ codesdd --version
 
 Se o terminal nao encontrar `codesdd`, a instalacao provavelmente foi concluida, mas o diretorio global do npm nao esta no `PATH` da sua sessao. Nesses casos, adicione o alias abaixo para o seu sistema operacional.
 
+### Configuracao global do CodeSDD
+
+- Caminho canonico: `~/.codesdd/config.toml`
+- Compatibilidade de leitura: `~/.config/codesdd/config.json` (somente fallback)
+- O comando `codesdd config path` sempre exibe o caminho canonico atual.
+- Cache global: `~/.codesdd/cache` com tiers logicos `providers`, `projects`, `schemas`, `deepagents` e `plugins`.
+- O tier `projects` usa fingerprint por raiz de projeto para evitar colisao de cache entre repositorios.
+- `codesdd config init` cria/normaliza `~/.codesdd/config.toml`, `~/.codesdd/cache/**` e `~/.codesdd/env.zsh` com conteudo nao secreto.
+- Em shell Zsh, `codesdd config init` garante um bloco idempotente no `~/.zshrc` para `source ~/.codesdd/env.zsh`.
+- A fronteira funcional e validavel: estado versionado do projeto fica em `.sdd`; config/runtime/cache comum fica em `~/.codesdd`; `.codesdd` dentro do repositorio e invalido para novo estado.
+- `codesdd config doctor --json` expoe `storage_boundary` com `project_state_dir`, `global_runtime_dir`, `global_cache_dir`, tiers de cache e regras de separacao.
+- `codesdd sdd plugin plan --project-root <path>` reutiliza essa fronteira para bloquear writes de plugin em `.codesdd` local e expor `workcell_runner.standalone.storage_boundary`.
+- O perfil gerado por `codesdd config init` e fail-closed: DeepAgents fica
+  desabilitado, runtime `disabled`, provider smoke `0` e rede `disabled` ate
+  que um operador habilite explicitamente um provedor live.
+
+Fluxo seguro recomendado:
+
+```bash
+codesdd config init
+codesdd config path
+codesdd config list
+codesdd config doctor --json
+```
+
+Para validar o modo deterministico sem credenciais:
+
+```bash
+CODESDD_DEEPAGENTS_ENABLED=true \
+CODESDD_DEEPAGENTS_RUNTIME=fake \
+codesdd config doctor --json
+```
+
 ### Windows PowerShell
 
 ```powershell
@@ -148,13 +322,6 @@ Add-Content $PROFILE "`nfunction codesdd { & '$target' @args }"
 codesdd --version
 ```
 
-Se voce tambem precisar manter scripts legados que chamam `openspec`, adicione o alias de compatibilidade no mesmo perfil:
-
-```powershell
-Add-Content $PROFILE "`nfunction openspec { codesdd @args }"
-. $PROFILE
-```
-
 ### Linux
 
 Para Bash:
@@ -175,14 +342,6 @@ printf "\nalias codesdd='%s'\n" "$(npm prefix -g)/bin/codesdd" >> ~/.zshrc
 codesdd --version
 ```
 
-Alias legado opcional:
-
-```bash
-printf "\nalias openspec='codesdd'\n" >> ~/.bashrc
-# ou, se usar Zsh:
-printf "\nalias openspec='codesdd'\n" >> ~/.zshrc
-```
-
 ### macOS / MacBook
 
 O shell padrao atual do macOS e Zsh:
@@ -194,12 +353,6 @@ printf "\nalias codesdd='%s'\n" "$(npm prefix -g)/bin/codesdd" >> ~/.zshrc
 codesdd --version
 ```
 
-Alias legado opcional para comandos antigos:
-
-```bash
-printf "\nalias openspec='codesdd'\n" >> ~/.zshrc
-```
-
 Se voce estiver desenvolvendo este fork localmente:
 
 ```bash
@@ -213,10 +366,24 @@ Atalhos uteis de manutencao local:
 ```bash
 pnpm run cleanup
 pnpm run cleanup:install
+pnpm run quality:review
 ```
 
 - `cleanup`: remove artefatos de build/cache local, rastros de ambiente (`.DS_Store`, `.idea/`, `.claude/`), stores legados de contexto local e logs de falha de compilacao/execucao.
 - `cleanup:install`: faz a limpeza acima e tambem remove `node_modules/` e lockfiles alternativos locais (`package-lock.json`, `yarn.lock`, `bun.lock*`), preservando o `pnpm-lock.yaml` versionado.
+- `quality:review`: executa build, lint, testes, cobertura, validacao SDD e pack-version sem remover `node_modules/` nem executar `pnpm install`; use em revisoes/auditorias que nao devem limpar o workspace.
+
+Antes de release, gere o resumo nao mutante de prontidao:
+
+```bash
+codesdd sdd release-readiness --strict
+```
+
+O comando verifica saude SDD, FEATs ativos, scripts de CI parity, metadata do
+pacote, fronteira de `.npmrc`, allowlist de publicacao, varredura de segredos
+de alta confianca, proveniencia/SBOM, smoke de instalacao via tarball com
+bootstrap da CLI, plano de rollback com `npm deprecate`, schemas essenciais e
+docs de release/seguranca.
 
 ## Como iniciar em um projeto novo
 
@@ -274,7 +441,7 @@ Atalhos em portugues no CLI:
 Se o projeto ja esta em andamento, o primeiro passo depois do `install` e inicializar o contexto:
 
 ```bash
-codesdd sdd init-context
+codesdd sdd init-context --frontend --lang en-US --layout en-US
 codesdd sdd check --render
 codesdd sdd onboard system
 ```
@@ -288,6 +455,13 @@ O `init-context` serve para:
 
 Em projetos grandes, esse bootstrap inicial nao substitui consolidacao progressiva. Ele cria uma base inicial para que o processo passe a evoluir de forma rastreavel.
 
+Para reconfigurar um projeto ja inicializado com os artefatos, templates, skills
+e views da versao instalada do CLI, use:
+
+```bash
+codesdd reload --tools none --lang en-US --layout en-US
+```
+
 ## Como usar no dia a dia
 
 Fluxo principal:
@@ -328,16 +502,16 @@ contadores e pode ser executado em `--dry-run` antes de gravar.
 Para absorver o corpus legado de especificacoes antes da remocao da pasta formal:
 
 ```bash
-codesdd sdd import-openspec --dry-run
-codesdd sdd import-openspec
-codesdd sdd import-openspec --remove --yes
+codesdd sdd import-legacy-spec --dry-run
+codesdd sdd import-legacy-spec
+codesdd sdd import-legacy-spec --remove --yes
 ```
 
-O `import-openspec` copia todos os arquivos de `openspec/` para
+O `import-legacy-spec` copia todos os arquivos de `legacy-spec/` para
 `.sdd/sources/legacy/spec-corpus`, calcula SHA-256 e tamanho de cada fonte,
 registra cada item em `.sdd/state/source-index.yaml` e grava um relatorio em
-`.sdd/sources/legacy/spec-corpus/_codesdd-import-report.yaml`. A opcao `--remove`
-so e aceita junto de `--yes` e remove `openspec/` apenas depois de concluir a
+`.sdd/sources/legacy/spec-corpus/_legacy-spec-import-report.yaml`. A opcao `--remove`
+so e aceita junto de `--yes` e remove `legacy-spec/` apenas depois de concluir a
 copia e a verificacao de checksum.
 
 If there is no ready FEAT, onboarding now returns guided steps such as creating an insight, opening a debate, deciding, and breaking down an EPIC instead of leaving `next_steps` empty.
@@ -348,6 +522,19 @@ If there is no ready FEAT, onboarding now returns guided steps such as creating
 codesdd sdd next
 ```
 
+Para operar o plano sem adivinhar, use:
+
+```bash
+codesdd sdd plan-status
+codesdd sdd execute-next --dry-run
+codesdd sdd execute-next
+```
+
+`plan-status` mostra FEATs ativas, a proxima lista ranqueada e a acao
+recomendada. `execute-next` usa o mesmo ranking de `next` e chama `sdd start`
+para a primeira FEAT pronta; use `--dry-run` para auditar a escolha sem mudar
+estado.
+
 Auditar a saude de evolucao do proprio processo SDD (ciclo recomendado: semestral):
 
 ```bash
@@ -448,19 +635,112 @@ workspace ativa.
 codesdd sdd context FEAT-0001
 ```
 
-4.1 Expor o bridge MCP para agentes externos
+Para reduzir consumo de contexto, `sdd context` aceita modos de budget:
+`--budget compact`, `--budget standard` e `--budget full` (`--compact` e
+`--full` sao atalhos). O modo `compact` preserva os campos principais e reduz
+listas grandes como `read_order`, `core_docs`, contratos, servicos e
+predecessores; a resposta inclui `context_budget` com estimativa de caracteres
+e campos truncados. Antes de truncar, listas conhecidas passam por dedupe
+deterministico, preservando a primeira ocorrencia e registrando a reducao em
+`context_budget.deduped_fields`.
+
+Quando o budget omite itens, a resposta tambem inclui
+`progressive_disclosure`, com contagem por campo e um `reveal_command` para
+reemitir o contexto completo (`codesdd sdd context <REF> --full --json`). Isso
+permite usar o pacote compacto como plano inicial sem perder a trilha de como
+expandir detalhes sob demanda.
+
+O pacote budgetado tambem usa cache descartavel em
+`~/.codesdd/cache/projects/<project-fingerprint>/context-summary`, isolado pelo
+fingerprint do projeto e por um fingerprint dos arquivos `.sdd/state` e da
+workspace da entidade. A resposta inclui `context_cache` com `hit`, `key`,
+`project_fingerprint` e `source_fingerprint`; quando a fonte muda, a chave muda
+e o pacote e recalculado.
+
+Quando a tarefa depende de economia de contexto, registre a medicao em
+`5-quality.yaml` usando `token_budget_gates.telemetry`. O gate aceita
+`budget_chars`, `actual_chars`, `efficiency_percent`, `gate` e `evidence_ref`;
+o Q95 usa a pior eficiencia estruturada e trata `gate: fail` ou eficiencia
+abaixo de `fail_below_percent` como bloqueio de qualidade.
+
+Para estabilizar validacoes longas, `5-quality.yaml` tambem aceita
+`runtime_quality_gates`. Use `performance[]` para registrar duracao, p95,
+memoria ou CPU com `threshold`, `actual` e `gate`; use `flakiness[]` para
+registrar `attempts`, `failures` ou `failure_rate_percent`. Quando houver
+telemetria, o Q95 incorpora o pior sinal de performance/flakiness no eixo de
+integridade; sem telemetria, o score permanece neutro para manter compatibilidade
+com workspaces antigos.
+
+4.1 Expor a fundacao MCP para agentes externos
+
+No repositorio local, use o entrypoint versionado do checkout atual para validar
+o contrato antes de empacotar ou publicar:
+
+```bash
+node bin/codesdd.js --no-telemetry sdd mcp-manifest --provider codex --json
+node bin/codesdd.js --no-telemetry sdd mcp-call codesdd.next --provider claude-code --json
+node bin/codesdd.js --no-telemetry sdd mcp-call codesdd.context --provider open-code --ref FEAT-0001 --json
+node bin/codesdd.js --no-telemetry sdd mcp-call codesdd.finalize --provider kimmy-code --ref FEAT-0001 --json
+```
+
+Depois da instalacao, os mesmos contratos ficam disponiveis pelo binario
+publico:
+
+```bash
+codesdd sdd mcp-manifest --provider codex --json
+codesdd sdd mcp-call codesdd.context --provider codex --ref FEAT-0001 --json
+```
+
+### Codex Live seguro
+
+Para Codex, os prompts sao gerados no home global do cliente
+(`$CODEX_HOME/prompts` ou `~/.codex/prompts`) e nao viram fonte operacional do
+projeto. O estado canonico continua em `.sdd/state/*.yaml`.
+
+Exemplo de configuracao local sem provedor live:
 
 ```bash
+codesdd install --tools codex
+codesdd config init
 codesdd sdd mcp-manifest --provider codex --json
-codesdd sdd mcp-call codesdd.next --provider claude-code --json
-codesdd sdd mcp-call codesdd.context --provider open-code --ref FEAT-0001 --json
-codesdd sdd mcp-call codesdd.finalize --provider kimmy-code --ref FEAT-0001 --json
+codesdd sdd mcp-call codesdd.next --provider codex --json
 ```
 
-O bridge MCP do CodeSDD e agnóstico a provedor e publica um envelope estável
-para `codesdd.next`, `codesdd.context` e `codesdd.finalize`, cobrindo Codex,
-Claude Code, Kimmy Code, Kilo Code, Open Code e clientes genéricos sem criar
-um estado paralelo fora do workspace canônico.
+Exemplo de smoke live OpenAI, com credencial somente no launcher:
+
+```bash
+export CODESDD_DEEPAGENTS_PROVIDER_SMOKE=1
+export CODESDD_AGENT_PROVIDER=deepagents
+export CODESDD_DEEPAGENTS_ENABLED=true
+export CODESDD_DEEPAGENTS_RUNTIME=deepagents-js
+export CODESDD_DEEPAGENTS_MODEL=openai:gpt-4o-mini
+export CODESDD_AGENT_NETWORK_POLICY=restricted
+export CODESDD_AGENT_ALLOWED_DOMAINS=api.openai.com
+export OPENAI_API_KEY="<secret-from-manager>"
+codesdd config doctor --json
+```
+
+A fundacao MCP do CodeSDD e agnostica a provedor e publica o envelope
+`codesdd-mcp-bridge/v1` para as ferramentas canonicas `codesdd.next`,
+`codesdd.context`, `codesdd.query`, `codesdd.read` e os demais nomes
+`codesdd.*` documentados pelo manifest.
+
+Agent Runtime v2 exporta planos de comando para DeepAgents, Codex exec e
+OpenCode run. Para OpenCode, o contrato
+`agent-runtime-opencode-run-evidence.schema.json` registra execucao,
+artefatos, validacoes e trechos redigidos sem permitir escrita direta em
+estado SDD; o `finalize` do CodeSDD continua sendo o unico escritor canonico
+do ciclo de vida.
+
+Perfis aceitos por `--provider`: `codex`, `claude-code`, `kimmy-code`,
+`kilo-code`, `open-code` e `generic`. Para OpenCode/Open Code, o bridge MCP usa
+o identificador `open-code`; `opencode` aparece em contratos antigos de
+agent-binding e nao e aceito por `sdd mcp-manifest` neste runtime.
+
+Matriz de provedores: consulte
+[docs/mcp-provider-compatibility.md](docs/mcp-provider-compatibility.md),
+mantida por FEAT-0164/Worker 4, para a tabela de clientes, IDs MCP, aliases,
+evidencias esperadas e a diferenca entre `open-code` e `opencode`.
 
 5. Implementar
 
@@ -474,6 +754,16 @@ Se você já estiver dentro de `.sdd/active/FEAT-####/`, o `finalize` também po
 inferir a FEAT alvo sem `--ref`, priorizando o workspace ativo atual antes de
 cair para a fila pendente padrão.
 
+Após consolidar uma FEAT, o resultado de `sdd finalize` inclui
+`post_finalize_replan` com as próximas FEATs prontas, ondas e contagens de
+bloqueios/conflitos recalculadas a partir do estado canônico. Em saída texto, o
+CLI mostra as primeiras próximas FEATs para orientar execução encadeada.
+
+`.sdd/state/finalize-queue.yaml` separa fila ativa de historico: `items` guarda
+somente finalizacoes `PENDING`, enquanto `history` guarda finalizacoes `DONE`.
+O `check` reporta pendentes e concluidas separadamente, e a view
+`.sdd/planning/finalize-queue.md` mostra a fila ativa mais o historico recente.
+
 Quando `requires_adr: true` ou o `2-plan.yaml` ativo declara impacto
 arquitetural sensivel, o `finalize` exige ADR existente e válido pela lente `adr`
 (seções `Contexto`, `Decisão`, `Consequências` e sem frase proibida de
@@ -490,6 +780,24 @@ contrato operacional das skills: registre uma entrada em
 Sem esse rastro, o fluxo fica bloqueado como qualquer outra evidência de
 qualidade obrigatória.
 
+O `2-plan.yaml` gerado inclui `governance`, que declara a fronteira canônica
+`codesdd-canonical-sdd-state`, os artefatos de planejamento envolvidos, refs de
+decisão, escritas de estado previstas, plano de rollback e gates de validação.
+O schema aceita workspaces históricos sem esse bloco por compatibilidade, mas
+novos planos devem manter esse contrato preenchido.
+
+O mesmo `2-plan.yaml` também inclui `execution_plan`, que explicita se a FEAT
+roda como `single-feature`, `parallel-wave` ou `chained-features`, sempre com
+`state_boundary_ref: codesdd-canonical-sdd-state`. O plano lista comandos,
+quais passos podem escrever estado, `allowed_state_writes`, escritas proibidas
+como `.codesdd/**` e os artefatos de handoff esperados. Planos de automação
+paralela exportados em `schemas/sdd/parallel-feat-automation-plan.schema.json`
+carregam a mesma fronteira para que execução encadeada não crie estado oculto.
+O scheduler encadeado consome FEATs com `blocked_by`, `status` e `lock_domains`,
+trata predecessores `DONE` como âncoras já satisfeitas, divide ondas para evitar
+locks concorrentes e reporta dependências não agendáveis no resultado exportado
+em `schemas/sdd/parallel-feat-scheduler-result.schema.json`.
+
 O `5-quality.yaml` agora também precisa fechar a rastreabilidade viva da
 workspace: preencha `traceability.spec_anchor` com o `updated_at` atual do
 `1-spec.yaml`, referencie a entrada correspondente do `4-changelog.yaml`, e
@@ -498,6 +806,11 @@ requisito -> `code_refs` -> `test_refs` -> `evidence_refs`. O `finalize`,
 `check` e `diagnose` passam a bloquear ou sinalizar drift quando a spec muda e
 esse vínculo não é revisitado.
 
+O ledger `q95_ledger` limita todos os percentuais a `0..100`, exige pesos que
+somam `100` e impede `status: pass` quando `score` fica abaixo de `threshold`.
+Isso mantém o Q95 auditável antes de qualquer automação de release ou execução
+encadeada consumir o resultado.
+
 O `finalize` também executa validação pós-active de lifecycle: a FEAT não pode
 ter cópia semântica em `.sdd/archive/<FEAT-ID>`, deve sair de `.sdd/active/` e
 deve aparecer uma única vez em `.sdd/archived/<FEAT-ID>`. `sdd check` e
@@ -635,7 +948,9 @@ The SDD bootstrap installs local curation in:
 .sdd/skills/curated/
 ```
 
-The default curation currently includes 66 skills across 8 bundles (canonical source: `.sdd/state/skill-catalog.yaml`).
+The default curation currently includes 79 skills across 11 bundles (canonical source: `.sdd/state/skill-catalog.yaml`).
+Skill catalog entries now follow the v2 metadata contract with `token_budget`, `integrity_hash`, `deterministic_pair`, `deprecated_at`, and `superseded_by` for routing governance and lifecycle traceability.
+`codesdd sdd skills sync` now enforces SHA-256 drift detection by layer: canonical curated skills block sync on `missing/modified` manifest hash, while user-extension skills emit non-blocking alerts so local customization remains possible.
 
 Entre elas:
 
@@ -646,8 +961,22 @@ Entre elas:
 - `planning-normalizer-sdd`
 - `api-clean-flask-langgraph` (bundle `python-agentic-backend`)
 - `devtrack-api` (bundle `architecture-backend`, canonical DevTrack/NestJS/TypeORM API architecture)
+- `devtrack-angular` (bundle `frontend-product`, canonical DevTrack Angular Admin architecture)
+- `devtrack-flutter` (bundle `frontend-product`, canonical DevTrack Flutter/Dart architecture)
+
+Skill routing is operational, not decorative. When `codesdd sdd context <FEAT-ID>` returns `recommended_skills`, or when a user explicitly directs a skill, the agent must read and follow that skill before implementation and record one `skill_evidence` entry per required skill in `.sdd/active/<FEAT-ID>/5-quality.yaml` before finalize. For API/backend work without an explicit alternative skill/profile, `devtrack-api` is the default architecture and naming source. Angular Admin/backoffice work that names admin pages, dashboards, CRUD, data grids, admin Formly, admin NGXS/state, official Angular framework patterns, permissions, reports, workflow, admin realtime, or admin chat uses `devtrack-angular`. Flutter/Dart work that names Flutter apps, widgets, routing, localization, responsive layout, JSON, HTTP, previews, widget tests, integration tests, go_router, ARB, or l10n uses `devtrack-flutter`. Explicit Python/Flask API work remains routed to `api-clean-flask-langgraph`.
+
+The `devtrack-api` skill has a Foundation-layout conformance test. When the Foundation checkout is not at `/Volumes/WORKSPACE/DEVTRACK_TOOLS/devtrack-foundation-api`, set `CODESDD_FOUNDATION_API_ROOT=/path/to/devtrack-foundation-api` before running `pnpm test -- test/specs/devtrack-api-foundation-layout.test.ts`.
+
+The executable `devtrack-api` contract pack lives in `.sdd/skills/curated/devtrack-api/references/contract-pack.yaml`. It defines the `prototype`, `foundation-compatible`, and `enterprise-strict` profiles, P0/P1/P2 severity semantics, early package-preview expectations, import/alias and TypeORM drift rules, and the `codesdd-validate` plus field-evidence drift maps consumed by later governance gates.
+
+The executable `devtrack-angular` contract pack lives in `.sdd/skills/curated/devtrack-angular/references/contract-pack.yaml`. It defines portable agent adapters, `prototype`, `production-admin`, and `enterprise-admin` profiles, pages-first Angular Admin architecture rules, Formly/NGXS/realtime/admin gates, official Angular skills mapping, and evidence expectations for Angular Admin delivery.
 
-Skill routing is operational, not decorative. When `codesdd sdd context <FEAT-ID>` returns `recommended_skills`, or when a user explicitly directs a skill, the agent must read and follow that skill before implementation and record one `skill_evidence` entry per required skill in `.sdd/active/<FEAT-ID>/5-quality.yaml` before finalize. For DevTrack/Foundation backend API work, `devtrack-api` is the canonical architecture and naming source.
+The executable `devtrack-flutter` contract pack lives in `.sdd/skills/curated/devtrack-flutter/references/contract-pack.yaml`. It defines portable agent adapters, `prototype`, `production-flutter`, and `enterprise-flutter` profiles, layered Flutter architecture rules, routing/localization/layout/data/test gates, official Flutter skills mapping, and evidence expectations for Flutter/Dart delivery.
+
+Consumer copies of `devtrack-api` are one-way CodeSDD materializations, not durable edit targets. The sync policy lives in `.sdd/skills/curated/devtrack-api/references/consumer-sync-policy.md`: update the consumer project through its CodeSDD update/bootstrap flow, compare the consumer copy with the canonical CodeSDD source, and record source version plus diff evidence in the consumer FEAT quality or handoff.
+
+Field validation for `devtrack-api` is governed by `.sdd/skills/curated/devtrack-api/references/field-validation-protocol.md`. A consumer project must keep its own evidence showing at least two detailed implementation debates and closure of divergence classes D-01 through D-08; CodeSDD keeps the protocol and external reference, not private consumer ledgers.
 
 Prompts recomendados tambem sao instalados em:
 
@@ -682,7 +1011,9 @@ Bootstrap:
 
 - `codesdd install --tools none`
 - `codesdd install --tools all`
+- `codesdd reload --tools none`
 - `codesdd sdd init-context`
+- `codesdd sdd init-context --frontend --lang en-US --layout en-US`
 - `codesdd sdd check --render`
 - `codesdd sdd check --render --strict`
 - `codesdd sdd diagnose`
@@ -710,6 +1041,8 @@ Onboarding e operacao:
 - `codesdd sdd orientar system`
 - `codesdd sdd next`
 - `codesdd sdd next --max-agents <N>` (limita o tamanho da primeira onda e lista itens adiados)
+- `codesdd sdd plan-status`
+- `codesdd sdd execute-next --dry-run`
 - `codesdd sdd start FEAT-0001 --fluxo direto|padrao|rigoroso`
 - `codesdd sdd aprovar FEAT-0001 --etapa proposta|planejamento|tarefas`
 - `codesdd sdd context FEAT-0001`
@@ -769,7 +1102,8 @@ O comando global oficial deste fork e:
 codesdd
 ```
 
-O caminho de distribuicao oficial deste repositorio e npm. Veja a secao [Instalacao global](#instalacao-global) para instalar globalmente e configurar o alias por sistema operacional.
+O caminho de distribuicao oficial deste repositorio e npm. Veja a secao
+[Instalacao global](#instalacao-global) para instalar globalmente.
 
 ```bash
 npm install -g @devtrack-solution/codesdd
@@ -801,7 +1135,7 @@ O CLI possui telemetria anônima de uso com desenho privacy-first:
 
 - sem captura de argumentos, conteúdo ou caminhos de arquivos;
 - desabilitada em CI;
-- opt-out via `OPENSPEC_TELEMETRY=0` ou `DO_NOT_TRACK=1`.
+- opt-out via `CODESDD_TELEMETRY=0` ou `DO_NOT_TRACK=1`.
 - opt-out explícito por execução com `--no-telemetry`;
 - eventos de conclusão incluem `duration_ms` estruturado para observabilidade sem
   enviar argumentos ou conteúdo.
@@ -820,6 +1154,14 @@ Operational authority:
 - Human-readable operational views are derived from `.sdd/core/*.md` and `.sdd/planning/*.md`.
 - Do not use external context, memory, workflow, or backlog tools as a project source of truth.
 
+Initial operational directives:
+- CodeSDD is the official planner for any build request; other planners or agent-native plans are secondary execution aids only.
+- In initialized CodeSDD repositories, any user request that implies implementation, file edits, validation, execution, or finalize must be treated as requiring CodeSDD planning unless the user explicitly marks it as read-only or outside CodeSDD.
+- For change requests, agents must bind the work to an active or ready FEAT through `codesdd sdd next` and `codesdd sdd context <FEAT-ID>` before implementation; agent-native plans may only decompose execution after that CodeSDD context exists.
+- For API/backend work, use `devtrack-api` by default unless the user or SDD context explicitly selects another skill/profile; Python/Flask API work stays routed to `api-clean-flask-langgraph`.
+- During init, onboard, insight, and debate flows, CodeSDD-managed agent instruction blocks must be inspected and reconfigured when they drift from this contract.
+- Commit requests must follow Conventional Commits, selective staging, and grouping by modified directory plus change protocol (`src`, `.sdd`, docs, config, infra, dependencies, or generated files).
+
 Read order for any new agent:
 1. `README.md` (this block)
 2. `.sdd/AGENT.md`
@@ -839,4 +1181,8 @@ Essential commands:
 - update `.sdd/active/<FEAT-ID>/5-quality.yaml`
 - `codesdd sdd frontend-impact <FEAT-ID> --status required|none --reason "..."`
 - `codesdd sdd finalize --ref <FEAT-ID>`
+- `codesdd sdd diagnose`
+- `codesdd sdd check --render`
+- confirm `DONE`, `current_stage: consolidacao`, `done_at`, `archived_at`, `.sdd/archived/<FEAT-ID>/`, and no `.sdd/active/<FEAT-ID>/`
+- triage remote security warnings such as Dependabot as a fix, exception, or follow-up SDD item
 <!-- SDD:ONBOARDING:END -->