qfai 1.5.7 → 1.6.0

package/README.md

@@ -123,7 +123,7 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
 - **qfai-sdd**: Unified SDD entrypoint with discussion-pack preflight guard (missing/incomplete/blocking OQ causes stop + next action guidance).
 - **qfai-prototyping**: Build an all-spec contract-aligned skeleton and prove runtime coverage before deep coding.
 - **qfai-atdd**: Implement acceptance tests driven by specs/scenarios.
-- **qfai-tdd-red / qfai-tdd-green / qfai-tdd-refactor (deprecated wrappers)**: Legacy entrypoints kept for backward compatibility only. They return deprecation guidance and route to `/qfai-atdd` + `/qfai-verify`.
+- **qfai-implement**: Unified TDD micro-cycle (Red/Green/Refactor) one test at a time using `test-list.md` as the execution ledger.
 - **qfai-verify**: Run/interpret the local quality gates and produce a release-ready summary.
 
 ### Workflow sequence (example)
@@ -166,9 +166,10 @@ AG->>Q: Read .qfai/assistant/skills/qfai-atdd/SKILL.md
 AG->>R: Implement acceptance tests
 AG-->>U: ATDD tests ready
 
-U->>AG: (Optional legacy) Run /qfai-tdd-red|green|refactor
-AG->>Q: Read deprecated wrapper skill
-AG-->>U: Route to /qfai-atdd and /qfai-verify
+U->>AG: Run /qfai-implement
+AG->>Q: Read .qfai/assistant/skills/qfai-implement/SKILL.md
+AG->>R: Execute TDD micro-cycle (Red/Green/Refactor) per test-list.md
+AG-->>U: Implementation complete
 
 U->>AG: Run /qfai-verify
 AG->>Q: Read .qfai/assistant/skills/qfai-verify/SKILL.md
@@ -357,11 +358,7 @@ Typical customizations.
 │   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-atdd
 │   │   │   │   └── SKILL.md
-│   │   │   ├── qfai-tdd-red
-│   │   │   │   └── SKILL.md
-│   │   │   ├── qfai-tdd-green
-│   │   │   │   └── SKILL.md
-│   │   │   ├── qfai-tdd-refactor
+│   │   │   ├── qfai-implement
 │   │   │   │   └── SKILL.md
 │   │   │   └── qfai-verify
 │   │   │       └── SKILL.md

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

@@ -17,9 +17,7 @@ flowchart TD
   A[/qfai-discussion/] --> C[/qfai-sdd/]
   C --> D[/qfai-prototyping/]
   D --> E[/qfai-atdd/]
