qfai 1.4.8 → 1.4.18

package/README.md

@@ -31,9 +31,9 @@ npx qfai report
 ## What you can do (CLI commands)
 
 - `npx qfai init`
-  - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit (`assistant/` with skills, instructions, agents, and steering templates), plus `qfai.config.yaml`.
+  - Creates the QFAI workspace under `.qfai/` (requirements/specs/status/contracts/report) and installs the AI assistant kit (`assistant/` with skills, instructions, agents, and steering templates), plus `qfai.config.yaml`.
 - `npx qfai validate`
-  - Validates specs/contracts/scenarios/traceability and writes `.qfai/report/validate.json`; use `--fail-on error` (or `--fail-on warning`) to turn it into a CI gate, and `--format github` to emit GitHub-friendly annotations. Use `--phase refinement` only for local refinement checks; CI should use default/full validation.
+  - Validates specs/contracts/scenarios/traceability and review gate artifacts (`.qfai/review/**/summary.json`), then writes `.qfai/report/validate.json`; use `--fail-on error` (or `--fail-on warning`) to turn it into a CI gate, and `--format github` to emit GitHub-friendly annotations. Use `--phase refinement` only for local refinement checks; CI should use default/full validation.
 - `npx qfai report`
   - Produces a human-readable report (`report.md` by default) or an internal JSON export (`report.json`) from `validate.json`; use `--base-url` to link file paths in Markdown to your repository viewer.
 - `npx qfai doctor`
@@ -56,8 +56,10 @@ 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-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-require**: Produce `01_sources.md`, `02_requirement-index.md`, and `03_open-questions.md` under `.qfai/require/require-<ts>/` from your idea or discussion output.
+- **qfai-sdd**: Unified SDD entrypoint with preflight mode selection (`specs-first` / `require-indexed` / `import-lite` / `interview-start`).
+- **qfai-sdd-refinement**: Build `_shared` + `spec-XXXX/01..06` from the selected preflight mode.
+- **qfai-sdd-planning**: Finalize `plan.md` and `spec-XXXX/10_Plan`; if specs are missing, redirect to refinement.
 - **qfai-prototyping**: Build a contract-aligned skeleton implementation before deep coding.
 - **qfai-atdd**: Implement acceptance tests driven by specs/scenarios.
 - **qfai-tdd-red**: Add failing unit/component tests from the approved acceptance scenarios.
@@ -87,18 +89,23 @@ AG-->>U: Config tuned to this repo
 
 opt If you only have an idea
 U->>AG: Run /qfai-discuss
-AG-->>U: Structured discuss package (.qfai/discuss/DISCUSS-XXXX/)
+AG-->>U: Structured discuss package (.qfai/discuss/discuss-<ts>/)
 end
 
 U->>AG: Run /qfai-require
 AG->>Q: Read .qfai/assistant/skills/qfai-require/SKILL.md
-AG->>R: Create/Update REQUIRE-XXXX package docs
-AG-->>U: Requirement package ready
+AG->>R: Create/Update require index docs under require-<ts> (01_sources/02_requirement-index/03_open-questions)
+AG-->>U: Requirement index 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-sdd-refinement (or /qfai-sdd)
+AG->>Q: Read .qfai/assistant/skills/qfai-sdd-refinement/SKILL.md
+AG->>R: Preflight + create/refine _shared + spec-XXXX/01..06
+AG-->>U: Refinement artifacts ready
+
+U->>AG: Run /qfai-sdd-planning
+AG->>Q: Read .qfai/assistant/skills/qfai-sdd-planning/SKILL.md
+AG->>R: Finalize plan.md + spec-XXXX/10_Plan (+ delta updates)
+AG-->>U: Planning artifacts ready
 
 U->>AG: Run /qfai-prototyping
 AG->>Q: Read .qfai/assistant/skills/qfai-prototyping/SKILL.md
@@ -146,6 +153,7 @@ Operational notes.
 - 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 `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).
+- Review gate policies (required/optional layers and reviewers) are defined in `.qfai/assistant/steering/review-gate.rules.yml`.
 
 ## Configuration
 
@@ -207,18 +215,19 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.4.8)
+## Minimal tutorial (v1.4.18)
 
 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`.
+3. Run `/qfai-require` to produce require index files (`01_sources`, `02_requirement-index`, `03_open-questions`) under `.qfai/require/require-<ts>/`.
+4. Run `/qfai-sdd` (or `/qfai-sdd-refinement` -> `/qfai-sdd-planning`) to build layered specs and finalized plans.
+5. For each completed layer gate, generate review artifacts under `.qfai/review/<scope>/<layer>/attempt-<NN>/`.
+6. 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.
+- Release gate: set `release_candidate: true` in `.qfai/status/*.json` (for example, `release.json`); open OQ then becomes error.
 
 ## FAQ
 
