qfai 1.4.25 → 1.4.27

package/README.md

@@ -39,6 +39,16 @@ npx qfai report
 - `npx qfai doctor`
   - Diagnoses configuration discovery, path resolution, glob scanning, and `validate.json` inputs before running validate/report; use `--fail-on` to enforce failures in CI.
 
+## ATDD annotation hard gate (v1.4.27)
+
+`qfai validate` enforces spec-to-test traceability with directory-based rules.
+
+- `tests/e2e/**`: annotate all covered user stories with `QFAI:SPEC-XXXX:US-YYYY`.
+- `tests/integration/**`: annotate all covered test cases with `QFAI:SPEC-XXXX:TC-YYYY`.
+- `tests/api/**`: annotate all covered API contracts with `QFAI:CON-API-XXXX`.
+- `tests/api/**` and `tests/e2e/**` must not use `TC` annotations.
+- `AC` annotations are not required in code; AC coverage is treated as indirect through full `TC` coverage.
+
 ## Operating model (skills-driven workflow)
 
 QFAI assumes you operate the project primarily via prepared custom skills.
@@ -210,7 +220,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.4.25)
+## Minimal tutorial (v1.4.27)
 
 1. `npx qfai init`
 2. Run `/qfai-discuss` to structure scope and open questions.
@@ -237,7 +247,7 @@ Release gate behavior:
 
 ## Continuous integration
 
-QFAI v1.4.25 generates integration wrappers under `.agents/**`, `.claude/**`,
+QFAI v1.4.27 generates integration wrappers under `.agents/**`, `.claude/**`,
 `.github/**`, and `.codex/**`.
 It does not generate GitHub Actions workflows.
 Configure CI in your own platform and run:

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

@@ -29,7 +29,7 @@ You MUST enforce the following:
 - **Plan is binding, but not absolute.**
   - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
 - **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - Reject when validation evidence is missing/failing (`qfai validate --fail-on error`) or required US/TC/CON coverage obligations are unmet in test-layer policy.
 
 ## Deliverables (MANDATORY)
 

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

@@ -2,45 +2,47 @@
 
 ## Mission
 
-- Implement all `layer=api` entries in the ATDD Coverage Ledger.
+- Implement API tests so every declared `CON-API-*` is covered at least once in `tests/api/**`.
+- Keep API layer focused on contract/auth/error obligations.
 
 ## 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-\*/09_delta.md (Decision Records; check rejected)
 - .qfai/contracts/api/\*\*
-- ATDD Coverage Ledger
+- .qfai/specs/spec-\*/11_Contracts.md (if present)
 - Existing API test stack (if any)
+- Current validation report and evidence
 
 ## Deliverables (MANDATORY)
 
 - Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
 - API test files (reuse existing stack)
-- Endpoint -> test mapping (ledger updates)
+- CON-API -> test file mapping list
 - 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
+- `CON-API-*` set cannot be derived from contracts
+- API test stack is missing and no approval exists to add one
+- Validation reports unresolved errors
 - 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
+- [ ] All required `CON-API-*` are covered in `tests/api/**`
+- [ ] `qfai validate --fail-on error` evidence is recorded
 
 ## Output format (structured)
 
 - Decision Records (DR-IDs) / rejected check
 - Implemented files list
-- Mapping summary (endpoint -> test)
+- Mapping summary (CON-API -> test)
 - Execution log summary
 - Evidence summary
 - Open Questions / Risks

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

@@ -2,44 +2,46 @@
 
 ## Mission
 
-- Implement all `layer=e2e` entries in the ATDD Coverage Ledger.
+- Implement E2E tests so every required `US-*` is covered at least once.
+- Keep E2E focused on user journeys; contract guarantees belong to API tests.
 
 ## 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
+- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/02_User-stories.md (or project-equivalent user story file)
 - Existing E2E framework/config (if any)
+- Current validation report and evidence
 
 ## 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)
+- E2E test files (reuse existing stack)
+- US -> test file mapping list
 - 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
+- `US-*` list cannot be derived from specs
+- E2E framework is missing and no approval exists to add one
+- Validation reports unresolved errors
 - 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
