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 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 (ATDD) driven by specs/scenarios.
66
- - **qfai-tdd-red**: Implement fast tests first (unit/component/integration).
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 Cucumber as the default option and explain pros/cons and posture fit.
212
- - Ask explicitly: "Do you allow adding Cucumber and related dependencies?"
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 annotation rule (mandatory)
254
+ ### SC evidence rule (mandatory)
233
255
 
234
- Every test function/block MUST include a traceability annotation:
256
+ Every test MUST provide traceability evidence using **one** of the following:
235
257
 
236
- ```
237
- QFAI:SC-XXXX
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. Run QFAI validation:
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
- 2. Run repository standard gates (discover from package.json/CI/docs):
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
- 3. All gates must PASS.
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
- - `spec.md` MUST contain **exactly 1** Business Requirement in the form: `[BR-0001-0001][P0] ...`
35
- - If you need 2+ BRs, split into additional spec packs.
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 BR)
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 **1** (max 1; one slice = one BR)
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 you need 2+ BRs, STOP and create additional spec packs.
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
- - [ ] BR lines = 1 (exactly one BR per spec pack)
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. Runtime evidence commands executed and outcomes recorded.
309
+ 1. Unit/Component Coverage Ledger shows `missing=0` (exceptions documented).
310
+
311
+ 2. Runtime evidence commands executed and outcomes recorded.
304
312
 
305
- 2. Run QFAI validation:
313
+ 3. Run QFAI validation:
306
314
 
307
315
  ```bash
308
316
  qfai validate --fail-on error
309
317
  ```
310
318
 
311
- 3. Run repository standard gates (discover from package.json/CI/docs):
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
- 4. All gates must PASS.
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/integration) and stop at RED."
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/integration) that enforce the spec and provide fast feedback.
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
- - Completion is based on executing the unit test suite and recording evidence.
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 (actionable errors).
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. Implement unit tests:
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
- 4. Run unit tests.
153
- 5. Run repository verification commands and record evidence.
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. Runtime evidence commands executed and outcomes recorded.
308
+ 1. Unit/Component Coverage Ledger shows `missing=0` (exceptions documented).
309
+
310
+ 2. Runtime evidence commands executed and outcomes recorded.
303
311
 
304
- 2. Run QFAI validation:
312
+ 3. Run QFAI validation:
305
313
 
306
314
  ```bash
307
315
  qfai validate --fail-on error
308
316
  ```
309
317
 
310
- 3. Run repository standard gates (discover from package.json/CI/docs):
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
- 4. All gates must PASS.
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