@devtrack-solution/codesdd 1.2.3 → 1.2.4

package/README.md

@@ -31,6 +31,7 @@ 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.
+- [docs/service-catalog-maturity-epic-0097.md](docs/service-catalog-maturity-epic-0097.md): scorecard e guardrails da maturidade 5 do catalogo de servicos.
 - [positioning.md](positioning.md): narrativa de posicionamento enterprise do CodeSDD.
 
 ## O que o CodeSDD faz
@@ -73,6 +74,10 @@ 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.
+- Reversa URL opera como superficie governada de frontend renderizado: `codesdd sdd reversa url <url>` exige aceite legal, escopo de autorizacao, intake guiado, stack alvo, limites de volumetria, politica de assets, boundary frontend-only e, quando solicitado, inventario redigido de contratos backend observados. Ele nao copia backend, bancos, credenciais, regras servidoras ou infraestrutura.
+- 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:
@@ -116,6 +121,14 @@ 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
@@ -144,7 +157,7 @@ a precedencia valida usa `AZURE_OPENAI_DEPLOYMENT_NAME`, depois
 
 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, cache L1 em memoria e cache L2 em `~/.codesdd/cache/projects/<fingerprint>/coordination`. 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:
 
@@ -152,10 +165,80 @@ 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
+```
+
+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.
+
+### Provisionamento Enterprise de itens numerados
+
+Em modo Enterprise multiagente, DEB, INS, EPIC, FEAT e demais artefatos numerados devem usar uma autoridade online de provisionamento antes de qualquer escrita canonica. O modo local/single-agent continua usando o estado versionado em `.sdd` sem contato remoto obrigatorio.
+
+Configure a identidade do projeto e a autoridade em `~/.codesdd/config.toml`:
+
+```toml
+[enterprise.provisioning]
+mode = "enterprise"
+project_id = "proj_devtrack_tools"
+tenant_id = "tenant-main"
+authority_url_env = "CODESDD_ALLOCATOR_URL"
+required_for_numbered_artifacts = true
+```
+
+Mantenha a URL real no shell, password manager ou secret store:
+
+```bash
+export CODESDD_ALLOCATOR_URL="https://allocator.example.test"
+```
+
+`codesdd config doctor --json` expoe `enterprise_provisioning` com `disabled`, `ready` ou `blocked`. Quando Enterprise esta solicitado e falta `project_id` ou autoridade, o doctor bloqueia; quando a autoridade estiver indisponivel em execucao, agentes Enterprise devem criar apenas drafts nao canonicos ate uma reserva online posterior.
+
+O contrato inicial do allocator vive em `src/core/sdd/artifact-id-allocator.ts`. Ele define requests/responses versionados para reservar IDs canonicos (`INS`, `DEB`, `EPIC`, `FEAT`, `FGAP`, `TD`), gera idempotency keys deterministicas, retorna `reserved` na primeira reserva e `replayed` quando a mesma chave/payload e repetida. Reuso da mesma idempotency key com outro payload e conflito bloqueante.
+
+O mesmo contrato tambem define leases de allocator com TTL, fencing token monotônico e audit trail. Uma lease ativa bloqueia outra lease concorrente para o mesmo projeto/tipo de artefato; replay da mesma idempotency key retorna a lease original; fencing token expirado ou divergente falha antes de ser usado por gates de escrita nos FEATs seguintes.
 
-Enquanto o cliente Redis nao existir no runtime, o status exposto e `requested-unavailable` e os defaults filesystem-first continuam autoritativos.
+CAS de escrita canonica tambem e modelado no contrato: `commitCanonicalArtifactWrite` exige lease existente, fencing token valido e `expected_revision` igual a revisao atual do artefato. Repetir a mesma idempotency key/payload retorna `replayed`; token vencido, token divergente ou revisao stale gera rejeicao auditavel.
 
-`codesdd config list` exibe o status atual da fronteira Redis e o namespace efetivo sem imprimir segredos.
+O gate Enterprise de comandos mutantes vive em `src/core/sdd/enterprise-mutating-command-gate.ts`. Ele permite comandos read-only, bloqueia mutacoes numeradas Enterprise sem lease/fencing valido e marca tentativas de bypass como `bypass-detected` antes de avaliar o lease.
+
+Modo draft nao canonico tambem vive no contrato do allocator. `createNoncanonicalDraft` cria um identificador `draft_<tipo>_<hash>` que nunca entra na sequencia canonica; `convertDraftToCanonicalArtifact` exige uma reserva real do allocator, vincula o draft ao ID canonico e retorna `replayed` se a conversao ja tiver sido aplicada.
+
+Gates de provenance vivem em `src/core/sdd/enterprise-provenance-gates.ts`. Eles verificam se reservas, leases, writes canonicos e conversoes de draft possuem audit/provenance suficiente para `diagnose`, `check`, `finalize` e CI bloquearem estados sem trilha.
+
+Recovery do allocator vive em `src/core/sdd/allocator-recovery.ts`. Ele reconstrói counters a partir do histórico de reservas e reporta branch lag quando uma revisão local está atrás da revisão canônica observada.
+
+Segurança do allocator vive em `src/core/sdd/allocator-security.ts`, com decisões determinísticas para quota por tenant/tipo de artefato e replay fora da janela permitida.
+
+A carta arquitetural de EPIC-0084 vive em `.sdd/core/adrs/ADR-FEAT-0363.md` e mapeia cada FEAT do fechamento para seu contrato, evidencia primaria e risco residual. Use essa matriz como trilha de auditoria antes de adicionar transporte remoto, persistencia ou wiring de comandos mutantes.
 
 ## Contrato de nomenclatura
 
@@ -247,6 +330,12 @@ Se o terminal nao encontrar `codesdd`, a instalacao provavelmente foi concluida,
 - 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 config doctor --json` tambem expoe `generated_instructions`, que aponta skills/prompts gerados sem o anuncio `CodeSDD Canonical Workflow`; quando `status=stale`, rode `codesdd update` ou reinstale as ferramentas afetadas.