+- [ ] All required `US-*` are covered in `tests/e2e/**`
+- [ ] `qfai validate --fail-on error` evidence is recorded
 
 ## Output format (structured)
 
 - Decision Records (DR-IDs) / rejected check
 - Implemented files list
-- Mapping summary (SC -> test)
+- Mapping summary (US -> test)
 - Execution log summary
 - Evidence summary
 - Open Questions / Risks

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

@@ -2,45 +2,46 @@
 
 ## Mission
 
-- Implement all `layer=integration` entries in the ATDD Coverage Ledger.
+- Implement integration tests so every required `TC-*` is covered at least once in `tests/integration/**`.
+- Keep integration layer focused on service boundary behavior and infra interactions.
 
 ## 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)
+- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/06_Test-Cases.md
+- Existing integration test stack (if any)
+- Current validation report and evidence
 
 ## 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)
+- Integration test files (reuse existing stack)
+- TC -> test file mapping list
 - 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
+- `TC-*` list cannot be derived from spec test cases
+- Integration test stack is missing and no approval exists to add one
+- Validation reports unresolved errors
 - 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
+- [ ] All required `TC-*` are covered in `tests/integration/**`
+- [ ] `qfai validate --fail-on error` evidence is recorded
 
 ## Output format (structured)
 
 - Decision Records (DR-IDs) / rejected check
 - Implemented files list
-- Mapping summary (CASE/EP -> test)
+- Mapping summary (TC -> test)
 - Execution log summary
 - Evidence summary
 - Open Questions / Risks

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

@@ -30,7 +30,7 @@ You MUST enforce the following:
 - **Plan is binding, but not absolute.**
   - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
 - **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - Reject when validation evidence is missing/failing (`qfai validate --fail-on error`) or required US/TC/CON coverage obligations are unmet in test-layer policy.
 
 ## Deliverables (MANDATORY)
 

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

@@ -30,7 +30,7 @@ You MUST enforce the following:
 - **Plan is binding, but not absolute.**
   - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
 - **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - Reject when validation evidence is missing/failing (`qfai validate --fail-on error`) or required US/TC/CON coverage obligations are unmet in test-layer policy.
 
 ## Deliverables (MANDATORY)
 

package/assets/init/.qfai/assistant/agents/coverage-planner.md

@@ -2,53 +2,48 @@
 
 ## Mission
 
-- Define and maintain coverage ledgers to prevent silent gaps.
-- Convert coverage findings into actionable, perspective-based EX/TC planning.
+- Define coverage obligations and operating rules for E2E/API/Integration.
+- Produce actionable checklists for implementers and reviewers.
 
 ## Inputs you must read
 
 - .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
-- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
-- .qfai/specs/spec-\*/04_Business-Rules.md
-- .qfai/specs/spec-\*/05_Examples.md
+- .qfai/assistant/steering/test-layers.md
+- .qfai/specs/spec-\*/02_User-stories.md
 - .qfai/specs/spec-\*/06_Test-Cases.md
+- .qfai/contracts/api/\*\*
 - .qfai/report/validate.log
-- .qfai/report/specs-coverage/spec-\*.md
-- Existing coverage ledgers and test files
+- Existing test files
 
 ## Deliverables (MANDATORY)
 
 - Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
-- Hard-gap list (`QFAI-COV-201/202/203/204/205/206`) with source-layer fixes
-- Density-smell list (for example `QFAI-COV-207`) with perspective-based improvement ideas
-- Scope ledger (what must be tested) with exclusions rationale
-- Coverage ledger mapped to BR/EX/TC layers
+- Coverage obligations checklist (`US` / `TC` / `CON-API`)
+- Layer assignment checklist (`tests/e2e|api|integration`)
+- Forbidden-reference checklist (API/E2E must not use TC annotations)
+- Signals summary (floors/ratios are signals, not gates)
 - Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
 ## Stop conditions (Blockers)
 
 - Rejected option would be reintroduced without RE-OPEN DR
-- Hidden exclusions or silent gaps detected
+- Source obligations are ambiguous
 - Evidence is missing or incomplete
