qfai 1.5.3 → 1.5.5

package/README.md

@@ -17,6 +17,10 @@ The agent reads the repository, produces the required artifacts, and iterates un
 
 ## Quick start
 
+> **Windows users:** `qfai init` creates symlinks internally.
+> You must enable **Developer Mode** (Settings → System → For developers → Developer Mode: ON)
+> before running `npx qfai init`, otherwise symlink creation will fail due to insufficient privileges.
+
 ```bash
 # 1) Initialize QFAI assets in your repository
 npx qfai init
@@ -246,7 +250,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.5.3)
+## Minimal tutorial (v1.5.5)
 
 1. `npx qfai init`
 2. Run `/qfai-discussion` to structure scope, open questions, and produce a discussion pack under `.qfai/discussion/discussion-<ts>/`.
@@ -278,7 +282,8 @@ It does not generate GitHub Actions workflows.
 Configure CI in your own platform and run:
 
 ```bash
-pnpm ci:local
+pnpm ci:gate
+pnpm check-types:future
 # or, minimum gate only:
 npx qfai validate --fail-on error
 ```
@@ -286,6 +291,7 @@ npx qfai validate --fail-on error
 Recommended baseline.
 
 - Keep CI on default/full validation (`qfai validate --fail-on error`); do not use `--phase refinement` in CI.
+- Keep `pnpm check-types:future` as a separate mandatory gate so future TS compatibility runs once without duplicating `pnpm ci:gate`.
 - Add a report step (`npx qfai report`) when you need a human-readable artifact.
 - Tune traceability globs in `qfai.config.yaml` to match your test layout.
 

package/assets/init/.qfai/assistant/instructions/requirements-decomposition.md

@@ -12,11 +12,11 @@ This document is the decision rule SSOT for AI and humans when answering:
 
 ## Canonical order (top -> down)
 
-1. **Source registry** (`require/require-*/01_Sources.md`)
-2. **Requirement index** (`require/require-*/03_REQ.md`)
-3. **Input gaps / Open Questions** (`require/require-*/08_OQ.md`)
-4. **Policy layer** (`specs/_policies/01..04`)
-5. **Capability slices** (`specs/spec-*/01..05` minimum)
+1. **Source registry** (`.qfai/require/require-*/01_Sources.md`)
+2. **Requirement index** (`.qfai/require/require-*/03_REQ.md`)
+3. **Input gaps / Open Questions** (`.qfai/require/require-*/08_OQ.md`)
+4. **Policy layer** (`.qfai/specs/_policies/01..04`)
+5. **Capability slices** (`.qfai/specs/spec-*/01..05` minimum)
 6. **ATDD / TDD** (tests + code)
 
 ## Decision rules
@@ -28,9 +28,9 @@ This document is the decision rule SSOT for AI and humans when answering:
 
 ### Rule 2 - Preserve layered ownership
 
-- `require/` stores only source/index/gap inputs.
-- `specs/` is the SSOT for detailed behavior and design decisions.
-- Do not duplicate detailed spec text in `require/`.
+- `.qfai/require/` stores only source/index/gap inputs.
+- `.qfai/specs/` is the SSOT for detailed behavior and design decisions.
+- Do not duplicate detailed spec text in `.qfai/require/`.
 
 ### Rule 3 - Keep ambiguity explicit
 
@@ -39,9 +39,9 @@ This document is the decision rule SSOT for AI and humans when answering:
 
 ## How to decompose (mechanical procedure)
 
-1. Register source documents and assumptions in `require-*/01_Sources.md`.
-2. Extract concise requirement index entries in `require-*/03_REQ.md`.
-3. Capture missing information in `require-*/08_OQ.md`.
+1. Register source documents and assumptions in `.qfai/require/require-*/01_Sources.md`.
+2. Extract concise requirement index entries in `.qfai/require/require-*/03_REQ.md`.
+3. Capture missing information in `.qfai/require/require-*/08_OQ.md`.
 4. Build `_policies` layer (`Objective`, `Initiative`, `Capabilities`, `Business Flow`).
 5. Split by capability (`1 CAP = 1 spec-XXXX`) and produce slice files.
 6. Derive acceptance tests and implementation from the finalized slices.
@@ -49,11 +49,11 @@ This document is the decision rule SSOT for AI and humans when answering:
 ## Example
 
 - Requirement index entry: `REQ-0003` linked to `SRC-0002`
-- Capability mapping: `CAP-0003` in `_policies/03_Capabilities.md`
-- Spec slice: `spec-0003/01_Spec.md` through `06_Test-Cases.md`
+- Capability mapping: `CAP-0003` in `.qfai/specs/_policies/03_Capabilities.md`
+- Spec slice: `.qfai/specs/spec-0003/01_Spec.md` through `06_Test-Cases.md`
 
 ## Non-goals
 
 - Managing release status flags in specs.
-- Keeping full requirement prose in `require/`.
+- Keeping full requirement prose in `.qfai/require/`.
 - Treating diagrams as mandatory at require stage.

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

@@ -2,7 +2,7 @@
 
 QFAI standardizes work into a fixed pipeline:
 
-**SDD → ATDD → TDD → Verification**
+## SDD -> ATDD -> TDD -> Verification
 
 This file defines the canonical stages and delegation expectations.
 

package/assets/init/.qfai/assistant/manifest/spec_required_files.json

@@ -8,7 +8,8 @@
     "06_Test-Cases.md",
     "07_Decisions.md",
     "08_Open-questions.md",
-    "09_delta.md"
+    "09_delta.md",
+    "10_Plan.md"
   ],
   "shared_dir": [
     "01_Objective.md",

package/assets/init/.qfai/assistant/skills/qfai-atdd/SKILL.md

@@ -1,25 +1,47 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-atdd
 title: QFAI ATDD (Executable acceptance tests)
 description: "Implement automated acceptance tests (E2E/API/Integration) aligned with US/TC/CON-API obligations from specs and contracts."
 argument-hint: "<spec-id> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [Orchestrator, TestVolumeEstimator, ATDDE2EImplementer, ATDDAPIImplementer, ATDDIntegrationImplementer, QAEngineer, TestEngineer, BackendEngineer, FrontendEngineer, Reviewer, RuntimeGatekeeper, DevOpsCIEngineer, CodeReviewer]
+roles:
+  - Orchestrator
+  - TestVolumeEstimator
+  - ATDDE2EImplementer
+  - ATDDAPIImplementer
+  - ATDDIntegrationImplementer
+  - QAEngineer
+  - TestEngineer
+  - BackendEngineer
+  - FrontendEngineer
+  - Reviewer
+  - RuntimeGatekeeper
+  - DevOpsCIEngineer
+  - CodeReviewer
 mode: execution-focused
-
 ---
 
-# /qfai-atdd — Implement Automated Acceptance Tests (ATDD)
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-atdd — Implement Automated Acceptance Tests (ATDD)
 
 [DRIFT-PROTOCOL:MANDATORY]
 
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed (e.g., test scope decisions, runtime environment confirmation),
+  the agent MUST use AskUserQuestion if the tool is available.
+- When AskUserQuestion supports structured choices (radio/multi-select),
+  the agent MUST prefer structured choices over free-text input.
+- If AskUserQuestion is technically unavailable, present the same question as a normal message
+  with explicit numbered choices.
+  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
+  The reason for unavailability MUST be stated.
+
 ## FORMAT SSOT (Mandatory)
 
 - Before writing or editing any `.qfai/**` artifact, read and follow the relevant directory README template and sample.

package/assets/init/.qfai/assistant/skills/qfai-configure/SKILL.md

@@ -1,11 +1,4 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-configure
 title: QFAI Configure (Tune qfai.config.yaml)
 description: "Analyze the repository and tune qfai.config.yaml (testFileGlobs, exclude globs, optional specSections)."
@@ -13,13 +6,29 @@ argument-hint: "[--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task]
 roles: [DevOpsCIEngineer, QAEngineer, CodeReviewer, Planner]
 mode: evidence-focused
-
 ---
 
-# /qfai-configure - Configure QFAI for this repository
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-configure - Configure QFAI for this repository
 
 [DRIFT-PROTOCOL:MANDATORY]
 
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed (e.g., configuration decisions, glob pattern confirmation),
+  the agent MUST use AskUserQuestion if the tool is available.
+- When AskUserQuestion supports structured choices (radio/multi-select),
+  the agent MUST prefer structured choices over free-text input.
+- If AskUserQuestion is technically unavailable, present the same question as a normal message
+  with explicit numbered choices.
+  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
+  The reason for unavailability MUST be stated.
+
 ## FORMAT SSOT (Mandatory)
 
 - **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
@@ -148,7 +157,9 @@ Rules:
 ## Delta Rejected Guard (Mandatory)
 
 - Do NOT reintroduce options marked as rejected in 09_delta.md.
-- If a rejected option must be reconsidered, create a **[RE-OPEN]** Decision Record in 09_delta.md that references the prior DR-ID, states what changed + new criteria, and includes explicit approval (user or instructions/steering).
+- If a rejected option must be reconsidered, create a **[RE-OPEN]** Decision
+  Record in 09_delta.md that references the prior DR-ID, states what changed +
+  new criteria, and includes explicit approval (user or instructions/steering).
 
 ## CRITICAL CONSTRAINTS (Read First)
 
@@ -166,8 +177,15 @@ Before declaring completion, you MUST:
 
 - OQ / undefined resolution: detect undefined or ambiguous items; resolve them or explicitly defer them with documented rationale and (when required by this prompt) user approval.
 - Deliverable completeness: verify every expected artifact listed in this prompt (and required README templates) exists and is fully populated; no missing required sections.
-- 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.
+- 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,
+  or 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
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/SKILL.md

@@ -1,12 +1,4 @@
-````skill
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-discussion
 title: QFAI Discussion (Unified Discuss + Require)
 description: "Run structured discussion that merges discuss and require into a single 15-file discussion pack with OQ-driven exit."
@@ -14,13 +6,29 @@ argument-hint: "<idea-or-problem> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
 roles: [Researcher, Facilitator, Interviewer, RequirementsAnalyst, QAEngineer, Planner]
 mode: interactive-by-default
-
 ---
 
-# /qfai-discussion - Unified Discuss + Require
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-discussion - Unified Discuss + Require
 
 [DRIFT-PROTOCOL:MANDATORY]
 
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed (e.g., Simulation mode approval, scope confirmation),
+  the agent MUST use AskUserQuestion if the tool is available.
+- When AskUserQuestion supports structured choices (radio/multi-select),
+  the agent MUST prefer structured choices over free-text input.
+- If AskUserQuestion is technically unavailable, present the same question as a normal message
+  with explicit numbered choices.
+  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
+  The reason for unavailability MUST be stated.
+
 ## FORMAT SSOT (Mandatory)
 
 - Before writing artifacts, read and follow:
@@ -333,5 +341,3 @@ You MUST end the user-facing output with a handoff sentence to `/qfai-sdd` in th
   Action: continue discussion loops until OQ states are explicit and complete.
 - Need additional risk analysis before SDD:
   Action: update `03_Story-Workshop.md` and `11_OQ-Register.md` with additional findings.
-
-````

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/review/Rxx_reviewer.md

@@ -1,9 +1,9 @@
 # Reviewer Result
 
-- reviewer_id: `<qa-lead>`
-- reviewer_role: `<Quality Lead>`
+- reviewer_id: `Rxx`
+- reviewer_role: `qa-lead`
 - verdict: `PASS` <!-- PASS | FAIL | N/A -->
-- reviewed_at: `<YYYY-MM-DDThh:mm:ssZ>`
+- reviewed_at: `YYYY-MM-DDThh:mm:ssZ`
 
 ## Checked
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/review/summary.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0",
-  "created_at": "2026-03-03T12:00:00+09:00",
+  "created_at": "YYYY-MM-DDThh:mm:ssZ",
   "target": {
     "kind": "discussion",
     "path": ".qfai/discussion/discussion-YYYYMMDDhhmmssSSS"

package/assets/init/.qfai/assistant/skills/qfai-prototyping/SKILL.md

@@ -1,25 +1,45 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-prototyping
 title: QFAI Prototyping (All-spec runnable skeleton gate)
 description: "Implement a minimum runnable skeleton for ALL specs and block DONE until evidence + validate gate pass."
 argument-hint: "[--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [FullStackEngineer, BackendEngineer, FrontendEngineer, DBEngineer, DevOpsCIEngineer, QAEngineer, RuntimeGatekeeper, UIUXReviewer, CodeReviewer]
+roles:
+  [
+    FullStackEngineer,
+    BackendEngineer,
+    FrontendEngineer,
+    DBEngineer,
+    DevOpsCIEngineer,
+    QAEngineer,
+    RuntimeGatekeeper,
+    UIUXReviewer,
+    CodeReviewer,
+  ]
 mode: execution-focused
-
 ---
 
-# /qfai-prototyping
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-prototyping
 
 [DRIFT-PROTOCOL:MANDATORY]
 
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed (e.g., implementation scope decisions, runtime environment confirmation),
+  the agent MUST use AskUserQuestion if the tool is available.
+- When AskUserQuestion supports structured choices (radio/multi-select),
+  the agent MUST prefer structured choices over free-text input.
+- If AskUserQuestion is technically unavailable, present the same question as a normal message
+  with explicit numbered choices.
+  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
+  The reason for unavailability MUST be stated.
+
 Run prototyping as an **all-spec stage**. Scope is fixed to **ALL specs** resolved from `.qfai/specs/spec-*`.
 
 This stage is complete only when all specs pass the minimum runtime contract:

package/assets/init/.qfai/assistant/skills/qfai-sdd/SKILL.md

@@ -1,25 +1,44 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-sdd
 title: QFAI SDD Unified (Outline/Slice/Plan/Delta)
 description: "Create and update layered SDD artifacts (\_policies + spec-XXXX) in one workflow."
 argument-hint: "[<spec-id-or-name>] [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [Planner, Architect, RequirementsAnalyst, SpecWriter, TraceabilityBuilder, TestStrategist, QAEngineer, CodeReviewer]
+roles:
+  [
+    Planner,
+    Architect,
+    RequirementsAnalyst,
+    SpecWriter,
+    TraceabilityBuilder,
+    TestStrategist,
+    QAEngineer,
+    CodeReviewer,
+  ]
 mode: approval-gated
-
 ---
 
-# /qfai-sdd - Unified SDD Workflow
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-sdd - Unified SDD Workflow
 
 [DRIFT-PROTOCOL:MANDATORY]
 
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed (e.g., OQ resolution, NFR priority decisions),
+  the agent MUST use AskUserQuestion if the tool is available.
+- When AskUserQuestion supports structured choices (radio/multi-select),
+  the agent MUST prefer structured choices over free-text input.
+- If AskUserQuestion is technically unavailable, present the same question as a normal message
+  with explicit numbered choices.
+  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
+  The reason for unavailability MUST be stated.
+
 ## FORMAT SSOT (Mandatory)
 
 - Before writing or editing any `.qfai/**` artifact, read and follow:

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/report/preflight_summary.md

@@ -16,4 +16,4 @@
 
 ## Next Commands
 
-- /qfai-discussion
+- /qfai-sdd

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_policies/05_Contracts.md

@@ -9,29 +9,47 @@
 
 ### DB Contracts
 
-| Short ID | Entity       | Declared ID | File                                    | Purpose           |
-| -------- | ------------ | ----------- | --------------------------------------- | ----------------- |
+0 items
+
+<!-- Example row (remove this comment block and add real rows when contracts exist):
 | DB-001   | order_drafts | CON-DB-0001 | `.qfai/contracts/db/db-0001-<slug>.sql` | draft persistence |
+-->
+
+| Short ID | Entity | Declared ID | File | Purpose |
+| -------- | ------ | ----------- | ---- | ------- |
 
 ### API Contracts
 
-| Short ID | Router      | Declared ID  | File                                       | Purpose      |
-| -------- | ----------- | ------------ | ------------------------------------------ | ------------ |
+0 items
+
+<!-- Example row:
 | API-001  | /api/orders | CON-API-0001 | `.qfai/contracts/api/api-0001-<slug>.yaml` | create draft |
+-->
+
+| Short ID | Router | Declared ID | File | Purpose |
+| -------- | ------ | ----------- | ---- | ------- |
 
 ### UI Contracts
 
-| Short ID | Screen       | Declared ID | File                                     | Purpose          |
-| -------- | ------------ | ----------- | ---------------------------------------- | ---------------- |
+0 items
+
+<!-- Example row:
 | UI-001   | order-create | CON-UI-0001 | `.qfai/contracts/ui/ui-0001-<slug>.yaml` | draft input form |
+-->
+
+| Short ID | Screen | Declared ID | File | Purpose |
+| -------- | ------ | ----------- | ---- | ------- |
 
 ## Mapping Rules
 
+- If no contracts are needed, keep each table and state `0 items` explicitly.
+- `<slug>` must be kebab-case from entity/router/screen.
+
+<!-- Example mappings (add when contracts exist):
 - `DB-001` maps to `CON-DB-0001`, file `db-0001-<slug>.sql`.
 - `API-001` maps to `CON-API-0001`, file `api-0001-<slug>.yaml`.
 - `UI-001` maps to `CON-UI-0001`, file `ui-0001-<slug>.yaml`.
-- `<slug>` must be kebab-case from entity/router/screen.
-- If no contracts are needed, keep each table and state `0 items` explicitly.
+-->
 
 ## Diagram (Mermaid required for ER/relationship)
 

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/spec/01_Spec.md

@@ -1,11 +1,11 @@
 # 01 Spec
 
-- Spec: spec-0001
-- Parent: CAP-0001
+- Spec: spec-XXXX
+- Parent: CAP-XXXX
 
 ## Consumer View
 
-- Primary SSOT for execution: `spec-0001/01_Spec.md`
+- Primary SSOT for execution: `spec-XXXX/01_Spec.md`
 - Default read set: this file + relevant contracts only
 - `_policies` is read-only escalation context and must not be read by default
 
@@ -47,7 +47,7 @@
 
 ### Escalation Targets (Read-only, decision basis)
 
-- specs/\_policies/01_Objective.md
-- specs/\_policies/02_Initiative.md
-- specs/\_policies/07_Constraints.md
-- specs/\_policies/08_Decisions.md
+- \_policies/01_Objective.md
+- \_policies/02_Initiative.md
+- \_policies/07_Constraints.md
+- \_policies/08_Decisions.md

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/spec/02_User-stories.md

@@ -6,7 +6,7 @@
 
 ## US-0001: <title>
 
-- Parent: CAP-0001
+- Parent: CAP-XXXX
 - Goal: <goal>
 - Non-goals: <non-goal>
 - Notes: <notes>

package/assets/init/.qfai/assistant/skills/qfai-tdd-green/SKILL.md

@@ -1,11 +1,4 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-tdd-green
 title: QFAI TDD Green (Deprecated Wrapper)
 description: "Deprecated wrapper. Legacy red/green/refactor chain is no longer a completion gate."
@@ -13,13 +6,29 @@ argument-hint: "[optional notes]"
 allowed-tools: [Read]
 roles: [Reviewer]
 mode: approval-gated
-
 ---
 
-# /qfai-tdd-green - Deprecated Wrapper
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-tdd-green - Deprecated Wrapper
 
 [DRIFT-PROTOCOL:MANDATORY]
 
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed (e.g., Simulation mode approval),
+  the agent MUST use AskUserQuestion if the tool is available.
+- When AskUserQuestion supports structured choices (radio/multi-select),
+  the agent MUST prefer structured choices over free-text input.
+- If AskUserQuestion is technically unavailable, present the same question as a normal message
+  with explicit numbered choices.
+  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
+  The reason for unavailability MUST be stated.
+
 ## Deprecation Notice (MUST)
 
 - This command is deprecated.

package/assets/init/.qfai/assistant/skills/qfai-tdd-red/SKILL.md

@@ -1,11 +1,4 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-tdd-red
 title: QFAI TDD Red (Deprecated Wrapper)
 description: "Deprecated wrapper. Legacy red/green/refactor chain is no longer a completion gate."
@@ -13,13 +6,29 @@ argument-hint: "[optional notes]"
 allowed-tools: [Read]
 roles: [Reviewer]
 mode: approval-gated
-
 ---
 
-# /qfai-tdd-red - Deprecated Wrapper
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-tdd-red - Deprecated Wrapper
 
 [DRIFT-PROTOCOL:MANDATORY]
 
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed (e.g., Simulation mode approval),
+  the agent MUST use AskUserQuestion if the tool is available.
+- When AskUserQuestion supports structured choices (radio/multi-select),
+  the agent MUST prefer structured choices over free-text input.
+- If AskUserQuestion is technically unavailable, present the same question as a normal message
+  with explicit numbered choices.
+  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
+  The reason for unavailability MUST be stated.
+
 ## Deprecation Notice (MUST)
 
 - This command is deprecated.

package/assets/init/.qfai/assistant/skills/qfai-tdd-refactor/SKILL.md

@@ -1,11 +1,4 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-tdd-refactor
 title: QFAI TDD Refactor (Deprecated Wrapper)
 description: "Deprecated wrapper. Legacy red/green/refactor chain is no longer a completion gate."
@@ -13,13 +6,29 @@ argument-hint: "[optional notes]"
 allowed-tools: [Read]
 roles: [Reviewer]
 mode: approval-gated
-
 ---
 
-# /qfai-tdd-refactor - Deprecated Wrapper
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-tdd-refactor - Deprecated Wrapper
 
 [DRIFT-PROTOCOL:MANDATORY]
 
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed (e.g., Simulation mode approval),
+  the agent MUST use AskUserQuestion if the tool is available.
+- When AskUserQuestion supports structured choices (radio/multi-select),
+  the agent MUST prefer structured choices over free-text input.
+- If AskUserQuestion is technically unavailable, present the same question as a normal message
+  with explicit numbered choices.
+  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
+  The reason for unavailability MUST be stated.
+
 ## Deprecation Notice (MUST)
 
 - This command is deprecated.