sdd-flow 1.3.2 → 2.0.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/CHANGELOG.md +33 -0
- package/CONTRIBUTING.md +25 -0
- package/LICENSE +21 -21
- package/README.md +113 -168
- package/README.pt-BR.md +100 -0
- package/bin/cli.js +162 -424
- package/docs/architecture.md +91 -0
- package/docs/distribution.md +64 -0
- package/docs/formats.md +212 -0
- package/docs/local-testing.pt-BR.md +195 -0
- package/docs/methodology.pt-BR.md +133 -0
- package/docs/migration.md +75 -0
- package/docs/quality-gates.pt-BR.md +160 -0
- package/docs/quality.md +56 -0
- package/docs/releases.pt-BR.md +186 -0
- package/docs/setup-documents.pt-BR.md +120 -0
- package/docs/usage.pt-BR.md +305 -0
- package/docs/validation.md +95 -0
- package/lib/adapters.js +115 -0
- package/lib/check.js +221 -0
- package/lib/context.js +117 -0
- package/lib/documents.js +71 -0
- package/lib/handoff.js +81 -0
- package/lib/history.js +16 -0
- package/lib/install.js +181 -0
- package/lib/io.js +119 -0
- package/lib/legacy-hashes.json +31 -0
- package/lib/markdown.js +71 -0
- package/lib/project.js +200 -0
- package/lib/quality.js +24 -0
- package/lib/revisions.js +79 -0
- package/lib/verification.js +267 -0
- package/package.json +55 -32
- package/templates/AGENTS.md +12 -49
- package/templates/QUICKSTART.md +16 -70
- package/templates/agents/AGENTS.md +54 -92
- package/templates/agents/DECISIONS.md +5 -21
- package/templates/agents/POLICIES.md +14 -0
- package/templates/agents/PROJECT.md +35 -145
- package/templates/agents/QUALITY.md +19 -0
- package/templates/agents/RULES.md +22 -132
- package/templates/agents/SETUP.md +38 -224
- package/templates/agents/config.yaml +13 -0
- package/templates/agents/current/_template.md +19 -0
- package/templates/agents/decisions/_template.md +22 -0
- package/templates/agents/prompts/conventional-commit.md +11 -51
- package/templates/agents/prompts/intake.md +23 -0
- package/templates/agents/prompts/pr-template.md +12 -21
- package/templates/agents/prompts/quality.md +57 -0
- package/templates/agents/prompts/rpi-close.md +23 -0
- package/templates/agents/prompts/rpi-implement.md +31 -68
- package/templates/agents/prompts/rpi-plan.md +87 -117
- package/templates/agents/prompts/rpi-research.md +21 -67
- package/templates/agents/prompts/rpi-validate.md +40 -103
- package/templates/agents/prompts/skill-call.md +11 -29
- package/templates/agents/prompts/task-create.md +13 -42
- package/templates/agents/skills/_template/SKILL.md +11 -37
- package/templates/agents/harness/claude-code/.hooks/guard-delete.sh +0 -22
- package/templates/agents/harness/claude-code/.hooks/guard-deps.sh +0 -25
- package/templates/agents/harness/claude-code/.hooks/guard-git.sh +0 -24
- package/templates/agents/harness/claude-code/commands/sdd-implement.md +0 -3
- package/templates/agents/harness/claude-code/commands/sdd-plan.md +0 -3
- package/templates/agents/harness/claude-code/commands/sdd-research.md +0 -3
- package/templates/agents/harness/claude-code/commands/sdd-validate.md +0 -3
- package/templates/agents/harness/claude-code/settings.json +0 -34
- package/templates/agents/harness/opencode/commands/sdd-implement.md +0 -3
- package/templates/agents/harness/opencode/commands/sdd-plan.md +0 -3
- package/templates/agents/harness/opencode/commands/sdd-research.md +0 -3
- package/templates/agents/harness/opencode/commands/sdd-validate.md +0 -3
- package/templates/agents/harness/opencode/opencode.json +0 -18
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# Metodologia e limites do sdd-flow
|
|
2
|
+
|
|
3
|
+
O objetivo do sdd-flow é organizar desenvolvimento assistido por IA, entregar contexto pertinente
|
|
4
|
+
e manter acompanhamento e rastreabilidade, independentemente da tecnologia da aplicação.
|
|
5
|
+
O CLI operacionaliza partes objetivas do método; o harness fornece ferramentas e execução.
|
|
6
|
+
Não é objetivo criar um orquestrador, um cliente MCP ou uma plataforma de agentes.
|
|
7
|
+
|
|
8
|
+
## O que continua essencial
|
|
9
|
+
|
|
10
|
+
1. Compreender o problema e investigar incertezas relevantes.
|
|
11
|
+
2. Definir escopo observável, requisitos e aceitação.
|
|
12
|
+
3. Planejar e executar resultados coesos, preservando o trabalho existente.
|
|
13
|
+
4. Verificar o comportamento e registrar o que foi realmente observado.
|
|
14
|
+
5. Consolidar conhecimento vigente e preservar o histórico da mudança.
|
|
15
|
+
|
|
16
|
+
Research, Plan, Implement, Validate e Close são responsabilidades lógicas. A pesquisa pode ser breve
|
|
17
|
+
quando já existe informação suficiente; rigorous exige um registro explícito. Verificações parciais
|
|
18
|
+
podem ocorrer durante a implementação. O encerramento depende de evidência final atual e consolidação.
|
|
19
|
+
Fases não obrigam abrir novas conversas. Uma sessão, subagentes nativos ou uma sessão nova são opções
|
|
20
|
+
do ambiente. Depois de compactação ou transferência, recupere o estado pelos arquivos canônicos.
|
|
21
|
+
|
|
22
|
+
Evidência de execução local e validação externa são distintas. Falta de ambiente não precisa bloquear
|
|
23
|
+
uma implementação concluída: um handoff atual registra o que ficou pendente e como testar com segurança.
|
|
24
|
+
O encerramento limited nunca representa teste externo aprovado; falhas observadas continuam registradas.
|
|
25
|
+
Veja quality-gates.pt-BR.md para a política required/advisory, exemplos BDD e procedimento TDD.
|
|
26
|
+
|
|
27
|
+
## Comparação com as versões analisadas
|
|
28
|
+
|
|
29
|
+
Base original: sdd-flow 1.3.3, commit d84c62d51d9c566b0f3e8a6279418220e0fc6e8f.
|
|
30
|
+
O anexo do colaborador foi analisado como conjunto de arquivos; não continha histórico Git que
|
|
31
|
+
permitisse demonstrar ancestralidade. A comparação se refere aos materiais examinados em 20/11/2026.
|
|
32
|
+
|
|
33
|
+
| Aspecto | Original 1.3.3 | Ajuste do colaborador | Atual 2.x |
|
|
34
|
+
|---|---|---|---|
|
|
35
|
+
| Método | RPIV e tarefas muito fragmentadas | Mais controles sobre o mesmo método | Método preservado, modos light/standard/rigorous, execução step/batch e consolidação |
|
|
36
|
+
| Contexto | Leitura global e histórico acumulado | Acrescentou conteúdo obrigatório e repetição | Seleção por tarefa/fase e fontes explícitas; histórico fora da leitura padrão |
|
|
37
|
+
| Tarefas | Estado repetido em TASK/PROGRESS | Conservou a necessidade de sincronização | TASK canônico; STATE curto e opcional |
|
|
38
|
+
| Rastreabilidade | Predominantemente orientações em Markdown | IDs e covers mais explícitos | IDs e relações validados, registros por execução e histórico de revisões |
|
|
39
|
+
| Skills | Extração por trechos fixos | Front matter com instruções de geração/leitura divergentes | Parser YAML, catálogo curto e corpo por pertinência |
|
|
40
|
+
| Aprovação | Orientação no processo | Aprovação de seis arquivos sem vincular todas ao conteúdo | Aprovação do escopo normativo com digest e snapshots |
|
|
41
|
+
| Mudança de regra | Procedimento manual de revisão do plano | Invalidação incompleta de alguns registros | Revisão, reabertura de trabalho afetado e rejeição de evidência obsoleta |
|
|
42
|
+
| Validação parcial | Permitida | Bloqueada com tarefas pendentes | Permitida, sem representar encerramento final |
|
|
43
|
+
| Teste manual | Previsto em instruções | Sem caminho claro até conclusão aprovada | Evidência manual real pode passar; falta de ambiente pode ser registrada como limited |
|
|
44
|
+
| Qualidade | Princípios no prompt | Atenção adicional às assertions e achados | Checks required/advisory, evidências, regressões, TDD/BDD e handoff seguro |
|
|
45
|
+
| Git | Proibição geral de writes | Não houve mecanismo novo de integração demonstrado no anexo | Autorização real e permissões nativas, sem bloqueio geral do método |
|
|
46
|
+
| Documentos | Opção fixa de PRD, roadmap e architecture | Sem evolução do instalador demonstrada no anexo | Mesma opção restaurada e presets adicionais SD/DS/ADR, preservando fontes existentes |
|
|
47
|
+
| Instalação | Cópia de templates com opção de sobrescrever | Sem instalador alternativo demonstrado no anexo | Preservação, conflitos, prévia, backups e migração conservadora |
|
|
48
|
+
|
|
49
|
+
O ganho demonstrável é estrutural e funcional: menos estados redundantes, seleção de contexto e
|
|
50
|
+
condições verificáveis. Isso não prova menor custo de tokens, melhor código ou superioridade sobre
|
|
51
|
+
todo framework. Tais afirmações exigem avaliações repetidas com tarefas, modelos e condições comparáveis.
|
|
52
|
+
|
|
53
|
+
O colaborador melhorou o desenho de rastreabilidade; esta evolução incorpora esses acertos e corrige
|
|
54
|
+
as inconsistências encontradas nos materiais. Não foram comparadas implementações reais produzidas
|
|
55
|
+
pelos três workflows, portanto superioridade de custo ou de qualidade do código gerado não está demonstrada.
|
|
56
|
+
|
|
57
|
+
O núcleo ficou mais verificável, mas também exige aprender formatos e comandos novos e usar Node 22+.
|
|
58
|
+
A seleção de contexto depende de referências bem mantidas; o CLI não infere automaticamente todos os
|
|
59
|
+
efeitos de uma mudança. A verificação é conservadora: alterações nos inputs podem exigir nova execução.
|
|
60
|
+
Identidade do revisor, semântica dos testes e segurança do ambiente não são atestadas pelo CLI.
|
|
61
|
+
Há hotspots de complexidade no próprio código, registrados em validation.md; os testes não eliminam
|
|
62
|
+
a necessidade de manutenção e avaliação prática nos harnesses.
|
|
63
|
+
|
|
64
|
+
## Como o fluxo funciona na prática
|
|
65
|
+
|
|
66
|
+
1. Instale a base e faça o setup guiado pelo agente, usando fontes e fatos disponíveis.
|
|
67
|
+
2. Crie uma mudança com objetivo delimitado; pesquise somente as incertezas relevantes.
|
|
68
|
+
3. Defina requisitos, exemplos de aceitação, tarefas e impacto nos consumidores.
|
|
69
|
+
4. Registre a autorização real e implemente dentro desse escopo, consultando contexto pertinente.
|
|
70
|
+
5. Execute checks disponíveis, revise assertions/regressões e registre limitações quando faltar ambiente.
|
|
71
|
+
6. Consolide o conhecimento vigente e encerre como verificado ou implementado com limitações explícitas.
|
|
72
|
+
|
|
73
|
+
Instalação não cria entendimento de produto sozinha. Veja setup-documents.pt-BR.md para perguntas,
|
|
74
|
+
PRD, ADR, system design, design system e modelos opcionais. O método não exige uma tríade fixa de documentos.
|
|
75
|
+
|
|
76
|
+
## O que permanece rastreável
|
|
77
|
+
|
|
78
|
+
| Pergunta | Registro |
|
|
79
|
+
|---|---|
|
|
80
|
+
| O que foi solicitado e qual aceitação deve ser atendida? | change.yaml e SPEC.md |
|
|
81
|
+
| Como será feito e em que estado está? | TASK.md |
|
|
82
|
+
| Qual escopo foi autorizado, quando e por quem? | approval e history/approval-*.json |
|
|
83
|
+
| O que mudou no plano aprovado e por quê? | history/revision-*.json |
|
|
84
|
+
| Quais comandos rodaram e que resultado produziram? | runs/ID/receipt.json e logs |
|
|
85
|
+
| Que observação manual foi realizada? | Evidência com cenário, executor, instante e fingerprint |
|
|
86
|
+
| Qual resultado pode ser usado agora? | verification.json, válido somente para os inputs atuais |
|
|
87
|
+
| Como o sistema funciona após a entrega? | current/ e decisões ativas |
|
|
88
|
+
| Como chegamos até aqui? | Histórico da mudança, arquivo e Git |
|
|
89
|
+
|
|
90
|
+
O framework rastreia artefatos, estados, decisões e execuções registradas. Não captura cada pensamento
|
|
91
|
+
do modelo nem todas as chamadas do harness. Sessões, traces e auditoria externa podem complementar
|
|
92
|
+
os registros. Aprovações são declarações registradas, não autenticação de identidade.
|
|
93
|
+
|
|
94
|
+
## Portabilidade
|
|
95
|
+
|
|
96
|
+
O núcleo funciona com arquivos e comandos. Adaptadores fornecem pontos de entrada, preservando
|
|
97
|
+
configurações existentes. Permissões, MCP, modelos, compactação e delegação pertencem ao harness.
|
|
98
|
+
Essas capacidades não alteram as condições de aceitação e de encerramento.
|
|
99
|
+
|
|
100
|
+
Ferramentas externas podem fornecer evidência; registre origem e instante quando relevantes.
|
|
101
|
+
O fingerprint local não atesta por conta própria um sistema remoto.
|
|
102
|
+
Não é necessário A2A ou multiagentes para seguir esta metodologia.
|
|
103
|
+
|
|
104
|
+
## Idioma e escrita
|
|
105
|
+
|
|
106
|
+
As instruções distribuídas do método permanecem em inglês como fonte comum.
|
|
107
|
+
O idioma dos documentos do aplicativo é configurável, independentemente do idioma desses templates.
|
|
108
|
+
|
|
109
|
+
~~~yaml
|
|
110
|
+
documentation:
|
|
111
|
+
language: pt-BR
|
|
112
|
+
~~~
|
|
113
|
+
|
|
114
|
+
Use português correto e UTF-8 nos artefatos narrativos: requisitos, aceitação, tarefas, pesquisa,
|
|
115
|
+
contratos, decisões e observações. Preserve termos originais quando a tradução prejudicar o significado.
|
|
116
|
+
Chaves técnicas, IDs, paths e APIs permanecem estáveis; a chave description pode ter valor em português.
|
|
117
|
+
Slugs podem ser ASCII sem eliminar acentos do título ou do conteúdo.
|
|
118
|
+
|
|
119
|
+
auto é o padrão genérico: o agente segue o idioma do usuário até o setup registrar a escolha da equipe.
|
|
120
|
+
Configurações antigas sem documentation continuam válidas. O CLI valida a tag e a inclui no contexto;
|
|
121
|
+
isso orienta o agente, não certifica linguisticamente cada frase.
|
|
122
|
+
Novas specs/tarefas têm textos iniciais em português quando a configuração usa pt ou pt-BR.
|
|
123
|
+
Outros idiomas podem ser usados pelo agente; os textos iniciais do CLI usam inglês como fallback.
|
|
124
|
+
Diagnósticos, chaves de máquina e relatórios determinísticos do CLI ainda podem permanecer em inglês;
|
|
125
|
+
esta versão não é uma localização completa da interface do CLI.
|
|
126
|
+
|
|
127
|
+
Não foi medido ganho de qualidade/custo por escrever as instruções em inglês. Não elimine
|
|
128
|
+
acentos como técnica de otimização. A clareza para autores e revisores de negócio é o critério principal.
|
|
129
|
+
Não traduza o histórico encerrado apenas para uniformizar aparência. A tradução de um contrato ativo
|
|
130
|
+
aprovado altera seu conteúdo e exige revisão; preserve o registro anterior.
|
|
131
|
+
|
|
132
|
+
Use local-testing.pt-BR.md para testar o CLI e executar cenários com um agente real.
|
|
133
|
+
Um pacote menor que omite uma regra é uma regressão, não uma otimização.
|
|
@@ -0,0 +1,75 @@
|
|
|
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.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Qualidade e validação sem acesso ao ambiente real
|
|
2
|
+
|
|
3
|
+
O objetivo é concluir trabalho útil com evidência honesta. Falta de produção ou homologação não exige
|
|
4
|
+
inventar um teste, arriscar dados reais ou manter uma implementação pronta bloqueada indefinidamente.
|
|
5
|
+
Falha observada, implementação incompleta e ausência de ambiente são situações diferentes.
|
|
6
|
+
|
|
7
|
+
## Política pequena por projeto
|
|
8
|
+
|
|
9
|
+
~~~yaml
|
|
10
|
+
quality:
|
|
11
|
+
tdd: preferred
|
|
12
|
+
checks:
|
|
13
|
+
- name: unit
|
|
14
|
+
command: npm test
|
|
15
|
+
timeout_ms: 60000
|
|
16
|
+
- name: complexity
|
|
17
|
+
command: npm run analyze:complexity
|
|
18
|
+
timeout_ms: 60000
|
|
19
|
+
level: advisory
|
|
20
|
+
- name: integration
|
|
21
|
+
command: npm run test:integration
|
|
22
|
+
timeout_ms: 60000
|
|
23
|
+
environment: external
|
|
24
|
+
~~~
|
|
25
|
+
|
|
26
|
+
Exemplo para um projeto com esses scripts reais; não os copie sem configurar as ferramentas.
|
|
27
|
+
Os padrões são level: required e environment: local. optional/preferred/required em quality.tdd
|
|
28
|
+
orientam o procedimento do agente; o CLI não certifica que ele realmente seguiu TDD.
|
|
29
|
+
|
|
30
|
+
- Required: falha observada impede declarar o gate aprovado.
|
|
31
|
+
- Advisory: resultado aparece no relatório, sem bloquear a aceitação funcional.
|
|
32
|
+
- External: o comando não roda por padrão; depende de ambiente/autorização disponíveis.
|
|
33
|
+
- --run-external permite solicitar execução externa, mas não concede autorização nem prova segurança.
|
|
34
|
+
|
|
35
|
+
Aceitação automatizada deve referenciar checks required. Um indicador advisory não comprova
|
|
36
|
+
o comportamento obrigatório. Limiar de complexidade, cobertura, dependências e carga pertence à
|
|
37
|
+
configuração da ferramenta usada. Não há percentual universal imposto pelo sdd-flow.
|
|
38
|
+
Não reclassifique uma falha de código como falta de acesso apenas para encerrar a mudança.
|
|
39
|
+
|
|
40
|
+
QUALITY.md registra critérios do projeto e links; é carregado em plan/validate/close.
|
|
41
|
+
POLICIES.md continua sendo a fonte de obrigações essenciais. O roteiro detalhado em
|
|
42
|
+
agents/prompts/quality.md é consultado quando necessário, sem entrar em toda tarefa.
|
|
43
|
+
Não é preciso instalar Sonar, Cucumber, uma plataforma de observabilidade ou um orquestrador.
|
|
44
|
+
|
|
45
|
+
## BDD e TDD sem duplicação de documentos
|
|
46
|
+
|
|
47
|
+
Registre exemplos concretos em acceptance.description da SPEC: estado inicial, ação e resultado.
|
|
48
|
+
Inclua fronteiras, rejeições e falhas pertinentes ao comportamento. Gherkin/Cucumber são opcionais.
|
|
49
|
+
|
|
50
|
+
Para mudanças de comportamento testáveis, prefira ciclos pequenos: teste falhando pelo motivo esperado,
|
|
51
|
+
implementação suficiente e refatoração. Para bugs, reproduza com regressão quando possível.
|
|
52
|
+
Guarde referências dos resultados RED/GREEN em task.evidence e logs, sem um diário sempre carregado.
|
|
53
|
+
sdd verify --scope partial pode registrar essas execuções, mas uma falha RED nunca é aprovação final.
|
|
54
|
+
Um comando verde não demonstra sozinho a qualidade das assertions, a cobertura semântica ou TDD.
|
|
55
|
+
|
|
56
|
+
## Quando o teste só pode ser feito pelo usuário
|
|
57
|
+
|
|
58
|
+
Classifique a dependência real. Para aceitação manual/inspeção:
|
|
59
|
+
|
|
60
|
+
~~~yaml
|
|
61
|
+
- id: AC02
|
|
62
|
+
covers: [REQ01]
|
|
63
|
+
description: No ambiente autorizado, um usuário sem permissão não consegue alterar o registro.
|
|
64
|
+
method: manual
|
|
65
|
+
environment: external
|
|
66
|
+
~~~
|
|
67
|
+
|
|
68
|
+
Para automação externa, marque o check com environment: external.
|
|
69
|
+
Execute os checks locais disponíveis. Não tente operar produção só para satisfazer a spec.
|
|
70
|
+
|
|
71
|
+
~~~sh
|
|
72
|
+
sdd handoff 001-minha-mudanca
|
|
73
|
+
~~~
|
|
74
|
+
|
|
75
|
+
O comando retorna um caminho novo HANDOFF-<id>.json dentro da spec. O agente preenche o documento.
|
|
76
|
+
Preserve schema_version, id e input_digest gerados; cada limitação tem alvo e responsável claros.
|
|
77
|
+
Exemplo de um item quando ainda não existe ambiente seguro:
|
|
78
|
+
|
|
79
|
+
~~~json
|
|
80
|
+
{
|
|
81
|
+
"kind": "criterion",
|
|
82
|
+
"id": "AC02",
|
|
83
|
+
"result": "deferred",
|
|
84
|
+
"reason": "O agente e o desenvolvedor não têm acesso a um ambiente adequado.",
|
|
85
|
+
"owner": "Responsável pelo projeto",
|
|
86
|
+
"environment": "unavailable",
|
|
87
|
+
"prerequisites": [],
|
|
88
|
+
"steps": [],
|
|
89
|
+
"expected": "A operação é negada e nenhum dado é alterado.",
|
|
90
|
+
"safety": "Não executar escritas, exclusões ou mudanças de permissão em produção como teste.",
|
|
91
|
+
"resume_when": "Existir uma cópia isolada com dados fictícios e acesso autorizado."
|
|
92
|
+
}
|
|
93
|
+
~~~
|
|
94
|
+
|
|
95
|
+
Quando houver teste seguro, use isolated, non-production ou production-read-only e forneça passos
|
|
96
|
+
curtos, pré-requisitos e resultado observável. Exemplo para uma cópia isolada:
|
|
97
|
+
|
|
98
|
+
1. Abra a versão indicada com os dados fictícios informados.
|
|
99
|
+
2. Entre com o perfil de teste sem a permissão necessária.
|
|
100
|
+
3. Tente a ação apenas nessa cópia isolada.
|
|
101
|
+
4. Confira a mensagem de recusa e que o registro fictício permaneceu igual.
|
|
102
|
+
5. Informe versão, ambiente, resultado observado e evidência sem expor credenciais/dados pessoais.
|
|
103
|
+
|
|
104
|
+
production-read-only só cabe quando a ação realmente não provoca efeitos; o nome do campo não
|
|
105
|
+
comprova isso. Não sugira testes de carga, envio de mensagens, exclusões, alterações de permissões ou
|
|
106
|
+
movimentação de dados reais em produção. Quando não houver um teste seguro, steps pode ficar vazio
|
|
107
|
+
em unavailable: registre a condição futura e siga com a implementação disponível.
|
|
108
|
+
|
|
109
|
+
O usuário não precisa preencher metadados técnicos para fazer o teste. O agente prepara USER_TESTS.md;
|
|
110
|
+
o usuário segue apenas o que é possível e seguro e relata o observado. O agente registra depois
|
|
111
|
+
executor, instante, versão e resultado reais, sem declarar que ele próprio executou o teste.
|
|
112
|
+
|
|
113
|
+
## Verificar e encerrar com limitações
|
|
114
|
+
|
|
115
|
+
~~~sh
|
|
116
|
+
sdd verify 001-minha-mudanca --handoff agents/specs/001-minha-mudanca/HANDOFF-ID.json
|
|
117
|
+
sdd close 001-minha-mudanca --by "Responsável" --note "Implementação revista; validação externa pendente" --archive
|
|
118
|
+
~~~
|
|
119
|
+
|
|
120
|
+
Use o caminho realmente retornado. A verificação gera USER_TESTS.md a partir do handoff validado
|
|
121
|
+
e registra os hashes do JSON e do roteiro. Não há execução automática desses passos.
|
|
122
|
+
Cada execução preserva seu roteiro em runs/ID/USER_TESTS.md; USER_TESTS.md é a cópia da versão mais recente.
|
|
123
|
+
|
|
124
|
+
| Resultado | Significado | Encerramento da implementação |
|
|
125
|
+
|---|---|---|
|
|
126
|
+
| passed | Aceitação e checks obrigatórios verificados para os inputs atuais | Permitido |
|
|
127
|
+
| limited | Trabalho concluído com limitações externas explícitas e handoff atual | Permitido, como implemented_with_limitations |
|
|
128
|
+
| partial | Verificação parcial ou itens ainda sem evidência/handoff suficiente | Continuar implementação/registro; não declarar encerramento final |
|
|
129
|
+
| failed | Falha obrigatória observada ou inputs alterados durante a execução | Corrigir/reavaliar e verificar novamente |
|
|
130
|
+
|
|
131
|
+
Com limited, acceptance_verified é false; os itens continuam deferred/not_applicable.
|
|
132
|
+
closure.validation, pending_verification e histórico preservam essas condições após arquivamento.
|
|
133
|
+
Antes de fechar, o estado da mudança é implemented, distinto de verified.
|
|
134
|
+
Consolide o comportamento implementado identificando o que ainda não foi observado no ambiente externo.
|
|
135
|
+
Concluir implementação não comprova funcionamento em produção e não autoriza deploy.
|
|
136
|
+
|
|
137
|
+
Se existe uma tarefa específica de teste externo, use kind: verification, status: deferred e
|
|
138
|
+
deferral: {by: Responsável, reason: Motivo}, cobrindo os IDs externos de aceitação.
|
|
139
|
+
Tarefas de implementação não podem ser adiadas dessa forma. Dependências realmente necessárias
|
|
140
|
+
continuam sendo respeitadas. Se a tarefa externa for executada, atualize seu estado para done antes
|
|
141
|
+
de gerar a evidência final dos inputs atuais.
|
|
142
|
+
|
|
143
|
+
Um caso externo not_applicable precisa de justificativa; não cancela silenciosamente um requisito.
|
|
144
|
+
Para remover comportamento do escopo, revise o contrato e a autorização normalmente.
|
|
145
|
+
Os checks advisory não executados ou falhos aparecem em warnings.
|
|
146
|
+
|
|
147
|
+
## Continuidade, segurança e rastreabilidade
|
|
148
|
+
|
|
149
|
+
- Um handoff só vale para seus inputs; mudança em código/plano exige revisar as limitações.
|
|
150
|
+
- Uma falha observada nos mesmos inputs não desaparece ao omitir evidência ou pular a execução externa.
|
|
151
|
+
- Guia/JSON alterado depois da verificação exige uma nova verificação antes de fechar.
|
|
152
|
+
- Todos os comandos continuam sujeitos às permissões reais. O CLI não é um sandbox.
|
|
153
|
+
- sdd status mostra o resultado do encerramento e as verificações pendentes.
|
|
154
|
+
- Uma dependência encerrada com limitações permite progresso, mas gera aviso para análise do trabalho seguinte.
|
|
155
|
+
- Reabra com motivo quando o ambiente estiver disponível, registre resultados reais e verifique novamente.
|
|
156
|
+
- O histórico do encerramento anterior, com suas limitações, permanece preservado.
|
|
157
|
+
|
|
158
|
+
CLI: 0 significa operação concluída, inclusive limited; 1 indica falha e 2 verificação partial.
|
|
159
|
+
Uma automação que exige validação integral deve avaliar verdict/acceptance_verified, não só o código 0.
|
|
160
|
+
Não transforme esse requisito de uma publicação específica em bloqueio universal do desenvolvimento.
|
package/docs/quality.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Quality and evaluation
|
|
2
|
+
|
|
3
|
+
## Automated checks
|
|
4
|
+
|
|
5
|
+
~~~sh
|
|
6
|
+
npm ci
|
|
7
|
+
npm test
|
|
8
|
+
npm run check
|
|
9
|
+
npm run test:coverage
|
|
10
|
+
npm pack --dry-run
|
|
11
|
+
~~~
|
|
12
|
+
|
|
13
|
+
Tests exercise real temporary projects and child processes:
|
|
14
|
+
installation/preservation/conflicts, YAML parsing, references and cycles, context budgets,
|
|
15
|
+
approval freshness, automated and manual verification, cancellation, archival/reopen,
|
|
16
|
+
timeouts, path restrictions, adapters, conservative migration and npm package installation.
|
|
17
|
+
|
|
18
|
+
Structural checks verify shipped metadata and exports. Test coverage helps find unexercised paths;
|
|
19
|
+
it is not a quality score or proof of semantic correctness.
|
|
20
|
+
|
|
21
|
+
CI is configured to run supported Node.js versions on Linux and Windows.
|
|
22
|
+
The package has one maintained runtime dependency, yaml, locked for reproducible contributor installation.
|
|
23
|
+
Review dependency updates and run package smoke tests before release.
|
|
24
|
+
|
|
25
|
+
## Forward evaluation
|
|
26
|
+
|
|
27
|
+
Use the same project baseline for:
|
|
28
|
+
1. A small reversible automated fix.
|
|
29
|
+
2. A capability with manual verification.
|
|
30
|
+
3. A partially implemented approved requirement that changes.
|
|
31
|
+
4. A fresh-session resume using only the context packet.
|
|
32
|
+
5. A change touching an integration whose current contract must remain valid.
|
|
33
|
+
|
|
34
|
+
Measure omitted constraints, time to resume, relevant/irrelevant documents loaded,
|
|
35
|
+
human interventions, rework and defects found. Repeat cases to account for model variation.
|
|
36
|
+
Do not grade the workflow only by how little Markdown it generates.
|
|
37
|
+
|
|
38
|
+
## Release checklist
|
|
39
|
+
|
|
40
|
+
- Run the suite, package checks and installed-tarball smoke test.
|
|
41
|
+
- Review the diff, migration instructions, scope/evidence semantics and security limitations.
|
|
42
|
+
- Exercise native adapters interactively when available; otherwise record the unverified compatibility without claiming it passed.
|
|
43
|
+
- Record any unverified platform behavior.
|
|
44
|
+
- Publish npm/marketplace artifacts only through an explicitly authorized release action.
|
|
45
|
+
|
|
46
|
+
No comparison in this project claims parity with every other workflow.
|
|
47
|
+
Quality claims should identify tested scenarios and remaining limits.
|
|
48
|
+
|
|
49
|
+
## Project quality and unavailable environments
|
|
50
|
+
|
|
51
|
+
Project-owned QUALITY.md selects meaningful criteria with links to analyzer configuration.
|
|
52
|
+
quality.tdd guides optional/preferred/required practice; acceptance descriptions carry concrete BDD examples.
|
|
53
|
+
Checks are required/local by default; advisory issues remain warnings and external commands require --run-external.
|
|
54
|
+
Full limited verification may close implementation with a current handoff and pending external verification.
|
|
55
|
+
It is not deployment approval or a claim that unavailable tests passed. Failed/partial/stale verification cannot close.
|
|
56
|
+
Detailed safe user-test instructions and examples: quality-gates.pt-BR.md.
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Atualização do pacote npm
|
|
2
|
+
|
|
3
|
+
Verificação em 20/11/2026: o registro público retorna sdd-flow@1.3.3 e latest aponta para 1.3.3.
|
|
4
|
+
Este checkout prepara 2.0.0 e ainda não representa uma publicação concluída.
|
|
5
|
+
|
|
6
|
+
## 1. Baixar e testar sem publicar
|
|
7
|
+
|
|
8
|
+
O ZIP inclui CLI, templates, documentação, testes e workflows, sem node_modules ou histórico Git.
|
|
9
|
+
Extraia-o e siga local-testing.pt-BR.md. O TGZ é o pacote instalável, sem a suíte de desenvolvimento.
|
|
10
|
+
O patch completo preserva commits e remoções de arquivos obsoletos e é a opção recomendada para envio ao GitHub.
|
|
11
|
+
Copiar arquivos do ZIP sobre o repositório não aplica essas remoções.
|
|
12
|
+
|
|
13
|
+
## 2. Aplicar a entrega no repositório Git
|
|
14
|
+
|
|
15
|
+
Exemplos PowerShell. Use uma clonagem nova para preservar trabalhos em andamento:
|
|
16
|
+
|
|
17
|
+
~~~powershell
|
|
18
|
+
git clone https://github.com/moisesuailab/sdd-flow.git sdd-flow-release
|
|
19
|
+
Set-Location sdd-flow-release
|
|
20
|
+
git switch main
|
|
21
|
+
git pull --ff-only
|
|
22
|
+
git status --short
|
|
23
|
+
git log -1 --oneline
|
|
24
|
+
git switch -c feat/sdd-flow-v2
|
|
25
|
+
git am 'C:\caminho\sdd-flow-2.0.0.patch'
|
|
26
|
+
~~~
|
|
27
|
+
|
|
28
|
+
O patch completo foi preparado e testado sobre d84c62d51d9c566b0f3e8a6279418220e0fc6e8f, a base 1.3.3 analisada.
|
|
29
|
+
Ele inclui as entregas anteriores desta conversa: não o reaplique sobre esses mesmos commits.
|
|
30
|
+
Se main tiver avançado, examine os conflitos com git status. git am --abort desfaz somente a aplicação em andamento;
|
|
31
|
+
não use reset --hard ou force push para contornar diferenças. Adapte a entrega à base atual e teste novamente.
|
|
32
|
+
|
|
33
|
+
O patch incremental sdd-flow-2.0.0-update.patch contém somente a evolução posterior ao commit
|
|
34
|
+
c7ab2338eac10d10d18f526f6e7d75a6e4e69255 (a entrega anterior, com quality gates e handoff).
|
|
35
|
+
Use-o apenas se essa entrega já estiver aplicada; ele não substitui o patch completo numa base 1.3.3.
|
|
36
|
+
Confira git log antes de escolher. Não aplique os dois patches sobre o mesmo checkout.
|
|
37
|
+
|
|
38
|
+
Depois da aplicação:
|
|
39
|
+
|
|
40
|
+
~~~powershell
|
|
41
|
+
npm ci
|
|
42
|
+
npm test
|
|
43
|
+
npm run check
|
|
44
|
+
npm run release:check -- --version 2.0.0 --tag next --check-registry
|
|
45
|
+
npm publish --dry-run --tag next
|
|
46
|
+
git status --short
|
|
47
|
+
git diff --check
|
|
48
|
+
git log -5 --oneline
|
|
49
|
+
~~~
|
|
50
|
+
|
|
51
|
+
Se fizer ajustes durante os testes, revise git diff, selecione arquivos com git add e crie um commit antes de enviar.
|
|
52
|
+
O patch já cria seus próprios commits. Não inclua credenciais, node_modules ou tarballs no commit.
|
|
53
|
+
|
|
54
|
+
## 3. Enviar branch e abrir PR
|
|
55
|
+
|
|
56
|
+
~~~powershell
|
|
57
|
+
git push -u origin feat/sdd-flow-v2
|
|
58
|
+
~~~
|
|
59
|
+
|
|
60
|
+
No GitHub, abra Compare & pull request, com base main e a branch enviada.
|
|
61
|
+
Título sugerido: “Evoluir metodologia, contexto e rastreabilidade do sdd-flow para 2.0”.
|
|
62
|
+
Descreva a mudança de formato, Node 22+, testes realizados, validação nos harnesses e limites conhecidos.
|
|
63
|
+
Espere os checks do CI e revise a migração antes do merge. Criar PR não publica no npm.
|
|
64
|
+
Se usar GitHub CLI autenticado, gh pr create --base main --head feat/sdd-flow-v2 abre esse fluxo.
|
|
65
|
+
|
|
66
|
+
Após o merge, publique o código integrado:
|
|
67
|
+
|
|
68
|
+
~~~powershell
|
|
69
|
+
git switch main
|
|
70
|
+
git pull --ff-only
|
|
71
|
+
npm ci
|
|
72
|
+
npm test
|
|
73
|
+
npm run check
|
|
74
|
+
~~~
|
|
75
|
+
|
|
76
|
+
Escolha uma rota abaixo: Actions com OIDC ou terminal autenticado. Não execute ambas para a mesma versão.
|
|
77
|
+
|
|
78
|
+
## PR, merge e publicação são operações distintas
|
|
79
|
+
|
|
80
|
+
O npm não exige PR: um mantenedor autorizado pode publicar a partir de um checkout local.
|
|
81
|
+
Para este projeto, o fluxo recomendado é revisar a branch por PR, executar CI, integrar em main e publicar o commit revisado.
|
|
82
|
+
A automação adicionada aqui aceita execução manual somente em main no repositório moisesuailab/sdd-flow.
|
|
83
|
+
Fazer merge não publica automaticamente e publicar no npm não atualiza o GitHub.
|
|
84
|
+
|
|
85
|
+
A versão 2 altera formatos e requisitos de runtime; não deve substituir o conteúdo de 1.3.3.
|
|
86
|
+
Cada nome/versão publicado é permanente. Use um número novo.
|
|
87
|
+
|
|
88
|
+
## Primeiro testar pela tag next
|
|
89
|
+
|
|
90
|
+
O campo version já está em 2.0.0; não execute npm version major novamente neste checkout.
|
|
91
|
+
A primeira publicação recomendada usa next, mantendo latest na versão anterior.
|
|
92
|
+
|
|
93
|
+
Após a publicação:
|
|
94
|
+
~~~sh
|
|
95
|
+
npm install -g sdd-flow@next
|
|
96
|
+
sdd --version
|
|
97
|
+
~~~
|
|
98
|
+
|
|
99
|
+
A versão 2.0.0 pode usar a tag next mesmo sem sufixo rc.
|
|
100
|
+
Se quiser versões de teste separadas, use números como 2.0.0-rc.1 e atualize package.json/package-lock juntos.
|
|
101
|
+
|
|
102
|
+
## Automação preparada
|
|
103
|
+
|
|
104
|
+
Arquivo: .github/workflows/publish.yml. Ele é acionado manualmente, sem publicar em todo push ou PR.
|
|
105
|
+
O job de publicação depende de testes no Node 22/24 em Linux/Windows.
|
|
106
|
+
O código é obtido pelo SHA do disparo, a versão é conferida e o registro é consultado antes do envio.
|
|
107
|
+
O mesmo tarball é inspecionado em dry-run e publicado. Artefatos de desenvolvimento ficam fora do pacote.
|
|
108
|
+
|
|
109
|
+
O acesso ao npm usa Trusted Publishing/OIDC, sem um token permanente no repositório.
|
|
110
|
+
O dono do pacote precisa configurar, nas definições do pacote no npm:
|
|
111
|
+
|
|
112
|
+
| Campo | Valor desta automação |
|
|
113
|
+
|---|---|
|
|
114
|
+
| Provedor | GitHub Actions |
|
|
115
|
+
| Organização/usuário | moisesuailab |
|
|
116
|
+
| Repositório | sdd-flow |
|
|
117
|
+
| Nome do workflow | publish.yml |
|
|
118
|
+
| Environment | npm |
|
|
119
|
+
| Ação permitida | Publicação direta com npm publish |
|
|
120
|
+
|
|
121
|
+
A autorização do npm é separada da conexão GitHub do ChatGPT.
|
|
122
|
+
Criar uma relação de confiança concede permissão de publicação e deve ser feito pelo responsável.
|
|
123
|
+
Se quiser revisão adicional, configure revisores no environment npm do GitHub; o nome por si só não cria proteção.
|
|
124
|
+
Confira as exigências atuais em https://docs.npmjs.com/trusted-publishers/ ao configurar.
|
|
125
|
+
|
|
126
|
+
Depois do merge e da configuração:
|
|
127
|
+
1. Abra a action “Publish npm package” no GitHub e execute em main.
|
|
128
|
+
2. Informe version igual a package.json, inicialmente 2.0.0.
|
|
129
|
+
3. Selecione dist_tag next.
|
|
130
|
+
4. Confira todos os jobs e verifique o registro:
|
|
131
|
+
|
|
132
|
+
~~~sh
|
|
133
|
+
npm view sdd-flow@2.0.0 version dist-tags --json
|
|
134
|
+
~~~
|
|
135
|
+
|
|
136
|
+
O workflow não configura permissões do npm por conta própria.
|
|
137
|
+
npm whoami sem login local não testa se um job OIDC do GitHub está autorizado.
|
|
138
|
+
|
|
139
|
+
## Publicação manual alternativa
|
|
140
|
+
|
|
141
|
+
Em um checkout revisado, com Node.js 22+ e acesso de mantenedor ao pacote:
|
|
142
|
+
|
|
143
|
+
~~~sh
|
|
144
|
+
npm ci
|
|
145
|
+
npm test
|
|
146
|
+
npm run check
|
|
147
|
+
npm run release:check -- --version 2.0.0 --tag next --check-registry
|
|
148
|
+
npm publish --dry-run --tag next
|
|
149
|
+
npm login
|
|
150
|
+
npm publish --tag next
|
|
151
|
+
~~~
|
|
152
|
+
|
|
153
|
+
Após o envio, confira npm view sdd-flow@2.0.0 version dist-tags --json e crie um novo laboratório
|
|
154
|
+
instalando explicitamente sdd-flow@2.0.0. Para registrar o marco no Git, crie e envie a tag v2.0.0
|
|
155
|
+
no commit integrado que foi publicado. Uma tag Git não publica no npm por si só.
|
|
156
|
+
|
|
157
|
+
O dry-run não concede acesso nem garante que a autenticação final funcionará.
|
|
158
|
+
O npm pode exigir confirmação de autenticação/2FA no fluxo oficial.
|
|
159
|
+
Não compartilhe senha, OTP ou token em mensagens ou arquivos do projeto.
|
|
160
|
+
O hook prepublishOnly repete testes e checks antes de uma publicação manual a partir do código-fonte.
|
|
161
|
+
|
|
162
|
+
## Tornar a versão estável
|
|
163
|
+
|
|
164
|
+
Depois de revisar adoção/migração, evidências disponíveis e limitações de compatibilidade,
|
|
165
|
+
um mantenedor autenticado pode promover a versão existente:
|
|
166
|
+
|
|
167
|
+
~~~sh
|
|
168
|
+
npm dist-tag add sdd-flow@2.0.0 latest
|
|
169
|
+
npm view sdd-flow dist-tags --json
|
|
170
|
+
~~~
|
|
171
|
+
|
|
172
|
+
Isso move a tag; não republica o mesmo número.
|
|
173
|
+
A automação de publish não promove automaticamente uma versão já existente.
|
|
174
|
+
Para um release novo depois disso, incremente o número apropriado, revise e publique novamente.
|
|
175
|
+
|
|
176
|
+
## Atualizar os projetos consumidores
|
|
177
|
+
|
|
178
|
+
Instale o CLI desejado e depois atualize os templates de cada projeto com sdd update --dry-run.
|
|
179
|
+
Não basta atualizar a instalação global para modificar os arquivos já copiados nos aplicativos.
|
|
180
|
+
Leia usage.pt-BR.md e migration.md antes de migrar o formato 1.x.
|
|
181
|
+
|
|
182
|
+
## Pré-condições que ainda precisam de acesso
|
|
183
|
+
|
|
184
|
+
A publicação real depende da autorização do mantenedor no npm ou de um Trusted Publisher configurado.
|
|
185
|
+
O envio da branch/PR depende de escrita no repositório. A conexão observada nesta sessão recusou escrita com 403.
|
|
186
|
+
Os arquivos e verificações preparados aqui não significam que a publicação ou o PR já ocorreram.
|