sdd-flow 2.0.0 → 2.0.1

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,387 @@
1
+ <div align="center">
2
+
1
3
  # sdd-flow
2
4
 
3
- Framework de processo para desenvolvimento assistido por IA, com contexto selecionado por tarefa,
4
- rastreabilidade e verificação vinculada à versão testada.
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.
5
45
 
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:
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.
9
49
 
10
- ~~~sh
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.x**, uma evolução com quebra de compatibilidade em relação à 1.x (veja a [migração](docs/migration.md)). 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
11
77
  npm ci
12
78
  npm link
13
- cd /caminho/do/projeto
14
- sdd init --harness claude-code
15
- ~~~
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.
16
182
 
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.
183
+ ```sh
184
+ sdd context 001-minha-mudanca --phase implement --task T01 --inspect
185
+ ```
19
186
 
20
- ## Princípios
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.
21
188
 
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.
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.
32
190
 
33
- ## Fluxo
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.
34
192
 
35
- ~~~sh
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
+ ## Rigor proporcional à mudança
222
+
223
+ | Modo | Quando usar |
224
+ |---|---|
225
+ | `light` | Mudança pequena; tarefas e pesquisa podem ser dispensadas |
226
+ | `standard` | Funcionalidade delimitada, com tarefas verificáveis |
227
+ | `rigorous` | Mudança sensível ou com maior incerteza, com pesquisa e aprovação explícitas |
228
+
229
+ O padrão de instalações novas é **step**: implementar e verificar uma tarefa e parar para revisão.
230
+ Autorize tarefas específicas ou todas as tarefas para continuar em lote sem confirmações repetidas.
231
+ Aprovar o plano, por si só, não muda essa autonomia. **Batch** também pode ser a preferência permanente;
232
+ atualizações preservam a escolha existente. Cada tarefa continua sendo verificada, respeitando dependências.
233
+
234
+ ## Verificação honesta, inclusive sem ambiente externo
235
+
236
+ O CLI executa checks configurados e registra comandos, resultados e inputs. Aprovações ficam vinculadas ao plano; verificações ficam vinculadas à versão examinada.
237
+
238
+ | Resultado | O que significa |
239
+ |---|---|
240
+ | `passed` | Verificação integral aprovada para os inputs atuais |
241
+ | `limited` | Implementação concluída com limitações externas e pendências explícitas |
242
+ | `partial` | Ainda não há condições para o encerramento final |
243
+ | `failed` | Há falha obrigatória observada ou alteração de inputs durante a execução |
244
+
245
+ **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`.
246
+
247
+ `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.
248
+
249
+ 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.
250
+
251
+ Leia o [guia de qualidade e falta de ambiente](docs/quality-gates.pt-BR.md).
252
+
253
+ ## Portabilidade e escopo
254
+
255
+ | O sdd-flow organiza | O harness fornece |
256
+ |---|---|
257
+ | Método, specs, contexto e rastreabilidade | Modelos, ferramentas e permissões |
258
+ | Referências e evidências | MCPs e acesso a serviços |
259
+ | Pontos de entrada e conhecimento exportável | Compactação e eventual delegação |
260
+
261
+ 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.**
262
+
263
+ 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).
264
+
265
+ ## Para agentes de IA
266
+
267
+ 1. Comece pelo `AGENTS.md` e pelo mapa do projeto.
268
+ 2. Use `SETUP.md` na adoção inicial; depois siga o procedimento da fase.
269
+ 3. Consulte as fontes pertinentes, sem carregar toda a pasta `docs/`.
270
+ 4. Preserve IDs, regras vigentes, arquitetura observada e trabalho existente.
271
+ 5. Considere consumidores e regressões antes de alterar comportamento compartilhado.
272
+ 6. Registre autorização real, resultados observados e limitações.
273
+ 7. Mantenha o estado canônico e consolide o conhecimento antes de encerrar.
274
+
275
+ 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.
276
+
277
+ <details>
278
+ <summary>Comandos essenciais para uma mudança</summary>
279
+
280
+ Exemplo com ID ilustrativo; o agente precisa preencher o plano entre os comandos:
281
+
282
+ ```sh
36
283
  sdd new minha-mudanca --mode standard
37
284
  sdd context 001-minha-mudanca --phase plan
38
- # Preencha SPEC.md e TASK.md nos formatos documentados.
285
+ # Definir requisitos, aceitação, tarefas e referências.
39
286
  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"
287
+
288
+ # Registrar somente a autorização realmente concedida:
289
+ sdd approve 001-minha-mudanca --by "Responsável"
290
+
42
291
  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.
292
+ # Implementar, verificar e atualizar as tarefas.
293
+ # Consolidar os contratos vigentes antes da verificação final.
46
294
  sdd verify 001-minha-mudanca
47
- sdd close 001-minha-mudanca --by "Moisés" --note "Sem alteração de contrato duradouro" --archive
48
- ~~~
295
+ sdd close 001-minha-mudanca --by "Responsável" --archive
296
+ ```
297
+
298
+ 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.
299
+
300
+ `sdd check` valida estrutura; `sdd verify` executa os checks configurados. Não são a mesma operação.
49
301
 
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.
302
+ </details>
54
303
 
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.
304
+ ## Reinstalar ou atualizar sem começar de novo
59
305
 
