qfai 1.4.0 → 1.4.6

package/README.md

@@ -56,10 +56,9 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
 
 - **qfai-configure**: Analyze the repository (language, frameworks, test layout, directory structure) and tailor `qfai.config.yaml` accordingly (especially `testFileGlobs`). Run this once right after `npx qfai init`, and re-run it when the repository structure changes.
 - **qfai-discuss**: Turn an idea into clear requirements by discussing scope, constraints, risks, and open questions.
-- **qfai-require**: Produce `.qfai/require/require.md` from your idea or discussion output.
-- **qfai-sdd-refinement**: Produce upstream SDD artifacts (`spec.md`, `delta.md`, `scenario.feature`, `case-catalogue.md`, `traceability-matrix.md`) and remove ambiguity.
-- **qfai-sdd-planning**: Produce `plan.md` as the How SSOT for downstream execution.
-- **qfai-spec**: Deprecated alias of `qfai-sdd-refinement` for backward compatibility.
+- **qfai-require**: Produce `.qfai/require/REQUIRE-XXXX/*` from your idea or discussion output.
+- **qfai-sdd**: Produce/update the full spec pack (`01_Spec.md` to `18_delta.md`) in one workflow (Outline -> Slice -> Plan finalize -> Delta).
+- **qfai-spec**: Deprecated alias of `qfai-sdd` for backward compatibility.
 - **qfai-scenario-test**: Implement acceptance tests (ATDD) driven by specs/scenarios.
 - **qfai-unit-test**: Implement unit tests (TDD) driven by specs/scenarios.
 - **qfai-implement**: Implement the feature; iterate test→fix until all quality gates are green.
@@ -88,23 +87,18 @@ AG-->>U: Config tuned to this repo
 
 opt If you only have an idea
 U->>AG: Run /qfai-discuss
-AG-->>U: Clarified requirements (notes)
+AG-->>U: Structured discuss package (.qfai/discuss/DISCUSS-XXXX/)
 end
 
 U->>AG: Run /qfai-require
 AG->>Q: Read .qfai/assistant/skills/qfai-require/SKILL.md
-AG->>R: Create/Update requirements docs
-AG-->>U: Requirements ready
+AG->>R: Create/Update REQUIRE-XXXX package docs
+AG-->>U: Requirement package ready
 
-U->>AG: Run /qfai-sdd-refinement
-AG->>Q: Read .qfai/assistant/skills/qfai-sdd-refinement/SKILL.md
-AG->>R: Create/refine specs + contracts + scenario.feature
-AG-->>U: Refinement artifacts ready
-
-U->>AG: Run /qfai-sdd-planning
-AG->>Q: Read .qfai/assistant/skills/qfai-sdd-planning/SKILL.md
-AG->>R: Create plan.md (How SSOT)
-AG-->>U: Planning artifacts ready
+U->>AG: Run /qfai-sdd
+AG->>Q: Read .qfai/assistant/skills/qfai-sdd/SKILL.md
+AG->>R: Create/refine spec pack (01..18) + contracts + 17_Plan.md
+AG-->>U: SDD artifacts ready
 
 U->>AG: Run /qfai-scenario-test
 AG->>Q: Read .qfai/assistant/skills/qfai-scenario-test/SKILL.md
@@ -132,10 +126,11 @@ R-->>U: Traceability checks and report artifacts
 Operational notes.
 
 - Each custom skill must output in the user’s language (absolute requirement).
+- Each custom skill must end with a completion message that enumerates all available next actions and clearly states what to do for each option.
 - Except `qfai-discuss`, each skill must analyze the project context (architecture, tech stack, test framework, repo structure) before generating artifacts or code.
 - Skills should delegate work to multiple role-based sub-agents (Planner, Architect, Contract Designer, QA, Code Reviewer, etc.) to emulate a real delivery flow.
-- Change classification (Primary/Tags) is required in delta.md and recommended in PRs. See `.qfai/assistant/instructions/change-classification.md`.
-- Verification planning is recorded in `delta.md` (`Verification -> Plan`) and validated in CI (`VFY-*` rules).
+- Change classification (Primary/Tags) is required in `18_delta.md` and recommended in PRs. See `.qfai/assistant/instructions/change-classification.md`.
+- Verification planning is recorded in `18_delta.md` (`Verification -> Plan`) and validated in CI (`VFY-*` rules).
 
 ## Configuration
 
