framework-aidf 0.0.0-stage → 0.2.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.
Files changed (154) hide show
  1. package/CHANGELOG.md +174 -0
  2. package/INSTALLATION.md +140 -0
  3. package/LICENSE +21 -0
  4. package/QODER.md +88 -0
  5. package/README.md +142 -2
  6. package/UTILISATION.md +188 -0
  7. package/assets/adapters/qoder/agents/aidf-orchestrator.md +30 -0
  8. package/assets/adapters/qoder/rules/00-core.md +28 -0
  9. package/assets/adapters/qoder/rules/10-security.md +33 -0
  10. package/assets/adapters/qoder/rules/20-context.md +39 -0
  11. package/assets/core/AGENTS.fragment.md +18 -0
  12. package/assets/core/AIDF.md +107 -0
  13. package/assets/docs/APPFLOW.md +66 -0
  14. package/assets/docs/BACKEND.md +71 -0
  15. package/assets/docs/CHANGELOG.md +25 -0
  16. package/assets/docs/CONVENTIONS.md +95 -0
  17. package/assets/docs/DECISIONS.md +60 -0
  18. package/assets/docs/PLAN.md +53 -0
  19. package/assets/docs/PRD.md +88 -0
  20. package/assets/docs/SECURITY.md +94 -0
  21. package/assets/docs/TRD.md +78 -0
  22. package/assets/docs/UI-UX.md +71 -0
  23. package/assets/docs/constitution.md +86 -0
  24. package/assets/hooks/audit.mjs +45 -0
  25. package/assets/hooks/session-context.mjs +53 -0
  26. package/assets/integrations/spec-kit/mapping.yaml +92 -0
  27. package/assets/knowledge/best-practices/testing.md +53 -0
  28. package/assets/knowledge/best-practices/web-dev-baseline.md +39 -0
  29. package/assets/knowledge/rules/api.md +45 -0
  30. package/assets/knowledge/rules/sql.md +44 -0
  31. package/assets/knowledge/rules/typescript.md +50 -0
  32. package/assets/knowledge/security-references/owasp-baseline.md +58 -0
  33. package/assets/registry/activation-map.yaml +83 -0
  34. package/assets/registry/dependencies.yaml +35 -0
  35. package/assets/registry/skills.yaml +541 -0
  36. package/assets/registry/sources.yaml +396 -0
  37. package/assets/schemas/architecture/v1.json +110 -0
  38. package/assets/schemas/constraints/v1.json +93 -0
  39. package/assets/schemas/decision/v1.json +106 -0
  40. package/assets/schemas/discovery/v1.json +91 -0
  41. package/assets/schemas/requirement/v1.json +136 -0
  42. package/assets/schemas/security/threat-model/v1.json +127 -0
  43. package/assets/schemas/test-plan/v1.json +108 -0
  44. package/assets/skills/aidf-architecture-review/SKILL.md +49 -0
  45. package/assets/skills/aidf-backend-implementation/SKILL.md +47 -0
  46. package/assets/skills/aidf-database-design/SKILL.md +48 -0
  47. package/assets/skills/aidf-devops-engineering/SKILL.md +41 -0
  48. package/assets/skills/aidf-documentation-maintenance/SKILL.md +41 -0
  49. package/assets/skills/aidf-frontend-implementation/SKILL.md +44 -0
  50. package/assets/skills/aidf-phase-transition/SKILL.md +48 -0
  51. package/assets/skills/aidf-product-analysis/SKILL.md +47 -0
  52. package/assets/skills/aidf-project-context/SKILL.md +57 -0
  53. package/assets/skills/aidf-requirements-engineering/SKILL.md +52 -0
  54. package/assets/skills/aidf-security-review/SKILL.md +57 -0
  55. package/assets/skills/aidf-testing-validation/SKILL.md +48 -0
  56. package/assets/skills/aidf-ui-ux-implementation/SKILL.md +43 -0
  57. package/assets/workflows/gates.yaml +232 -0
  58. package/assets/workflows/phases.yaml +161 -0
  59. package/bin/aidf.mjs +12 -0
  60. package/demo/run-demo.mjs +97 -0
  61. package/docs/aidf/ADR-001-artefacts-architectur.md +126 -0
  62. package/docs/aidf/ADR-002-requirements-registry.md +145 -0
  63. package/docs/aidf/ADR-003-traceability-chain.md +145 -0
  64. package/docs/aidf/ADR-004-markdown-generation.md +134 -0
  65. package/docs/aidf/ADR-005-validation-and-tests.md +170 -0
  66. package/docs/aidf/ADR-006-cli-commands.md +189 -0
  67. package/docs/aidf/ADR-007-compatibility-and-migration.md +119 -0
  68. package/docs/aidf/ADR-008-schema-versioning.md +115 -0
  69. package/docs/aidf/ADR-009-artefacts-scope.md +84 -0
  70. package/docs/aidf/ARCHITECTURE.md +137 -0
  71. package/docs/aidf/COMPATIBILITY.md +90 -0
  72. package/docs/aidf/DECISIONS.md +200 -0
  73. package/docs/aidf/FRAMEWORK.md +38 -0
  74. package/docs/aidf/IDE-QODER.md +61 -0
  75. package/docs/aidf/INSTALL.md +99 -0
  76. package/docs/aidf/INVENTORY.md +72 -0
  77. package/docs/aidf/L1-ARCHITECTURE-RAPPORT.md +353 -0
  78. package/docs/aidf/LIMITATIONS.md +69 -0
  79. package/docs/aidf/MATRICE-0.1.0-vers-0.2.0.md +155 -0
  80. package/docs/aidf/SECURITY.md +86 -0
  81. package/docs/aidf/SKILLS.md +78 -0
  82. package/docs/aidf/SPECKIT.md +67 -0
  83. package/docs/aidf/USAGE.md +113 -0
  84. package/docs/aidf/VALIDATION.md +55 -0
  85. package/package.json +37 -4
  86. package/src/cli.mjs +148 -0
  87. package/src/commands/artefacts.mjs +129 -0
  88. package/src/commands/config.mjs +130 -0
  89. package/src/commands/context.mjs +55 -0
  90. package/src/commands/decision.mjs +142 -0
  91. package/src/commands/design.mjs +141 -0
  92. package/src/commands/docs.mjs +133 -0
  93. package/src/commands/doctor.mjs +210 -0
  94. package/src/commands/evidence.mjs +178 -0
  95. package/src/commands/install.mjs +154 -0
  96. package/src/commands/release.mjs +214 -0
  97. package/src/commands/requirements.mjs +196 -0
  98. package/src/commands/resources.mjs +181 -0
  99. package/src/commands/scan.mjs +139 -0
  100. package/src/commands/security.mjs +97 -0
  101. package/src/commands/setup.mjs +68 -0
  102. package/src/commands/skills.mjs +204 -0
  103. package/src/commands/speckit.mjs +78 -0
  104. package/src/commands/tests.mjs +81 -0
  105. package/src/commands/traceability.mjs +116 -0
  106. package/src/commands/uninstall.mjs +238 -0
  107. package/src/commands/validate.mjs +84 -0
  108. package/src/commands/workflow.mjs +137 -0
  109. package/src/core/adapters/base.mjs +32 -0
  110. package/src/core/adapters/generic.mjs +70 -0
  111. package/src/core/adapters/index.mjs +24 -0
  112. package/src/core/adapters/opencode.mjs +115 -0
  113. package/src/core/adapters/qoder.mjs +228 -0
  114. package/src/core/artefacts/index.mjs +1 -0
  115. package/src/core/artefacts/validation.mjs +161 -0
  116. package/src/core/bootstrap.mjs +179 -0
  117. package/src/core/config.mjs +123 -0
  118. package/src/core/context.mjs +187 -0
  119. package/src/core/design-engineering/complexity-classifier.mjs +78 -0
  120. package/src/core/design-engineering/engine.mjs +197 -0
  121. package/src/core/design-engineering/fallback/mockups.mjs +221 -0
  122. package/src/core/design-engineering/fallback/wireframes.mjs +114 -0
  123. package/src/core/design-engineering/figma/validators.mjs +178 -0
  124. package/src/core/design-engineering/index.mjs +9 -0
  125. package/src/core/design-engineering/visual-parity/capture.mjs +172 -0
  126. package/src/core/detect.mjs +220 -0
  127. package/src/core/docsgen.mjs +175 -0
  128. package/src/core/evidence.mjs +210 -0
  129. package/src/core/installer.mjs +377 -0
  130. package/src/core/manifest.mjs +53 -0
  131. package/src/core/paths.mjs +94 -0
  132. package/src/core/requirements/index.mjs +13 -0
  133. package/src/core/requirements/registry.mjs +234 -0
  134. package/src/core/resource-inventory.mjs +434 -0
  135. package/src/core/resources.mjs +280 -0
  136. package/src/core/security/threat-model.mjs +235 -0
  137. package/src/core/skills.mjs +353 -0
  138. package/src/core/source-skills.mjs +213 -0
  139. package/src/core/speckit.mjs +195 -0
  140. package/src/core/technology-decision/analyzer-deterministic.mjs +240 -0
  141. package/src/core/technology-decision/engine.mjs +157 -0
  142. package/src/core/technology-decision/generator.mjs +204 -0
  143. package/src/core/technology-decision/index.mjs +17 -0
  144. package/src/core/technology-decision/options/index.mjs +10 -0
  145. package/src/core/testplan.mjs +176 -0
  146. package/src/core/traceability/chain.mjs +488 -0
  147. package/src/core/traceability/index.mjs +12 -0
  148. package/src/core/workflow.mjs +471 -0
  149. package/src/util/args.mjs +69 -0
  150. package/src/util/frontmatter.mjs +26 -0
  151. package/src/util/fsx.mjs +208 -0
  152. package/src/util/logger.mjs +74 -0
  153. package/src/util/text.mjs +66 -0
  154. package/src/util/yaml.mjs +379 -0