-- BR/EX/TC mapping is ambiguous
 
 ## Sign-off checklist (Check Last)
 
 - [ ] Deliverables are complete
 - [ ] Evidence is present (gitignored)
-- [ ] No silent gaps remain
-- [ ] Handoff includes actionable next steps
+- [ ] Handoff is actionable for implementers/reviewers
+- [ ] Gate/non-gate boundary is explicit
 
 ## Output format (structured)
 
 - Decision Records (DR-IDs) / rejected check
-- Findings
-- Hard gaps (`QFAI-COV-201..206`)
-- Density smells (`QFAI-COV-207` and similar)
-- Coverage ledger
-- Perspective-based EX/TC proposal (boundary, negative, permission, state)
-- Exclusions rationale
+- Coverage obligations checklist
+- Layer assignment checklist
+- Forbidden-reference checklist
+- Signals summary
 - Evidence summary
 - Open Questions / Risks
 - Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/design-review-lead.md

@@ -30,7 +30,7 @@ You MUST enforce the following:
 - **Plan is binding, but not absolute.**
   - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
 - **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - Reject when validation evidence is missing/failing (`qfai validate --fail-on error`) or required US/TC/CON coverage obligations are unmet in test-layer policy.
 
 ## Deliverables (MANDATORY)
 

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

@@ -30,7 +30,7 @@ You MUST enforce the following:
 - **Plan is binding, but not absolute.**
   - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
 - **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - Reject when validation evidence is missing/failing (`qfai validate --fail-on error`) or required US/TC/CON coverage obligations are unmet in test-layer policy.
 
 ## Deliverables (MANDATORY)
 

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

@@ -30,7 +30,7 @@ You MUST enforce the following:
 - **Plan is binding, but not absolute.**
   - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
 - **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - Reject when validation evidence is missing/failing (`qfai validate --fail-on error`) or required US/TC/CON coverage obligations are unmet in test-layer policy.
 
 ## Deliverables (MANDATORY)
 

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

@@ -33,7 +33,7 @@ You MUST enforce the following:
 - **Plan is binding, but not absolute.**
   - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
 - **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - Reject when validation evidence is missing/failing (`qfai validate --fail-on error`) or required US/TC/CON coverage obligations are unmet in test-layer policy.
 
 ## Deliverables (MANDATORY)
 

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

@@ -29,7 +29,7 @@ You MUST enforce the following:
 - **Plan is binding, but not absolute.**
   - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
 - **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - Reject when validation evidence is missing/failing (`qfai validate --fail-on error`) or required US/TC/CON coverage obligations are unmet in test-layer policy.
 
 ## Deliverables (MANDATORY)
 

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

@@ -10,24 +10,24 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/instructions/drift-protocol.md (must enforce upstream-change approval)
 - .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md (test-layer definitions + required coverage expectations)
-- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- Coverage ledgers + evidence + gate results
+- .qfai/assistant/steering/test-layers.md (US/TC/CON obligations and forbidden references)
+- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
+- Validation evidence and gate results (`qfai validate --fail-on error`)
 
 ## Cross-cutting review: Drift Protocol (MANDATORY)
 
 You MUST enforce the following:
 
 - **No upstream artifact edits without explicit user approval.**
-  - Upstream artifacts include: discuss/require/spec/refinement outputs, `plan.md`, contracts, schema decisions, and any SSOT docs owned by earlier phases.
-  - If an upstream change was necessary, you must see a **Change Request** with:
+  - Upstream artifacts include discuss/require/spec/planning outputs, contracts, and schema decisions.
+  - If an upstream change was necessary, review a Change Request with:
     - at least 3 options + recommendation,
-    - explicit **user approval**,
-    - and evidence that the correct **owner skill** was re-run to apply the change (downstream must not patch upstream directly).
+    - explicit user approval,
+    - and evidence that the correct owner skill was re-run.
 - **Plan is binding, but not absolute.**
