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,101 +1,109 @@
1
- # Implementation validation
2
-
3
- Date: 2026-11-20. Source baseline: d84c62d51d9c566b0f3e8a6279418220e0fc6e8f (1.3.3).
4
- Results below were observed while preparing 2.0.0 and re-run (88 tests, package check, audit) for 2.0.1.
5
- 2.0.0 and 2.0.1 are published to npm under the `next` dist-tag first; `latest` is promoted manually.
6
- No marketplace release was published.
7
-
8
- ## Observed automated results
9
-
10
- | Environment/check | Result |
11
- |---|---|
12
- | Linux, Node.js 24.22.3 | 88 tests passed |
13
- | Linux, Node.js 22.23.5 | 88 tests passed |
14
- | Package syntax/template/export contracts | Passed |
15
- | Real npm tarball installed in a separate temporary consumer | Passed on both tested Node versions |
16
- | CLI initialization from a path containing spaces | Passed |
17
- | Dependency audit | 0 reported vulnerabilities for the installed runtime dependency set |
18
- | Diff whitespace validation | Passed |
19
- | npm publication dry run (no registry write) | Passed |
20
- | Exact version/channel and public-registry availability preflight | Passed for 2.0.0 with next |
21
-
22
- The automated suite exercises actual passing/failing test processes, stale scope/evidence,
23
- partial verification, manual/inspection closure, preservation/conflict handling,
24
- cancelled history, archival/reopen, timeout behavior, YAML errors, restricted paths,
25
- native layouts and conservative migration. Assertions check outcomes rather than only file existence.
26
-
27
- Additional scenarios cover context-size diagnostics without exposing document bodies, explicit source
28
- sections, local business-rule revisions and dependent-task reopening, project-policy changes,
29
- preserved approval snapshots and run receipts, release-channel checks and fail-closed registry errors.
30
- The package includes the Portuguese usage/release guides and project-policy/intake templates.
31
- Additional language/reinitialization tests cover optional legacy configuration, locale validation,
32
- UTF-8/Portuguese accents in generated artifacts and context, stable machine IDs, and preservation
33
- of a configured project without requesting a removed setup guide. Portuguese methodology,
34
- local testing and GitHub publication instructions are included in the source/package.
35
-
36
- Quality/environment scenarios additionally verify required versus advisory checks, opt-in external
37
- execution, honest limited closure, deferred verification tasks, safe handoff validation, stale/tampered
38
- instructions, preservation of known failures, reopening with actual observations and per-run user-guide history.
39
- Limited implementation completion is explicitly distinct from fully verified acceptance and deployment approval.
40
-
41
- New adoption/regression scenarios start from a plain user goal without PRD/ADR, preserve existing
42
- application code/product documents on installation and catch an actual consumer regression while
43
- the edited function's isolated unit test remains green.
44
- The installed-package test now uses a fresh temporary npm cache and a local tarball of the installed
45
- parser, removing its accidental dependency on warmed registry metadata after an environment restart.
46
-
47
- Optional document scaffolding is exercised both from source and the installed tarball: the legacy
48
- PRD/roadmap/system-design set, selected design-system/ADR drafts, proposed decision metadata,
49
- Portuguese accents, preservation of existing content, read-only previews and preflight path collisions.
50
-
51
- Installation assertions also verify the new step default and preservation of an existing batch choice
52
- across reinitialization and updates. Multi-task authorization is a procedure followed by the agent;
53
- the CLI does not inspect a conversation or certify that the agent actually stopped between tasks.
54
-
55
- ## Advisory code metrics
56
-
57
- Node.js 24 test coverage reported 94.17% lines, 81.16% branches and 94.15% functions in its instrumented
58
- report (CLI, lib, release-check and test-support). This is not application acceptance coverage;
59
- child-process instrumentation and the included helper files limit interpretation of the aggregate.
60
-
61
- ESLint 10.15.0 cyclomatic complexity analysis, using a diagnostic warning threshold of 20, identified
62
- maintenance hotspots in validation, revision, context composition and command dispatch.
63
- These findings remain advisory; no universal threshold is imposed on consumer projects or used
64
- to claim that all quality metrics passed. Broad mechanical refactoring was outside this functional change.
65
-
66
- ## Independent workflow exercises
67
-
68
- An independent agent followed the generated workflow skill in isolated projects:
69
-
70
- 1. A standard JavaScript addition module: 11 success/rejection regression tests,
71
- one observed manual acceptance case, current capability consolidation, full verification,
72
- archival, reopening and rejection of immediate reclosure without a new receipt.
73
- 2. A light manual-only change with no task file or test framework: actual manual evidence,
74
- approved-requirement revision, stale authorization/evidence rejection, reauthorization,
75
- revised verification and archival.
76
- 3. Existing team instructions, native settings and unrelated commands survived installation.
77
- Customized workflow/native files were preserved; explicit replacement created backups.
78
- All three exported layouts included their license and referenced resources.
79
-
80
- The exercises exposed a setup-removal contradiction and evidence-regeneration friction.
81
- Both were corrected and covered by regression tests.
82
- Tests also detected inherited node:test context suppressing nested tests and environment warnings
83
- interfering with JSON error parsing; the runner and machine-output channel were corrected.
84
- The full publication dry run also exposed inherited npm dry-run configuration preventing the
85
- tarball smoke test from creating its temporary artifact; the test explicitly isolates that flag.
86
-
87
- ## Limits and pending release checks
88
-
89
- - Windows execution is configured in CI but was not run in this Linux workspace.
90
- - The npm registry still reports 1.3.3 as latest. No authenticated npm publisher was available locally.
91
- - GitHub integration rejected repository writes with HTTP 403; no remote PR or CI run was created.
92
- - Trusted publishing must be configured by the package owner before the manual release workflow can publish.
93
- - Claude Code and OpenCode applications were not installed. Layouts and metadata were tested;
94
- interactive tool-version compatibility remains a release check.
95
- - No comparative model benchmark against other frameworks was performed.
96
- - Manual evidence and approvals are recorded assertions, not authenticated attestations.
97
- - Configured commands use the current account permissions. Native permissions and environment
98
- isolation remain necessary; the CLI is not a sandbox.
99
- - Passing a configured command does not prove semantic coverage of every linked acceptance criterion.
100
-
101
- Use docs/quality.md to repeat checks and record future release evidence.
1
+ # Implementation validation
2
+
3
+ Date: 2026-11-20. Current source baseline: f209b37850634c34379898f83fff039ba267342f (published 2.0.1).
4
+ This release is 2.1.0. No marketplace release was published.
5
+ Earlier 2.0 development results are retained where labeled historical; current automated results follow.
6
+
7
+ ## Observed automated results
8
+
9
+ | Environment/check | Result |
10
+ |---|---|
11
+ | Linux, Node.js 24.22.3 | 114 tests passed |
12
+ | Linux, Node.js 22.23.5 | 114 tests passed |
13
+ | Package syntax/template/export contracts | Passed |
14
+ | Real npm tarball installed in a separate temporary consumer | Passed on both tested Node versions |
15
+ | CLI initialization from a path containing spaces | Passed |
16
+ | Dependency audit | 0 reported vulnerabilities for the installed runtime dependency set |
17
+ | Diff whitespace validation | Passed |
18
+ | npm publication dry run (no registry write) | Passed |
19
+ | Exact version/channel and public-registry availability preflight | Passed for 2.1.0 with next |
20
+
21
+ The automated suite exercises actual passing/failing test processes, stale scope/evidence,
22
+ partial verification, manual/inspection closure, preservation/conflict handling,
23
+ cancelled history, archival/reopen, timeout behavior, YAML errors, restricted paths,
24
+ native layouts and conservative migration. Assertions check outcomes rather than only file existence.
25
+
26
+ Additional scenarios cover context-size diagnostics without exposing document bodies, explicit source
27
+ sections, local business-rule revisions and dependent-task reopening, project-policy changes,
28
+ preserved approval snapshots and run receipts, release-channel checks and fail-closed registry errors.
29
+ The package includes the Portuguese usage/release guides and project-policy/intake templates.
30
+ Additional language/reinitialization tests cover optional legacy configuration, locale validation,
31
+ UTF-8/Portuguese accents in generated artifacts and context, stable machine IDs, and preservation
32
+ of a configured project without requesting a removed setup guide. Portuguese methodology,
33
+ local testing and GitHub publication instructions are included in the source/package.
34
+
35
+ Quality/environment scenarios additionally verify required versus advisory checks, opt-in external
36
+ execution, honest limited closure, deferred verification tasks, safe handoff validation, stale/tampered
37
+ instructions, preservation of known failures, reopening with actual observations and per-run user-guide history.
38
+ Limited implementation completion is explicitly distinct from fully verified acceptance and deployment approval.
39
+
40
+ New adoption/regression scenarios start from a plain user goal without PRD/ADR, preserve existing
41
+ application code/product documents on installation and catch an actual consumer regression while
42
+ the edited function's isolated unit test remains green.
43
+ The installed-package test now uses a fresh temporary npm cache and a local tarball of the installed
44
+ parser, removing its accidental dependency on warmed registry metadata after an environment restart.
45
+
46
+ Optional document scaffolding is exercised both from source and the installed tarball: the legacy
47
+ PRD/roadmap/system-design set, selected design-system/ADR drafts, proposed decision metadata,
48
+ Portuguese accents, preservation of existing content, read-only previews and preflight path collisions.
49
+
50
+ Installation assertions also verify the new step default and preservation of an existing batch choice
51
+ across reinitialization and updates. Multi-task authorization is a procedure followed by the agent;
52
+ the CLI does not inspect a conversation or certify that the agent actually stopped between tasks.
53
+
54
+ Spec-management regression scenarios cover stable identities after rename/renumber, manual folder moves,
55
+ scope and receipt preservation, archive/restore independent of closure, recoverable and permanent removal,
56
+ retained closure summaries, manual deletion, unfinished/missing prerequisites, optional historical references,
57
+ required-source failures, ambiguous aliases, malformed unrelated manifests and legacy ID-only registries.
58
+ Failure-injection tests exercise move rollback and interrupted permanent deletion. Manual evidence,
59
+ artifacts and external handoff/guide hashes remain usable after cosmetic moves; failures never become passes.
60
+ The installed-tarball smoke test exercises rename/archive/restore/remove, not only source-level APIs.
61
+
62
+ ## Advisory code metrics
63
+
64
+ Node.js 24 test coverage reported 95.34% lines, 83.67% branches and 95.12% functions in its instrumented
65
+ report (CLI, lib, release-check and test-support). This is not application acceptance coverage;
66
+ child-process instrumentation and the included helper files limit interpretation of the aggregate.
67
+
68
+ ESLint 10.15.0 cyclomatic complexity analysis, using a diagnostic warning threshold of 20, identified
69
+ maintenance hotspots in validation, revision, context composition and command dispatch.
70
+ The repeated analysis recorded 16 advisory warnings and no lint errors; new catalog/management
71
+ branches also exceed that diagnostic threshold. These are maintenance findings, not a claim of uniformly low complexity.
72
+ These findings remain advisory; no universal threshold is imposed on consumer projects or used
73
+ to claim that all quality metrics passed. Broad mechanical refactoring was outside this functional change.
74
+
75
+ ## Independent workflow exercises
76
+
77
+ An independent agent followed the generated workflow skill in isolated projects:
78
+
79
+ 1. A standard JavaScript addition module: 11 success/rejection regression tests,
80
+ one observed manual acceptance case, current capability consolidation, full verification,
81
+ archival, reopening and rejection of immediate reclosure without a new receipt.
82
+ 2. A light manual-only change with no task file or test framework: actual manual evidence,
83
+ approved-requirement revision, stale authorization/evidence rejection, reauthorization,
84
+ revised verification and archival.
85
+ 3. Existing team instructions, native settings and unrelated commands survived installation.
86
+ Customized workflow/native files were preserved; explicit replacement created backups.
87
+ All three exported layouts included their license and referenced resources.
88
+
89
+ The exercises exposed a setup-removal contradiction and evidence-regeneration friction.
90
+ Both were corrected and covered by regression tests.
91
+ Tests also detected inherited node:test context suppressing nested tests and environment warnings
92
+ interfering with JSON error parsing; the runner and machine-output channel were corrected.
93
+ The full publication dry run also exposed inherited npm dry-run configuration preventing the
94
+ tarball smoke test from creating its temporary artifact; the test explicitly isolates that flag.
95
+
96
+ ## Limits and pending release checks
97
+
98
+ - CI runs ubuntu and windows on Node.js 22 and 24; the 2.1.0 commit passed all four jobs before publication.
99
+ - Releases are published manually from a maintainer terminal (no provenance attestation) or by the OIDC workflow.
100
+ - Trusted publishing must be configured by the package owner before the manual release workflow can publish.
101
+ - Claude Code and OpenCode applications were not installed. Layouts and metadata were tested;
102
+ interactive tool-version compatibility remains a release check.
103
+ - No comparative model benchmark against other frameworks was performed.
104
+ - Manual evidence and approvals are recorded assertions, not authenticated attestations.
105
+ - Configured commands use the current account permissions. Native permissions and environment
106
+ isolation remain necessary; the CLI is not a sandbox.
107
+ - Passing a configured command does not prove semantic coverage of every linked acceptance criterion.
108
+
109
+ Use docs/quality.md to repeat checks and record future release evidence.
package/lib/catalog.js ADDED
@@ -0,0 +1,162 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+ const io = require('./io');
6
+ const md = require('./markdown');
7
+
8
+ const REGISTRY = 'agents/.sdd/registry.json';
9
+ const ID = /^\d+-[a-z0-9]+(?:-[a-z0-9]+)*$/;
10
+ const AREAS = ['agents/specs', 'agents/archive'];
11
+ const TRASH = 'agents/.sdd/trash';
12
+ const selectorName = value => typeof value === 'string' && value.length > 0 && value.length <= 255 && !/[\\/\0]/.test(value) && !['.', '..'].includes(value);
13
+
14
+ function registry(root) {
15
+ const value = io.exists(root, REGISTRY) ? io.json(root, REGISTRY) : { ids: [], records: {} };
16
+ if (!Array.isArray(value.ids) || value.ids.some(id => !ID.test(id)) ||
17
+ (value.records !== undefined && (!value.records || typeof value.records !== 'object' || Array.isArray(value.records)))) {
18
+ throw new Error('Invalid SDD registry');
19
+ }
20
+ value.records ||= {};
21
+ for (const [id, record] of Object.entries(value.records)) {
22
+ if (!ID.test(id) || !record || typeof record !== 'object') throw new Error('Invalid SDD registry record');
23
+ for (const file of [record.path, record.restore_path].filter(Boolean)) {
24
+ io.resolve(root, file);
25
+ if (![...AREAS, TRASH].some(parent => file.startsWith(parent + '/') && !file.slice(parent.length + 1).includes('/'))) {
26
+ throw new Error('Invalid SDD registry location: ' + file);
27
+ }
28
+ }
29
+ if (record.aliases !== undefined && (!Array.isArray(record.aliases) || record.aliases.some(name => !selectorName(name)))) {
30
+ throw new Error('Invalid SDD registry aliases');
31
+ }
32
+ }
33
+ return value;
34
+ }
35
+
36
+ function list(root, { includeTrash = false, issues = [] } = {}) {
37
+ const result = [];
38
+ const records = registry(root).records;
39
+ for (const parent of [...AREAS, ...(includeTrash ? [TRASH] : [])]) {
40
+ if (!io.exists(root, parent)) continue;
41
+ for (const item of fs.readdirSync(io.resolve(root, parent), { withFileTypes: true })) {
42
+ if (item.name.startsWith('_') || item.name.startsWith('.')) continue;
43
+ if (item.isSymbolicLink()) throw new Error('Symbolic links are not followed: ' + parent + '/' + item.name);
44
+ if (!item.isDirectory()) continue;
45
+ const relative = parent + '/' + item.name;
46
+ let id = item.name;
47
+ let invalid;
48
+ const file = relative + '/change.yaml';
49
+ try {
50
+ if (io.exists(root, file)) {
51
+ const change = md.parseYaml(io.read(root, file), file);
52
+ if (change.schema_version !== 2 || !ID.test(change.id)) throw new Error(file + ': invalid schema_version or id');
53
+ id = change.id;
54
+ } else {
55
+ const previous = Object.entries(records).find(([, record]) => record.path === relative);
56
+ if (previous && previous[1].status !== 'legacy') throw new Error(file + ': recorded spec is missing its manifest; restore or repair this file');
57
+ if (!ID.test(id)) continue;
58
+ }
59
+ } catch (error) {
60
+ invalid = error.message;
61
+ id = Object.entries(records).find(([, record]) => record.path === relative)?.[0] || (ID.test(item.name) ? item.name : null);
62
+ issues.push({ path: relative, kind: 'invalid-manifest', remedy: error.message });
63
+ if (!id) continue;
64
+ }
65
+ result.push({ id, relative, name: item.name, ...(invalid && { invalid }), location: parent === AREAS[0] ? 'active' : parent === AREAS[1] ? 'archive' : 'trash' });
66
+ }
67
+ }
68
+ return result;
69
+ }
70
+
71
+ function locate(root, selector, options) {
72
+ if (!selectorName(selector)) throw new Error('Expected a spec ID or folder name');
73
+ const inventory = registry(root);
74
+ const matches = list(root, options).filter(spec => {
75
+ const record = inventory.records[spec.id];
76
+ if (inventory.ids.includes(selector) && selector !== spec.id) return false;
77
+ return spec.id === selector || spec.name === selector ||
78
+ record?.aliases?.includes(selector) ||
79
+ (/^\d+$/.test(selector) && [spec.id, spec.name].some(name => name.split('-')[0] === selector));
80
+ });
81
+ if (matches.length !== 1) {
82
+ const error = new Error(matches.length ? 'Ambiguous spec ID or folder name: ' + selector
83
+ : 'Spec not found: ' + selector + '. Run sdd reconcile --dry-run to inspect missing or moved specs.');
84
+ error.code = matches.length ? 'SPEC_AMBIGUOUS' : 'SPEC_NOT_FOUND';
85
+ throw error;
86
+ }
87
+ if (matches[0].invalid) throw new Error(matches[0].invalid);
88
+ return matches[0];
89
+ }
90
+
91
+ function remember(root, spec, extra = {}) {
92
+ const value = registry(root);
93
+ const previous = value.records[spec.id] || {};
94
+ const aliases = [...new Set([...(previous.aliases || []), previous.path && path.posix.basename(previous.path),
95
+ ...(!spec.relative.startsWith(TRASH + '/') ? [path.posix.basename(spec.relative)] : [])].filter(Boolean))];
96
+ const closure = spec.change?.closure;
97
+ value.records[spec.id] = {
98
+ ...previous, path: spec.relative, status: spec.change?.status || 'legacy',
99
+ availability: spec.relative.startsWith(TRASH + '/') ? 'trash' : 'present',
100
+ aliases, capabilities: spec.change?.capabilities || [],
101
+ ...(closure && { closure: Object.fromEntries(['at', 'run_id', 'validation', 'acceptance_verified', 'outcome'].map(key => [key, closure[key] ?? null])) }),
102
+ observed_at: new Date().toISOString(), ...extra,
103
+ };
104
+ value.ids = [...new Set([...value.ids, spec.id])].sort();
105
+ io.writeJson(root, REGISTRY, value);
106
+ return value.records[spec.id];
107
+ }
108
+
109
+ function referencePath(root, file) {
110
+ io.resolve(root, file);
111
+ const match = file.match(/^agents\/(?:specs|archive)\/([^/]+)\/(.+)$/);
112
+ if (!match) return file;
113
+ try {
114
+ const spec = locate(root, match[1]);
115
+ return spec.relative + '/' + match[2];
116
+ } catch (error) {
117
+ if (error.code === 'SPEC_NOT_FOUND') {
118
+ const manifest = file.slice(0, file.length - match[2].length) + 'change.yaml';
119
+ if (io.exists(root, file) && io.exists(root, manifest)) throw new Error('Reference folder conflicts with a reserved spec identity: ' + file);
120
+ return file;
121
+ }
122
+ throw error;
123
+ }
124
+ }
125
+
126
+ function historical(ref) {
127
+ return typeof ref === 'object' && ref !== null && ref.historical === true;
128
+ }
129
+
130
+ function reference(root, ref) {
131
+ const declared = typeof ref === 'string' ? ref : ref?.path;
132
+ if (typeof ref !== 'string' && (!ref || typeof ref !== 'object' || Array.isArray(ref) ||
133
+ (ref.historical !== undefined && typeof ref.historical !== 'boolean'))) throw new Error('Invalid context/source reference');
134
+ const file = referencePath(root, declared);
135
+ if (!io.exists(root, file) && historical(ref)) return { path: file, declared, missing: true };
136
+ const doc = md.load(root, file, false);
137
+ if (typeof ref === 'object' && ref.section) md.section(doc.body, ref.section, file);
138
+ return { path: file, declared, missing: false };
139
+ }
140
+
141
+ function dependency(root, id) {
142
+ if (!ID.test(id)) throw new Error('Dependency must use a stable full spec ID: ' + id);
143
+ const matches = list(root).filter(spec => spec.id === id);
144
+ if (matches.length > 1) throw new Error('Ambiguous spec identity: ' + id);
145
+ if (matches.length) {
146
+ const location = matches[0];
147
+ if (location.invalid) throw new Error(location.invalid);
148
+ const file = location.relative + '/change.yaml';
149
+ if (!io.exists(root, file)) return { ...location, legacy: true };
150
+ return { ...location, change: md.parseYaml(io.read(root, file), file), legacy: false, retained: false };
151
+ } else {
152
+ const record = registry(root).records[id];
153
+ if (record?.status === 'closed' && record.closure) {
154
+ return { id, retained: true, legacy: false, change: {
155
+ id, status: 'closed', depends_on: [], capabilities: record.capabilities || [], closure: record.closure,
156
+ } };
157
+ }
158
+ return { id, missing: true, previous_status: record?.status || null };
159
+ }
160
+ }
161
+
162
+ module.exports = { REGISTRY, ID, AREAS, TRASH, registry, list, locate, remember, referencePath, reference, historical, dependency };
package/lib/check.js CHANGED
@@ -4,6 +4,7 @@ const io = require('./io');
4
4
  const md = require('./markdown');
