sdd-flow 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.pt-BR.md CHANGED
@@ -1,100 +1,414 @@
1
- # sdd-flow
2
-
3
- Framework de processo para desenvolvimento assistido por IA, com contexto selecionado por tarefa,
4
- rastreabilidade e verificação vinculada à versão testada.
5
-
6
- Este checkout prepara a versão 2.0.0. A publicação no npm é uma ação de release separada.
7
- O foco é metodológico: organização, contexto pertinente e rastreabilidade, sem criar um orquestrador.
8
- Requer Node.js 22 ou superior. Para testar este código:
9
-
10
- ~~~sh
11
- npm ci
12
- npm link
13
- cd /caminho/do/projeto
14
- sdd init --harness claude-code
15
- ~~~
16
-
17
- Também há adaptador para OpenCode: sdd harness opencode.
18
- Complete agents/SETUP.md, configure os comandos reais em agents/config.yaml e execute sdd doctor.
19
-
20
- ## Princípios
21
-
22
- - Mantenha o AGENTS.md curto, com navegação para os documentos relevantes.
23
- - Separe conhecimento vigente, mudança ativa e histórico.
24
- - Descubra skills por name e description; carregue seu corpo quando necessário.
25
- - Use tarefas por resultado verificável, podendo alterar vários arquivos.
26
- - Escolha modo light, standard ou rigorous e autonomia step ou batch.
27
- - Mantenha o estado das tarefas apenas no front matter de TASK.md.
28
- - Aprove o escopo autorizado, sem exigir aprovações de arquivos de progresso vazios.
29
- - Verifique com comandos reais e evidência de execução. Testes manuais podem passar.
30
- - Diferencie checks obrigatórios e informativos; registre limitações externas sem exigir testes arriscados em produção.
31
- - Consolide contratos vigentes antes da verificação final e do arquivamento.
32
-
33
- ## Fluxo
34
-
35
- ~~~sh
36
- sdd new minha-mudanca --mode standard
37
- sdd context 001-minha-mudanca --phase plan
38
- # Preencha SPEC.md e TASK.md nos formatos documentados.
39
- sdd check 001-minha-mudanca
40
- # Somente após autorização real do usuário para esse escopo:
41
- sdd approve 001-minha-mudanca --by "Moisés"
42
- sdd context 001-minha-mudanca --phase implement --task T01
43
- # Implemente, verifique e atualize a tarefa.
44
- sdd verify 001-minha-mudanca --scope partial
45
- # Consolide os documentos vigentes e conclua as tarefas.
46
- sdd verify 001-minha-mudanca
47
- sdd close 001-minha-mudanca --by "Moisés" --note "Sem alteração de contrato duradouro" --archive
48
- ~~~
49
-
50
- Para verificação manual/inspeção, sdd evidence ID cria um registro para os inputs atuais.
51
- Execute o cenário, preencha resultado, executor, data e observações e use
52
- sdd verify ID --evidence agents/specs/ID/EVIDENCE.json.
53
- Se código ou contrato mudar, a evidência anterior fica obsoleta.
54
-
55
- Sem ambiente adequado, sdd handoff ID prepara um registro de limitações para preencher.
56
- sdd verify ID --handoff CAMINHO gera USER_TESTS.md e pode resultar em limited.
57
- Isso permite encerrar a implementação com pendências explícitas, sem declarar teste externo aprovado.
58
- Leia o [guia de qualidade e falta de ambiente](docs/quality-gates.pt-BR.md) para TDD/BDD, gates e o roteiro seguro ao usuário.
59
-
60
- ## Front matter e contexto
61
-
62
- Front matter é metadado estruturado, interpretado por um parser YAML real.
63
- Skills usam name e description do formato Agent Skills. Contratos do workflow usam schema_version,
64
- tipo de artefato e seus campos específicos. README e textos apenas humanos não precisam de metadados.
65
-
66
- O comando context seleciona as referências declaradas em change.yaml, a fase e a tarefa.
67
- Também permite seções por título exato. Não há extração de um número fixo de linhas.
68
- Se o limite em bytes for excedido, o comando apresenta o problema sem truncar instruções.
69
- O limite mede bytes, não tokens, e pode ser configurado.
70
-
71
- ## Distribuição e manutenção
72
-
73
- ~~~sh
74
- sdd update --dry-run
75
- sdd harness claude-code
76
- sdd harness opencode
77
- sdd export claude-code --out packages/claude-code
78
- sdd export opencode --out packages/opencode
79
- ~~~
80
-
81
- Os adaptadores instalam comandos e uma skill nos diretórios ativos das ferramentas.
82
- Não alteram permissões nativas nem removem configurações antigas silenciosamente.
83
- A exportação prepara diretórios versionáveis; não publica nem instala plugins.
84
-
85
- Consulte os [formatos](docs/formats.md), a [migração](docs/migration.md),
86
- a [distribuição](docs/distribution.md) e os [critérios de qualidade](docs/quality.md).
87
- A CLI valida estrutura e executa checks; revisão semântica e permissões continuam necessárias.
88
-
89
- O [guia de uso](docs/usage.pt-BR.md) explica adoção em projetos existentes, início do zero,
90
- excesso de contexto, regras particulares, skills e mudanças de escopo.
91
- O [guia de publicação](docs/releases.pt-BR.md) distingue PR, merge, publicação npm e atualização dos consumidores.
92
-
93
- Consulte a [metodologia e comparação das versões](docs/methodology.pt-BR.md) e o
94
- [roteiro de testes locais](docs/local-testing.pt-BR.md), com exemplos PowerShell.
95
- Configure documentation.language: pt-BR em agents/config.yaml para documentos do projeto em português.
96
- Preserve UTF-8 e acentuação; chaves técnicas e IDs não devem ser traduzidos.
97
-
98
- O [guia de perguntas do setup e documentos](docs/setup-documents.pt-BR.md) distingue PRD, ADR, system design e design system.
99
- sdd init --docs restaura a criação opcional de prd.md, roadmap.md e architecture.md.
100
- Para selecionar referências, use sdd docs --types prd,sd,ds,adr,roadmap. Documentos existentes são preservados.
1
+ <div align="center">
2
+
3
+ # sdd-flow
4
+
5
+ ### Um fluxo claro para desenvolver com IA.
6
+
7
+ Contexto relevante para o agente.<br>
8
+ Mudanças bem definidas para você.<br>
9
+ Histórico rastreável para o projeto.
10
+
11
+ ![Node.js 22 ou superior](https://img.shields.io/badge/Node.js-%E2%89%A5%2022-417E38)
12
+ ![Licença MIT](https://img.shields.io/badge/licen%C3%A7a-MIT-2563EB)
13
+ ![Metodologia portátil](https://img.shields.io/badge/metodologia-independente%20de%20stack-475569)
14
+
15
+ [English](README.md) · [Começar](#comece-em-3-passos) · [Entender o fluxo](#como-funciona) · [Contexto](#como-o-contexto-permanece-enxuto) · [Documentação](#documentação)
16
+
17
+ </div>
18
+
19
+ ---
20
+
21
+ **O sdd-flow organiza o desenvolvimento assistido por IA em mudanças pequenas o suficiente para entender, implementar e verificar.**
22
+
23
+ Você descreve o que precisa. O agente consulta as referências pertinentes, prepara uma spec, implementa o escopo autorizado e registra os resultados. O conhecimento e o andamento permanecem no repositório, disponíveis para a próxima sessão.
24
+
25
+ | Organização | Contexto | Rastreabilidade |
26
+ |---|---|---|
27
+ | Uma spec por mudança coesa | Fontes selecionadas por fase e tarefa | Requisitos, tarefas, decisões e verificações conectados |
28
+
29
+ **No dia a dia, seu foco continua na spec.** O agente e o CLI mantêm os registros de apoio. Configuração, skills e documentos gerais são consultados quando pertinentes.
30
+
31
+ ## Como funciona
32
+
33
+ ```mermaid
34
+ flowchart TD
35
+ A["Você descreve a mudança"] --> B["Agente pesquisa e planeja"]
36
+ B --> C["Você revisa o escopo"]
37
+ C --> D["Agente implementa e verifica"]
38
+ D --> E{"Resultado"}
39
+ E -->|"Precisa de ajuste"| D
40
+ E -->|"Pronto para encerrar"| F["Consolidar e registrar a entrega"]
41
+ D -. "Regra mudou" .-> B
42
+ ```
43
+
44
+ **Pesquisar → planejar → implementar → validar → encerrar.** As etapas são responsabilidades do trabalho; podem acontecer na mesma conversa.
45
+
46
+ - **Antes:** esclarecer o objetivo, definir aceitação e considerar impactos.
47
+ - **Durante:** executar tarefas coesas e verificar regressões.
48
+ - **Depois:** registrar o que foi observado e atualizar o conhecimento vigente.
49
+
50
+ O framework serve tanto para **projetos novos** quanto para **aplicações em desenvolvimento**, com qualquer stack. Node.js 22+ é necessário para o CLI, não para a aplicação que você está construindo.
51
+
52
+ ## Comece em 3 passos
53
+
54
+ > **Versão deste README: 2.1.** A gestão flexível de specs é nova nesta versão. Confira a versão com `sdd --version`.
55
+
56
+ ### 1. Instale o CLI
57
+
58
+ Com Node.js 22+:
59
+
60
+ ```sh
61
+ npm install -g sdd-flow
62
+ sdd --version
63
+ ```
64
+
65
+ <details>
66
+ <summary>Outras opções: executar sem instalar ou pelo código-fonte</summary>
67
+
68
+ Executar sem instalação global:
69
+
70
+ ```sh
71
+ npx sdd-flow@latest --help
72
+ ```
73
+
74
+ Pelo código-fonte do **sdd-flow** (para quem contribui):
75
+
76
+ ```sh
77
+ npm ci
78
+ npm link
79
+ sdd --version
80
+ ```
81
+
82
+ Instalar o pacote disponibiliza o CLI. Os arquivos do método entram em cada aplicação ao executar `sdd init`.
83
+
84
+ </details>
85
+
86
+ ### 2. Ative no seu projeto
87
+
88
+ ```sh
89
+ cd /caminho/do/seu-projeto
90
+ sdd init
91
+ ```
92
+
93
+ Usa Claude Code ou OpenCode? Você pode instalar seus pontos de entrada:
94
+
95
+ ```sh
96
+ sdd harness claude-code
97
+ # Alternativa: sdd harness opencode
98
+ ```
99
+
100
+ Em outros ambientes, indique ao agente o `AGENTS.md` do projeto. O núcleo usa arquivos e comandos, sem exigir um adaptador específico.
101
+
102
+ ### 3. Use seus prompts habituais
103
+
104
+ Para configurar o projeto:
105
+
106
+ ```text
107
+ Leia e siga as instruções do arquivo agents/SETUP.md para configurar o workflow.
108
+ ```
109
+
110
+ Depois, apresente a demanda e indique a etapa. Prompts curtos continuam sendo suficientes:
111
+
112
+ | Etapa | Pedido ao agente |
113
+ |---|---|
114
+ | Pesquisa | Leia e siga as instruções do arquivo agents/prompts/rpi-research.md. |
115
+ | Planejamento | Leia e siga as instruções do arquivo agents/prompts/rpi-plan.md. |
116
+ | Implementação | Leia e siga as instruções do arquivo agents/prompts/rpi-implement.md. |
117
+ | Validação | Leia e siga as instruções do arquivo agents/prompts/rpi-validate.md. |
118
+ | Encerramento | Leia e siga as instruções do arquivo agents/prompts/rpi-close.md. |
119
+
120
+ Os procedimentos contêm as instruções do método; você não precisa repeti-las no chat.
121
+ A demanda e a spec precisam estar identificadas. Se houver várias mudanças ou uma sessão sem contexto,
122
+ informe o ID, como “Use a spec 001-exportar-dados”, ou deixe o agente esclarecer essa ambiguidade.
123
+
124
+ O setup é inicial. Depois de concluído, `SETUP.md` pode ser removido; não é necessário refazê-lo a cada spec.
125
+ Idioma e padrões particulares ficam na configuração e nas políticas do projeto.
126
+
127
+ **Seu foco continua na spec, nas tarefas e no resultado da validação.** O agente usa o CLI e mantém
128
+ os registros de apoio. Você pode acompanhar as etapas na mesma conversa.
129
+
130
+ Para uma aplicação existente, o setup registra uma baseline observada. Não refatora o projeto
131
+ nem inventa specs para o passado.
132
+
133
+ ## O que entra no repositório
134
+
135
+ | Conjunto | Para que serve |
136
+ |---|---|
137
+ | `AGENTS.md` e `QUICKSTART.md` | Entrada e orientação inicial |
138
+ | `agents/PROJECT.md` | Mapa curto da aplicação e suas fontes |
139
+ | `agents/POLICIES.md` e `agents/QUALITY.md` | Particularidades e critérios do projeto |
140
+ | `agents/config.yaml` | Idioma, autonomia, rigor e comandos de verificação |
141
+ | `agents/RULES.md`, `agents/AGENTS.md` e `agents/prompts/` | Método e procedimentos |
142
+ | `agents/specs/` | Mudanças em andamento |
143
+ | `agents/current/` e decisões ativas | Conhecimento vigente |
144
+ | `agents/archive/` | Mudanças encerradas |
145
+ | `agents/skills/` | Procedimentos reutilizáveis do projeto |
146
+
147
+ A instalação também inclui modelos e controles de manutenção. **Não cria funcionalidades nem specs fictícias.** `SETUP.md` orienta a configuração e pode ser removido após concluí-la.
148
+
149
+ Cada spec reúne os artefatos necessários:
150
+
151
+ | Artefato | Papel |
152
+ |---|---|
153
+ | `change.yaml` | Identidade, referências, dependências e ciclo de vida |
154
+ | `SPEC.md` | Requisitos e aceitação |
155
+ | `TASK.md` | Plano e estado das tarefas, quando aplicável |
156
+ | `RESEARCH.md` | Pesquisa, quando necessária ou exigida pelo modo |
157
+ | Evidências e registros de execução | O que foi verificado, para qual versão e com qual resultado |
158
+
159
+ O agente mantém esses artefatos conforme o trabalho avança. Pesquisa, evidências e histórico não são todos gerados por `sdd new`.
160
+
161
+ ## Como o contexto permanece enxuto
162
+
163
+ **O repositório guarda o conhecimento. O agente recebe uma seleção pertinente para o trabalho atual.**
164
+
165
+ ```mermaid
166
+ flowchart TD
167
+ A["Spec e tarefa atual"] --> D["Selecionar contexto"]
168
+ B["Contratos, decisões e skills"] --> D
169
+ C["Referências pertinentes de docs/"] --> D
170
+ D --> E{"Cabe no orçamento?"}
171
+ E -->|"Sim"| F["Entregar pacote ao agente"]
172
+ E -->|"Não"| G["Revisar fontes, seções e escopo"]
173
+ G --> D
174
+ ```
175
+
176
+ - O ponto de entrada é um mapa curto.
177
+ - A fase e a tarefa orientam a seleção.
178
+ - Skills são descobertas por nome e descrição; o corpo é carregado quando selecionado.
179
+ - Documentos extensos podem ser referenciados por seção.
180
+ - O histórico completo não entra automaticamente em cada sessão.
181
+ - `TASK.md` concentra o andamento; `STATE.md` é uma retomada curta e opcional.
182
+
183
+ ```sh
184
+ sdd context 001-minha-mudanca --phase implement --task T01 --inspect
185
+ ```
186
+
187
+ A inspeção mostra o tamanho e os documentos contribuintes, sem emitir seus corpos. O orçamento padrão é **48.000 bytes**, configurável; não é uma contagem de tokens nem o limite total da conversa.
188
+
189
+ Se o pacote ultrapassar o orçamento, a geração informa o problema **sem truncar conteúdo silenciosamente**. O agente pode selecionar seções, revisar referências ou separar entregas independentes.
190
+
191
+ A seleção depende de referências bem mantidas. O CLI não descobre sozinho todos os efeitos de uma mudança nem controla o histórico do chat.
192
+
193
+ ## Use docs/ como seu acervo de referências
194
+
195
+ PRD, regras de negócio, System Design, ADRs, Design System, contratos e materiais externos podem continuar organizados em `docs/`, com ou sem subpastas.
196
+
197
+ **Centralize as fontes; selecione a leitura.** O agente consulta o índice e os documentos pertinentes, preservando a origem e identificando o que está vigente.
198
+
199
+ Exemplo de referência em `change.yaml`:
200
+
201
+ ```yaml
202
+ sources:
203
+ - path: docs/produto/prd.md
204
+ section: Exportação de dados
205
+ context:
206
+ - path: docs/design/design-system.md
207
+ section: Estados e interações
208
+ ```
209
+
210
+ Não há um conjunto obrigatório de documentos. Uma descrição clara pode bastar para iniciar um projeto.
211
+
212
+ Quer modelos opcionais?
213
+
214
+ ```sh
215
+ sdd docs --types prd,sd,ds,adr,roadmap --dry-run
216
+ sdd docs --types prd,sd,ds,adr,roadmap
217
+ ```
218
+
219
+ Arquivos existentes são preservados. Os novos são rascunhos para revisão. Consulte [setup e documentos](docs/setup-documents.pt-BR.md).
220
+
221
+ ## Organize specs sem perder o trabalho
222
+
223
+ Nome da pasta e número visual podem mudar mantendo o ID técnico. Você pode arquivar specs inacabadas,
224
+ restaurar ou remover conteúdo obsoleto. Remoção é recuperável por padrão; exclusão definitiva é explícita.
225
+
226
+ Referências históricas ausentes geram avisos. Pré-requisitos desconhecidos precisam de análise,
227
+ sem exigir que outra spec seja refeita nem inventar que algo foi concluído.
228
+
229
+ <details>
230
+ <summary>Renomear, arquivar, restaurar e descartar</summary>
231
+
232
+ ```sh
233
+ sdd rename 015-exportacao --name exportar-relatorios --number 3 --by "Responsável" --reason "Organizar" --dry-run
234
+ sdd archive 015-exportacao --by "Responsável" --reason "Retirar da área ativa"
235
+ sdd restore 015-exportacao --by "Responsável" --reason "Retomar"
236
+ sdd remove 015-exportacao --by "Responsável" --reason "Obsoleta" --dry-run
237
+ sdd reconcile --dry-run
238
+ sdd status --all
239
+ ```
240
+
241
+ Use os IDs reais e revise as prévias. Rename preserva o ID 015-exportacao mesmo com a pasta 003-exportar-relatorios.
242
+ Reconcile atualiza apenas o inventário observado; não altera requisitos nem fabrica evidência.
243
+ Contratos vigentes ficam disponíveis independentemente das pastas históricas.
244
+ Leia [gestão de specs](docs/spec-management.pt-BR.md) para aplicação, descarte permanente e recuperação.
245
+
246
+ </details>
247
+
248
+ ## Rigor proporcional à mudança
249
+
250
+ | Modo | Quando usar |
251
+ |---|---|
252
+ | `light` | Mudança pequena; tarefas e pesquisa podem ser dispensadas |
253
+ | `standard` | Funcionalidade delimitada, com tarefas verificáveis |
254
+ | `rigorous` | Mudança sensível ou com maior incerteza, com pesquisa e aprovação explícitas |
255
+
256
+ O padrão de instalações novas é **step**: implementar e verificar uma tarefa e parar para revisão.
257
+ Autorize tarefas específicas ou todas as tarefas para continuar em lote sem confirmações repetidas.
258
+ Aprovar o plano, por si só, não muda essa autonomia. **Batch** também pode ser a preferência permanente;
259
+ atualizações preservam a escolha existente. Cada tarefa continua sendo verificada, respeitando dependências.
260
+
261
+ ## Verificação honesta, inclusive sem ambiente externo
262
+
263
+ O CLI executa checks configurados e registra comandos, resultados e inputs. Aprovações ficam vinculadas ao plano; verificações ficam vinculadas à versão examinada.
264
+
265
+ | Resultado | O que significa |
266
+ |---|---|
267
+ | `passed` | Verificação integral aprovada para os inputs atuais |
268
+ | `limited` | Implementação concluída com limitações externas e pendências explícitas |
269
+ | `partial` | Ainda não há condições para o encerramento final |
270
+ | `failed` | Há falha obrigatória observada ou alteração de inputs durante a execução |
271
+
272
+ **Falta de produção ou homologação não precisa bloquear uma implementação pronta.** Um handoff pode registrar o que falta e gerar um roteiro seguro em `USER_TESTS.md`.
273
+
274
+ `limited` não significa que o teste externo passou e não autoriza deploy. Uma falha conhecida não desaparece ao omitir sua evidência.
275
+
276
+ Checks obrigatórios bloqueiam em caso de falha; indicadores informativos aparecem como avisos. TDD, exemplos BDD e métricas podem ser adotados conforme o projeto, sem uma ferramenta ou percentual universal obrigatório.
277
+
278
+ Leia o [guia de qualidade e falta de ambiente](docs/quality-gates.pt-BR.md).
279
+
280
+ ## Portabilidade e escopo
281
+
282
+ | O sdd-flow organiza | O harness fornece |
283
+ |---|---|
284
+ | Método, specs, contexto e rastreabilidade | Modelos, ferramentas e permissões |
285
+ | Referências e evidências | MCPs e acesso a serviços |
286
+ | Pontos de entrada e conhecimento exportável | Compactação e eventual delegação |
287
+
288
+ O método pode ser seguido em uma conversa, em sessões separadas ou com delegação nativa. **Não exige multiagentes nem cria um orquestrador próprio.**
289
+
290
+ Adaptadores para Claude Code e OpenCode fornecem comandos e uma skill do workflow. Exports preparam conhecimento para distribuição; não publicam em marketplaces. Veja [adaptadores e distribuição](docs/distribution.md).
291
+
292
+ ## Para agentes de IA
293
+
294
+ 1. Comece pelo `AGENTS.md` e pelo mapa do projeto.
295
+ 2. Use `SETUP.md` na adoção inicial; depois siga o procedimento da fase.
296
+ 3. Consulte as fontes pertinentes, sem carregar toda a pasta `docs/`.
297
+ 4. Preserve IDs, regras vigentes, arquitetura observada e trabalho existente.
298
+ 5. Considere consumidores e regressões antes de alterar comportamento compartilhado.
299
+ 6. Registre autorização real, resultados observados e limitações.
300
+ 7. Mantenha o estado canônico e consolide o conhecimento antes de encerrar.
301
+
302
+ Metadados estruturados usam YAML; não há dependência de números fixos de linha. Documentos de referência são dados do projeto e não substituem a autorização do usuário.
303
+
304
+ <details>
305
+ <summary>Comandos essenciais para uma mudança</summary>
306
+
307
+ Exemplo com ID ilustrativo; o agente precisa preencher o plano entre os comandos:
308
+
309
+ ```sh
310
+ sdd new minha-mudanca --mode standard
311
+ sdd context 001-minha-mudanca --phase plan
312
+ # Definir requisitos, aceitação, tarefas e referências.
313
+ sdd check 001-minha-mudanca
314
+
315
+ # Registrar somente a autorização realmente concedida:
316
+ sdd approve 001-minha-mudanca --by "Responsável"
317
+
318
+ sdd context 001-minha-mudanca --phase implement --task T01
319
+ # Implementar, verificar e atualizar as tarefas.
320
+ # Consolidar os contratos vigentes antes da verificação final.
321
+ sdd verify 001-minha-mudanca
322
+ sdd close 001-minha-mudanca --by "Responsável" --archive
323
+ ```
324
+
325
+ O fechamento exige consolidação das capacidades selecionadas ou `--note` explicando por que não há atualização duradoura. Evidências manuais e limitações externas usam os argumentos específicos de verificação.
326
+
327
+ `sdd check` valida estrutura; `sdd verify` executa os checks configurados. Não são a mesma operação.
328
+
329
+ </details>
330
+
331
+ ## Reinstalar ou atualizar sem começar de novo
332
+
333
+ O instalador 2.x distingue arquivos do projeto e arquivos gerenciados do método.
334
+
335
+ | Situação | Comportamento esperado |
336
+ |---|---|
337
+ | `init` repetido na mesma versão | Preserva configuração e trabalho existentes; arquivos ausentes podem ser repostos |
338
+ | Núcleo personalizado | Informa conflito em vez de sobrescrever silenciosamente |
339
+ | Nova versão do CLI | Não atualiza automaticamente os arquivos já copiados na aplicação |
340
+ | `update` com núcleo reconhecido e sem conflito | Atualiza os arquivos gerenciados e preserva os arquivos do projeto |
341
+ | Projeto vindo da 1.x | Exige revisão do núcleo e dos formatos das specs; não converte evidência antiga em aprovação atual |
342
+
343
+ `PROJECT.md`, `POLICIES.md`, `QUALITY.md`, `config.yaml` e `DECISIONS.md` existentes são preservados.
344
+ Specs, skills próprias, documentos em `docs/` e histórico não são apagados pelo instalador.
345
+ Se o setup foi concluído e removido, a manutenção normal não o recria.
346
+
347
+ Antes de atualizar, preserve o estado atual em commit ou backup. Instale a versão desejada do CLI
348
+ — pelo npm ou, para testes, pelo código-fonte — e, dentro da aplicação, execute:
349
+
350
+ ```sh
351
+ sdd --version
352
+ sdd update --dry-run
353
+ # Revise a prévia e resolva os conflitos antes de aplicar.
354
+ sdd update
355
+ sdd doctor
356
+ ```
357
+
358
+ Se usa adaptador, atualize seus pontos de entrada com `sdd harness claude-code` ou `sdd harness opencode`.
359
+ Configurações nativas não são sobrescritas; permissões e hooks antigos exigem revisão própria.
360
+
361
+ <details>
362
+ <summary>Migrar da 1.x ou tratar um conflito</summary>
363
+
364
+ O updater reconhece os templates originais não modificados da base 1.3.3.
365
+ Versões personalizadas, inclusive adaptações de terceiros, podem exigir revisão manual.
366
+
367
+ Para uma spec antiga que será retomada ou normalizada:
368
+
369
+ ```sh
370
+ sdd migrate 001-minha-mudanca --dry-run
371
+ sdd migrate 001-minha-mudanca
372
+ ```
373
+
374
+ Use o ID real. A migração preserva os corpos antigos e cria estruturas para revisão.
375
+ Revise requisitos, aceitação, tarefas e referências antes de normalizar.
376
+ Não é necessário converter todo o histórico encerrado só para adotar o fluxo nas próximas mudanças.
377
+
378
+ Arquivos centrais personalizados geram conflito e interrompem a aplicação das mudanças planejadas do núcleo.
379
+ Transfira particularidades para políticas, contratos ou skills antes de decidir substituir o núcleo.
380
+ `--replace-managed` é uma opção explícita após revisão; conteúdos substituídos recebem backups.
381
+
382
+ Essa proteção descreve o instalador 2.x. Não use um instalador 1.x para fazer downgrade nem
383
+ presuma compatibilidade automática com versões futuras.
384
+ Veja o [guia de migração](docs/migration.md).
385
+
386
+ </details>
387
+
388
+ ## Documentação
389
+
390
+ | Quero… | Consultar |
391
+ |---|---|
392
+ | Usar o fluxo do início ao fim | [Guia de uso](docs/usage.pt-BR.md) |
393
+ | Entender setup, perguntas e documentos | [Setup e referências](docs/setup-documents.pt-BR.md) |
394
+ | Conhecer o método e a evolução | [Metodologia](docs/methodology.pt-BR.md) |
395
+ | Configurar qualidade e testes externos | [Quality gates](docs/quality-gates.pt-BR.md) |
396
+ | Entender os formatos | [Formatos e exemplos](docs/formats.md) |
397
+ | Testar localmente | [Laboratórios de teste](docs/local-testing.pt-BR.md) |
398
+ | Atualizar projetos antigos | [Migração](docs/migration.md) |
399
+ | Preparar plugins e skills | [Distribuição](docs/distribution.md) |
400
+ | Revisar evidências e limites da entrega | [Validação registrada](docs/validation.md) |
401
+ | Publicar uma versão | [GitHub e npm](docs/releases.pt-BR.md) |
402
+ | Contribuir | [Contribuição](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) |
403
+
404
+ ## Limites importantes
405
+
406
+ O CLI valida relações declaradas e registra execuções. Uma suíte verde não prova que as assertions cobrem todo o negócio. Aprovações são declarações registradas, não autenticação de identidade.
407
+
408
+ Comandos usam as permissões da conta atual; o CLI não é sandbox. Revise configurações, use os controles nativos do harness e escolha ambientes seguros.
409
+
410
+ A seleção de contexto reduz leitura desnecessária; não garante menor custo ou melhor código em qualquer tarefa. A compatibilidade interativa dos adaptadores deve ser verificada nas versões de ferramentas utilizadas.
411
+
412
+ ## Licença
413
+
414
+ [MIT](LICENSE).