qfai 1.2.13 → 1.3.0

package/README.md

@@ -63,7 +63,7 @@ QFAI includes a small set of custom prompts (stored under `.qfai/assistant/promp
 - **qfai-spec**: Produce `.qfai/specs/*` and `.qfai/contracts/*` from the requirements, including traceability scaffolding.
   - Includes a preflight step that bootstraps missing `qfai.config.yaml` and `assistant/steering/*` when run directly after init.
 - **qfai-prototyping**: Implement a minimal runnable skeleton (UI + API + DB) from contracts before test automation. Run after `/qfai-spec` to ensure the app is runnable with `pnpm dev` (or equivalent) before writing tests.
-- **qfai-atdd**: Implement acceptance tests (E2E/API/Integration) and drive Scenario Coverage to 100% using a Coverage Ledger.
+- **qfai-atdd**: Implement acceptance tests (E2E/API/Integration), enforce layer floors, and drive Coverage Ledger to 100% (sub-agents required when supported).
 - **qfai-tdd-red**: Implement fast tests first (unit/component) and drive Unit/Component Scenario Coverage to 100% using a Coverage Ledger.
 - **qfai-tdd-green**: Implement production code to make the tests pass.
 - **qfai-tdd-refactor**: Refactor safely after tests are green.
@@ -112,7 +112,7 @@ AG-->>U: Runnable prototype ready (dev server starts)
 
 U->>AG: Run /qfai-atdd
 AG->>Q: Read .qfai/assistant/prompts/qfai-atdd.md
-AG->>R: Implement acceptance tests
+AG->>R: Implement acceptance tests (3 layers + floors)
 AG-->>U: Acceptance tests ready
 
 U->>AG: Run /qfai-tdd-red
@@ -143,8 +143,8 @@ Operational notes.
 - Each custom prompt must output in the user’s language (absolute requirement).
 - Prompts must consult instructions/steering and delta.md; rejected options must not be reintroduced without a [RE-OPEN] Decision Record.
 - Except `qfai-discuss`, each prompt must analyze the project context (architecture, tech stack, test framework, repo structure) before generating artifacts or code.
-- Prompts should delegate work to multiple role-based sub-agents (Researcher, Planner, Architect, Contract Designer, QA, Code Reviewer, etc.) to emulate a real delivery flow.
-- /qfai-atdd and /qfai-tdd-red must maintain a Coverage Ledger and do not declare completion until missing=0 (exceptions documented).
+- Prompts must delegate work to role-based sub-agents when supported; Orchestrator does not implement and Reviewer is non-edit.
+- /qfai-atdd and /qfai-tdd-red must maintain a Coverage Ledger and do not declare completion until 100% implemented (exceptions require DR + approval).
 
 ## Configuration
 

package/assets/init/.qfai/assistant/agents/atdd-api-implementer.md

@@ -0,0 +1,47 @@
+# ATDD API Implementer
+
+## Mission
+
+- Implement all `layer=api` entries in the ATDD Coverage Ledger.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/scenario.feature
+- .qfai/contracts/api/\*\*
+- ATDD Coverage Ledger
+- Existing API test stack (if any)
+
+## Deliverables (MANDATORY)
+
+- Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
+- API test files (reuse existing stack)
+- Endpoint -> test mapping (ledger updates)
+- Execution logs (commands + results)
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- Rejected option would be reintroduced without RE-OPEN DR
+- Ledger missing or layer=api floor not met
+- API test stack missing and no approval to add one
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] API floor met (or DR-approved exception)
+- [ ] Ledger mapping is updated
+
+## Output format (structured)
+
+- Decision Records (DR-IDs) / rejected check
+- Implemented files list
+- Mapping summary (endpoint -> test)
+- Execution log summary
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/atdd-e2e-implementer.md

@@ -0,0 +1,46 @@
+# ATDD E2E Implementer
+
+## Mission
+
+- Implement all `layer=e2e` entries in the ATDD Coverage Ledger.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/scenario.feature
+- ATDD Coverage Ledger
+- Existing E2E framework/config (if any)
+
+## Deliverables (MANDATORY)
+
+- Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
+- E2E test files (Playwright preferred; reuse existing stack)
+- SC -> test mapping (ledger updates)
+- Execution logs (commands + results)
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- Rejected option would be reintroduced without RE-OPEN DR
+- Ledger missing or layer=e2e floor not met
+- E2E framework missing and no approval to add one
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] E2E floor met (or DR-approved exception)
+- [ ] Ledger mapping is updated
+
+## Output format (structured)
+
+- Decision Records (DR-IDs) / rejected check
+- Implemented files list
+- Mapping summary (SC -> test)
+- Execution log summary
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/atdd-integration-implementer.md

@@ -0,0 +1,47 @@
+# ATDD Integration Implementer
+
+## Mission
+
+- Implement all `layer=integration` entries in the ATDD Coverage Ledger.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/scenario.feature
+- .qfai/specs/spec-\*/case-catalogue.md
+- ATDD Coverage Ledger
+- Existing integration test stack (Cucumber preferred)
+
+## Deliverables (MANDATORY)
+
+- Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
+- Integration test files (Cucumber preferred; reuse existing stack)
+- CASE/endpoint -> test mapping (ledger updates)
+- Execution logs (commands + results)
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- Rejected option would be reintroduced without RE-OPEN DR
+- Ledger missing or layer=integration floor not met
+- Integration test stack missing and no approval to add one
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] Integration floor met (or DR-approved exception)
+- [ ] Ledger mapping is updated
+
+## Output format (structured)
+
+- Decision Records (DR-IDs) / rejected check
+- Implemented files list
+- Mapping summary (CASE/EP -> test)
+- Execution log summary
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/doc-steward.md