60
- ## Front matter e contexto
306
+ O instalador 2.x distingue arquivos do projeto e arquivos gerenciados do método.
61
307
 
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.
308
+ | Situação | Comportamento esperado |
309
+ |---|---|
310
+ | `init` repetido na mesma versão | Preserva configuração e trabalho existentes; arquivos ausentes podem ser repostos |
311
+ | Núcleo personalizado | Informa conflito em vez de sobrescrever silenciosamente |
312
+ | Nova versão do CLI | Não atualiza automaticamente os arquivos já copiados na aplicação |
313
+ | `update` com núcleo reconhecido e sem conflito | Atualiza os arquivos gerenciados e preserva os arquivos do projeto |
314
+ | 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 |
65
315
 
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.
316
+ `PROJECT.md`, `POLICIES.md`, `QUALITY.md`, `config.yaml` e `DECISIONS.md` existentes são preservados.
317
+ Specs, skills próprias, documentos em `docs/` e histórico não são apagados pelo instalador.
318
+ Se o setup foi concluído e removido, a manutenção normal não o recria.
70
319
 
71
- ## Distribuição e manutenção
320
+ Antes de atualizar, preserve o estado atual em commit ou backup. Instale a versão desejada do CLI
321
+ — pelo npm ou, para testes, pelo código-fonte — e, dentro da aplicação, execute:
72
322
 