-  E --> F[/qfai-tdd-red/]
-  F --> G[/qfai-tdd-green/]
-  G --> H[/qfai-tdd-refactor/]
+  E --> F[/qfai-implement/]
 ```
 
 > Formatting must follow the templates and checklists documented in each directory README.

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

@@ -66,9 +66,13 @@ Prototyping stage policy:
 - Completion requires prototyping evidence (markdown + json in `.qfai/evidence/`) and `qfai validate --fail-on error` pass.
 - Coverage gaps (missing spec rows, unresolved declared checks, API 404) are blocking.
 
+Implementation stage:
+
+- `/qfai-implement` orchestrates the full TDD micro-cycle (Red/Green/Refactor) one test at a time using `test-list.md` as the execution ledger.
+
 Legacy note:
 
-- `/qfai-tdd-red`, `/qfai-tdd-green`, and `/qfai-tdd-refactor` are deprecated wrappers and are not canonical completion stages.
+- The three legacy TDD skills were abolished. Use `/qfai-implement` instead.
 
 ### Stage 0 — Steering refresh contract (mandatory)
 

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

@@ -228,7 +228,7 @@ Turn specs/contracts obligations (`US` / `TC` / `CON-API`) into runnable accepta
 ## Scope (ATDD only)
 
 - In scope: E2E, API, Integration.
-- Out of scope: Unit and Component (`/qfai-tdd-red`).
+- Out of scope: Unit and Component (`/qfai-implement`).
 
 ## Non-goals
 
@@ -421,9 +421,7 @@ When declaring DONE, include:
 
 When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
 
-- Proceed (recommended): `/qfai-tdd-red`.
-  Action: derive unit/component RED tests from acceptance tests.
+- Proceed (recommended): `/qfai-implement`.
+  Action: run unified TDD micro-cycle (Red/Green/Refactor) one test at a time from test-list.md.
 - Acceptance tests need fixes: rerun `/qfai-atdd`.
   Action: close uncovered `US` / `TC` / `CON-API` obligations and rerun validation.
-- Implementation phase: `/qfai-tdd-green`.
-  Action: implement code to satisfy failing tests.

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

@@ -0,0 +1,221 @@
+---
+name: qfai-implement
+title: QFAI Implement (Unified TDD Micro-cycle)
+description: "Unified implementation skill that orchestrates the full TDD micro-cycle (Red/Green/Refactor) one test at a time using test-list.md as the execution ledger."
+argument-hint: "<spec-id>"
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
+roles: [Implementer, Reviewer]
+mode: approval-gated
+---
+
+<!--
+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-implement - Unified TDD Micro-cycle
+
+[DRIFT-PROTOCOL:MANDATORY]
+
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed (e.g., exception handling, 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.
+
+## CRITICAL CONSTRAINTS (Read First)
+
+- This skill processes **one test at a time** from `test-list.md`.
+- Each item goes through the full TDD micro-cycle: write a **failing test** first, then make it pass, then refactor.
+- The execution ledger is located at `.qfai/specs/spec-XXXX/tdd/test-list.md`.
+- Items are processed **serially** by default. Parallel processing is allowed only when items target independent SUT slices with no shared state.
+- Status transitions follow a strict forward-only lifecycle: `todo` -> `red` -> `green` -> `refactor` -> `done`.
+- The `exception` status can be reached from any active status when an anomaly is detected.
+- Backward transitions are prohibited (e.g., `green` -> `red` is not allowed).
+- Completed items (`done`) are skipped on re-execution.
+- When all items are `done`, report "nothing to do" and exit.
+
+## Goal
+
+Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioning each through Red -> Green -> Refactor -> Done, producing tested production code aligned with the spec.
+
+## Non-goals
+
+- Writing spec artifacts (use `/qfai-sdd`).
+- Writing acceptance tests (use `/qfai-atdd`).
+- Running validation gates (use `/qfai-verify`).
+- Parallel execution across multiple specs simultaneously.
+
+## Execution Ledger: test-list.md
+
+The execution ledger at `.qfai/specs/spec-XXXX/tdd/test-list.md` tracks progress with these required columns:
+
+| Column    | Description                                        |
+| --------- | -------------------------------------------------- |
+| TDD-ID    | Unique identifier for the TDD item (e.g., TDD-001) |
+| TC-Refs   | References to test cases from `06_Test-Cases.md`   |
+| Layer     | Test layer (Unit, Integration, etc.)               |
+| Test file | Path to the test file                              |
+| Selector  | Test selector/description for targeted execution   |
+| Status    | Current lifecycle status                           |
+
+### Status Lifecycle
+
+Valid status values: `todo`, `red`, `green`, `refactor`, `done`, `exception`.
+
+Allowed transitions:
+
+- `todo` -> `red` (write a failing test)
+- `red` -> `green` (make the test pass with minimal code)
+- `green` -> `refactor` (improve code quality while keeping tests green)
+- `refactor` -> `done` (item complete)
+- Any active status -> `exception` (anomaly detected; record DR-ID in Notes column if present)
+
+Backward transitions are prohibited. Attempting `green` -> `red` must produce:
+`"Backward transition prohibited: green -> red"`.
+
+### Exception Handling
+
+When transitioning to `exception`:
+
+- A DR-ID (Decision Record ID) should be recorded in the Notes column if present.
+- If a Notes column exists but is empty, emit warning: `"exception status requires DR-ID in Notes column"`.
+
+## Required Process
+
+### Phase: Red (Write Failing Test)
+
+1. Read `test-list.md` and select the first item with `Status = todo`.
+2. Transition status to `red`.
+3. Write a **failing test** based on the TC-Refs specification.
+4. Run the test and **watch it fail** — confirm the test actually fails for the expected reason.
+5. If the test unexpectedly passes, transition to `exception` and record the anomaly.
+
+### Phase: Green (Make It Pass)
+
+1. Write the **minimum production code** to make the failing test pass.
+2. Run the test and **watch it pass**.
+3. Transition status to `green`.
+4. If the test still fails after implementation, investigate and fix. Do not skip to refactor.
+
+### Phase: Refactor
+
+1. Improve code quality (naming, structure, duplication removal) while keeping all tests green.
+2. Run the full relevant test suite to confirm nothing broke.
+3. Transition status to `refactor`, then immediately to `done`.
+
+### Completion
+
+1. After processing all items, update `test-list.md` with final statuses.
+2. If all items are `done`, report "All items complete".
+3. If some items are `exception`, report them with their DR-IDs.
+
+## Sub-agent Delegation (MANDATORY)
+
+### Orchestrator Protocol (MUST)
+
+- Orchestrator reads `test-list.md`, determines the next pending item, and delegates each TDD phase.
+- Orchestrator MUST NOT write test or production code directly.
+- Orchestrator updates `test-list.md` status after each phase completes.
+
+### Sub-agent Roles
+
+| Role        | Responsibility                               |
+| ----------- | -------------------------------------------- |
+| TestWriter  | Writes the failing test (Red phase)          |
+| Implementer | Writes minimal production code (Green phase) |
+| Refactorer  | Improves code quality (Refactor phase)       |
+| TestRunner  | Executes tests and reports pass/fail results |
+
+### Capability Probe (MUST)
+
+1. Run one harmless Probe Task once at stage start.
+2. If subagents are unavailable, explicitly ask for Simulation mode approval.
+3. Without explicit approval, stop the stage.
+
+### Simulation mode (Opt-in only)
+
+- Allowed only when user explicitly states `Simulation mode allowed`.
+- Record both:
+  - `Subagents: simulated (reason: <why unavailable>)`
+  - `User approval: <quote or reference>`
+
+## Work Orders Summary
+
+Every major artifact in this stage MUST include this table schema:
+
+| Step | Role (sub-agent) | Task title | Input (refs) | Output (refs) | Status (PASS/REVISE) |
+| ---- | ---------------- | ---------- | ------------ | ------------- | -------------------- |
+| 1    | `role`           | `task`     | `refs`       | `refs`        | PASS/REVISE          |
+
+### Reviewer Gate (MUST)
+
+- Delegate final completion gate to an independent Reviewer.
+- Reviewer checks Drift Protocol compliance and alignment with `.qfai/assistant/steering/test-layers.md`.
+- Test volume floors/ratios are not gates; they are signals.
+- Do not declare DONE until Reviewer returns `PASS`; otherwise apply `REVISE`.
+
+## Parallelization Policy
+
+- **Default**: Serial execution. Items are processed one at a time in `test-list.md` order.
+- **Exception**: When items target completely independent SUT modules with no shared state, parallel processing may be used with explicit user approval.
+- Serial execution ensures that each test is written and verified in isolation before moving to the next.
+
+## Completion Contract (Shared)
+
+Before declaring completion, you MUST:
+
+- All `todo` items in `test-list.md` have been processed.
+- Each processed item reached `done` or `exception` status.
+- All tests pass (`npm test` or equivalent).
+- `test-list.md` reflects the final state accurately.
+- Exception items have DR-IDs recorded (in Notes column if present).
+
+## Evidence (MANDATORY)
+
+Create/update: `.qfai/evidence/implement-spec-XXXX.md`
+
+Required sections:
+
+- Objective
+- Items processed (TDD-ID, TC-Refs, final status)
+- Test results summary
+- Exception items (if any) with DR-IDs
+- Commands executed
+
+## FINAL CHECKLIST (Check Last)
+
+- [ ] CRITICAL CONSTRAINTS were followed.
+- [ ] Each item was processed one test at a time.
+- [ ] Red phase: test was written and confirmed to fail.
+- [ ] Green phase: minimal code was written and test confirmed to pass.
+- [ ] Refactor phase: code improved with tests still passing.
+- [ ] `test-list.md` statuses are accurate.
+- [ ] No backward transitions occurred.
+- [ ] Exception items have DR-IDs recorded.
+- [ ] All tests pass.
+
+## Completion Checklist (MUST)
+
+- [ ] This skill's Definition of Done is satisfied.
+- [ ] Required artifacts were produced or updated (if applicable).
+- [ ] Open questions were logged to the proper OQ file (if applicable).
+- [ ] The completion message was presented to the user.
+- [ ] Next actions were enumerated for all available options.
+
+## Completion Message & Next Actions (MUST)
+
+When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
+
+- Verify gates: `/qfai-verify`.
+  Action: run `qfai validate --fail-on error` and confirm all gates pass.
+- Spec updates needed: `/qfai-sdd`.
+  Action: update spec artifacts if implementation revealed scope changes.
+- Acceptance tests: `/qfai-atdd`.
+  Action: ensure acceptance test coverage aligns with implementation.

package/assets/init/.qfai/specs/spec-XXXX/tdd/test-list.md

@@ -0,0 +1,4 @@
+# TDD Execution Ledger
+
+| TDD-ID | TC-Refs | Layer | Test file | Selector | Status |
+| ------ | ------- | ----- | --------- | -------- | ------ |