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,189 @@
|
|
|
1
|
+
# ADR-006 — CLI Commands
|
|
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 18 CLI commands:
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
init, install, update, uninstall, setup, resources, doctor, scan,
|
|
14
|
+
skills, workflow, validate, evidence, docs, context, speckit, config, version, help
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
L1 introduces canonical JSON artefacts and new features that require CLI commands. The question is: add new commands or extend existing ones?
|
|
18
|
+
|
|
19
|
+
## Decision
|
|
20
|
+
|
|
21
|
+
**Minimize new commands**. Prefer extending existing commands when the functionality fits their scope. Add new commands only when:
|
|
22
|
+
|
|
23
|
+
1. The scope is distinct and large enough to justify a new command
|
|
24
|
+
2. The command would otherwise grow too complex
|
|
25
|
+
3. The command has a clear user-facing workflow
|
|
26
|
+
|
|
27
|
+
### Command matrix
|
|
28
|
+
|
|
29
|
+
| Feature | Command | Reason |
|
|
30
|
+
|---|---|---|---|
|
|
31
|
+
| List requirements | `requirements list` | New command (large scope) |
|
|
32
|
+
| Show requirement | `requirements show <id>` | New command |
|
|
33
|
+
| Add requirement | `requirements add` | New command |
|
|
34
|
+
| Update requirement | `requirements update <id>` | New command |
|
|
35
|
+
| Delete requirement | `requirements delete <id>` | New command |
|
|
36
|
+
| Link to tests | `requirements link <id>` | New command |
|
|
37
|
+
| Compute coverage | `requirements coverage` | New command |
|
|
38
|
+
| Validate artefact | `artefacts validate` | New command |
|
|
39
|
+
| List artefacts | `artefacts list` | New command |
|
|
40
|
+
| Generate Markdown | `docs generate` | Extend `docs` |
|
|
41
|
+
| Detect divergence | `docs check` | Extend `docs` |
|
|
42
|
+
| Regenerate Markdown | `docs regenerate` | Extend `docs` |
|
|
43
|
+
| Traceability report | `traceability report` | New command |
|
|
44
|
+
| Missing links | `traceability missing` | New command |
|
|
45
|
+
| Verify chain | `traceability verify <id>` | New command |
|
|
46
|
+
|
|
47
|
+
### Proposed new commands
|
|
48
|
+
|
|
49
|
+
#### `artefacts` (new command)
|
|
50
|
+
|
|
51
|
+
Manage canonical artefacts (requirements, decisions, test-plan, etc.)
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# List all artefacts
|
|
55
|
+
aidf artefacts list [--json]
|
|
56
|
+
|
|
57
|
+
# Show artefact details
|
|
58
|
+
aidf artefacts show <id> [--json]
|
|
59
|
+
|
|
60
|
+
# Validate artefact
|
|
61
|
+
aidf artefacts validate <path> [--json]
|
|
62
|
+
|
|
63
|
+
# Validate all artefacts
|
|
64
|
+
aidf artefacts validate-all [--json]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
#### `requirements` (new command)
|
|
68
|
+
|
|
69
|
+
Manage requirements registry
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
# List requirements
|
|
73
|
+
aidf requirements list [--type F|NF] [--status <status>] [--json]
|
|
74
|
+
|
|
75
|
+
# Show requirement
|
|
76
|
+
aidf requirements show <id> [--json]
|
|
77
|
+
|
|
78
|
+
# Add requirement
|
|
79
|
+
aidf requirements add --id <id> --type F|NF --title <title> --desc <desc> [--priority must|should|could] [--acceptance <criterion>] [--link <targetId>]
|
|
80
|
+
|
|
81
|
+
# Update requirement
|
|
82
|
+
aidf requirements update <id> [--title <new>] [--desc <new>] [--acceptance <new>] [--link <add|remove> <targetId>]
|
|
83
|
+
|
|
84
|
+
# Delete requirement (mark BLOCKED)
|
|
85
|
+
aidf requirements delete <id> [--yes]
|
|
86
|
+
|
|
87
|
+
# Link to tests
|
|
88
|
+
aidf requirements link <id> --test <path>#<test-name> [--type verified-by|implemented-by]
|
|
89
|
+
|
|
90
|
+
# Compute coverage
|
|
91
|
+
aidf requirements coverage [--json]
|
|
92
|
+
|
|
93
|
+
# Validate registry
|
|
94
|
+
aidf requirements validate [--json]
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
#### `traceability` (new command)
|
|
98
|
+
|
|
99
|
+
Manage and verify traceability chain
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# Report all broken chains
|
|
103
|
+
aidf traceability report [--json]
|
|
104
|
+
|
|
105
|
+
# Find requirements without design
|
|
106
|
+
aidf traceability missing --type design [--json]
|
|
107
|
+
|
|
108
|
+
# Find tests without evidence
|
|
109
|
+
aidf traceability missing --type evidence [--json]
|
|
110
|
+
|
|
111
|
+
# Verify chain for artefact
|
|
112
|
+
aidf traceability verify <id> [--json]
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
#### `docs` (extend existing command)
|
|
116
|
+
|
|
117
|
+
Add Markdown generation and divergence detection
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
# Existing: list documents
|
|
121
|
+
aidf docs list [--json]
|
|
122
|
+
|
|
123
|
+
# Existing: change document status
|
|
124
|
+
aidf docs status <doc> <status> [--by <name>] [--note <note>]
|
|
125
|
+
|
|
126
|
+
# NEW: generate JSON from Markdown
|
|
127
|
+
aidf docs generate <doc> [--json]
|
|
128
|
+
|
|
129
|
+
# NEW: detect divergences
|
|
130
|
+
aidf docs check [--json]
|
|
131
|
+
|
|
132
|
+
# NEW: regenerate Markdown (overwrites manual changes)
|
|
133
|
+
aidf docs regenerate <doc> [--yes]
|
|
134
|
+
|
|
135
|
+
# NEW: reconcile frozen document (requires approval)
|
|
136
|
+
aidf docs reconcile <doc> --by <name> [--note <note>]
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Exit codes
|
|
140
|
+
|
|
141
|
+
| Code | Meaning |
|
|
142
|
+
|---|---|
|
|
143
|
+
| `0` | Success |
|
|
144
|
+
| `1` | Failure/blocked (missing required parameter, artefact not found, invalid schema, etc.) |
|
|
145
|
+
| `2` | Conflict or contradiction (human approval required, frozen document, divergence, etc.) |
|
|
146
|
+
|
|
147
|
+
### `--json` support
|
|
148
|
+
|
|
149
|
+
All new commands support `--json` for machine-readable output.
|
|
150
|
+
|
|
151
|
+
### `--human --by <name>` support
|
|
152
|
+
|
|
153
|
+
Commands that modify artefacts support human accountability:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
# Regenerate Markdown requires human approval
|
|
157
|
+
aidf docs regenerate PRD --by "Jeremy"
|
|
158
|
+
|
|
159
|
+
# Delete requirement requires human approval
|
|
160
|
+
aidf requirements delete REQ-F-001 --by "Jeremy" --yes
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Consequences
|
|
164
|
+
|
|
165
|
+
### Positive
|
|
166
|
+
|
|
167
|
+
- Minimal new commands (only when scope justifies)
|
|
168
|
+
- Consistent with existing command patterns
|
|
169
|
+
- `--json` and `--human` support everywhere
|
|
170
|
+
- Exit codes preserved
|
|
171
|
+
|
|
172
|
+
### Negative
|
|
173
|
+
|
|
174
|
+
- New commands to learn
|
|
175
|
+
- CLI grows slightly
|
|
176
|
+
|
|
177
|
+
### Neutral
|
|
178
|
+
|
|
179
|
+
- Commands are additive, not replacing existing ones
|
|
180
|
+
- Existing commands unchanged
|
|
181
|
+
|
|
182
|
+
## Status
|
|
183
|
+
|
|
184
|
+
**proposed** — awaiting human validation before implementation.
|
|
185
|
+
|
|
186
|
+
## Next steps
|
|
187
|
+
|
|
188
|
+
- If approved: implement `artefacts`, `requirements`, `traceability`, extended `docs` commands
|
|
189
|
+
- Tests required: command parsing, execution, JSON output, human approval
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# ADR-007 — Compatibility and Migration
|
|
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 is already installed in many projects. L1 introduces canonical JSON artefacts. The question is: how do we migrate existing projects without breaking them?
|
|
11
|
+
|
|
12
|
+
## Decision
|
|
13
|
+
|
|
14
|
+
**L1 is additive only**. Never modify or delete existing AIDF 0.1.0 files.
|
|
15
|
+
|
|
16
|
+
### Migration rules
|
|
17
|
+
|
|
18
|
+
1. **No breaking changes to existing files**
|
|
19
|
+
- Never overwrite `.aidf/docs/*.md`
|
|
20
|
+
- Never delete `.aidf/config.json`
|
|
21
|
+
- Never modify `.aidf/manifest.json`
|
|
22
|
+
- Never delete existing artefacts
|
|
23
|
+
|
|
24
|
+
2. **New files are added**
|
|
25
|
+
- `.aidf/artefacts/` directory (new)
|
|
26
|
+
- `.aidf/artefacts/requirements.json` (new)
|
|
27
|
+
- `.aidf/artefacts/decisions/` (new)
|
|
28
|
+
- etc.
|
|
29
|
+
|
|
30
|
+
3. **Existing tests pass**
|
|
31
|
+
- All 44 existing tests must pass
|
|
32
|
+
- No existing test is deleted
|
|
33
|
+
- New tests are additive
|
|
34
|
+
|
|
35
|
+
4. **Install is idempotent**
|
|
36
|
+
- Re-running `aidf install` never overwrites existing artefacts
|
|
37
|
+
- Only adds missing artefacts
|
|
38
|
+
|
|
39
|
+
5. **No automatic migration of existing projects**
|
|
40
|
+
- Existing projects stay as-is (Markdown documents only)
|
|
41
|
+
- L1 features are opt-in
|
|
42
|
+
- No automatic conversion of existing documents
|
|
43
|
+
|
|
44
|
+
### Migration path for new projects
|
|
45
|
+
|
|
46
|
+
New projects using AIDF 0.2.0:
|
|
47
|
+
|
|
48
|
+
1. Install AIDF 0.2.0
|
|
49
|
+
2. Documents created in `.aidf/docs/`
|
|
50
|
+
3. User creates canonical JSON artefacts manually or via CLI
|
|
51
|
+
4. Link JSON artefacts to documents
|
|
52
|
+
5. Track coverage, tests, evidence
|
|
53
|
+
|
|
54
|
+
### Migration path for existing projects (optional)
|
|
55
|
+
|
|
56
|
+
Projects that want L1 features:
|
|
57
|
+
|
|
58
|
+
1. Install AIDF 0.2.0 (additive, no breaking changes)
|
|
59
|
+
2. Run `aidf docs check` (detects nothing to generate yet)
|
|
60
|
+
3. Manually create JSON artefacts OR use CLI to create new ones
|
|
61
|
+
4. Link JSON artefacts to existing documents
|
|
62
|
+
5. Gradually adopt L1 features
|
|
63
|
+
|
|
64
|
+
### Compatibility matrix
|
|
65
|
+
|
|
66
|
+
| Feature | AIDF 0.1.0 | AIDF 0.2.0 |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| CLI commands | 18 | 18 + 3 new |
|
|
69
|
+
| Artefact files | 11 Markdown | 11 Markdown + JSON artefacts |
|
|
70
|
+
| Tests | 44 | 44 + new tests |
|
|
71
|
+
| JSON artefacts | None | 7+ canonical artefacts |
|
|
72
|
+
| Link resolution | No | Yes |
|
|
73
|
+
| Coverage computation | No (manual) | Yes (deterministic) |
|
|
74
|
+
|
|
75
|
+
### Rollback
|
|
76
|
+
|
|
77
|
+
If L1 implementation needs rollback:
|
|
78
|
+
|
|
79
|
+
1. **Git ensures reversion** (commit 85f187a baseline)
|
|
80
|
+
2. **New files can be deleted**
|
|
81
|
+
3. **No existing files were modified**
|
|
82
|
+
4. **All existing tests still pass**
|
|
83
|
+
|
|
84
|
+
### Compatibility verification
|
|
85
|
+
|
|
86
|
+
- All 44 existing tests pass
|
|
87
|
+
- No existing tests deleted
|
|
88
|
+
- New tests additive only
|
|
89
|
+
- CLI exit codes preserved
|
|
90
|
+
- `--json` support maintained
|
|
91
|
+
- Existing commands unchanged
|
|
92
|
+
|
|
93
|
+
## Consequences
|
|
94
|
+
|
|
95
|
+
### Positive
|
|
96
|
+
|
|
97
|
+
- Existing projects unaffected
|
|
98
|
+
- Migration is opt-in and reversible
|
|
99
|
+
- No breaking changes
|
|
100
|
+
- Git ensures rollback
|
|
101
|
+
|
|
102
|
+
### Negative
|
|
103
|
+
|
|
104
|
+
- Dual file system (Markdown + JSON)
|
|
105
|
+
- User must opt-in to L1 features
|
|
106
|
+
|
|
107
|
+
### Neutral
|
|
108
|
+
|
|
109
|
+
- New files added under `.aidf/artefacts/`
|
|
110
|
+
- Old files remain in `.aidf/docs/`
|
|
111
|
+
|
|
112
|
+
## Status
|
|
113
|
+
|
|
114
|
+
**proposed** — awaiting human validation before implementation.
|
|
115
|
+
|
|
116
|
+
## Next steps
|
|
117
|
+
|
|
118
|
+
- If approved: implement additive-only changes, preserve all existing tests
|
|
119
|
+
- Tests required: install idempotency, no file overwrite, rollback verification
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# ADR-008 — Schema Versioning
|
|
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
|
+
JSON artefacts use schemas. The question is: how do we version schemas and handle schema evolution?
|
|
11
|
+
|
|
12
|
+
## Decision
|
|
13
|
+
|
|
14
|
+
### Schema versioning
|
|
15
|
+
|
|
16
|
+
Each artefact schema has an independent version:
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
{
|
|
20
|
+
"$schema": "https://aidf.dev/schemas/requirement/v1",
|
|
21
|
+
"id": "REQ-F-001",
|
|
22
|
+
"schemaVersion": "1.0.0",
|
|
23
|
+
...
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- **Schema version**: Independent of AIDF version
|
|
28
|
+
- **Artefact version**: Stored in `schemaVersion` field
|
|
29
|
+
- **AIDF version**: 0.2.0 (framework version)
|
|
30
|
+
|
|
31
|
+
### Schema location
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
.aidf/framework/
|
|
35
|
+
schemas/
|
|
36
|
+
requirement/
|
|
37
|
+
v1.json
|
|
38
|
+
v2.json
|
|
39
|
+
architecture/
|
|
40
|
+
v1.json
|
|
41
|
+
decisions/
|
|
42
|
+
v1.json
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Schema evolution
|
|
46
|
+
|
|
47
|
+
When a schema changes:
|
|
48
|
+
|
|
49
|
+
1. **Create new schema version** (v1 → v2)
|
|
50
|
+
2. **Keep old schema** (v1 still supported)
|
|
51
|
+
3. **Migration tool** converts v1 → v2 (optional, explicit)
|
|
52
|
+
4. **New artefacts use v2**
|
|
53
|
+
5. **Old artefacts remain v1** (no automatic migration)
|
|
54
|
+
|
|
55
|
+
### Migration strategy
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Dry-run migration
|
|
59
|
+
aidf artefacts migrate --dry-run [--from 1.0.0 --to 2.0.0]
|
|
60
|
+
|
|
61
|
+
# Execute migration
|
|
62
|
+
aidf artefacts migrate --to 2.0.0 [--yes]
|
|
63
|
+
|
|
64
|
+
# Rollback migration
|
|
65
|
+
aidf artefacts migrate --rollback [--yes]
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Backward compatibility
|
|
69
|
+
|
|
70
|
+
- **New schema version must be backward compatible**
|
|
71
|
+
- **Old AIDF versions can read new artefacts** (ignoring new fields)
|
|
72
|
+
- **New AIDF versions can read old artefacts** (applying defaults for missing fields)
|
|
73
|
+
|
|
74
|
+
### Validation
|
|
75
|
+
|
|
76
|
+
Each artefact is validated against its `schemaVersion`:
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"validation": {
|
|
81
|
+
"schemaVersion": "1.0.0",
|
|
82
|
+
"timestamp": "2026-11-20T...",
|
|
83
|
+
"valid": true,
|
|
84
|
+
"errors": [],
|
|
85
|
+
"warnings": []
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Consequences
|
|
91
|
+
|
|
92
|
+
### Positive
|
|
93
|
+
|
|
94
|
+
- Schema evolution without breaking changes
|
|
95
|
+
- Backward compatibility maintained
|
|
96
|
+
- Migration is explicit and controlled
|
|
97
|
+
|
|
98
|
+
### Negative
|
|
99
|
+
|
|
100
|
+
- More files (schema versions)
|
|
101
|
+
- Migration tool required
|
|
102
|
+
|
|
103
|
+
### Neutral
|
|
104
|
+
|
|
105
|
+
- Schema versions are independent
|
|
106
|
+
- AIDF supports multiple schema versions
|
|
107
|
+
|
|
108
|
+
## Status
|
|
109
|
+
|
|
110
|
+
**proposed** — awaiting human validation before implementation.
|
|
111
|
+
|
|
112
|
+
## Next steps
|
|
113
|
+
|
|
114
|
+
- If approved: implement schema versioning, migration tool, backward compatibility
|
|
115
|
+
- Tests required: schema validation, migration, backward compatibility
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# ADR-009 — Artefacts Scope
|
|
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
|
+
The question is: which artefacts do we include in L1? The answer depends on:
|
|
11
|
+
|
|
12
|
+
1. What AIDF needs to trace (requirements, decisions, tests, evidence)
|
|
13
|
+
2. What makes sense for the first iteration
|
|
14
|
+
3. What is minimal but complete
|
|
15
|
+
|
|
16
|
+
## Decision
|
|
17
|
+
|
|
18
|
+
### L1 canonical artefacts
|
|
19
|
+
|
|
20
|
+
| Artefact | File | Description | Priority |
|
|
21
|
+
|---|---|---|---|
|
|
22
|
+
| discovery | `.aidf/artefacts/discovery.json` | Project facts, constraints, resources | P0 |
|
|
23
|
+
| constraints | `.aidf/artefacts/constraints.json` | Non-negotiable limits | P0 |
|
|
24
|
+
| requirements | `.aidf/artefacts/requirements.json` | Requirement registry | P0 |
|
|
25
|
+
| architecture | `.aidf/artefacts/architecture.json` | Architecture decisions and model | P1 |
|
|
26
|
+
| decisions/ | `.aidf/artefacts/decisions/` | ADRs | P1 |
|
|
27
|
+
| test-plan | `.aidf/artefacts/test-plan.json` | Test strategy and test map | P1 |
|
|
28
|
+
| security/threat-model | `.aidf/artefacts/security/threat-model.json` | STRIDE threat model | P1 |
|
|
29
|
+
|
|
30
|
+
### Rationale
|
|
31
|
+
|
|
32
|
+
- **P0 (core)**: discovery, constraints, requirements — minimal required for L1
|
|
33
|
+
- **P1 (extended)**: architecture, decisions, test-plan, threat-model — can be added later
|
|
34
|
+
|
|
35
|
+
### Artefact dependencies
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
discovery → constraints → requirements → architecture → test-plan
|
|
39
|
+
↓
|
|
40
|
+
decisions
|
|
41
|
+
↓
|
|
42
|
+
security/threat-model
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Iterative approach
|
|
46
|
+
|
|
47
|
+
- **L1-A**: Design (ADR-001 to ADR-009)
|
|
48
|
+
- **L1-B**: Core artefacts (discovery, constraints, requirements)
|
|
49
|
+
- **L1-C**: Extended artefacts (architecture, decisions, test-plan, threat-model)
|
|
50
|
+
|
|
51
|
+
### Future artefacts (not in L1)
|
|
52
|
+
|
|
53
|
+
- codeSnippets/ (code examples)
|
|
54
|
+
- api-specs/ (OpenAPI, AsyncAPI)
|
|
55
|
+
- db-schema/ (database schemas)
|
|
56
|
+
- ci-cd/ (pipeline definitions)
|
|
57
|
+
|
|
58
|
+
These can be added in L2+ without breaking L1.
|
|
59
|
+
|
|
60
|
+
## Consequences
|
|
61
|
+
|
|
62
|
+
### Positive
|
|
63
|
+
|
|
64
|
+
- Minimal artefacts for first iteration
|
|
65
|
+
- Clear priority order
|
|
66
|
+
- Future artefacts can be added incrementally
|
|
67
|
+
|
|
68
|
+
### Negative
|
|
69
|
+
|
|
70
|
+
- Some features delayed to L2+
|
|
71
|
+
|
|
72
|
+
### Neutral
|
|
73
|
+
|
|
74
|
+
- artefacts are extensible
|
|
75
|
+
- New artefacts can be added without breaking changes
|
|
76
|
+
|
|
77
|
+
## Status
|
|
78
|
+
|
|
79
|
+
**proposed** — awaiting human validation before implementation.
|
|
80
|
+
|
|
81
|
+
## Next steps
|
|
82
|
+
|
|
83
|
+
- If approved: implement P0 artefacts (discovery, constraints, requirements) in L1-B
|
|
84
|
+
- P1 artefacts (architecture, decisions, test-plan, threat-model) deferred to L1-C
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# AIDF Architecture
|
|
2
|
+
|
|
3
|
+
Status: VALIDATED
|
|
4
|
+
Version: 0.1.0
|
|
5
|
+
Updated: 2026-10-31
|
|
6
|
+
|
|
7
|
+
## 1. Design goals and non-goals
|
|
8
|
+
|
|
9
|
+
AIDF is a governance layer installed *inside a project*, not a platform:
|
|
10
|
+
|
|
11
|
+
- It adapts to the host project (stack detected at install time, no architecture
|
|
12
|
+
is imposed).
|
|
13
|
+
- It never replaces the IDE, an existing cockpit, or project-owned files.
|
|
14
|
+
- Every file it writes is recorded in `.aidf/manifest.json` with a SHA-256.
|
|
15
|
+
- Every executable claim needs recorded evidence; otherwise the status is
|
|
16
|
+
`NOT_PROVEN`/`BLOCKED`.
|
|
17
|
+
|
|
18
|
+
Non-goals: package management, remote push, CI hosting, UI dashboards, and
|
|
19
|
+
secret handling (secrets are never read, only their filenames are listed).
|
|
20
|
+
|
|
21
|
+
## 2. Runtime model
|
|
22
|
+
|
|
23
|
+
- **Pure Node.js ESM, zero runtime dependencies** (rationale: DEC-006).
|
|
24
|
+
- Node >= 20.11 (tested on 24.21.0).
|
|
25
|
+
- YAML is handled by a small subset parser/dumper (`src/util/yaml.mjs`) that is
|
|
26
|
+
covered by tests; registries are YAML for human editing, machine state is JSON.
|
|
27
|
+
|
|
28
|
+
## 3. Module map
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
bin/aidf.mjs ──► src/cli.mjs (dispatcher, global flags, exit codes)
|
|
32
|
+
├─ src/commands/*.mjs (one file per command)
|
|
33
|
+
├─ src/core/paths.mjs (canonical layout + vocabularies)
|
|
34
|
+
├─ src/core/config.mjs (config schema + document statuses)
|
|
35
|
+
├─ src/core/manifest.mjs (ownership records)
|
|
36
|
+
├─ src/core/installer.mjs (action engine: write/copy/mkdir/
|
|
37
|
+
│ managed-block/merge-json/junction,
|
|
38
|
+
│ conflict + backup + dry-run)
|
|
39
|
+
├─ src/core/bootstrap.mjs (core install plan + launcher)
|
|
40
|
+
├─ src/core/detect.mjs (environment + project inventory)
|
|
41
|
+
├─ src/core/skills.mjs (discovery, validation, dependency
|
|
42
|
+
│ resolution, statuses, linking)
|
|
43
|
+
├─ src/core/resources.mjs (external resource inspection/lock)
|
|
44
|
+
├─ src/core/workflow.mjs (phases, gates, command runner)
|
|
45
|
+
├─ src/core/evidence.mjs (hash-chained evidence)
|
|
46
|
+
├─ src/core/context.mjs (task → documents + skills selection)
|
|
47
|
+
├─ src/core/speckit.mjs (Spec Kit status/init/sync)
|
|
48
|
+
├─ src/core/adapters/{base,qoder,generic}.mjs (IDE adapters)
|
|
49
|
+
└─ src/util/{args,fsx,frontmatter,logger,text,yaml}.mjs
|
|
50
|
+
assets/
|
|
51
|
+
adapters/qoder/ rules + orchestrator templates
|
|
52
|
+
core/ AIDF.md + AGENTS fragment
|
|
53
|
+
docs/ 11 project document templates
|
|
54
|
+
hooks/ session-context.mjs, audit.mjs
|
|
55
|
+
integrations/ spec-kit mapping.yaml
|
|
56
|
+
knowledge/ seeded rules (api, sql, typescript, testing, owasp baseline)
|
|
57
|
+
registry/ skills.yaml, dependencies.yaml, activation-map.yaml, sources.yaml
|
|
58
|
+
skills/ 13 first-party SKILL.md
|
|
59
|
+
workflows/ phases.yaml, gates.yaml
|
|
60
|
+
tests/ node:test suites (unit + CLI end-to-end)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## 4. Install layout inside a project
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
AGENTS.md managed block (user content preserved)
|
|
67
|
+
.qoder/rules/aidf-*.md adapter rules (qoder)
|
|
68
|
+
.qoder/skills/aidf-*/ adapter skills (qoder)
|
|
69
|
+
.qoder/agents/ orchestrator (qoder)
|
|
70
|
+
.qoder/settings.json hook entries merged, existing keys kept
|
|
71
|
+
.aidf/AIDF.md agent entry point
|
|
72
|
+
.aidf/config.json project + documents + security configuration
|
|
73
|
+
.aidf/manifest.json ownership, hashes, backups, history, links
|
|
74
|
+
.aidf/bin/aidf.mjs launcher → .aidf/framework/src/cli.mjs
|
|
75
|
+
.aidf/framework/ self-contained copy (update by re-running a newer dist)
|
|
76
|
+
.aidf/docs/ 11 documents with statuses
|
|
77
|
+
.aidf/registry/ skills.yaml, activation-map, dependencies, resources.lock
|
|
78
|
+
.aidf/workflows/ phases.yaml + gates.yaml (project-editable copies)
|
|
79
|
+
.aidf/evidence/ evidence records + index.json + hash chain
|
|
80
|
+
.aidf/state/ workflow.json, context snapshots
|
|
81
|
+
.aidf/knowledge/ curated rules + sources/index.yaml
|
|
82
|
+
.aidf/reports/ SCAN.md, install.md
|
|
83
|
+
.aidf/backups/ kept before overwriting managed files
|
|
84
|
+
.aidf/logs/ local-only JSONL command logs (.gitignore'd)
|
|
85
|
+
.aidf-uninstall-backup/ created only when uninstall --force removes edited files
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## 5. Action engine contract (`Installer`)
|
|
89
|
+
|
|
90
|
+
Actions: `mkdir`, `write`, `copy`, `managed-block`, `merge-json`, `junction`.
|
|
91
|
+
Status vocabulary: `CREATED`, `UPDATED`, `UNCHANGED`, `CONFLICT`, `LINKED`,
|
|
92
|
+
`FAILED`, and `WOULD_*` in dry-run. Invariants:
|
|
93
|
+
|
|
94
|
+
- A file not recorded in the manifest is never overwritten (`CONFLICT`).
|
|
95
|
+
- A manifest-recorded file modified locally is never overwritten (`CONFLICT`)
|
|
96
|
+
unless `--force`, which keeps a backup in `.aidf/backups/<timestamp>/`.
|
|
97
|
+
- Dry-run writes nothing (including logs).
|
|
98
|
+
- `merge-json` unions arrays and keeps existing keys.
|
|
99
|
+
- `managed-block` replaces only the exact AIDF block region.
|
|
100
|
+
- Paths go through `resolveInside` (rejects traversal, absolute paths, reserved
|
|
101
|
+
Windows names, and invalid characters).
|
|
102
|
+
|
|
103
|
+
## 6. Workflow and gates
|
|
104
|
+
|
|
105
|
+
Phases: `intake → discovery → specification → planning → implementation →
|
|
106
|
+
testing → security → release`. Each phase has `<phase>-entry` and
|
|
107
|
+
`<phase>-exit` gates in `assets/workflows/gates.yaml` with typed checks:
|
|
108
|
+
|
|
109
|
+
`file-exists`, `doc-status`, `evidence`, `command`, `previous-gate`, `manual`.
|
|
110
|
+
|
|
111
|
+
Status precedence in a gate: `FAIL > BLOCKED > NOT_PROVEN > PASS`;
|
|
112
|
+
`NOT_APPLICABLE` never blocks. Command checks execute only with `--allow-exec`
|
|
113
|
+
or `security.allowCommandExecution=true`, never through a shell
|
|
114
|
+
(`shell: false`, no operator allowed), and they record stdout/stderr, exit code
|
|
115
|
+
and duration in evidence.
|
|
116
|
+
|
|
117
|
+
## 7. Evidence and context
|
|
118
|
+
|
|
119
|
+
- Evidence records are JSON with `sha256` over their body, chained with
|
|
120
|
+
`previous = lastHash`; `aidf evidence verify` re-verifies every record.
|
|
121
|
+
- `doc-status`/gate statuses can require `humanApproval`; human records require
|
|
122
|
+
explicit `--by "<name>"`.
|
|
123
|
+
- The context assembler scores documents and skills from `activation-map.yaml`
|
|
124
|
+
(always-on, phase, keywords) and merges the project registry; contradiction-
|
|
125
|
+
sensitive documents that are `BLOCKED`/`OUTDATED` set the context status to
|
|
126
|
+
`BLOCKED` and exit code 2.
|
|
127
|
+
|
|
128
|
+
## 8. Extensibility
|
|
129
|
+
|
|
130
|
+
- New adapters: implement `plan/verify/detect` and register in
|
|
131
|
+
`src/core/adapters/index.mjs`; the CLI and registry code are adapter-agnostic
|
|
132
|
+
(`ide` field in `skills.yaml` filters compatibility).
|
|
133
|
+
- New skills: add `assets/skills/<name>/SKILL.md` + `assets/registry/skills.yaml`
|
|
134
|
+
entry + dependency entry; discovery, validation and statuses are generic.
|
|
135
|
+
- New external resources: add a `sources.yaml` entry; `aidf setup resources`
|
|
136
|
+
writes a reproducible lock file (`resources.lock.json`) with commit, tree
|
|
137
|
+
hash and licence decision.
|