+- `codesdd config doctor --json` tambem expoe `enterprise_provisioning`, que valida identidade de projeto e autoridade online obrigatoria para artefatos numerados em modo Enterprise multiagente.
+- O contrato de reserva de IDs canonicos fica em `src/core/sdd/artifact-id-allocator.ts`; ele e propositalmente puro/testavel e ainda nao substitui os gates de lease/CAS/mutating commands dos FEATs dependentes.
+- `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.
@@ -330,21 +419,54 @@ pnpm run quality:review
 - `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
 
 Entre no repositorio onde voce quer usar o sistema e rode:
 
 ```bash
-codesdd install --tools none
+codesdd sdd init-context
+```
+
+O `init-context` e o primeiro comando de capacidade CodeSDD dentro do projeto: ele inspeciona a base, cria/atualiza `.sdd/`, preenche contexto inicial de arquitetura, stack, servicos e mapa do repositorio, e deixa o projeto pronto para operar com estado canonico. Em um projeto recem-inicializado, valide e leia o onboarding antes do primeiro trabalho:
+
+```bash
+codesdd sdd check --render
+codesdd sdd onboard system
+```
+
+O `sdd check --render` separa ruido historico de pendencia real. Para frontend,
+use `Gaps de frontend abertos` como indicador operacional de trabalho pendente;
+`Gaps de frontend resolvidos/historicos` e `Gaps de frontend total historico`
+preservam auditoria de FGAPs ja fechados. Para lock domains, apenas
+`Lock domains compartilhados ativos` indica risco de paralelizacao atual;
+locks compartilhados historicos/mistos sao contexto de auditoria e nao devem
+ser tratados como blocker por si so.
+
+Depois disso, o primeiro trabalho normalmente comeca assim:
+
+```bash
+codesdd sdd insight "descreva a mudanca ou iniciativa"
 ```
 
-Para ja nascer com nomenclatura mais intuitiva em portugues nas pastas do SDD:
+Se quiser fixar idioma/layout em portugues:
 
 ```bash
-codesdd install --tools none --lang pt-BR --layout pt-BR
+codesdd sdd init-context --lang pt-BR --layout pt-BR
 ```
 
