@devtrack-solution/codesdd 1.2.2

package/README.md

@@ -0,0 +1,842 @@
+# CodeSDD
+
+CodeSDD e uma evolucao do OpenSpec focada em 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;
+- existem varios agentes trabalhando em paralelo;
+- o frontend fica defasado em relacao ao backend;
+- um agente novo entra no repositorio sem contexto previo;
+- o sistema ja existe e precisa ser absorvido sem reler todo o codigo.
+
+## O que o CodeSDD faz
+
+O CodeSDD organiza o desenvolvimento em 4 camadas:
+
+1. Descoberta
+- `INSIGHT`: ideia bruta
+- `DEBATE`: discussao estruturada
+- `EPIC`: ideia aprovada para futuro planejamento
+- `DISCARDED`: ideia rejeitada com motivo registrado
+
+2. Planejamento
+- `EPIC` pode ser quebrado em `FEATs` (`RAD` segue como alias legado)
+- `FEAT` vira unidade executavel
+- o backlog registra dependencias, bloqueios e paralelizacao
+
+3. Execucao
+- cada `FEAT` ganha um workspace proprio em `.sdd/active/FEAT-0001/`
+- esse workspace tem `spec`, `plan`, `tasks` e `changelog`
+
+4. Memoria operacional
+- `.sdd/state/*.yaml` e a fonte canonica
+- `.sdd/core/*.md` sao views operacionais geradas a partir do estado
+- `README.md`, `AGENTS.md`, `AGENT.md` e `.sdd/AGENT.md` orientam humanos e agentes
+- nenhum outro armazenamento de contexto, memoria, workflow, backlog, scratchpad ou handoff e fonte operacional do projeto
+
+## Autoridade operacional
+
+- Estado, progresso, dependencias, bloqueios, qualidade e handoff vivem em `.sdd/state/*.yaml`.
+- `.sdd/core/*.md` e `.sdd/planning/*.md` sao views operacionais derivadas.
+- Workspaces em execucao vivem em `.sdd/active/<FEAT-ID>/`.
+- 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.
+
+## 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.
+
+Variaveis reconhecidas:
+
+- `CODESDD_REDIS_URL`: URL Redis especifica do CodeSDD.
+- `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`.
+
+Enquanto o cliente Redis nao existir no runtime, o status exposto e `requested-unavailable` e os defaults filesystem-first continuam autoritativos.
+
+## 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`.
+
+Durante a migracao para CodeSDD, esse contrato permite manter uma janela de
+compatibilidade rastreavel sem perder o objetivo final: remover termos legados
+fora das allowlists temporarias e registrar cada excecao com owner e fase de
+remocao.
+
+## Fronteira com a DevTrack Foundation API
+
+Para o backend padrao oficial, o CodeSDD deve operar com uma fronteira clara:
+
+- `devtrack-foundation-api` e a fonte canonica de arquitetura backend, bundles/skills `foundation-*` e eventual starter backend.
+- `devtrack-tools-codesdd` e a camada de distribuicao que instala runtime SDD, perfis, templates e materializacao controlada dessa referencia em projetos derivados.
+- Este repositorio nao deve passar a manter um backend canonico paralelo; quando houver adocao da Foundation, ela deve acontecer por profile/bootstrap/distribuicao.
+- O mapa derivado da arvore de pacotes da referencia backend fica em [docs/foundation-backend-reference-structure.md](docs/foundation-backend-reference-structure.md) e deve ser tratado como referencia operacional, nao como nova fonte canonica.
+
+## O que fica instalado no projeto
+
+Depois do bootstrap, o projeto passa a ter:
+
+- `README.md`
+- `AGENTS.md`
+- `AGENT.md`
+- `.sdd/`
+- `.sdd/config.yaml`
+- `.sdd/state/`
+- `.sdd/core/`
+- `.sdd/discovery/`
+- `.sdd/planning/`
+- `.sdd/active/`
+- `.sdd/archived/`
+- `.sdd/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
+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.
+
+Dentro de `.sdd/` ficam:
+
+- memoria operacional do projeto
+- backlog executavel
+- debates e epics
+- gaps e decisoes de frontend
+- skills curadas
+- documentacao viva do sistema
+
+## Instalacao global
+
+Requer:
+
+- Node.js `20.19.0` ou superior
+- `npm`
+
+A instalacao global oficial e feita via npm:
+
+```bash
+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,
+confira:
+
+```bash
+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.
+
+### Windows PowerShell
+
+```powershell
+npm install -g @devtrack-solution/codesdd
+$target = Join-Path (npm config get prefix) "codesdd.cmd"
+New-Item -ItemType File -Force $PROFILE
+Add-Content $PROFILE "`nfunction codesdd { & '$target' @args }"
+. $PROFILE
+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:
+
+```bash
+npm install -g @devtrack-solution/codesdd
+printf "\nalias codesdd='%s'\n" "$(npm prefix -g)/bin/codesdd" >> ~/.bashrc
+. ~/.bashrc
+codesdd --version
+```
+
+Para Zsh:
+
+```bash
+npm install -g @devtrack-solution/codesdd
+printf "\nalias codesdd='%s'\n" "$(npm prefix -g)/bin/codesdd" >> ~/.zshrc
+. ~/.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:
+
+```bash
+npm install -g @devtrack-solution/codesdd
+printf "\nalias codesdd='%s'\n" "$(npm prefix -g)/bin/codesdd" >> ~/.zshrc
+. ~/.zshrc
+codesdd --version
+```
+
+Alias legado opcional para comandos antigos:
+
+```bash
+printf "\nalias openspec='codesdd'\n" >> ~/.zshrc
+```
+
+Se voce estiver desenvolvendo este fork localmente:
+
+```bash
+pnpm install
+pnpm run build
+npm install -g .
+```
+
+Atalhos uteis de manutencao local:
+
+```bash
+pnpm run cleanup
+pnpm run cleanup:install
+```
+
+- `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.
+
+## Como iniciar em um projeto novo
+
+Entre no repositorio onde voce quer usar o sistema e rode:
+
+```bash
+codesdd install --tools none
+```
+
+Para ja nascer com nomenclatura mais intuitiva em portugues nas pastas do SDD:
+
+```bash
+codesdd install --tools none --lang pt-BR --layout pt-BR
+```
+
+Se quiser integrar ferramentas suportadas no bootstrap:
+
+```bash
+codesdd install --tools all
+```
+
+Ou somente algumas:
+
+```bash
+codesdd install --tools codex,cursor,claude
+```
+
+Esse comando instala de uma vez:
+
+- 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:
+
+```bash
+codesdd install --tools none --no-frontend
+```
+
+Atalhos em portugues no CLI:
+
+- `codesdd instalar` (alias de `codesdd install`)
+- `codesdd sdd iniciar` (alias de `codesdd sdd init`)
+- `codesdd sdd iniciar-contexto` (alias de `codesdd sdd init-context`)
+- `codesdd sdd ideia`, `debater`, `decidir`, `desdobrar`, `iniciar-execucao`, `aprovar`, `contexto`, `orientar`, `consolidar`, `proximo`, `checar`, `ingestao-deposito`
+- `codesdd arquivar` (alias em portugues para `codesdd archive`)
+
+## Como absorver um projeto que ja existe
+
+Se o projeto ja esta em andamento, o primeiro passo depois do `install` e inicializar o contexto:
+
+```bash
+codesdd sdd init-context
+codesdd sdd check --render
+codesdd sdd onboard system
+```
+
+O `init-context` serve para:
+
+- inspecionar a base existente
+- preencher contexto inicial de arquitetura, stack, servicos e mapa do repositorio
+- gerar a memoria inicial do sistema
+- preparar onboarding para agentes novos
+
+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.
+
+## Como usar no dia a dia
+
+Fluxo principal:
+
+1. Ver o sistema como um todo
+
+```bash
+codesdd sdd onboard system
+```
+
+Antes de executar comandos operacionais do SDD, a CLI verifica se existe estado legado em `.sdd/state/`.
+Quando detecta migracao pendente, ela executa a conversao mandatória para o formato canonico atual antes de seguir.
+This primarily normalizes legacy IDs (`RAD-*`, `FEAT-*`, `SRC-*` without four-digit padding), migrates legacy workspace Markdown docs to YAML when needed, and persists `state_version: 2` in `.sdd/config.yaml`.
+
+Para inspecionar ou aplicar a migracao de workspaces manualmente:
+
+```bash
+codesdd sdd migrate-workspace --dry-run
+codesdd sdd migrate-workspace --feat FEAT-0001
+```
+
+O comando converte documentos conhecidos em `.sdd/active/<FEAT-ID>/` e `.sdd/archived/<FEAT-ID>/` de `.md` para `.yaml`, valida o resultado com os schemas Zod e marca lacunas com `# MIGRATION: field required but source had no content`. A migracao manual de estado via `codesdd sdd migrate` exige confirmacao interativa ou `--yes`.
+
+Para reconstruir estado canonico quando os arquivos YAML em `.sdd/state/` perderem
+sincronia com os artefatos no disco:
+
+```bash
+codesdd sdd rebuild --from-disk --dry-run
+codesdd sdd rebuild --from-disk --json
+```
+
+O `rebuild --from-disk` reconcilia `discovery-index.yaml` e `backlog.yaml` a
+partir de `.sdd/discovery/`, `.sdd/planned/`, `.sdd/active/` e
+`.sdd/archived/`. Ele preserva campos ricos já existentes, recria registros
+ausentes quando consegue derivar `FEAT`/`EPIC` de documentos validos, atualiza
+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
+```
+
+O `import-openspec` copia todos os arquivos de `openspec/` 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
+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.
+
+2. Ver o que pode comecar agora
+
+```bash
+codesdd sdd next
+```
+
+Auditar a saude de evolucao do proprio processo SDD (ciclo recomendado: semestral):
+
+```bash
+codesdd sdd audit
+codesdd sdd audit --json
+```
+
+Cada execucao de `audit` anexa um snapshot em `.sdd/state/audit-history.yaml`
+com score, saude, metricas principais e recomendacao, permitindo comparar
+tendencia entre ciclos sem depender de memoria externa.
+
+Contratos de qualidade novos usam enforcement `blocking` por padrao. Para nao
+bloquear uma finalizacao, registre uma excecao formal com escopo, risco aceito,
+controle compensatorio, prazo de revisao e aprovador; sem excecao, ausencia de
+evidencia continua bloqueando o finalize.
+
+Medir fluxo operacional a partir do transition log:
+
+```bash
+codesdd sdd metrics --since 7d
+codesdd sdd metrics --since 24h --json
+```
+
+O `metrics` calcula lead time de FEATs finalizadas, aging de FEATs em progresso
+e throughput por dia usando `.sdd/state/transition-log.yaml`. A janela aceita
+formatos relativos (`7d`, `24h`, `2w`) ou timestamp ISO.
+
+Reconciliar duplicatas historicas registradas por `warning_links`:
+
+```bash
+codesdd sdd dedup --apply --dry-run
+codesdd sdd dedup --apply --json
+```
+
+O `dedup --apply` consome `warning_links` de registros historicos/terminais em
+`backlog.yaml` e `discovery-index.yaml`, transfere rastreabilidade para o item
+canonico, atualiza referencias simples como `blocked_by` e limpa apenas os links
+reconciliados. Itens ativos continuam intactos e aparecem como warnings para
+decisao manual.
+
+Avaliar se uma FEAT esta ampla demais antes de avançar:
+
+```bash
+codesdd sdd lint feature FEAT-0001
+codesdd sdd lint feature FEAT-0001 --strict --json
+```
+
+O lint de feature usa o workspace YAML e o backlog para verificar quantidade de
+tasks, `lock_domains`, superficies frontend e modulos tocados. Sem `--strict`,
+warnings documentam risco sem falhar; com `--strict`, qualquer warning retorna
+exit code diferente de zero.
+
+Diagnosticar a estrutura SDD com relatorio canonico, sem aplicar correcoes:
+
+```bash
+codesdd sdd diagnose
+codesdd sdd diagnose --json
+codesdd sdd diagnose --strict --output .sdd/reports/diagnose.json
+```
+
+O `diagnose` verifica diretórios canonicos, estado YAML, referencias, workspaces
+ativos/arquivados, views geradas e fronteiras de path dentro de `.sdd`. O comando
+retorna exit code `0` para saudavel, `1` para erros, `2` para bloqueadores,
+`3` para opcoes invalidas e `4` para falha interna.
+
+Planejar saneamento com classificacao safe/manual/blocked sem gravar alteracoes:
+
+```bash
+codesdd sdd sanitize --dry-run
+codesdd sdd sanitize --from-report .sdd/reports/diagnose.json
+codesdd sdd sanitize --dry-run --json
+codesdd sdd sanitize --from-report .sdd/reports/diagnose.json --apply --yes
+codesdd sdd sanitize rollback SAN-20260422T100000Z-ABCDEF12 --reason "restore before migration"
+```
+
+O `sanitize` transforma findings do `diagnose` em um plano deterministico de acoes
+`mkdir`, `render`, `move`, `register`, `manual_review` ou `skip`, incluindo
+candidatos de quarentena para casos inseguros e acoes bloqueadas separadas.
+Quando executado com `--apply --yes`, aplica apenas acoes `safe` em transacao,
+gera manifest em `.sdd/reports/sanitize/`, grava trilha de auditoria (`jsonl`) e
+permite rollback pelo `transaction_id`.
+
+3. Iniciar uma feature
+
+```bash
+codesdd sdd start FEAT-0001 --fluxo padrao
+```
+
+Se a `FEAT` no backlog tiver `requires_adr: true`, ou se declarar impacto
+arquitetural em superficies como `cli`, `validation`, `schema`, `state`, `sdd`
+ou `contract`, o `start` cria automaticamente `.sdd/core/adrs/ADR-FEAT-####.md`
+(sem sobrescrever ADR já existente) e injeta a referência no `1-spec.yaml` da
+workspace ativa.
+
+4. Ler o contexto da feature
+
+```bash
+codesdd sdd context FEAT-0001
+```
+
+4.1 Expor o bridge MCP para agentes externos
+
+```bash
+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
+```
+
+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.
+
+5. Implementar
+
+6. Consolidar memoria ao final
+
+```bash
+codesdd sdd finalize --ref FEAT-0001
+```
+
+Se você já estiver dentro de `.sdd/active/FEAT-####/`, o `finalize` também pode
+inferir a FEAT alvo sem `--ref`, priorizando o workspace ativo atual antes de
+cair para a fila pendente padrão.
+
+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
+placeholder). Em caso de violação, o fluxo é bloqueado.
+
+Para features vinculadas a `EPIC-0020`/`EPIC-0021`, os YAMLs da workspace ativa
+devem registrar `compliance_context`, `privacy_controls` e
+`security_integrity`. O `finalize` valida esses gates e bloqueia a transição
+sem esses campos, exceto com `--force-transition`.
+
+Quando a feature tiver `recommended_skills`, o `5-quality.yaml` também vira o
+contrato operacional das skills: registre uma entrada em
+`skill_evidence.evidence[]` para cada skill requerida antes do `finalize`.
+Sem esse rastro, o fluxo fica bloqueado como qualquer outra evidência de
+qualidade obrigatória.
+
+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
+registre ao menos um mapeamento em `traceability.requirements[]` ligando
+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 `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
+`sdd diagnose` reportam `.sdd/archive/FEAT-*` como estrutura não canônica; use
+`.sdd/archived/` para workspaces concluídos.
+
+Regra operacional central:
+
+uma feature so esta realmente concluida quando a documentacao afetada foi atualizada antes do `finalize`.
+
+Isso inclui, quando houver impacto:
+
+- `README.md`
+- `AGENTS.md`
+- `AGENT.md`
+- `.sdd/README.md`
+- `.sdd/AGENT.md`
+- `.sdd/core/*.md`
+- gaps e decisoes de frontend
+
+## Saúde Estrutural, Ciclo de Vida e Garantias de Segurança (Structural Health)
+
+O CodeSDD implementa uma plataforma determinística de saúde estrutural (`sdd diagnose` e `sdd sanitize`) para garantir que o projeto evolua sem corrupção de estado, garantindo **segurança transacional**, **fuga de root boundary** e **invariância de idioma**.
+
+### 1. Modelo Conceitual e Ciclo de Vida (Lifecycle Semantics)
+O ciclo de vida das features transita obrigatoriamente pelas raízes canônicas:
+- **`planned`** (`.sdd/planned/`): Feature aprovada e desdobrada (estado `READY` ou `BLOCKED`), aguardando início.
+- **`active`** (`.sdd/active/`): Feature em execução (estado `IN_PROGRESS`). Mudanças ocorrem no código e contratos de qualidade.
+- **`archived`** (`.sdd/archived/`): Feature entregue e consolidada (estado `DONE`).
+
+`.sdd/archive/` não é raiz de lifecycle canônica. Se ela contiver diretórios
+`FEAT-*`, `check`, `diagnose` e `finalize` tratam isso como duplicidade
+`archive`/`archived` e bloqueiam a conclusão até a evidência ser revisada e
+consolidada em `.sdd/archived/`.
+
+### 2. Diagnóstico e Saneamento
+- **Diagnóstico (`sdd diagnose`)**: Inspeciona a coerência entre o YAML canônico, referências (links/âncoras), workspaces, views geradas e fronteiras de *path*.
+- **Saneamento (`sdd sanitize`)**: Gera um plano determinístico (`safe`, `manual`, `blocked`) para corrigir os achados do diagnóstico. Operações `safe` podem ser aplicadas (`--apply --yes`) dentro de uma transação.
+- **Rollback**: Toda aplicação de saneamento gera um manifesto em `.sdd/reports/sanitize/` permitindo reversão (`codesdd sdd sanitize rollback <SAN-ID>`).
+
+### 3. Garantias de Fuga de Diretório (Root-Boundary Containment)
+Nenhum comando gerenciado pelo CodeSDD (geração de plano, relatórios, views, etc.) tem permissão para escrever fora da raiz `.sdd` ativa.
+- **Path Traversal / Absolute Paths**: Resolvidos e bloqueados imediatamente se apontarem para fora do diretório do projeto ou `.sdd`.
+- **Symlink Escapes**: Links simbólicos são inspecionados via `realpath` antes de qualquer gravação.
+Esta garantia aplica-se estritamente tanto à interface CLI quanto aos agentes operando via chamadas de função (function calls).
+
+### 4. Invariância de Idioma (Language Invariance)
+- A prosa narrativa e conteúdo (ex. descrições em markdown, documentação humana) podem ser localizados.
+- **Tokens estruturais, metadados YAML e diretórios operacionais (ex: `planned`, `active`, `archived`) são fixos em inglês.** Não utilize traduções para criar esses diretórios.
+- Alias legados podem ser suportados pontualmente na CLI, mas a estrutura física deve respeitar a canonicidade.
+
+### 5. Guia de Migração e Troubleshooting
+Projetos legados podem apresentar:
+- **Pastas traduzidas** (ex: `pendencias` ao invés de `planned`, ou `arquivados` ao invés de `archived`). O comando `sdd check --render` ou a própria inicialização (`sdd start`) podem mapear esses desvios. Recomenda-se rodar `sdd diagnose` e `sdd sanitize` para regularizar esses *paths*.
+- **Features presas em `active`**: Rode `codesdd sdd finalize --ref <FEAT-ID>` se a feature estiver concluída, ou migre para `planned` se estiver pausada.
+- **Índices Duplicados**: Rode `sdd diagnose`. Achados apontarão identidades conflitantes (IDs duplicados) exigindo resolução manual.
+
+### 6. Function Calls para Agentes
+Além da CLI, as mesmas primitivas de saúde e segurança estão expostas para integrações (ex. agentes rodando em TypeScript):
+- `diagnoseSddRoot(payload)`: Promise<DiagnosticReport>
+- `sanitizeSddRoot(payload)`: Promise<SanitizationReport>
+- `verifySddBoundary(payload)`: Promise<BoundaryReport>
+Essas funções compartilham o exato motor Zod de validação, regras de *boundary* e auditoria.
+
+## Como lidar com ideias novas durante a implementacao
+
+Quando surgir uma ideia no meio do desenvolvimento:
+
+```bash
+codesdd sdd insight "descricao da ideia"
+codesdd sdd debate INS-0001
+codesdd sdd decide DEB-0001 --outcome epic
+codesdd sdd breakdown EPIC-0001 --mode graph --incremental
+```
+
+Esse fluxo serve para nao enfiar no backlog algo que ainda nao foi pensado.
+
+## Como lidar com PRD, wireframe, HTML e material bruto
+
+O CodeSDD separa descoberta de ingestao de documentos consolidados.
+
+Se voce ja possui:
+
+- PRD
+- RFC
+- historias do usuario
+- wireframes
+- imagens
+- html mockado
+- referencias visuais
+
+these materials should go to:
+
+```text
+.sdd/sources/
+```
+
+Estrutura:
+
+```text
+.sdd/sources/
+├── prds/
+├── rfcs/
+├── stories/
+├── wireframes/
+├── html-mocks/
+├── visual-references/
+├── interviews/
+├── attachments/
+└── legacy/
+```
+
+Depois disso, rode:
+
+```bash
+codesdd sdd ingest-deposito --source-dir .sdd/sources --title "Initial system planning"
+```
+
+This command scans sources, indexes raw material, creates or reuses an EPIC, breaks down FEATs, and tries to start the first ready FEAT.
+
+Depois disso, o sistema usa o indice de fontes e as skills curadas para transformar esse material em:
+
+- canonical context
+- EPIC
+- features
+- pending and resolved frontend gaps
+- consolidated frontend sitemap
+- insights only when real ambiguity exists
+
+## Skills incluidas no bootstrap
+
+The SDD bootstrap installs local curation in:
+
+```text
+.sdd/skills/curated/
+```
+
+The default curation currently includes 66 skills across 8 bundles (canonical source: `.sdd/state/skill-catalog.yaml`).
+
+Entre elas:
+
+- `repo-context-bootstrap`
+- `source-intake-sdd`
+- `business-extractor-sdd`
+- `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)
+
+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.
+
+Prompts recomendados tambem sao instalados em:
+
+```text
+.sdd/prompts/
+```
+
+Tambem sao instaladas skills curadas de apoio para execucao e planejamento.
+
+Para explorar bundles e sugestoes de adocao:
+
+- `codesdd sdd skills bundles`
+- `codesdd sdd skills suggest --phase plan --domains backend,api`
+
+## Arquivos importantes para onboarding
+
+Um agente novo deve seguir esta ordem:
+
+1. `README.md`
+2. `.sdd/AGENT.md`
+3. `.sdd/core/index.md`
+4. `.sdd/core/arquitetura.md`
+5. `.sdd/core/servicos.md`
+6. `.sdd/core/spec-tecnologica.md`
+7. `.sdd/core/repo-map.md`
+8. `.sdd/core/fontes.md`
+9. `.sdd/core/frontend-decisions.md`
+
+## Comandos principais
+
+Bootstrap:
+
+- `codesdd install --tools none`
+- `codesdd install --tools all`
+- `codesdd sdd init-context`
+- `codesdd sdd check --render`
+- `codesdd sdd check --render --strict`
+- `codesdd sdd diagnose`
+- `codesdd sdd diagnose --json`
+- `codesdd sdd diagnose --strict --output .sdd/reports/diagnose.json`
+- `codesdd sdd rebuild --from-disk --dry-run`
+- `codesdd sdd rebuild --from-disk --json`
+- `codesdd sdd sanitize --dry-run`
+- `codesdd sdd sanitize --from-report .sdd/reports/diagnose.json`
+- `codesdd sdd sanitize --dry-run --json`
+- `codesdd sdd sanitize --from-report .sdd/reports/diagnose.json --apply --yes`
+- `codesdd sdd sanitize rollback SAN-20260422T100000Z-ABCDEF12 --reason "restore before migration"`
+- `codesdd sdd audit`
+- `codesdd sdd metrics --since 7d`
+- `codesdd sdd metrics --since 24h --json`
+- `codesdd sdd dedup --apply --dry-run`
+- `codesdd sdd dedup --apply --json`
+- `codesdd sdd lint feature FEAT-0001`
+- `codesdd sdd lint feature FEAT-0001 --strict --json`
+- `codesdd sdd ingest-deposito`
+
+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 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`
+
+Descoberta:
+
+- `codesdd sdd insight "..."`
+- `codesdd sdd debate INS-0001`
+- `codesdd sdd decide DEB-0001 --outcome epic|discard`
+- `codesdd sdd desdobrar EPIC-0001 --mode graph --incremental`
+
+## Documentacao
+
+Guia detalhado em portugues:
+
+- [Manual SDD PT-BR](docs/sdd-manual-pt-br.md)
+- [Historia da Marina (uso pratico)](docs/historia-marina-uso-pratico.md)
+- [Release e Rollback](docs/release.md)
+- [Kit estatico do SDD](kits/codesdd-static-kit/README.md)
+- [Guia de contribuicao](CONTRIBUTING.md)
+- [Politica de seguranca](SECURITY.md)
+- [Codigo de conduta](CODE_OF_CONDUCT.md)
+- [Suporte](SUPPORT.md)
+
+Guia interno do sistema:
+
+- [.sdd/README.md](.sdd/README.md)
+- [.sdd/AGENT.md](.sdd/AGENT.md)
+
+## Desenvolvimento local
+
+```bash
+pnpm install
+pnpm run build
+pnpm test
+pnpm run lint
+pnpm run sdd:validate
+```
+
+Loop local do CLI:
+
+```bash
+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`.
+
+## Estado atual da distribuicao
+
+O comando global oficial deste fork e:
+
+```bash
+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.
+
+```bash
+npm install -g @devtrack-solution/codesdd
+```
+
+Fallback suportado:
+- instalacao por tarball (`npm pack` + `npm install -g ./devtrack-solution-codesdd-<versao>.tgz`)
+
+## Colaboracao
+
+Para contribuir com seguranca e previsibilidade:
+
+- siga [CONTRIBUTING.md](CONTRIBUTING.md);
+- reporte vulnerabilidades por [SECURITY.md](SECURITY.md);
+- respeite o [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md);
+- use [SUPPORT.md](SUPPORT.md) para escolher o canal certo.
+
+Este repositório foi preparado para ser público com foco em:
+
+- licença MIT explícita;
+- automação de CI e smoke test de instalação;
+- templates de issue e PR;
+- atualização automática de dependências;
+- hygiene de versionamento para evitar artefatos locais e arquivos sensíveis no repositório.
+
+## Telemetria e privacidade
+
+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 explícito por execução com `--no-telemetry`;
+- eventos de conclusão incluem `duration_ms` estruturado para observabilidade sem
+  enviar argumentos ou conteúdo.
+
+Se você identificar comportamento diferente disso, reporte via [SECURITY.md](SECURITY.md).
+
+## Licenca
+
+MIT
+
+<!-- SDD:ONBOARDING:START -->
+## Onboarding SDD
+
+Operational authority:
+- Canonical operational state, planning, dependencies, blockers, and handoff live only in `.sdd/state/*.yaml`.
+- 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.
+
+Read order for any new agent:
+1. `README.md` (this block)
+2. `.sdd/AGENT.md`
+3. `.sdd/core/index.md`
+4. `.sdd/core/arquitetura.md`
+5. `.sdd/core/servicos.md`
+6. `.sdd/core/spec-tecnologica.md`
+7. `.sdd/core/repo-map.md`
+8. `.sdd/core/fontes.md`
+9. `.sdd/core/frontend-sitemap.md` (when frontend is enabled)
+10. `.sdd/core/frontend-decisions.md` (when frontend is enabled)
+
+Essential commands:
+- `codesdd sdd onboard system`
+- `codesdd sdd next`
+- `codesdd sdd context <FEAT-ID>`
+- update `.sdd/active/<FEAT-ID>/5-quality.yaml`
+- `codesdd sdd frontend-impact <FEAT-ID> --status required|none --reason "..."`
+- `codesdd sdd finalize --ref <FEAT-ID>`
+<!-- SDD:ONBOARDING:END -->