@devtrack-solution/codesdd 1.2.2 → 1.2.3

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,85 @@ 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.
+- 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.
+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`. A fabrica `createFilesystemFirstCoordinationAdapters` em `src/core/sdd/coordination/` mantem esse comportamento mesmo quando Redis e solicitado, ate que um adaptador Redis real seja instalado.
 
 Variaveis reconhecidas:
 
@@ -57,11 +155,15 @@ Variaveis reconhecidas:
 
 Enquanto o cliente Redis nao existir no runtime, o status exposto e `requested-unavailable` e os defaults filesystem-first continuam autoritativos.
 
+`codesdd config list` exibe o status atual da fronteira Redis e o namespace efetivo sem imprimir segredos.
+
 ## 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 +194,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 +229,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 +238,36 @@ 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`.
+- 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 +279,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 +299,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 +310,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 +323,12 @@ 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.
 
 ## Como iniciar em um projeto novo
 
@@ -274,7 +386,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 +400,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 +447,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.
@@ -448,19 +567,69 @@ workspace ativa.
 codesdd sdd context FEAT-0001
 ```
 
-4.1 Expor o bridge MCP para agentes externos
+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
+```
+
+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
 ```
 
-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.
+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.
+
+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
 
@@ -636,6 +805,8 @@ The SDD bootstrap installs local curation in:
 ```
 
 The default curation currently includes 66 skills across 8 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:
 
@@ -647,7 +818,15 @@ Entre elas:
 - `api-clean-flask-langgraph` (bundle `python-agentic-backend`)
 - `devtrack-api` (bundle `architecture-backend`, canonical DevTrack/NestJS/TypeORM API 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 DevTrack/Foundation backend API work, `devtrack-api` is the canonical architecture and naming source.
+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`.
+
+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.
+
+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 +861,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`
@@ -769,7 +950,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 +983,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 +1002,12 @@ 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.
+- 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 +1027,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 -->

package/bin/codesdd.js

@@ -5,6 +5,7 @@ process.env.CODESDD_CLI_PACKAGE_NAME = '@devtrack-solution/codesdd';
 process.env.CODESDD_CLI_ENTRYPOINT = 'bin/codesdd.js';
 process.env.CODESDD_CLI_PRODUCT_NAME = 'CodeSDD';
 
-delete process.env.CODESDD_CLI_IMPORT;
+process.env.CODESDD_CLI_IMPORT = '1';
 
-await import('../dist/cli/index.js');
+const { runCli } = await import('../dist/cli/index.js');
+await runCli();

package/dist/cli/index.d.ts

@@ -1,3 +1,3 @@
-import { Command } from 'commander';
-export declare const program: Command;
+export { createCliProgram, getCommandPath, runCli } from './program.js';
+export declare const program: import("commander").Command;
 //# sourceMappingURL=index.d.ts.map