-Se quiser integrar ferramentas suportadas no bootstrap:
+Se quiser gerar assets de assistente explicitamente para agentes como Codex, Claude, Cursor ou OpenCode, use `install --tools` depois que o projeto tiver contexto CodeSDD:
 
 ```bash
 codesdd install --tools all
@@ -356,21 +478,19 @@ Ou somente algumas:
 codesdd install --tools codex,cursor,claude
 ```
 
-Esse comando instala de uma vez:
+Para OpenCode, use `--tools opencode` para instalar skills/prompts gerados. O provider MCP do bridge SDD usa outro id: `--provider open-code`.
+
+O `init-context` prepara a base CodeSDD do projeto:
 
-- a base do runtime
 - `.sdd/config.yaml`
 - `.sdd/`
-- skills curadas
-- prompts recomendados por workflow
-- templates
 - estados YAML canonicos
 - documentos iniciais do projeto
 
-Se voce nao quiser habilitar frontend no bootstrap:
+Se voce nao quiser habilitar frontend na inicializacao de contexto:
 
 ```bash
-codesdd install --tools none --no-frontend
+codesdd sdd init-context --no-frontend
 ```
 
 Atalhos em portugues no CLI:
@@ -383,15 +503,21 @@ Atalhos em portugues no CLI:
 
 ## Como absorver um projeto que ja existe
 
-Se o projeto ja esta em andamento, o primeiro passo depois do `install` e inicializar o contexto:
+Se o projeto ja esta em andamento, rode o mesmo comando na raiz:
 
 ```bash
-codesdd sdd init-context --frontend --lang en-US --layout en-US
+codesdd sdd init-context
 codesdd sdd check --render
 codesdd sdd onboard system
 ```
 
-O `init-context` serve para:
+O `init-context` detecta marcadores de codigo existente e executa a absorcao inicial de contexto. Para reabsorver de forma controlada depois que o projeto ja estiver governado, rode o mesmo comando com as opcoes necessarias:
+
+```bash
+codesdd sdd init-context --frontend --lang en-US --layout en-US
+```
+
+Esse comando serve para:
 
 - inspecionar a base existente
 - preencher contexto inicial de arquitetura, stack, servicos e mapa do repositorio
@@ -467,6 +593,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
@@ -567,6 +706,42 @@ workspace ativa.
 codesdd sdd context FEAT-0001
 ```
 
+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
@@ -621,10 +796,19 @@ A fundacao MCP do CodeSDD e agnostica a provedor e publica o envelope
 `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.
+o identificador `open-code`. Use `opencode` apenas como id tecnico de assets
+gerados por `codesdd install --tools opencode` e em contratos de runtime
+OpenCode que executam o binario `opencode`; esse id nao e aceito por
+`sdd mcp-manifest` neste runtime.
 
 Matriz de provedores: consulte
 [docs/mcp-provider-compatibility.md](docs/mcp-provider-compatibility.md),
@@ -643,6 +827,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
@@ -659,6 +853,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
@@ -667,6 +879,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
@@ -804,7 +1021,7 @@ 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.
 
@@ -816,18 +1033,30 @@ Entre elas:
 - `frontend-extractor-sdd`
 - `planning-normalizer-sdd`
 - `api-clean-flask-langgraph` (bundle `python-agentic-backend`)
