qfai 1.2.13 → 1.3.0

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

@@ -58,6 +58,13 @@ When unsure, read inputs in this order:
 - You MUST stop and escalate if scope remains ambiguous or required inputs are missing.
 - Completion must be approved by a reviewer who did not lead the discussion.
 
+## Sub-agent policy (mandatory)
+
+- If subagents are supported, Orchestrator MUST delegate: Researcher, Facilitator/Interviewer, Reviewer (non-edit).
+- Orchestrator must not lead and approve the same discussion.
+- Evidence must include work orders and reviewer notes.
+- If subagents are not supported, simulate role separation with explicit role sections.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:
@@ -71,6 +78,19 @@ Before declaring completion, you MUST:
 
 Turn a vague idea into explicit, testable requirements and decisions that downstream prompts can implement without guesswork.
 
+## Non-goals
+
+- Writing final requirements/specs (use `/qfai-require` / `/qfai-spec`).
+- Implementation work.
+
+## Mandatory Outputs
+
+- Requirements Seed
+- Decision Table (with rejected/deferred options)
+- Discuss record: `.qfai/discussions/discuss-XXXX.md`
+- Evidence file: `.qfai/evidence/discuss-<discuss-id>.md`
+- Reviewer notes (PASS or concrete rework list)
+
 ## Success Criteria (Definition of Done)
 
 - A “Requirements Seed” exists: goals, non-goals, constraints, acceptance criteria (high level), and open questions.
@@ -92,6 +112,11 @@ Turn a vague idea into explicit, testable requirements and decisions that downst
 - "We discussed" without decision and rationale.
 - No explicit scope boundary.
 
+## Failure handling (mandatory)
+
+- If blocked/unknown, stop and record a DR in delta.md (do not skip).
+- If required coverage remains undecided, do not declare completion.
+
 ## Required Coverage (MUST address)
 
 The discussion MUST cover the following topics before completion:

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

@@ -64,6 +64,13 @@ When unsure, read inputs in this order:
 - Implementation must align with existing project conventions; do NOT introduce new frameworks.
 - Completion must be approved by a reviewer who did not implement the code.
 
+## Sub-agent policy (mandatory)
+
+- If subagents are supported, Orchestrator MUST delegate: implementation (Frontend/Backend/DB), Runtime Gatekeeper, Reviewer (non-edit).
+- Orchestrator must not implement directly when delegation is available.
+- Evidence must include work orders and reviewer notes.
+- If subagents are not supported, simulate role separation with explicit role sections.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:
@@ -73,6 +80,22 @@ Before declaring completion, you MUST:
 - OQ / placeholder scan: scan all generated artifacts (including evidence) for placeholders such as "TBD", "TODO", "TBA", "TBC", "XXX", "???", "OQ", "OPEN QUESTION", "UNDEFINED", "PLACEHOLDER", and localized equivalents in the user's language. Resolve or explicitly defer; do not leave silent placeholders.
 - Smoke check (if applicable): when the prompt produces runnable code/tests/configs, execute the smallest command that proves basic run/start/operate and record evidence. If not applicable, state "not applicable" with a short rationale.
 
+## Goal
+
+Build a minimal runnable vertical slice from contracts so the app boots and users can perform at least one primary interaction.
+
+## Non-goals
+
+- Acceptance tests (use `/qfai-atdd`).
+- Unit/component tests (use TDD phases).
+
+## Mandatory Outputs
+
+- Runnable skeleton implementation aligned with contracts
+- Runtime Interaction Gate evidence (boot + access + interaction)
+- Evidence file: `.qfai/evidence/prototyping-<spec-id>.md`
+- Reviewer notes (PASS or concrete rework list)
+
 ## Inputs (read first)
 
 - `.qfai/contracts/ui/*.yaml` (routes/screens/elements/actions)
@@ -145,12 +168,13 @@ Implement the following **contract-satisfying skeleton**, aiming for the smalles
 5. Implement DB skeleton and connect (or provide clear temporary store).
 6. Run the dev server and perform a manual “happy path” click-through.
 
-## Sub-agent assignments (recommended)
+## Sub-agent assignments (required when supported)
 
 - UI Skeleton Builder: FrontendEngineer (apply UI layout guardrails).
 - API/DB Skeleton Builder: BackendEngineer + DBEngineer.
 - Runtime Smoke Checker: RuntimeGatekeeper (boot/access/interaction evidence).
 - UI/UX Reviewer: UIUXReviewer (layout sanity check).
