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,78 @@
1
+ # AIDF Skills
2
+
3
+ Status: VALIDATED
4
+
5
+ ## 1. Status vocabulary and lifecycle
6
+
7
+ ```
8
+ DISCOVERED file found on disk by the discovery walk
9
+ VALIDATED frontmatter and body pass Qoder constraints
10
+ REGISTERED present in .aidf/registry/skills.yaml
11
+ AVAILABLE VALIDATED and all dependencies AVAILABLE
12
+ BLOCKED file missing, duplicate, or dependencies not ready
13
+ INCOMPATIBLE frontmatter invalid or adapter not supported
14
+ ```
15
+
16
+ Constraints enforced (Qoder documented limits): `name` matches
17
+ `^[a-z0-9][a-z0-9-]{0,63}$`, `description` ≤ 1024 chars, frontmatter required,
18
+ directory name should match `name`.
19
+
20
+ ## 2. First-party catalog (installed by the qoder adapter)
21
+
22
+ | id | skill | phases | depends on |
23
+ |---|---|---|---|
24
+ | project-context | aidf-project-context | intake, discovery | — |
25
+ | product-analysis | aidf-product-analysis | intake, specification | project-context |
26
+ | requirements-engineering | aidf-requirements-engineering | specification, planning | product-analysis |
27
+ | architecture-review | aidf-architecture-review | discovery, planning | project-context |
28
+ | database-design | aidf-database-design | planning, implementation | architecture-review |
29
+ | ui-ux-implementation | aidf-ui-ux-implementation | specification, planning | requirements-engineering |
30
+ | frontend-implementation | aidf-frontend-implementation | implementation | ui-ux-implementation |
31
+ | backend-implementation | aidf-backend-implementation | implementation | architecture-review |
32
+ | testing-validation | aidf-testing-validation | implementation, testing | requirements-engineering |
33
+ | security-review | aidf-security-review | security, release | testing-validation |
34
+ | devops-engineering | aidf-devops-engineering | implementation, release | architecture-review |
35
+ | documentation-maintenance | aidf-documentation-maintenance | implementation, release | project-context |
36
+ | phase-transition | aidf-phase-transition | all | project-context, testing-validation |
37
+
38
+ Each SKILL.md carries: purpose, trigger list, documents it may update, hard
39
+ rules (e.g. "no PASS without evidence", "real tests, not mocks"), and
40
+ deliverables. Source files: `assets/skills/<name>/SKILL.md`.
41
+
42
+ ## 3. Context selection (how skills are picked)
43
+
44
+ `assets/registry/activation-map.yaml` defines three layers:
45
+
46
+ 1. **always-on**: `constitution` + `CONVENTIONS` documents, `project-context`
47
+ skill.
48
+ 2. **by phase**: the phase's `requiredDocuments` and `skills` (from
49
+ `assets/workflows/phases.yaml`) with weight 3.
50
+ 3. **by keyword**: 10 rules (api, database, ui, security, test, ci, refactor,
51
+ bug, docs, performance) with weight 2.
52
+
53
+ The assembler merges by id, sorts by priority, and caps (`context.maxSkills`,
54
+ default 5). If a contradiction-sensitive document (`SECURITY`, `TRD`,
55
+ `BACKEND`, `PRD`) is `BLOCKED` or `OUTDATED`, the whole context is `BLOCKED`.
56
+
57
+ ## 4. External skills
58
+
59
+ External skill locations are scanned read-only (`src/core/skills.mjs`):
60
+
61
+ - project `.qoder/skills`, `.aidf/skills`, `.claude/skills`, `.agent(s)/skills`,
62
+ - user `~/.qoder/skills`,
63
+ - locally cloned sources registered in `assets/registry/sources.yaml`
64
+ (mattpocock-skills, superpowers).
65
+
66
+ They are indexed (id, name, path, hash, status) and never copied. `aidf skills
67
+ link <id>` creates a junction into `.qoder/skills` for a specific external
68
+ skill when the IDE cannot see it. Duplicate names across roots are `BLOCKED`
69
+ rather than resolved silently.
70
+
71
+ ## 5. Adding a first-party skill
72
+
73
+ 1. Create `assets/skills/<aidf-name>/SKILL.md` (frontmatter + body).
74
+ 2. Add an entry in `assets/registry/skills.yaml` (id, description, phases,
75
+ triggers, `ide` compatibility).
76
+ 3. If it depends on others, add an entry in `assets/registry/dependencies.yaml`.
77
+ 4. Run `node --test "tests/*.test.mjs"`; `skills validate` must report all
78
+ 13 + 1 skills AVAILABLE with no cycles.
@@ -0,0 +1,67 @@
1
+ # AIDF ↔ GitHub Spec Kit
2
+
3
+ Status: VALIDATED against specify CLI 1.2.3 and spec-kit source 1.2.6.dev0
4
+
5
+ ## 1. Ownership model
6
+
7
+ AIDF owns **product-wide durable truth** (constitution, PRD, TRD, SECURITY,
8
+ CONVENTIONS, DECISIONS). Spec Kit owns **feature-level change artefacts**
9
+ (`specs/<feature>/spec.md`, `plan.md`, `tasks.md`). Each fact lives in exactly
10
+ one place; feature specs reference `.aidf/docs/PRD.md` requirement IDs (FR-…)
11
+ instead of restating them.
12
+
13
+ ## 2. Verified integration facts (2026-10-31)
14
+
15
+ - `specify init --here --integration qodercli --ignore-agent-tools
16
+ --non-interactive` succeeds in an empty directory (exit 0).
17
+ - It creates `.specify/` (`templates/`, `scripts/`, `scripts/powershell/`,
18
+ `memory/constitution.md`, `workflows/`, `init-options.json`,
19
+ `integrations/qodercli.manifest.json`) **without** touching `.aidf/`,
20
+ `AGENTS.md` or `.qoder/` content.
21
+ - It writes `.qoder/skills/speckit-*` (10 skills with hyphen names). The
22
+ documented `speckit.` (dot) variant also existed historically; both are
23
+ accepted by `specKitStatus`.
24
+ - In a directory that already contains AIDF, the same init fails with
25
+ “Current directory is not empty … Re-run with --force to merge into it”.
26
+
27
+ ## 3. AIDF command mapping
28
+
29
+ | AIDF command | What it runs / does |
30
+ |---|---|
31
+ | `aidf speckit status` | Reports `.specify` presence, templates, constitution sync state, detected `speckit-*` skills, CLI path/version. |
32
+ | `aidf speckit init` | Runs the init command above. Requires `--allow-exec`. If the project is not empty it is `BLOCKED` until `--specify-force` is passed (explicit opt-in for `--force`). |
33
+ | `aidf speckit sync --adopt` | Publishes the AIDF constitution as a generated copy: `<!-- AIDF:SOURCE-HASH:<sha256> -->` + body of `.aidf/docs/constitution.md`. |
34
+ | `aidf speckit sync` | Refreshes the copy when the source hash changed; reports `UNCHANGED` otherwise. |
35
+
36
+ Constitution sync states: `IN_SYNC`, `OUTDATED`, `EXTERNAL` (a constitution
37
+ without the AIDF marker), `NOT_APPLICABLE` (absent).
38
+
39
+ ## 4. Conflict rule (verified)
40
+
41
+ If `.specify/memory/constitution.md` exists without the AIDF hash marker
42
+ (e.g. freshly created by `specify init`, or customised by the team), `aidf
43
+ speckit sync` reports `CONFLICT` (exit 2) and never overwrites it. The human
44
+ must merge manually, move the file aside, or delete it knowingly.
45
+
46
+ ## 5. Document mapping (also written to `.specify/aidf/mapping.md`)
47
+
48
+ | AIDF document | Spec Kit artefact | Owner |
49
+ |---|---|---|
50
+ | constitution | `.specify/memory/constitution.md` | AIDF (copy-with-hash) |
51
+ | PRD | `specs/<feature>/spec.md` (requirements reference) | shared |
52
+ | TRD | `specs/<feature>/plan.md` | shared |
53
+ | APPFLOW | `specs/<feature>/spec.md` scenarios | shared |
54
+ | UI-UX | `specs/<feature>/design/` | shared |
55
+ | BACKEND | `specs/<feature>/contracts/` | shared |
56
+ | PLAN | `specs/<feature>/tasks.md` | shared |
57
+ | SECURITY | `specs/<feature>/checklists/security.md` | AIDF |
58
+ | CONVENTIONS | constitution/agent instructions | AIDF |
59
+
60
+ ## 6. How the two systems interlock
61
+
62
+ - AIDF gates are phase-level and durable; Spec Kit `/speckit-*` commands are
63
+ feature-level commands an agent may run during a feature.
64
+ - `implementation-exit` evidence can capture the same diff that a feature task
65
+ list tracks; no duplicated status fields.
66
+ - The generated constitution copy keeps the two tools from diverging on
67
+ project principles, with a verifiable source hash.
@@ -0,0 +1,113 @@
1
+ # AIDF Usage Guide — daily workflow
2
+
3
+ Status: VALIDATED
4
+
5
+ ## 0. Session start (human or agent)
6
+
7
+ ```powershell
8
+ node .aidf/bin/aidf.mjs doctor
9
+ node .aidf/bin/aidf.mjs workflow status
10
+ node .aidf/bin/aidf.mjs context --task "<request>"
11
+ ```
12
+
13
+ The context file (`.aidf/state/context/latest.md`) is the contract between the
14
+ human and the agent: it lists what to read, which skills to load, and any
15
+ contradictions. If it reports `BLOCKED` (exit code 2), the affected decisions
16
+ are frozen until the document is fixed or a human resolves the contradiction.
17
+
18
+ ## 1. The cycle
19
+
20
+ ```
21
+ intake → discovery → specification → planning → implementation → testing → security → release
22
+ ```
23
+
24
+ Move forward only through gates:
25
+
26
+ ```powershell
27
+ node .aidf/bin/aidf.mjs workflow enter <phase> # runs <phase>-entry gate
28
+ node .aidf/bin/aidf.mjs workflow exit <phase> # runs <phase>-exit gate
29
+ node .aidf/bin/aidf.mjs workflow next # enter the next phase
30
+ aidf validate --gate <gate-id> # evaluate any single gate
31
+ ```
32
+
33
+ Gates and their checks live in `.aidf/workflows/gates.yaml`; the column report
34
+ shows every check with `PASS / BLOCKED / FAIL / NOT_PROVEN / NOT_APPLICABLE`
35
+ and the reason.
36
+
37
+ ## 2. Evidence
38
+
39
+ Everything that supports a `PASS` is recorded under `.aidf/evidence/` as a
40
+ hash-chained JSON record:
41
+
42
+ ```powershell
43
+ aidf evidence add --type plan-approval --human --by "Jeremy" --note "approved plan v2"
44
+ aidf evidence capture --type implementation-change --note "auth module"
45
+ aidf evidence verify
46
+ ```
47
+
48
+ - `capture` lists the git diff/untracked files; it stores filenames only.
49
+ - Agent-declared evidence is stored but not treated as human approval.
50
+ - `doc-status` and gate checks can require `humanApproval`; without it the gate
51
+ becomes `BLOCKED`.
52
+
53
+ ## 3. Documents
54
+
55
+ ```powershell
56
+ aidf docs list
57
+ aidf docs show SECURITY
58
+ aidf docs status PRD VALIDATED --by "Jeremy"
59
+ aidf docs status UI-UX NOT_APPLICABLE --note "No UI in API-only phase"
60
+ ```
61
+
62
+ `VALIDATED` needs an accountable human (`--by`); `NOT_APPLICABLE` needs a
63
+ reason. Statuses are also written to the document frontmatter.
64
+
65
+ ## 4. Skills
66
+
67
+ ```powershell
68
+ aidf skills list
69
+ aidf skills show aidf-testing-validation
70
+ aidf skills validate # cycles, missing deps, compatibility
71
+ aidf skills refresh # rebuild .aidf/registry/skills.yaml
72
+ aidf skills link <id> # link an external skill into .qoder/skills
73
+ ```
74
+
75
+ 13 first-party skills exist; never load them all — the context command selects
76
+ by phase and keywords.
77
+
78
+ ## 5. Command execution policy
79
+
80
+ Command checks (e.g. the `test` gate check) only execute when the project
81
+ explicitly allows it:
82
+
83
+ ```powershell
84
+ aidf config set security.allowCommandExecution true # project-wide
85
+ aidf validate --phase testing --kind exit --allow-exec # one-shot
86
+ ```
87
+
88
+ In both cases the runner is shell-free, rejects shell operators, and records
89
+ the command, exit code, duration and captured output in evidence.
90
+
91
+ ## 6. Spec Kit usage
92
+
93
+ ```powershell
94
+ aidf speckit status
95
+ aidf speckit init --allow-exec [--specify-force]
96
+ aidf speckit sync [--adopt]
97
+ ```
98
+
99
+ - Feature-level work still uses `/speckit-*` commands from Spec Kit.
100
+ - Feature specs must reference `.aidf/docs/PRD.md` requirement IDs instead of
101
+ restating them.
102
+ - The mapping contract is written to `.specify/aidf/mapping.md`.
103
+
104
+ ## 7. Troubleshooting quick table
105
+
106
+ | Symptom | Cause | Action |
107
+ |---|---|---|
108
+ | `doctor` exit 1 | a FAIL check | read the check row and its `detail` |
109
+ | install `conflicts=1` | managed file edited locally | merge manually or `--force` (backup kept) |
110
+ | gate `BLOCKED` | missing evidence with human approval | `aidf evidence add --human --by …` |
111
+ | context `BLOCKED` | contradiction-sensitive doc `BLOCKED`/`OUTDATED` | fix the document or record a decision |
112
+ | `speckit init` BLOCKED | project dir not empty | add `--specify-force` (explicit opt-in) |
113
+ | `speckit sync` exit 2 | Spec Kit constitution is not AIDF-generated | merge manually; AIDF never overwrites |
@@ -0,0 +1,55 @@
1
+ # AIDF Validation Record
2
+
3
+ Date: 2026-10-31 (Europe/Paris)
4
+ Toolchain: Node v24.21.0, `node --test` built-in runner.
5
+ Scope: AIDF 0.1.0 framework code + installation into two real scratch projects.
6
+
7
+ ## 1. Test suites (all executed)
8
+
9
+ | Suite | Coverage | Result |
10
+ |---|---|---|
11
+ | `tests/yaml.test.mjs` | subset parser/dumper: maps, sequences, inline arrays, quoted values, block scalars `|`/`>`/`|-`, comments, roundtrip, rejection of malformed input, real `gates.yaml` (16 gates) and `skills.yaml` (13 skills) | PASS (6 tests) |
12
+ | `tests/paths.test.mjs` | `resolveInside` traversal/absolute/reserved-name/invalid-character rejection; managed block replace/remove; `deepMerge`; `slugify`; `truncate` | PASS (8 tests) |
13
+ | `tests/installer.test.mjs` | action engine: create/update-idempotence, unmanaged file preserved (CONFLICT), edited managed file preserved (CONFLICT), `--force` with backup, dry-run writes nothing, mkdir idempotent, managed block preserves user text, merge-json keeps keys/arrays, summary | PASS (9 tests) |
14
+ | `tests/skills.test.mjs` | skill validation rules (name/name-length/description 1024/duplicates); full registry build → 13 AVAILABLE with hashes; dependency cycle detection; catalog consistency | PASS (6 tests) |
15
+ | `tests/adapters.test.mjs` | registry, Qoder plan artifact set (3 rules + 13 skills + agent + hooks + settings merge), verify = CONTRACT-PROVEN with runtime checks NOT_PROVEN, failure on missing rule, generic adapter | PASS (5 tests) |
16
+ | `tests/cli.test.mjs` | end-to-end via spawned `bin/aidf.mjs`: dry-run (no side effects), install, AGENTS.md preservation, doctor JSON, scan --record with `.env` name-only, skills validate, context, intake-entry gate, config set/get, speckit status, resources inspect, uninstall refusal/dry-run/real + restoration of AGENTS.md & existing rule | PASS (1 test) |
17
+ | **Total** | | **43/43 PASS** |
18
+
19
+ ## 2. Real-project installation matrix (executed)
20
+
21
+ | Project setup | Actions verified | Result |
22
+ |---|---|---|
23
+ | demo project: existing `AGENTS.md`, `.qoder/rules/existing.md`, `package.json`, `.env` | install dry-run → 131 WOULD_* / 0 write; install → 132 CREATED; idempotent re-run → `created=0 updated=0 unchanged=133`; edited rule → CONFLICT preserved, exit 2; `--force` not needed (content kept) | PASS |
24
+ | demo: `aidf doctor` (installed launcher) | config/manifest/documents/adapter/skills/spec-kit/evidence-integrity/workflow/security checks; `CONTRACT-PROVEN 5/8`, 3 runtime NOT_PROVEN warnings shown | PASS |
25
+ | demo: `scan --record` → `.aidf/reports/SCAN.md` + evidence; `skills validate` PASS (0 external in temp dir); `workflow status`; `context` assembled BACKEND/SECURITY + 5 skills AVAILABLE; `validate --gate intake-entry` PASS with evidence hash | PASS |
26
+ | AIDF+Spec Kit project (`aidf-speckit`) | `speckit status` PRESENT, EXTERNAL constitution, 10 speckit-* skills detected after fix; `speckit sync` → CONFLICT (no overwrite), mapping.md created, exit 2 | PASS |
27
+ | fresh-with-AIDF project (`aidf-speckit-init`, `-force`) | `speckit init` without flag → BLOCKED (non-empty); with `--specify-force` → CREATED via `specify init … --force`; `--force` merge verified additive (AGENTS.md 1066 bytes intact, `.aidf/`, `.qoder/` intact) | PASS |
28
+ | constitution sync roundtrip (`aidf-speckit-force`) | original moved aside → `sync --adopt` CREATED; re-sync → UNCHANGED; source edited → UPDATED; status → IN_SYNC (hash marker verified) | PASS |
29
+
30
+ ## 3. Chain-of-trust checks executed on real runs
31
+
32
+ - `aidf evidence verify` / doctor `evidence-integrity`: all recorded evidence
33
+ re-hashed OK (index `previous` → record `hash` chain intact).
34
+ - `doctor --json` returns machine-readable checks; exit codes 0 (success),
35
+ 1 (refusal), and 2 (conflicts) observed as designed (uninstall conflicts,
36
+ speckit sync conflict, context BLOCKED path logic).
37
+
38
+ ## 4. Explicitly NOT proven in this run (manual/IDE checks)
39
+
40
+ | Item | Why not proven by files | Required evidence |
41
+ |---|---|---|
42
+ | Qoder rule activation (Always Apply) | UI setting, not encoded in files | human sets it; `aidf evidence add --human --by …` |
43
+ | Qoder `/skills` runtime discovery | requires a live IDE session | screenshot/listing from `/skills` |
44
+ | Hook execution in Qoder runtime | hooks fire inside the IDE, not from the CLI | an edit writes `.aidf/logs/audit-<date>.jsonl` then human confirms |
45
+ | `npm publish` / remote push compatibility | intentionally not exercised (no authorization) | N/A for 0.1.0 |
46
+
47
+ ## 5. Exit-code contract verification
48
+
49
+ | Scenario | Observed |
50
+ |---|---|
51
+ | `aidf doctor` on healthy install | exit 0 |
52
+ | `aidf speckit init` without permission | exit 1 (BLOCKED) |
53
+ | `aidf uninstall` without `--yes` | exit 1 (refusal) |
54
+ | install with 1 conflict | exit 2 |
55
+ | `aidf speckit sync` over external constitution | exit 2 (CONFLICT preserved) |
package/package.json CHANGED
@@ -1,6 +1,39 @@
1
1
  {
2
2
  "name": "framework-aidf",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "AI Development Framework - a portable, governable development environment for AI-assisted software delivery",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "bin": {
8
+ "aidf": "bin/aidf.mjs"
9
+ },
10
+ "engines": {
11
+ "node": ">=20.11.0"
12
+ },
13
+ "files": [
14
+ "bin",
15
+ "src",
16
+ "assets",
17
+ "docs",
18
+ "demo",
19
+ "README.md",
20
+ "INSTALLATION.md",
21
+ "UTILISATION.md",
22
+ "QODER.md",
23
+ "CHANGELOG.md",
24
+ "LICENSE"
25
+ ],
26
+ "scripts": {
27
+ "test": "node --test \"tests/**/*.test.mjs\"",
28
+ "demo": "node demo/run-demo.mjs",
29
+ "doctor": "node bin/aidf.mjs doctor"
30
+ },
31
+ "keywords": [
32
+ "ai",
33
+ "coding-agent",
34
+ "governance",
35
+ "spec-driven-development",
36
+ "qoder",
37
+ "spec-kit"
38
+ ]
39
+ }
package/src/cli.mjs ADDED
@@ -0,0 +1,148 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * AIDF command dispatcher.
4
+ *
5
+ * Global flags are extracted before the command parses its own arguments so a
6
+ * command can never silently ignore `--json`. Every command returns an exit
7
+ * code: 0 success, 1 failure/blocked, 2 conflicts or contradictions.
8
+ */
9
+ import { createLogger } from './util/logger.mjs';
10
+ import { FRAMEWORK_ROOT, AIDF_VERSION } from './core/paths.mjs';
11
+ import { ADAPTER_KEYS } from './core/adapters/index.mjs';
12
+
13
+ import { installCommand, initCommand, updateCommand } from './commands/install.mjs';
14
+ import { uninstallCommand } from './commands/uninstall.mjs';
15
+ import { setupCommand } from './commands/setup.mjs';
16
+ import { resourcesCommand } from './commands/resources.mjs';
17
+ import { doctorCommand } from './commands/doctor.mjs';
18
+ import { scanCommand } from './commands/scan.mjs';
19
+ import { skillsCommand } from './commands/skills.mjs';
20
+ import { workflowCommand } from './commands/workflow.mjs';
21
+ import { validateCommand } from './commands/validate.mjs';
22
+ import { evidenceCommand } from './commands/evidence.mjs';
23
+ import { docsCommand } from './commands/docs.mjs';
24
+ import { contextCommand } from './commands/context.mjs';
25
+ import { speckitCommand } from './commands/speckit.mjs';
26
+ import { configCommand } from './commands/config.mjs';
27
+ import { artefactsCommand } from './commands/artefacts.mjs';
28
+ import { requirementsCommand } from './commands/requirements.mjs';
29
+ import { traceabilityCommand } from './commands/traceability.mjs';
30
+ import { decisionCommand } from './commands/decision.mjs';
31
+ import { designCommand } from './commands/design.mjs';
32
+ import { securityCommand } from './commands/security.mjs';
33
+ import { testsCommand } from './commands/tests.mjs';
34
+ import { releaseCommand } from './commands/release.mjs';
35
+
36
+ const COMMANDS = {
37
+ init: { run: initCommand, summary: 'Install AIDF into a project (alias of install).' },
38
+ install: { run: installCommand, summary: 'Install or refresh AIDF in a project.' },
39
+ update: { run: updateCommand, summary: 'Re-apply the current AIDF version without losing project files.' },
40
+ uninstall: { run: uninstallCommand, summary: 'Remove AIDF-managed files, preserving project-owned files.' },
41
+ setup: { run: setupCommand, summary: 'Prepare optional resources (setup resources).' },
42
+ resources: { run: resourcesCommand, summary: 'Inspect indexed external resources.' },
43
+ doctor: { run: doctorCommand, summary: 'Verify the installation, adapter contract and evidence integrity.' },
44
+ scan: { run: scanCommand, summary: 'Inventory the real project and environment.' },
45
+ skills: { run: skillsCommand, summary: 'List, validate, show or link skills.' },
46
+ workflow: { run: workflowCommand, summary: 'Show phases and move through gates.' },
47
+ validate: { run: validateCommand, summary: 'Evaluate a phase gate and record evidence.' },
48
+ evidence: { run: evidenceCommand, summary: 'Record, list and verify evidence.' },
49
+ docs: { run: docsCommand, summary: 'List documents and change their status.' },
50
+ context: { run: contextCommand, summary: 'Assemble the minimum context for a task.' },
51
+ speckit: { run: speckitCommand, summary: 'Inspect, initialise or sync GitHub Spec Kit.' },
52
+ config: { run: configCommand, summary: 'Read or change project configuration.' },
53
+ artefacts: { run: artefactsCommand, summary: 'List, show, validate or verify structured artefacts.' },
54
+ requirements: { run: requirementsCommand, summary: 'Manage the requirements registry and coverage.' },
55
+ traceability: { run: traceabilityCommand, summary: 'Traceability report, chain verification and link checks.' },
56
+ decision: { run: decisionCommand, summary: 'Evaluate a technology decision (deterministic engine).' },
57
+ design: { run: designCommand, summary: 'Classify complexity and run the design workflow.' },
58
+ security: { run: securityCommand, summary: 'Generate and inspect the STRIDE threat model artefact.' },
59
+ tests: { run: testsCommand, summary: 'Generate a test plan artefact and report requirement coverage.' },
60
+ release: { run: releaseCommand, summary: 'Build a release readiness report from gates, docs and evidence.' },
61
+ version: { run: versionCommand, summary: 'Print the AIDF version.' },
62
+ help: { run: helpCommand, summary: 'Show this help.' },
63
+ };
64
+
65
+ function versionCommand() {
66
+ process.stdout.write(`${AIDF_VERSION}\n`);
67
+ return 0;
68
+ }
69
+
70
+ function helpCommand(argv, ctx) {
71
+ const lines = [];
72
+ lines.push(`AIDF ${AIDF_VERSION} — AI Development Framework`);
73
+ lines.push('');
74
+ lines.push('Usage: aidf <command> [options]');
75
+ lines.push('');
76
+ lines.push('Commands:');
77
+ const width = Math.max(...Object.keys(COMMANDS).map((k) => k.length));
78
+ for (const [name, entry] of Object.entries(COMMANDS)) {
79
+ lines.push(` ${name.padEnd(width)} ${entry.summary}`);
80
+ }
81
+ lines.push('');
82
+ lines.push(`Adapters: ${ADAPTER_KEYS.join(', ')}`);
83
+ lines.push('Global flags: --json, --version, --help');
84
+ lines.push('');
85
+ lines.push('Examples:');
86
+ lines.push(' aidf install --adapter qoder --with-hooks');
87
+ lines.push(' aidf context --task "add invoice export"');
88
+ lines.push(' aidf validate --phase testing --kind exit --allow-exec');
89
+ lines.push(' aidf workflow enter implementation');
90
+ lines.push('');
91
+ process.stdout.write(`${lines.join('\n')}\n`);
92
+ return 0;
93
+ }
94
+
95
+ function extractGlobals(argv) {
96
+ const globals = { json: false, quiet: false, debug: false, version: false };
97
+ const rest = [];
98
+ for (const token of argv) {
99
+ if (token === '--json') globals.json = true;
100
+ else if (token === '--quiet' || token === '-q') globals.quiet = true;
101
+ else if (token === '--debug') globals.debug = true;
102
+ else if (token === '--version' || token === '-v') globals.version = true;
103
+ else rest.push(token);
104
+ }
105
+ return { globals, rest };
106
+ }
107
+
108
+ export async function main(argv) {
109
+ const { globals, rest } = extractGlobals(argv);
110
+ const logger = createLogger({
111
+ json: globals.json,
112
+ level: globals.quiet ? 'error' : (process.env.AIDF_LOG_LEVEL ?? 'info'),
113
+ });
114
+ const ctx = {
115
+ logger,
116
+ json: globals.json,
117
+ frameworkRoot: FRAMEWORK_ROOT,
118
+ cwd: process.cwd(),
119
+ };
120
+
121
+ if (globals.version) return versionCommand();
122
+ if (globals.debug) process.env.AIDF_DEBUG = '1';
123
+
124
+ const commandName = rest[0];
125
+ if (!commandName || commandName === '--help' || commandName === '-h') {
126
+ return helpCommand([], ctx);
127
+ }
128
+ const entry = COMMANDS[commandName];
129
+ if (!entry) {
130
+ logger.error(`Unknown command "${commandName}". Run "aidf help".`);
131
+ return 1;
132
+ }
133
+ try {
134
+ return await entry.run(rest.slice(1), ctx);
135
+ } catch (error) {
136
+ if (error && error.name === 'PathSafetyError') {
137
+ logger.error(`Refused unsafe path: ${error.message}`);
138
+ return 1;
139
+ }
140
+ logger.error(error && error.message ? error.message : String(error));
141
+ if (process.env.AIDF_DEBUG === '1' && error?.stack) {
142
+ process.stderr.write(`${error.stack}\n`);
143
+ }
144
+ return 1;
145
+ }
146
+ }
147
+
148
+ export { COMMANDS };
@@ -0,0 +1,129 @@
1
+ import { parseArgs } from '../util/args.mjs';
2
+ import { resolveProjectRoot, isInitialized } from '../core/paths.mjs';
3
+ import { attachLogFile } from '../util/logger.mjs';
4
+ import {
5
+ loadAllArtefacts, loadArtefact, verifyChain,
6
+ } from '../core/traceability/chain.mjs';
7
+ import { validateArtefact, resolveLinks } from '../core/artefacts/index.mjs';
8
+
9
+ export function artefactsArgSpec() {
10
+ return {
11
+ booleans: ['json', 'help', 'all'],
12
+ aliases: { h: 'help', t: 'target' },
13
+ };
14
+ }
15
+
16
+ function printJson(ctx, value) {
17
+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
18
+ }
19
+
20
+ export async function artefactsCommand(argv, ctx) {
21
+ const args = parseArgs(argv, artefactsArgSpec());
22
+ const sub = args._[0] ?? 'list';
23
+ if (args.help) {
24
+ ctx.logger.info('Usage: aidf artefacts <list|show|validate|verify> [id] [--type t] [--status s] [--all]');
25
+ return 0;
26
+ }
27
+ const root = resolveProjectRoot({ target: args.target, cwd: process.cwd() });
28
+ if (!isInitialized(root)) {
29
+ ctx.logger.error(`AIDF is not initialized in ${root}. Run "aidf install" first.`);
30
+ return 1;
31
+ }
32
+ await attachLogFile(ctx.logger, root).catch(() => null);
33
+
34
+ if (sub === 'list') {
35
+ const artefacts = await loadAllArtefacts(root);
36
+ let rows = [...artefacts.values()].map((a) => ({
37
+ id: a.id,
38
+ type: a.type ?? '-',
39
+ status: a.status ?? 'DRAFT',
40
+ updatedAt: a.updatedAt ?? '-',
41
+ }));
42
+ if (args.type) rows = rows.filter((r) => r.type === args.type);
43
+ if (args.status) rows = rows.filter((r) => r.status === args.status);
44
+ if (ctx.json) {
45
+ printJson(ctx, { count: rows.length, artefacts: rows });
46
+ } else {
47
+ ctx.logger.info(`Artefacts (${rows.length})`);
48
+ ctx.logger.table(rows, [
49
+ { key: 'id', label: 'ID' },
50
+ { key: 'type', label: 'Type' },
51
+ { key: 'status', label: 'Status' },
52
+ { key: 'updatedAt', label: 'Updated' },
53
+ ]);
54
+ }
55
+ return 0;
56
+ }
57
+
58
+ if (sub === 'show') {
59
+ const id = args._[1];
60
+ if (!id) {
61
+ ctx.logger.error('Usage: aidf artefacts show <id>');
62
+ return 1;
63
+ }
64
+ const artefact = await loadArtefact(root, id);
65
+ if (!artefact) {
66
+ ctx.logger.error(`Artefact not found: ${id}`);
67
+ return 1;
68
+ }
69
+ printJson(ctx, artefact);
70
+ return 0;
71
+ }
72
+
73
+ if (sub === 'validate') {
74
+ const targets = args.all
75
+ ? [...(await loadAllArtefacts(root)).values()]
76
+ : args._[1]
77
+ ? [await loadArtefact(root, args._[1])].filter(Boolean)
78
+ : null;
79
+ if (!targets) {
80
+ ctx.logger.error('Usage: aidf artefacts validate <id> | --all');
81
+ return 1;
82
+ }
83
+ if (targets.length === 0) {
84
+ ctx.logger.error('No artefacts found.');
85
+ return 1;
86
+ }
87
+ const results = [];
88
+ let failed = 0;
89
+ for (const artefact of targets) {
90
+ const validation = await validateArtefact(artefact);
91
+ const links = await resolveLinks(root, artefact.links);
92
+ const errors = [...validation.errors, ...links.errors];
93
+ const warnings = [...validation.warnings];
94
+ if (errors.length > 0) failed += 1;
95
+ results.push({ id: artefact.id, valid: errors.length === 0, errors, warnings });
96
+ }
97
+ if (ctx.json) {
98
+ printJson(ctx, { total: results.length, valid: results.filter((r) => r.valid).length, results });
99
+ } else {
100
+ for (const r of results) {
101
+ ctx.logger.info(`${r.id}: ${r.valid ? 'VALID' : 'INVALID'}`);
102
+ for (const e of r.errors) ctx.logger.error(` - ${e}`);
103
+ for (const w of r.warnings) ctx.logger.warn(` - ${w}`);
104
+ }
105
+ }
106
+ return failed === 0 ? 0 : 1;
107
+ }
108
+
109
+ if (sub === 'verify') {
110
+ const id = args._[1];
111
+ if (!id) {
112
+ ctx.logger.error('Usage: aidf artefacts verify <id>');
113
+ return 1;
114
+ }
115
+ const result = await verifyChain(root, id);
116
+ if (ctx.json) {
117
+ printJson(ctx, result);
118
+ } else {
119
+ ctx.logger.info(`Chain for ${id}: ${result.ok ? 'OK' : 'BROKEN'}`);
120
+ ctx.logger.info(`Path: ${result.path.join(' -> ')}`);
121
+ for (const b of result.brokenLinks) ctx.logger.error(` - ${b}`);
122
+ if (result.coverage) ctx.logger.info(`Coverage: ${JSON.stringify(result.coverage)}`);
123
+ }
124
+ return result.ok ? 0 : 1;
125
+ }
126
+
127
+ ctx.logger.error(`Unknown artefacts subcommand: ${sub}`);
128
+ return 1;
129
+ }