@@ -0,0 +1,24 @@
1
+ import { QoderAdapter } from './qoder.mjs';
2
+ import { GenericAdapter } from './generic.mjs';
3
+ import { OpenCodeAdapter } from './opencode.mjs';
4
+
5
+ const FACTORIES = {
6
+ qoder: () => new QoderAdapter(),
7
+ generic: () => new GenericAdapter(),
8
+ opencode: () => new OpenCodeAdapter(),
9
+ };
10
+
11
+ export const ADAPTER_KEYS = Object.keys(FACTORIES);
12
+
13
+ export function getAdapter(key) {
14
+ const factory = FACTORIES[key];
15
+ if (!factory) throw new Error(`Unknown adapter "${key}". Available: ${ADAPTER_KEYS.join(', ')}`);
16
+ return factory();
17
+ }
18
+
19
+ export function listAdapters() {
20
+ return ADAPTER_KEYS.map((key) => {
21
+ const adapter = getAdapter(key);
22
+ return { key, name: adapter.name, capabilities: adapter.capabilities };
23
+ });
24
+ }
@@ -0,0 +1,115 @@
1
+ import path from 'node:path';
2
+ import { Adapter } from './base.mjs';
3
+ import { readText, exists } from '../../util/fsx.mjs';
4
+ import { loadSkillCatalog } from '../skills.mjs';
5
+
6
+ /**
7
+ * OpenCode adapter.
8
+ *
9
+ * Verified against https://opencode.ai/docs/skills/: OpenCode discovers
10
+ * skills in `.opencode/skills/<id>/SKILL.md` (project scope) and reads
11
+ * AGENTS.md as the instruction file. This adapter writes exactly those two
12
+ * surfaces and does not claim runtime activation: only a real OpenCode session
13
+ * can prove that a skill is loaded.
14
+ */
15
+ export class OpenCodeAdapter extends Adapter {
16
+ constructor() {
17
+ super({
18
+ key: 'opencode',
19
+ name: 'OpenCode',
20
+ capabilities: ['agents-md', 'skills'],
21
+ });
22
+ }
23
+
24
+ async detect(env) {
25
+ return {
26
+ installed: Boolean(env?.ide?.opencode?.installed),
27
+ home: env?.ide?.opencode?.home ?? null,
28
+ capabilities: {
29
+ agentsMd: true,
30
+ rules: false,
31
+ skills: true,
32
+ hooks: false,
33
+ customAgents: false,
34
+ mcp: false,
35
+ plugins: false,
36
+ },
37
+ limitations: [
38
+ 'OpenCode skill discovery is file-based; AIDF can write .opencode/skills/<id>/SKILL.md but cannot prove the running session advertised it.',
39
+ 'AGENTS.md is loaded as instructions; runtime compliance is not observable from the filesystem.',
40
+ 'Verified 2026-11-21: OpenCode only discovers project skills when the project root is a git worktree (a .git entry). Without it, .opencode/skills/* is silently ignored.',
41
+ ],
42
+ };
43
+ }
44
+
45
+ async plan(context) {
46
+ const { frameworkRoot } = context;
47
+ const actions = [];
48
+ const fragment = await readText(path.join(frameworkRoot, 'assets', 'core', 'AGENTS.fragment.md'));
49
+ actions.push({
50
+ kind: 'managed-block',
51
+ path: 'AGENTS.md',
52
+ blockId: 'default',
53
+ content: fragment,
54
+ category: 'instructions',
55
+ });
56
+
57
+ const catalog = await loadSkillCatalog(frameworkRoot);
58
+ for (const skill of catalog) {
59
+ actions.push({
60
+ kind: 'write',
61
+ path: path.posix.join('.opencode', 'skills', skill.name, 'SKILL.md'),
62
+ content: await readText(path.join(frameworkRoot, 'assets', 'skills', skill.name, 'SKILL.md')),
63
+ category: 'skills',
64
+ });
65
+ }
66
+ return actions;
67
+ }
68
+
69
+ async verify(context) {
70
+ const { root, frameworkRoot } = context;
71
+ const checks = [];
72
+ const agents = path.join(root, 'AGENTS.md');
73
+ const agentsText = (await exists(agents)) ? await readText(agents) : '';
74
+ const agentsOk = agentsText.includes('<!-- AIDF:BEGIN');
75
+ checks.push({
76
+ id: 'agents-md-block',
77
+ status: agentsOk ? 'PASS' : 'FAIL',
78
+ evidence: 'AGENTS.md managed block present',
79
+ });
80
+
81
+ const catalog = await loadSkillCatalog(frameworkRoot);
82
+ let installed = 0;
83
+ for (const skill of catalog) {
84
+ if (await exists(path.join(root, '.opencode', 'skills', skill.name, 'SKILL.md'))) installed += 1;
85
+ }
86
+ checks.push({
87
+ id: 'skill-files',
88
+ status: installed === catalog.length ? 'PASS' : installed === 0 ? 'FAIL' : 'PARTIAL',
89
+ evidence: `${installed}/${catalog.length} built-in SKILL.md files present`,
90
+ });
91
+ const isGitWorktree = await exists(path.join(root, '.git'));
92
+ checks.push({
93
+ id: 'git-worktree',
94
+ status: isGitWorktree ? 'PASS' : 'PARTIAL',
95
+ evidence: isGitWorktree
96
+ ? 'Project is a git worktree; OpenCode can discover project skills.'
97
+ : 'No .git entry: OpenCode ignores .opencode/skills/* outside a git worktree (verified 2026-11-21). Run git init or use another adapter.',
98
+ });
99
+ checks.push({
100
+ id: 'runtime-skill-discovery',
101
+ status: 'NOT_PROVEN',
102
+ evidence: 'Requires a real OpenCode session that lists or invokes an AIDF skill.',
103
+ });
104
+
105
+ const failed = checks.some((c) => c.status === 'FAIL');
106
+ const partial = checks.some((c) => c.status === 'PARTIAL');
107
+ return {
108
+ status: failed ? 'FAIL' : partial ? 'PARTIAL' : 'CONTRACT-PROVEN',
109
+ checks,
110
+ limitations: [
111
+ 'Runtime discovery is NOT_PROVEN until an OpenCode session invokes an AIDF skill.',
112
+ ],
113
+ };
114
+ }
115
+ }
@@ -0,0 +1,228 @@
1
+ import path from 'node:path';
2
+ import { Adapter } from './base.mjs';
3
+ import { readText, exists } from '../../util/fsx.mjs';
4
+ import { validateSkillContent, loadSkillCatalog } from '../skills.mjs';
5
+
6
+ export class QoderAdapter extends Adapter {
7
+ constructor() {
8
+ super({
9
+ key: 'qoder',
10
+ name: 'Qoder IDE',
11
+ capabilities: ['agents-md', 'rules', 'skills', 'hooks', 'custom-agents'],
12
+ });
13
+ }
14
+
15
+ async detect(env) {
16
+ return {
17
+ installed: Boolean(env?.ide?.qoder?.installed),
18
+ home: env?.ide?.qoder?.home ?? null,
19
+ capabilities: {
20
+ agentsMd: true,
21
+ rules: true,
22
+ skills: true,
23
+ hooks: true,
24
+ customAgents: true,
25
+ mcp: true,
26
+ plugins: true,
27
+ },
28
+ limitations: [
29
+ 'Rule activation type (Always Apply / Model Decision / Specific Files / Apply Manually) is set in the Qoder UI; AIDF can create rule files but cannot prove their activation from the filesystem.',
30
+ 'Skill and rule runtime discovery must be confirmed in a Qoder session (e.g. /skills).',
31
+ 'Qoder IDE documentation and Qoder CLI documentation differ on precedence when a skill exists at both user and project level; AIDF does not rely on that precedence.',
32
+ ],
33
+ };
34
+ }
35
+
36
+ async plan(context) {
37
+ const { frameworkRoot, withHooks } = context;
38
+ const actions = [];
39
+ const assets = path.join(frameworkRoot, 'assets');
40
+
41
+ const fragment = await readText(path.join(assets, 'core', 'AGENTS.fragment.md'));
42
+ actions.push({
43
+ kind: 'managed-block',
44
+ path: 'AGENTS.md',
45
+ blockId: 'default',
46
+ content: fragment,
47
+ category: 'instructions',
48
+ });
49
+
50
+ for (const rule of ['00-core.md', '10-security.md', '20-context.md']) {
51
+ actions.push({
52
+ kind: 'write',
53
+ path: path.posix.join('.qoder', 'rules', `aidf-${rule}`),
54
+ content: await readText(path.join(assets, 'adapters', 'qoder', 'rules', rule)),
55
+ category: 'ide-rules',
56
+ });
57
+ }
58
+
59
+ const catalog = await loadSkillCatalog(frameworkRoot);
60
+ for (const skill of catalog) {
61
+ actions.push({
62
+ kind: 'write',
63
+ path: path.posix.join('.qoder', 'skills', skill.name, 'SKILL.md'),
64
+ content: await readText(path.join(assets, 'skills', skill.name, 'SKILL.md')),
65
+ category: 'skills',
66
+ });
67
+ }
68
+
69
+ actions.push({
70
+ kind: 'write',
71
+ path: path.posix.join('.qoder', 'agents', 'aidf-orchestrator.md'),
72
+ content: await readText(path.join(assets, 'adapters', 'qoder', 'agents', 'aidf-orchestrator.md')),
73
+ category: 'ide-agents',
74
+ });
75
+
76
+ if (withHooks) {
77
+ actions.push({
78
+ kind: 'write',
79
+ path: '.aidf/hooks/session-context.mjs',
80
+ content: await readText(path.join(assets, 'hooks', 'session-context.mjs')),
81
+ category: 'hooks',
82
+ });
83
+ actions.push({
84
+ kind: 'write',
85
+ path: '.aidf/hooks/audit.mjs',
86
+ content: await readText(path.join(assets, 'hooks', 'audit.mjs')),
87
+ category: 'hooks',
88
+ });
89
+ actions.push({
90
+ kind: 'merge-json',
91
+ path: '.qoder/settings.json',
92
+ patch: {
93
+ hooks: {
94
+ SessionStart: [
95
+ {
96
+ hooks: [
97
+ {
98
+ type: 'command',
99
+ command: 'node .aidf/hooks/session-context.mjs',
100
+ timeout: 15,
101
+ statusMessage: 'AIDF: loading project context',
102
+ },
103
+ ],
104
+ },
105
+ ],
106
+ PostToolUse: [
107
+ {
108
+ matcher: 'Write|Edit|search_replace|create_file',
109
+ hooks: [
110
+ {
111
+ type: 'command',
112
+ command: 'node .aidf/hooks/audit.mjs',
113
+ timeout: 10,
114
+ async: true,
115
+ },
116
+ ],
117
+ },
118
+ ],
119
+ },
120
+ },
121
+ category: 'ide-settings',
122
+ });
123
+ }
124
+
125
+ return actions;
126
+ }
127
+
128
+ async verify(context) {
129
+ const { root, frameworkRoot } = context;
130
+ const checks = [];
131
+ const env = context.env ?? {};
132
+ checks.push({
133
+ id: 'qoder-installed',
134
+ status: env?.ide?.qoder?.installed ? 'PASS' : 'NOT_PROVEN',
135
+ evidence: env?.ide?.qoder?.home ?? null,
136
+ limitation: env?.ide?.qoder?.installed ? null : 'Qoder installation not detected on this machine.',
137
+ });
138
+
139
+ const agents = path.join(root, 'AGENTS.md');
140
+ const agentsText = (await exists(agents)) ? await readText(agents) : '';
141
+ checks.push({
142
+ id: 'agents-md-block',
143
+ status: agentsText.includes('<!-- AIDF:BEGIN') ? 'PASS' : 'FAIL',
144
+ evidence: 'AGENTS.md managed block',
145
+ });
146
+
147
+ const rulesDir = path.join(root, '.qoder', 'rules');
148
+ const ruleFiles = ['aidf-00-core.md', 'aidf-10-security.md', 'aidf-20-context.md'];
149
+ const presentRules = [];
150
+ for (const file of ruleFiles) {
151
+ if (await exists(path.join(rulesDir, file))) presentRules.push(file);
152
+ }
153
+ checks.push({
154
+ id: 'rule-files',
155
+ status: presentRules.length === ruleFiles.length ? 'PASS' : 'FAIL',
156
+ evidence: presentRules,
157
+ limitation: 'Activation type is not encoded in the rule file; confirm it in the Qoder UI (Always Apply).',
158
+ });
159
+
160
+ const catalog = await loadSkillCatalog(frameworkRoot);
161
+ const invalid = [];
162
+ for (const skill of catalog) {
163
+ const file = path.join(root, '.qoder', 'skills', skill.name, 'SKILL.md');
164
+ if (!(await exists(file))) {
165
+ invalid.push(`${skill.name}: missing`);
166
+ continue;
167
+ }
168
+ const validation = validateSkillContent(await readText(file), { directoryName: skill.name });
169
+ if (!validation.valid) invalid.push(`${skill.name}: ${validation.errors.join('; ')}`);
170
+ }
171
+ checks.push({
172
+ id: 'skills-installed',
173
+ status: invalid.length === 0 ? 'PASS' : 'FAIL',
174
+ evidence: `${catalog.length} skills`,
175
+ limitation: invalid.length ? invalid : null,
176
+ });
177
+
178
+ const settings = path.join(root, '.qoder', 'settings.json');
179
+ let settingsOk = true;
180
+ let settingsNote = 'not present';
181
+ if (await exists(settings)) {
182
+ try {
183
+ const parsed = JSON.parse(await readText(settings));
184
+ settingsOk = true;
185
+ settingsNote = parsed.hooks ? 'hooks configured' : 'no hooks';
186
+ } catch (error) {
187
+ settingsOk = false;
188
+ settingsNote = error.message;
189
+ }
190
+ }
191
+ checks.push({
192
+ id: 'settings-json',
193
+ status: settingsOk ? 'PASS' : 'FAIL',
194
+ evidence: settingsNote,
195
+ });
196
+
197
+ checks.push({
198
+ id: 'runtime-skill-discovery',
199
+ status: 'NOT_PROVEN',
200
+ evidence: null,
201
+ limitation: 'Open a Qoder session and run /skills; confirm aidf-project-context is listed.',
202
+ });
203
+ checks.push({
204
+ id: 'runtime-rule-activation',
205
+ status: 'NOT_PROVEN',
206
+ evidence: null,
207
+ limitation: 'Qoder Settings → Rules: set aidf-00-core and aidf-10-security to Always Apply.',
208
+ });
209
+ checks.push({
210
+ id: 'runtime-hook-activation',
211
+ status: context.withHooks ? 'NOT_PROVEN' : 'NOT_APPLICABLE',
212
+ evidence: null,
213
+ limitation: context.withHooks
214
+ ? 'Restart Qoder and verify a tool edit writes .aidf/logs/audit-<date>.jsonl.'
215
+ : 'Hooks were not requested at install time.',
216
+ });
217
+
218
+ const fileChecks = checks.filter((c) => !c.id.startsWith('runtime-'));
219
+ const filesOk = fileChecks.every((c) => c.status === 'PASS' || c.status === 'NOT_APPLICABLE');
220
+ return {
221
+ status: filesOk ? 'CONTRACT-PROVEN' : 'FAIL',
222
+ checks,
223
+ limitations: [
224
+ 'File presence and format are proven. Runtime activation in Qoder requires a manual session check.',
225
+ ],
226
+ };
227
+ }
228
+ }
@@ -0,0 +1 @@
1
+ export { validateArtefact, resolveLinks, getAllArtefactIds, hashArtefact, ARTIFACT_STATUSES, ENVELOPE_REQUIRED } from './validation.mjs';
@@ -0,0 +1,161 @@
1
+ import { readText, readJson, exists, sha256Text } from '../../util/fsx.mjs';
2
+ import { FRAMEWORK_ROOT } from '../paths.mjs';
3
+ import { parseYaml } from '../../util/yaml.mjs';
4
+
5
+ export const ARTIFACT_STATUSES = ['DRAFT', 'VALIDATED', 'BLOCKED', 'OUTDATED'];
6
+ export const ENVELOPE_REQUIRED = ['id', 'schemaVersion', 'createdAt', 'updatedAt', 'status', 'source', 'links'];
7
+
8
+ /**
9
+ * Validate an artefact JSON against its schema.
10
+ * Returns { valid, errors, warnings }
11
+ */
12
+ export async function validateArtefact(json, options = {}) {
13
+ const errors = [];
14
+ const warnings = [];
15
+
16
+ // Check required envelope fields
17
+ for (const field of ENVELOPE_REQUIRED) {
18
+ if (!(field in json)) {
19
+ errors.push(`Missing required field: ${field}`);
20
+ }
21
+ }
22
+
23
+ // Validate schemaVersion format
24
+ if (json.schemaVersion && typeof json.schemaVersion !== 'string') {
25
+ errors.push('schemaVersion must be a string');
26
+ }
27
+
28
+ // Validate id format
29
+ if (json.id && typeof json.id !== 'string') {
30
+ errors.push('id must be a string');
31
+ }
32
+
33
+ // Validate status
34
+ if (json.status && !ARTIFACT_STATUSES.includes(json.status)) {
35
+ errors.push(`Invalid status: ${json.status}. Must be one of: ${ARTIFACT_STATUSES.join(', ')}`);
36
+ }
37
+
38
+ // Validate source
39
+ if (json.source) {
40
+ if (typeof json.source !== 'object') {
41
+ errors.push('source must be an object');
42
+ } else {
43
+ if (!json.source.type || !['human', 'generated', 'derived'].includes(json.source.type)) {
44
+ errors.push('source.type must be one of: human, generated, derived');
45
+ }
46
+ if (!json.source.author || typeof json.source.author !== 'string') {
47
+ errors.push('source.author must be a string');
48
+ }
49
+ if (!json.source.createdAt || !isValidIsoDate(json.source.createdAt)) {
50
+ errors.push('source.createdAt must be a valid ISO-8601 date-time');
51
+ }
52
+ }
53
+ }
54
+
55
+ // Validate links
56
+ if (json.links && typeof json.links !== 'object') {
57
+ errors.push('links must be an object');
58
+ }
59
+
60
+ // Validate validation object
61
+ if (json.validation) {
62
+ if (typeof json.validation !== 'object') {
63
+ errors.push('validation must be an object');
64
+ } else {
65
+ if (!json.validation.schemaVersion || typeof json.validation.schemaVersion !== 'string') {
66
+ errors.push('validation.schemaVersion must be a string');
67
+ }
68
+ if (!isValidIsoDate(json.validation.timestamp)) {
69
+ errors.push('validation.timestamp must be a valid ISO-8601 date-time');
70
+ }
71
+ if (typeof json.validation.valid !== 'boolean') {
72
+ errors.push('validation.valid must be a boolean');
73
+ }
74
+ if (json.validation.errors && !Array.isArray(json.validation.errors)) {
75
+ errors.push('validation.errors must be an array');
76
+ }
77
+ if (json.validation.warnings && !Array.isArray(json.validation.warnings)) {
78
+ errors.push('validation.warnings must be an array');
79
+ }
80
+ }
81
+ }
82
+
83
+ return { valid: errors.length === 0, errors, warnings };
84
+ }
85
+
86
+ /**
87
+ * Resolve links and verify they point to existing artefacts.
88
+ * Returns { resolved, unresolved, errors }
89
+ */
90
+ export async function resolveLinks(root, links, options = {}) {
91
+ const unresolved = [];
92
+ const errors = [];
93
+
94
+ if (!links || typeof links !== 'object') {
95
+ return { resolved: [], unresolved: [], errors: ['links must be an object'] };
96
+ }
97
+
98
+ // Get all artefact IDs in the artefacts directory
99
+ const artefactIds = await getAllArtefactIds(root);
100
+
101
+ // Check each link
102
+ const linkTypes = ['implements', 'designedBy', 'implementedBy', 'verifiedBy', 'evidencedBy'];
103
+ for (const linkType of linkTypes) {
104
+ const targetIds = links[linkType];
105
+ if (!targetIds || !Array.isArray(targetIds)) continue;
106
+
107
+ for (const targetId of targetIds) {
108
+ if (!artefactIds.has(targetId)) {
109
+ unresolved.push({ type: linkType, targetId });
110
+ errors.push(`Unresolved link: ${linkType} -> ${targetId} (not found in artefacts)`);
111
+ }
112
+ }
113
+ }
114
+
115
+ return { resolved: unresolved.length === 0 ? Object.keys(links).length : 0, unresolved, errors };
116
+ }
117
+
118
+ /**
119
+ * Get all artefact IDs from the artefacts directory.
120
+ */
121
+ export async function getAllArtefactIds(root) {
122
+ const ids = new Set();
123
+ const { aidfPaths } = await import('../paths.mjs');
124
+ const { readDirSafe } = await import('../../util/fsx.mjs');
125
+
126
+ const artefactsDir = aidfPaths(root).artefacts.dir;
127
+ if (!await exists(artefactsDir)) {
128
+ return ids;
129
+ }
130
+
131
+ try {
132
+ const { collectArtefactFiles } = await import('../traceability/chain.mjs');
133
+ const files = await collectArtefactFiles(root);
134
+ for (const { id } of files) {
135
+ ids.add(id);
136
+ }
137
+ } catch {
138
+ // Directory doesn't exist or can't be read
139
+ }
140
+
141
+ return ids;
142
+ }
143
+
144
+ /**
145
+ * Check if a string is a valid ISO-8601 date-time.
146
+ */
147
+ function isValidIsoDate(str) {
148
+ if (typeof str !== 'string') return false;
149
+ const date = new Date(str);
150
+ return !isNaN(date.getTime()) && str.includes('T');
151
+ }
152
+
153
+ /**
154
+ * Calculate SHA-256 hash of an artefact body (excluding hash field if present).
155
+ */
156
+ export function hashArtefact(body) {
157
+ const copy = { ...body };
158
+ delete copy.hash;
159
+ delete copy.validation;
160
+ return sha256Text(JSON.stringify(copy, null, 2));
161
+ }