@devtrack-solution/codesdd

v1.2.4

Published

11 days ago

AI-native system for spec-driven development

0High
0Medium
0Low

wiltonof

codesdd specs cli ai development

CodeSDD

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;
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.

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.

Backlog provider integration is documented as a projection-only boundary in 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: reconhecimento conceitual e fronteira clean-room (fora do fluxo operacional).
docs/THIRD_PARTY_NOTICES.md: notices tecnicos/licencas para dependencias runtime.
docs/service-catalog-maturity-epic-0097.md: scorecard e guardrails da maturidade 5 do catalogo de servicos.
positioning.md: narrativa de posicionamento enterprise do CodeSDD.

O que o CodeSDD faz

O CodeSDD organiza o desenvolvimento em 4 camadas:

Descoberta

INSIGHT: ideia bruta
DEBATE: discussao estruturada
EPIC: ideia aprovada para futuro planejamento
DISCARDED: ideia rejeitada com motivo registrado

Planejamento

EPIC pode ser quebrado em FEATs (RAD segue como alias legado)
FEAT vira unidade executavel
o backlog registra dependencias, bloqueios e paralelizacao

Execucao

cada FEAT ganha um workspace proprio em .sdd/active/FEAT-0001/
esse workspace tem spec, plan, tasks e changelog

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.

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.
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:

Adocao oficial do runtime DeepAgents governado.
Fronteira control plane (CodeSDD) vs execution plane (DeepAgents).
Autoridade de filesystem/memoria e regra sem fonte paralela de estado.
Politica de sandbox e worktree isolada.
Politica HITL e mapeamento de interrupt_on.
Interoperabilidade com plugin broker.
Interoperabilidade MCP e exposicao de ferramentas.
Interoperabilidade Reversa e evidencia de engenharia reversa.
Politica de execucao autonoma por tiers de risco.
Politica de .env, segredos e fingerprint de configuracao.
Contratos de evidencia estruturada e retencao.

O ADR charter desta formalizacao esta em .sdd/core/adrs/ADR-FEAT-0240.md.