-  - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
-- **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - If reality diverged from plan, downstream work must STOP and escalate via Change Request.
+- **Do NOT enforce test-volume ratios as a gate.**
+  - Floors/ratios are signals only; completion gate is validation with zero errors.
 
 ## Deliverables (MANDATORY)
 
@@ -37,13 +37,13 @@ You MUST enforce the following:
 
 ## Must-reject conditions
 
-- Do NOT reject solely due to suggested test-volume floors/ratios; use them as signals only. Coverage is the gate.
+- Validation evidence is missing or failing (`qfai validate --fail-on error`)
+- Required `US`/`TC`/`CON-API` coverage obligations are unmet
+- Forbidden references remain (`tests/api/**` or `tests/e2e/**` with `QFAI:SPEC-XXXX:TC-YYYY`)
 - Upstream artifact changed without explicit user approval + recorded Change Request
-- 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)
+- Runtime gate not executed when required by prompt
 
 ## Sign-off checklist (Check Last)
 

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

@@ -2,49 +2,47 @@
 
 ## Mission
 
-- Estimate test volume as a risk signal and detect thin areas.
+- Estimate test volume as risk signals using obligations from specs/contracts.
+- Provide planning hints without turning floors/ratios into completion gates.
 
 ## Inputs you must read
 
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
-- .qfai/specs/spec-\*/04_Business-Rules.md
-- .qfai/specs/spec-\*/05_Examples.md
+- .qfai/specs/spec-\*/02_User-stories.md
 - .qfai/specs/spec-\*/06_Test-Cases.md
-- .qfai/report/specs-coverage/spec-\*.md
-- .qfai/report/validate.log
-- .qfai/contracts/\*\*
+- .qfai/contracts/api/\*\*
+- .qfai/report/validate.log (if available)
 
 ## Deliverables (MANDATORY)
 
 - Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
-- Risk-signal table (Layer / Raw count / Signal / Evidence / Notes)
-- Density-smell findings (for example multi-BR EX rows) and impact summary
-- Improvement proposals by perspective (boundary/negative/permission/state)
-- BLOCKED list when data is missing
+- Signal table (Layer / Raw count / Signal / Evidence / Notes)
+- Execution-time risk notes and prioritization hints
+- Missing-input list when counts cannot be derived
+- Explicit statement: signals are not completion gates
 - Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
 ## Stop conditions (Blockers)
 
 - Rejected option would be reintroduced without RE-OPEN DR
-- BR/EX/TC source counts cannot be derived and no fallback is available
+- US/TC/CON source counts cannot be derived and no fallback exists
 - Evidence is missing or incomplete
 
 ## Sign-off checklist (Check Last)
 
 - [ ] Deliverables are complete
 - [ ] Evidence is present (gitignored)
-- [ ] Risk signals are justified with evidence
-- [ ] BLOCKED items are explicit
+- [ ] Signals are justified with explicit evidence
+- [ ] Gate/non-gate boundary is explicit
 
 ## Output format (structured)
 
 - Decision Records (DR-IDs) / rejected check
-- Risk-signal table
-- Density-smell findings
-- Perspective-based improvement proposals
-- BLOCKED list (if any)
+- Signal table
+- Risk notes
+- Missing-input list (if any)
 - Evidence summary
 - Open Questions / Risks
 - Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/ui-ux-reviewer.md

@@ -29,7 +29,7 @@ You MUST enforce the following:
 - **Plan is binding, but not absolute.**
   - If reality diverged from plan, downstream work must STOP and escalate via Change Request → approval.
 - **Do NOT enforce test pyramid ratios as a gate.**
-  - Reject only when coverage obligations are unmet (Coverage Ledger not 100% unless approved exception) or required layers are missing without approval.
+  - Reject when validation evidence is missing/failing (`qfai validate --fail-on error`) or required US/TC/CON coverage obligations are unmet in test-layer policy.
 
 ## Deliverables (MANDATORY)
 

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

@@ -24,8 +24,8 @@ Delegate work to specialized roles to reduce blind spots and improve quality.
 - **Architect**: design, boundaries, compatibility considerations
 - **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
