sdd-flow 2.0.1 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/formats.md CHANGED
@@ -1,215 +1,221 @@
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.
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 manifest ID remains stable when the folder is renamed or renumbered; lookup accepts its current folder name too.
81
+ Optional related lists historical spec IDs without requiring their content or loading them into context.
82
+ Source/context objects may use historical: true for nonessential provenance; missing historical files warn.
83
+ Missing required sources still fail. Missing unfinished dependencies warn in plan and block execution until reviewed;
84
+ a retained recorded closure can satisfy a discarded historical dependency, with explicit warnings and fresh consumer checks.
85
+ Use management commands and reconcile; see spec-management.pt-BR.md for retention and recovery limits.
86
+ The approval command updates approval and ID history; do not fabricate those fields manually.
87
+
88
+ Lifecycle statuses: draft, implementing, implemented (limited verification), verified, closed, cancelled.
89
+ IDs remain reserved after archival through the durable project registry.
90
+ Store original requirement paths or {path: ..., section: Exact heading} references in sources. Research/plan context loads those sources/sections;
91
+ other phases may consult them on demand.
92
+
93
+ ## Normative specification
94
+
95
+ ~~~yaml
96
+ ---
97
+ schema_version: 2
98
+ artifact: spec
99
+ id: 001-addition
100
+ requirements:
101
+ - id: REQ01
102
+ description: Add two finite numbers and reject nonnumeric values.
103
+ acceptance:
104
+ - id: AC01
105
+ covers: [REQ01]
106
+ description: Adding 2 and 3 yields 5; a string input raises TypeError.
107
+ method: automated
108
+ checks: [unit]
109
+ ---
110
+ ~~~
111
+
112
+ Use REQ, BR or EB for requirement IDs, AC or TC for acceptance IDs.
113
+ Every active requirement needs acceptance coverage. Methods: automated, manual or inspection.
114
+ Automated criteria reference configured check names. A single check can cover several criteria;
115
+ the reviewer must inspect whether assertions actually establish the declared behavior.
116
+ Keep details and rationale in the Markdown body; do not duplicate task execution status there.
117
+
118
+ ## Canonical tasks
119
+
120
+ ~~~yaml
121
+ ---
122
+ schema_version: 2
123
+ artifact: tasks
124
+ id: 001-addition
125
+ tasks:
126
+ - id: T01
127
+ title: Implement addition and regression checks.
128
+ status: pending
129
+ covers: [REQ01, AC01]
130
+ depends_on: []
131
+ verify: The concrete success and rejection scenarios pass with the unit check.
132
+ ---
133
+ ~~~
134
+
135
+ Statuses: pending, in_progress, done, cancelled. Dependencies must be acyclic.
136
+ A started/done task requires completed dependencies. Task state changes do not invalidate scope approval;
137
+ changes to title, covers, depends_on, verify or normative body do.
138
+ Execution evidence may use the task evidence field without changing normative scope.
139
+ An external-only verification task may use kind: verification, status: deferred and deferral: {by: Name, reason: Explanation}.
140
+ It must cover external acceptance IDs, not replace unfinished implementation. Actual verification requires updating it to done.
141
+ Deferral execution metadata does not change the approved plan, but does bind the verification fingerprint.
142
+ Light changes may omit TASK.md. Standard/rigorous changes require at least one task.
143
+
144
+ To cancel an item, retain its ID and add status: cancelled and cancellation: {by: Name, reason: Explanation}.
145
+ Reassign or cancel dependent references consistently. No automatic code deletion is inferred.
146
+ IDs previously recorded by scope approval cannot disappear from a later revision.
147
+
148
+ ## Manual and inspection evidence
149
+
150
+ For each manual/inspection criterion, generate a current template:
151
+
152
+ ~~~sh
153
+ sdd evidence 001-addition
154
+ ~~~
155
+
156
+ The template contains schema_version, change ID, input_digest and cases.
157
+ Execute the scenario before setting a case to passed/failed:
158
+
159
+ ~~~json
160
+ {
161
+ "id": "AC02",
162
+ "result": "passed",
163
+ "by": "Moisés",
164
+ "at": "2026-11-20T16:00:00Z",
165
+ "notes": "Observed the expected result in the isolated test environment.",
166
+ "artifacts": []
167
+ }
168
+ ~~~
169
+
170
+ Allowed results: passed, failed, not_run, blocked. Executed results require actor, timestamp and notes.
171
+ Artifacts are project-relative regular files and are hashed. Do not record secrets.
172
+ Evidence must match the current input digest. Finish source changes and task status updates before generating it.
173
+ Store evidence under the spec folder so filling it does not itself change the application source fingerprint.
174
+ If EVIDENCE.json already exists, the default command returns a new revision-specific filename and preserves
175
+ the previous observations. Use that returned path with --evidence. An explicit --out never overwrites a file.
176
+
177
+ ~~~sh
178
+ sdd verify 001-addition --evidence agents/specs/001-addition/EVIDENCE.json
179
+ ~~~
180
+
181
+ Full success can close a manually tested project. Partial runs never close changes.
182
+ Verification receipts record check-to-criterion mappings, output logs and known limitations.
183
+
184
+ ## Current knowledge and decisions
185
+
186
+ ~~~yaml
187
+ ---
188
+ schema_version: 2
189
+ kind: capability
190
+ id: arithmetic
191
+ description: Arithmetic operations and input validation.
192
+ status: active
193
+ changes: [001-addition]
194
+ ---
195
+ ~~~
196
+
197
+ Maintain the current behavior and source links in the body. Add the change ID before final verification.
198
+ Decisions use kind: decision, status: active or superseded, and superseded_by when replaced.
199
+ Select the active ADR paths; do not load an entire global append-only decision log every session.
200
+
201
+ ## Research
202
+
203
+ Rigorous mode requires RESEARCH.md with schema_version: 2, artifact: research and the matching id.
204
+ Document source evidence, decisions, risks and resolved questions in its body.
205
+ Research is optional for other modes. It does not replace the authoritative sources.
206
+
207
+ ## Project policies, revision and history
208
+
209
+ POLICIES.md contains mandatory project-specific constraints and is preserved by updates.
210
+ Scope approval binds these policies, check commands and verification exclusions in addition to the plan.
211
+ It also binds QUALITY.md and quality settings. Advisory checks cannot be the evidence for required acceptance.
212
+ Context budgets are diagnostic settings and do not change scope approval by themselves.
213
+
214
+ Each approval retains a normative snapshot in history/approval-*.json. Editing a rule or policy
215
+ does not rewrite that prior snapshot. Use sdd revise ID --by NAME --reason TEXT --dry-run to inspect
216
+ affected task states, then record the revision and authorize the new scope.
217
+ Requirement/acceptance links determine local impact; policy, prose or reference changes may reopen all tasks.
218
+ Dependent tasks are reopened transitively. The agent must still review semantic impact and update tests.
219
+
220
+ Each verification run retains runs/RUN_ID/receipt.json alongside its logs; verification.json is the current view.
221
+ These historical records are not loaded automatically into context.