qfai 1.3.19 → 1.4.4

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
@@ -134,8 +128,8 @@ Operational notes.
 - Each custom skill must output in the user’s language (absolute requirement).
 - 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 +177,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.4)
+
+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 +269,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 +330,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 +348,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

@@ -2,76 +2,81 @@
 
 ## Purpose
 
-`.qfai/` is the **single workspace** for QFAI artifacts so that requirements, contracts, spec packs, and automation stay aligned and traceable.
+`.qfai/` is the single workspace for QFAI artifacts so requirements, contracts, spec packs, and automation stay aligned.
 
-This folder is generated by `qfai init`. It is designed to be:
+This folder is generated by `qfai init` and designed to be:
 
-- **predictable** (stable file layout),
-- **reviewable** (human-readable Markdown/YAML/SQL),
-- **machine-checkable** (validators enforce minimal structural rules).
+- predictable (stable layout),
+- reviewable (human-readable Markdown/YAML/SQL),
+- machine-checkable (validators enforce minimal structural rules).
 
 ## Recommended QFAI sequence (project)
 
 ```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 in each directory README.
-> Do not invent per-file formats.
-> Requirements decomposition starts from **Actors** and **Business Flows** in `require/`.
-> Keep `business-flows.md` as the top-level narrative backbone; derive REQ/SPEC/SCENARIO from BF steps.
+> Formatting must follow the templates and checklists documented in each directory README.
 
 ## Directory map
 
 ```text
 .qfai/
 ├── README.md
-├── discussions/
+├── discuss/
 │   ├── README.md
-│   └── discuss-0001-<topic>.md   # discussion log (decision/evidence)
+│   └── DISCUSS-0001/
+│       ├── 00_Summary.md
+│       ├── ...
+│       └── 07_Open-questions.md
+├── discussions/              # legacy compatibility
+│   └── README.md
 ├── assistant/
-│   ├── skills/             # canonical skills (SSOT)
-│   ├── skills.local/       # project-specific skill overrides
-│   ├── agents/             # sub-agent missions / guardrails
-│   ├── steering/           # project steering (inputs for skills, includes test-layers.md)
-│   └── instructions/       # tool/integration instructions (includes drift-protocol.md)
+│   ├── skills/               # canonical skills (SSOT)
+│   ├── skills.local/         # project-specific overrides
+│   ├── agents/               # sub-agent missions
+│   ├── steering/             # project steering inputs
+│   └── instructions/         # workflow and guardrail docs
 ├── require/
 │   ├── README.md
-│   ├── glossary.md         # terms (SSOT)
-│   ├── actors.md           # actor catalog (SSOT)
-│   ├── business-flows.md   # business flow catalog (SSOT)
-│   ├── require.md          # requirements (REQ-*) + BF coverage map
-│   └── open-questions.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
 ├── contracts/
 │   ├── README.md
-│   ├── api/README.md       # OpenAPI YAML style guide
-│   ├── db/README.md        # SQL contracts style guide
-│   └── ui/README.md        # UI contract YAML style guide
+│   ├── api/
+│   │   ├── README.md
+│   │   └── api-0001-sample.yaml
+│   ├── db/
+│   │   ├── README.md
+│   │   └── db-0001-sample.sql
+│   └── ui/
+│       ├── README.md
+│       └── ui-0001-sample.yaml
 ├── specs/
 │   ├── README.md
 │   └── spec-0001/
-│       ├── spec.md
-│       ├── delta.md
-│       ├── scenario.feature
-│       ├── case-catalogue.md
-│       ├── traceability-matrix.md
-│       └── plan.md
-├── templates/
-│   └── spec/
-│       ├── delta.md
-│       ├── plan.md
-│       └── implementation-brief.md  # deprecated migration stub (validation fails if used as How SSOT)
+│       ├── 01_Spec.md
+│       ├── 02_Objective.md
+│       ├── ...
+│       ├── 17_Plan.md
+│       └── 18_delta.md
 └── evidence/
     ├── README.md
-    └── <skill>-<run>.md    # completion evidence (gitignored by default)
+    └── <skill>-<run>.md
 ```
 
 ## Rules (global)
@@ -81,44 +86,37 @@ flowchart TD
 Each directory `README.md` defines:
 
 - required files,
-- canonical **template**,
-- realistic **sample**,
+- template expectations,
 - quality checklist,
 - anti-patterns.
 
-All custom skills must:
-
-1. read the relevant directory README(s),
-2. generate artifacts matching their templates,
-3. run a self-check before declaring completion.
+Custom skills should read relevant README files before writing artifacts.
 
 ### R2. Evidence is not versioned by default
 
-Evidence under `.qfai/evidence/` is **gitignored by default** (see repository `.gitignore` and/or project `.git/info/exclude`).
-
-- Evidence is still useful locally and in PR review (attach or paste snippets), but it should not pollute version control.
+Evidence under `.qfai/evidence/` is gitignored by default.
+It is useful for local review but should not pollute version control.
 
 ### R3. Keep artifacts atomic
 
-- Prefer many small, stable identifiers (REQ/BR/AC/CASE/SC) over long paragraphs that hide multiple rules.
-- If a statement contains multiple independent “must” clauses, split it.
+- Prefer small stable identifiers (REQ/BR/AC/TC/EX/etc.) over long mixed paragraphs.
+- If one line contains multiple independent constraints, split it.
 
-### R4. Do not put templates in skills
+### R4. Spec Pack 01..18 is runtime SSOT
 
-Templates/samples MUST live only in `.qfai/**/README.md`.
-Skills only **reference** them to avoid double maintenance.
+- 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.
 
 ## Skills (SSOT)
 
-QFAI also ships an **assistant skills** tree at `assistant/skills/`.
-
-`assistant/skills/**` is the canonical source of truth.
-Tool-specific wrappers (`.claude/skills`, `.github/skills`, `.codex/skills`) must point to this tree.
+`assistant/skills/**` is the canonical source.
+Tool-specific wrappers (`.claude/skills`, `.github/skills`, `.codex/skills`) should point to this tree.
 
 ## Where to look next
 
 - Requirements format: `require/README.md`
-- Contracts format: `contracts/README.md` and sub-READMEs
+- Contracts format: `contracts/README.md` and child READMEs
 - Spec pack format: `specs/README.md`
-- Change classification (Primary/Tags): `assistant/instructions/change-classification.md`
+- Change classification: `assistant/instructions/change-classification.md`
 - Evidence rules: `evidence/README.md`

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

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

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

@@ -10,7 +10,8 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - Existing discussion records under `.qfai/discussions/`
-- .qfai/require/require.md (if present)
+- .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,7 +9,8 @@
 - .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/\*\*

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

@@ -9,7 +9,8 @@
 - .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

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,7 +9,8 @@
 - .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)
 - Discussion records under `.qfai/discussions/`
 - .qfai/specs/spec-\*/spec.md (if available)
 

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.
 

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)