@@ -183,6 +178,44 @@ QFAI uses a small, opinionated set of artifacts to reduce ambiguity and prevent
 
 Traceability is validated across these artifacts, so code changes remain grounded in the specs and the tests prove compliance.
 
+## SSOT boundaries
+
+```mermaid
+flowchart LR
+  S[.qfai/specs/**] --> L[16_Traceability-ledger.md]
+  C[.qfai/contracts/**] --> L
+  L --> V[qfai validate]
+  V --> R[.qfai/report/**]
+```
+
+- Specs SSOT: `.qfai/specs/**` (`01..18`, especially `16_Traceability-ledger.md` and `18_delta.md`)
+- Contracts SSOT: `.qfai/contracts/**`
+- Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
+
+## Minimal tutorial (v1.4.6)
+
+1. `npx qfai init`
+2. Run `/qfai-discuss` to structure scope and open questions.
+3. Run `/qfai-require` to produce `REQUIRE-XXXX`.
+4. Run `/qfai-sdd` to build `spec-XXXX/01..18`.
+5. Run `npx qfai validate` then `npx qfai report`.
+
+Release gate behavior:
+
+- Merge gate: `qfai validate` must pass (`error=0`), and open OQ is warning.
+- Release gate: set `release_candidate: true` in `03_Initiative.md`; open OQ then becomes error.
+
+## FAQ
+
+- Q: I referenced AC/TC directly from upper layers and got an error.
+  - A: Keep upper-to-lower references out of upper docs; use `16_Traceability-ledger.md` for cross-layer linkage.
+- Q: Ledger validation fails with missing columns.
+  - A: Ensure required columns exist: `trace_id,obj_id,init_id,cap_id,flow_id,us_id,ac_id,ex_ids,tc_ids`.
+- Q: `18_delta.md` fails validation.
+  - A: Include all required sections (`Change Summary`, `Rationale`, `Candidates Considered`, `Adopted`, `Rejected`, `Impact`, `Follow-ups`) and include both `DO NOT` and `Temptation` in `Rejected`.
+- Q: release_candidate validation fails due open questions.
+  - A: In `15_Open-questions.md`, change `status: open` to `resolved` or `deferred` and keep evidence.
+
 ## Continuous integration (GitHub Actions)
 
 (GitHub Actions)
@@ -237,9 +270,7 @@ Typical customizations.
 │       │   └── SKILL.md
 │       ├── qfai-scenario-test
 │       │   └── SKILL.md
-│       ├── qfai-sdd-refinement
-│       │   └── SKILL.md
-│       ├── qfai-sdd-planning
+│       ├── qfai-sdd
 │       │   └── SKILL.md
 │       ├── qfai-spec
 │       │   └── SKILL.md
@@ -300,6 +331,12 @@ Typical customizations.
 │   │   │   ├── structure.md
 │   │   │   └── tech.md
 │   │   └── README.md
+│   ├── discuss
+│   │   ├── README.md
+│   │   └── DISCUSS-0001
+│   │       ├── 00_Summary.md
+│   │       ├── ...
+│   │       └── 07_Open-questions.md
 │   ├── contracts
 │   │   ├── api
 │   │   │   └── README.md
@@ -312,7 +349,15 @@ Typical customizations.
 │   │   └── README.md
 │   ├── require
 │   │   ├── README.md
-│   │   └── require.md
+│   │   ├── REQUIRE-0001
+│   │   │   ├── 00_Summary.md
+│   │   │   ├── ...
+│   │   │   └── 07_Open-questions.md
+│   │   ├── glossary.md        # legacy compatibility
+│   │   ├── actors.md          # legacy compatibility
+│   │   ├── business-flows.md  # legacy compatibility
+│   │   ├── require.md         # legacy compatibility
+│   │   └── open-questions.md  # legacy compatibility
 │   ├── specs
 │   │   └── README.md
 │   └── README.md

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

