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,91 @@
1
+ # Context and lifecycle architecture
2
+
3
+ This is a development methodology with executable checks, not an agent orchestrator.
4
+ Phases are logical responsibilities; sessions, compaction and delegation belong to the harness.
5
+
6
+ ## Components
7
+
8
+ | Module | Responsibility |
9
+ |---|---|
10
+ | lib/io.js | Project-relative paths, atomic writes, hashing, bounded scans and mutation locks |
11
+ | lib/markdown.js | YAML parsing, Markdown metadata and heading selection |
12
+ | lib/project.js | Config, identities, skill catalog and input fingerprints |
13
+ | lib/check.js | Structural contracts, coverage references, cycles and approval checks |
14
+ | lib/context.js | Phase/task context composition with provenance and a byte budget |
15
+ | lib/verification.js | Command runs, observed evidence, receipts and closure |
16
+ | lib/history.js / lib/revisions.js | Immutable event/scope snapshots and explicit change-impact revisions |
17
+ | lib/quality.js / lib/handoff.js | Check policy, environment limitations and version-bound user-test instructions |
18
+ | lib/install.js | Ownership-aware updates, diagnostics and conservative migration |
19
+ | lib/documents.js | Optional reference-document drafts; preserve existing sources and require no fixed document set |
20
+ | lib/adapters.js | Native wrappers and export layouts from shared workflow knowledge |
21
+ | bin/cli.js | Arguments, orchestration, output and exit codes |
22
+
23
+ ## Context selection
24
+
25
+ The initial entry point is a short map. Core constraints, project-specific mandatory policies, project map and the current phase
26
+ form the base packet. The active task selects its requirement/acceptance metadata.
27
+ The specification body remains available because scope constraints in prose must not be silently lost.
28
+ Selected current capability contracts and ADRs are loaded with provenance.
29
+ Only explicit skill selections load bodies; the catalog carries descriptions without bodies.
30
+ Sources/research are included during research/plan and remain available on demand otherwise.
31
+
32
+ Large documents can be selected by an exact ATX heading. Heading extraction ignores fenced code;
33
+ it ends at the next heading of equal or higher level. The packet fails on overflow and reports file sizes.
34
+ It measures UTF-8 bytes rather than estimating model tokens. The default budget is a project setting,
35
+ not a universal optimum.
36
+ Use --inspect to get sizes/remedies without emitting bodies. Generating an over-budget packet raises
37
+ CONTEXT_BUDGET_EXCEEDED; this is a recoverable selection checkpoint, not a failure of the application.
38
+ The framework cannot intercept arbitrary chat input; intake guidance handles broad requests at the agent level.
39
+
40
+ No vector database or model API is required. The agent can inspect additional code and sources
41
+ when needed, explaining the relevance. Selection completeness still depends on the project map
42
+ and declared relationships; scripts cannot infer every domain dependency.
43
+
44
+ Optional documentation.language selects the project-artifact language (auto when absent).
45
+ The context header carries the language and UTF-8 encoding. Distributed procedures remain English;
46
+ agents preserve the project's spelling and diacritics while keeping machine keys/IDs stable.
47
+ This is guidance plus locale validation, not linguistic certification or full CLI localization.
48
+
49
+ ## Three distinct states
50
+
51
+ Scope authorization binds the normative specification, task plan, selected references, project policies and verification/execution policy.
52
+ Routine task status/evidence updates do not require reapproving an unchanged plan.
53
+ Execution state is canonical in TASK.md. Optional STATE.md summarizes only the next step and blockers.
54
+ Verification binds source bytes, selected workflow contracts, configuration and task states.
55
+
56
+ Approval is a recorded assertion of actual user authorization, not authenticated identity.
57
+ Changing its by field is not a security boundary. Tool permission enforcement belongs to the agent runtime.
58
+ Prior scope snapshots are preserved separately. Explicit revisions compare structured requirements,
59
+ acceptance and task links, reopen impacted tasks/dependents, and conservatively reopen all for broad policy/prose changes.
60
+ This comparison supports impact review; it does not infer all semantic dependencies.
61
+
62
+ ## Evidence freshness
63
+
64
+ Source scanning includes project files outside agents/, excluding dependency internals and declared output paths.
65
+ Referenced workflow contracts and selected skill resources are included explicitly.
66
+ Mutation locks serialize SDD operations; they do not stop another editor or process changing source.
67
+ Verification compares inputs before and after running checks. Changes during the run fail the receipt.
68
+ Closure recomputes the fingerprint and rechecks logs/artifacts. A current full passed or limited receipt is required.
69
+ Limited records implementation completion with explicit external deferrals, not external test success or deployment approval.
70
+ Only environment-dependent verification can be deferred. Required observed failures remain failures for the same inputs;
71
+ omitting evidence or skipping external execution cannot silently erase them. External commands are opt-in.
72
+ Required checks gate completion; advisory issues remain visible. Handoff JSON and generated user steps are hash-bound.
73
+
74
+ Generated outputs must be excluded deliberately when commands create them; an overbroad exclusion
75
+ can hide meaningful changes. The CLI does not claim cryptographic attestation against someone
76
+ who can edit both source and evidence. It prevents accidental stale reuse in the intended cooperative workflow.
77
+
78
+ ## Consolidation
79
+
80
+ Update current capability contracts before final verification and record the producing change ID.
81
+ Keep historical proposals, alternatives and execution logs in the change folder.
82
+ Closed changes can move to archive without changing identity.
83
+ Reopening preserves history and removes the current verification receipt; new verification is required.
84
+
85
+ ## Decisions
86
+
87
+ Use a maintained YAML parser rather than a partial parser based on regex or fixed excerpts.
88
+ The sole runtime dependency is yaml, pinned through package-lock.json.
89
+ Keep the core portable and expose native wrappers separately.
90
+ Do not ship regex-based shell hooks as a security boundary.
91
+ Conservative migration preserves original bodies and never invents approvals or test success.
@@ -0,0 +1,64 @@
1
+ # Adapters and distribution
2
+
3
+ ## Shared knowledge
4
+
5
+ Maintain the core procedures once under templates/agents/.
6
+ The adapters generate thin native commands and a workflow skill with shared references.
7
+ Exported bundles carry the MIT license and explicit prerequisites.
8
+
9
+ Skills use the public Agent Skills name/description format.
10
+ Other workflow front matter is internal metadata; arbitrary schema fields are not automatically
11
+ understood by Claude Code or OpenCode.
12
+
13
+ ## Local native entry points
14
+
15
+ ~~~sh
16
+ sdd harness claude-code
17
+ sdd harness opencode
18
+ ~~~
19
+
20
+ Claude Code: .claude/commands/sdd-*.md, .claude/skills/sdd-flow/ and a managed CLAUDE.md block.
21
+ OpenCode: .opencode/commands/sdd-*.md and .opencode/skills/sdd-flow/.
22
+ Slash commands: /sdd-research, /sdd-plan, /sdd-implement, /sdd-validate, /sdd-close.
23
+ Project-specific skills remain canonical in agents/skills/ and are discovered through sdd skills list;
24
+ the workflow skill directs the agent to load selected bodies.
25
+
26
+ Installations preserve unrelated command files and existing settings.
27
+ Removal is ownership-aware. These adapters install knowledge entry points, not a sandbox or permissions policy.
28
+ Use the tool's native controls to enforce execution permissions.
29
+
30
+ ## Export a directory
31
+
32
+ ~~~sh
33
+ sdd export claude-code --out packages/claude-code
34
+ sdd export opencode --out packages/opencode
35
+ sdd export agent-skills --out packages/portable
36
+ ~~~
37
+
38
+ The output directory must not exist. Export paths stay inside the project and cannot traverse symlinks.
39
+ Claude Code exports .claude-plugin/plugin.json and skills/sdd-flow/.
40
+ OpenCode exports .opencode/skills/sdd-flow/ for copying into a project.
41
+ Agent Skills exports skills/sdd-flow/ for clients that support that format.
42
+ All bundles require Node.js 22+ and a separately installed sdd-flow 2.x CLI.
43
+ No model, account, API credential or specific application stack is embedded.
44
+
45
+ For a local Claude Code smoke test, use the official --plugin-dir support with the exported directory
46
+ in an environment where Claude Code is installed. Export does not publish to a marketplace.
47
+ OpenCode JavaScript plugins have a separate runtime API; a portable knowledge skill should not
48
+ be described as a tested JavaScript plugin.
49
+
50
+ ## Compatibility evidence and release work
51
+
52
+ Automated tests verify generated layouts, front matter, references and preservation behavior.
53
+ A real interactive invocation in each target tool/version is still required before claiming
54
+ runtime compatibility for a release. Record versions and outcomes in the release checklist.
55
+
56
+ Public references consulted on 2026-11-20:
57
+ - https://agentskills.io/specification
58
+ - https://code.claude.com/docs/en/plugins-reference
59
+ - https://code.claude.com/docs/en/skills
60
+ - https://opencode.ai/docs/skills/
61
+ - https://opencode.ai/docs/commands/
62
+
63
+ Future marketplace packaging can reuse these exports and add marketplace metadata.
64
+ Publish versioned bundles and release notes; avoid maintaining divergent copies of the procedures.
@@ -0,0 +1,215 @@
1
+ # Formats and worked example
2
+
3
+ ## Metadata policy
4
+
5
+ Use YAML front matter for machine-consumed Markdown, and YAML for configuration/manifests.
6
+ Skills follow Agent Skills: name matches the directory, is lowercase kebab-case (1–64 characters),
7
+ and description explains the procedure and triggers (1–1024 characters).
8
+ Human-only README files do not need front matter.
9
+ General document metadata is an sdd-flow convention; clients do not automatically interpret arbitrary fields.
10
+
11
+ Optional config.yaml documentation.language is auto or a BCP 47 language tag such as pt-BR or en.
12
+ Existing configurations without this mapping use auto. It guides project-authored narrative; keys, IDs,
13
+ paths and original quotations remain stable. UTF-8 and normal spelling/diacritics are preserved.
14
+ Portuguese seed headings are generated for pt/pt-BR; other CLI seed headings use English as fallback.
15
+ See methodology.pt-BR.md for scope and localization limits.
16
+
17
+ The CLI parses YAML 1.2 with the yaml package. Duplicate keys, aliases, unsupported tags,
18
+ non-mapping roots and reserved prototype keys are rejected. Front matter must start at the file's
19
+ beginning (BOM/CRLF are accepted), close with a delimiter and stay under 64 KiB.
20
+
21
+ ## Project configuration
22
+
23
+ Optional reference scaffolding: init --docs creates prd.md, roadmap.md and architecture.md.
24
+ docs --types prd,sd,ds,adr,roadmap selects presets; --dry-run is read-only and existing files are preserved.
25
+ ADR templates are proposed rather than actual active decisions. No fixed reference-document set is required.
26
+
27
+ ~~~yaml
28
+ schema_version: 2
29
+ mode: standard
30
+ autonomy: step
31
+ approval: required
32
+ context:
33
+ max_bytes: 48000
34
+ checks:
35
+ - name: unit
36
+ command: node --test
37
+ timeout_ms: 60000
38
+ verification:
39
+ exclude: [coverage, dist]
40
+ ~~~
41
+
42
+ Check commands execute through the local shell using the current account.
43
+ Names are unique lowercase IDs. Timeouts are positive integers up to 3,600,000 ms.
44
+ Optional level is required (default) or advisory; environment is local (default) or external.
45
+ External commands are skipped unless --run-external is explicitly requested and authorized.
46
+ Optional quality.tdd is optional, preferred (default) or required; it guides the method rather than attesting test chronology.
47
+ QUALITY.md is project-owned, preserved by maintenance and read for planning/review.
48
+ Configure generated paths explicitly; do not exclude source or dependency manifests.
49
+ New installations use step as the standing default. Explicit user authorization for named tasks or
50
+ all tasks permits a bounded batch without changing configuration; plan approval alone does not.
51
+ Existing configured autonomy is preserved on update. Task checks and dependencies still apply in batches.
52
+ A timeout kills the spawned process group on POSIX. On Windows the CLI invokes taskkill.exe
53
+ for its spawned process tree, with shell-process termination as fallback. Use a controlled environment
54
+ when stronger process isolation is required.
55
+
56
+ ## Change manifest
57
+
58
+ Created by sdd new NAME:
59
+
60
+ ~~~yaml
61
+ schema_version: 2
62
+ id: 001-addition
63
+ title: Addition
64
+ mode: standard
65
+ status: draft
66
+ capabilities: []
67
+ decisions: []
68
+ skills: []
69
+ depends_on: []
70
+ context:
71
+ - path: src/math.js
72
+ sources: []
73
+ approval: null
74
+ ~~~
75
+
76
+ All paths are project-relative. Absolute paths, traversal and symbolic-link traversal are refused.
77
+ context also accepts {path: docs/domain.md, section: Exact heading}.
78
+ List relevant capabilities/decisions explicitly; they must have kind: capability/decision and status: active.
79
+ Dependencies reference full change IDs. Implementation/verification requires dependencies to be closed.
80
+ The approval command updates approval and ID history; do not fabricate those fields manually.
81
+
82
+ Lifecycle statuses: draft, implementing, implemented (limited verification), verified, closed, cancelled.
83
+ IDs remain reserved after archival through the durable project registry.
84
+ Store original requirement paths or {path: ..., section: Exact heading} references in sources. Research/plan context loads those sources/sections;
85
+ other phases may consult them on demand.
86
+
87
+ ## Normative specification
88
+
89
+ ~~~yaml
90
+ ---
91
+ schema_version: 2
92
+ artifact: spec
93
+ id: 001-addition
94
+ requirements:
95
+ - id: REQ01
96
+ description: Add two finite numbers and reject nonnumeric values.
97
+ acceptance:
98
+ - id: AC01
99
+ covers: [REQ01]
100
+ description: Adding 2 and 3 yields 5; a string input raises TypeError.
101
+ method: automated
102
+ checks: [unit]
103
+ ---
104
+ ~~~
105
+
106
+ Use REQ, BR or EB for requirement IDs, AC or TC for acceptance IDs.
107
+ Every active requirement needs acceptance coverage. Methods: automated, manual or inspection.
108
+ Automated criteria reference configured check names. A single check can cover several criteria;
109
+ the reviewer must inspect whether assertions actually establish the declared behavior.
110
+ Keep details and rationale in the Markdown body; do not duplicate task execution status there.
111
+
112
+ ## Canonical tasks
113
+
114
+ ~~~yaml
115
+ ---
116
+ schema_version: 2
117
+ artifact: tasks
118
+ id: 001-addition
119
+ tasks:
120
+ - id: T01
121
+ title: Implement addition and regression checks.
122
+ status: pending
123
+ covers: [REQ01, AC01]
124
+ depends_on: []
125
+ verify: The concrete success and rejection scenarios pass with the unit check.
126
+ ---
127
+ ~~~
128
+
129
+ Statuses: pending, in_progress, done, cancelled. Dependencies must be acyclic.
130
+ A started/done task requires completed dependencies. Task state changes do not invalidate scope approval;
131
+ changes to title, covers, depends_on, verify or normative body do.
132
+ Execution evidence may use the task evidence field without changing normative scope.
133
+ An external-only verification task may use kind: verification, status: deferred and deferral: {by: Name, reason: Explanation}.
134
+ It must cover external acceptance IDs, not replace unfinished implementation. Actual verification requires updating it to done.
135
+ Deferral execution metadata does not change the approved plan, but does bind the verification fingerprint.
136
+ Light changes may omit TASK.md. Standard/rigorous changes require at least one task.
137
+
138
+ To cancel an item, retain its ID and add status: cancelled and cancellation: {by: Name, reason: Explanation}.
139
+ Reassign or cancel dependent references consistently. No automatic code deletion is inferred.
140
+ IDs previously recorded by scope approval cannot disappear from a later revision.
141
+
142
+ ## Manual and inspection evidence
143
+
144
+ For each manual/inspection criterion, generate a current template:
145
+
146
+ ~~~sh
147
+ sdd evidence 001-addition
148
+ ~~~
149
+
150
+ The template contains schema_version, change ID, input_digest and cases.
151
+ Execute the scenario before setting a case to passed/failed:
152
+
153
+ ~~~json
154
+ {
155
+ "id": "AC02",
156
+ "result": "passed",
157
+ "by": "Moisés",
158
+ "at": "2026-11-20T16:00:00Z",
159
+ "notes": "Observed the expected result in the isolated test environment.",
160
+ "artifacts": []
161
+ }
162
+ ~~~
163
+
164
+ Allowed results: passed, failed, not_run, blocked. Executed results require actor, timestamp and notes.
165
+ Artifacts are project-relative regular files and are hashed. Do not record secrets.
166
+ Evidence must match the current input digest. Finish source changes and task status updates before generating it.
167
+ Store evidence under the spec folder so filling it does not itself change the application source fingerprint.
168
+ If EVIDENCE.json already exists, the default command returns a new revision-specific filename and preserves
169
+ the previous observations. Use that returned path with --evidence. An explicit --out never overwrites a file.
170
+
171
+ ~~~sh
172
+ sdd verify 001-addition --evidence agents/specs/001-addition/EVIDENCE.json
173
+ ~~~
174
+
175
+ Full success can close a manually tested project. Partial runs never close changes.
176
+ Verification receipts record check-to-criterion mappings, output logs and known limitations.
177
+
178
+ ## Current knowledge and decisions
179
+
180
+ ~~~yaml
181
+ ---
182
+ schema_version: 2
183
+ kind: capability
184
+ id: arithmetic
185
+ description: Arithmetic operations and input validation.
186
+ status: active
187
+ changes: [001-addition]
188
+ ---
189
+ ~~~
190
+
191
+ Maintain the current behavior and source links in the body. Add the change ID before final verification.
192
+ Decisions use kind: decision, status: active or superseded, and superseded_by when replaced.
193
+ Select the active ADR paths; do not load an entire global append-only decision log every session.
194
+
195
+ ## Research
196
+
197
+ Rigorous mode requires RESEARCH.md with schema_version: 2, artifact: research and the matching id.
198
+ Document source evidence, decisions, risks and resolved questions in its body.
199
+ Research is optional for other modes. It does not replace the authoritative sources.
200
+
201
+ ## Project policies, revision and history
202
+
203
+ POLICIES.md contains mandatory project-specific constraints and is preserved by updates.
204
+ Scope approval binds these policies, check commands and verification exclusions in addition to the plan.
205
+ It also binds QUALITY.md and quality settings. Advisory checks cannot be the evidence for required acceptance.
206
+ Context budgets are diagnostic settings and do not change scope approval by themselves.
207
+
208
+ Each approval retains a normative snapshot in history/approval-*.json. Editing a rule or policy
209
+ does not rewrite that prior snapshot. Use sdd revise ID --by NAME --reason TEXT --dry-run to inspect
210
+ affected task states, then record the revision and authorize the new scope.
211
+ Requirement/acceptance links determine local impact; policy, prose or reference changes may reopen all tasks.
212
+ Dependent tasks are reopened transitively. The agent must still review semantic impact and update tests.
213
+
214
+ Each verification run retains runs/RUN_ID/receipt.json alongside its logs; verification.json is the current view.
215
+ These historical records are not loaded automatically into context.
@@ -0,0 +1,196 @@
1
+ # Testes locais antes de publicar
2
+
3
+ Este roteiro testa o código-fonte da versão 2.x deste checkout, sem depender do pacote publicado no npm.
4
+ Exemplos: PowerShell no Windows. Requer Git e Node.js 22+; Node 24 pode ser usado para validar.
5
+ Mantenha os laboratórios fora da pasta do framework. Use cópia/branch para aplicações reais.
6
+
7
+ ## 1. Validar o pacote
8
+
9
+ Abra a pasta do checkout que contém package.json:
10
+
11
+ ~~~powershell
12
+ node --version
13
+ npm --version
14
+ npm ci
15
+ npm test
16
+ npm run check
17
+ npm audit
18
+ npm publish --dry-run --tag next
19
+ ~~~
20
+
21
+ O último comando não publica. Ele exercita prepublishOnly, que executa testes e checks.
22
+ O teste de empacotamento instala o tarball em um consumidor temporário e executa o CLI instalado.
23
+ Ele usa cache temporário vazio e tarball local do parser já instalado, evitando depender de metadados prévios do npm.
24
+ Não é necessário npm login para testar o código. O aviso de falta de login no dry-run é esperado.
25
+ Investigue falhas; erro de rede no audit não significa resultado de segurança aprovado.
26
+ npm run test:coverage fornece cobertura, não uma nota de qualidade.
27
+ Confira também o CI e os harnesses/versões que pretende anunciar.
28
+
29
+ ## 2. Laboratório sem trocar o CLI global
30
+
31
+ Na pasta do código-fonte:
32
+
33
+ ~~~powershell
34
+ $SddSource = (Get-Location).Path
35
+ $SddCli = Join-Path $SddSource 'bin/cli.js'
36
+ $SddLab = Join-Path ([System.IO.Path]::GetTempPath()) ('sdd-flow-laboratorio-' + [guid]::NewGuid().ToString('N'))
37
+ New-Item -ItemType Directory -Path $SddLab | Out-Null
38
+ Set-Location $SddLab
39
+ git init
40
+ node $SddCli --version
41
+ node $SddCli init
42
+ ~~~
43
+
44
+ node $SddCli equivale a sdd, mas aponta exatamente para o código baixado.
45
+ Para o agente executar sdd diretamente, instale o tarball conforme a seção 7,
46
+ ou indique a ele o caminho absoluto deste CLI. Evite executar a versão pública 1.3.3 por engano.
47
+
48
+ Configure agents/config.yaml preservando os demais campos:
49
+
50
+ ~~~yaml
51
+ documentation:
52
+ language: pt-BR
53
+ checks:
54
+ - name: unit
55
+ command: node --test
56
+ timeout_ms: 10000
57
+ ~~~
58
+
59
+ Esse check é para o exemplo Node abaixo. Em outra tecnologia, use seus comandos reais.
60
+ Exclua apenas saídas geradas quando necessário, sem excluir código ou testes da verificação.
61
+
62
+ Para exercitar os documentos opcionais depois de definir o idioma:
63
+
64
+ ~~~powershell
65
+ node $SddCli docs --types prd,sd,ds,adr,roadmap --dry-run
66
+ node $SddCli docs --types prd,sd,ds,adr,roadmap
67
+ ~~~
68
+
69
+ Confira os rascunhos em docs/, acrescente uma regra real ao PRD e repita o comando.
70
+ A regra deve ser preservada. O template ADR deve continuar proposed até existir uma decisão real.
71
+ Não é necessário preencher todos os modelos para continuar; selecione apenas os úteis ao laboratório.
72
+ Veja setup-documents.pt-BR.md para distinguir referências de produto e artefatos de cada mudança.
73
+
74
+ ## 3. Uma entrega real com o agente
75
+
76
+ Ative o ponto de entrada do harness escolhido, quando aplicável:
77
+
78
+ ~~~powershell
79
+ node $SddCli harness claude-code
80
+ # Alternativa: node $SddCli harness opencode
81
+ ~~~
82
+
83
+ Em outro harness, aponte para AGENTS.md e agents/prompts/.
84
+ Adaptadores não instalam o aplicativo, concedem acesso ou modificam permissões.
85
+
86
+ Pedido inicial sugerido:
87
+
88
+ ~~~text
89
+ Leia agents/SETUP.md e configure este projeto de laboratório.
90
+ Vamos criar uma biblioteca Node.js pequena, sem dependências externas.
91
+ Escreva os documentos do projeto em português brasileiro, em UTF-8, com acentos.
92
+ Registre apenas escolhas conhecidas. Nesta etapa configure o fluxo, sem implementar.
93
+ Use o CLI 2.x que indiquei; não execute a versão pública 1.3.3 por engano.
94
+ ~~~
95
+
96
+ Depois peça:
97
+
98
+ ~~~text
99
+ Planeje uma spec standard para calcularFrete(valorCentavos).
100
+ Aceite apenas inteiros não negativos. A partir de 5000 centavos, o frete é 0;
101
+ abaixo disso, é 990. Entradas inválidas devem lançar erro.
102
+ Inclua aceitação para 0, 4999, 5000, valores negativos, fracionários e não numéricos.
103
+ Não implemente antes de apresentar o plano.
104
+ ~~~
105
+
106
+ Revise valores, limites e comportamento inválido. Autorize o plano real quando correto.
107
+ Depois peça código/testes, checks reais, consolidação do contrato, verificação e encerramento.
108
+ Não informe que houve autorização antes de concedê-la.
109
+
110
+ Se registrar a aprovação pelo terminal, use o ID realmente criado:
111
+
112
+ ~~~powershell
113
+ node $SddCli check 001-calcular-frete
114
+ node $SddCli approve 001-calcular-frete --by 'Moisés'
115
+ node $SddCli context 001-calcular-frete --phase implement --task T01 --inspect
116
+ ~~~
117
+
118
+ IDs são exemplos; use os do seu laboratório. Não marque tarefas como done apenas para passar o verificador.
119
+
120
+ ## 4. Cenários de aceitação do workflow
121
+
122
+ | Cenário | Ação | Resultado esperado |
123
+ |---|---|---|
124
+ | Início do zero | Complete a entrega acima | Contrato, tarefas, testes reais, evidência e encerramento coerentes |
125
+ | Reinstalação | Rode init após configurar PROJECT/POLICIES/config e concluir setup | Arquivos próprios preservados; SETUP removido não reaparece |
126
+ | Conflito no núcleo | Em uma cópia, personalize RULES e rode update --dry-run | Conflito informado; conteúdo preservado até revisão explícita |
127
+ | Projeto existente | Adote uma cópia de um aplicativo funcional | Baseline observada, sem refatoração ou specs fictícias do passado |
128
+ | Regra alterada | Durante uma spec ativa aprovada, mude o limite para 7000 e revise o plano | Aprovação obsoleta, motivo registrado e tarefas afetadas reabertas |
129
+ | Falha real | Quebre um teste numa spec ativa | Verificação falha; o resultado antigo não permite encerrar |
130
+ | Validação parcial | Verifique antes de concluir as tarefas | Resultado parcial/pending honesto, sem encerramento |
131
+ | Teste manual | Use uma spec light para observação com interação real | Evidência com executor, resultado e fingerprint pode passar após execução |
132
+ | Retomada | Continue em outra sessão ou após compactação | Recupera objetivo, regra, tarefa e próxima ação pelos arquivos |
133
+ | Contexto excessivo | Inspecione referências grandes; teste --max-bytes 1024 | Diagnóstico sem truncamento; contexto pertinente permite continuar |
134
+ | Idioma | Use “autorização”, “revisão” e “não numérico” | UTF-8 preservado; texto em português; chaves/IDs estáveis |
135
+ | Sem ambiente real | Classifique o teste externo, prepare handoff e gere o roteiro seguro | Pode fechar implementação como limited, mantendo acceptance_verified false e testes pendentes |
136
+ | Indicador informativo | Configure uma análise advisory que falha, mantendo testes funcionais válidos | Aviso registrado, sem declarar falha funcional nem esconder o indicador |
137
+ | Falha externa observada | Execute um teste externo autorizado que falha; depois omita essa execução | A falha nos mesmos inputs permanece; não vira deferred para permitir fechamento |
138
+ | Efeito em consumidor | Altere uma função compartilhada mantendo seu teste isolado verde, mas quebrando um cenário do consumidor | O teste de regressão do consumidor detecta a falha e impede declarar o gate aprovado |
139
+
140
+ Use outra spec para objetivo novo depois do encerramento.
141
+ Para revisão na mesma spec, altere antes de encerrar ou reabra explicitamente com motivo.
142
+ Uma falha provocada nessa matriz é resultado esperado do controle, não defeito do framework.
143
+
144
+ ## 5. Conferir rastreabilidade
145
+
146
+ - SPEC.md: requisitos e aceitação correspondem ao pedido e aos casos de borda.
147
+ - TASK.md: tarefas por resultado; uma única fonte do estado.
148
+ - history/approval-*.json: escopos aprovados preservados.
149
+ - history/revision-*.json: motivo e impacto das alterações.
150
+ - runs/ID/receipt.json e logs: comandos e resultados de execuções reais.
151
+ - verification.json: resultado corrente vinculado aos inputs verificados.
152
+ - current/: comportamento consolidado sem depender de todas as specs antigas.
153
+ - archive/: preservação de artefatos e IDs.
154
+
155
+ Evidência manual não pode transformar leitura de código em alegação de execução.
156
+ Confira as assertions: um comando verde sozinho não prova cobertura de negócio.
157
+
158
+ ## 6. Registrar a avaliação do agente
159
+
160
+ Registre fora do snapshot verificado da aplicação, em sua issue/PR ou notas de avaliação:
161
+
162
+ | Campo | O que anotar |
163
+ |---|---|
164
+ | Ambiente | OS, Node/CLI/harness, modelo e modo |
165
+ | Caso | Laboratório e commit/base |
166
+ | Correção | Requisitos omitidos, testes ausentes e resultados incorretos |
167
+ | Contexto | Documentos selecionados, conteúdo irrelevante e facilidade de retomada |
168
+ | Intervenção | Correções e confirmações desnecessárias pedidas ao desenvolvedor |
169
+ | Rastreabilidade | Se outra pessoa entende escopo, revisão e execução pelos registros |
170
+ | Eficiência | Tempo/custo, comparando tarefas e condições equivalentes |
171
+
172
+ Repita um caso em outro harness se pretende anunciar compatibilidade.
173
+ Sem esse ambiente, registre a lacuna. Corrija falhas de instalação antes de avaliar o método.
174
+
175
+ ## 7. Testar o tarball
176
+
177
+ Volte à pasta do framework:
178
+
179
+ ~~~powershell
180
+ Set-Location $SddSource
181
+ npm pack
182
+ ~~~
183
+
184
+ Se quiser trocar a instalação global, em outro terminal instale o caminho exato do tarball:
185
+
186
+ ~~~powershell
187
+ npm pack
188
+ npm install -g '.\sdd-flow-<versão>.tgz'
189
+ sdd --version
190
+ ~~~
191
+
192
+ Confira Get-Command sdd e repita init/context no laboratório.
193
+ Para restaurar uma versão global anterior, instale explicitamente aquela versão.
194
+ Para testar o pacote já publicado, use sdd-flow@next (ou sdd-flow, quando a 2.x for latest).
195
+
196
+ Após os testes, siga releases.pt-BR.md para publicar uma nova versão.