+- Reviewer: CodeReviewer (non-edit; PASS/FAIL only).
 
 ## Runtime Interaction Gate (mandatory)
 
@@ -182,6 +206,11 @@ You may declare completion ONLY if:
   - includes “Format Self-Check”,
   - includes a short manual verification log.
 
+## Failure handling (mandatory)
+
+- If blocked/unknown, stop and record a DR in delta.md (do not skip).
+- If Runtime Interaction Gate fails, fix and re-run before declaring completion.
+
 ## Reviewer checklist (for CodeReviewer role)
 
 - No test automation was added here.

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

@@ -68,6 +68,13 @@ When unsure, read inputs in this order:
 - You MUST stop and escalate if requirements are ambiguous or acceptance signals are missing.
 - Completion must be approved by a reviewer who did not author the requirements.
 
+## Sub-agent policy (mandatory)
+
+- If subagents are supported, Orchestrator MUST delegate: OQ Harvester, OQ Reviewer, Requirements Analyst, Reviewer (non-edit).
+- Orchestrator must not author and approve the same artifact.
+- Evidence must include work orders and reviewer notes.
+- If subagents are not supported, simulate role separation with explicit role sections.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:
@@ -81,6 +88,18 @@ Before declaring completion, you MUST:
 
 Turn the Requirements Seed into a reviewable, testable requirements artifact under `.qfai/require/`.
 
+## Non-goals
+
+- Spec/contract authoring (use `/qfai-spec`).
+- Implementation work.
+
+## Mandatory Outputs
+
+- `.qfai/require/require.md`
+- `.qfai/require/open-questions.md` (OQ ledger)
+- Evidence file: `.qfai/evidence/require-<work-id>.md`
+- Reviewer notes (PASS or concrete rework list)
+
 ## Success Criteria (Definition of Done)
 
 - A requirements document (`require.md`) exists in the requirements directory and is readable by a newcomer.
@@ -104,6 +123,11 @@ Turn the Requirements Seed into a reviewable, testable requirements artifact und
 - Missing acceptance signal for any requirement.
 - Any Open item remains in open-questions.md.
 
+## Failure handling (mandatory)
+
+- If blocked/unknown, stop and record a DR in delta.md (do not skip).
+- If Open items remain, do not declare completion.
+
 ## Evidence (MANDATORY)
 
 Create and update: `.qfai/evidence/require-<work-id>.md`

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

@@ -51,6 +51,18 @@ When unsure, read inputs in this order:
 - P3: `.qfai/specs/<spec-id>/delta.md` (Decision Records; if no spec yet, state "not applicable")
 - P4: other artifacts (spec.md, scenario.feature, contracts, evidence)
 