@@ -15,13 +15,12 @@ This folder is generated by `qfai init` and designed to be:
 ```mermaid
 flowchart TD
   A[/qfai-discuss/] --> B[/qfai-require/]
-  B --> C[/qfai-sdd-refinement/]
-  C --> D[/qfai-sdd-planning/]
-  D --> E[/qfai-prototyping/]
-  E --> F[/qfai-atdd/]
-  F --> G[/qfai-tdd-red/]
-  G --> H[/qfai-tdd-green/]
-  H --> I[/qfai-tdd-refactor/]
+  B --> 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/]
 ```
 
 > Formatting must follow the templates and checklists documented in each directory README.
@@ -31,9 +30,8 @@ flowchart TD
 ```text
 .qfai/
 ├── README.md
-├── discussions/
-│   ├── README.md
-│   └── discuss-0001-<topic>.md
+├── discuss/
+│   └── README.md
 ├── assistant/
 │   ├── skills/               # canonical skills (SSOT)
 │   ├── skills.local/         # project-specific overrides
@@ -41,40 +39,20 @@ flowchart TD
 │   ├── steering/             # project steering inputs
 │   └── instructions/         # workflow and guardrail docs
 ├── require/
-│   ├── README.md
-│   ├── glossary.md
-│   ├── actors.md
-│   ├── business-flows.md
-│   ├── require.md
-│   └── open-questions.md
+│   └── README.md
 ├── contracts/
 │   ├── README.md
 │   ├── api/
-│   │   ├── README.md
-│   │   └── api-0001-sample.yaml
+│   │   └── README.md
 │   ├── db/
-│   │   ├── README.md
-│   │   └── db-0001-sample.sql
+│   │   └── README.md
 │   └── ui/
-│       ├── README.md
-│       └── ui-0001-sample.yaml
+│       └── README.md
 ├── specs/
-│   ├── README.md
-│   └── spec-0001/
-│       ├── spec.md
-│       ├── delta.md
-│       ├── scenario.feature
-│       ├── case-catalogue.md
-│       ├── traceability-matrix.md
-│       ├── plan.md
-│       ├── 01_Spec.md
-│       ├── ...
-│       ├── 17_Plan.md
-│       └── 18_delta.md
-├── templates/
-│   └── spec/                 # compatibility templates (runtime SSOT files)
+│   └── README.md
 └── evidence/
     ├── README.md
+    ├── .gitignore
     └── <skill>-<run>.md
 ```
 
@@ -101,10 +79,16 @@ It is useful for local review but should not pollute version control.
 - Prefer small stable identifiers (REQ/BR/AC/TC/EX/etc.) over long mixed paragraphs.
 - If one line contains multiple independent constraints, split it.
 
-### R4. Runtime compatibility first, layered overlay second
+### R4. Spec Pack 01..18 is runtime SSOT
+
+- Runtime validators and downstream skills consume `01_*` to `18_*`.
+- Traceability links are written in `16_Traceability-ledger.md`.
+- Derived outputs under `.qfai/report/**` are non-SSOT.
+
+### R5. init is an empty scaffold
 
-- Runtime validators and downstream skills consume `spec.md`, `delta.md`, `scenario.feature`, `case-catalogue.md`, `traceability-matrix.md`, and `plan.md`.
-- Layered files (`01_*` to `18_*`) are optional overlays and must stay synchronized when present.
+- `qfai init` creates README-centric directories for `discuss`, `require`, `contracts`, and `specs`.
+- Sample artifacts are provided under skill templates (for example, `assistant/skills/qfai-spec/templates/contracts/`).
 
 ## Skills (SSOT)
 

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

@@ -11,7 +11,8 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .qfai/require/require.md
+- .qfai/require/REQUIRE-XXXX/\* (preferred)
+- .qfai/require/require.md (legacy compatibility)
 - Existing architecture docs (if any)
 
 ## Deliverables (MANDATORY)

package/assets/init/.qfai/assistant/agents/contract-designer.md

@@ -11,7 +11,8 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .qfai/require/require.md
+- .qfai/require/REQUIRE-XXXX/\* (preferred)
+- .qfai/require/require.md (legacy compatibility)
 - Existing contracts under `.qfai/contracts/**`
 
 ## Deliverables (MANDATORY)