-- `devtrack-api` (bundle `architecture-backend`, canonical DevTrack/NestJS/TypeORM API architecture)
+- `devtrack-api` (bundle `architecture-backend`, compatibility binding for Foundation-derived CodeSDD API profiles)
+- `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. Explicit Python/Flask API work remains routed to `api-clean-flask-langgraph`.
+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, select one CodeSDD API profile: `minimal-rest`, `rest-auth-rbac`, `rest-crud-typeorm`, `evented-api`, `ai-agent-api`, or `full-foundation-compatible`; `devtrack-api` remains the compatibility skill/alias. 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.
+That conformance test now checks the live Foundation BO and TypeORM topology: aggregate `.bo.ts` files must use `extends GenericBusinessObject<T>` followed by `implements <Name>Interface, IValidator`, and persistence wiring must use `src/infrastructure/adapters/orm/typeorm.module.ts` plus context modules such as `<context>-orm.module.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, mandatory `cleanup`/`cleanup:install` plus port-safe `start`/`start:dev` bootstrap scripts for linked/generated API projects, and the `codesdd-validate` plus field-evidence drift maps consumed by later governance gates.
+
+The EPIC-0080 dual-boundary charter lives in `.sdd/core/adrs/ADR-FEAT-0373.md`. It freezes the rule that CodeSDD keeps plural internal layer roots for this CLI repository while every `devtrack-api` preview, artifact map, validator, and generated output must target singular Foundation-compatible roots. For this EPIC, `human_validation_gate.status` is limited to `approved`, `corrected`, `pending`, or `rejected`; any material source, profile, exception, or validator change invalidates prior approval back to `pending` until a human re-approves it.
+
+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.
+
+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.
 
+Legacy generated `devtrack-api` previews, scaffold dry-runs, caches, artifact maps, validator results, and evidence bundles are governed by `.sdd/skills/curated/devtrack-api/references/generated-artifact-invalidation.md`. Pre-EPIC-0080 generated artifacts are noncanonical by default and must be classified as `revalidated`, `invalidated`, `grandfathered`, or `not_applicable` before supporting any Foundation-compatible claim.
+
 Prompts recomendados tambem sao instalados em:
 
 ```text
@@ -857,13 +1086,11 @@ Um agente novo deve seguir esta ordem:
 
 ## Comandos principais
 
-Bootstrap:
+Inicializacao e reparo de projeto:
 
-- `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 reload --tools none`
 - `codesdd sdd check --render`
 - `codesdd sdd check --render --strict`
 - `codesdd sdd diagnose`
@@ -885,18 +1112,31 @@ Bootstrap:
 - `codesdd sdd lint feature FEAT-0001 --strict --json`
 - `codesdd sdd ingest-deposito`
 
+Assets de agentes:
+
+- `codesdd install --tools none` (nao gera assets de agentes)
+- `codesdd install --tools all`
+- `codesdd install --tools opencode` (assets OpenCode; MCP continua `--provider open-code`)
+
 Onboarding e operacao:
 
 - `codesdd sdd onboard system`
 - `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`
 - `codesdd sdd audit`
 - `codesdd sdd finalize --ref FEAT-0001`
 
+Absorcao de contexto:
+
+- `codesdd sdd init-context`
+- `codesdd sdd init-context --frontend --lang en-US --layout en-US`
+
 Descoberta:
 
 - `codesdd sdd insight "..."`
@@ -940,7 +1180,16 @@ pnpm run dev:cli
 
 O repositório instala automaticamente um hook de `pre-commit` local via `.githooks/` durante `pnpm install`. Esse hook chama `node scripts/pre-commit-sdd-fast.mjs`, inspeciona arquivos staged e roda `codesdd sdd check --strict` somente quando houver arquivos `.sdd/` no commit. Para a validacao completa antes de PR/release, rode `pnpm run sdd:validate`.
 
-A matriz autoritativa de cobertura da CLI fica em `src/core/cli/command-matrix.ts`. Sempre que um novo leaf command for registrado, atualize a matriz junto para explicitar se a cobertura esperada e `contract`, `spawned-e2e` ou `exception`.
+A matriz autoritativa de cobertura e taxonomia publica da CLI fica em `src/core/cli/command-matrix.ts`. Sempre que um novo leaf command for registrado, atualize a matriz junto para explicitar se a cobertura esperada e `contract`, `spawned-e2e` ou `exception`, e classifique o comando como lifecycle canonico, bootstrap/repair, compatibilidade, migracao, diagnostico/governanca ou interno.
+
+Harness pratico de comandos:
+
+```bash
+pnpm exec vitest run test/helpers/practical-api-fixture.test.ts
+pnpm exec vitest run --testTimeout 120000 test/e2e/practical-api-command-system.test.ts
+```
+
+Esse harness cria uma API ficticia `proposal-builder-api` em diretorio temporario, isola `HOME`, `USERPROFILE`, `XDG_*`, `CODEX_HOME` e flags de runtime, e valida um ciclo real do CodeSDD com exatamente um `INS`, um `DEB`, um `EPIC` e um `FEAT`. A cobertura da matriz publica deve terminar sem comandos faltantes: cada caminho fica marcado como `executed`, `dry_run`, `alias_covered` ou `skipped_external` com motivo explicito.
 
 ## Estado atual da distribuicao
 
@@ -1004,7 +1253,9 @@ Operational authority:
 
 Initial operational directives:
 - CodeSDD is the official planner for any build request; other planners or agent-native plans are secondary execution aids only.
-- 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`.
+- 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, select a CodeSDD API profile (`minimal-rest`, `rest-auth-rbac`, `rest-crud-typeorm`, `evented-api`, `ai-agent-api`, or `full-foundation-compatible`); `devtrack-api` remains the compatibility skill/alias and 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).
 