+## Change Type (Mandatory)
+
+Before editing `delta.md`, declare the Change Type 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`
+
 ## Delta Rejected Guard (Mandatory)
 
 - Do NOT reintroduce options marked as rejected in delta.md.
@@ -74,6 +86,13 @@ When unsure, read inputs in this order:
 - You MUST stop and escalate if IDs, contracts, or scope are inconsistent.
 - Completion must be approved by a reviewer who did not author the spec pack.
 
+## Sub-agent policy (mandatory)
+
+- If subagents are supported, Orchestrator MUST delegate: OQ Harvester, OQ Reviewer, Option Explorer, Option Reviewer, Contract Designer, Reviewer (non-edit).
+- Orchestrator must not author and approve the same artifact.
+- Evidence must include work orders and reviewer notes.
+- If subagents are not supported, simulate role separation with explicit role sections.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:
@@ -89,6 +108,23 @@ Create/update an atomic spec pack that is readable and mechanically verifiable.
 
 This prompt is intentionally strict. If you cannot satisfy the strict rules, you MUST split the work into additional spec packs.
 
+## Non-goals
+
+- Implementation work.
+- Skipping OQ/decision logging.
+
+## Mandatory Outputs
+
+- `.qfai/specs/spec-XXXX/spec.md`
+- `.qfai/specs/spec-XXXX/delta.md`
+- `.qfai/specs/spec-XXXX/scenario.feature`
+- `.qfai/specs/spec-XXXX/case-catalogue.md`
+- `.qfai/specs/spec-XXXX/traceability-matrix.md` (status planned/implemented)
+- Updated contracts under `.qfai/contracts/**` (if needed)
+- `.qfai/require/open-questions.md` (OQ ledger)
+- Evidence file: `.qfai/evidence/spec-<spec-id>.md`
+- Reviewer notes (PASS or concrete rework list)
+
 ## Hard Constraints (MUST)
 
 ### Atomicity / Granularity (quantitative)
@@ -167,6 +203,11 @@ The following order is mandatory and must not be parallelized or rearranged:
 - Any Open item remains in open-questions.md.
 - Decision Records are missing rejected items without explicit trivial-change justification.
 
+## Failure handling (mandatory)
+
+- If blocked/unknown, stop and record a DR in delta.md (do not skip).
+- If Open items remain, do not declare completion.
+
 ## Evidence (MANDATORY)
 
 Create and update: `.qfai/evidence/spec-<spec-id>.md`

package/assets/init/.qfai/assistant/prompts/qfai-tdd-green.md

@@ -38,6 +38,18 @@ When unsure, read inputs in this order:
 - P3: `.qfai/specs/<spec-id>/delta.md` (Decision Records; if no spec yet, state "not applicable")
 - P4: other artifacts (spec.md, scenario.feature, contracts, evidence)
 
+## Change Type (Mandatory)
+
+Before updating `delta.md`, declare the Change Type 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`
+
 ## Delta Rejected Guard (Mandatory)
 
 - Do NOT reintroduce options marked as rejected in delta.md.
@@ -56,6 +68,13 @@ When unsure, read inputs in this order:
 - You MUST stop and escalate if runtime evidence or quality gates are missing.
 - Completion must be approved by a reviewer who did not implement the code.
 
+## Sub-agent policy (mandatory)
+
+- If subagents are supported, Orchestrator MUST delegate: implementation (Frontend/Backend), QA, UI/UX review, Runtime Gatekeeper, Reviewer (non-edit).
+- Orchestrator must not implement directly when delegation is available.
+- Evidence must include work orders and reviewer notes.
+- If subagents are not supported, simulate role separation with explicit role sections.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:
@@ -69,6 +88,18 @@ Before declaring completion, you MUST:
 
 Orchestrate production implementation according to spec + contracts + scenario so RED tests pass and the green quality gate is reached.
 
+## Non-goals
+
+- Writing new tests (use `/qfai-tdd-red` or `/qfai-atdd`).
+- Re-implementing rejected options without a RE-OPEN DR.
+
+## Mandatory Outputs
+
+- Implementation changes that make RED tests pass
+- Runtime Interaction Gate evidence
+- Evidence file: `.qfai/evidence/tdd-green-<spec-id>.md`
+- Reviewer notes (PASS or concrete rework list)
+
 ## Guardrails
 
 - You are the orchestrator. Do not implement directly; delegate to engineer roles.
@@ -89,7 +120,7 @@ Orchestrate production implementation according to spec + contracts + scenario s
 
 - Implementation matches the spec and contracts.
 - TDD tests pass (and ATDD tests pass when applicable).
-- Unit/Component Coverage Ledger shows `missing=0` (exceptions documented).
+- Unit/Component Coverage Ledger shows 100% implemented (blocked/skipped require DR + approval).
 - Repo quality gates pass (lint/type/build/pack as applicable).
 - Verification evidence is recorded (commands + results).
 - Program is runnable; runtime evidence is recorded and meets project-type expectations.
@@ -108,10 +139,15 @@ Orchestrate production implementation according to spec + contracts + scenario s
 - "Tests passed" without runtime evidence.
 - Completion without reviewer sign-off.
 
+## Failure handling (mandatory)
+
+- If blocked/unknown, stop and record a DR in delta.md (do not skip).
+- If Runtime Interaction Gate fails, fix and re-run before declaring completion.
+
 ## Coverage Ledger continuity
 
 - Review the Unit/Component Coverage Ledger from `/qfai-tdd-red`.
-- Do not declare completion until `missing=0` and exceptions are documented.
+- Do not declare completion until Coverage Ledger is 100% implemented (blocked/skipped require DR + approval).
 
 ## Non‑Negotiable Principles (QFAI Articles)
 
@@ -193,15 +229,15 @@ Simulate roles by running the same sequence yourself:
 
 You must not advance to the next phase until the current gate is PASS.
 
-| Phase                | Owner                            | Gate output                                               |
-| -------------------- | -------------------------------- | --------------------------------------------------------- |
-| P0: Scope Derivation | Orchestrator                     | Implementation Scope Table completed                      |
-| P1: Implementation   | FrontendEngineer/BackendEngineer | Contract-to-implementation mapping with TODOs resolved    |
-| P2: QA Review        | QAEngineer                       | Coverage/gap check (missing=0 or explicit exceptions)     |
-| P2.5: UI/UX Review   | UIUXReviewer                     | Layout sanity check (guardrails satisfied)                |
-| P3: Runtime Evidence | RuntimeGatekeeper                | Boot + contract path run + UI interaction (if applicable) |
-| P4: Quality Gates    | DevOpsCIEngineer                 | Repo-defined gates PASS                                   |
-| P5: Completion       | CodeReviewer                     | DoD PASS declared by non-implementer                      |
+| Phase                | Owner                            | Gate output                                                                  |
+| -------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
+| P0: Scope Derivation | Orchestrator                     | Implementation Scope Table completed                                         |
+| P1: Implementation   | FrontendEngineer/BackendEngineer | Contract-to-implementation mapping with TODOs resolved                       |
+| P2: QA Review        | QAEngineer                       | Coverage/gap check (100% implemented; blocked/skipped require DR + approval) |
+| P2.5: UI/UX Review   | UIUXReviewer                     | Layout sanity check (guardrails satisfied)                                   |
+| P3: Runtime Evidence | RuntimeGatekeeper                | Boot + contract path run + UI interaction (if applicable)                    |
+| P4: Quality Gates    | DevOpsCIEngineer                 | Repo-defined gates PASS                                                      |
+| P5: Completion       | CodeReviewer                     | DoD PASS declared by non-implementer                                         |
 
 Optional (strongly recommended): run a Devil's Advocate check right before completion to look for hidden gaps.
 
@@ -507,7 +543,7 @@ Iterate until all gates pass, prioritizing:
 
 **Before declaring implementation complete, you MUST verify:**
 
-1. Unit/Component Coverage Ledger shows `missing=0` (exceptions documented).
+1. Unit/Component Coverage Ledger shows 100% implemented (blocked/skipped require DR + approval).
 
 2. Runtime evidence commands executed and outcomes recorded.
 

package/assets/init/.qfai/assistant/prompts/qfai-tdd-red.md

@@ -38,6 +38,18 @@ When unsure, read inputs in this order:
 - P3: `.qfai/specs/<spec-id>/delta.md` (Decision Records; if no spec yet, state "not applicable")
 - P4: other artifacts (spec.md, scenario.feature, contracts, evidence)
 
+## Change Type (Mandatory)
+
+Before updating `delta.md`, declare the Change Type 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`
+
 ## Delta Rejected Guard (Mandatory)
 
 - Do NOT reintroduce options marked as rejected in delta.md.
@@ -53,6 +65,13 @@ When unsure, read inputs in this order:
 - You MUST stop and escalate if RED is not reproducible.
 - 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 Engineer, Unit Test Scope Enforcer, QA, Reviewer (non-edit).
+- Orchestrator must not implement tests directly when delegation is available.
+- Evidence must include work orders and reviewer notes.
+- If subagents are not supported, simulate role separation with explicit role sections.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:
@@ -71,6 +90,18 @@ Implement fast tests (unit/component) that enforce the spec and provide reproduc
 - In scope: Unit and Component tests.
 - Out of scope: E2E/API/Integration (use `/qfai-atdd`).
 
+## Non-goals
+
+- Production code changes beyond testability shims.
+- Acceptance/E2E tests.
+
+## Mandatory Outputs
+
+- Unit/Component Coverage Ledger
+- Unit/Component test implementations (RED)
+- Evidence file: `.qfai/evidence/tdd-red-<spec-id>.md`
+- Reviewer notes (non-edit)
+
 ## Scope Guardrails (tests-only)
 
 ### Mandatory constraints (tests only)
@@ -119,7 +150,7 @@ If tests cannot proceed because implementation is missing:
 ## Success Criteria (Definition of Done)
 
 - Unit/Component tests exist, are deterministic, and runnable in CI.
-- Coverage Ledger for Unit/Component shows `missing=0` (exceptions documented).
+- Coverage Ledger for Unit/Component shows 100% implemented (blocked/skipped require DR + approval).
 - Completion is based on executing the unit/component test suite and recording evidence.
 - Tests cover core logic and key edge cases derived from spec/scenario.
 - Tests fail meaningfully and the failing state is observed (RED evidence).
@@ -139,6 +170,11 @@ If tests cannot proceed because implementation is missing:
 - Tests added without mapping to requirements/contracts.
 - No reproducible RED.
 
+## Failure handling (mandatory)
+
+- If blocked/unknown, stop and record a DR in delta.md (do not skip).
+- If RED cannot be reproduced, fix the test setup or stop and report.
+
 ## TDD Coverage Ledger (Unit/Component)
 
 Create a ledger that lists every Scenario (SC) in Unit/Component scope:
@@ -146,7 +182,7 @@ Create a ledger that lists every Scenario (SC) in Unit/Component scope:
 - Inputs: `.qfai/specs/**/scenario.feature`
 - Scope: `@layer-unit`, `@layer-component`
 - Columns: SC ID / layer / target unit or component / test file / status (`done|missing|exception`)
-- Rule: **`missing=0` is required before completion.**
+- Rule: **Coverage Ledger must be 100% implemented (blocked/skipped require DR + approval) before completion.**
 
 If a test is not automatable right now, record it as `exception` with a clear reason and a follow-up plan.
 

package/assets/init/.qfai/assistant/prompts/qfai-tdd-refactor.md

@@ -11,7 +11,7 @@ title: QFAI TDD Refactor (Improve structure safely)
 description: "Refactor code without behavior change after tests are green."
 argument-hint: "<spec-id> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [ArchitectReviewer, BackendEngineer, FrontendEngineer, QAEngineer, CodeReviewer]
+roles: [ArchitectReviewer, BackendEngineer, FrontendEngineer, QAEngineer, RuntimeGatekeeper, CodeReviewer]
 mode: refactor
 
 ---
@@ -38,6 +38,18 @@ When unsure, read inputs in this order:
 - P3: `.qfai/specs/<spec-id>/delta.md` (Decision Records; if no spec yet, state "not applicable")
 - P4: other artifacts (spec.md, scenario.feature, contracts, evidence)
 
+## Change Type (Mandatory)
+
+Before updating `delta.md`, declare the Change Type 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`
+
 ## Delta Rejected Guard (Mandatory)
 
 - Do NOT reintroduce options marked as rejected in delta.md.