package/assets/init/.qfai/assistant/agents/design-owner.md

@@ -10,7 +10,8 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .qfai/require/require.md
+- .qfai/require/REQUIRE-XXXX/\* (preferred)
+- .qfai/require/require.md (legacy compatibility)
 - Evidence summaries under `.qfai/evidence/` (gitignored)
 
 ## Deliverables (MANDATORY)

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

@@ -10,8 +10,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- Existing discussion records under `.qfai/discussions/`
-- .qfai/require/require.md (if present)
+- Existing discussion records under `.qfai/discuss/`
+- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
+- .qfai/require/require.md (legacy compatibility)
 
 ## Deliverables (MANDATORY)
 

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

@@ -9,8 +9,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- Existing discussion records under `.qfai/discussions/`
-- .qfai/require/require.md (if present)
+- Existing discussion records under `.qfai/discuss/`
+- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
+- .qfai/require/require.md (legacy compatibility)
 
 ## Deliverables (MANDATORY)
 

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

@@ -9,11 +9,12 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/require/require.md (if present)
+- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
+- .qfai/require/require.md (legacy compatibility)
 - .qfai/specs/spec-\*/spec.md
 - .qfai/specs/spec-\*/delta.md (draft)
 - .qfai/contracts/\*\*
-- Existing discussion records under `.qfai/discussions/`
+- Existing discussion records under `.qfai/discuss/`
 
 ## Deliverables (MANDATORY)
 

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

@@ -9,12 +9,13 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/require/require.md (if present)
+- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
+- .qfai/require/require.md (legacy compatibility)
 - .qfai/require/open-questions.md (if present)
 - .qfai/specs/spec-\*/spec.md
 - .qfai/specs/spec-\*/delta.md
 - .qfai/contracts/\*\*
-- Existing discussion records under `.qfai/discussions/`
+- Existing discussion records under `.qfai/discuss/`
 
 ## Deliverables (MANDATORY)
 

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

@@ -12,7 +12,8 @@
 - .qfai/assistant/steering/test-layers.md (test-layer definitions + required coverage expectations)
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - OQ candidate list from OQ Harvester
-- .qfai/require/require.md (if present)
+- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
+- .qfai/require/require.md (legacy compatibility)
 - .qfai/require/open-questions.md (if present)
 - .qfai/specs/spec-\*/spec.md
 - .qfai/specs/spec-\*/delta.md

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

@@ -10,7 +10,8 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .qfai/require/require.md
+- .qfai/require/REQUIRE-XXXX/\* (preferred)
+- .qfai/require/require.md (legacy compatibility)
 - Existing constraints and gate commands
 
 ## Deliverables (MANDATORY)

package/assets/init/.qfai/assistant/agents/project-lead.md

@@ -9,7 +9,8 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/require/require.md
+- .qfai/require/REQUIRE-XXXX/\* (preferred)
+- .qfai/require/require.md (legacy compatibility)
 - .qfai/specs/spec-\*/spec.md
 - Evidence summaries under `.qfai/evidence/` (gitignored)
 

package/assets/init/.qfai/assistant/agents/requirements-analyst.md

@@ -9,8 +9,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/require/require.md (if present)
-- Discussion records under `.qfai/discussions/`
+- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
+- .qfai/require/require.md (legacy compatibility)
+- Discussion records under `.qfai/discuss/`
 - .qfai/specs/spec-\*/spec.md (if available)
 
 ## Deliverables (MANDATORY)

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

@@ -10,7 +10,7 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - User-provided idea/problem statement
-- Existing discussion records under `.qfai/discussions/`
+- Existing discussion records under `.qfai/discuss/`
 
 ## Deliverables (MANDATORY)
 

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

@@ -15,7 +15,7 @@ This document is the **decision rule SSOT** for AI and humans when answering:
 1. **Glossary** (`require/glossary.md`)
 2. **Actors** (`require/actors.md`)
 3. **Business flows** (`require/business-flows.md`)