O runtime DeepAgents e opt-in. A configuracao segura permanece desligada por padrao (CODESDD_DEEPAGENTS_ENABLED=false e CODESDD_DEEPAGENTS_RUNTIME=disabled), com modo fake para testes deterministicos sem credenciais e modo deepagents-js para a implementacao nativa Node/TypeScript carregada sob politica, HITL e contrato de modelo. O pacote npm deepagents e carregado de forma dinamica, apenas quando esse modo real passa nos checks de prontidao. A fronteira Node/TypeScript passa pela factory src/core/sdd/deepagents/runtime-factory.ts, que entrega adapters separados para disabled, fake e deepagents-js sem transformar DeepAgents em fonte canonica de estado. As tools CodeSDD para DeepAgents sao uma projecao governada do registro MCP em src/core/sdd/deepagents/codesdd-tools.ts, e o enforcement de env, rede, HITL e writes planejados passa por src/core/sdd/deepagents/policy-enforcement.ts antes de qualquer instanciacao real. As saidas do runtime sao normalizadas por src/core/sdd/deepagents/evidence-mapper.ts para os contratos deepagent-run-*, deepagent-tool-call-*, deepagent-subagent-*, deepagent-decision-* e deepagent-quality-*. O comando codesdd sdd agent run <FEAT-ID> --provider deepagents ja consome essa fronteira TypeScript: no modo disabled, ele registra evidencia de runtime bloqueado sem instanciar agente; no modo fake, executa o adapter deterministico sem credenciais; e no modo deepagents-js, so materializa o adapter nativo quando os feature toggles, modelo, credencial de launcher e politicas passam. Falhas de prontidao viram evidencia estruturada fail-closed. Para validar uma mudanca antes de invocar runtime, use codesdd sdd preflight <FEAT-ID> --intent-operation <op> --write-scope <glob> --planned-writes <path> --json. Esse comando executa os mesmos guardrails de mutacao com runtime_skipped: true e emite telemetria segura em evidence.guardrail_telemetry, contendo apenas decisao, status por gate, nivel de risco e classificacoes agregadas, sem paths brutos, texto de objetivo ou valores de override. Os cenarios golden de EPIC-0078 cobrem catalogo aditivo permitido, substituicao bloqueada, override valido, override invalido e refactor amplo legitimo. O smoke operacional padrao esta em pnpm run test:deepagents-smoke, cobrindo disabled e fake sem segredos nem rede; o smoke real de provedor so roda com CODESDD_DEEPAGENTS_PROVIDER_SMOKE=1, modelo, chave de launcher e dominio de rede explicitamente liberado. Para diagnostico local, codesdd config doctor --json executa preflight operacional e reporta status disabled|ready|blocked para runtime/provider, modelo, variaveis obrigatorias, endpoint e politica de rede sem imprimir credenciais. Modelos hospedados na Azure e endpoints OpenAI-compatible usam provider profiles governados (azure-openai:, azure-ai:, openai-compatible:, xai:/grok:, moonshot:/kimi: e cohere:/coyers:). Credenciais e endpoints podem vir de variaveis nomeadas por CODESDD_DEEPAGENTS_CREDENTIAL_ENV e CODESDD_DEEPAGENTS_ENDPOINT_ENV; o CodeSDD registra apenas nomes, presenca e fingerprints, nunca valores de segredo. Saidas de diagnostico/configuracao tambem aplicam redaction por chave sensivel (*key*, *secret*, *token*, *password*, *credential*, *private*, *auth*) para evitar leakage acidental em stdout, JSON e contratos de evidencia. Para Azure OpenAI, aliases de deployment divergentes (AZURE_OPENAI_DEPLOYMENT vs AZURE_OPENAI_DEPLOYMENT_NAME) entram em fail-fast e bloqueiam o runtime; a precedencia valida usa AZURE_OPENAI_DEPLOYMENT_NAME, depois AZURE_OPENAI_DEPLOYMENT, depois AZURE_OPENAI_API_DEPLOYMENT_NAME.

Coordenacao opcional com Redis