@@ -229,11 +238,13 @@ Release gate behavior:
 - 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.
+  - A: Keep specs definition-only, then update status in `.qfai/status/*.json` and convert open OQ to `resolved` or `deferred` with evidence.
 
 ## Continuous integration
 
-QFAI v1.4.8 no longer generates `.github/**` assets.
+QFAI v1.4.18 generates `.github/**` only for Copilot integration wrappers
+(`.github/prompts`, `.github/agents`).
+It does not generate GitHub Actions workflows.
 Configure CI in your own platform and run:
 
 ```bash
@@ -301,6 +312,10 @@ Typical customizations.
 │   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-sdd
 │   │   │   │   └── SKILL.md
+│   │   │   ├── qfai-sdd-refinement
+│   │   │   │   └── SKILL.md
+│   │   │   ├── qfai-sdd-planning
+│   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-atdd
 │   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-tdd-red
@@ -315,13 +330,14 @@ Typical customizations.
 │   │   │   └── README.md
 │   │   ├── steering
 │   │   │   ├── README.md
+│   │   │   ├── review-gate.rules.yml
 │   │   │   ├── product.md
 │   │   │   ├── structure.md
 │   │   │   └── tech.md
 │   │   └── README.md
 │   ├── discuss
 │   │   ├── README.md
-│   │   └── DISCUSS-0001
+│   │   └── discuss-20260215205220203
 │   │       ├── 00_Summary.md
 │   │       ├── ...
 │   │       └── 07_Open-questions.md
@@ -337,10 +353,14 @@ Typical customizations.
 │   │   └── README.md
 │   ├── require
 │   │   ├── README.md
-│   │   ├── REQUIRE-0001
-│   │   │   ├── 00_Summary.md
-│   │   │   ├── ...
-│   │   │   └── 07_Open-questions.md
+│   │   └── require-20260215205220203
+│   │       ├── 01_sources.md
+│   │       ├── 02_requirement-index.md
+│   │       └── 03_open-questions.md
+│   ├── review
+│   │   └── README.md
+│   ├── status
+│   │   ├── .gitignore
 │   │   └── README.md
 │   ├── specs
 │   │   └── README.md
@@ -348,10 +368,17 @@ Typical customizations.
 └── qfai.config.yaml
 ```
 
+Integration wrappers are also generated for immediate use:
+
+- Claude Code: `.claude/commands/**`, `.claude/agents/**`
+- GitHub Copilot: `.github/prompts/**`, `.github/agents/**`
+- Codex: `.codex/skills/**`
+
 ## Agent integrations
 
-`npx qfai init` installs only canonical skills under `.qfai/assistant/skills/**`.
-If your toolchain needs wrapper files, manage them in your own repository convention and keep `.qfai/assistant/skills/**` as SSOT.
+`npx qfai init` installs canonical skills under `.qfai/assistant/skills/**` (SSOT)
+and generates thin wrapper assets for Copilot / Claude Code / Codex.
+If wrapper assets drift from canonical skills, rerun `npx qfai init --force` to resync.
 
 ## Contributing (for QFAI maintainers)
 

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

@@ -15,12 +15,13 @@ This folder is generated by `qfai init` and designed to be:
 ```mermaid
 flowchart TD
   A[/qfai-discuss/] --> B[/qfai-require/]
-  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/]
+  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/]
 ```
 
 > Formatting must follow the templates and checklists documented in each directory README.
@@ -39,7 +40,18 @@ flowchart TD
 │   ├── steering/             # project steering inputs
 │   └── instructions/         # workflow and guardrail docs
 ├── require/
+│   ├── README.md
+│   └── require-YYYYMMDDhhmmssSSS/
+│       ├── 01_sources.md
+│       ├── 02_requirement-index.md
+│       └── 03_open-questions.md
+├── report/
+│   └── README.md
+├── review/
 │   └── README.md
+├── status/
+│   ├── README.md
+│   └── .gitignore
 ├── contracts/
 │   ├── README.md
 │   ├── api/
@@ -79,15 +91,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. Spec Pack 01..18 is runtime SSOT
+### R4. Layered specs are runtime SSOT
 
-- Runtime validators and downstream skills consume `01_*` to `18_*`.
-- Traceability links are written in `16_Traceability-ledger.md`.
+- Runtime validators and downstream skills consume `_shared/**` and `spec-XXXX/**`.
+- Split rule is fixed: `1 CAP = 1 spec`.
+- Parent chain is fixed: `US -> CAP`, `AC -> US`, `BR -> AC`, `EX -> BR|AC`, `TC -> EX`.
 - Derived outputs under `.qfai/report/**` are non-SSOT.
 
 ### R5. init is an empty scaffold
 
