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,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.