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.
@@ -1,195 +1,200 @@
1
- # Testes locais antes de publicar
2
-
3
- Este roteiro testa a versão 2.0.0 baixada, sem depender da versão pública no npm.
4
- Exemplos: PowerShell no Windows. Requer Git e Node.js 22+; Node 24 pode ser usado para validar.
5
- Mantenha os laboratórios fora da pasta do framework. Use cópia/branch para aplicações reais.
6
-
7
- ## 1. Validar o pacote
8
-
9
- Extraia o ZIP e abra a pasta que contém package.json:
10
-
11
- ~~~powershell
12
- node --version
13
- npm --version
14
- npm ci
15
- npm test
16
- npm run check
17
- npm audit
18
- npm publish --dry-run --tag next
19
- ~~~
20
-
21
- O último comando não publica. Ele exercita prepublishOnly, que executa testes e checks.
22
- O teste de empacotamento instala o tarball em um consumidor temporário e executa o CLI instalado.
23
- Ele usa cache temporário vazio e tarball local do parser já instalado, evitando depender de metadados prévios do npm.
24
- Não é necessário npm login para testar o código. O aviso de falta de login no dry-run é esperado.
25
- Investigue falhas; erro de rede no audit não significa resultado de segurança aprovado.
26
- npm run test:coverage fornece cobertura, não uma nota de qualidade.
27
- Confira também o CI e os harnesses/versões que pretende anunciar.
28
-
29
- ## 2. Laboratório sem trocar o CLI global
30
-
31
- Na pasta do código-fonte:
32
-
33
- ~~~powershell
34
- $SddSource = (Get-Location).Path
35
- $SddCli = Join-Path $SddSource 'bin/cli.js'
36
- $SddLab = Join-Path ([System.IO.Path]::GetTempPath()) ('sdd-flow-laboratorio-' + [guid]::NewGuid().ToString('N'))
37
- New-Item -ItemType Directory -Path $SddLab | Out-Null
38
- Set-Location $SddLab
39
- git init
40
- node $SddCli --version
41
- node $SddCli init
42
- ~~~
43
-
44
- node $SddCli equivale a sdd, mas aponta exatamente para o código baixado.
45
- Para o agente executar sdd diretamente, instale o tarball conforme a seção 7,
46
- ou indique a ele o caminho absoluto deste CLI. Evite executar a versão pública 1.3.3 por engano.
47
-
48
- Configure agents/config.yaml preservando os demais campos:
49
-
50
- ~~~yaml
51
- documentation:
52
- language: pt-BR
53
- checks:
54
- - name: unit
55
- command: node --test
56
- timeout_ms: 10000
57
- ~~~
58
-
59
- Esse check é para o exemplo Node abaixo. Em outra tecnologia, use seus comandos reais.
60
- Exclua apenas saídas geradas quando necessário, sem excluir código ou testes da verificação.
61
-
62
- Para exercitar os documentos opcionais depois de definir o idioma:
63
-
64
- ~~~powershell
65
- node $SddCli docs --types prd,sd,ds,adr,roadmap --dry-run
66
- node $SddCli docs --types prd,sd,ds,adr,roadmap
67
- ~~~
68
-
69
- Confira os rascunhos em docs/, acrescente uma regra real ao PRD e repita o comando.
70
- A regra deve ser preservada. O template ADR deve continuar proposed até existir uma decisão real.
71
- Não é necessário preencher todos os modelos para continuar; selecione apenas os úteis ao laboratório.
72
- Veja setup-documents.pt-BR.md para distinguir referências de produto e artefatos de cada mudança.
73
-
74
- ## 3. Uma entrega real com o agente
75
-
76
- Ative o ponto de entrada do harness escolhido, quando aplicável:
77
-
78
- ~~~powershell
79
- node $SddCli harness claude-code
80
- # Alternativa: node $SddCli harness opencode
81
- ~~~
82
-
83
- Em outro harness, aponte para AGENTS.md e agents/prompts/.
84
- Adaptadores não instalam o aplicativo, concedem acesso ou modificam permissões.
85
-
86
- Pedido inicial sugerido:
87
-
88
- ~~~text
89
- Leia agents/SETUP.md e configure este projeto de laboratório.
90
- Vamos criar uma biblioteca Node.js pequena, sem dependências externas.
91
- Escreva os documentos do projeto em português brasileiro, em UTF-8, com acentos.
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.
94
- ~~~
95
-
96
- Depois peça:
97
-
98
- ~~~text
99
- Planeje uma spec standard para calcularFrete(valorCentavos).
100
- Aceite apenas inteiros não negativos. A partir de 5000 centavos, o frete é 0;
101
- abaixo disso, é 990. Entradas inválidas devem lançar erro.
102
- Inclua aceitação para 0, 4999, 5000, valores negativos, fracionários e não numéricos.
103
- Não implemente antes de apresentar o plano.
104
- ~~~
105
-
106
- Revise valores, limites e comportamento inválido. Autorize o plano real quando correto.
107
- Depois peça código/testes, checks reais, consolidação do contrato, verificação e encerramento.
108
- Não informe que houve autorização antes de concedê-la.
109
-
110
- Se registrar a aprovação pelo terminal, use o ID realmente criado:
111
-
112
- ~~~powershell
113
- node $SddCli check 001-calcular-frete
114
- node $SddCli approve 001-calcular-frete --by 'Moisés'
115
- node $SddCli context 001-calcular-frete --phase implement --task T01 --inspect
116
- ~~~
117
-
118
- IDs são exemplos; use os do seu laboratório. Não marque tarefas como done apenas para passar o verificador.
119
-
120
- ## 4. Cenários de aceitação do workflow
121
-
122
- | Cenário | Ação | Resultado esperado |
123
- |---|---|---|
124
- | Início do zero | Complete a entrega acima | Contrato, tarefas, testes reais, evidência e encerramento coerentes |
125
- | Reinstalação | Rode init após configurar PROJECT/POLICIES/config e concluir setup | Arquivos próprios preservados; SETUP removido não reaparece |
126
- | Conflito no núcleo | Em uma cópia, personalize RULES e rode update --dry-run | Conflito informado; conteúdo preservado até revisão explícita |
127
- | Projeto existente | Adote uma cópia de um aplicativo funcional | Baseline observada, sem refatoração ou specs fictícias do passado |
128
- | Regra alterada | Durante uma spec ativa aprovada, mude o limite para 7000 e revise o plano | Aprovação obsoleta, motivo registrado e tarefas afetadas reabertas |
129
- | Falha real | Quebre um teste numa spec ativa | Verificação falha; o resultado antigo não permite encerrar |
130
- | Validação parcial | Verifique antes de concluir as tarefas | Resultado parcial/pending honesto, sem encerramento |
131
- | Teste manual | Use uma spec light para observação com interação real | Evidência com executor, resultado e fingerprint pode passar após execução |
132
- | Retomada | Continue em outra sessão ou após compactação | Recupera objetivo, regra, tarefa e próxima ação pelos arquivos |
133
- | Contexto excessivo | Inspecione referências grandes; teste --max-bytes 1024 | Diagnóstico sem truncamento; contexto pertinente permite continuar |
134
- | Idioma | Use “autorização”, “revisão” e “não numérico” | UTF-8 preservado; texto em português; chaves/IDs estáveis |
135
- | Sem ambiente real | Classifique o teste externo, prepare handoff e gere o roteiro seguro | Pode fechar implementação como limited, mantendo acceptance_verified false e testes pendentes |
136
- | Indicador informativo | Configure uma análise advisory que falha, mantendo testes funcionais válidos | Aviso registrado, sem declarar falha funcional nem esconder o indicador |
137
- | Falha externa observada | Execute um teste externo autorizado que falha; depois omita essa execução | A falha nos mesmos inputs permanece; não vira deferred para permitir fechamento |
138
- | Efeito em consumidor | Altere uma função compartilhada mantendo seu teste isolado verde, mas quebrando um cenário do consumidor | O teste de regressão do consumidor detecta a falha e impede declarar o gate aprovado |
139
-
140
- Use outra spec para objetivo novo depois do encerramento.
141
- Para revisão na mesma spec, altere antes de encerrar ou reabra explicitamente com motivo.
142
- Uma falha provocada nessa matriz é resultado esperado do controle, não defeito do framework.
143
-
144
- ## 5. Conferir rastreabilidade
145
-
146
- - SPEC.md: requisitos e aceitação correspondem ao pedido e aos casos de borda.
147
- - TASK.md: tarefas por resultado; uma única fonte do estado.
148
- - history/approval-*.json: escopos aprovados preservados.
149
- - history/revision-*.json: motivo e impacto das alterações.
150
- - runs/ID/receipt.json e logs: comandos e resultados de execuções reais.
151
- - verification.json: resultado corrente vinculado aos inputs verificados.
152
- - current/: comportamento consolidado sem depender de todas as specs antigas.
153
- - archive/: preservação de artefatos e IDs.
154
-
155
- Evidência manual não pode transformar leitura de código em alegação de execução.
156
- Confira as assertions: um comando verde sozinho não prova cobertura de negócio.
157
-
158
- ## 6. Registrar a avaliação do agente
159
-
160
- Registre fora do snapshot verificado da aplicação, em sua issue/PR ou notas de avaliação:
161
-
162
- | Campo | O que anotar |
163
- |---|---|
164
- | Ambiente | OS, Node/CLI/harness, modelo e modo |
165
- | Caso | Laboratório e commit/base |
166
- | Correção | Requisitos omitidos, testes ausentes e resultados incorretos |
167
- | Contexto | Documentos selecionados, conteúdo irrelevante e facilidade de retomada |
168
- | Intervenção | Correções e confirmações desnecessárias pedidas ao desenvolvedor |
169
- | Rastreabilidade | Se outra pessoa entende escopo, revisão e execução pelos registros |
170
- | Eficiência | Tempo/custo, comparando tarefas e condições equivalentes |
171
-
172
- Repita um caso em outro harness se pretende anunciar compatibilidade.
173
- Sem esse ambiente, registre a lacuna. Corrija falhas de instalação antes de avaliar o método.
174
-
175
- ## 7. Testar o tarball
176
-
177
- Volte à pasta do framework:
178
-
179
- ~~~powershell
180
- Set-Location $SddSource
181
- npm pack
182
- ~~~
183
-
184
- Se quiser trocar a instalação global, em outro terminal instale o caminho exato do tarball:
185
-
186
- ~~~powershell
187
- npm install -g 'C:\caminho\sdd-flow-2.0.0.tgz'
188
- sdd --version
189
- ~~~
190
-
191
- Confira Get-Command sdd e repita init/context no laboratório.
192
- 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
-
195
- Após os testes, siga releases.pt-BR.md para enviar a branch, revisar o PR e publicar.
1
+ # Testes locais antes de publicar
2
+
3
+ Este roteiro testa o código-fonte da versão 2.x deste checkout, sem depender do pacote publicado no npm.
4
+ Exemplos: PowerShell no Windows. Requer Git e Node.js 22+; Node 24 pode ser usado para validar.
5
+ Mantenha os laboratórios fora da pasta do framework. Use cópia/branch para aplicações reais.
6
+
7
+ ## 1. Validar o pacote
8
+
9
+ Abra a pasta do checkout que contém package.json:
10
+
11
+ ~~~powershell
12
+ node --version
13
+ npm --version
14
+ npm ci
15
+ npm test
16
+ npm run check
17
+ npm audit
18
+ npm publish --dry-run --tag next
19
+ ~~~
20
+
21
+ O último comando não publica. Ele exercita prepublishOnly, que executa testes e checks.
22
+ O teste de empacotamento instala o tarball em um consumidor temporário e executa o CLI instalado.
23
+ Ele usa cache temporário vazio e tarball local do parser já instalado, evitando depender de metadados prévios do npm.
24
+ Não é necessário npm login para testar o código. O aviso de falta de login no dry-run é esperado.
25
+ Investigue falhas; erro de rede no audit não significa resultado de segurança aprovado.
26
+ npm run test:coverage fornece cobertura, não uma nota de qualidade.
27
+ Confira também o CI e os harnesses/versões que pretende anunciar.
28
+
29
+ ## 2. Laboratório sem trocar o CLI global
30
+
31
+ Na pasta do código-fonte:
32
+
33
+ ~~~powershell
34
+ $SddSource = (Get-Location).Path
35
+ $SddCli = Join-Path $SddSource 'bin/cli.js'
36
+ $SddLab = Join-Path ([System.IO.Path]::GetTempPath()) ('sdd-flow-laboratorio-' + [guid]::NewGuid().ToString('N'))
37
+ New-Item -ItemType Directory -Path $SddLab | Out-Null
38
+ Set-Location $SddLab
39
+ git init
40
+ node $SddCli --version
41
+ node $SddCli init
42
+ ~~~
43
+
44
+ node $SddCli equivale a sdd, mas aponta exatamente para o código baixado.
45
+ Para o agente executar sdd diretamente, instale o tarball conforme a seção 7,
46
+ ou indique a ele o caminho absoluto deste CLI. Evite executar a versão pública 1.3.3 por engano.
47
+
48
+ Configure agents/config.yaml preservando os demais campos:
49
+
50
+ ~~~yaml
51
+ documentation:
52
+ language: pt-BR
53
+ checks:
54
+ - name: unit
55
+ command: node --test
56
+ timeout_ms: 10000
57
+ ~~~
58
+
59
+ Esse check é para o exemplo Node abaixo. Em outra tecnologia, use seus comandos reais.
60
+ Exclua apenas saídas geradas quando necessário, sem excluir código ou testes da verificação.
61
+
62
+ Para exercitar os documentos opcionais depois de definir o idioma:
63
+
64
+ ~~~powershell
65
+ node $SddCli docs --types prd,sd,ds,adr,roadmap --dry-run
66
+ node $SddCli docs --types prd,sd,ds,adr,roadmap
67
+ ~~~
68
+
69
+ Confira os rascunhos em docs/, acrescente uma regra real ao PRD e repita o comando.
70
+ A regra deve ser preservada. O template ADR deve continuar proposed até existir uma decisão real.
71
+ Não é necessário preencher todos os modelos para continuar; selecione apenas os úteis ao laboratório.
72
+ Veja setup-documents.pt-BR.md para distinguir referências de produto e artefatos de cada mudança.
73
+
74
+ ## 3. Uma entrega real com o agente
75
+
76
+ Ative o ponto de entrada do harness escolhido, quando aplicável:
77
+
78
+ ~~~powershell
79
+ node $SddCli harness claude-code
80
+ # Alternativa: node $SddCli harness opencode
81
+ ~~~
82
+
83
+ Em outro harness, aponte para AGENTS.md e agents/prompts/.
84
+ Adaptadores não instalam o aplicativo, concedem acesso ou modificam permissões.
85
+
86
+ Pedido inicial sugerido:
87
+
88
+ ~~~text
89
+ Leia agents/SETUP.md e configure este projeto de laboratório.
90
+ Vamos criar uma biblioteca Node.js pequena, sem dependências externas.
91
+ Escreva os documentos do projeto em português brasileiro, em UTF-8, com acentos.
92
+ Registre apenas escolhas conhecidas. Nesta etapa configure o fluxo, sem implementar.
93
+ Use o CLI 2.x que indiquei; não execute a versão pública 1.3.3 por engano.
94
+ ~~~
95
+
96
+ Depois peça:
97
+
98
+ ~~~text
99
+ Planeje uma spec standard para calcularFrete(valorCentavos).
100
+ Aceite apenas inteiros não negativos. A partir de 5000 centavos, o frete é 0;
101
+ abaixo disso, é 990. Entradas inválidas devem lançar erro.
102
+ Inclua aceitação para 0, 4999, 5000, valores negativos, fracionários e não numéricos.
103
+ Não implemente antes de apresentar o plano.
104
+ ~~~
105
+
106
+ Revise valores, limites e comportamento inválido. Autorize o plano real quando correto.
107
+ Depois peça código/testes, checks reais, consolidação do contrato, verificação e encerramento.
108
+ Não informe que houve autorização antes de concedê-la.
109
+
110
+ Se registrar a aprovação pelo terminal, use o ID realmente criado:
111
+
112
+ ~~~powershell
113
+ node $SddCli check 001-calcular-frete
114
+ node $SddCli approve 001-calcular-frete --by 'Moisés'
115
+ node $SddCli context 001-calcular-frete --phase implement --task T01 --inspect
116
+ ~~~
117
+
118
+ IDs são exemplos; use os do seu laboratório. Não marque tarefas como done apenas para passar o verificador.
119
+
120
+ ## 4. Cenários de aceitação do workflow
121
+
122
+ | Cenário | Ação | Resultado esperado |
123
+ |---|---|---|
124
+ | Início do zero | Complete a entrega acima | Contrato, tarefas, testes reais, evidência e encerramento coerentes |
125
+ | Reinstalação | Rode init após configurar PROJECT/POLICIES/config e concluir setup | Arquivos próprios preservados; SETUP removido não reaparece |
126
+ | Conflito no núcleo | Em uma cópia, personalize RULES e rode update --dry-run | Conflito informado; conteúdo preservado até revisão explícita |
127
+ | Projeto existente | Adote uma cópia de um aplicativo funcional | Baseline observada, sem refatoração ou specs fictícias do passado |
128
+ | Regra alterada | Durante uma spec ativa aprovada, mude o limite para 7000 e revise o plano | Aprovação obsoleta, motivo registrado e tarefas afetadas reabertas |
129
+ | Falha real | Quebre um teste numa spec ativa | Verificação falha; o resultado antigo não permite encerrar |
130
+ | Validação parcial | Verifique antes de concluir as tarefas | Resultado parcial/pending honesto, sem encerramento |
131
+ | Teste manual | Use uma spec light para observação com interação real | Evidência com executor, resultado e fingerprint pode passar após execução |
132
+ | Retomada | Continue em outra sessão ou após compactação | Recupera objetivo, regra, tarefa e próxima ação pelos arquivos |
133
+ | Contexto excessivo | Inspecione referências grandes; teste --max-bytes 1024 | Diagnóstico sem truncamento; contexto pertinente permite continuar |
134
+ | Idioma | Use “autorização”, “revisão” e “não numérico” | UTF-8 preservado; texto em português; chaves/IDs estáveis |
135
+ | Sem ambiente real | Classifique o teste externo, prepare handoff e gere o roteiro seguro | Pode fechar implementação como limited, mantendo acceptance_verified false e testes pendentes |
136
+ | Indicador informativo | Configure uma análise advisory que falha, mantendo testes funcionais válidos | Aviso registrado, sem declarar falha funcional nem esconder o indicador |
137
+ | Falha externa observada | Execute um teste externo autorizado que falha; depois omita essa execução | A falha nos mesmos inputs permanece; não vira deferred para permitir fechamento |
138
+ | Efeito em consumidor | Altere uma função compartilhada mantendo seu teste isolado verde, mas quebrando um cenário do consumidor | O teste de regressão do consumidor detecta a falha e impede declarar o gate aprovado |
139
+ | Reorganização | Renomeie/renumere uma spec aprovada, mantendo seu conteúdo | ID e escopo preservados; contexto resolve o caminho atual |
140
+ | Descarte | Remova uma spec, restaure-a e examine --all | Área ativa limpa, código intacto e conteúdo recuperável |
141
+ | Exclusão manual | Exclua uma pasta de laboratório com consumidores | Reconcile distingue encerramento retido, histórico e pré-requisito desconhecido |
142
+ | Metadados defeituosos | Invalide o manifesto de uma spec de laboratório | Diagnóstico local; spec saudável sem relação continua operável |
143
+
144
+ Use outra spec para objetivo novo depois do encerramento.
145
+ Para revisão na mesma spec, altere antes de encerrar ou reabra explicitamente com motivo.
146
+ Uma falha provocada nessa matriz é resultado esperado do controle, não defeito do framework.
147
+
148
+ ## 5. Conferir rastreabilidade
149
+
150
+ - SPEC.md: requisitos e aceitação correspondem ao pedido e aos casos de borda.
151
+ - TASK.md: tarefas por resultado; uma única fonte do estado.
152
+ - history/approval-*.json: escopos aprovados preservados.
153
+ - history/revision-*.json: motivo e impacto das alterações.
154
+ - runs/ID/receipt.json e logs: comandos e resultados de execuções reais.
155
+ - verification.json: resultado corrente vinculado aos inputs verificados.
156
+ - current/: comportamento consolidado sem depender de todas as specs antigas.
157
+ - archive/: preservação de artefatos e IDs.
158
+
159
+ Evidência manual não pode transformar leitura de código em alegação de execução.
160
+ Confira as assertions: um comando verde sozinho não prova cobertura de negócio.
161
+
162
+ ## 6. Registrar a avaliação do agente
163
+
164
+ Registre fora do snapshot verificado da aplicação, em sua issue/PR ou notas de avaliação:
165
+
166
+ | Campo | O que anotar |
167
+ |---|---|
168
+ | Ambiente | OS, Node/CLI/harness, modelo e modo |
169
+ | Caso | Laboratório e commit/base |
170
+ | Correção | Requisitos omitidos, testes ausentes e resultados incorretos |
171
+ | Contexto | Documentos selecionados, conteúdo irrelevante e facilidade de retomada |
172
+ | Intervenção | Correções e confirmações desnecessárias pedidas ao desenvolvedor |
173
+ | Rastreabilidade | Se outra pessoa entende escopo, revisão e execução pelos registros |
174
+ | Eficiência | Tempo/custo, comparando tarefas e condições equivalentes |
175
+
176
+ Repita um caso em outro harness se pretende anunciar compatibilidade.
177
+ Sem esse ambiente, registre a lacuna. Corrija falhas de instalação antes de avaliar o método.
178
+
179
+ ## 7. Testar o tarball
180
+
181
+ Volte à pasta do framework:
182
+
183
+ ~~~powershell
184
+ Set-Location $SddSource
185
+ npm pack
186
+ ~~~
187
+
188
+ Se quiser trocar a instalação global, em outro terminal instale o caminho exato do tarball:
189
+
190
+ ~~~powershell
191
+ npm pack
192
+ npm install -g '.\sdd-flow-<versão>.tgz'
193
+ sdd --version
194
+ ~~~
195
+
196
+ Confira Get-Command sdd e repita init/context no laboratório.
197
+ Para restaurar uma versão global anterior, instale explicitamente aquela versão.
198
+ Para testar o pacote já publicado, use sdd-flow@next (ou sdd-flow, quando a 2.x for latest).
199
+
200
+ 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
@@ -1,75 +1,82 @@
1
- # Migrating from 1.x
2
-
3
- 2.x changes the artifact format and requires Node.js 22+. Work in a versioned branch and review the diff.
4
-
5
- ## Preview and install the new core
6
-
7
- ~~~sh
8
- sdd update --dry-run
9
- sdd update
10
- ~~~
11
-
12
- The updater recognizes unchanged templates from the 1.3.3 baseline.
13
- It preserves project-owned PROJECT.md, POLICIES.md, config.yaml and the historical DECISIONS.md.
14
- The root entry point is a managed block; existing custom content outside that block is preserved.
15
- Custom or unowned core files produce a conflict and no planned template writes are applied.
16
- Review them before using sdd update --replace-managed. Replaced contents are backed up under agents/.sdd/backups/.
17
-
18
- Do not use replacement as an automatic resolution for project-specific requirements.
19
- Move durable rules to the project map, current contracts or ADRs, then review the new core.
20
-
21
- ## Migrate each legacy change
22
-
23
- ~~~sh
24
- sdd migrate 001-feature --dry-run
25
- sdd migrate 001-feature
26
- ~~~
27
-
28
- Migration adds change.yaml and preserves the original Markdown bodies.
29
- It extracts recognizable task IDs/statuses without inventing requirement links or verify evidence.
30
- Original files are backed up. The new scope remains draft and unapproved.
31
- Legacy context remains readable before migration with an explicit warning.
32
-
33
- Review SPEC.md requirements/acceptance and TASK.md covers/verify/dependencies.
34
- Consolidate current behavior from the old specs into current capability documents.
35
- Remove legacy: true only after normalization. Resolve sdd check findings and record actual authorization.
36
- Old PROGRESS.md, TEST.md, decisions and validation reports remain historical; v2 does not treat them
37
- as canonical state or current execution evidence.
38
-
39
- ## Adapters and old settings
40
-
41
- ~~~sh
42
- sdd harness claude-code
43
- sdd harness opencode
44
- ~~~
45
-
46
- 2.x installs native commands and a workflow skill, plus a managed CLAUDE.md entry for compatible clients.
47
- No permission settings are changed. Existing 1.x active hooks/settings are not silently deleted.
48
- Review old .claude/settings.json, opencode.json(c) and agents/harness references manually.
49
- Remove obsolete blocks only after confirming which parts belong to the old workflow.
50
-
51
- Existing adapter files with local/unowned edits are preserved and reported.
52
- Removal deletes only files whose current content matches the recorded ownership hash.
53
- Update installed wrappers by rerunning the corresponding harness command after a core upgrade.
54
-
55
- ## Backups and recovery
56
-
57
- Backups retain project-relative names under the reported backup directory.
58
- Compare and restore only the desired files. The CLI never runs Git reset or rewrites repository history.
59
- Do not delete the registry when archiving changes; it reserves IDs even if directories later move.
60
- If a crashed process leaves agents/.sdd/lock, confirm no SDD mutation is active before removing it.
61
-
62
- ## Behavioral changes
63
-
64
- - Step-by-step execution is optional; batch is the default within authorized scope.
65
- - Research is optional except in rigorous mode.
66
- - Task state lives in YAML metadata, with no duplicate PROGRESS table.
67
- - Approval applies to scope, not to six independently mutable files.
68
- - Mandatory project constraints live in POLICIES.md; skills carry conditional procedures.
69
- - Approved-scope snapshots, revisions and each run receipt remain available outside default context.
70
- - Tests may be automated, manual or inspection-based.
71
- - Partial verification is supported and cannot close a change.
72
- - Closing requires fresh full evidence and explicit consolidation.
73
- - Full limited verification may close implementation with a current environment handoff, retaining pending tests explicitly.
74
- - Existing checks remain required/local. Classify external checks deliberately; they no longer run without --run-external.
75
- - QUALITY.md is project-owned. New quality policy fields can invalidate old active approvals; review/reapprove their actual scope.
1
+ # Migrating from 1.x
2
+
3
+ 2.x changes the artifact format and requires Node.js 22+. Work in a versioned branch and review the diff.
4
+
5
+ ## Preview and install the new core
6
+
7
+ ~~~sh
8
+ sdd update --dry-run
9
+ sdd update
10
+ ~~~
11
+
12
+ The updater recognizes unchanged templates from the 1.3.3 baseline.
13
+ It preserves project-owned PROJECT.md, POLICIES.md, config.yaml and the historical DECISIONS.md.
14
+ The root entry point is a managed block; existing custom content outside that block is preserved.
15
+ Custom or unowned core files produce a conflict and no planned template writes are applied.
16
+ Review them before using sdd update --replace-managed. Replaced contents are backed up under agents/.sdd/backups/.
17
+
18
+ Do not use replacement as an automatic resolution for project-specific requirements.
19
+ Move durable rules to the project map, current contracts or ADRs, then review the new core.
20
+
21
+ ## Migrate each legacy change
22
+
23
+ ~~~sh
24
+ sdd migrate 001-feature --dry-run
25
+ sdd migrate 001-feature
26
+ ~~~
27
+
28
+ Migration adds change.yaml and preserves the original Markdown bodies.
29
+ It extracts recognizable task IDs/statuses without inventing requirement links or verify evidence.
30
+ Original files are backed up. The new scope remains draft and unapproved.
31
+ Legacy context remains readable before migration with an explicit warning.
32
+
33
+ Review SPEC.md requirements/acceptance and TASK.md covers/verify/dependencies.
34
+ Consolidate current behavior from the old specs into current capability documents.
35
+ Remove legacy: true only after normalization. Resolve sdd check findings and record actual authorization.
36
+ Old PROGRESS.md, TEST.md, decisions and validation reports remain historical; v2 does not treat them
37
+ as canonical state or current execution evidence.
38
+
39
+ ## Adapters and old settings
40
+
41
+ ~~~sh
42
+ sdd harness claude-code
43
+ sdd harness opencode
44
+ ~~~
45
+
46
+ 2.x installs native commands and a workflow skill, plus a managed CLAUDE.md entry for compatible clients.
47
+ No permission settings are changed. Existing 1.x active hooks/settings are not silently deleted.
48
+ Review old .claude/settings.json, opencode.json(c) and agents/harness references manually.
49
+ Remove obsolete blocks only after confirming which parts belong to the old workflow.
50
+
51
+ Existing adapter files with local/unowned edits are preserved and reported.
52
+ Removal deletes only files whose current content matches the recorded ownership hash.
53
+ Update installed wrappers by rerunning the corresponding harness command after a core upgrade.
54
+
55
+ ## Backups and recovery
56
+
57
+ The current 2.x core discovers manifest IDs independently of directory names. Existing IDs need no conversion.
58
+ After updating, run sdd reconcile --dry-run and sdd reconcile while historical specs are still present to inventory observed closures.
59
+ Use rename/archive/restore/remove to organize specs; related and historical source references are optional additions.
60
+ Status defaults to active specs; --all includes archives, recoverable removals and retained records.
61
+ See spec-management.pt-BR.md. Missing old content without a recorded closure remains unknown rather than automatically passed.
62
+
63
+ Backups retain project-relative names under the reported backup directory.
64
+ Compare and restore only the desired files. The CLI never runs Git reset or rewrites repository history.
65
+ Do not delete the registry when archiving changes; it reserves IDs even if directories later move.
66
+ If a crashed process leaves agents/.sdd/lock, confirm no SDD mutation is active before removing it.
67
+
68
+ ## Behavioral changes
69
+
70
+ - New projects default to step; explicit user authorization for several/all tasks permits a bounded batch.
71
+ - Existing configured autonomy is preserved. Update does not reset a project's batch preference to step.
72
+ - Research is optional except in rigorous mode.
73
+ - Task state lives in YAML metadata, with no duplicate PROGRESS table.
74
+ - Approval applies to scope, not to six independently mutable files.
75
+ - Mandatory project constraints live in POLICIES.md; skills carry conditional procedures.
76
+ - Approved-scope snapshots, revisions and each run receipt remain available outside default context.
77
+ - Tests may be automated, manual or inspection-based.
78
+ - Partial verification is supported and cannot close a change.
79
+ - Closing requires fresh full evidence and explicit consolidation.
80
+ - Full limited verification may close implementation with a current environment handoff, retaining pending tests explicitly.
81
+ - Existing checks remain required/local. Classify external checks deliberately; they no longer run without --run-external.
82
+ - QUALITY.md is project-owned. New quality policy fields can invalidate old active approvals; review/reapprove their actual scope.