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.
- package/CHANGELOG.md +174 -0
- package/INSTALLATION.md +140 -0
- package/LICENSE +21 -0
- package/QODER.md +88 -0
- package/README.md +142 -2
- package/UTILISATION.md +188 -0
- package/assets/adapters/qoder/agents/aidf-orchestrator.md +30 -0
- package/assets/adapters/qoder/rules/00-core.md +28 -0
- package/assets/adapters/qoder/rules/10-security.md +33 -0
- package/assets/adapters/qoder/rules/20-context.md +39 -0
- package/assets/core/AGENTS.fragment.md +18 -0
- package/assets/core/AIDF.md +107 -0
- package/assets/docs/APPFLOW.md +66 -0
- package/assets/docs/BACKEND.md +71 -0
- package/assets/docs/CHANGELOG.md +25 -0
- package/assets/docs/CONVENTIONS.md +95 -0
- package/assets/docs/DECISIONS.md +60 -0
- package/assets/docs/PLAN.md +53 -0
- package/assets/docs/PRD.md +88 -0
- package/assets/docs/SECURITY.md +94 -0
- package/assets/docs/TRD.md +78 -0
- package/assets/docs/UI-UX.md +71 -0
- package/assets/docs/constitution.md +86 -0
- package/assets/hooks/audit.mjs +45 -0
- package/assets/hooks/session-context.mjs +53 -0
- package/assets/integrations/spec-kit/mapping.yaml +92 -0
- package/assets/knowledge/best-practices/testing.md +53 -0
- package/assets/knowledge/best-practices/web-dev-baseline.md +39 -0
- package/assets/knowledge/rules/api.md +45 -0
- package/assets/knowledge/rules/sql.md +44 -0
- package/assets/knowledge/rules/typescript.md +50 -0
- package/assets/knowledge/security-references/owasp-baseline.md +58 -0
- package/assets/registry/activation-map.yaml +83 -0
- package/assets/registry/dependencies.yaml +35 -0
- package/assets/registry/skills.yaml +541 -0
- package/assets/registry/sources.yaml +396 -0
- package/assets/schemas/architecture/v1.json +110 -0
- package/assets/schemas/constraints/v1.json +93 -0
- package/assets/schemas/decision/v1.json +106 -0
- package/assets/schemas/discovery/v1.json +91 -0
- package/assets/schemas/requirement/v1.json +136 -0
- package/assets/schemas/security/threat-model/v1.json +127 -0
- package/assets/schemas/test-plan/v1.json +108 -0
- package/assets/skills/aidf-architecture-review/SKILL.md +49 -0
- package/assets/skills/aidf-backend-implementation/SKILL.md +47 -0
- package/assets/skills/aidf-database-design/SKILL.md +48 -0
- package/assets/skills/aidf-devops-engineering/SKILL.md +41 -0
- package/assets/skills/aidf-documentation-maintenance/SKILL.md +41 -0
- package/assets/skills/aidf-frontend-implementation/SKILL.md +44 -0
- package/assets/skills/aidf-phase-transition/SKILL.md +48 -0
- package/assets/skills/aidf-product-analysis/SKILL.md +47 -0
- package/assets/skills/aidf-project-context/SKILL.md +57 -0
- package/assets/skills/aidf-requirements-engineering/SKILL.md +52 -0
- package/assets/skills/aidf-security-review/SKILL.md +57 -0
- package/assets/skills/aidf-testing-validation/SKILL.md +48 -0
- package/assets/skills/aidf-ui-ux-implementation/SKILL.md +43 -0
- package/assets/workflows/gates.yaml +232 -0
- package/assets/workflows/phases.yaml +161 -0
- package/bin/aidf.mjs +12 -0
- package/demo/run-demo.mjs +97 -0
- package/docs/aidf/ADR-001-artefacts-architectur.md +126 -0
- package/docs/aidf/ADR-002-requirements-registry.md +145 -0
- package/docs/aidf/ADR-003-traceability-chain.md +145 -0
- package/docs/aidf/ADR-004-markdown-generation.md +134 -0
- package/docs/aidf/ADR-005-validation-and-tests.md +170 -0
- package/docs/aidf/ADR-006-cli-commands.md +189 -0
- package/docs/aidf/ADR-007-compatibility-and-migration.md +119 -0
- package/docs/aidf/ADR-008-schema-versioning.md +115 -0
- package/docs/aidf/ADR-009-artefacts-scope.md +84 -0
- package/docs/aidf/ARCHITECTURE.md +137 -0
- package/docs/aidf/COMPATIBILITY.md +90 -0
- package/docs/aidf/DECISIONS.md +200 -0
- package/docs/aidf/FRAMEWORK.md +38 -0
- package/docs/aidf/IDE-QODER.md +61 -0
- package/docs/aidf/INSTALL.md +99 -0
- package/docs/aidf/INVENTORY.md +72 -0
- package/docs/aidf/L1-ARCHITECTURE-RAPPORT.md +353 -0
- package/docs/aidf/LIMITATIONS.md +69 -0
- package/docs/aidf/MATRICE-0.1.0-vers-0.2.0.md +155 -0
- package/docs/aidf/SECURITY.md +86 -0
- package/docs/aidf/SKILLS.md +78 -0
- package/docs/aidf/SPECKIT.md +67 -0
- package/docs/aidf/USAGE.md +113 -0
- package/docs/aidf/VALIDATION.md +55 -0
- package/package.json +37 -4
- package/src/cli.mjs +148 -0
- package/src/commands/artefacts.mjs +129 -0
- package/src/commands/config.mjs +130 -0
- package/src/commands/context.mjs +55 -0
- package/src/commands/decision.mjs +142 -0
- package/src/commands/design.mjs +141 -0
- package/src/commands/docs.mjs +133 -0
- package/src/commands/doctor.mjs +210 -0
- package/src/commands/evidence.mjs +178 -0
- package/src/commands/install.mjs +154 -0
- package/src/commands/release.mjs +214 -0
- package/src/commands/requirements.mjs +196 -0
- package/src/commands/resources.mjs +181 -0
- package/src/commands/scan.mjs +139 -0
- package/src/commands/security.mjs +97 -0
- package/src/commands/setup.mjs +68 -0
- package/src/commands/skills.mjs +204 -0
- package/src/commands/speckit.mjs +78 -0
- package/src/commands/tests.mjs +81 -0
- package/src/commands/traceability.mjs +116 -0
- package/src/commands/uninstall.mjs +238 -0
- package/src/commands/validate.mjs +84 -0
- package/src/commands/workflow.mjs +137 -0
- package/src/core/adapters/base.mjs +32 -0
- package/src/core/adapters/generic.mjs +70 -0
- package/src/core/adapters/index.mjs +24 -0
- package/src/core/adapters/opencode.mjs +115 -0
- package/src/core/adapters/qoder.mjs +228 -0
- package/src/core/artefacts/index.mjs +1 -0
- package/src/core/artefacts/validation.mjs +161 -0
- package/src/core/bootstrap.mjs +179 -0
- package/src/core/config.mjs +123 -0
- package/src/core/context.mjs +187 -0
- package/src/core/design-engineering/complexity-classifier.mjs +78 -0
- package/src/core/design-engineering/engine.mjs +197 -0
- package/src/core/design-engineering/fallback/mockups.mjs +221 -0
- package/src/core/design-engineering/fallback/wireframes.mjs +114 -0
- package/src/core/design-engineering/figma/validators.mjs +178 -0
- package/src/core/design-engineering/index.mjs +9 -0
- package/src/core/design-engineering/visual-parity/capture.mjs +172 -0
- package/src/core/detect.mjs +220 -0
- package/src/core/docsgen.mjs +175 -0
- package/src/core/evidence.mjs +210 -0
- package/src/core/installer.mjs +377 -0
- package/src/core/manifest.mjs +53 -0
- package/src/core/paths.mjs +94 -0
- package/src/core/requirements/index.mjs +13 -0
- package/src/core/requirements/registry.mjs +234 -0
- package/src/core/resource-inventory.mjs +434 -0
- package/src/core/resources.mjs +280 -0
- package/src/core/security/threat-model.mjs +235 -0
- package/src/core/skills.mjs +353 -0
- package/src/core/source-skills.mjs +213 -0
- package/src/core/speckit.mjs +195 -0
- package/src/core/technology-decision/analyzer-deterministic.mjs +240 -0
- package/src/core/technology-decision/engine.mjs +157 -0
- package/src/core/technology-decision/generator.mjs +204 -0
- package/src/core/technology-decision/index.mjs +17 -0
- package/src/core/technology-decision/options/index.mjs +10 -0
- package/src/core/testplan.mjs +176 -0
- package/src/core/traceability/chain.mjs +488 -0
- package/src/core/traceability/index.mjs +12 -0
- package/src/core/workflow.mjs +471 -0
- package/src/util/args.mjs +69 -0
- package/src/util/frontmatter.mjs +26 -0
- package/src/util/fsx.mjs +208 -0
- package/src/util/logger.mjs +74 -0
- package/src/util/text.mjs +66 -0
- 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
|