@@ -0,0 +1,38 @@
+# Doc Steward
+
+## Mission
+
+- Update documentation impacted by prompt/agent changes.
+- Prevent duplicate sources; point to README templates as SSOT.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- CHANGELOG.md / README.md / docs/\*\*
+- Prompt/agent diffs
+
+## Deliverables (MANDATORY)
+
+- Doc impact checklist (what changed, where to update)
+- Updated docs/README/mermaid (as needed)
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- Evidence is missing or incomplete
+- Doc updates are required but not identified
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] Docs updated or explicitly listed as TODO
+
+## Output format (structured)
+
+- Impacted docs list
+- Changes made
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/orchestrator.md

@@ -0,0 +1,45 @@
+# Orchestrator
+
+## Mission
+
+- Plan, delegate, integrate, and decide pass/fail (no direct implementation when subagents exist).
+- Enforce stage gates, DoD, and evidence capture.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
+- Prompt-specific artifacts (ledgers, traceability, evidence)
+
+## Deliverables (MANDATORY)
+
+- Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
+- Work Orders for each subagent (scope, inputs, outputs, gates)
+- Stage Gates plan + current status
+- Completion report (DoD checklist + evidence links)
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- Subagent delegation missing when required
+- Ledger missing or not 100% implemented
+- Reviewer sign-off missing
+- Rejected option would be reintroduced without RE-OPEN DR
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] Stage gates are PASS
+- [ ] Reviewer sign-off recorded
+
+## Output format (structured)
+
+- Decision Records (DR-IDs) / rejected check
+- Work Orders
+- Stage Gates status
+- Completion report (DoD)
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/researcher.md

@@ -18,6 +18,7 @@
 - Research memo (English sources summarized in the user's language)
 - Glossary of key terms
 - Risk/constraint notes and candidate question angles
+- 3-choice question candidates (+ "recommend for me")
 - Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
 ## Stop conditions (Blockers)

package/assets/init/.qfai/assistant/agents/reviewer.md

@@ -0,0 +1,43 @@
+# Reviewer
+
+## Mission
+
+- Audit compliance with Completion Contract and prompt DoD.
+- Non-edit only: return pass/fail and concrete rework instructions.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
+- Coverage ledgers + evidence + gate results
+
+## Deliverables (MANDATORY)
+
+- Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
+- Review notes (PASS or rework list)
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Must-reject conditions
+
+- Coverage Ledger missing or not 100% implemented (no approved exception)
+- E2E=0 or Integration=0 without DR + approval
+- Subagent delegation missing when required
+- delta.md rejected option reintroduced without RE-OPEN DR
+- Runtime Gate not executed (when required by prompt)
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] Rework list is concrete and actionable
+- [ ] PASS only when DoD is satisfied
+
+## Output format (structured)
+
+- Decision Records (DR-IDs) / rejected check
+- PASS or FAIL
+- Rework list (if FAIL)
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/runtime-gatekeeper.md

