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.
Files changed (70) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/CONTRIBUTING.md +25 -0
  3. package/LICENSE +21 -21
  4. package/README.md +113 -168
  5. package/README.pt-BR.md +100 -0
  6. package/bin/cli.js +162 -424
  7. package/docs/architecture.md +91 -0
  8. package/docs/distribution.md +64 -0
  9. package/docs/formats.md +212 -0
  10. package/docs/local-testing.pt-BR.md +195 -0
  11. package/docs/methodology.pt-BR.md +133 -0
  12. package/docs/migration.md +75 -0
  13. package/docs/quality-gates.pt-BR.md +160 -0
  14. package/docs/quality.md +56 -0
  15. package/docs/releases.pt-BR.md +186 -0
  16. package/docs/setup-documents.pt-BR.md +120 -0
  17. package/docs/usage.pt-BR.md +305 -0
  18. package/docs/validation.md +95 -0
  19. package/lib/adapters.js +115 -0
  20. package/lib/check.js +221 -0
  21. package/lib/context.js +117 -0
  22. package/lib/documents.js +71 -0
  23. package/lib/handoff.js +81 -0
  24. package/lib/history.js +16 -0
  25. package/lib/install.js +181 -0
  26. package/lib/io.js +119 -0
  27. package/lib/legacy-hashes.json +31 -0
  28. package/lib/markdown.js +71 -0
  29. package/lib/project.js +200 -0
  30. package/lib/quality.js +24 -0
  31. package/lib/revisions.js +79 -0
  32. package/lib/verification.js +267 -0
  33. package/package.json +55 -32
  34. package/templates/AGENTS.md +12 -49
  35. package/templates/QUICKSTART.md +16 -70
  36. package/templates/agents/AGENTS.md +54 -92
  37. package/templates/agents/DECISIONS.md +5 -21
  38. package/templates/agents/POLICIES.md +14 -0
  39. package/templates/agents/PROJECT.md +35 -145
  40. package/templates/agents/QUALITY.md +19 -0
  41. package/templates/agents/RULES.md +22 -132
  42. package/templates/agents/SETUP.md +38 -224
  43. package/templates/agents/config.yaml +13 -0
  44. package/templates/agents/current/_template.md +19 -0
  45. package/templates/agents/decisions/_template.md +22 -0
  46. package/templates/agents/prompts/conventional-commit.md +11 -51
  47. package/templates/agents/prompts/intake.md +23 -0
  48. package/templates/agents/prompts/pr-template.md +12 -21
  49. package/templates/agents/prompts/quality.md +57 -0
  50. package/templates/agents/prompts/rpi-close.md +23 -0
  51. package/templates/agents/prompts/rpi-implement.md +31 -68
  52. package/templates/agents/prompts/rpi-plan.md +87 -117
  53. package/templates/agents/prompts/rpi-research.md +21 -67
  54. package/templates/agents/prompts/rpi-validate.md +40 -103
  55. package/templates/agents/prompts/skill-call.md +11 -29
  56. package/templates/agents/prompts/task-create.md +13 -42
  57. package/templates/agents/skills/_template/SKILL.md +11 -37
  58. package/templates/agents/harness/claude-code/.hooks/guard-delete.sh +0 -22
  59. package/templates/agents/harness/claude-code/.hooks/guard-deps.sh +0 -25
  60. package/templates/agents/harness/claude-code/.hooks/guard-git.sh +0 -24
  61. package/templates/agents/harness/claude-code/commands/sdd-implement.md +0 -3
  62. package/templates/agents/harness/claude-code/commands/sdd-plan.md +0 -3
  63. package/templates/agents/harness/claude-code/commands/sdd-research.md +0 -3
  64. package/templates/agents/harness/claude-code/commands/sdd-validate.md +0 -3
  65. package/templates/agents/harness/claude-code/settings.json +0 -34
  66. package/templates/agents/harness/opencode/commands/sdd-implement.md +0 -3
  67. package/templates/agents/harness/opencode/commands/sdd-plan.md +0 -3
  68. package/templates/agents/harness/opencode/commands/sdd-research.md +0 -3
  69. package/templates/agents/harness/opencode/commands/sdd-validate.md +0 -3
  70. 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.
@@ -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.