sdd-flow 1.3.3 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/CONTRIBUTING.md +25 -0
  3. package/LICENSE +21 -21
  4. package/README.md +402 -168
  5. package/README.pt-BR.md +387 -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 +215 -0
  10. package/docs/local-testing.pt-BR.md +196 -0
  11. package/docs/methodology.pt-BR.md +139 -0
  12. package/docs/migration.md +76 -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 +105 -0
  16. package/docs/setup-documents.pt-BR.md +120 -0
  17. package/docs/usage.pt-BR.md +310 -0
  18. package/docs/validation.md +101 -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 -50
  35. package/templates/QUICKSTART.md +16 -70
  36. package/templates/agents/AGENTS.md +58 -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 +24 -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 +35 -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,139 @@
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
+ Instalações novas usam step: uma tarefa por vez, seguida de revisão. A autorização do usuário para
23
+ várias tarefas específicas ou todas as tarefas permite continuar nesse lote sem confirmações repetidas
24
+ nem alteração obrigatória da configuração. Aprovação do plano, por si só, não muda a autonomia.
25
+ Batch pode ser a preferência permanente; atualizações preservam a escolha de projetos existentes.
26
+ Cada tarefa continua sendo verificada e as dependências respeitadas, inclusive durante um lote.
27
+
28
+ Evidência de execução local e validação externa são distintas. Falta de ambiente não precisa bloquear
29
+ uma implementação concluída: um handoff atual registra o que ficou pendente e como testar com segurança.
30
+ O encerramento limited nunca representa teste externo aprovado; falhas observadas continuam registradas.
31
+ Veja quality-gates.pt-BR.md para a política required/advisory, exemplos BDD e procedimento TDD.
32
+
33
+ ## Comparação com as versões analisadas
34
+
35
+ Base original: sdd-flow 1.3.3, commit d84c62d51d9c566b0f3e8a6279418220e0fc6e8f.
36
+ O anexo do colaborador foi analisado como conjunto de arquivos; não continha histórico Git que
37
+ permitisse demonstrar ancestralidade. A comparação se refere aos materiais examinados em 20/11/2026.
38
+
39
+ | Aspecto | Original 1.3.3 | Ajuste do colaborador | Atual 2.x |
40
+ |---|---|---|---|
41
+ | 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 |
42
+ | 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 |
43
+ | Tarefas | Estado repetido em TASK/PROGRESS | Conservou a necessidade de sincronização | TASK canônico; STATE curto e opcional |
44
+ | 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 |
45
+ | 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 |
46
+ | 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 |
47
+ | 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 |
48
+ | Validação parcial | Permitida | Bloqueada com tarefas pendentes | Permitida, sem representar encerramento final |
49
+ | 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 |
50
+ | Qualidade | Princípios no prompt | Atenção adicional às assertions e achados | Checks required/advisory, evidências, regressões, TDD/BDD e handoff seguro |
51
+ | 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 |
52
+ | 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 |
53
+ | 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 |
54
+
55
+ O ganho demonstrável é estrutural e funcional: menos estados redundantes, seleção de contexto e
56
+ condições verificáveis. Isso não prova menor custo de tokens, melhor código ou superioridade sobre
57
+ todo framework. Tais afirmações exigem avaliações repetidas com tarefas, modelos e condições comparáveis.
58
+
59
+ O colaborador melhorou o desenho de rastreabilidade; esta evolução incorpora esses acertos e corrige
60
+ as inconsistências encontradas nos materiais. Não foram comparadas implementações reais produzidas
61
+ pelos três workflows, portanto superioridade de custo ou de qualidade do código gerado não está demonstrada.
62
+
63
+ O núcleo ficou mais verificável, mas também exige aprender formatos e comandos novos e usar Node 22+.
64
+ A seleção de contexto depende de referências bem mantidas; o CLI não infere automaticamente todos os
65
+ efeitos de uma mudança. A verificação é conservadora: alterações nos inputs podem exigir nova execução.
66
+ Identidade do revisor, semântica dos testes e segurança do ambiente não são atestadas pelo CLI.
67
+ Há hotspots de complexidade no próprio código, registrados em validation.md; os testes não eliminam
68
+ a necessidade de manutenção e avaliação prática nos harnesses.
69
+
70
+ ## Como o fluxo funciona na prática
71
+
72
+ 1. Instale a base e faça o setup guiado pelo agente, usando fontes e fatos disponíveis.
73
+ 2. Crie uma mudança com objetivo delimitado; pesquise somente as incertezas relevantes.
74
+ 3. Defina requisitos, exemplos de aceitação, tarefas e impacto nos consumidores.
75
+ 4. Registre a autorização real e implemente dentro desse escopo, consultando contexto pertinente.
76
+ 5. Execute checks disponíveis, revise assertions/regressões e registre limitações quando faltar ambiente.
77
+ 6. Consolide o conhecimento vigente e encerre como verificado ou implementado com limitações explícitas.
78
+
79
+ Instalação não cria entendimento de produto sozinha. Veja setup-documents.pt-BR.md para perguntas,
80
+ PRD, ADR, system design, design system e modelos opcionais. O método não exige uma tríade fixa de documentos.
81
+
82
+ ## O que permanece rastreável
83
+
84
+ | Pergunta | Registro |
85
+ |---|---|
86
+ | O que foi solicitado e qual aceitação deve ser atendida? | change.yaml e SPEC.md |
87
+ | Como será feito e em que estado está? | TASK.md |
88
+ | Qual escopo foi autorizado, quando e por quem? | approval e history/approval-*.json |
89
+ | O que mudou no plano aprovado e por quê? | history/revision-*.json |
90
+ | Quais comandos rodaram e que resultado produziram? | runs/ID/receipt.json e logs |
91
+ | Que observação manual foi realizada? | Evidência com cenário, executor, instante e fingerprint |
92
+ | Qual resultado pode ser usado agora? | verification.json, válido somente para os inputs atuais |
93
+ | Como o sistema funciona após a entrega? | current/ e decisões ativas |
94
+ | Como chegamos até aqui? | Histórico da mudança, arquivo e Git |
95
+
96
+ O framework rastreia artefatos, estados, decisões e execuções registradas. Não captura cada pensamento
97
+ do modelo nem todas as chamadas do harness. Sessões, traces e auditoria externa podem complementar
98
+ os registros. Aprovações são declarações registradas, não autenticação de identidade.
99
+
100
+ ## Portabilidade
101
+
102
+ O núcleo funciona com arquivos e comandos. Adaptadores fornecem pontos de entrada, preservando
103
+ configurações existentes. Permissões, MCP, modelos, compactação e delegação pertencem ao harness.
104
+ Essas capacidades não alteram as condições de aceitação e de encerramento.
105
+
106
+ Ferramentas externas podem fornecer evidência; registre origem e instante quando relevantes.
107
+ O fingerprint local não atesta por conta própria um sistema remoto.
108
+ Não é necessário A2A ou multiagentes para seguir esta metodologia.
109
+
110
+ ## Idioma e escrita
111
+
112
+ As instruções distribuídas do método permanecem em inglês como fonte comum.
113
+ O idioma dos documentos do aplicativo é configurável, independentemente do idioma desses templates.
114
+
115
+ ~~~yaml
116
+ documentation:
117
+ language: pt-BR
118
+ ~~~
119
+
120
+ Use português correto e UTF-8 nos artefatos narrativos: requisitos, aceitação, tarefas, pesquisa,
121
+ contratos, decisões e observações. Preserve termos originais quando a tradução prejudicar o significado.
122
+ Chaves técnicas, IDs, paths e APIs permanecem estáveis; a chave description pode ter valor em português.
123
+ Slugs podem ser ASCII sem eliminar acentos do título ou do conteúdo.
124
+
125
+ auto é o padrão genérico: o agente segue o idioma do usuário até o setup registrar a escolha da equipe.
126
+ Configurações antigas sem documentation continuam válidas. O CLI valida a tag e a inclui no contexto;
127
+ isso orienta o agente, não certifica linguisticamente cada frase.
128
+ Novas specs/tarefas têm textos iniciais em português quando a configuração usa pt ou pt-BR.
129
+ Outros idiomas podem ser usados pelo agente; os textos iniciais do CLI usam inglês como fallback.
130
+ Diagnósticos, chaves de máquina e relatórios determinísticos do CLI ainda podem permanecer em inglês;
131
+ esta versão não é uma localização completa da interface do CLI.
132
+
133
+ Não foi medido ganho de qualidade/custo por escrever as instruções em inglês. Não elimine
134
+ acentos como técnica de otimização. A clareza para autores e revisores de negócio é o critério principal.
135
+ Não traduza o histórico encerrado apenas para uniformizar aparência. A tradução de um contrato ativo
136
+ aprovado altera seu conteúdo e exige revisão; preserve o registro anterior.
137
+
138
+ Use local-testing.pt-BR.md para testar o CLI e executar cenários com um agente real.
139
+ Um pacote menor que omite uma regra é uma regressão, não uma otimização.
@@ -0,0 +1,76 @@
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
+ - New projects default to step; explicit user authorization for several/all tasks permits a bounded batch.
65
+ - Existing configured autonomy is preserved. Update does not reset a project's batch preference to step.
66
+ - Research is optional except in rigorous mode.
67
+ - Task state lives in YAML metadata, with no duplicate PROGRESS table.
68
+ - Approval applies to scope, not to six independently mutable files.
69
+ - Mandatory project constraints live in POLICIES.md; skills carry conditional procedures.
70
+ - Approved-scope snapshots, revisions and each run receipt remain available outside default context.
71
+ - Tests may be automated, manual or inspection-based.
72
+ - Partial verification is supported and cannot close a change.
73
+ - Closing requires fresh full evidence and explicit consolidation.
74
+ - Full limited verification may close implementation with a current environment handoff, retaining pending tests explicitly.
75
+ - Existing checks remain required/local. Classify external checks deliberately; they no longer run without --run-external.
76
+ - 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,105 @@
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.
@@ -0,0 +1,120 @@
1
+ # Perguntas do setup e documentos de referência
2
+
3
+ O setup configura o modo de trabalhar com IA. Os documentos do produto fornecem contexto e decisões.
4
+ sdd init instala arquivos; o agente interpreta objetivo, código e fontes ao seguir agents/SETUP.md.
5
+ O CLI não entrevista o usuário nem descobre automaticamente todas as regras de negócio.
6
+
7
+ ## O que o agente precisa saber
8
+
9
+ Não há questionário obrigatório. Primeiro consulte as informações fornecidas e o próprio projeto.
10
+ Pergunte somente sobre lacunas materiais que alterem comportamento, escopo, arquitetura ou segurança.
11
+
12
+ | Informação | Projeto novo | Projeto existente |
13
+ |---|---|---|
14
+ | Propósito e público | Descrição do usuário ou material fornecido | README/PRD e aplicação; confirmar quando houver ambiguidade |
15
+ | Resultado pretendido | Primeira entrega ou objetivo conhecido; refinamento pode ocorrer por spec | Próxima mudança quando definida; não é necessário reconstruir todo o passado |
16
+ | Regras e restrições | Regras conhecidas, permissões e integrações relevantes | Código, contratos e fontes vigentes; separar intenção e comportamento observado |
17
+ | Tecnologia | Escolhas obrigatórias ou proposta justificada a revisar | Manifests, configuração, dependências e estrutura reais |
18
+ | Convenções e interface | Padrões fornecidos ou decisões ainda abertas | Componentes, tokens, design system e práticas existentes |
19
+ | Verificação | O que pode ser executado com segurança e o que depende de outro ambiente | Testes e resultados de baseline disponíveis, com limitações |
20
+ | Idioma e autonomia | Preferências conhecidas da equipe | Preservar configuração existente e perguntar apenas sobre conflitos |
21
+
22
+ Uma instalação pode ser feita antes dessas respostas. O agente pode registrar fatos e dúvidas
23
+ enquanto configura o projeto. Para implementar comportamento ainda ambíguo, precisa resolver a decisão
24
+ material; não precisa perguntar sobre fatos já claros no repositório nem preencher detalhes especulativos.
25
+
26
+ Em projeto existente, o setup preserva código e documentos e apresenta um resumo do entendimento.
27
+ Não autoriza refatorar, trocar arquitetura ou corrigir problemas históricos por conta própria.
28
+ Em projeto novo, uma descrição clara pode ser suficiente para começar; o PRD formal é opcional.
29
+
30
+ ## PRD, SD, ADR e DS têm funções diferentes
31
+
32
+ | Documento | Pergunta principal | Conteúdo | Uso |
33
+ |---|---|---|---|
34
+ | PRD — Product Requirements Document | O que construir, para quem e com qual resultado? | Objetivos, escopo, regras, restrições e exemplos de aceitação | Direção do produto e fonte para mudanças |
35
+ | SD — System Design | Como a solução se organiza e se comunica? | Componentes, contratos, dados, integrações, segurança e operação | Mudanças arquiteturais ou entre componentes |
36
+ | ADR — Architecture Decision Record | Por que esta decisão foi tomada? | Contexto, alternativas/compromissos, escolha, consequências e estado | Um registro por decisão relevante |
37
+ | DS — Design System | Como a interface deve se apresentar e se comportar? | Tokens, componentes, estados, acessibilidade e responsividade | Trabalho de interface quando aplicável |
38
+ | Roadmap | Quais resultados vêm primeiro? | Prioridades, dependências e entregas esperadas | Priorização, sem duplicar estado das tarefas |
39
+
40
+ Um ADR não substitui um system design. O design system não precisa existir num serviço sem interface.
41
+ Arquivos de API, modelo de dados, segurança, operação e estratégia de testes também podem ser usados.
42
+ Esses nomes são convenções úteis, não uma lista fechada dos documentos aceitos pelo framework.
43
+
44
+ ## Os três arquivos da versão antiga
45
+
46
+ Na 1.3.3, o instalador perguntava se deveria criar docs/.
47
+ Quando a pasta ainda não existia, criava prd.md, roadmap.md e architecture.md.
48
+ Não criava automaticamente uma tríade PRD/ADR/SD.
49
+
50
+ A interface 2.x oferece essa conveniência de maneira explícita e opcional:
51
+
52
+ ~~~sh
53
+ sdd init --docs
54
+ ~~~
55
+
56
+ Sem --docs, o setup não cria documentos de produto. Para escolher outros modelos depois:
57
+
58
+ ~~~sh
59
+ sdd docs --types prd,sd,ds,adr,roadmap --dry-run
60
+ sdd docs --types prd,sd,ds,adr,roadmap
61
+ ~~~
62
+
63
+ | Preset | Caminho |
64
+ |---|---|
65
+ | prd | docs/prd.md |
66
+ | roadmap | docs/roadmap.md |
67
+ | sd | docs/architecture.md |
68
+ | ds | docs/design-system.md |
69
+ | adr | docs/adr/README.md e docs/adr/_template.md |
70
+
71
+ O comando também cria docs/README.md quando ausente.
72
+ Sem --types, sdd docs usa os três presets originais: prd,roadmap,sd.
73
+ Pode selecionar apenas um, como sdd docs --types ds.
74
+ O dry-run não escreve arquivos. Documentos existentes são preservados, inclusive quando já contêm conteúdo personalizado.
75
+ Os arquivos são rascunhos para o agente/equipe revisar e preencher; não representam pesquisa ou decisões executadas.
76
+ O template ADR é proposed. Um registro real só deve ser selecionado como decisão active depois da escolha efetiva.
77
+
78
+ Use documentation.language: pt-BR em agents/config.yaml antes de gerar para receber os modelos em português.
79
+ auto usa os textos iniciais em inglês até o setup registrar a língua da equipe e preencher os documentos.
80
+ Chaves e estados técnicos permanecem estáveis; texto do projeto usa UTF-8 e acentos.
81
+
82
+ ## Uma fonte por assunto
83
+
84
+ Preserve o local das fontes existentes. Se ADRs já ficam em agents/decisions/, não copie as mesmas
85
+ decisões para docs/adr/. Use um índice ou referência. Para decisões novas, escolha um local canônico.
86
+ Os presets não impedem outros caminhos; não existem nomes obrigatórios para documentos fornecidos pelo usuário.
87
+
88
+ Mapeie caminhos e responsabilidades em agents/PROJECT.md, sem copiar o conteúdo inteiro.
89
+ Regras essenciais do projeto pertencem a POLICIES.md; procedimentos reutilizáveis a skills;
90
+ conhecimento de comportamento vigente a current/. Esses papéis podem apontar para documentos já existentes.
91
+
92
+ Cada mudança seleciona somente as fontes necessárias. Exemplo:
93
+
94
+ ~~~yaml
95
+ sources:
96
+ - path: docs/prd.md
97
+ section: Exportação de dados
98
+ context:
99
+ - path: docs/design-system.md
100
+ section: Estados e interações
101
+ decisions:
102
+ - docs/adr/0001-formato-exportacao.md
103
+ ~~~
104
+
105
+ decisions exige os metadados de decisão do sdd-flow, incluindo kind: decision e status: active.
106
+ Um ADR antigo sem esses metadados pode ser consultado por context/sources sem conversão em massa.
107
+ Preserve sua origem e selecione sua pertinência; não invente uma aprovação ou razão histórica.
108
+
109
+ Para PDFs/imagens, use os leitores do harness. O CLI compõe texto Markdown/UTF-8, não interpreta
110
+ semanticamente um PDF ou um arquivo de design. Quando útil, mantenha um trecho revisado com proveniência
111
+ e o original preservado. Links externos podem ser consultados com as ferramentas disponíveis, sem exigir um harness específico.
112
+
113
+ ## Documentação do framework e documentação da aplicação
114
+
115
+ A pasta docs/ do repositório sdd-flow explica como o framework funciona.
116
+ A pasta docs/ de uma aplicação consumidora contém referências daquele produto.
117
+ Instalar o workflow não copia todo o manual do framework para o contexto da aplicação.
118
+
119
+ A pasta não precisa ter todos os presets nem um número fixo de arquivos.
120
+ Gere o que for útil e mantenha referências curtas; não recrie o crescimento indiscriminado de documentos.