5
5
  const project = require('./project');
6
6
  const quality = require('./quality');
7
+ const catalog = require('./catalog');
7
8
 
8
9
  function check(root, id, { phase = 'plan', final = false } = {}) {
9
10
  const errors = [];
@@ -28,21 +29,20 @@ function check(root, id, { phase = 'plan', final = false } = {}) {
28
29
  if (new Set(change[field].map(x => JSON.stringify(x))).size !== change[field].length) fail('Duplicate change.' + field + ' entry');
29
30
  }
30
31
  for (const ref of [...change.capabilities, ...change.decisions]) {
31
- md.load(root, ref, false);
32
+ md.load(root, catalog.referencePath(root, ref), false);
32
33
  }
33
34
  for (const ref of [...change.context, ...change.sources]) {
34
- const file = typeof ref === 'string' ? ref : ref?.path;
35
- const document = md.load(root, file, false);
36
- if (typeof ref === 'object' && ref.section) md.section(document.body, ref.section, file);
35
+ const document = catalog.reference(root, ref);
36
+ if (document.missing) warnings.push('Historical reference is unavailable: ' + document.declared);
37
37
  }
38
38
  for (const [field, kind] of [['capabilities', 'capability'], ['decisions', 'decision']]) {
39
39
  for (const file of change[field]) {
40
- const { data } = md.load(root, file);
40
+ const { data } = md.load(root, catalog.referencePath(root, file));
41
41
  if (data.kind !== kind || data.status !== 'active') fail(file + ': expected active ' + kind);
42
42
  }
43
43
  }
44
- const catalog = project.skills(root);
45
- for (const name of change.skills) if (!catalog.some(s => s.name === name)) fail('Unknown skill: ' + name);
44
+ const skillCatalog = project.skills(root);
45
+ for (const name of change.skills) if (!skillCatalog.some(s => s.name === name)) fail('Unknown skill: ' + name);
46
46
  specification = md.load(root, spec.relative + '/SPEC.md');
47
47
  const data = specification.data;
48
48
  if (data.schema_version !== 2 || data.artifact !== 'spec' || data.id !== spec.id) fail('SPEC.md metadata does not match this spec');
@@ -149,6 +149,13 @@ function check(root, id, { phase = 'plan', final = false } = {}) {
149
149
  const research = md.load(root, spec.relative + '/RESEARCH.md');
150
150
  if (research.data.schema_version !== 2 || research.data.artifact !== 'research' || research.data.id !== spec.id || !research.body.trim()) fail('Rigorous mode requires reviewed RESEARCH.md with matching metadata');
151
151
  }
152
+ if (change.related !== undefined && (!Array.isArray(change.related) || change.related.some(item => typeof item !== 'string' || !catalog.ID.test(item)))) fail('change.related must contain historical spec IDs');
153
+ else for (const related of change.related || []) {
154
+ try {
155
+ const target = catalog.dependency(root, related);
156
+ if (target.missing || target.retained) warnings.push('Historical spec content is unavailable: ' + related);
157
+ } catch (error) { warnings.push('Historical spec cannot be consulted: ' + related + '; ' + error.message); }
158
+ }
152
159
  const graph = [];
153
160
  const visiting = new Set();
154
161
  function dependencies(current) {
@@ -156,12 +163,19 @@ function check(root, id, { phase = 'plan', final = false } = {}) {
156
163
  visiting.add(current.id);
157
164
  graph.push([current.id, current.change.depends_on]);
158
165
  for (const dependency of current.change.depends_on) {
159
- const target = project.loadSpec(root, dependency);
166
+ const target = catalog.dependency(root, dependency);
167
+ if (target.missing) {
168
+ const message = 'Unresolved dependency: ' + dependency + '. Inspect current contracts/code/tests, restore its source, or revise this prerequisite; no need to recreate this spec. Use sdd reconcile --dry-run.';
169
+ if (['implement', 'validate', 'close'].includes(phase)) fail(message);
170
+ else warnings.push(message);
171
+ continue;
172
+ }
160
173
  if (target.legacy) { fail('Dependency needs migration: ' + dependency); continue; }
161
174
  if (!Array.isArray(target.change.depends_on)) throw new Error('Invalid dependency manifest: ' + dependency);
162
175
  if (['implement', 'validate', 'close'].includes(phase) && target.change.status !== 'closed') fail('Dependency is not closed: ' + dependency);
163
176
  if (target.change.closure?.validation === 'limited') warnings.push('Dependency has pending external verification: ' + dependency);
164
- dependencies(target);
177
+ if (target.retained) warnings.push('Dependency uses a retained historical closure, not fresh acceptance evidence: ' + dependency);
178
+ if (target.change.status !== 'closed') dependencies(target);
165
179
  }
166
180
  }
167
181
  dependencies(spec);
@@ -170,6 +184,7 @@ function check(root, id, { phase = 'plan', final = false } = {}) {
170
184
  fail('Scope approval is missing or stale. Review the plan and record the user authorization with sdd approve ' + spec.id + ' --by NAME');
171
185
  }
172
186
  if (['implement', 'validate'].includes(phase) && ['closed', 'cancelled'].includes(change.status)) fail('Change is ' + change.status + '; reopen it before further implementation or verification');
187
+ if (['implement', 'validate'].includes(phase) && spec.location !== 'active') fail('Spec is archived; run sdd restore before implementation or verification');
173
188
  if (!change.capabilities.length) warnings.push('No lasting capability document selected; close will require an explicit consolidation note');
174
189
  return { valid: !errors.length, errors, warnings, spec, specification, tasks };
175
190
  } catch (error) {
@@ -203,6 +218,7 @@ function approve(root, id, by) {
203
218
  const result = requireValid(check(root, id));
204
219
  const { spec, specification, tasks } = result;
205
220
  if (['closed', 'cancelled'].includes(spec.change.status)) throw new Error('Reopen this change before approving it');
221
+ if (spec.location !== 'active') throw new Error('Restore an archived spec before approving it');
206
222
  const previous = spec.change.id_ledger || {};
207
223
  spec.change.id_ledger = Object.fromEntries(['requirements', 'acceptance', 'tasks'].map(field => {
208
224
  const current = field === 'tasks' ? tasks : specification.data[field];