Redis e uma fronteira opcional para coordenacao tecnica de locks, cache, filas e eventos. Ele nao substitui a autoridade operacional de .sdd/state/*.yaml.

Por padrao, CodeSDD usa locks em filesystem, 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:

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.
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:

[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:

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:

[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:

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.

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.

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

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 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 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/ (YAML workspace templates)
.sdd/skills/curated/
.sdd/sources/
.sdd/prompts/

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/legacy-spec-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:

npm install -g @devtrack-solution/codesdd

O binario principal publicado pelo pacote e codesdd. Depois de instalar, confira:

codesdd --version

Se o terminal nao encontrar codesdd, a instalacao provavelmente foi concluida, mas o diretorio global do npm nao esta no PATH da sua sessao. Nesses casos, adicione o alias abaixo para o seu sistema operacional.

Configuracao global do CodeSDD

Caminho canonico: ~/.codesdd/config.toml
Compatibilidade de leitura: ~/.config/codesdd/config.json (somente fallback)
O comando codesdd config path sempre exibe o caminho canonico atual.
Cache global: ~/.codesdd/cache com tiers logicos providers, projects, schemas, deepagents e plugins.
O tier projects usa fingerprint por raiz de projeto para evitar colisao de cache entre repositorios.
codesdd config init cria/normaliza ~/.codesdd/config.toml, ~/.codesdd/cache/** e ~/.codesdd/env.zsh com conteudo nao secreto.
Em shell Zsh, codesdd config init garante um bloco idempotente no ~/.zshrc para source ~/.codesdd/env.zsh.
A fronteira funcional e validavel: estado versionado do projeto fica em .sdd; config/runtime/cache comum fica em ~/.codesdd; .codesdd dentro do repositorio e invalido para novo estado.
codesdd config doctor --json expoe storage_boundary com project_state_dir, global_runtime_dir, global_cache_dir, tiers de cache e regras de separacao.
codesdd 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.

Fluxo seguro recomendado:

codesdd config init
codesdd config path
codesdd config list
codesdd config doctor --json

Para validar o modo deterministico sem credenciais:

CODESDD_DEEPAGENTS_ENABLED=true \
CODESDD_DEEPAGENTS_RUNTIME=fake \
codesdd config doctor --json

Windows 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

Linux

Para Bash:

npm install -g @devtrack-solution/codesdd
printf "\nalias codesdd='%s'\n" "$(npm prefix -g)/bin/codesdd" >> ~/.bashrc
. ~/.bashrc
codesdd --version

Para Zsh:

npm install -g @devtrack-solution/codesdd
printf "\nalias codesdd='%s'\n" "$(npm prefix -g)/bin/codesdd" >> ~/.zshrc
. ~/.zshrc
codesdd --version

macOS / MacBook

O shell padrao atual do macOS e Zsh:

npm install -g @devtrack-solution/codesdd
printf "\nalias codesdd='%s'\n" "$(npm prefix -g)/bin/codesdd" >> ~/.zshrc
. ~/.zshrc
codesdd --version

Se voce estiver desenvolvendo este fork localmente:

pnpm install
pnpm run build
npm install -g .

Atalhos uteis de manutencao local:

pnpm run cleanup
pnpm run cleanup:install
pnpm run quality:review

cleanup: remove artefatos de build/cache local, rastros de ambiente (.DS_Store, .idea/, .claude/), stores legados de contexto local e logs de falha de compilacao/execucao.
cleanup:install: faz a limpeza acima e tambem remove node_modules/ e lockfiles alternativos locais (package-lock.json, yarn.lock, bun.lock*), preservando o pnpm-lock.yaml versionado.
quality:review: executa build, lint, testes, cobertura, validacao SDD e pack-version sem remover node_modules/ nem executar pnpm install; use em revisoes/auditorias que nao devem limpar o workspace.

Antes de release, gere o resumo nao mutante de prontidao:

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:

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:

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:

codesdd sdd insight "descreva a mudanca ou iniciativa"

Se quiser fixar idioma/layout em portugues:

codesdd sdd init-context --lang pt-BR --layout pt-BR

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:

codesdd install --tools all

Ou somente algumas:

codesdd install --tools codex,cursor,claude

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:

.sdd/config.yaml
.sdd/
estados YAML canonicos
documentos iniciais do projeto

Se voce nao quiser habilitar frontend na inicializacao de contexto:

codesdd sdd init-context --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, rode o mesmo comando na raiz:

codesdd sdd init-context
codesdd sdd check --render
codesdd sdd onboard system

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:

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
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.

Para reconfigurar um projeto ja inicializado com os artefatos, templates, skills e views da versao instalada do CLI, use:

codesdd reload --tools none --lang en-US --layout en-US

Como usar no dia a dia

Fluxo principal:

Ver o sistema como um todo

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:

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:

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:

codesdd sdd import-legacy-spec --dry-run
codesdd sdd import-legacy-spec
codesdd sdd import-legacy-spec --remove --yes

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/_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.

Ver o que pode comecar agora

codesdd sdd next

Para operar o plano sem adivinhar, use:

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):

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:

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:

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:

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:

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:

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.

Iniciar uma feature

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.

Ler o contexto da feature

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 o contrato antes de empacotar ou publicar:

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:

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:

codesdd install --tools codex
codesdd config init
codesdd sdd mcp-manifest --provider codex --json
codesdd sdd mcp-call codesdd.next --provider codex --json

Exemplo de smoke live OpenAI, com credencial somente no launcher:

export CODESDD_DEEPAGENTS_PROVIDER_SMOKE=1
export CODESDD_AGENT_PROVIDER=deepagents
export CODESDD_DEEPAGENTS_ENABLED=true
export CODESDD_DEEPAGENTS_RUNTIME=deepagents-js
export CODESDD_DEEPAGENTS_MODEL=openai:gpt-4o-mini
export CODESDD_AGENT_NETWORK_POLICY=restricted
export CODESDD_AGENT_ALLOWED_DOMAINS=api.openai.com
export OPENAI_API_KEY="<secret-from-manager>"
codesdd config doctor --json

A fundacao MCP do CodeSDD e agnostica a provedor e publica o envelope codesdd-mcp-bridge/v1 para as ferramentas canonicas codesdd.next, codesdd.context, codesdd.query, codesdd.read e os demais nomes codesdd.* documentados pelo manifest.

Agent Runtime v2 exporta planos de comando para DeepAgents, Codex exec e OpenCode run. Para OpenCode, o contrato agent-runtime-opencode-run-evidence.schema.json registra execucao, artefatos, validacoes e trechos redigidos sem permitir escrita direta em estado SDD; o finalize do CodeSDD continua sendo o unico escritor canonico do ciclo de vida.

Perfis aceitos por --provider: codex, claude-code, kimmy-code, kilo-code, open-code e generic. Para OpenCode/Open Code, o bridge MCP usa o identificador open-code. 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, mantida por FEAT-0164/Worker 4, para a tabela de clientes, IDs MCP, aliases, evidencias esperadas e a diferenca entre open-code e opencode.

Implementar
Consolidar memoria ao final

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.

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 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 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 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 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 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
sanitizeSddRoot(payload): Promise
verifySddBoundary(payload): Promise 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:

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:

.sdd/sources/

Estrutura:

.sdd/sources/
├── prds/
├── rfcs/
├── stories/
├── wireframes/
├── html-mocks/
├── visual-references/
├── interviews/
├── attachments/
└── legacy/

Depois disso, rode:

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:

.sdd/skills/curated/

The default curation currently includes 79 skills across 11 bundles (canonical source: .sdd/state/skill-catalog.yaml). Skill catalog entries now follow the v2 metadata contract with token_budget, integrity_hash, deterministic_pair, deprecated_at, and superseded_by for routing governance and lifecycle traceability. codesdd sdd skills sync now enforces SHA-256 drift detection by layer: canonical curated skills block sync on missing/modified manifest hash, while user-extension skills emit non-blocking alerts so local customization remains possible.

Entre elas:

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

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:

.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:

README.md
.sdd/AGENT.md
.sdd/core/index.md
.sdd/core/arquitetura.md
.sdd/core/servicos.md
.sdd/core/spec-tecnologica.md
.sdd/core/repo-map.md
.sdd/core/fontes.md
.sdd/core/frontend-decisions.md

Comandos principais

Inicializacao e reparo de projeto:

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
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

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 "..."
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:

Guia interno do sistema:

Desenvolvimento local

pnpm install
pnpm run build
pnpm test
pnpm run lint
pnpm run sdd:validate

Loop local do CLI:

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 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:

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

O comando global oficial deste fork e:

codesdd

O caminho de distribuicao oficial deste repositorio e npm. Veja a secao Instalacao global para instalar globalmente.

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;
reporte vulnerabilidades por SECURITY.md;
respeite o CODE_OF_CONDUCT.md;
use 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 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.

Se você identificar comportamento diferente disso, reporte via SECURITY.md.

Licenca

MIT

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.

Initial operational directives:

CodeSDD is the official planner for any build request; other planners or agent-native plans are secondary execution aids only.
In initialized CodeSDD repositories, any user request that implies implementation, file edits, validation, execution, or finalize must be treated as requiring CodeSDD planning unless the user explicitly marks it as read-only or outside CodeSDD.
For change requests, agents must bind the work to an active or ready FEAT through codesdd sdd next and codesdd sdd context <FEAT-ID> before implementation; agent-native plans may only decompose execution after that CodeSDD context exists.
For API/backend work, 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).

Read order for any new agent:

README.md (this block)
.sdd/AGENT.md
.sdd/core/index.md
.sdd/core/arquitetura.md
.sdd/core/servicos.md
.sdd/core/spec-tecnologica.md
.sdd/core/repo-map.md
.sdd/core/fontes.md
.sdd/core/frontend-sitemap.md (when frontend is enabled)
.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>
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