@@ -50,10 +62,18 @@ When unsure, read inputs in this order:
 - You MUST produce the required evidence file: `.qfai/evidence/tdd-refactor-<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.
+- You MUST re-run the Runtime Gate (when applicable) and capture evidence.
 - You MUST run the mandatory checks listed below and record outcomes.
 - You MUST stop and escalate if refactor risks behavior changes.
 - Completion must be approved by a reviewer who did not implement the refactor.
 
+## Sub-agent policy (mandatory)
+
+- If subagents are supported, Orchestrator MUST delegate: implementation (Engineers), QA, Runtime Gatekeeper, Reviewer (non-edit).
+- Orchestrator must not implement directly when delegation is available.
+- Evidence must include work orders and reviewer notes.
+- If subagents are not supported, simulate role separation with explicit role sections.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:
@@ -67,6 +87,18 @@ Before declaring completion, you MUST:
 
 Refactor the codebase without behavior change after tests are green, preserving spec and contract intent.
 
+## Non-goals
+
+- Adding new features or changing external behavior.
+- Writing new tests (use TDD phases).
+
+## Mandatory Outputs
+
+- Refactor diffs with behavior preserved
+- Runtime Gate evidence (if applicable)
+- Evidence file: `.qfai/evidence/tdd-refactor-<spec-id>.md`
+- Reviewer notes (PASS or concrete rework list)
+
 ## Guardrails
 
 - Do not invent DB/API/infra. If missing, stop and raise Open Questions.
@@ -78,7 +110,7 @@ Refactor the codebase without behavior change after tests are green, preserving
 
 - Behavior remains unchanged and matches the spec and contracts.
 - TDD/ATDD tests remain green after refactor.
-- Unit/Component Coverage Ledger remains `missing=0` (exceptions documented).
+- Unit/Component Coverage Ledger remains 100% implemented (blocked/skipped require DR + approval).
 - Repo quality gates pass (lint/type/build/pack as applicable).
 - Verification evidence is recorded (commands + results).
 - Evidence file exists: `.qfai/evidence/tdd-refactor-<spec-id>.md`.
@@ -94,6 +126,11 @@ Refactor the codebase without behavior change after tests are green, preserving
 - Behavior changes without spec update.
 - Tests not run after refactor.
 
+## Failure handling (mandatory)
+
+- If blocked/unknown, stop and record a DR in delta.md (do not skip).
+- If Runtime Gate fails, fix and re-run before declaring completion.
+
 ## Coverage Ledger continuity
 
 - Review the Unit/Component Coverage Ledger from `/qfai-tdd-red`.
@@ -431,7 +468,7 @@ Iterate until all gates pass, prioritizing:
 
 **Before declaring implementation complete, you MUST verify:**
 
-1. Unit/Component Coverage Ledger shows `missing=0` (exceptions documented).
+1. Unit/Component Coverage Ledger shows 100% implemented (blocked/skipped require DR + approval).
 
 2. Runtime evidence commands executed and outcomes recorded.
 

package/assets/init/.qfai/evidence/README.md

@@ -20,7 +20,8 @@ Recommended approach:
 
 ## Naming
 
-- `.qfai/evidence/<prompt>-<run-id>.md`
+- Summary file: `.qfai/evidence/<prompt>-<run-id>.md`
+- Optional artifacts: `.qfai/evidence/<prompt>/<YYYY-MM-DD>/<run-id>/...`
 - `<run-id>`: prefer `spec-XXXX` when applicable.
 
 ## Minimal content template

package/assets/init/.qfai/specs/README.md

@@ -41,7 +41,7 @@ specs/
   - `CASE-XXXX-YYYY` (test case)
   - `SC-XXXX-YYYY` (scenario tag in feature file)
 - Traceability must be consistent:
-  - `traceability-matrix.md` maps **REQ → BR → AC → CASE → SC → Contracts**.
+- `traceability-matrix.md` maps **REQ → BR → AC → CASE → SC → Status → Contracts**.
 - `scenario.feature` may contain multiple Scenarios/Outlines (standard Gherkin style).
 - Layer/size tags:
   - Each Scenario SHOULD declare `@layer:<...>` and `@size:<...>` once the project opts in.
@@ -185,6 +185,9 @@ specs/
 
 - date: <YYYY-MM-DD>
 - author: <AI/role or human>
+- change_type_primary: Initial | Behavior | Structural | Ops
+- change_type_tags: <space-separated tags or empty>
+  - example: @api @db
 - scope: <files/areas>
 - change: <what changed>
 - reason: <why it changed>
@@ -204,6 +207,8 @@ specs/
 - selected: <option>
 - rejected:
   - <option> — <reason>
+    - do_not: <what must not be reintroduced>
+    - temptation: <why it may be tempting to reintroduce>
 - impact: <downstream impact>
 - followups: <todos>
 - related_contracts: <QFAI-CONTRACT-REF or IDs>
@@ -336,11 +341,18 @@ Explain why the case set is “enough”:
 | Created | <YYYY-MM-DD> |
 | Updated | <YYYY-MM-DD> |
 
-## Full chain (REQ → BR → AC → CASE → SC → Contracts)
+## Full chain (REQ → BR → AC → CASE → SC → Status → Contracts)
 
-| REQ           | BR             | AC             | CASE             | SC             | Contracts                  |
-| ------------- | -------------- | -------------- | ---------------- | -------------- | -------------------------- |
-| REQ-FUNC-0010 | BR-<XXXX>-0001 | AC-<XXXX>-0001 | CASE-<XXXX>-0001 | SC-<XXXX>-0001 | UI-0001, API-0002, DB-0003 |
+| REQ           | BR             | AC             | CASE             | SC             | Status      | Contracts                  |
+| ------------- | -------------- | -------------- | ---------------- | -------------- | ----------- | -------------------------- |
+| REQ-FUNC-0010 | BR-<XXXX>-0001 | AC-<XXXX>-0001 | CASE-<XXXX>-0001 | SC-<XXXX>-0001 | implemented | UI-0001, API-0002, DB-0003 |
+
+Status values:
+
+- `implemented` | `planned` (default: implemented if omitted)
+- Use `planned` for Unit/Component during ATDD phase; promote to `implemented` in TDD/full.
+
+Note: The Status column is optional. If omitted, all rows are treated as `implemented` for backward compatibility.
 
 ## Coverage summary
 

package/assets/init/root/.claude/agents/atdd-api-implementer.md

@@ -0,0 +1,17 @@
+# ATDD API Implementer (Claude Code wrapper)
+
+## Purpose
+
+This is a thin wrapper for Claude Code agents. The canonical role card lives in .qfai/assistant/agents/atdd-api-implementer.md.
+
+## Rules
+
+- Always follow the .qfai role card and instructions first.
+- If this file conflicts with .qfai, the .qfai content wins.
+- Do not proceed without reading the role card.
+
+## Minimal steps
+
+1. Read .qfai/assistant/agents/atdd-api-implementer.md and follow its output format.
+2. Use .qfai/assistant/steering/ and .qfai/assistant/instructions/ as required context.
+3. List unknowns as Open Questions; do not mix them with decisions.

package/assets/init/root/.claude/agents/atdd-e2e-implementer.md

@@ -0,0 +1,17 @@
+# ATDD E2E Implementer (Claude Code wrapper)
+
+## Purpose
+
+This is a thin wrapper for Claude Code agents. The canonical role card lives in .qfai/assistant/agents/atdd-e2e-implementer.md.
+
+## Rules
+
+- Always follow the .qfai role card and instructions first.
+- If this file conflicts with .qfai, the .qfai content wins.
+- Do not proceed without reading the role card.
+
+## Minimal steps
+
+1. Read .qfai/assistant/agents/atdd-e2e-implementer.md and follow its output format.
+2. Use .qfai/assistant/steering/ and .qfai/assistant/instructions/ as required context.
+3. List unknowns as Open Questions; do not mix them with decisions.

package/assets/init/root/.claude/agents/atdd-integration-implementer.md

@@ -0,0 +1,17 @@
+# ATDD Integration Implementer (Claude Code wrapper)
+
+## Purpose
+
+This is a thin wrapper for Claude Code agents. The canonical role card lives in .qfai/assistant/agents/atdd-integration-implementer.md.
+
+## Rules
+
+- Always follow the .qfai role card and instructions first.
+- If this file conflicts with .qfai, the .qfai content wins.
+- Do not proceed without reading the role card.
+
+## Minimal steps
+
+1. Read .qfai/assistant/agents/atdd-integration-implementer.md and follow its output format.
+2. Use .qfai/assistant/steering/ and .qfai/assistant/instructions/ as required context.
+3. List unknowns as Open Questions; do not mix them with decisions.

package/assets/init/root/.claude/agents/doc-steward.md

@@ -0,0 +1,17 @@
+# Doc Steward (Claude Code wrapper)
+
+## Purpose
+
+This is a thin wrapper for Claude Code agents. The canonical role card lives in .qfai/assistant/agents/doc-steward.md.
+
+## Rules
+
+- Always follow the .qfai role card and instructions first.
+- If this file conflicts with .qfai, the .qfai content wins.
+- Do not proceed without reading the role card.
+
+## Minimal steps
+
+1. Read .qfai/assistant/agents/doc-steward.md and follow its output format.
+2. Use .qfai/assistant/steering/ and .qfai/assistant/instructions/ as required context.
+3. List unknowns as Open Questions; do not mix them with decisions.

package/assets/init/root/.claude/agents/orchestrator.md

@@ -0,0 +1,17 @@
+# Orchestrator (Claude Code wrapper)
+
+## Purpose
+
+This is a thin wrapper for Claude Code agents. The canonical role card lives in .qfai/assistant/agents/orchestrator.md.
+
+## Rules
+
+- Always follow the .qfai role card and instructions first.
+- If this file conflicts with .qfai, the .qfai content wins.
+- Do not proceed without reading the role card.
+
+## Minimal steps
+
+1. Read .qfai/assistant/agents/orchestrator.md and follow its output format.
+2. Use .qfai/assistant/steering/ and .qfai/assistant/instructions/ as required context.
+3. List unknowns as Open Questions; do not mix them with decisions.