@@ -16,7 +16,8 @@
 
 - Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
 - Runtime commands executed + key outputs
-- Runtime smoke evidence (UI interaction if applicable)
+- Runtime smoke evidence (boot + access + interaction; include URL)
+- Test execution logs when required (unit/e2e/integration/api)
 - Reproducibility notes (ports, env, data)
 - Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 

package/assets/init/.qfai/assistant/agents/test-engineer.md

@@ -17,7 +17,7 @@
 
 - Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
 - Automation plan per layer (unit/component/integration/api/e2e)
-- Coverage ledger with missing=0 goal and exceptions documented
+- Coverage ledger is 100% implemented (blocked/skipped require DR + approval)
 - Execution proof (commands + key outputs)
 - Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 

package/assets/init/.qfai/assistant/agents/test-volume-estimator.md

@@ -0,0 +1,46 @@
+# Test Volume Estimator
+
+## Mission
+
+- Compute ATDD floors (E2E/API/Integration) and detect underestimation.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/scenario.feature
+- .qfai/specs/spec-\*/case-catalogue.md
+- .qfai/specs/spec-\*/traceability-matrix.md
+- .qfai/contracts/\*\*
+
+## Deliverables (MANDATORY)
+
+- Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
+- Floor estimate table (Layer / Raw count / Multiplier / Floor / Evidence / Notes)
+- K rationale (3..5) with complexity signals
+- BLOCKED list when data is missing
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- Rejected option would be reintroduced without RE-OPEN DR
+- Endpoint count cannot be derived and no fallback is available
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] Floors are justified with evidence
+- [ ] BLOCKED items are explicit
+
+## Output format (structured)
+
+- Decision Records (DR-IDs) / rejected check
+- Floor table
+- K rationale
+- BLOCKED list (if any)
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/instructions/agent-selection.md

@@ -13,6 +13,8 @@ Delegate work to specialized roles to reduce blind spots and improve quality.
 ## Default delegation map
 
 - **Researcher**: collect pre-knowledge (English sources), glossary, risks, and question angles
+- **Orchestrator**: plan, delegate, integrate, and enforce stage gates (no direct implementation)
+- **Test Volume Estimator**: compute ATDD floors and detect underestimation
 - **OQ Harvester**: extract undefined/ambiguous decisions and draft question candidates
 - **OQ Reviewer**: review OQ candidates for completeness, neutrality, and safe deferral
 - **Option Explorer**: propose multiple solution options + trade-offs + recommendation for delta.md
@@ -23,10 +25,14 @@ Delegate work to specialized roles to reduce blind spots and improve quality.
 - **Contract Designer**: contracts (UI/API: YAML, DB: SQL), IDs, indexing implications
 - **QA Engineer**: risk-based checks, regression scope, quality gate review
 - **Test Engineer**: scenario.feature and test scaffolding strategy
+- **ATDD Implementers**: E2E/API/Integration implementation per ledger and floors
 - **Front-end / Back-end Engineer**: implementation within repo conventions
 - **UI/UX Reviewer**: layout sanity, interaction usability, and UI guardrail checks
 - **DevOps/CI Engineer**: verify-pack/CI impacts
 - **Code Reviewer**: style, maintainability, correctness
+- **Reviewer**: non-edit completion audit (PASS/FAIL + rework list)
+- **Runtime Gatekeeper**: runtime evidence and smoke verification
+- **Doc Steward**: doc impact analysis and README/mermaid updates
 
 ## If subagents are not supported
 

package/assets/init/.qfai/assistant/instructions/workflow.md

@@ -14,6 +14,22 @@ This file defines the canonical stages and delegation expectations.
 
 ---
 
