sdd-flow 2.0.1 → 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,105 +1,108 @@
1
- # Publicação de uma nova versão
2
-
3
- Guia do mantenedor para publicar o pacote npm `sdd-flow` a partir deste repositório.
4
- Cada nome/versão publicado no npm é permanente: nunca reutilize um número, incremente-o.
5
- Publicar no npm não atualiza o GitHub, e enviar ao GitHub não publica no npm.
6
-
7
- ## 1. Preparar
8
-
9
- ~~~sh
10
- git switch main
11
- git pull --ff-only
12
- npm ci
13
- npm test
14
- npm run check
15
- npm audit
16
- ~~~
17
-
18
- 1. Atualize `CHANGELOG.md` com a nova versão e a data.
19
- 2. Altere a versão sem criar tag: `npm version <major|minor|patch> --no-git-tag-version`
20
- (atualiza `package.json` e `package-lock.json` juntos).
21
- 3. Faça o commit e envie para `main`. Não inclua credenciais, `node_modules` ou tarballs.
22
- 4. Aguarde o CI (Linux e Windows, Node 22 e 24) ficar verde.
23
-
24
- Escolha da versão: correção ou ajuste de documentação/default dentro da mesma linha é patch;
25
- funcionalidade compatível é minor; mudança incompatível de formato ou de runtime é major.
26
-
27
- ## 2. Publicar primeiro em `next`
28
-
29
- `next` mantém `latest` na versão anterior, permitindo testar o pacote real do registro.
30
- Escolha uma rota; não execute ambas para a mesma versão.
31
-
32
- ### Rota A — terminal autenticado
33
-
34
- Requer acesso de mantenedor e Node.js 22+.
35
-
36
- ~~~sh
37
- npm run release:check -- --version <versão> --tag next --check-registry
38
- npm publish --dry-run --tag next
39
- npm login
40
- npm publish --tag next
41
- ~~~
42
-
43
- - O hook `prepublishOnly` repete testes e checks.
44
- - O npm pode abrir o navegador para confirmar passkey/2FA, ou pedir `--otp=<código>`.
45
- Não compartilhe senha, OTP ou token em mensagens ou arquivos do projeto.
46
-
47
- ### Rota B — GitHub Actions com Trusted Publishing (OIDC)
48
-
49
- Arquivo: `.github/workflows/publish.yml`. Acionamento manual, somente em `main` no repositório
50
- `moisesuailab/sdd-flow`; depende de testes em Node 22/24 em Linux/Windows. O código vem do SHA do disparo,
51
- a versão é conferida e o mesmo tarball passa por dry-run e publicação, com provenance. Não há token permanente.
52
-
53
- Configure uma vez, nas definições do pacote no npm:
54
-
55
- | Campo | Valor |
56
- |---|---|
57
- | Provedor | GitHub Actions |
58
- | Organização/usuário | moisesuailab |
59
- | Repositório | sdd-flow |
60
- | Nome do workflow | publish.yml |
61
- | Environment | npm |
62
-
63
- E crie o environment `npm` no GitHub (com revisores obrigatórios, se quiser uma aprovação adicional).
64
- Depois: Actions → “Publish npm package” → Run workflow em `main`, com `version` igual ao `package.json`
65
- e `dist_tag` = `next`. Documentação atual: https://docs.npmjs.com/trusted-publishers/
66
-
67
- ## 3. Verificar
68
-
69
- ~~~sh
70
- npm view sdd-flow dist-tags --json
71
- npx sdd-flow@next --help
72
- ~~~
73
-
74
- Em uma pasta vazia, execute `npx sdd-flow@next init` e `npx sdd-flow@next doctor`.
75
- O `doctor` indica pendência até que `agents/PROJECT.md` seja preenchido; isso é esperado.
76
-
77
- ## 4. Tornar estável
78
-
79
- Depois de revisar migração, evidências e limitações, um mantenedor autenticado promove a versão existente:
80
-
81
- ~~~sh
82
- npm dist-tag add sdd-flow@<versão> latest
83
- npm view sdd-flow dist-tags --json
84
- ~~~
85
-
86
- Isso move a tag; não republica o número. Para voltar atrás, aponte `latest` para a versão anterior
87
- (`npm dist-tag add sdd-flow@<anterior> latest`). A automação de publish não promove versões.
88
-
89
- ## 5. Registrar no GitHub
90
-
91
- Crie a tag no **commit exato que foi publicado** (`npm view sdd-flow@<versão> gitHead`):
92
-
93
- ~~~sh
94
- git tag -a v<versão> <gitHead> -m "sdd-flow <versão>"
95
- git push origin v<versão>
96
- ~~~
97
-
98
- Crie o GitHub Release a partir da tag, usando a seção da versão no `CHANGELOG.md`.
99
- Marque como pré-lançamento enquanto a versão estiver só em `next`.
100
-
101
- ## Atualizar os projetos consumidores
102
-
103
- Instale o CLI desejado e atualize os templates de cada projeto com `sdd update --dry-run`.
104
- Atualizar a instalação global não modifica os arquivos já copiados nos aplicativos.
105
- Leia `usage.pt-BR.md` e `migration.md` antes de migrar o formato 1.x.
1
+ # Publicação de uma nova versão
2
+
3
+ Guia do mantenedor para publicar o pacote npm `sdd-flow` a partir deste repositório.
4
+ Cada nome/versão publicado no npm é permanente: nunca reutilize um número, incremente-o.
5
+ Publicar no npm não atualiza o GitHub, e enviar ao GitHub não publica no npm.
6
+
7
+ ## 1. Preparar
8
+
9
+ ~~~sh
10
+ git switch main
11
+ git pull --ff-only
12
+ npm ci
13
+ npm test
14
+ npm run check
15
+ npm audit
16
+ ~~~
17
+
18
+ 1. Atualize `CHANGELOG.md` com a nova versão e a data.
19
+ 2. Altere a versão sem criar tag: `npm version <major|minor|patch> --no-git-tag-version`
20
+ (atualiza `package.json` e `package-lock.json` juntos).
21
+ 3. Faça o commit e envie para `main`. Não inclua credenciais, `node_modules` ou tarballs.
22
+ 4. Aguarde o CI (Linux e Windows, Node 22 e 24) ficar verde.
23
+
24
+ Escolha da versão: correção ou ajuste de documentação/default dentro da mesma linha é patch;
25
+ funcionalidade compatível é minor; mudança incompatível de formato ou de runtime é major.
26
+
27
+ ## 2. Publicar primeiro em `next`
28
+
29
+ `next` mantém `latest` na versão anterior, permitindo testar o pacote real do registro.
30
+ Escolha uma rota; não execute ambas para a mesma versão.
31
+
32
+ ### Rota A — terminal autenticado
33
+
34
+ Requer acesso de mantenedor e Node.js 22+.
35
+
36
+ ~~~sh
37
+ npm run release:check -- --version <versão> --tag next --check-registry
38
+ npm publish --dry-run --tag next
39
+ npm login
40
+ npm publish --tag next
41
+ ~~~
42
+
43
+ - O hook `prepublishOnly` repete testes e checks.
44
+ - O npm pode abrir o navegador para confirmar passkey/2FA, ou pedir `--otp=<código>`.
45
+ Não compartilhe senha, OTP ou token em mensagens ou arquivos do projeto.
46
+
47
+ ### Rota B — GitHub Actions com Trusted Publishing (OIDC)
48
+
49
+ Arquivo: `.github/workflows/publish.yml`. Acionamento manual, somente em `main` no repositório
50
+ `moisesuailab/sdd-flow`; depende de testes em Node 22/24 em Linux/Windows. O código vem do SHA do disparo,
51
+ a versão é conferida e o mesmo tarball passa por dry-run e publicação, com provenance. Não há token permanente.
52
+
53
+ Configure uma vez, nas definições do pacote no npm:
54
+
55
+ | Campo | Valor |
56
+ |---|---|
57
+ | Provedor | GitHub Actions |
58
+ | Organização/usuário | moisesuailab |
59
+ | Repositório | sdd-flow |
60
+ | Nome do workflow | publish.yml |
61
+ | Environment | npm |
62
+
63
+ E crie o environment `npm` no GitHub (com revisores obrigatórios, se quiser uma aprovação adicional).
64
+ Depois: Actions → “Publish npm package” → Run workflow em `main`, com `version` igual ao `package.json`
65
+ e `dist_tag` = `next`. Documentação atual: https://docs.npmjs.com/trusted-publishers/
66
+
67
+ ## 3. Verificar
68
+
69
+ ~~~sh
70
+ npm view sdd-flow dist-tags --json
71
+ npx sdd-flow@next --help
72
+ ~~~
73
+
74
+ Em uma pasta vazia, execute `npx sdd-flow@next init` e `npx sdd-flow@next doctor`.
75
+ O `doctor` indica pendência até que `agents/PROJECT.md` seja preenchido; isso é esperado.
76
+
77
+ ## 4. Tornar estável
78
+
79
+ Depois de revisar migração, evidências e limitações, um mantenedor autenticado promove a versão existente:
80
+
81
+ ~~~sh
82
+ npm dist-tag add sdd-flow@<versão> latest
83
+ npm view sdd-flow dist-tags --json
84
+ ~~~
85
+
86
+ Isso move a tag; não republica o número. Para voltar atrás, aponte `latest` para a versão anterior
87
+ (`npm dist-tag add sdd-flow@<anterior> latest`). A automação de publish não promove versões.
88
+
89
+ ## 5. Registrar no GitHub
90
+
91
+ Crie a tag no **commit exato que foi publicado** (`npm view sdd-flow@<versão> gitHead`):
92
+
93
+ ~~~sh
94
+ git tag -a v<versão> <gitHead> -m "sdd-flow <versão>"
95
+ git push origin v<versão>
96
+ ~~~
97
+
98
+ Crie o GitHub Release a partir da tag, usando a seção da versão no `CHANGELOG.md`.
99
+ Marque como pré-lançamento enquanto a versão estiver só em `next`.
100
+
101
+ ## Atualizar os projetos consumidores
102
+
103
+ Instale o CLI desejado e atualize os templates de cada projeto com `sdd update --dry-run`.
104
+ Após revisar e aplicar, execute sdd reconcile --dry-run e sdd reconcile enquanto os históricos ainda existem,
105
+ para registrar localizações e encerramentos observáveis. Atualize os pontos de entrada do harness quando utilizados.
106
+ Consulte spec-management.pt-BR.md para renomeação, arquivamento, descarte e recuperação.
107
+ Atualizar a instalação global não modifica os arquivos já copiados nos aplicativos.
108
+ Leia `usage.pt-BR.md` e `migration.md` antes de migrar o formato 1.x.
@@ -0,0 +1,169 @@
1
+ # Organização, arquivamento e descarte de specs
2
+
3
+ O ID técnico de uma spec permanece estável. Nome da pasta, número visual e localização podem mudar.
4
+ O agente pode executar estas operações a partir de um pedido simples do usuário, respeitando sua autorização.
5
+ Não é necessário editar manifestos e históricos manualmente para reorganizar pastas.
6
+
7
+ ## Renomear e renumerar
8
+
9
+ ~~~sh
10
+ sdd rename 015-exportacao --name exportar-relatorios --number 3 --by "Moisés" --reason "Reorganizar entregas" --dry-run
11
+ sdd rename 015-exportacao --name exportar-relatorios --number 3 --by "Moisés" --reason "Reorganizar entregas"
12
+ ~~~
13
+
14
+ A pasta passa a ser agents/specs/003-exportar-relatorios. O campo id continua 015-exportacao.
15
+ Não existe UUID obrigatório nem conversão em massa dos IDs existentes.
16
+
17
+ - --name muda o nome da pasta; --number altera seu prefixo visual. Ambos podem ser usados separadamente.
18
+ - O CLI aceita o ID estável e o nome atual da pasta; aliases registrados preservam nomes anteriores.
19
+ - Se um atalho numérico ficar ambíguo depois de reordenar, use o ID completo.
20
+ - Identidades e aliases de outras specs não podem ser reutilizados como um nome completo.
21
+ - O título normativo e o conteúdo da SPEC não são reescritos por rename. Alterações de comportamento seguem revisão de escopo.
22
+ - Mover ou renomear sem mudar os inputs normativos preserva a aprovação e a validade dos recibos.
23
+ - Evidências, snapshots e logs anteriores não são reescritos para aparentar outro passado.
24
+
25
+ O resolvedor acompanha caminhos estruturados para arquivos dentro de specs movidas, incluindo sources/context e evidências.
26
+ Isso não é uma substituição global: links Markdown arbitrários, texto livre e referências em ferramentas externas não são editados automaticamente.
27
+ Revise links ativos quando necessário; mantenha a proveniência dos registros históricos.
28
+
29
+ Renomear uma pasta manualmente também é reconhecido quando change.yaml permanece com o mesmo ID.
30
+ Use reconcile para atualizar o inventário. Não altere o campo id por uma preferência de organização.
31
+
32
+ ## Arquivar e restaurar
33
+
34
+ ~~~sh
35
+ sdd archive 015-exportacao --by "Moisés" --reason "Retirar da área ativa"
36
+ sdd restore 015-exportacao --by "Moisés" --reason "Retomar o planejamento"
37
+ ~~~
38
+
39
+ Archive move a pasta para agents/archive/ e preserva seu nome e estado.
40
+ Pode arquivar uma spec draft, implementing, cancelled, verified ou closed. Arquivar não significa concluir ou aprovar.
41
+ Uma spec arquivada precisa ser restaurada antes de continuar implementação/verificação.
42
+ Close --archive continua disponível para encerrar e arquivar em uma operação.
43
+
44
+ Restore de uma spec arquivada a devolve à área ativa. Se ela estiver closed/cancelled, use reopen quando for retomar o ciclo.
45
+ Restaurar localização não remove as condições de encerramento nem transforma um recibo antigo em execução nova.
46
+
47
+ ## Remover com recuperação ou excluir definitivamente
48
+
49
+ ~~~sh
50
+ sdd remove 015-exportacao --by "Moisés" --reason "Spec obsoleta" --dry-run
51
+ sdd remove 015-exportacao --by "Moisés" --reason "Spec obsoleta"
52
+ ~~~
53
+
54
+ Por padrão, o conteúdo vai para agents/.sdd/trash/. Deixa de participar da área ativa e do contexto normal.
55
+ O comando informa os vínculos de specs ativas afetados, sem alterar o código da aplicação.
56
+
57
+ ~~~sh
58
+ sdd restore 015-exportacao --by "Moisés" --reason "Recuperar documento"
59
+ ~~~
60
+
61
+ A restauração da lixeira usa a localização anterior, inclusive archive quando foi de lá que a spec foi removida.
62
+ Se a pasta de destino estiver ocupada, --name permite escolher outro nome.
63
+ Nomes que colidam com outra identidade/alias são recusados.
64
+
65
+ Para descarte permanente, use explicitamente:
66
+
67
+ ~~~sh
68
+ sdd remove 015-exportacao --permanent --by "Moisés" --reason "Descartar o histórico detalhado"
69
+ ~~~
70
+
71
+ O conteúdo removido não pode ser restaurado pelo CLI após exclusão definitiva. Git/backup só ajudam se houver uma cópia.
72
+ A exclusão exige autorização real; --by registra o responsável declarado, não autentica sua identidade.
73
+
74
+ O CLI conserva um registro compacto de identidade, último estado observado, aliases, localização e eventual encerramento.
75
+ Esse registro não inclui o texto completo da spec, tarefas, logs ou todas as observações.
76
+ Ele cresce com as identidades registradas e não substitui uma política de backup; o limite de leitura de metadados do CLI continua aplicável.
77
+ Preservar uma identidade não exige conservar sua pasta inteira. Não reutilize o ID técnico para outro trabalho.
78
+
79
+ Em falha de persistência, operações de movimentação tentam restaurar a pasta e o inventário anterior.
80
+ Uma exclusão permanente interrompida é reportada como tal; conteúdo restante é identificado para inspeção.
81
+ Locks não impedem edição externa nem tornam o sistema imune a interrupções do processo ou do disco.
82
+
83
+ ## Tipos de referência
84
+
85
+ | Tipo | Como representar | Se o conteúdo desaparecer |
86
+ |---|---|---|
87
+ | Origem histórica | related: [ID] | Aviso; não bloqueia por ausência do histórico |
88
+ | Fonte histórica opcional | Objeto sources/context com historical: true | Aviso, sem leitura de conteúdo inexistente |
89
+ | Fonte/contrato obrigatório | capabilities, decisions ou sources/context comum | Diagnóstico de referência obrigatória; restaurar ou revisar antes de executar |
90
+ | Pré-requisito de execução | depends_on: [ID estável] | Usar encerramento histórico conhecido, ou investigar o pré-requisito ainda não resolvido |
91
+
92
+ Exemplo:
93
+
94
+ ~~~yaml
95
+ related:
96
+ - 002-planejamento-antigo
97
+ sources:
98
+ - path: docs/produto/prd.md
99
+ section: Exportação
100
+ context:
101
+ - path: agents/archive/002-planejamento-antigo/RESEARCH.md
102
+ historical: true
103
+ capabilities:
104
+ - agents/current/autorizacao.md
105
+ depends_on: []
106
+ ~~~
107
+
108
+ Related fornece proveniência e não carrega outra spec inteira.
109
+ Historical é opcional e só deve ser usado quando a referência realmente não constitui uma obrigação da mudança.
110
+ Marcar uma regra obrigatória como histórica para contornar um erro é incorreto.
111
+ Alterar sources/context ou depends_on de um plano aprovado exige a revisão correspondente.
112
+
113
+ Prefira contratos vigentes para conhecimento reutilizável. Guarde-os fora de pastas que pretende descartar.
114
+ Use depends_on apenas para um pré-requisito real, sem ligar todas as specs umas às outras.
115
+
116
+ ## Dependência fechada cujo conteúdo foi descartado
117
+
118
+ Se a spec foi encerrada e o resultado foi registrado, o consumidor pode usar o resumo histórico de encerramento.
119
+ Não é necessário manter toda a cadeia de specs anteriores para cada mudança nova.
120
+
121
+ - O resumo não é evidência fresca de funcionamento do sistema atual.
122
+ - O consumidor continua obrigado a verificar sua própria aceitação.
123
+ - Uma conclusão limited mantém o aviso de validação externa pendente.
124
+ - Contratos históricos ausentes/superseded geram aviso no contexto; selecione a referência vigente pertinente.
125
+ - Nenhum arquivo de evidência excluído é apresentado como recuperado.
126
+
127
+ Em projetos anteriores a este recurso, execute reconcile enquanto os arquivos ainda existem para registrar os estados observáveis.
128
+ Sem conteúdo nem registro prévio, o CLI não pode adivinhar um encerramento perdido.
129
+
130
+ ## Exclusão manual ou dependência inacabada
131
+
132
+ ~~~sh
133
+ sdd reconcile --dry-run
134
+ sdd reconcile
135
+ sdd doctor
136
+ ~~~
137
+
138
+ A prévia mostra localizações observadas, conteúdo ausente e referências afetadas.
139
+ Reconcile atualiza apenas o inventário a partir do que está disponível. Não modifica requisitos, remove dependências ou fabrica testes/aprovações.
140
+ Mudanças de nomes manuais são descobertas pelo manifesto. Duplicatas de identidade são diagnosticadas, sem escolher uma cópia silenciosamente.
141
+
142
+ Uma dependência ausente sem encerramento conhecido:
143
+ 1. Gera aviso no planejamento, permitindo revisar a spec existente.
144
+ 2. Continua impedindo implementar/validar/fechar como se o pré-requisito estivesse resolvido.
145
+ 3. Não obriga cancelar ou refazer a spec.
146
+
147
+ O agente deve verificar código, contratos e testes atuais. Depois pode recuperar a fonte ou revisar o vínculo:
148
+ - Se o pré-requisito já existe, referencie o contrato vigente e revise a necessidade de depends_on.
149
+ - Se ainda falta comportamento, planeje o trabalho necessário.
150
+ - Se não há informação suficiente, esclareça somente a lacuna.
151
+ - Preserve o ID e o trabalho válido; não invente o histórico perdido.
152
+
153
+ Ao mudar o plano aprovado, execute revise, registre a autorização real e produza a verificação atual.
154
+ Um manifesto defeituoso é reportado localmente; não deve impedir operar uma spec saudável sem relação com ele.
155
+
156
+ ## Acompanhamento e atualização
157
+
158
+ ~~~sh
159
+ sdd status
160
+ sdd status --all
161
+ sdd status 015-exportacao
162
+ ~~~
163
+
164
+ Status sem ID mostra a área ativa. --all inclui arquivo, lixeira e registros retidos de conteúdo ausente/descartado.
165
+ Um registro retido é identificado como histórico, sem representar a existência da pasta.
166
+
167
+ Os formatos schema 2 existentes continuam válidos. Related/historical são opcionais.
168
+ Atualize o CLI, revise update --dry-run, atualize os pontos de entrada do harness e execute reconcile.
169
+ As preferências do projeto, como autonomia e idioma, continuam preservadas.