-4. **Requirements** (`require/require.md`)
+4. **Requirements** (`require/REQUIRE-XXXX/*` preferred, `require/require.md` legacy compatibility)
 5. **Spec packs** (`specs/spec-*/spec.md`, `delta.md`, `scenario.feature`, `case-catalogue.md`, `traceability-matrix.md`)
 6. **ATDD / TDD** (tests + code)
 

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

@@ -57,7 +57,7 @@ Do not proceed without a declared Change Type.
 
 ### Stage 0 — Steering refresh contract (mandatory)
 
-At the beginning of each stage (`qfai-discuss`, `qfai-require`, `qfai-sdd-*`, `qfai-atdd`, `qfai-tdd-*`, `qfai-implement`, `qfai-verify`):
+At the beginning of each stage (`qfai-discuss`, `qfai-require`, `qfai-sdd`, `qfai-atdd`, `qfai-tdd-*`, `qfai-implement`, `qfai-verify`):
 
 1. Check these steering files:
    - `.qfai/assistant/steering/manifest.md`

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

@@ -153,7 +153,7 @@ Rules:
 - Do NOT declare completion based on unit/component tests.
 - `plan.md` is the primary How SSOT for execution phases.
 - `implementation-brief.md` is deprecated and must not be used as How SSOT.
-- If `plan.md` is missing, STOP and run `/qfai-sdd-planning` before proceeding.
+- If `plan.md` is missing, STOP and run `/qfai-sdd` before proceeding.
 - Acceptance tests must be runnable and Coverage Ledger must be 100% implemented (blocked/skipped require DR + approval).
 - You MUST evaluate layer floors as volume signals (E2E=SC count, API=endpoints, Integration=max(endpoints×K, ΣCASE)).
 - E2E=0 or Integration=0 is forbidden unless a DR + user approval + reviewer PASS explicitly allows it.
@@ -540,7 +540,7 @@ Read:
 
 - STOP and do not proceed with test implementation.
 - Inform the user that the spec pack must be split or fixed.
-- Recommend running `/qfai-sdd-refinement` (and `/qfai-sdd-planning` when How must change) to adjust the spec packs.
+- Recommend running `/qfai-sdd` to adjust the spec packs.
 
 **Rationale:** QFAI validate rules require unique SC tags per file, and large scenario counts should be split to keep traceability clear.
 
@@ -692,3 +692,22 @@ When you declare DONE, include:
 - [ ] All mandatory checks were executed and recorded.
 - [ ] No untracked gaps remain (or they are explicitly documented).
 - [ ] Completion approved by a reviewer who did not implement the tests.
+
+## 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.
+
+- Proceed (recommended): `/qfai-tdd-red`.
+  Action: derive unit/component RED tests from acceptance scenarios.
+- Acceptance tests need fixes: rerun `/qfai-atdd`.
+  Action: correct scenario coverage gaps and rerun test evidence.
+- Implementation phase: `/qfai-tdd-green`.
+  Action: implement code to satisfy failing tests.

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

@@ -171,7 +171,7 @@ Before declaring completion, you MUST:
 
 Analyze the repository and update `qfai.config.yaml` so traceability checks are actionable, with a documented minimum runnable path.
 
-Note: /qfai-sdd-refinement includes a preflight step that bootstraps missing config/steering when run directly after init.
+Note: /qfai-sdd includes a preflight step that bootstraps missing config/steering when run directly after init.
 /qfai-configure remains the recommended way to tune `qfai.config.yaml` early with a clean, minimal diff.
 
 ## Success Criteria (Definition of Done)
@@ -452,3 +452,22 @@ When you declare DONE, include:
 - [ ] All mandatory checks were executed and recorded.
 - [ ] No untracked gaps remain (or they are explicitly documented).
 - [ ] Completion approved by a reviewer who did not modify the config.
+
+## 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.
+
+- Proceed (recommended): `/qfai-require`.
+  Action: run it to formalize requirements from the configured project context.
+- Requirements are still unclear: `/qfai-discuss`.
+  Action: collect missing scope, constraints, and assumptions first.
+- Configuration needs refinement: rerun `/qfai-configure`.
+  Action: provide additional include/exclude evidence and update `qfai.config.yaml`.