+- **Test Engineer**: US/TC/CON-API obligations and test scaffolding strategy
+- **ATDD Implementers**: E2E/API/Integration implementation per required coverage (`US` / `TC` / `CON-API`)
 - **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

package/assets/init/.qfai/assistant/instructions/drift-protocol.md

@@ -8,14 +8,17 @@ This file defines mandatory change control for all downstream execution phases.
 
 Upstream artifacts include, at minimum:
 
-- `spec.md`, `delta.md`, `scenario.feature`, `case-catalogue.md`, `traceability-matrix.md`, `plan.md`
+- `01_Spec.md`, `02_User-stories.md`, `03_Acceptance-Criteria.md`, `04_Business-Rules.md`, `05_Examples.md`, `06_Test-Cases.md`, `07_Decisions.md`, `08_Open-questions.md`, `09_delta.md`
+- `_shared/*` layered artifacts and `11_Contracts.md` (or project-equivalent contract index)
+- `10_Plan.md` and other owner-phase planning outputs
+- Legacy spec-pack SSOT files when present: `spec.md`, `delta.md`, `plan.md`, `traceability-matrix.md`, `scenario.feature`, `case-catalogue.md`, and numbered pack files (for example `01_Spec.md`..`18_delta.md`)
 - contracts and schema decisions owned by earlier phases
 - outputs of discuss/require/refinement/planning stages
 
 ## Allowed exceptions (minimal whitelist)
 
 - `.qfai/evidence/**` append/update
-- `traceability-matrix.md` progress status updates when the project workflow explicitly allows downstream updates
+- progress status updates only when the project workflow explicitly allows downstream updates
 
 Any exception beyond this list requires explicit user approval.
 

package/assets/init/.qfai/assistant/instructions/migrations/v1.4.27-atdd-alignment.md

@@ -0,0 +1,35 @@
+# ATDD Alignment Migration Memo
+
+## Purpose
+
+- Migrate ATDD operation from scenario/ledger-centric flow to obligations-driven flow.
+- Keep legacy artifacts compatible while removing them from mandatory completion gates.
+
+## Rule Changes
+
+- Old default:
+  - `scenario.feature` and coverage ledger were treated as mandatory completion inputs.
+- New default:
+  - Required obligations are IDs in specs/contracts:
+    - `US-*` -> `tests/e2e/**`
+    - `TC-*` -> `tests/integration/**`
+    - `CON-API-*` -> `tests/api/**`
+  - Completion gate is validation pass with no errors.
+  - Floors/ratios are signals only.
+
+## Fast Migration Steps
+
+1. Run validation and collect missing obligations from the report.
+2. Add required annotations to test files (`US` / `TC` / `CON-API`).
+3. Move tests into canonical directories:
+   - `tests/e2e`
+   - `tests/api`
+   - `tests/integration`
+4. Remove forbidden references (`TC` annotations in API/E2E tests).
+5. Re-run:
+   - `qfai validate --fail-on error`
+
+## Legacy Compatibility
+
+- `scenario.feature` and old ledger files may remain in the repository.
+- They are optional evidence only and must not be used as completion gates.

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

@@ -40,7 +40,7 @@ Do not proceed without a declared Change Type.
 
 - Read and enforce `.qfai/assistant/steering/test-layers.md`.
 - Treat floors/ratios as signals, not completion gates.
-- Coverage Ledger completeness is the completion gate (or approved exception).
+- Completion gate is `qfai validate --fail-on error` with evidence.
 
 ---
 
@@ -52,7 +52,7 @@ Do not proceed without a declared Change Type.
 3. Specification refinement (SDD): preflight + `_shared` / `spec-XXXX/01..06`
 4. Specification planning (SDD): `spec-XXXX/10_Plan.md` (How-only)
 5. Prototyping (optional): contract-aligned implementation skeleton
-6. Scenario tests (ATDD): runnable scenario tests derived from `scenario.feature`
+6. Acceptance tests (ATDD): runnable E2E/API/Integration tests derived from specs/contracts obligations (`US` / `TC` / `CON-API`)
 7. TDD: red/green/refactor loop enforcing spec + tests
 8. Verify: run quality gates and provide evidence