package/dist/applications/sdd/index.d.ts

@@ -0,0 +1,16 @@
+export { ApproveService } from '../../core/sdd/services/approve.service.js';
+export { BreakdownService } from '../../core/sdd/services/breakdown.service.js';
+export { ContextService } from '../../core/sdd/services/context.service.js';
+export { DebateService } from '../../core/sdd/services/debate.service.js';
+export { DecideService } from '../../core/sdd/services/decide.service.js';
+export { DeepAgentsRunService, type DeepAgentsRunRequest, type DeepAgentsRunResult } from '../../core/sdd/services/agent-run.service.js';
+export { FeatureLintService, collectTaskCommands, formatFeatureLintReport, isFoundationPrescriptiveFeature, type FeatureLintFinding, type FeatureLintOptions, type FeatureLintReport, } from '../../core/sdd/services/feature-lint.service.js';
+export { FinalizeService } from '../../core/sdd/services/finalize.service.js';
+export { FrontendGapService } from '../../core/sdd/services/frontend-gap.service.js';
+export { FrontendImpactService } from '../../core/sdd/services/frontend-impact.service.js';
+export { GovernanceControlPlaneService } from '../../core/sdd/services/governance-control-plane.service.js';
+export { InsightService } from '../../core/sdd/services/insight.service.js';
+export { NextService } from '../../core/sdd/services/next.service.js';
+export { OnboardService } from '../../core/sdd/services/onboard.service.js';
+export { StartService } from '../../core/sdd/services/start.service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/applications/sdd/index.js

@@ -0,0 +1,16 @@
+export { ApproveService } from '../../core/sdd/services/approve.service.js';
+export { BreakdownService } from '../../core/sdd/services/breakdown.service.js';
+export { ContextService } from '../../core/sdd/services/context.service.js';
+export { DebateService } from '../../core/sdd/services/debate.service.js';
+export { DecideService } from '../../core/sdd/services/decide.service.js';
+export { DeepAgentsRunService } from '../../core/sdd/services/agent-run.service.js';
+export { FeatureLintService, collectTaskCommands, formatFeatureLintReport, isFoundationPrescriptiveFeature, } from '../../core/sdd/services/feature-lint.service.js';
+export { FinalizeService } from '../../core/sdd/services/finalize.service.js';
+export { FrontendGapService } from '../../core/sdd/services/frontend-gap.service.js';
+export { FrontendImpactService } from '../../core/sdd/services/frontend-impact.service.js';
+export { GovernanceControlPlaneService } from '../../core/sdd/services/governance-control-plane.service.js';
+export { InsightService } from '../../core/sdd/services/insight.service.js';
+export { NextService } from '../../core/sdd/services/next.service.js';
+export { OnboardService } from '../../core/sdd/services/onboard.service.js';
+export { StartService } from '../../core/sdd/services/start.service.js';
+//# sourceMappingURL=index.js.map