+## Change Type (Mandatory)
+
+At the start of any work, classify the change and record it in:
+
+- `delta.md` Change Log (latest CL entry)
+- PR description (Change Type section)
+
+Allowed values:
+
+- Primary: `Initial | Behavior | Structural | Ops`
+- Tags (optional): `@ui @api @db @nfr @docs @test`
+
+Do not proceed without a declared Change Type.
+
+---
+
 ## Stages (canonical)
 
 0. Steering refresh (project memory bootstrap)

package/assets/init/.qfai/assistant/prompts/qfai-atdd.md

@@ -11,7 +11,7 @@ title: QFAI ATDD (Executable acceptance tests)
 description: "Implement automated acceptance tests (E2E/API/Integration) aligned with scenario.feature and specs."
 argument-hint: "<spec-id> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [TestEngineer, QAEngineer, BackendEngineer, FrontendEngineer, CodeReviewer, DevOpsCIEngineer]
+roles: [Orchestrator, TestVolumeEstimator, ATDDE2EImplementer, ATDDAPIImplementer, ATDDIntegrationImplementer, QAEngineer, TestEngineer, BackendEngineer, FrontendEngineer, Reviewer, RuntimeGatekeeper, DevOpsCIEngineer, CodeReviewer]
 mode: execution-focused
 
 ---
@@ -46,7 +46,10 @@ When unsure, read inputs in this order:
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Do NOT declare completion based on unit/component tests.
-- Acceptance tests must be runnable and Coverage Ledger must reach `missing=0` (exceptions documented).
+- Acceptance tests must be runnable and Coverage Ledger must be 100% implemented (blocked/skipped require DR + approval).
+- You MUST enforce layer floors (E2E=SC count, API=endpoints, Integration=max(endpoints×K, ΣCASE)).
+- E2E=0 or Integration=0 is forbidden unless a DR + user approval + reviewer PASS explicitly allows it.
+- Orchestrator MUST NOT implement tests directly when subagents are available (delegate work orders).
 - You MUST produce the required evidence file: `.qfai/evidence/atdd-<spec-id>.md`.
   - `.qfai/evidence/` is intentionally NOT tracked by Git (it ships with a local `.gitignore`).
   - Do NOT commit evidence files; summarize key outcomes in the PR description instead.
@@ -54,6 +57,17 @@ When unsure, read inputs in this order:
 - You MUST stop and escalate if scenarios are left unimplemented without explicit exclusions.
 - Completion must be approved by a reviewer who did not implement the tests.
 