-- `qfai init` creates README-centric directories for `discuss`, `require`, `contracts`, and `specs`.
+- `qfai init` creates README-centric directories for `discuss`, `require`, `report`, `status`, `contracts`, and `specs`.
 - Sample artifacts are provided under skill templates (for example, `assistant/skills/qfai-sdd/templates/contracts/`).
 
 ## Skills (SSOT)
@@ -98,7 +111,8 @@ Invoke canonical skills from this tree directly.
 ## Where to look next
 
 - Requirements format: `require/README.md`
+- Review gate format: `review/README.md`
 - Contracts format: `contracts/README.md` and child READMEs
-- Spec pack format: `specs/README.md`
+- Layered spec format: `specs/README.md`
 - Change classification: `assistant/instructions/change-classification.md`
 - Evidence rules: `evidence/README.md`

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

@@ -11,8 +11,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .qfai/require/REQUIRE-XXXX/\* (preferred)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 - Existing architecture docs (if any)
 
 ## Deliverables (MANDATORY)

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

@@ -11,8 +11,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .qfai/require/REQUIRE-XXXX/\* (preferred)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 - Existing contracts under `.qfai/contracts/**`
 
 ## Deliverables (MANDATORY)

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

@@ -10,8 +10,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .qfai/require/REQUIRE-XXXX/\* (preferred)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 - Evidence summaries under `.qfai/evidence/` (gitignored)
 
 ## Deliverables (MANDATORY)

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

@@ -11,8 +11,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - Existing discussion records under `.qfai/discuss/`
-- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 
 ## Deliverables (MANDATORY)
 

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

@@ -10,8 +10,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - Existing discussion records under `.qfai/discuss/`
-- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 
 ## Deliverables (MANDATORY)
 

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

@@ -9,8 +9,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 - .qfai/specs/spec-\*/spec.md
 - .qfai/specs/spec-\*/delta.md (draft)
 - .qfai/contracts/\*\*

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

@@ -9,8 +9,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/require/REQUIRE-XXXX/\* (preferred if present)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 - .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,8 +12,9 @@
 - .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-XXXX/\* (preferred if present)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 - .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,8 +10,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .qfai/require/REQUIRE-XXXX/\* (preferred)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 - Existing constraints and gate commands
 
 ## Deliverables (MANDATORY)

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

@@ -9,8 +9,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/require/REQUIRE-XXXX/\* (preferred)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 - .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-XXXX/\* (preferred if present)
-- .qfai/require/require.md (legacy compatibility)
+- .qfai/require/require-\*/01_sources.md
+- .qfai/require/require-\*/02_requirement-index.md
+- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
 - Discussion records under `.qfai/discuss/`
 - .qfai/specs/spec-\*/spec.md (if available)
 

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

@@ -2,74 +2,58 @@
 
 ## Purpose
 
-Define a **repeatable decomposition** from top-level domain context to requirements, specs, and tests.
+Define a repeatable decomposition from external requirement sources to layered specs and tests.
 
-This document is the **decision rule SSOT** for AI and humans when answering:
+This document is the decision rule SSOT for AI and humans when answering:
 
-- "What is the top-level structure?"
-- "How do we break down work into spec packs?"
-- "How do we keep traceability stable?"
+- What inputs are required before SDD starts?
+- How should capabilities be split into spec directories?
+- How is traceability kept stable?
 
 ## Canonical order (top -> down)
 
-1. **Glossary** (`require/glossary.md`)
-2. **Actors** (`require/actors.md`)
-3. **Business flows** (`require/business-flows.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`)
+1. **Source registry** (`require/require-*/01_sources.md`)
+2. **Requirement index** (`require/require-*/02_requirement-index.md`)
+3. **Input gaps / Open Questions** (`require/require-*/03_open-questions.md`)
+4. **Shared specs** (`specs/_shared/01..04`)
+5. **Capability slices** (`specs/spec-*/01..05` minimum)
 6. **ATDD / TDD** (tests + code)
 
 ## Decision rules
 
-### Rule 1 - Always anchor scope to Business Flow steps
+### Rule 1 - Start from source-backed inputs
 
-- A spec pack MUST be a slice of **one or more BF steps**.
-- If a BF step is in scope, it MUST be covered by:
-  - a requirement (`REQ-*`) and/or
-  - a spec pack (`spec-*`) and/or
-  - an explicit Out-of-scope row in the Coverage Map.
+- Every requirement index row must point to source IDs (`SRC-XXXX`).
+- If source linkage is missing, stop and create an Open Question.
 
