qfai 1.2.2 → 1.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -2
- package/assets/init/.qfai/assistant/agents/code-reviewer.md +2 -0
- package/assets/init/.qfai/assistant/agents/coverage-planner.md +3 -0
- package/assets/init/.qfai/assistant/agents/planner.md +2 -1
- package/assets/init/.qfai/assistant/agents/qa-engineer.md +3 -0
- package/assets/init/.qfai/assistant/agents/qa-gatekeeper.md +3 -0
- package/assets/init/.qfai/assistant/agents/qa-lead.md +3 -0
- package/assets/init/.qfai/assistant/agents/qa-reviewer.md +3 -0
- package/assets/init/.qfai/assistant/agents/test-engineer.md +2 -0
- package/assets/init/.qfai/assistant/agents/unit-test-scope-enforcer.md +2 -0
- package/assets/init/.qfai/assistant/prompts/qfai-atdd.md +33 -12
- package/assets/init/.qfai/assistant/prompts/qfai-spec.md +12 -7
- package/assets/init/.qfai/assistant/prompts/qfai-tdd-green.md +12 -4
- package/assets/init/.qfai/assistant/prompts/qfai-tdd-red.md +26 -8
- package/assets/init/.qfai/assistant/prompts/qfai-tdd-refactor.md +12 -4
- package/assets/init/root/qfai.config.yaml +6 -0
- package/dist/cli/index.cjs +325 -29
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.mjs +325 -29
- package/dist/cli/index.mjs.map +1 -1
- package/dist/index.cjs +325 -29
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +14 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.mjs +325 -29
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -62,8 +62,8 @@ QFAI includes a small set of custom prompts (stored under `.qfai/assistant/promp
|
|
|
62
62
|
- **qfai-require**: Produce `require.md` in the requirements directory from your idea or discussion output.
|
|
63
63
|
- **qfai-spec**: Produce `.qfai/specs/*` and `.qfai/contracts/*` from the requirements, including traceability scaffolding.
|
|
64
64
|
- Includes a preflight step that bootstraps missing `qfai.config.yaml` and `assistant/steering/*` when run directly after init.
|
|
65
|
-
- **qfai-atdd**: Implement acceptance tests (
|
|
66
|
-
- **qfai-tdd-red**: Implement fast tests first (unit/component/
|
|
65
|
+
- **qfai-atdd**: Implement acceptance tests (E2E/API/Integration) and drive Scenario Coverage to 100% using a Coverage Ledger.
|
|
66
|
+
- **qfai-tdd-red**: Implement fast tests first (unit/component) and drive Unit/Component Scenario Coverage to 100% using a Coverage Ledger.
|
|
67
67
|
- **qfai-tdd-green**: Implement production code to make the tests pass.
|
|
68
68
|
- **qfai-tdd-refactor**: Refactor safely after tests are green.
|
|
69
69
|
- **qfai-verify**: Run/interpret the local quality gates and produce a PR-ready summary.
|
|
@@ -137,6 +137,7 @@ Operational notes.
|
|
|
137
137
|
- Each custom prompt must output in the user’s language (absolute requirement).
|
|
138
138
|
- Except `qfai-discuss`, each prompt must analyze the project context (architecture, tech stack, test framework, repo structure) before generating artifacts or code.
|
|
139
139
|
- Prompts should delegate work to multiple role-based sub-agents (Planner, Architect, Contract Designer, QA, Code Reviewer, etc.) to emulate a real delivery flow.
|
|
140
|
+
- /qfai-atdd and /qfai-tdd-red must maintain a Coverage Ledger and do not declare completion until missing=0 (exceptions documented).
|
|
140
141
|
|
|
141
142
|
## Configuration
|
|
142
143
|
|
|
@@ -161,6 +162,7 @@ validation:
|
|
|
161
162
|
testFileGlobs:
|
|
162
163
|
- "src/**/*.test.ts"
|
|
163
164
|
- "tests/**/*.spec.ts"
|
|
165
|
+
- "features/**/*.feature"
|
|
164
166
|
testFileExcludeGlobs:
|
|
165
167
|
- "**/fixtures/**"
|
|
166
168
|
scMustHaveTest: true
|
|
@@ -227,6 +229,11 @@ QFAI uses a small, opinionated set of artifacts to reduce ambiguity and prevent
|
|
|
227
229
|
|
|
228
230
|
Traceability is validated across these artifacts, so code changes remain grounded in the specs and the tests prove compliance.
|
|
229
231
|
|
|
232
|
+
Traceability evidence can be provided in two ways:
|
|
233
|
+
|
|
234
|
+
- `QFAI:SC-XXXX-XXXX` annotations inside test code
|
|
235
|
+
- `@SC-XXXX-XXXX` tags inside `.feature` files (Cucumber-style acceptance tests)
|
|
236
|
+
|
|
230
237
|
### Test strategy tags (optional)
|
|
231
238
|
|
|
232
239
|
You can annotate scenarios with lightweight test strategy metadata to keep the test pyramid/trophy healthy.
|
|
@@ -235,6 +242,8 @@ These tags are opt-in and only produce warnings, so you can roll them out gradua
|
|
|
235
242
|
- Layer tags: `@layer-unit`, `@layer-component`, `@layer-integration`, `@layer-api`, `@layer-e2e`
|
|
236
243
|
- Size tags: `@size-s`, `@size-m`, `@size-l`
|
|
237
244
|
|
|
245
|
+
Traceability enforcement is layer-aware: once any SC in a layer has test evidence, coverage for that layer becomes mandatory; layers without evidence are deferred until tests exist.
|
|
246
|
+
|
|
238
247
|
## Continuous integration (GitHub Actions)
|
|
239
248
|
|
|
240
249
|
(GitHub Actions)
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
- Findings with severity
|
|
10
10
|
- Suggested fixes
|
|
11
11
|
- Residual risks and testing gaps
|
|
12
|
+
- Layer-scope drift check (ATDD vs TDD)
|
|
12
13
|
|
|
13
14
|
## Non-goals
|
|
14
15
|
|
|
@@ -20,6 +21,7 @@
|
|
|
20
21
|
|
|
21
22
|
- Follow `.qfai/assistant/instructions/*` and `.qfai/assistant/steering/*`
|
|
22
23
|
- Keep outputs specific and testable
|
|
24
|
+
- Flag layer drift (e.g., unit/component tests created during ATDD)
|
|
23
25
|
- If evidence is missing, mark TBD and ask targeted questions
|
|
24
26
|
|
|
25
27
|
## Output format
|
|
@@ -3,11 +3,13 @@
|
|
|
3
3
|
## Mission
|
|
4
4
|
|
|
5
5
|
- Enumerate cases using coverage techniques and provide saturation evidence.
|
|
6
|
+
- Build Coverage Ledger entries for Scenario Coverage (done/missing/exception).
|
|
6
7
|
|
|
7
8
|
## Deliverables
|
|
8
9
|
|
|
9
10
|
- Case Catalogue with required fields
|
|
10
11
|
- Saturation stop-rule evidence
|
|
12
|
+
- Coverage Ledger entries with status per SC
|
|
11
13
|
- Notes on missing coverage or ambiguity
|
|
12
14
|
|
|
13
15
|
## Non-goals
|
|
@@ -22,6 +24,7 @@
|
|
|
22
24
|
security abuse, concurrency/idempotency/retry, and ops/observability coverage
|
|
23
25
|
- Do not use numeric targets; coverage must be proven by methods + saturation
|
|
24
26
|
- Contracts-first: cases must map to existing contracts only
|
|
27
|
+
- Do not declare completion until Coverage Ledger shows missing=0 (exceptions documented)
|
|
25
28
|
- If evidence is insufficient, request rework and document risks
|
|
26
29
|
|
|
27
30
|
## Output format
|
|
@@ -2,12 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
## Mission
|
|
4
4
|
|
|
5
|
-
- Create a phased plan with tests and risk controls.
|
|
5
|
+
- Create a phased plan with tests, coverage ledger steps, and risk controls.
|
|
6
6
|
|
|
7
7
|
## Deliverables
|
|
8
8
|
|
|
9
9
|
- Step-by-step plan
|
|
10
10
|
- Test strategy
|
|
11
|
+
- Coverage Ledger plan and exception register
|
|
11
12
|
- Risk and mitigation notes
|
|
12
13
|
|
|
13
14
|
## Non-goals
|
|
@@ -3,12 +3,14 @@
|
|
|
3
3
|
## Mission
|
|
4
4
|
|
|
5
5
|
- Identify edge cases and validation criteria for quality.
|
|
6
|
+
- Audit Coverage Ledger completeness (missing=0 or exceptions).
|
|
6
7
|
|
|
7
8
|
## Deliverables
|
|
8
9
|
|
|
9
10
|
- QA checklist
|
|
10
11
|
- Failure-case coverage
|
|
11
12
|
- Suggested regression tests
|
|
13
|
+
- Coverage Ledger audit findings
|
|
12
14
|
|
|
13
15
|
## Non-goals
|
|
14
16
|
|
|
@@ -20,6 +22,7 @@
|
|
|
20
22
|
|
|
21
23
|
- Follow `.qfai/assistant/instructions/*` and `.qfai/assistant/steering/*`
|
|
22
24
|
- Keep outputs specific and testable
|
|
25
|
+
- Do not fix missing coverage yourself; request rework when ledger is incomplete
|
|
23
26
|
- If evidence is missing, mark TBD and ask targeted questions
|
|
24
27
|
|
|
25
28
|
## Output format
|
|
@@ -3,11 +3,13 @@
|
|
|
3
3
|
## Mission
|
|
4
4
|
|
|
5
5
|
- Act as the final quality gate and approve only with strong evidence.
|
|
6
|
+
- Block approval unless Coverage Ledger is complete.
|
|
6
7
|
|
|
7
8
|
## Deliverables
|
|
8
9
|
|
|
9
10
|
- Gate decision with evidence summary
|
|
10
11
|
- Blocking issues and required rework list
|
|
12
|
+
- Coverage Ledger audit decision
|
|
11
13
|
|
|
12
14
|
## Non-goals
|
|
13
15
|
|
|
@@ -20,6 +22,7 @@
|
|
|
20
22
|
- Assume upstream artifacts have gaps; demand proof of coverage
|
|
21
23
|
- Contracts-first: traceability must map to existing contracts only
|
|
22
24
|
- Do not claim coverage by counts; use coverage techniques + saturation evidence
|
|
25
|
+
- Require missing=0 (or explicit exceptions) in the Coverage Ledger before approval
|
|
23
26
|
- If evidence is insufficient, stop the process and request rework
|
|
24
27
|
|
|
25
28
|
## Output format
|
|
@@ -3,11 +3,13 @@
|
|
|
3
3
|
## Mission
|
|
4
4
|
|
|
5
5
|
- Enforce test quality and completeness as the highest priority.
|
|
6
|
+
- Block approval unless Coverage Ledger is complete.
|
|
6
7
|
|
|
7
8
|
## Deliverables
|
|
8
9
|
|
|
9
10
|
- Review findings with strict acceptance criteria
|
|
10
11
|
- Escalation notes and required rework items
|
|
12
|
+
- Coverage Ledger audit decision
|
|
11
13
|
|
|
12
14
|
## Non-goals
|
|
13
15
|
|
|
@@ -20,6 +22,7 @@
|
|
|
20
22
|
- Assume upstream artifacts have gaps; review for missing cases
|
|
21
23
|
- Contracts-first: traceability must map to existing contracts only
|
|
22
24
|
- Do not claim coverage by counts; use coverage techniques + saturation evidence
|
|
25
|
+
- Require missing=0 (or explicit exceptions) in the Coverage Ledger before approval
|
|
23
26
|
- If evidence is insufficient, block approval and request rework
|
|
24
27
|
|
|
25
28
|
## Output format
|
|
@@ -3,11 +3,13 @@
|
|
|
3
3
|
## Mission
|
|
4
4
|
|
|
5
5
|
- Validate coverage, traceability, and contracts-first adherence.
|
|
6
|
+
- Audit Coverage Ledger completeness (missing=0 or exceptions).
|
|
6
7
|
|
|
7
8
|
## Deliverables
|
|
8
9
|
|
|
9
10
|
- Review findings on missing cases and traceability gaps
|
|
10
11
|
- Recommendations for additional tests or scenarios
|
|
12
|
+
- Coverage Ledger audit findings
|
|
11
13
|
|
|
12
14
|
## Non-goals
|
|
13
15
|
|
|
@@ -20,6 +22,7 @@
|
|
|
20
22
|
- Assume upstream artifacts have gaps; review for missing cases
|
|
21
23
|
- Contracts-first: traceability must map to existing contracts only
|
|
22
24
|
- Do not claim coverage by counts; use coverage techniques + saturation evidence
|
|
25
|
+
- Require missing=0 (or explicit exceptions) in the Coverage Ledger before approval
|
|
23
26
|
- If evidence is insufficient, request rework and document risks
|
|
24
27
|
|
|
25
28
|
## Output format
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
- New or updated tests
|
|
10
10
|
- Test data setup
|
|
11
11
|
- Coverage notes
|
|
12
|
+
- Coverage Ledger updates (done/missing/exception)
|
|
12
13
|
|
|
13
14
|
## Non-goals
|
|
14
15
|
|
|
@@ -20,6 +21,7 @@
|
|
|
20
21
|
|
|
21
22
|
- Follow `.qfai/assistant/instructions/*` and `.qfai/assistant/steering/*`
|
|
22
23
|
- Keep outputs specific and testable
|
|
24
|
+
- Always add SC evidence and update the Coverage Ledger
|
|
23
25
|
- If evidence is missing, mark TBD and ask targeted questions
|
|
24
26
|
|
|
25
27
|
## Output format
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
- Scope compliance review (ALLOWLIST vs DENYLIST)
|
|
10
10
|
- Traceability check on tests to SPEC/BR/SC
|
|
11
11
|
- Blocking issues and required follow-up actions
|
|
12
|
+
- Coverage Ledger completeness check (unit/component)
|
|
12
13
|
|
|
13
14
|
## Non-goals
|
|
14
15
|
|
|
@@ -22,6 +23,7 @@
|
|
|
22
23
|
- If the required test surface is missing, stop and request qfai-implement
|
|
23
24
|
- Ensure tests are deterministic and independent
|
|
24
25
|
- Require evidence of test commands and repo gate commands
|
|
26
|
+
- Require missing=0 (or explicit exceptions) in the Coverage Ledger
|
|
25
27
|
|
|
26
28
|
## Output format
|
|
27
29
|
|
|
@@ -22,13 +22,32 @@ mode: execution-focused
|
|
|
22
22
|
|
|
23
23
|
Turn `.qfai/specs/spec-XXXX/scenario.feature` into **runnable acceptance tests** (E2E/API/Integration) in this repository (terminal + CI).
|
|
24
24
|
|
|
25
|
+
## Scope (ATDD only)
|
|
26
|
+
|
|
27
|
+
- In scope: E2E, API, Integration.
|
|
28
|
+
- Out of scope: Unit and Component (use `/qfai-tdd-red`).
|
|
29
|
+
|
|
25
30
|
## Success Criteria (Definition of Done)
|
|
26
31
|
|
|
32
|
+
- Scenario Coverage is 100% for ATDD layers (E2E/API/Integration).
|
|
33
|
+
- An ATDD Coverage Ledger exists with `missing=0` and explicit exceptions.
|
|
27
34
|
- Acceptance tests exist and are runnable via documented commands.
|
|
28
35
|
- Tests are stable (no flakiness) and diagnostic (failures explain why).
|
|
29
36
|
- Existing acceptance automation (if any) is reused; no new framework is added without approval.
|
|
37
|
+
- QFAI validate passes for ATDD layers (layer-aware traceability).
|
|
30
38
|
- Quality checks (lint/typecheck/tests) pass in the repo’s standard way.
|
|
31
39
|
|
|
40
|
+
## ATDD Coverage Ledger (mandatory)
|
|
41
|
+
|
|
42
|
+
Create a ledger that lists every Scenario (SC) in ATDD scope:
|
|
43
|
+
|
|
44
|
+
- Inputs: `.qfai/specs/**/scenario.feature`
|
|
45
|
+
- Scope: `@layer-e2e`, `@layer-api`, `@layer-integration`
|
|
46
|
+
- Columns: SC ID / spec pack / layer / size / test file / run command / status (`done|missing|exception`)
|
|
47
|
+
- Rule: **`missing=0` is required before completion.**
|
|
48
|
+
|
|
49
|
+
If a test is not automatable right now, record it as `exception` with a clear reason and a follow-up plan.
|
|
50
|
+
|
|
32
51
|
## Non‑Negotiable Principles (QFAI Articles)
|
|
33
52
|
|
|
34
53
|
These principles are inspired by “constitution / articles” patterns used by other agent frameworks, but tailored to QFAI.
|
|
@@ -208,8 +227,11 @@ If acceptance/E2E automation exists:
|
|
|
208
227
|
|
|
209
228
|
If none exists:
|
|
210
229
|
|
|
211
|
-
- Propose
|
|
212
|
-
-
|
|
230
|
+
- Propose defaults by layer:
|
|
231
|
+
- E2E: Playwright Test
|
|
232
|
+
- Integration: Cucumber
|
|
233
|
+
- API: language-default test runner (project standard if any)
|
|
234
|
+
- Ask explicitly before adding any new dependencies or runners.
|
|
213
235
|
- Proceed only if the user approves. If not approved, stop and report.
|
|
214
236
|
|
|
215
237
|
## Step 2.5 — Implement Cucumber only when approved
|
|
@@ -229,15 +251,12 @@ Rules:
|
|
|
229
251
|
- Keep step definitions reusable but not overly generic.
|
|
230
252
|
- Ensure each scenario asserts observable behavior.
|
|
231
253
|
|
|
232
|
-
### SC
|
|
254
|
+
### SC evidence rule (mandatory)
|
|
233
255
|
|
|
234
|
-
Every test
|
|
256
|
+
Every test MUST provide traceability evidence using **one** of the following:
|
|
235
257
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
Where `SC-XXXX` matches the scenario tag in `scenario.feature`.
|
|
258
|
+
- Code-based tests: `QFAI:SC-XXXX-XXXX` annotation in the test file
|
|
259
|
+
- Cucumber feature tests: `@SC-XXXX-XXXX` tag on the Scenario
|
|
241
260
|
|
|
242
261
|
Example (TypeScript/JavaScript):
|
|
243
262
|
|
|
@@ -293,13 +312,15 @@ Provide:
|
|
|
293
312
|
|
|
294
313
|
**Before declaring tests complete, you MUST verify:**
|
|
295
314
|
|
|
296
|
-
1.
|
|
315
|
+
1. ATDD Coverage Ledger shows `missing=0` for E2E/API/Integration (exceptions documented).
|
|
316
|
+
|
|
317
|
+
2. Run QFAI validation:
|
|
297
318
|
|
|
298
319
|
```bash
|
|
299
320
|
qfai validate --fail-on error
|
|
300
321
|
```
|
|
301
322
|
|
|
302
|
-
|
|
323
|
+
3. Run repository standard gates (discover from package.json/CI/docs):
|
|
303
324
|
- format check
|
|
304
325
|
- lint
|
|
305
326
|
- typecheck
|
|
@@ -308,7 +329,7 @@ Provide:
|
|
|
308
329
|
|
|
309
330
|
Record the exact commands and results.
|
|
310
331
|
|
|
311
|
-
|
|
332
|
+
4. All gates must PASS.
|
|
312
333
|
|
|
313
334
|
If you cannot run these commands (environment limitation):
|
|
314
335
|
|
|
@@ -31,8 +31,9 @@ This prompt is intentionally strict. If you cannot satisfy the strict rules, you
|
|
|
31
31
|
- `scenario.feature` MAY contain multiple `Scenario:` / `Scenario Outline:` blocks.
|
|
32
32
|
- Recommended: **1-3 scenarios per spec pack**. If you need more, split into additional spec packs (e.g., `spec-0002`, `spec-0003`, ...).
|
|
33
33
|
- SC tags must be **unique within the file** (no duplicate SC across scenarios).
|
|
34
|
-
-
|
|
35
|
-
|
|
34
|
+
- Each Scenario MUST include exactly one layer tag and one size tag (`@layer-*`, `@size-*`).
|
|
35
|
+
- `spec.md` MUST keep Business Requirements atomic: **1 BR = 1 rule** in the form: `[BR-0001-0001][P0] ...`
|
|
36
|
+
- Keep BR count under a small cap (default max 5). If you need more, split into additional spec packs.
|
|
36
37
|
- `spec.md` MUST define **one primary feature slice** (one "thing" to implement). Do not define multiple features.
|
|
37
38
|
|
|
38
39
|
### Contracts First (Order of Work)
|
|
@@ -75,7 +76,7 @@ The following order is mandatory and must not be parallelized or rearranged:
|
|
|
75
76
|
|
|
76
77
|
- A new directory exists: `.qfai/specs/spec-XXXX/` (or an existing one is updated).
|
|
77
78
|
- These files exist and are coherent:
|
|
78
|
-
- `spec.md` (SDD spec; atomic slice; 1
|
|
79
|
+
- `spec.md` (SDD spec; atomic slice; BRs are 1-rule each, within the cap)
|
|
79
80
|
- `case-catalogue.md` (coverage techniques + saturation evidence)
|
|
80
81
|
- `delta.md` (Decision Log; includes candidates + rejected + deferred)
|
|
81
82
|
- `scenario.feature` (ATDD skeleton; multiple scenarios allowed; SC tags must be unique)
|
|
@@ -337,6 +338,7 @@ These constraints ensure spec packs align with QFAI's validate rules and prevent
|
|
|
337
338
|
- `scenario.feature` MAY contain multiple `Scenario:` / `Scenario Outline:` blocks.
|
|
338
339
|
- Recommended: **1-3 scenarios per spec pack**. If you need more, **split into separate spec packs** (`spec-0002`, `spec-0003`, ...).
|
|
339
340
|
- SC tags must be **unique within the file** (no duplicate SC across scenarios).
|
|
341
|
+
- Each Scenario MUST include exactly one layer tag and one size tag (`@layer-*`, `@size-*`).
|
|
340
342
|
|
|
341
343
|
Violation: If you exceed the recommended scenario count or duplicate SC tags, STOP and split/fix before continuing.
|
|
342
344
|
|
|
@@ -344,7 +346,8 @@ Violation: If you exceed the recommended scenario count or duplicate SC tags, ST
|
|
|
344
346
|
|
|
345
347
|
A spec pack is **too large** if ANY of these are true:
|
|
346
348
|
|
|
347
|
-
- BR lines exceed
|
|
349
|
+
- BR lines exceed the cap (default max 5)
|
|
350
|
+
- Any BR bundles multiple rules (use separate BRs instead)
|
|
348
351
|
- **Two or more user roles** appear as the subject (e.g., admin AND regular user)
|
|
349
352
|
- **Two or more primary user actions (When)** exist (e.g., register AND delete)
|
|
350
353
|
- **Multiple external interface groups** are mixed (e.g., 2+ API endpoint families in one spec)
|
|
@@ -353,7 +356,7 @@ Split rule (simple):
|
|
|
353
356
|
|
|
354
357
|
- Separate by user action (register / update / delete / etc.).
|
|
355
358
|
- Error flows also require their own spec pack if they add scenarios.
|
|
356
|
-
- If
|
|
359
|
+
- If BR count exceeds the cap or a BR contains multiple rules, split into additional spec packs.
|
|
357
360
|
|
|
358
361
|
### (C) ID format (machine-verifiable)
|
|
359
362
|
|
|
@@ -388,7 +391,8 @@ Before finalizing the spec pack, verify:
|
|
|
388
391
|
|
|
389
392
|
- [ ] Scenario count is within the recommended range (1-3), or the pack is split
|
|
390
393
|
- [ ] SC tags are unique within `scenario.feature`
|
|
391
|
-
- [ ]
|
|
394
|
+
- [ ] Each Scenario has exactly one layer tag and one size tag
|
|
395
|
+
- [ ] BRs are 1-rule each and within the cap (default max 5)
|
|
392
396
|
- [ ] `case-catalogue.md` exists with coverage + saturation evidence
|
|
393
397
|
- [ ] `traceability-matrix.md` exists and links AC <-> BR <-> CASE <-> Examples
|
|
394
398
|
- [ ] All referenced `.qfai/contracts/**` files exist (missing = 0)
|
|
@@ -603,6 +607,7 @@ Create a minimal but correct Gherkin skeleton aligned with acceptance criteria.
|
|
|
603
607
|
- Recommended: **1-3 scenarios per spec pack**. If you need more, split into separate spec packs.
|
|
604
608
|
- Feature must include exactly one `@SPEC-0001` tag.
|
|
605
609
|
- Each Scenario must include exactly one `@SC-0001-0001` tag and at least one `@BR-0001-0001` tag.
|
|
610
|
+
- Each Scenario must include exactly one `@layer-*` tag and one `@size-*` tag.
|
|
606
611
|
- SC tags must be unique across scenarios in the file.
|
|
607
612
|
|
|
608
613
|
Template:
|
|
@@ -615,7 +620,7 @@ Feature: <Feature name>
|
|
|
615
620
|
Background:
|
|
616
621
|
Given <common preconditions>
|
|
617
622
|
|
|
618
|
-
@SC-0001-0001 @BR-0001-0001
|
|
623
|
+
@SC-0001-0001 @BR-0001-0001 @layer-api @size-s
|
|
619
624
|
Scenario: <scenario name>
|
|
620
625
|
Given <specific precondition>
|
|
621
626
|
When <user action>
|
|
@@ -33,10 +33,16 @@ Implement production code according to **spec + contracts + scenario** so the RE
|
|
|
33
33
|
|
|
34
34
|
- Implementation matches the spec and contracts.
|
|
35
35
|
- TDD tests pass (and ATDD tests pass when applicable).
|
|
36
|
+
- Unit/Component Coverage Ledger shows `missing=0` (exceptions documented).
|
|
36
37
|
- Repo quality gates pass (lint/type/build/pack as applicable).
|
|
37
38
|
- Verification evidence is recorded (commands + results).
|
|
38
39
|
- Program is runnable; runtime evidence is recorded and meets project-type expectations.
|
|
39
40
|
|
|
41
|
+
## Coverage Ledger continuity
|
|
42
|
+
|
|
43
|
+
- Review the Unit/Component Coverage Ledger from `/qfai-tdd-red`.
|
|
44
|
+
- Do not declare completion until `missing=0` and exceptions are documented.
|
|
45
|
+
|
|
40
46
|
## Non‑Negotiable Principles (QFAI Articles)
|
|
41
47
|
|
|
42
48
|
These principles are inspired by “constitution / articles” patterns used by other agent frameworks, but tailored to QFAI.
|
|
@@ -300,15 +306,17 @@ Iterate until all gates pass, prioritizing:
|
|
|
300
306
|
|
|
301
307
|
**Before declaring implementation complete, you MUST verify:**
|
|
302
308
|
|
|
303
|
-
1.
|
|
309
|
+
1. Unit/Component Coverage Ledger shows `missing=0` (exceptions documented).
|
|
310
|
+
|
|
311
|
+
2. Runtime evidence commands executed and outcomes recorded.
|
|
304
312
|
|
|
305
|
-
|
|
313
|
+
3. Run QFAI validation:
|
|
306
314
|
|
|
307
315
|
```bash
|
|
308
316
|
qfai validate --fail-on error
|
|
309
317
|
```
|
|
310
318
|
|
|
311
|
-
|
|
319
|
+
4. Run repository standard gates (discover from package.json/CI/docs):
|
|
312
320
|
- format check
|
|
313
321
|
- lint
|
|
314
322
|
- typecheck
|
|
@@ -317,7 +325,7 @@ Iterate until all gates pass, prioritizing:
|
|
|
317
325
|
|
|
318
326
|
Record the exact commands and results.
|
|
319
327
|
|
|
320
|
-
|
|
328
|
+
5. All gates must PASS.
|
|
321
329
|
|
|
322
330
|
If you cannot run these commands (environment limitation):
|
|
323
331
|
|
|
@@ -8,7 +8,7 @@ QFAI Prompt Body (SSOT)
|
|
|
8
8
|
|
|
9
9
|
id: qfai-tdd-red
|
|
10
10
|
title: QFAI TDD Red (Test-first)
|
|
11
|
-
description: "Implement fast tests first (unit/component
|
|
11
|
+
description: "Implement fast tests first (unit/component) and stop at RED."
|
|
12
12
|
argument-hint: "<spec-id> [--auto]"
|
|
13
13
|
allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
|
|
14
14
|
roles: [UnitTestScopeEnforcer, TestEngineer, QAEngineer, CodeReviewer]
|
|
@@ -20,7 +20,12 @@ mode: test-first
|
|
|
20
20
|
|
|
21
21
|
## Purpose
|
|
22
22
|
|
|
23
|
-
Implement **fast tests** (unit/component
|
|
23
|
+
Implement **fast tests** (unit/component) that enforce the spec and provide fast feedback.
|
|
24
|
+
|
|
25
|
+
## Scope (TDD Red only)
|
|
26
|
+
|
|
27
|
+
- In scope: Unit and Component tests.
|
|
28
|
+
- Out of scope: E2E/API/Integration (use `/qfai-atdd`).
|
|
24
29
|
|
|
25
30
|
## Scope Guardrails (tests-only)
|
|
26
31
|
|
|
@@ -68,14 +73,26 @@ If tests cannot proceed because implementation is missing:
|
|
|
68
73
|
|
|
69
74
|
## Success Criteria (Definition of Done)
|
|
70
75
|
|
|
71
|
-
- Unit tests exist, are deterministic, and runnable in CI.
|
|
72
|
-
-
|
|
76
|
+
- Unit/Component tests exist, are deterministic, and runnable in CI.
|
|
77
|
+
- Coverage Ledger for Unit/Component shows `missing=0` (exceptions documented).
|
|
78
|
+
- Completion is based on executing the unit/component test suite and recording evidence.
|
|
73
79
|
- Tests cover core logic and key edge cases derived from spec/scenario.
|
|
74
|
-
- Tests fail meaningfully (
|
|
80
|
+
- Tests fail meaningfully and the failing state is observed (RED evidence).
|
|
75
81
|
- All changes stay within the ALLOWLIST.
|
|
76
82
|
- Any production-code change includes an explicit exception rationale.
|
|
77
83
|
- Repository verification commands PASS unless you are stopped at RED due to missing implementation.
|
|
78
84
|
|
|
85
|
+
## TDD Coverage Ledger (Unit/Component)
|
|
86
|
+
|
|
87
|
+
Create a ledger that lists every Scenario (SC) in Unit/Component scope:
|
|
88
|
+
|
|
89
|
+
- Inputs: `.qfai/specs/**/scenario.feature`
|
|
90
|
+
- Scope: `@layer-unit`, `@layer-component`
|
|
91
|
+
- Columns: SC ID / layer / target unit or component / test file / status (`done|missing|exception`)
|
|
92
|
+
- Rule: **`missing=0` is required before completion.**
|
|
93
|
+
|
|
94
|
+
If a test is not automatable right now, record it as `exception` with a clear reason and a follow-up plan.
|
|
95
|
+
|
|
79
96
|
## Non‑Negotiable Principles (QFAI Articles)
|
|
80
97
|
|
|
81
98
|
These principles are inspired by “constitution / articles” patterns used by other agent frameworks, but tailored to QFAI.
|
|
@@ -146,11 +163,12 @@ Simulate roles by running the same sequence yourself:
|
|
|
146
163
|
|
|
147
164
|
1. Identify the target scope from SPEC/BR/AC/CASE/Scenario.
|
|
148
165
|
2. Identify existing test framework and conventions; follow them.
|
|
149
|
-
3.
|
|
166
|
+
3. Build the Unit/Component Coverage Ledger and list missing items.
|
|
167
|
+
4. Implement unit/component tests:
|
|
150
168
|
- prioritize edge/error cases and invariants derived from CASE catalogue
|
|
151
169
|
- ensure tests are deterministic and independent
|
|
152
|
-
|
|
153
|
-
|
|
170
|
+
5. Run unit/component tests.
|
|
171
|
+
6. Run repository verification commands and record evidence.
|
|
154
172
|
|
|
155
173
|
## Step 0 — Load Context (always)
|
|
156
174
|
|
|
@@ -33,9 +33,15 @@ Refactor the codebase **without behavior change** after tests are green, preserv
|
|
|
33
33
|
|
|
34
34
|
- Behavior remains unchanged and matches the spec and contracts.
|
|
35
35
|
- TDD/ATDD tests remain green after refactor.
|
|
36
|
+
- Unit/Component Coverage Ledger remains `missing=0` (exceptions documented).
|
|
36
37
|
- Repo quality gates pass (lint/type/build/pack as applicable).
|
|
37
38
|
- Verification evidence is recorded (commands + results).
|
|
38
39
|
|
|
40
|
+
## Coverage Ledger continuity
|
|
41
|
+
|
|
42
|
+
- Review the Unit/Component Coverage Ledger from `/qfai-tdd-red`.
|
|
43
|
+
- Do not declare completion if the ledger regresses (missing must remain 0).
|
|
44
|
+
|
|
39
45
|
## Non‑Negotiable Principles (QFAI Articles)
|
|
40
46
|
|
|
41
47
|
These principles are inspired by “constitution / articles” patterns used by other agent frameworks, but tailored to QFAI.
|
|
@@ -299,15 +305,17 @@ Iterate until all gates pass, prioritizing:
|
|
|
299
305
|
|
|
300
306
|
**Before declaring implementation complete, you MUST verify:**
|
|
301
307
|
|
|
302
|
-
1.
|
|
308
|
+
1. Unit/Component Coverage Ledger shows `missing=0` (exceptions documented).
|
|
309
|
+
|
|
310
|
+
2. Runtime evidence commands executed and outcomes recorded.
|
|
303
311
|
|
|
304
|
-
|
|
312
|
+
3. Run QFAI validation:
|
|
305
313
|
|
|
306
314
|
```bash
|
|
307
315
|
qfai validate --fail-on error
|
|
308
316
|
```
|
|
309
317
|
|
|
310
|
-
|
|
318
|
+
4. Run repository standard gates (discover from package.json/CI/docs):
|
|
311
319
|
- format check
|
|
312
320
|
- lint
|
|
313
321
|
- typecheck
|
|
@@ -316,7 +324,7 @@ Iterate until all gates pass, prioritizing:
|
|
|
316
324
|
|
|
317
325
|
Record the exact commands and results.
|
|
318
326
|
|
|
319
|
-
|
|
327
|
+
5. All gates must PASS.
|
|
320
328
|
|
|
321
329
|
If you cannot run these commands (environment limitation):
|
|
322
330
|
|
|
@@ -9,6 +9,11 @@ validation:
|
|
|
9
9
|
failOn: error
|
|
10
10
|
require:
|
|
11
11
|
specSections: []
|
|
12
|
+
testStrategy:
|
|
13
|
+
requireLayerTags: false
|
|
14
|
+
requireSizeTags: false
|
|
15
|
+
maxE2eScenarioRatio: null
|
|
16
|
+
maxE2eScenarioCount: null
|
|
12
17
|
traceability:
|
|
13
18
|
brMustHaveSc: true
|
|
14
19
|
scMustHaveTest: true
|
|
@@ -17,6 +22,7 @@ validation:
|
|
|
17
22
|
- tests/**/*.spec.ts
|
|
18
23
|
- src/**/*.test.ts
|
|
19
24
|
- src/**/*.spec.ts
|
|
25
|
+
- features/**/*.feature
|
|
20
26
|
testFileExcludeGlobs: []
|
|
21
27
|
scNoTestSeverity: error
|
|
22
28
|
orphanContractsPolicy: error
|