73
- ~~~sh
323
+ ```sh
324
+ sdd --version
74
325
  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.
326
+ # Revise a prévia e resolva os conflitos antes de aplicar.
327
+ sdd update
328
+ sdd doctor
329
+ ```
330
+
331
+ Se usa adaptador, atualize seus pontos de entrada com `sdd harness claude-code` ou `sdd harness opencode`.
332
+ Configurações nativas não são sobrescritas; permissões e hooks antigos exigem revisão própria.
333
+
334
+ <details>
335
+ <summary>Migrar da 1.x ou tratar um conflito</summary>
336
+
337
+ O updater reconhece os templates originais não modificados da base 1.3.3.
338
+ Versões personalizadas, inclusive adaptações de terceiros, podem exigir revisão manual.
339
+
340
+ Para uma spec antiga que será retomada ou normalizada:
341
+
342
+ ```sh
343
+ sdd migrate 001-minha-mudanca --dry-run
344
+ sdd migrate 001-minha-mudanca
345
+ ```
346
+
347
+ Use o ID real. A migração preserva os corpos antigos e cria estruturas para revisão.
348
+ Revise requisitos, aceitação, tarefas e referências antes de normalizar.
349
+ Não é necessário converter todo o histórico encerrado só para adotar o fluxo nas próximas mudanças.
350
+
351
+ Arquivos centrais personalizados geram conflito e interrompem a aplicação das mudanças planejadas do núcleo.
352
+ Transfira particularidades para políticas, contratos ou skills antes de decidir substituir o núcleo.
353
+ `--replace-managed` é uma opção explícita após revisão; conteúdos substituídos recebem backups.
354
+
355
+ Essa proteção descreve o instalador 2.x. Não use um instalador 1.x para fazer downgrade nem
356
+ presuma compatibilidade automática com versões futuras.
357
+ Veja o [guia de migração](docs/migration.md).
358
+
359
+ </details>
360
+
361
+ ## Documentação
362
+
363
+ | Quero… | Consultar |
364
+ |---|---|
365
+ | Usar o fluxo do início ao fim | [Guia de uso](docs/usage.pt-BR.md) |
366
+ | Entender setup, perguntas e documentos | [Setup e referências](docs/setup-documents.pt-BR.md) |
367
+ | Conhecer o método e a evolução | [Metodologia](docs/methodology.pt-BR.md) |
368
+ | Configurar qualidade e testes externos | [Quality gates](docs/quality-gates.pt-BR.md) |
369
+ | Entender os formatos | [Formatos e exemplos](docs/formats.md) |
370
+ | Testar localmente | [Laboratórios de teste](docs/local-testing.pt-BR.md) |
371
+ | Atualizar projetos antigos | [Migração](docs/migration.md) |
372
+ | Preparar plugins e skills | [Distribuição](docs/distribution.md) |
373
+ | Revisar evidências e limites da entrega | [Validação registrada](docs/validation.md) |
374
+ | Publicar uma versão | [GitHub e npm](docs/releases.pt-BR.md) |
375
+ | Contribuir | [Contribuição](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) |
376
+
377
+ ## Limites importantes
378
+
379
+ 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.
380
+
381
+ 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.
382
+
383
+ 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.
384
+
385
+ ## Licença
386
+
387
+ [MIT](LICENSE).
package/docs/formats.md CHANGED
@@ -27,7 +27,7 @@ ADR templates are proposed rather than actual active decisions. No fixed referen
27
27
  ~~~yaml
28
28
  schema_version: 2
29
29
  mode: standard
30
- autonomy: batch
30
+ autonomy: step
31
31
  approval: required
32
32
  context:
33
33
  max_bytes: 48000
@@ -46,6 +46,9 @@ External commands are skipped unless --run-external is explicitly requested and
46
46
  Optional quality.tdd is optional, preferred (default) or required; it guides the method rather than attesting test chronology.
47
47
  QUALITY.md is project-owned, preserved by maintenance and read for planning/review.
48
48
  Configure generated paths explicitly; do not exclude source or dependency manifests.
49
+ New installations use step as the standing default. Explicit user authorization for named tasks or
50
+ all tasks permits a bounded batch without changing configuration; plan approval alone does not.
51
+ Existing configured autonomy is preserved on update. Task checks and dependencies still apply in batches.
49
52
  A timeout kills the spawned process group on POSIX. On Windows the CLI invokes taskkill.exe
50
53
  for its spawned process tree, with shell-process termination as fallback. Use a controlled environment
51
54
  when stronger process isolation is required.
@@ -1,12 +1,12 @@
1
1
  # Testes locais antes de publicar
2
2
 
3
- Este roteiro testa a versão 2.0.0 baixada, sem depender da versão pública no npm.
3
+ Este roteiro testa o código-fonte da versão 2.x deste checkout, sem depender do pacote publicado no npm.
4
4
  Exemplos: PowerShell no Windows. Requer Git e Node.js 22+; Node 24 pode ser usado para validar.
