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,232 @@
1
+ schemaVersion: 1
2
+ description: |
3
+ Executable gate definitions. Status precedence: FAIL > BLOCKED > NOT_PROVEN >
4
+ PASS. A check marked NOT_APPLICABLE does not block, but its reason is recorded.
5
+ Command checks only run when the caller passes --allow-exec or the project
6
+ configuration sets security.allowCommandExecution=true.
7
+
8
+ gates:
9
+ - id: intake-entry
10
+ phase: intake
11
+ kind: entry
12
+ description: AIDF is initialized and the constitution exists.
13
+ checks:
14
+ - id: manifest-present
15
+ type: file-exists
16
+ path: .aidf/manifest.json
17
+ blocking: true
18
+ - id: constitution-present
19
+ type: file-exists
20
+ path: .aidf/docs/constitution.md
21
+ blocking: true
22
+
23
+ - id: intake-exit
24
+ phase: intake
25
+ kind: exit
26
+ description: Task classified and context assembled.
27
+ checks:
28
+ - id: context-selected
29
+ type: file-exists
30
+ path: .aidf/state/context/latest.md
31
+ blocking: true
32
+ - id: task-classification
33
+ type: evidence
34
+ evidenceType: task-classification
35
+ blocking: true
36
+
37
+ - id: discovery-entry
38
+ phase: discovery
39
+ kind: entry
40
+ description: Intake gate passed.
41
+ checks:
42
+ - id: previous-intake
43
+ type: previous-gate
44
+ gate: intake-exit
45
+ blocking: true
46
+
47
+ - id: discovery-exit
48
+ phase: discovery
49
+ kind: exit
50
+ description: Project facts verified and recorded.
51
+ checks:
52
+ - id: project-scan
53
+ type: evidence
54
+ evidenceType: project-scan
55
+ blocking: true
56
+ - id: trd-not-blocked
57
+ type: doc-status
58
+ documents: [TRD]
59
+ disallowed: [BLOCKED, OUTDATED]
60
+ blocking: true
61
+
62
+ - id: specification-entry
63
+ phase: specification
64
+ kind: entry
65
+ description: Discovery gate passed.
66
+ checks:
67
+ - id: previous-discovery
68
+ type: previous-gate
69
+ gate: discovery-exit
70
+ blocking: true
71
+
72
+ - id: specification-exit
73
+ phase: specification
74
+ kind: exit
75
+ description: Specification validated by a human, with security impact identified.
76
+ checks:
77
+ - id: prd-validated
78
+ type: doc-status
79
+ documents: [PRD, APPFLOW]
80
+ allowed: [VALIDATED, NOT_APPLICABLE]
81
+ blocking: true
82
+ - id: security-not-contradictory
83
+ type: doc-status
84
+ documents: [SECURITY]
85
+ disallowed: [BLOCKED, OUTDATED]
86
+ blocking: true
87
+ - id: spec-human-validation
88
+ type: evidence
89
+ evidenceType: spec-validation
90
+ requireHumanApproval: true
91
+ blocking: true
92
+
93
+ - id: planning-entry
94
+ phase: planning
95
+ kind: entry
96
+ description: Specification gate passed.
97
+ checks:
98
+ - id: previous-specification
99
+ type: previous-gate
100
+ gate: specification-exit
101
+ blocking: true
102
+
103
+ - id: planning-exit
104
+ phase: planning
105
+ kind: exit
106
+ description: Technical plan approved by a human.
107
+ checks:
108
+ - id: trd-plan-validated
109
+ type: doc-status
110
+ documents: [TRD, PLAN]
111
+ allowed: [VALIDATED, NOT_APPLICABLE]
112
+ blocking: true
113
+ - id: backend-not-blocked
114
+ type: doc-status
115
+ documents: [BACKEND]
116
+ disallowed: [BLOCKED, OUTDATED]
117
+ blocking: true
118
+ - id: plan-human-approval
119
+ type: evidence
120
+ evidenceType: plan-approval
121
+ requireHumanApproval: true
122
+ blocking: true
123
+
124
+ - id: implementation-entry
125
+ phase: implementation
126
+ kind: entry
127
+ description: Plan approved.
128
+ checks:
129
+ - id: previous-planning
130
+ type: previous-gate
131
+ gate: planning-exit
132
+ blocking: true
133
+
134
+ - id: implementation-exit
135
+ phase: implementation
136
+ kind: exit
137
+ description: Changes implemented and captured.
138
+ checks:
139
+ - id: conventions-not-contradictory
140
+ type: doc-status
141
+ documents: [CONVENTIONS]
142
+ disallowed: [BLOCKED, OUTDATED]
143
+ blocking: true
144
+ - id: implementation-evidence
145
+ type: evidence
146
+ evidenceType: implementation-change
147
+ blocking: true
148
+
149
+ - id: testing-entry
150
+ phase: testing
151
+ kind: entry
152
+ description: Implementation gate passed.
153
+ checks:
154
+ - id: previous-implementation
155
+ type: previous-gate
156
+ gate: implementation-exit
157
+ blocking: true
158
+
159
+ - id: testing-exit
160
+ phase: testing
161
+ kind: exit
162
+ description: Real tests executed successfully.
163
+ checks:
164
+ - id: test-command
165
+ type: command
166
+ commandKey: test
167
+ blocking: true
168
+ - id: test-evidence
169
+ type: evidence
170
+ evidenceType: test-run
171
+ blocking: true
172
+
173
+ - id: security-entry
174
+ phase: security
175
+ kind: entry
176
+ description: Testing gate passed.
177
+ checks:
178
+ - id: previous-testing
179
+ type: previous-gate
180
+ gate: testing-exit
181
+ blocking: true
182
+
183
+ - id: security-exit
184
+ phase: security
185
+ kind: exit
186
+ description: Security reviewed and approved by a human.
187
+ checks:
188
+ - id: security-doc-validated
189
+ type: doc-status
190
+ documents: [SECURITY]
191
+ allowed: [VALIDATED, NOT_APPLICABLE]
192
+ blocking: true
193
+ - id: security-audit
194
+ type: command
195
+ commandKey: securityAudit
196
+ blocking: false
197
+ missing: NOT_APPLICABLE
198
+ - id: security-human-approval
199
+ type: evidence
200
+ evidenceType: security-review
201
+ requireHumanApproval: true
202
+ blocking: true
203
+
204
+ - id: release-entry
205
+ phase: release
206
+ kind: entry
207
+ description: Security gate passed.
208
+ checks:
209
+ - id: previous-security
210
+ type: previous-gate
211
+ gate: security-exit
212
+ blocking: true
213
+
214
+ - id: release-exit
215
+ phase: release
216
+ kind: exit
217
+ description: All prior gates passed and release approved by a human.
218
+ checks:
219
+ - id: prior-gates
220
+ type: previous-gate
221
+ gates: [intake-exit, discovery-exit, specification-exit, planning-exit, implementation-exit, testing-exit, security-exit]
222
+ blocking: true
223
+ - id: build-command
224
+ type: command
225
+ commandKey: build
226
+ blocking: false
227
+ missing: NOT_APPLICABLE
228
+ - id: release-human-approval
229
+ type: evidence
230
+ evidenceType: release-approval
231
+ requireHumanApproval: true
232
+ blocking: true
@@ -0,0 +1,161 @@
1
+ schemaVersion: 1
2
+ description: |
3
+ AIDF development cycle. Each phase declares what must be true before entering
4
+ and before leaving. Gates are executable definitions in gates.yaml.
5
+
6
+ phases:
7
+ - id: intake
8
+ name: Intake and classification
9
+ objective: Understand the request, classify it and assemble the minimum context.
10
+ requiredDocuments: [constitution, CONVENTIONS, PRD]
11
+ skills: [project-context, phase-transition]
12
+ inputs: [user request, repository state]
13
+ deliverables:
14
+ - classified task (feature, bug, refactor, security, docs, ops)
15
+ - context manifest
16
+ tests:
17
+ - context manifest exists and lists selected documents/skills
18
+ acceptance:
19
+ - the task type and affected areas are stated
20
+ - open questions are listed instead of guessed
21
+ exitGate: intake-exit
22
+ blockingConditions:
23
+ - the request contradicts the constitution or SECURITY.md
24
+ - a required secret or access is missing
25
+
26
+ - id: discovery
27
+ name: Discovery
28
+ objective: Establish verified facts about the project, constraints and resources.
29
+ requiredDocuments: [TRD, DECISIONS]
30
+ skills: [project-context, architecture-review]
31
+ inputs: [repository, git state, existing AI resources]
32
+ deliverables:
33
+ - project scan evidence
34
+ - verified facts vs open questions
35
+ tests:
36
+ - scan executed and recorded
37
+ acceptance:
38
+ - no architectural claim without a file reference
39
+ exitGate: discovery-exit
40
+ blockingConditions:
41
+ - the repository cannot be read
42
+ - a contradiction affects architecture or data ownership
43
+
44
+ - id: specification
45
+ name: Specification
46
+ objective: Define behaviour, flows, interface impact and acceptance criteria.
47
+ requiredDocuments: [PRD, APPFLOW, UI-UX, SECURITY]
48
+ skills: [product-analysis, requirements-engineering, ui-ux-implementation]
49
+ inputs: [classified task, context manifest, discovery findings]
50
+ deliverables:
51
+ - updated PRD/APPFLOW/UI-UX
52
+ - numbered acceptance criteria
53
+ - human validation of the specification
54
+ tests:
55
+ - every requirement has an acceptance criterion and verification method
56
+ acceptance:
57
+ - scope and non-goals are explicit
58
+ - security and data impacts are identified
59
+ exitGate: specification-exit
60
+ blockingConditions:
61
+ - unresolved product decision
62
+ - security or data contradiction
63
+
64
+ - id: planning
65
+ name: Planning
66
+ objective: Turn the specification into a technical plan, tasks and test strategy.
67
+ requiredDocuments: [TRD, PLAN, BACKEND]
68
+ skills: [architecture-review, database-design, requirements-engineering]
69
+ inputs: [validated specification]
70
+ deliverables:
71
+ - technical plan and task breakdown
72
+ - test strategy
73
+ - human approval of the plan
74
+ tests:
75
+ - each task has a dependency and acceptance criterion
76
+ acceptance:
77
+ - plan is consistent with TRD and SECURITY
78
+ - rollback path exists for data or deployment changes
79
+ exitGate: planning-exit
80
+ blockingConditions:
81
+ - unresolved architectural conflict
82
+ - missing contract or data model
83
+
84
+ - id: implementation
85
+ name: Implementation
86
+ objective: Implement the planned change in small, reviewable increments.
87
+ requiredDocuments: [CONVENTIONS, BACKEND, UI-UX]
88
+ skills: [frontend-implementation, backend-implementation, database-design, devops-engineering]
89
+ inputs: [approved plan, tasks]
90
+ deliverables:
91
+ - code and configuration changes
92
+ - updated tests
93
+ - implementation evidence (files changed)
94
+ tests:
95
+ - focused tests for changed behaviour
96
+ acceptance:
97
+ - code follows existing conventions and design system
98
+ - no unrelated refactor
99
+ exitGate: implementation-exit
100
+ blockingConditions:
101
+ - build or typecheck failure
102
+ - change requires an unapproved architecture decision
103
+
104
+ - id: testing
105
+ name: Testing and validation
106
+ objective: Prove the change with real execution, including failure paths.
107
+ requiredDocuments: [PLAN, CONVENTIONS]
108
+ skills: [testing-validation]
109
+ inputs: [implementation diff]
110
+ deliverables:
111
+ - executed test command with output hash
112
+ - list of untested paths and limitations
113
+ tests:
114
+ - project test command exits 0
115
+ acceptance:
116
+ - nominal and failure paths covered
117
+ - mocks are not presented as integrations
118
+ exitGate: testing-exit
119
+ blockingConditions:
120
+ - test command missing or not executable
121
+ - failing tests
122
+
123
+ - id: security
124
+ name: Security validation
125
+ objective: Review the change for security and privacy risk and record residual risk.
126
+ requiredDocuments: [SECURITY, BACKEND, DECISIONS]
127
+ skills: [security-review, testing-validation]
128
+ inputs: [diff, test evidence, threat model]
129
+ deliverables:
130
+ - security findings with severity and evidence
131
+ - human security approval
132
+ tests:
133
+ - configured audit command (if any) executed
134
+ acceptance:
135
+ - no unmitigated high-severity finding
136
+ - residual risks accepted by a human
137
+ exitGate: security-exit
138
+ blockingConditions:
139
+ - unmitigated high-severity finding
140
+ - missing human security approval
141
+
142
+ - id: release
143
+ name: Release and documentation
144
+ objective: Finalize documentation, changelog and release evidence.
145
+ requiredDocuments: [CHANGELOG, PLAN, DECISIONS]
146
+ skills: [documentation-maintenance, phase-transition, devops-engineering]
147
+ inputs: [all prior evidence]
148
+ deliverables:
149
+ - updated documents and changelog
150
+ - release report
151
+ - human release approval
152
+ tests:
153
+ - all prior exit gates PASS
154
+ - build command (if configured) exits 0
155
+ acceptance:
156
+ - no document claims an unverified behaviour
157
+ - rollback procedure documented
158
+ exitGate: release-exit
159
+ blockingConditions:
160
+ - any prior gate not PASS
161
+ - missing human release approval
package/bin/aidf.mjs ADDED
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+ import { main } from '../src/cli.mjs';
3
+
4
+ main(process.argv.slice(2)).then((code) => {
5
+ process.exitCode = code;
6
+ }).catch((error) => {
7
+ process.stderr.write(`aidf: fatal: ${error && error.message ? error.message : String(error)}\n`);
8
+ if (process.env.AIDF_DEBUG === '1' && error && error.stack) {
9
+ process.stderr.write(`${error.stack}\n`);
10
+ }
11
+ process.exitCode = 70;
12
+ });
@@ -0,0 +1,97 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * AIDF live demo.
4
+ *
5
+ * This demo performs real operations against a temporary project:
6
+ * install -> doctor -> context -> query a gate -> inspect resources.
7
+ * It never prints predefined success messages: every summary comes from the
8
+ * actual command output, and the demo exits with the first failing exit code.
9
+ *
10
+ * Usage: node demo/run-demo.mjs [--keep]
11
+ */
12
+ import path from 'node:path';
13
+ import os from 'node:os';
14
+ import fsp from 'node:fs/promises';
15
+ import { execFile } from 'node:child_process';
16
+ import { promisify } from 'node:util';
17
+
18
+ const execFileAsync = promisify(execFile);
19
+ const BIN = path.resolve(import.meta.dirname, '..', 'bin', 'aidf.mjs');
20
+ const keep = process.argv.includes('--keep');
21
+
22
+ async function run(args) {
23
+ try {
24
+ const { stdout, stderr } = await execFileAsync(process.execPath, [BIN, ...args], {
25
+ cwd: path.dirname(BIN),
26
+ env: { ...process.env, AIDF_LOG_LEVEL: 'error' },
27
+ maxBuffer: 20 * 1024 * 1024,
28
+ });
29
+ return { code: 0, stdout, stderr };
30
+ } catch (error) {
31
+ return { code: error.code ?? 1, stdout: error.stdout ?? '', stderr: error.stderr ?? '' };
32
+ }
33
+ }
34
+
35
+ function parse(result, label) {
36
+ try {
37
+ return JSON.parse(result.stdout);
38
+ } catch {
39
+ throw new Error(`${label}: invalid JSON output (exit ${result.code}).\n${result.stdout}\n${result.stderr}`);
40
+ }
41
+ }
42
+
43
+ async function main() {
44
+ const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'aidf-demo-'));
45
+ console.log(`AIDF demo — temporary project: ${root}`);
46
+ try {
47
+ await fsp.writeFile(
48
+ path.join(root, 'package.json'),
49
+ JSON.stringify({ name: 'aidf-demo-project', version: '1.0.0', scripts: { test: 'node --version' } }, null, 2),
50
+ 'utf8',
51
+ );
52
+
53
+ const install = await run(['install', '--target', root, '--adapter', 'qoder', '--json']);
54
+ const installed = parse(install, 'install');
55
+ console.log(`install: created=${installed.summary.created} updated=${installed.summary.updated} conflicts=${installed.summary.conflicts} failed=${installed.summary.failed}`);
56
+ if (install.code !== 0) process.exitCode = install.code;
57
+
58
+ const doctor = await run(['doctor', '--target', root, '--json']);
59
+ const diagnosed = parse(doctor, 'doctor');
60
+ for (const check of diagnosed.checks) {
61
+ console.log(`doctor: ${check.id} -> ${check.status}`);
62
+ }
63
+ if (doctor.code !== 0) process.exitCode = doctor.code;
64
+
65
+ const context = await run(['context', '--target', root, '--task', 'add an API endpoint with a database migration', '--json']);
66
+ const assembled = parse(context, 'context');
67
+ console.log(`context: status=${assembled.context.status} documents=${assembled.context.documents.length} skills=${assembled.context.skills.length}`);
68
+ if (context.code !== 0) process.exitCode = context.code;
69
+
70
+ const gate = await run(['validate', '--gate', 'intake-entry', '--target', root, '--json']);
71
+ const report = parse(gate, 'validate');
72
+ console.log(`gate intake-entry: ${report.status}`);
73
+ if (gate.code !== 0) process.exitCode = gate.code;
74
+
75
+ const resources = await run(['resources', 'inspect', '--target', root, '--json']);
76
+ const listed = parse(resources, 'resources');
77
+ const counts = listed.reduce((acc, r) => {
78
+ acc[r.status] = (acc[r.status] ?? 0) + 1;
79
+ return acc;
80
+ }, {});
81
+ console.log(`resources: ${listed.length} indexed source(s) — ${Object.entries(counts).map(([k, v]) => `${k}=${v}`).join(' ')}`);
82
+ if (resources.code !== 0) process.exitCode = resources.code;
83
+
84
+ console.log('note: this demo exercises the CLI and filesystem contracts; it does not prove Qoder runtime (/skills, Always Apply, hooks).');
85
+ } finally {
86
+ if (keep) {
87
+ console.log(`Kept for inspection: ${root}`);
88
+ } else {
89
+ await fsp.rm(root, { recursive: true, force: true });
90
+ }
91
+ }
92
+ }
93
+
94
+ main().catch((error) => {
95
+ console.error(error.message);
96
+ process.exitCode = 1;
97
+ });
@@ -0,0 +1,126 @@
1
+ # ADR-001 — Structured Artefacts Architecture
2
+
3
+ - Status: **proposed**
4
+ - Date: 2026-11-20
5
+ - Deciders: AIDF maintainer
6
+ - Reference: AIDF 0.1.0 baseline (commit 85f187a)
7
+
8
+ ## Context
9
+
10
+ AIDF 0.1.0 uses Markdown documents as the primary source of project artefacts (PRD, TRD, UI-UX, SECURITY, etc.). These documents are useful for human consumption but lack:
11
+
12
+ - A machine-readable structure for validation
13
+ - Stable identifiers for traceability
14
+ - Explicit relationships between requirements, design, implementation and tests
15
+ - A mechanism to verify that a "covered" requirement actually has executable tests
16
+
17
+ The project needs a structured artefact system that:
18
+
19
+ 1. Preserves Markdown documents for human readability
20
+ 2. Adds a machine-readable layer for validation and traceability
21
+ 3. Connects requirements → design → implementation → tests → evidence
22
+ 4. Prevents虚假 declarations of coverage without real execution
23
+ 5. Works within the existing AIDF workflow and CLI
24
+
25
+ ## Decision
26
+
27
+ Introduce a layered artefact model:
28
+
29
+ | Layer | Format | Purpose | Read/Write | Source of Truth |
30
+ |---|---|---|---|---|
31
+ | **Canonical** | JSON | Machine validation, linking, traceability | CLI-only writes | JSON files |
32
+ | **Documentary** | Markdown | Human readability, review | Read-only (derived) | JSON |
33
+ | **Generated** | Markdown | Display in IDE, CLI | Read-only (derived) | JSON |
34
+
35
+ ### Artefact types
36
+
37
+ AIDF will manage the following canonical artefacts:
38
+
39
+ ```text
40
+ aidf/
41
+ artefacts/
42
+ discovery.json # Project facts, constraints, resources
43
+ constraints.json # Non-negotiable limits (tech stack, budget, deadlines)
44
+ requirements.json # Requirement registry
45
+ architecture.json # Architecture decisions and component model
46
+ test-plan.json # Test strategy and test map
47
+ decisions/
48
+ <decision-id>.json # ADRs (Architectural Decision Records)
49
+ security/
50
+ threat-model.json # STRIDE-based threat model
51
+ ```
52
+
53
+ ### Envelope contract (common schema)
54
+
55
+ Every artefact shares a common envelope:
56
+
57
+ ```json
58
+ {
59
+ "id": "stable-identifier",
60
+ "schemaVersion": "1.0.0",
61
+ "createdAt": "2026-11-20T...",
62
+ "updatedAt": "2026-11-20T...",
63
+ "status": "DRAFT"|"VALIDATED"|"BLOCKED"|"OUTDATED",
64
+ "source": {
65
+ "type": "human"|"generated"|"derived",
66
+ "author": "Jeremy"|"aidf",
67
+ "createdAt": "2026-11-20T...",
68
+ "generator": null|"schema-name@1.0.0"
69
+ },
70
+ "links": [
71
+ {
72
+ "targetId": "REQ-F-001",
73
+ "targetType": "requirement",
74
+ "type": "implements"|"designed-by"|"tested-by"|"verified-by"
75
+ }
76
+ ],
77
+ "validation": {
78
+ "schemaVersion": "1.0.0",
79
+ "timestamp": "2026-11-20T...",
80
+ "valid": true,
81
+ "errors": [],
82
+ "warnings": []
83
+ }
84
+ }
85
+ ```
86
+
87
+ ### Rationale
88
+
89
+ - **id**: Stable identifier that survives reordering, editing, migration
90
+ - **schemaVersion**: Independent of AIDF version; enables schema evolution
91
+ - **createdAt/updatedAt**: Immutable creation date, mutable update date
92
+ - **status**: Reuse existing AIDF statuses (DRAFT, VALIDATED, BLOCKED, OUTDATED)
93
+ - **source**: Provenance tracking; distinguishes human vs generated content
94
+ - **links**: Explicit relationships (requirement → design → implementation)
95
+ - **validation**: Real-time validation result, not just declaration
96
+
97
+ ## Consequences
98
+
99
+ ### Positive
100
+
101
+ - Artefacts are machine-validated (schema, types, links)
102
+ - Traceability chain is verifiable (requirement → evidence)
103
+ - Coverage calculation is deterministic (no false PASS)
104
+ - Markdown remains human-readable (derived view)
105
+ - No breaking change to existing CLI or workflow
106
+
107
+ ### Negative
108
+
109
+ - More files to manage in `.aidf/`
110
+ - Initial migration of existing Markdown documents
111
+ - CLI commands required for artefact manipulation
112
+
113
+ ### Neutral
114
+
115
+ - artefacts are stored under `.aidf/artefacts/` (not replacing `.aidf/docs/`)
116
+ - Markdown documents remain under `.aidf/docs/` (read-only, generated)
117
+
118
+ ## Status
119
+
120
+ **proposed** — awaiting human validation before implementation.
121
+
122
+ ## Next steps
123
+
124
+ - L1-A design complete; ready for L1-B implementation (schemas and registry)
125
+ - If approved: implement JSON schemas, registry, validation, tests
126
+ - If rejected: retain current Markdown-only model, re-evaluate requirements