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,145 @@
1
+ # ADR-002 — Requirements Registry
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 does not have a structured requirement registry. Requirements may be written in Markdown (PRD, BACKEND) but:
11
+
12
+ - No stable identifiers for requirements (IDs are implicit in position)
13
+ - No connection to design, implementation, tests or evidence
14
+ - No way to verify "coverage" without executing real tests
15
+ - No way to track which requirements are incomplete or untested
16
+
17
+ The project needs a requirement registry that:
18
+
19
+ 1. Assigns stable identifiers (REQ-F-001, REQ-NF-001)
20
+ 2. Connects requirements to design, tests and evidence
21
+ 3. Computes coverage deterministically (not by declaration)
22
+ 4. Distinguishes between "implemented" and "verified"
23
+
24
+ ## Decision
25
+
26
+ Create a requirements registry as a canonical artefact:
27
+
28
+ ```text
29
+ .aidf/artefacts/requirements.json
30
+ ```
31
+
32
+ ### Requirement schema
33
+
34
+ ```json
35
+ {
36
+ "id": "REQ-F-001",
37
+ "schemaVersion": "1.0.0",
38
+ "createdAt": "2026-11-20T...",
39
+ "updatedAt": "2026-11-20T...",
40
+ "status": "DRAFT"|"VALIDATED"|"BLOCKED"|"OUTDATED",
41
+ "type": "FUNCTIONAL"|"NON_FUNCTIONAL",
42
+ "title": "User can reset password",
43
+ "description": "Registered users can initiate a password reset...",
44
+ "priority": "must"|"should"|"could",
45
+ "acceptanceCriteria": [
46
+ {
47
+ "id": "REQ-F-001-AC1",
48
+ "description": "Email is sent to registered address",
49
+ "verification": {
50
+ "type": "test"|"manual"|"review",
51
+ "testPath": "tests/auth/password-reset.test.mjs#reset-sends-email",
52
+ "command": "node --test tests/auth/password-reset.test.mjs"
53
+ }
54
+ }
55
+ ],
56
+ "links": {
57
+ "implements": ["PRD-FR-001"],
58
+ "designedBy": ["ARCH-001"],
59
+ "implementedBy": ["BACKEND-EMAIL-SERVICE"],
60
+ "verifiedBy": ["REQ-F-001-TEST-1", "REQ-F-001-TEST-2"]
61
+ },
62
+ "validation": { ... }
63
+ }
64
+ ```
65
+
66
+ ### Identifiers
67
+
68
+ - **FUNCTIONAL**: `REQ-F-XXX` (e.g., REQ-F-001)
69
+ - **NON_FUNCTIONAL**: `REQ-NF-XXX` (e.g., REQ-NF-001)
70
+ - **CRITERIA**: `REQ-F-XXX-ACn` (e.g., REQ-F-001-AC1)
71
+
72
+ Identifiers are stable and never reused. Deleting a requirement marks it `BLOCKED` but keeps its ID.
73
+
74
+ ### Coverage calculation (deterministic)
75
+
76
+ A requirement is **COVERED** only when:
77
+
78
+ 1. **All acceptance criteria are TESTED**
79
+ - Each criterion has at least one verification entry
80
+ - Each verification references an existing test file
81
+ - The test command has been executed (evidence exists)
82
+
83
+ 2. **Test result is PASS**
84
+ - Evidence record exists for the test run
85
+ - Evidence status is `PASS`
86
+ - Evidence references the test path/command
87
+
88
+ 3. **Evidence is recent**
89
+ - Evidence timestamp is within retention period
90
+ - Evidence commit matches current branch head (if git)
91
+
92
+ **Coverage is computed at runtime, never declared.**
93
+
94
+ ### Registry API (proposed CLI)
95
+
96
+ ```bash
97
+ # List requirements
98
+ aidf requirements list [--type F|NF] [--status DRAFT|VALIDATED]
99
+
100
+ # Show requirement details
101
+ aidf requirements show REQ-F-001 [--json]
102
+
103
+ # Create requirement
104
+ aidf requirements add --id REQ-F-001 --type F --title "..." --desc "..."
105
+
106
+ # Update requirement
107
+ aidf requirements update REQ-F-001 --title "new title"
108
+
109
+ # Compute coverage
110
+ aidf requirements coverage [--json]
111
+
112
+ # Link to tests
113
+ aidf requirements link REQ-F-001 --test tests/auth/reset.test.mjs#reset-sends-email
114
+
115
+ # Validate registry
116
+ aidf requirements validate [--json]
117
+ ```
118
+
119
+ ## Consequences
120
+
121
+ ### Positive
122
+
123
+ - Stable requirement identifiers
124
+ - Link to design, implementation, tests
125
+ - Deterministic coverage (no false PASS)
126
+ - Evidence-based validation
127
+
128
+ ### Negative
129
+
130
+ - More files to manage
131
+ - CLI commands required for manipulation
132
+
133
+ ### Neutral
134
+
135
+ - Registry stored under `.aidf/artefacts/requirements.json`
136
+ - Markdown documents remain source of record for PRD/BACKEND
137
+
138
+ ## Status
139
+
140
+ **proposed** — awaiting human validation before implementation.
141
+
142
+ ## Next steps
143
+
144
+ - If approved: implement schema, registry management, coverage calculation
145
+ - Tests required: identifier stability, link resolution, coverage computation
@@ -0,0 +1,145 @@
1
+ # ADR-003 — Traceability Chain
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 has no mechanism to verify that:
11
+
12
+ - A requirement has design documentation
13
+ - Design documentation is implemented
14
+ - Implementation is tested
15
+ - Tests have been executed and passed
16
+ - Evidence is linked to the requirement
17
+
18
+ The project needs a traceability chain that:
19
+
20
+ 1. Connects requirement → design → implementation → test → evidence
21
+ 2. Verifies each link exists and is valid
22
+ 3. Reports breaks in the chain
23
+ 4. Computes overall coverage deterministically
24
+
25
+ ## Decision
26
+
27
+ Define explicit link types between artefacts:
28
+
29
+ | Link type | Source | Target | Meaning |
30
+ |---|---|---|---|
31
+ | `implements` | requirement | requirement/decision | Requirement implements a higher-level goal |
32
+ | `designed-by` | requirement/design | architecture/design | Requirement/feature has a design |
33
+ | `implemented-by` | design | implementation | Design has implementation (file/function) |
34
+ | `verified-by` | requirement/test | test | Requirement/test has verification |
35
+ | `evidenced-by` | test/evidence | evidence | Test execution has evidence |
36
+
37
+ ### Chain structure
38
+
39
+ ```json
40
+ {
41
+ "requirement": {
42
+ "id": "REQ-F-001",
43
+ "links": {
44
+ "implements": ["PRD-001"],
45
+ "designedBy": ["DES-001"],
46
+ "verifiedBy": ["REQ-F-001-TEST-1"]
47
+ }
48
+ },
49
+ "design": {
50
+ "id": "DES-001",
51
+ "links": {
52
+ "designedBy": ["REQ-F-001"],
53
+ "implementedBy": ["BACKEND-001"]
54
+ }
55
+ },
56
+ "implementation": {
57
+ "id": "BACKEND-001",
58
+ "links": {
59
+ "implementedBy": ["DES-001"],
60
+ "verifiedBy": ["REQ-F-001-TEST-1"]
61
+ }
62
+ },
63
+ "test": {
64
+ "id": "REQ-F-001-TEST-1",
65
+ "links": {
66
+ "verifiedBy": ["REQ-F-001", "BACKEND-001"],
67
+ "evidencedBy": ["EVID-001"]
68
+ }
69
+ },
70
+ "evidence": {
71
+ "id": "EVID-001",
72
+ "links": {
73
+ "evidencedBy": ["REQ-F-001-TEST-1"],
74
+ "requirement": "REQ-F-001"
75
+ }
76
+ }
77
+ }
78
+ ```
79
+
80
+ ### Verification API (proposed CLI)
81
+
82
+ ```bash
83
+ # Verify requirement chain
84
+ aidf traceability verify REQ-F-001 [--json]
85
+
86
+ # Report all broken chains
87
+ aidf traceability report [--json]
88
+
89
+ # Find requirements without design
90
+ aidf traceability missing --type design [--json]
91
+
92
+ # Find tests without evidence
93
+ aidf traceability missing --type evidence [--json]
94
+ ```
95
+
96
+ ### Coverage computation
97
+
98
+ ```text
99
+ coverage = {
100
+ requirements: {
101
+ total: 10,
102
+ covered: 3,
103
+ untested: 4,
104
+ testedButNotPassing: 3
105
+ },
106
+ design: {
107
+ total: 5,
108
+ implemented: 2,
109
+ notImplemented: 3
110
+ },
111
+ tests: {
112
+ total: 6,
113
+ executed: 3,
114
+ passing: 1,
115
+ failing: 2
116
+ }
117
+ }
118
+ ```
119
+
120
+ ## Consequences
121
+
122
+ ### Positive
123
+
124
+ - End-to-end traceability
125
+ - Break detection (requirement without test, test without evidence)
126
+ - Deterministic coverage computation
127
+
128
+ ### Negative
129
+
130
+ - More files to manage
131
+ - Link validation required
132
+
133
+ ### Neutral
134
+
135
+ - Links are explicit, never inferred
136
+ - Missing links are reported, not assumed
137
+
138
+ ## Status
139
+
140
+ **proposed** — awaiting human validation before implementation.
141
+
142
+ ## Next steps
143
+
144
+ - If approved: implement link types, verification, coverage computation
145
+ - Tests required: chain verification, break detection, coverage calculation
@@ -0,0 +1,134 @@
1
+ # ADR-004 — Markdown Generation and Divergence Detection
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 has 11 Markdown documents in `.aidf/docs/`:
11
+
12
+ - PRD.md, TRD.md, UI-UX.md, SECURITY.md, BACKEND.md
13
+ - APPFLOW.md, PLAN.md, DECISIONS.md, CHANGELOG.md, CONVENTIONS.md, constitution.md
14
+
15
+ These documents are:
16
+
17
+ - Currently the source of truth (no canonical JSON layer)
18
+ - Human-edited (no generation mechanism)
19
+ - Not linked to requirements or tests
20
+
21
+ L1 introduces canonical JSON artefacts. The question is: how do we handle existing Markdown documents?
22
+
23
+ ## Decision
24
+
25
+ Preserve existing Markdown documents and treat them as the **canonical source** for now. L1 artefacts will be **derived** from them.
26
+
27
+ ### Migration strategy
28
+
29
+ 1. **Read existing Markdown documents** (`.aidf/docs/*.md`)
30
+ 2. **Extract structured data** from frontmatter and body
31
+ 3. **Generate canonical JSON artefacts** (`.aidf/artefacts/requirements.json`, etc.)
32
+ 4. **Record source metadata** (original file, hash, generation timestamp)
33
+ 5. **Detect divergence** if Markdown is modified after generation
34
+
35
+ ### Divergence detection
36
+
37
+ Each canonical artefact stores:
38
+
39
+ ```json
40
+ {
41
+ "source": {
42
+ "type": "markdown",
43
+ "path": ".aidf/docs/PRD.md",
44
+ "hash": "sha256-...",
45
+ "generatedAt": "2026-11-20T...",
46
+ "generator": "requirements-schema@1.0.0"
47
+ }
48
+ }
49
+ ```
50
+
51
+ If a Markdown file is edited manually after generation:
52
+
53
+ ```json
54
+ {
55
+ "source": {
56
+ "type": "markdown",
57
+ "path": ".aidf/docs/PRD.md",
58
+ "hash": "sha256-old...",
59
+ "generatedAt": "2026-11-20T...",
60
+ "generator": "requirements-schema@1.0.0"
61
+ },
62
+ "divergence": {
63
+ "detected": true,
64
+ "reason": "Source Markdown hash changed (PRD.md is now sha256-new...)",
65
+ "recommendation": "Manually reconcile or regenerate (overwrites manual changes)"
66
+ }
67
+ }
68
+ ```
69
+
70
+ ### Frozen documents
71
+
72
+ Documents marked with `frozen: true` in their frontmatter are **protected**:
73
+
74
+ ```markdown
75
+ ---
76
+ doc: constitution
77
+ status: DRAFT
78
+ frozen: true
79
+ ---
80
+ ```
81
+
82
+ Rules for frozen documents:
83
+
84
+ - **Never** regenerate automatically
85
+ - **Never** overwrite silently
86
+ - **Never** modify frontmatter without explicit permission
87
+ - Any reconciliation requires human approval
88
+
89
+ ### Proposed CLI for Markdown management
90
+
91
+ ```bash
92
+ # List Markdown documents with status
93
+ aidf docs list [--json]
94
+
95
+ # Generate JSON from Markdown
96
+ aidf docs generate PRD [--json]
97
+
98
+ # Detect divergences
99
+ aidf docs check [--json]
100
+
101
+ # Regenerate (overwrites manual changes)
102
+ aidf docs regenerate PRD [--yes]
103
+
104
+ # Reconcile frozen document (requires approval)
105
+ aidf docs reconcile PRD --by "Jeremy"
106
+ ```
107
+
108
+ ## Consequences
109
+
110
+ ### Positive
111
+
112
+ - Existing Markdown documents remain usable
113
+ - Generation is deterministic and reproducible
114
+ - Divergence is detected, never hidden
115
+ - Frozen documents are protected
116
+
117
+ ### Negative
118
+
119
+ - Initial migration adds files
120
+ - CLI commands required for generation
121
+
122
+ ### Neutral
123
+
124
+ - Markdown documents remain in `.aidf/docs/`
125
+ - Canonical JSON artefacts stored in `.aidf/artefacts/`
126
+
127
+ ## Status
128
+
129
+ **proposed** — awaiting human validation before implementation.
130
+
131
+ ## Next steps
132
+
133
+ - If approved: implement Markdown parsing, JSON generation, divergence detection
134
+ - Tests required: generation reproducibility, divergence detection, frozen protection
@@ -0,0 +1,170 @@
1
+ # ADR-005 — Validation and Tests
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 has 44 tests in `tests/*.test.mjs`. L1 introduces canonical JSON artefacts that need:
11
+
12
+ 1. Schema validation (JSON Schema Draft 2020-12)
13
+ 2. Link resolution verification
14
+ 3. Coverage computation tests
15
+ 4. Markdown generation tests
16
+ 5. Compatibility with existing tests
17
+
18
+ ## Decision
19
+
20
+ Maintain separate layers for validation and testing:
21
+
22
+ ### 1. Schema validation (deterministic)
23
+
24
+ Use JSON Schema Draft 2020-12 for all artefacts.
25
+
26
+ ```json
27
+ {
28
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
29
+ "$id": "https://aidf.dev/schemas/requirement/v1",
30
+ "title": "Requirement",
31
+ "description": "A structured requirement in AIDF",
32
+ "type": "object",
33
+ "properties": {
34
+ "id": { "type": "string", "pattern": "^REQ-[FN]\\d{3}$" },
35
+ "schemaVersion": { "const": "1.0.0" },
36
+ "createdAt": { "type": "string", "format": "date-time" },
37
+ "updatedAt": { "type": "string", "format": "date-time" },
38
+ "status": { "enum": ["DRAFT", "VALIDATED", "BLOCKED", "OUTDATED"] },
39
+ "type": { "enum": ["FUNCTIONAL", "NON_FUNCTIONAL"] },
40
+ "title": { "type": "string", "minLength": 1 },
41
+ "description": { "type": "string", "minLength": 10 },
42
+ "acceptanceCriteria": {
43
+ "type": "array",
44
+ "items": { "$ref": "#/$defs/criterion" }
45
+ },
46
+ "links": { "$ref": "#/$defs/links" }
47
+ },
48
+ "required": ["id", "schemaVersion", "createdAt", "status", "type", "title", "description"],
49
+ "$defs": {
50
+ "links": { "type": "object", "properties": { ... } },
51
+ "criterion": { "type": "object", "properties": { ... } }
52
+ }
53
+ }
54
+ ```
55
+
56
+ Validation rules:
57
+
58
+ - **Schema validation**: JSON Schema_draft 2020-12
59
+ - **Link validation**: All `targetId` must reference existing artefacts
60
+ - **Type validation**: Enum values must be in allowed list
61
+ - **ID stability**: No duplicates, IDs are never reused
62
+
63
+ ### 2. Link resolution (deterministic)
64
+
65
+ When an artefact references another:
66
+
67
+ ```json
68
+ {
69
+ "links": {
70
+ "designedBy": ["DES-001", "DES-002"]
71
+ }
72
+ }
73
+ ```
74
+
75
+ Verification:
76
+
77
+ 1. Check `DES-001` exists in artefacts directory
78
+ 2. Check `DES-002` exists in artefacts directory
79
+ 3. Report missing links as `BLOCKED`
80
+ 4. Do not accept link if target doesn't exist
81
+
82
+ ### 3. Coverage computation (deterministic)
83
+
84
+ Coverage is computed from data, not declared:
85
+
86
+ ```json
87
+ {
88
+ "coverage": {
89
+ "requirements": {
90
+ "total": 10,
91
+ "covered": 3,
92
+ "untested": 4,
93
+ "testedButNotPassing": 3,
94
+ "details": [
95
+ { "id": "REQ-F-001", "status": "COVERED", "tests": 2 },
96
+ { "id": "REQ-F-002", "status": "UNTESTED", "tests": 0 }
97
+ ]
98
+ }
99
+ }
100
+ }
101
+ ```
102
+
103
+ Rules:
104
+
105
+ - **Uncovered**: No linked tests exist
106
+ - **Tested but not passing**: Tests exist but evidence is `FAIL` or `NOT_PROVEN`
107
+ - **Covered**: All acceptance criteria have passing evidence
108
+
109
+ ### 4. Test suite structure
110
+
111
+ | Test file | Scope | Status |
112
+ |---|---|---|
113
+ | `tests/schema*.test.mjs` | JSON Schema validation | **new** |
114
+ | `tests/links*.test.mjs` | Link resolution | **new** |
115
+ | `tests/coverage*.test.mjs` | Coverage computation | **new** |
116
+ | `tests/generation*.test.mjs` | Markdown generation | **new** |
117
+ | `tests/requirements*.test.mjs` | Requirement registry | **new** |
118
+ | `tests/traceability*.test.mjs` | Traceability chain | **new** |
119
+ | Existing tests | CLI, workflow, evidence, etc. | **existing, pass** |
120
+
121
+ ### 5. Compatibility rules
122
+
123
+ - **Existing tests must pass** (44/44)
124
+ - **No existing test is deleted**
125
+ - **New tests are additive**
126
+ - **CLI commands respect existing exit codes** (0=success, 1=failure/blocked, 2=conflict)
127
+
128
+ ### 6. Validation API (proposed CLI)
129
+
130
+ ```bash
131
+ # Validate artefact
132
+ aidf validate artefact requirements.json [--json]
133
+
134
+ # Validate all artefacts
135
+ aidf validate all [--json]
136
+
137
+ # Check link integrity
138
+ aidf validate links [--json]
139
+
140
+ # Compute coverage
141
+ aidf validate coverage [--json]
142
+ ```
143
+
144
+ ## Consequences
145
+
146
+ ### Positive
147
+
148
+ - Deterministic validation (no LLM or approximation)
149
+ - Link integrity enforced
150
+ - Coverage is computed, not declared
151
+ - Existing tests preserved
152
+
153
+ ### Negative
154
+
155
+ - More test files to maintain
156
+ - Schema evolution required for breaking changes
157
+
158
+ ### Neutral
159
+
160
+ - Validation is separate from execution
161
+ - Tests are additive, never destructive
162
+
163
+ ## Status
164
+
165
+ **proposed** — awaiting human validation before implementation.
166
+
167
+ ## Next steps
168
+
169
+ - If approved: implement JSON schemas, validation, link resolution, coverage
170
+ - Tests required: schema validation, link resolution, coverage computation, generation reproducibility