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,90 @@
1
+ # AIDF Compatibility Matrix
2
+
3
+ Status: VALIDATED for the cells marked; others are declared, not exercised.
4
+
5
+ ## 1. Supported hosts
6
+
7
+ | Component | Requirement | Validated on |
8
+ |---|---|---|
9
+ | Node.js | >= 20.11 (ESM, `import.meta.dirname`) | 24.21.0 (Windows) |
10
+ | OS | Windows 10/11, Linux, macOS (Node paths) | Windows 11 26200 x64 |
11
+ | Shell integration | none required | PowerShell 5.1 (`npm.ps1` blocked → use `cmd /c` for npm) |
12
+ | Git | optional (evidence capture and `specify` init degrade gracefully) | git 2.56 |
13
+
14
+ ## 2. IDE adapters
15
+
16
+ | Adapter | Status | Project scope | Notes |
17
+ |---|---|---|---|
18
+ | qoder | CONTRACT-PROVEN (install + verifier); runtime activation requires manual UI steps | `.qoder/rules`, `.qoder/skills`, `.qoder/agents`, `.qoder/settings.json`, `AGENTS.md` | validated against Qoder 1.106.3 layout + official docs |
19
+ | opencode | PROVEN runtime (2026-11-21): real `opencode run` session read the AIDF block and discovered project skills; requires a git worktree for project-skill discovery | `AGENTS.md`, `.opencode/skills/` | verified on OpenCode 1.18.34; non-git projects get files but no skill discovery (PARTIAL) |
20
+ | generic | PROVEN (AGENTS.md managed block + built-in skills under `.aidf/skills/`) | `AGENTS.md`, `.aidf/skills/` | any AGENTS.md-compatible host; skills are files on disk — runtime loading depends on the agent reading the AIDF registry |
21
+
22
+ ## 3. GitHub Spec Kit
23
+
24
+ | Combination | Result |
25
+ |---|---|
26
+ | `specify` CLI 1.2.3 + `--integration qodercli` | validated: init (empty dir), merge (`--force`), `.qoder/skills/speckit-*` |
27
+ | spec-kit source 1.2.6.dev0 (commit `ba7894d`) | referenced only (templates/docs); not assumed to match CLI |
28
+ | older CLI versions | declared compatible down to 1.0.0 (mapping schema), not exercised |
29
+
30
+ ## 4. Coexistence rules
31
+
32
+ | Existing artifact | AIDF behaviour | Verified |
33
+ |---|---|---|
34
+ | `AGENTS.md` exists | append managed block, user content preserved, uninstall restores | yes |
35
+ | `.qoder/rules/*` (non-AIDF) | untouched | yes |
36
+ | `.qoder/settings.json` with hooks | AIDF entries merged as a new group; existing entries kept; uninstall removes only AIDF groups | yes |
37
+ | `.specify/` already present | no reinit; sync honours existing constitution (CONFLICT) | yes |
38
+ | `.env` or other secret files | name listed only, content never read, never copied into reports | yes |
39
+ | non-git project | evidence capture falls back to the file list provided by the caller | yes |
40
+ | duplicate skill names across roots | both flagged, statuses BLOCKED (never silently resolved) | yes |
41
+
42
+ ## 5. Known incompatible / blocked
43
+
44
+ | Item | Status | Reason |
45
+ |---|---|---|
46
+ | `dictionary-of-ai-coding` licence | RESOLVED 2026-11-21 | MIT declared by the owner (no LICENSE file in the clone); registry updated, skills indexable |
47
+ | `pencil` redistribution | BLOCKED | GPL-2.0 licence; excluded from the MIT AIDF distribution by human decision |
48
+ | `.qoder/commands` (legacy) | NOT_APPLICABLE | dropped by Qoder IDE 1.24+; AIDF uses skills |
49
+ | npm global install of AIDF | declared, not exercised in 0.1.0 | package ships `bin` but the recommended flow is the portable checkout |
50
+ | Qoder marketplace plugin packaging | NOT_APPLICABLE | out of scope for 0.1.0 |
51
+
52
+ ## 6. Version compatibility
53
+
54
+ - Config schema: `schemaVersion: 1` (rejects others with a clear message).
55
+ - Manifest schema: `schemaVersion: 1`.
56
+ - AIDF registries are forward-compatible by additive entries; unknown skill
57
+ statuses keep the catalog importable but report `INCOMPATIBLE`.
58
+
59
+ ## 7. 0.2.0 L0 compatibility notes
60
+
61
+ - **Packaging**: the npm tarball now includes `INSTALLATION.md`,
62
+ `UTILISATION.md`, `QODER.md`, `CHANGELOG.md` and `demo/`. Existing installs
63
+ are unaffected until they reinstall/update.
64
+ - **Gate semantics (deliberate defect fixes)**:
65
+ - a blocking check can no longer resolve to `NOT_APPLICABLE` (it is
66
+ `BLOCKED`);
67
+ - a gate whose blocking checks are all skipped is `NOT_PROVEN`;
68
+ - a gate with no blocking check must declare `applicability: informative` to
69
+ PASS;
70
+ - `doc-status` reads the document frontmatter and fails on a mismatch with
71
+ `config.json`.
72
+ - **Evidence**: `evidence verify` is stricter and checks the whole chain. The
73
+ JSON output keeps `checked` and `bad` and adds `ok` and `problems`.
74
+ - **Approvals**: `security.requireAuthenticatedApproval` is optional. When
75
+ absent (old configs) behaviour is compatible: declared approvals still pass
76
+ gates, but `doctor` reports `WARN` and evidence records
77
+ `approval.authenticated: false`.
78
+ - **Frozen documents**: install/update still never rewrite project documents,
79
+ registries, workflows or knowledge, even with `--force` (regression-tested).
80
+ - **CLI**: 26 verbs, exit codes 0/1/2, `--json` shape additive only.
81
+ - **New commands (0.2.0)**: `artefacts`, `requirements`, `traceability`,
82
+ `decision`, `design`, `security`, `tests`, `release`, plus
83
+ `resources inventory|coverage|reconcile` and `skills sources|catalog|enable`.
84
+ All are additive; no 0.1.0 verb changed semantics.
85
+ - **Decision Engine**: the optional LLM analyzer (`AI_MODEL`/`callLLM`) was
86
+ removed. AIDF owns no model; interpretation is delegated to the invoking
87
+ agent (`analysis.delegation`). The deterministic path is unchanged.
88
+ - **Migration**: covered by `tests/migration.test.mjs` (legacy 0.1.0 fixture
89
+ upgrades additively, files preserved, engines usable) and verified manually
90
+ against a real 0.1.0 install copy (148 → 198 managed files, 0 conflicts).
@@ -0,0 +1,200 @@
1
+ # AIDF Decision Log
2
+
3
+ Format: decision, status, date, rationale, consequences.
4
+ Statuses: PROPOSED, ACCEPTED, REVISIT, SUPERSEDED.
5
+
6
+ ## DEC-001 — Framework identity and scope
7
+ - Status: ACCEPTED (2026-10-30)
8
+ - AIDF is a governance layer installed inside projects; it does not replace the
9
+ IDE, an existing cockpit, or project architecture.
10
+ - Consequence: the framework owns only `.aidf/`, the managed `AGENTS.md` block,
11
+ and explicitly namespaced adapter files (`aidf-*`).
12
+
13
+ ## DEC-002 — Qoder is the first adapter; `generic` is the baseline
14
+ - Status: ACCEPTED (2026-10-30)
15
+ - Evidence used: official Qoder rules/skills/hooks/agents documentation plus the
16
+ observed `.qoder` layout of installed Qoder 1.106.3.
17
+ - Consequence: `src/core/adapters/qoder.mjs` generates `aidf-` prefixed rules,
18
+ skills and the orchestrator agent. Other IDEs can be added without touching
19
+ core modules.
20
+
21
+ ## DEC-003 — Rule activation is reported as NOT_PROVEN, not automatic
22
+ - Status: ACCEPTED (2026-10-30)
23
+ - Reason: the activation type (Always Apply etc.) is a Qoder UI setting; the
24
+ filesystem cannot prove it.
25
+ - Consequence: `qoder.verify()` returns `CONTRACT-PROVEN` for file/contract
26
+ checks and `NOT_PROVEN` for runtime checks (`/skills` discovery, rule
27
+ activation, hook activation). Nothing in AIDF claims runtime activation.
28
+
29
+ ## DEC-004 — Managed AGENTS.md block instead of replacement
30
+ - Status: ACCEPTED (2026-10-30)
31
+ - Consequence: pre-existing `AGENTS.md` content is preserved byte-for-byte;
32
+ AIDF adds `<`!-- AIDF:BEGIN ... AIDF:END --`>`. Uninstall restores the user
33
+ file and deletes it only if the block was its sole content.
34
+
35
+ ## DEC-005 — Ownership tracking with SHA-256 in `.aidf/manifest.json`
36
+ - Status: ACCEPTED (2026-10-30)
37
+ - Consequence: files not in the manifest are never overwritten; edited managed
38
+ files produce `CONFLICT` (exit 2); `--force` keeps a timestamped backup.
39
+
40
+ ## DEC-006 — Node ESM runtime with zero dependencies
41
+ - Status: ACCEPTED (2026-10-30)
42
+ - Reason: the host had `npm.ps1` blocked by execution policy; the framework
43
+ must work with `node` alone.
44
+ - Consequence: a deliberately small YAML subset parser is used; registries are
45
+ human-editable YAML, machine state is JSON.
46
+
47
+ ## DEC-007 — YAML subset parser instead of a library
48
+ - Status: ACCEPTED (2026-10-31)
49
+ - Consequence: supported syntax (nested maps, sequences, inline arrays, quoted
50
+ strings, `|`/`>` and `|-` block scalars) is covered by tests; unsupported
51
+ constructs fail loudly instead of being mis-parsed.
52
+
53
+ ## DEC-008 — Command execution is opt-in and shell-free
54
+ - Status: ACCEPTED (2026-10-30)
55
+ - Consequence: command checks run only with `--allow-exec` or
56
+ `security.allowCommandExecution=true`; `spawn(…, { shell: false })`; shell
57
+ operators (`|`, `&`, `;`, `<`, `>`, backticks, `$( )`) are rejected before
58
+ execution; output is truncated and recorded as evidence.
59
+
60
+ ## DEC-009 — Spec Kit integration is reference + copy-with-hash
61
+ - Status: ACCEPTED (2026-10-30, revised 2026-10-31)
62
+ - AIDF documents are durable product truth; Spec Kit specs cover one feature.
63
+ - `.specify/memory/constitution.md` may receive a generated AIDF copy marked
64
+ `<!-- AIDF:SOURCE-HASH:… -->`. Any existing Spec Kit constitution without this
65
+ marker is a conflict that AIDF never overwrites (verified behaviour).
66
+ - Mapping facts live once; feature specs reference PRD requirement IDs.
67
+
68
+ ## DEC-010 — `specify init` on a non-empty project requires explicit opt-in
69
+ - Status: ACCEPTED (2026-10-31)
70
+ - Finding (verified): `specify init --here --non-interactive` fails with
71
+ “Current directory is not empty” when AIDF is already installed.
72
+ - Consequence: `aidf speckit init` reports `BLOCKED` and requires
73
+ `--specify-force`, which appends `--force` to the specify call. The merge was
74
+ verified to be additive (AGENTS.md, `.aidf/`, `.qoder/` remained intact).
75
+
76
+ ## DEC-011 — Spec Kit skill detection uses both prefixes
77
+ - Status: ACCEPTED (2026-10-31)
78
+ - Finding (verified): specify 1.2.3 installs `.qoder/skills/speckit-*`
79
+ (hyphen), while earlier docs described `speckit.` (dot).
80
+ - Consequence: `specKitStatus` accepts `speckit-` and `speckit.`; verified
81
+ against a real qodercli init (10 skills detected).
82
+
83
+ ## DEC-012 — Resources with unknown licences are BLOCKED and index-only
84
+ - Status: ACCEPTED (2026-10-30)
85
+ - Consequence: `dictionary-of-ai-coding` is indexed by name/path/commit only;
86
+ `installGitResource` refuses network installs for unknown licences.
87
+
88
+ ## DEC-013 — Documents vs status transitions
89
+ - Status: ACCEPTED (2026-10-30)
90
+ - `VALIDATED` requires `--by "<name>"` (human accountability); `NOT_APPLICABLE`
91
+ requires a `--note`; `aidf docs status` also updates the document frontmatter
92
+ and manifest hash.
93
+
94
+ ## DEC-014 — Exit code contract
95
+ - Status: ACCEPTED (2026-10-30)
96
+ - `0` = success, `1` = failure/blocked/refusal, `2` = conflict or contradiction
97
+ (context BLOCKED, install conflicts, Spec Kit constitution conflict).
98
+
99
+ ## DEC-015 — Document frontmatter is canonical; config is a projection
100
+ - Status: ACCEPTED (2026-11-20, L0)
101
+ - Context: `aidf docs status` updated both `config.json` and the Markdown
102
+ frontmatter, but gates read only `config.json`. A stale or hand-edited config
103
+ could therefore claim `VALIDATED` while the file was still a `DRAFT` template.
104
+ - Problem: the framework reported a gate PASS without a real document.
105
+ - Options:
106
+ 1. Keep config as canonical (rejected: hidden state, easy to fake).
107
+ 2. Read the file on every check (chosen).
108
+ 3. Generate both from a database (out of scope for 0.2.0 L0).
109
+ - Decision: `doc-status` reads `.aidf/docs/<DOC>.md`, requires a frontmatter
110
+ `status`, fails on a config/file mismatch, and applies `allowed`/`disallowed`
111
+ to the file value. `doctor` keeps the same cross-check.
112
+ - Consequences: a mismatch is `FAIL`; a missing file is `BLOCKED`; no silent
113
+ PASS is possible. Existing projects that only changed `config.json` will now
114
+ see a real failure until the file is aligned.
115
+ - Risks: legacy documents without frontmatter block gates. Mitigation: the
116
+ templates already ship frontmatter; the error names the file.
117
+ - Compatibility: no CLI verb, exit code or check type changed.
118
+ - Tests: `tests/workflow.test.mjs` (matching, mismatch, missing file),
119
+ `tests/doctor.test.mjs` (config/file mismatch).
120
+
121
+ ## DEC-016 — Exhaustive applicability rules for gates
122
+ - Status: ACCEPTED (2026-11-20, L0)
123
+ - Context: `NOT_APPLICABLE` did not block, so a gate whose blocking checks were
124
+ all skipped could PASS; a blocking command declared `missing:
125
+ NOT_APPLICABLE` was also silently skipped.
126
+ - Decision:
127
+ 1. A blocking check may never resolve to `NOT_APPLICABLE`; a missing blocking
128
+ command is `BLOCKED`.
129
+ 2. A gate with blocking checks but zero applicable blocking checks is
130
+ `NOT_PROVEN`.
131
+ 3. A gate without blocking checks must declare `applicability: informative`
132
+ to PASS; otherwise it is `NOT_PROVEN` (misconfiguration cannot pass).
133
+ - Consequences: informative gates stay possible but explicit; security exits
134
+ cannot be satisfied by configuration gaps.
135
+ - Risks: a project that intentionally configured a blocking command as
136
+ `NOT_APPLICABLE` must now remove the command or set `blocking: false`.
137
+ - Compatibility: the six check types and status precedence are unchanged.
138
+ - Tests: `tests/workflow.test.mjs` (blocking N/A, no blocking check,
139
+ informative gate).
140
+
141
+ ## DEC-017 — Evidence chain verification is complete and never repairs itself
142
+ - Status: ACCEPTED (2026-11-20, L0)
143
+ - Context: `evidence verify` checked each file hash only; `previous` links,
144
+ ordering, index divergence, duplicates and unindexed files were not checked.
145
+ - Decision: `verifyEvidenceChain` verifies every hash, every `previous` link,
146
+ chronological order, `index.lastHash`, duplicate ids/files, missing files and
147
+ unindexed records. `doctor` and `evidence verify` use it. The function only
148
+ reports; it never rewrites history.
149
+ - Consequences: `evidence verify --json` keeps `checked` and `bad` and adds
150
+ `ok` and `problems` (additive). Exit 1 on any problem.
151
+ - Risks: legacy chains with a hand-edited index now fail instead of passing.
152
+ That is the intended honesty.
153
+ - Compatibility: existing record files are unchanged.
154
+ - Tests: `tests/evidence.test.mjs`, `tests/doctor.test.mjs`.
155
+
156
+ ## DEC-018 — Declared approval is not authentication
157
+ - Status: ACCEPTED (2026-11-20, L0), signature mechanism PROPOSED
158
+ - Context: `--human --by "name"` wrote `humanApproval: true` and gates accepted
159
+ it. The agent can run the same command, so this is an identity declaration,
160
+ not proof of human presence.
161
+ - Decision:
162
+ 1. Evidence now carries `approval { declaredBy, declaredAt, authenticated,
163
+ method, keyId }`; `--human` always records `authenticated: false` and
164
+ `method: declared`. `approvedBy` is preserved as historical declared
165
+ identity.
166
+ 2. `security.requireAuthenticatedApproval` (additive, optional, default
167
+ `false`) makes human-required gates reject declared-only approval as
168
+ `NOT_PROVEN`.
169
+ 3. No signing key is generated or read. A verifiable signature scheme is
170
+ proposed for validation; until then authentication is `NOT_PROVEN`.
171
+ - Consequences: default installs remain compatible and `doctor` reports
172
+ declared-only approvals as `WARN`; strict projects can opt in now.
173
+ - Risks: enabling the flag without an external signing process blocks security
174
+ and release exits. That is intentional and must be documented.
175
+ - Compatibility: old configs without the flag validate and behave as before.
176
+ - Tests: `tests/evidence.test.mjs`, `tests/workflow.test.mjs`,
177
+ `tests/doctor.test.mjs`.
178
+
179
+ ## DEC-019 — L0 packaging, demo and CI are real, not decorative
180
+ - Status: ACCEPTED (2026-11-20, L0)
181
+ - Context: `package.json.files` omitted `INSTALLATION.md`,
182
+ `UTILISATION.md`, `QODER.md` and `CHANGELOG.md` although bootstrap copies
183
+ them; `npm run demo` pointed to a missing file; there was no CI.
184
+ - Decision:
185
+ 1. Ship the four guides and `demo/` in the npm tarball.
186
+ 2. Implement `demo/run-demo.mjs` as a real temporary-project run
187
+ (install → doctor → context → gate → resources); no predefined output.
188
+ 3. Add a GitHub Actions workflow (syntax, tests, demo, diagnostics).
189
+ 4. Add a packaging test that runs `npm pack`, inspects the tarball, installs
190
+ it in a temporary prefix, runs `--version`, `init` and `doctor`.
191
+ - Consequences: the package is testable as installed, not only from the repo.
192
+ - Risks: CI is unproven until the repository is under Git and the workflow runs
193
+ (the workspace is not a Git repository). This remains `NOT_PROVEN`.
194
+ - Tests: `tests/packaging.test.mjs`, `demo/run-demo.mjs`.
195
+
196
+ ## REVISIT list
197
+ - Qoder project-vs-user skill precedence: docs conflict; AIDF links installs
198
+ into `.qoder/skills` only and never relies on resolution order.
199
+ - A `qoder` marketplace/registry adapter (auto-download of AIDF skills) was
200
+ rejected for 0.1.0: no network installs without human authorization.
@@ -0,0 +1,38 @@
1
+ # AIDF As-Installed Package
2
+
3
+ Status: VALIDATED (installable unit)
4
+ Date: 2026-10-31
5
+
6
+ This file documents what a *consumer* receives when AIDF is installed into
7
+ their own project, as shipped by version 0.1.0.
8
+
9
+ ## 1. What ships on `aidf install`
10
+
11
+ | Destination | Content |
12
+ |---|---|
13
+ | `.aidf/framework/` | complete self-contained copy of the distribution's `src/` and `assets/` (plus README, LICENSE, package.json) |
14
+ | `.aidf/bin/aidf.mjs` | launcher wired to the copied framework |
15
+ | `.aidf/AIDF.md` | agent entry point (session protocol, conflict hierarchy, status vocabulary) |
16
+ | `.aidf/docs/*.md` | 11 honest templates: constitution, PRD, TRD, APPFLOW, UI-UX, BACKEND, PLAN, SECURITY, CONVENTIONS, DECISIONS, CHANGELOG |
17
+ | `.aidf/registry/*.yaml` | skills catalog (13), dependencies, activation map, sources |
18
+ | `.aidf/workflows/*.yaml` | phases (8) + executable gates (16) |
19
+ | `.qoder/*` (qoder adapter) | `aidf-*` rules, 13 skills, orchestrator agent, merged hook entries |
20
+ | `.aidf/evidence/`, `state/`, `reports/`, `backups/`, `logs/` | runtime state (logs and backups stay local) |
21
+
22
+ ## 2. Verified behaviours as an installable unit (measured on real runs)
23
+
24
+ - **Idempotency**: re-running update twice → second run `created=0 updated=0
25
+ unchanged=133`.
26
+ - **Conflict safety**: local edit of a managed rule → `CONFLICT`, file
27
+ preserved, exit code 2.
28
+ - **Dry-run purity**: `install --dry-run` leaves no trace, including logs.
29
+ - **Uninstall**: restores pre-existing `AGENTS.md`, keeps unrelated rule
30
+ files, removes only AIDF-owned files; `--keep-data` keeps docs+evidence.
31
+ - **Secrets**: a `.env` present in the E2E project had its filename listed and
32
+ its content never read or echoed anywhere in reports.
33
+ - **Manifest honesty**: every created file is recorded in
34
+ `.aidf/manifest.json` with its SHA-256; `doctor` verifies presence.
35
+
36
+ Reference the live validation record in `docs/aidf/VALIDATION.md`. Qoder
37
+ runtime activation remains a manual, human-evidenced step by design
38
+ (`docs/aidf/IDE-QODER.md`).
@@ -0,0 +1,61 @@
1
+ # AIDF ↔ Qoder IDE Adapter
2
+
3
+ Status: VALIDATED (contract), runtime activation NOT_PROVEN (by design)
4
+
5
+ ## 1. Why Qoder first
6
+
7
+ Qoder IDE 1.106.3 is installed on the author machine; official documentation
8
+ defines project rules, skills, hooks and custom agents that AIDF can generate
9
+ deterministically. The adapter is the first implementation of the adapter
10
+ interface; `generic` (AGENTS.md block only) is the baseline fallback.
11
+
12
+ ## 2. Installed artifacts
13
+
14
+ | Path | Content |
15
+ |---|---|
16
+ | `AGENTS.md` | managed block pointing to `.aidf/AIDF.md` (user content preserved) |
17
+ | `.qoder/rules/aidf-00-core.md` | operating rule: inspect before modify, statuses, evidence |
18
+ | `.qoder/rules/aidf-10-security.md` | secret policy, protected files, opt-in execution |
19
+ | `.qoder/rules/aidf-20-context.md` | how to read `.aidf/state/context/latest.md` |
20
+ | `.qoder/skills/aidf-<name>/SKILL.md` | 13 first-party skills |
21
+ | `.qoder/agents/aidf-orchestrator.md` | orchestrator agent (Read/Grep/Glob/Bash + skill list) |
22
+ | `.qoder/settings.json` (with `--with-hooks`) | `SessionStart` and `PostToolUse` hook entries (merged) |
23
+ | `.aidf/hooks/session-context.mjs` | SessionStart hook: phase reminder, blocked docs; fails open |
24
+ | `.aidf/hooks/audit.mjs` | PostToolUse hook: redacted audit line (metadata only, never content) |
25
+
26
+ ## 3. Verification levels
27
+
28
+ `aidf doctor` runs `QoderAdapter.verify()` and reports:
29
+
30
+ - `PASS`: node version, config, manifest, document files, evidence integrity.
31
+ - `CONTRACT-PROVEN`: adapter files exist and satisfy constraints (agents block,
32
+ 3 rules, 13 skills parse, settings JSON valid).
33
+ - `NOT_PROVEN` until a human confirms in a real session:
34
+ - `runtime-skill-discovery` → `/skills` lists `aidf-project-context`;
35
+ - `runtime-rule-activation` → rules set to Always Apply in the Qoder UI;
36
+ - `runtime-hook-activation` → an edit writes `.aidf/logs/audit-<date>.jsonl`.
37
+
38
+ This split is deliberate: a file existing is evidence of installation, not
39
+ evidence of runtime activation.
40
+
41
+ ## 4. Manual activation checklist (one time per project)
42
+
43
+ 1. Open the project in Qoder; wait for indexing.
44
+ 2. Run `/skills`; verify the 13 `aidf-*` skills and any `speckit-*` skills.
45
+ 3. Settings → Rules: set `aidf-00-core` and `aidf-10-security` to **Always
46
+ Apply**; leave `aidf-20-context` as Model Decision or Specific Files.
47
+ 4. With hooks: restart Qoder; make one edit; check `.aidf/logs/`.
48
+ 5. Run `aidf evidence add --type qoder-runtime-activation --human --by "<name>"
49
+ --note "/skills listing confirmed"` so the manual check becomes evidence.
50
+
51
+ ## 5. Known limitations
52
+
53
+ - Activation type is a UI setting; the rule file can only carry the reminder.
54
+ - Qoder docs disagree on project vs user skill precedence (IDE doc says
55
+ project wins; CLI doc says user wins). AIDF installs into project scope only
56
+ and never depends on the resolution order.
57
+ - Hooks execute with the process environment of Qoder; `audit.mjs` logs only
58
+ relative paths and tool names, never file content (secret-safe by design).
59
+ - `.qoder/commands` are legacy (dropped in Qoder IDE 1.24+); AIDF does not
60
+ generate them. Spec Kit's qodercli integration installs skills, which is the
61
+ current mechanism.
@@ -0,0 +1,99 @@
1
+ # AIDF Installation and Update Guide
2
+
3
+ Status: VALIDATED
4
+
5
+ ## 1. Prerequisites
6
+
7
+ - Node.js >= 20.11 (validated on 24.21.0). No npm packages are required.
8
+ - Optional: Qoder IDE (for the `qoder` adapter), `specify` CLI (for Spec Kit).
9
+ - Windows: PowerShell execution policy blocked `npm.ps1`; AIDF needs `node` on
10
+ PATH, nothing else.
11
+
12
+ ## 2. Install AIDF into a project
13
+
14
+ From inside a project (recommended):
15
+
16
+ ```powershell
17
+ node C:\path\to\aidf\bin\aidf.mjs install --adapter qoder --with-hooks
18
+ ```
19
+
20
+ From outside, targeting the project:
21
+
22
+ ```powershell
23
+ node C:\path\to\aidf\bin\aidf.mjs install --target C:\path\to\project --adapter qoder --with-hooks
24
+ ```
25
+
26
+ `aidf init <dir>` is an alias of `install` and accepts the same options.
27
+
28
+ Options:
29
+
30
+ | Option | Meaning |
31
+ |---|---|
32
+ | `--adapter qoder\|generic` | IDE adapter (default: `qoder`). |
33
+ | `--with-hooks` | Install `.aidf/hooks/*.mjs` and declare SessionStart/PostToolUse hooks in `.qoder/settings.json`. |
34
+ | `--dry-run` | Print the action plan only; nothing is written (not even logs). |
35
+ | `--force` | Only re-applies AIDF-managed files that changed locally (backup kept). |
36
+ | `--name <name>` | Override the project name in config. |
37
+
38
+ Verified behaviour (2026-10-31, real runs on Windows):
39
+
40
+ - Existing `AGENTS.md` content is preserved, the AIDF block is appended.
41
+ - Existing `.qoder/rules/**` files are untouched; only `aidf-*.md` is created.
42
+ - Existing `.qoder/settings.json` keys survive hook merging.
43
+ - `.env`, `.git`, `node_modules` are skipped; no secret content is read.
44
+ - Idempotency: re-running install reports `created=0 updated=0 unchanged=N`.
45
+
46
+ ## 3. Post-install checklist
47
+
48
+ ```powershell
49
+ node .aidf/bin/aidf.mjs doctor
50
+ node .aidf/bin/aidf.mjs scan --record
51
+ node .aidf/bin/aidf.mjs skills validate
52
+ node .aidf/bin/aidf.mjs setup resources
53
+ ```
54
+
55
+ Then in Qoder:
56
+
57
+ 1. Restart/open the project; run `/skills` to confirm the 13 `aidf-*` skills.
58
+ 2. Settings → Rules: set `aidf-00-core` and `aidf-10-security` to
59
+ **Always Apply** (this manual step is what turns the NOT_PROVEN runtime
60
+ checks into proven ones).
61
+ 3. With hooks: restart Qoder once so the SessionStart hook loads.
62
+
63
+ ## 4. Update
64
+
65
+ Re-run the newer distribution against the project:
66
+
67
+ ```powershell
68
+ node C:\path\to\new-aidf\bin\aidf.mjs update --target C:\path\to\project --adapter qoder
69
+ ```
70
+
71
+ Only manifest-owned files are refreshed (backups kept). Project documents,
72
+ evidence and workflow state are preserved. Running `update` from the installed
73
+ copy re-applies the *current* version; to change versions use a newer
74
+ distribution checkout.
75
+
76
+ ## 5. Uninstall
77
+
78
+ ```powershell
79
+ node .aidf/bin/aidf.mjs uninstall --dry-run # preview
80
+ node .aidf/bin/aidf.mjs uninstall --yes # remove everything AIDF owns
81
+ node .aidf/bin/aidf.mjs uninstall --yes --keep-data # keep .aidf/docs + evidence
82
+ node .aidf/bin/aidf.mjs uninstall --yes --force # also remove edited managed files (backups kept)
83
+ ```
84
+
85
+ Verified: modified managed files are preserved with `CONFLICT` (exit 2) and
86
+ removed only via `--force` with a backup; `AGENTS.md` is restored (deleted only
87
+ when the block was its only content); hook entries are removed from
88
+ `.qoder/settings.json` without touching other settings; `.env` and project
89
+ files are never touched.
90
+
91
+ ## 6. CI / non-interactive usage
92
+
93
+ All commands accept `--json` and are deterministic. Example:
94
+
95
+ ```powershell
96
+ node .aidf/bin/aidf.mjs validate --phase testing --kind exit --allow-exec --json
97
+ ```
98
+
99
+ Exit codes: `0` success, `1` failure/blocked, `2` conflict/contradiction.
@@ -0,0 +1,72 @@
1
+ # AIDF Inventory
2
+
3
+ - Date: 2026-10-31 (Europe/Paris).
4
+ - Scope: host machine of the AIDF author, populated with real clones and tooling.
5
+ - Method: direct inspection of file systems, installed versions (`<tool> --version`
6
+ where available) and official documentation retained as references. No content
7
+ or value of a `.env` file was read.
8
+
9
+ ## 1. Host environment
10
+
11
+ | Item | Value | Evidence |
12
+ |---|---|---|
13
+ | OS | Windows 11 x64, build 26200 | `os.release()` / system information at inventory time |
14
+ | Node.js | v24.21.0 | `node --version` |
15
+ | npm | 11.19.0 (execution policy blocks `npm.ps1`; use `cmd /c npm` or plain `node`) | Phase 0 check |
16
+ | Python | 3.14 | `python --version` (Phase 0) |
17
+ | uv | installed (`specify` CLI depends on it) | `uv --version` (Phase 0) |
18
+ | git | 2.56 | `git --version` (Phase 0) |
19
+ | Qoder IDE | 1.106.3 installed (`~/.qoder` present) | Phase 0 file-system check |
20
+ | specify CLI | `specify 1.2.3` (`C:\Python314\Scripts\specify.exe`) | executed during validation |
21
+ | GitHub CLI | `gh` present on PATH | `where gh` (Phase 0) |
22
+
23
+ The `vibecoding` workspace itself is not a git repository.
24
+
25
+ ## 2. Workspace resources (as referenced by `assets/registry/sources.yaml`)
26
+
27
+ | Resource | Path | Licence | Status | Evidence |
28
+ |---|---|---|---|---|
29
+ | github-spec-kit | `../resources/spec-kit` (source 1.2.6.dev0, commit `ba7894d`) | MIT | PRESENT | clone + `aidf setup resources` inspection |
30
+ | mattpocock-skills | `../resources/skills` (v1.3.2, commit `a496f55`) | MIT | PRESENT | clone inspection |
31
+ | superpowers | `../resources/superpowers` (v7.0.1, commit `2ce8aa1`) | MIT | PRESENT | clone inspection |
32
+ | agent-rules-books | `../resources/agent-rules-books` (commit `a7d7649`) | MIT | PRESENT | clone inspection |
33
+ | dictionary-of-ai-coding | `../resources/dictionary-of-ai-coding` (commit `ed1ebe`) | unknown | BLOCKED (index-only) | no LICENSE file in clone |
34
+ | jeremy-web-modules | `../resources/MODULES` (corpus privé, ~321 docs de cours) | proprietary-owner | PARTIAL (index-only) | registre + lock (2026-10-31) |
35
+ | owasp-asvs | `../resources/owasp-asvs` (5.0.0, commit `9ccce0e`) | CC-BY-SA-4.0 | PRESENT | clone épinglé (autorisation humaine) |
36
+ | qoder-docs | https://docs.qoder.com | proprietary-docs | reference | verified pages retained in DECISIONS |
37
+ | owasp-asvs | https://owasp.org/...ASVS | CC-BY-SA-4.0 | NOT_INSTALLED (v unknown) | referenced by name only |
38
+ | typescript-handbook | https://www.typescriptlang.org/docs/handbook/ | Apache-2.0 | reference | cited, not copied |
39
+
40
+ ## 3. Qoder capabilities verified (documentation + real CLI/IDE checks)
41
+
42
+ - Project rules live in `.qoder/rules/*.md`; the activation type (Always Apply /
43
+ Model Decision / Specific Files / Apply Manually) is a UI setting — it is not
44
+ encoded in the file, so AIDF cannot prove it from the filesystem.
45
+ - Skills: project-level `.qoder/skills/<name>/SKILL.md`, user-level
46
+ `~/.qoder/skills`; `name` ≤ 64 lowercase-hyphen chars, `description` ≤ 1024.
47
+ - Qoder IDE 1.24+ dropped `.qoder/commands`; Spec Kit's `qodercli` integration
48
+ installs skills under `.qoder/skills/` (verified with specify 1.2.3).
49
+ - Hooks (`SessionStart`, `PostToolUse`, …) in `.qoder/settings.json`,
50
+ `.qoder/settings.local.json` or `~/.qoder/settings.json`.
51
+ - Custom agents: `.qoder/agents/*.md` with YAML frontmatter.
52
+ - `AGENTS.md` is honoured automatically by Qoder; project rules take precedence.
53
+
54
+ ## 4. Document and status vocabulary
55
+
56
+ - Documents: `PRD`, `TRD`, `APPFLOW`, `UI-UX`, `BACKEND`, `PLAN`, `SECURITY`,
57
+ `CONVENTIONS`, `constitution`, `DECISIONS`, `CHANGELOG`.
58
+ - Document statuses: `DRAFT`, `VALIDATED`, `BLOCKED`, `OUTDATED`, `NOT_APPLICABLE`.
59
+ - Gate statuses: `PASS`, `BLOCKED`, `FAIL`, `NOT_PROVEN`, `NOT_APPLICABLE`.
60
+ - Skill statuses: `DISCOVERED`, `VALIDATED`, `REGISTERED`, `AVAILABLE`,
61
+ `BLOCKED`, `INCOMPATIBLE`.
62
+ - Final-report statuses: `PROVEN`, `CONTRACT-PROVEN`, `BLOCKED`, `NOT_PROVEN`,
63
+ `NOT_APPLICABLE`.
64
+
65
+ ## 5. Open deltas recorded at inventory time
66
+
67
+ 1. Qoder documentation does not state how project vs user skills are resolved
68
+ (IDE doc and CLI doc disagree); AIDF does not rely on this precedence.
69
+ 2. The `dictionary-of-ai-coding` clone has no LICENSE file: content stays
70
+ index-only until the owner clarifies the licence.
71
+ 3. `npm.ps1` is blocked by the execution policy; AIDF has zero npm runtime
72
+ dependencies, so this has no runtime impact.