+## Sub-agent policy (mandatory)
+
+- If subagents are supported, Orchestrator MUST delegate:
+  - Test Volume Estimator
+  - ATDD E2E/API/Integration Implementers
+  - Reviewer (non-edit)
+  - Runtime Gatekeeper
+- Orchestrator is responsible for plan, delegation, integration, and pass/fail only (no direct test implementation).
+- Evidence MUST include Work Orders + implementer outputs + reviewer notes.
+- If subagents are NOT supported, simulate role separation with explicit role sections and keep Reviewer non-edit.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:
@@ -72,28 +86,83 @@ Turn `.qfai/specs/spec-XXXX/scenario.feature` into runnable acceptance tests (E2
 - In scope: E2E, API, Integration.
 - Out of scope: Unit and Component (use `/qfai-tdd-red`).
 
+## Non-goals
+
+- Unit/Component test implementation (handled in `/qfai-tdd-red`).
+- Product feature changes beyond what is needed to make ATDD tests runnable.
+
+## Mandatory Outputs
+
+1. Test Volume Estimate (floor table with evidence)
+2. ATDD Coverage Ledger (path + per-SC mapping)
+3. Implemented tests per layer (E2E/API/Integration)
+4. Traceability updates (traceability-matrix status planned/implemented)
+5. Reviewer notes (PASS or concrete rework list; non-edit)
+6. Evidence file: `.qfai/evidence/atdd-<spec-id>.md`
+
+## Test Volume Floor (mandatory)
+
+- E2E floor = number of E2E-target scenarios
+- API floor = number of endpoints (OpenAPI/contract derived)
+- Integration floor = max(endpoints × K, ΣCASE)
+  - K default = 3; raise to 4-5 for higher complexity (search, roles, workflow, heavy validation, concurrency)
+- If ΣCASE < endpoints × K, add cases or log a spec improvement task and still implement to the floor.
+
+### Estimator output table (required)
+
+| Layer       | Raw count | Multiplier |   Floor | Evidence               | Notes |
+| ----------- | --------: | ---------: | ------: | ---------------------- | ----- |
+| E2E         |   #SC_e2e |         ×1 | E2E_min | scenario.feature       |       |
+| API         |       #EP |         ×1 | API_min | contracts/openapi      |       |
+| Integration |       #EP |         ×K | INT_min | contracts + complexity |       |
+
+## Endpoint count rule (deterministic)
+
+1. contracts/OpenAPI (preferred)
+2. traceability-matrix endpoint list (if present)
+3. route definitions (only if reliably detectable)
+4. otherwise: BLOCKED (request missing info)
+
+## Layer selection rule (when @layer is missing)
+
+- UI interaction / navigation → e2e
+- Pure HTTP/API flow → api
+- Cross-boundary or step-reuse value → integration
+- If ambiguous, raise a DR in delta.md and do not guess.
+
 ## Success Criteria (Definition of Done)
 
 - Scenario Coverage is 100% for ATDD layers (E2E/API/Integration).
-- An ATDD Coverage Ledger exists with `missing=0` and explicit exceptions.
+- An ATDD Coverage Ledger exists with 100% implemented (blocked/skipped require DR + approval).
+- Layer floors are met for E2E/API/Integration (exceptions require DR + approval).
+- E2E=0 / Integration=0 is NOT allowed without an approved exception.
 - Acceptance tests exist and are runnable via documented commands.
 - Tests are stable (no flakiness) and diagnostic (failures explain why).
 - Existing acceptance automation (if any) is reused; no new framework is added without approval.
 - QFAI validate passes for ATDD layers (layer-aware traceability).
 - Quality checks (lint/typecheck/tests) pass in the repo’s standard way.
 - Evidence file exists: `.qfai/evidence/atdd-<spec-id>.md`.
+- Work Orders + Implementer outputs + Reviewer notes are captured in evidence.
 - Completion is approved by a reviewer who did not implement the tests.
 
 ## Mandatory checks
 
 - Layer allocation (`@layer`/`@size`) is applied per scenario.
 - Coverage ledger includes each scenario and its automation status.
+- Test Volume Estimate exists and floors are met.
+- traceability-matrix status is updated (planned/implemented).
 - Runtime evidence exists for each implemented layer.
 
 ## Not-done criteria
 
 - Scenarios left unimplemented without explicit "excluded" rationale.
 - Tests exist but were never executed.
+- E2E=0 or Integration=0 without DR + approval.
+
+## Failure handling (mandatory)
+
+- If blocked/unknown, stop and raise a DR in delta.md (do not skip).
+- Do not declare completion when any gate is FAIL; loop until PASS.
 
 ## ATDD Coverage Ledger (mandatory)
 
@@ -101,10 +170,11 @@ Create a ledger that lists every Scenario (SC) in ATDD scope:
 
 - Inputs: `.qfai/specs/**/scenario.feature`
 - Scope: `@layer-e2e`, `@layer-api`, `@layer-integration`
-- Columns: SC ID / spec pack / layer / size / test file / run command / status (`done|missing|exception`)
-- Rule: **`missing=0` is required before completion.**
+- Preferred path: `.qfai/specs/<spec-id>/atdd/coverage-ledger.md` (or repo-defined location from README)
+- Columns: SC ID / spec pack / layer / size / test asset / run command / status (`implemented|blocked|skipped-with-decision`) / DR-ID
+- Rule: **all SC entries must be implemented** unless DR-approved blocked/skipped.
 
-If a test is not automatable right now, record it as `exception` with a clear reason and a follow-up plan.
+If a test is not automatable right now, record it as `blocked` and link a DR in delta.md with user approval.
 
 ## Evidence (MANDATORY)
 
@@ -112,8 +182,10 @@ Create and update: `.qfai/evidence/atdd-<spec-id>.md`
 
 Evidence must include:
 
-- acceptance coverage ledger (SC -> layer -> implemented files -> command)
+- test volume estimate (floor table + evidence)
+- acceptance coverage ledger (SC -> layer -> implemented assets -> command)
 - execution logs (E2E/API/Integration)
+- work orders + implementer outputs + reviewer notes
 
 ### Required sections
 
@@ -122,6 +194,7 @@ Evidence must include:
 - Decisions made (with rationale)
 - Work performed (what changed, where)
 - Commands executed + key outputs
+- Test volume estimate
 - Gaps / Open risks (must be explicit; "none" is acceptable if justified)
 - Final status (PASS/FAIL) + who confirmed
 
@@ -140,15 +213,19 @@ Evidence must include:
 
 ## Commands executed + key outputs
 
+## Test volume estimate
+
 ## Coverage ledger summary
 
-- missing:
-- exceptions:
+- implemented:
+- blocked/skipped:
 
 ## Acceptance coverage ledger
 
 ## Execution logs
 
+## Work orders + reviewer notes
+
 ## Gaps / Open risks
 
 ## Final status (PASS/FAIL) + who confirmed
@@ -220,19 +297,32 @@ Simulate roles by running the same sequence yourself:
 
 - Write a short “role output” section per role, then consolidate into the final deliverable(s).
 
+## ATDD Work Orders (mandatory)
+
+- Test Volume Estimator: compute floors and K with evidence.
+- ATDD E2E Implementer: implement all `layer=e2e` ledger rows.
+- ATDD API Implementer: implement all `layer=api` ledger rows.
+- ATDD Integration Implementer: implement all `layer=integration` ledger rows.
+- Reviewer (non-edit): validate floors, ledger 100%, traceability status, and gate results.
+- Runtime Gatekeeper: run ATDD suites and capture logs.
+
 ## Completion Separation (mandatory)
 
 - Implementation (TestEngineer/Frontend/Backend) and completion approval (CodeReviewer) must be separate.
 - QAEngineer must confirm coverage and missing items before completion approval.
+- Reviewer must be non-edit (return-only; no direct file edits).
 
 ## Stage Gates (Do not skip)
 
-P0: Scope & plan confirmed (Orchestrator)  
-P1: Implementation done (Engineers)  
-P2: QA coverage/traceability review done (QA)  
-P3: Runtime evidence captured (Runtime Gatekeeper / DevOps)  
-P4: Repo quality gates PASS (DevOps)  
-P5: Completion confirmed (Reviewer)
+P0: Plan & Ledger created (Orchestrator)  
+P1: Layer assignment validated (Reviewer)  
+P2: E2E implemented (E2E Implementer)  
+P3: API implemented (API Implementer)  
+P4: Integration implemented (Integration Implementer)  
+P5: Coverage 100% verified (QA/Reviewer)  
+P6: Runtime evidence captured (Runtime Gatekeeper)  
+P7: Repo quality gates PASS (DevOps)  
+P8: Completion confirmed (Reviewer)
 
 ## Context Refresh (mandatory for long tasks)
 
@@ -441,15 +531,17 @@ Provide:
 
 **Before declaring tests complete, you MUST verify:**
 
-1. ATDD Coverage Ledger shows `missing=0` for E2E/API/Integration (exceptions documented).
+1. ATDD Coverage Ledger is 100% implemented (blocked/skipped require DR + approval).
+
+2. Test Volume floors are met (E2E/API/Integration).
 
-2. Run QFAI validation:
+3. Run QFAI validation (ATDD phase):
 
    ```bash
-   qfai validate --fail-on error
+   qfai validate --phase atdd --fail-on error
    ```
 
-3. Run repository standard gates (discover from package.json/CI/docs):
+4. Run repository standard gates (discover from package.json/CI/docs):
    - format check
    - lint
    - typecheck
@@ -458,7 +550,7 @@ Provide:
 
    Record the exact commands and results.
 
-4. All gates must PASS.
+5. All gates must PASS.
 
 If you cannot run these commands (environment limitation):