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.
@@ -1,91 +1,98 @@
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.
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/catalog.js | Stable manifest identities, folder/alias resolution and compact retained closure records |
14
+ | lib/management.js | Rename, archive, restore, discard, impact previews and observed-inventory reconciliation |
15
+ | lib/check.js | Structural contracts, coverage references, cycles and approval checks |
16
+ | lib/context.js | Phase/task context composition with provenance and a byte budget |
17
+ | lib/verification.js | Command runs, observed evidence, receipts and closure |
18
+ | lib/history.js / lib/revisions.js | Immutable event/scope snapshots and explicit change-impact revisions |
19
+ | lib/quality.js / lib/handoff.js | Check policy, environment limitations and version-bound user-test instructions |
20
+ | lib/install.js | Ownership-aware updates, diagnostics and conservative migration |
21
+ | lib/documents.js | Optional reference-document drafts; preserve existing sources and require no fixed document set |
22
+ | lib/adapters.js | Native wrappers and export layouts from shared workflow knowledge |
23
+ | bin/cli.js | Arguments, orchestration, output and exit codes |
24
+
25
+ ## Context selection
26
+
27
+ The initial entry point is a short map. Core constraints, project-specific mandatory policies, project map and the current phase
28
+ form the base packet. The active task selects its requirement/acceptance metadata.
29
+ The specification body remains available because scope constraints in prose must not be silently lost.
30
+ Selected current capability contracts and ADRs are loaded with provenance.
31
+ Only explicit skill selections load bodies; the catalog carries descriptions without bodies.
32
+ Sources/research are included during research/plan and remain available on demand otherwise.
33
+
34
+ Large documents can be selected by an exact ATX heading. Heading extraction ignores fenced code;
35
+ it ends at the next heading of equal or higher level. The packet fails on overflow and reports file sizes.
36
+ It measures UTF-8 bytes rather than estimating model tokens. The default budget is a project setting,
37
+ not a universal optimum.
38
+ Use --inspect to get sizes/remedies without emitting bodies. Generating an over-budget packet raises
39
+ CONTEXT_BUDGET_EXCEEDED; this is a recoverable selection checkpoint, not a failure of the application.
40
+ The framework cannot intercept arbitrary chat input; intake guidance handles broad requests at the agent level.
41
+
42
+ No vector database or model API is required. The agent can inspect additional code and sources
43
+ when needed, explaining the relevance. Selection completeness still depends on the project map
44
+ and declared relationships; scripts cannot infer every domain dependency.
45
+
46
+ Optional documentation.language selects the project-artifact language (auto when absent).
47
+ The context header carries the language and UTF-8 encoding. Distributed procedures remain English;
48
+ agents preserve the project's spelling and diacritics while keeping machine keys/IDs stable.
49
+ This is guidance plus locale validation, not linguistic certification or full CLI localization.
50
+
51
+ ## Three distinct states
52
+
53
+ Scope authorization binds the normative specification, task plan, selected references, project policies and verification/execution policy.
54
+ Routine task status/evidence updates do not require reapproving an unchanged plan.
55
+ Execution state is canonical in TASK.md. Optional STATE.md summarizes only the next step and blockers.
56
+ Verification binds source bytes, selected workflow contracts, configuration and task states.
57
+
58
+ Approval is a recorded assertion of actual user authorization, not authenticated identity.
59
+ Changing its by field is not a security boundary. Tool permission enforcement belongs to the agent runtime.
60
+ Prior scope snapshots are preserved separately. Explicit revisions compare structured requirements,
61
+ acceptance and task links, reopen impacted tasks/dependents, and conservatively reopen all for broad policy/prose changes.
62
+ This comparison supports impact review; it does not infer all semantic dependencies.
63
+
64
+ ## Evidence freshness
65
+
66
+ Source scanning includes project files outside agents/, excluding dependency internals and declared output paths.
67
+ Referenced workflow contracts and selected skill resources are included explicitly.
68
+ Mutation locks serialize SDD operations; they do not stop another editor or process changing source.
69
+ Verification compares inputs before and after running checks. Changes during the run fail the receipt.
70
+ Closure recomputes the fingerprint and rechecks logs/artifacts. A current full passed or limited receipt is required.
71
+ Limited records implementation completion with explicit external deferrals, not external test success or deployment approval.
72
+ Only environment-dependent verification can be deferred. Required observed failures remain failures for the same inputs;
73
+ omitting evidence or skipping external execution cannot silently erase them. External commands are opt-in.
74
+ Required checks gate completion; advisory issues remain visible. Handoff JSON and generated user steps are hash-bound.
75
+
76
+ Generated outputs must be excluded deliberately when commands create them; an overbroad exclusion
77
+ can hide meaningful changes. The CLI does not claim cryptographic attestation against someone
78
+ who can edit both source and evidence. It prevents accidental stale reuse in the intended cooperative workflow.
79
+
80
+ ## Consolidation
81
+
82
+ Update current capability contracts before final verification and record the producing change ID.
83
+ Keep historical proposals, alternatives and execution logs in the change folder.
84
+ Closed changes can move to archive without changing identity.
85
+ Folder names and visual numbers are independent of manifest ID. Management moves preserve normative scope and receipts;
86
+ structural reference paths resolve through live identities/known aliases without rewriting historical bytes.
87
+ Missing historical sources may warn, while required contracts and unresolved execution prerequisites remain actionable.
88
+ Recorded closure summaries can outlive discarded spec content; they are historical facts, not fresh verification.
89
+ Reconcile records observed inventory only. It does not manufacture a missing closure, alter scope or infer business correctness.
90
+ Reopening preserves history and removes the current verification receipt; new verification is required.
91
+
92
+ ## Decisions
93
+
94
+ Use a maintained YAML parser rather than a partial parser based on regex or fixed excerpts.
95
+ The sole runtime dependency is yaml, pinned through package-lock.json.
96
+ Keep the core portable and expose native wrappers separately.
97
+ Do not ship regex-based shell hooks as a security boundary.
98
+ Conservative migration preserves original bodies and never invents approvals or test success.