-### Rule 2 - Use actors to remove ambiguity
+### Rule 2 - Preserve layered ownership
 
-When writing requirements/specs/scenarios, explicitly name:
+- `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/`.
 
-- the primary actor who initiates the interaction
-- any supporting actors (external services, humans, systems)
+### Rule 3 - Keep ambiguity explicit
 
-If an actor is missing, add it to `actors.md` before proceeding.
+- Unknowns remain explicit as Open Questions.
+- Resolved answers are promoted to `_shared` or `spec-XXXX` artifacts, then OQ status is updated.
 
-### Rule 3 - Keep Glossary small but authoritative
+## How to decompose (mechanical procedure)
 
-- Add terms only if they reduce ambiguity or avoid inconsistent naming.
-- Prefer **one term** with synonyms over multiple near-duplicate terms.
-- When a term changes meaning, record the decision in a discussion log.
+1. Register source documents and assumptions in `require-*/01_sources.md`.
+2. Extract concise requirement index entries in `require-*/02_requirement-index.md`.
+3. Capture missing information in `require-*/03_open-questions.md`.
+4. Build `_shared` 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.
 
-## How to decompose (mechanical procedure)
+## Example
 
-1. Draft **Actors** (Primary / Supporting / System).
-2. Draft **Business Flow backbone**:
-   - 5-15 steps per flow is a useful target.
-   - Each step should be a verb phrase and observable.
-3. For each in-scope BF step, draft:
-   - a candidate user story (optional; can remain implicit)
-   - one or more atomic **REQ-FUNC** items (EARS style recommended)
-   - any **REQ-NFR** needed for the step
-4. Group BF steps into spec packs:
-   - Aim for 1-3 scenarios per spec pack.
-   - Split when scenarios exceed that or when the slice spans multiple distinct user goals.
-5. In each spec pack:
-   - Reference BF step IDs and actor IDs in `spec.md` Context.
-   - Ensure traceability matrix includes BF step IDs.
-
-## Examples
-
-### Example: One BF step -> one spec pack
-
-- BF step: `BF-0003-S02 User submits validation request`
-- Spec pack: `spec-0012`
-  - Context: Actor `ACT-0001 Developer`
-  - Traceability: `BF-0003-S02 -> REQ-FUNC-0044 -> spec-0012 -> SC-0012-01`
+- Requirement index entry: `REQ-0003` linked to `SRC-0002`
+- Capability mapping: `CAP-0003` in `_shared/03_Capabilities.md`
+- Spec slice: `spec-0003/01_Spec.md` through `06_Test-cases.md`
 
 ## Non-goals
 
-- BPMN diagrams are NOT required (text-first). If you add diagrams, they are optional evidence, not SSOT.
+- Managing release status flags in specs.
+- Keeping full requirement prose in `require/`.
+- Treating diagrams as mandatory at require stage.

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

@@ -49,15 +49,16 @@ Do not proceed without a declared Change Type.
 0. Steering refresh (project memory bootstrap)
 1. Discussion (optional): clarify idea → requirement seed
 2. Requirements: requirements document in `.qfai/require/`
-3. Specification (SDD): `.qfai/specs/spec-XXXX/`
-4. Prototyping (optional): contract-aligned implementation skeleton
-5. Scenario tests (ATDD): runnable scenario tests derived from `scenario.feature`
-6. TDD: red/green/refactor loop enforcing spec + tests
-7. Verify: run quality gates and provide evidence
+3. Specification refinement (SDD): preflight + `_shared` / `spec-XXXX/01..06`
+4. Specification planning (SDD): `plan.md` + `spec-XXXX/10_Plan.md`
+5. Prototyping (optional): contract-aligned implementation skeleton
+6. Scenario tests (ATDD): runnable scenario tests derived from `scenario.feature`
+7. TDD: red/green/refactor loop enforcing spec + tests
+8. Verify: run quality gates and provide evidence
 
 ### Stage 0 — Steering refresh contract (mandatory)
 
-At the beginning of each stage (`qfai-discuss`, `qfai-require`, `qfai-sdd`, `qfai-prototyping`, `qfai-atdd`, `qfai-tdd-*`, `qfai-verify`):
+At the beginning of each stage (`qfai-discuss`, `qfai-require`, `qfai-sdd`, `qfai-sdd-refinement`, `qfai-sdd-planning`, `qfai-prototyping`, `qfai-atdd`, `qfai-tdd-*`, `qfai-verify`):
 
 1. Check these steering files:
    - `.qfai/assistant/steering/manifest.md`