5
5
  Mantenha os laboratórios fora da pasta do framework. Use cópia/branch para aplicações reais.
6
6
 
7
7
  ## 1. Validar o pacote
8
8
 
9
- Extraia o ZIP e abra a pasta que contém package.json:
9
+ Abra a pasta do checkout que contém package.json:
10
10
 
11
11
  ~~~powershell
12
12
  node --version
@@ -90,7 +90,7 @@ Leia agents/SETUP.md e configure este projeto de laboratório.
90
90
  Vamos criar uma biblioteca Node.js pequena, sem dependências externas.
91
91
  Escreva os documentos do projeto em português brasileiro, em UTF-8, com acentos.
92
92
  Registre apenas escolhas conhecidas. Nesta etapa configure o fluxo, sem implementar.
93
- Use o CLI 2.0.0 que indiquei; não execute a versão pública 1.3.3 por engano.
93
+ Use o CLI 2.x que indiquei; não execute a versão pública 1.3.3 por engano.
94
94
  ~~~
95
95
 
96
96
  Depois peça:
@@ -184,12 +184,13 @@ npm pack
184
184
  Se quiser trocar a instalação global, em outro terminal instale o caminho exato do tarball:
185
185
 
186
186
  ~~~powershell
187
- npm install -g 'C:\caminho\sdd-flow-2.0.0.tgz'
187
+ npm pack
188
+ npm install -g '.\sdd-flow-<versão>.tgz'
188
189
  sdd --version
189
190
  ~~~
190
191
 
191
192
  Confira Get-Command sdd e repita init/context no laboratório.
192
193
  Para restaurar uma versão global anterior, instale explicitamente aquela versão.
193
- Não instale sdd-flow@next antes de existir a publicação desejada.
194
+ Para testar o pacote já publicado, use sdd-flow@next (ou sdd-flow, quando a 2.x for latest).
194
195
 
195
- Após os testes, siga releases.pt-BR.md para enviar a branch, revisar o PR e publicar.
196
+ Após os testes, siga releases.pt-BR.md para publicar uma nova versão.
@@ -19,6 +19,12 @@ podem ocorrer durante a implementação. O encerramento depende de evidência fi
19
19
  Fases não obrigam abrir novas conversas. Uma sessão, subagentes nativos ou uma sessão nova são opções
20
20
  do ambiente. Depois de compactação ou transferência, recupere o estado pelos arquivos canônicos.
21
21
 
22
+ Instalações novas usam step: uma tarefa por vez, seguida de revisão. A autorização do usuário para
23
+ várias tarefas específicas ou todas as tarefas permite continuar nesse lote sem confirmações repetidas
24
+ nem alteração obrigatória da configuração. Aprovação do plano, por si só, não muda a autonomia.
25
+ Batch pode ser a preferência permanente; atualizações preservam a escolha de projetos existentes.
26
+ Cada tarefa continua sendo verificada e as dependências respeitadas, inclusive durante um lote.
27
+
22
28
  Evidência de execução local e validação externa são distintas. Falta de ambiente não precisa bloquear
23
29
  uma implementação concluída: um handoff atual registra o que ficou pendente e como testar com segurança.
24
30
  O encerramento limited nunca representa teste externo aprovado; falhas observadas continuam registradas.
package/docs/migration.md CHANGED
@@ -61,7 +61,8 @@ If a crashed process leaves agents/.sdd/lock, confirm no SDD mutation is active
61
61
 
62
62
  ## Behavioral changes
63
63
 
64
- - Step-by-step execution is optional; batch is the default within authorized scope.
64
+ - New projects default to step; explicit user authorization for several/all tasks permits a bounded batch.
65
+ - Existing configured autonomy is preserved. Update does not reset a project's batch preference to step.
65
66
  - Research is optional except in rigorous mode.
66
67
  - Task state lives in YAML metadata, with no duplicate PROGRESS table.
67
68
  - Approval applies to scope, not to six independently mutable files.