qfai 1.4.9 → 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.9)
+## 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,11 @@ 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.9 generates `.github/**` only for Copilot integration wrappers
+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:
@@ -303,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
@@ -317,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
@@ -339,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

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`

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

@@ -69,12 +69,12 @@ Every major artifact in this stage MUST include this table schema:
 
 ## CRITICAL CONSTRAINTS (Read First)
 
-- This skill optimizes interviews for layered Spec Pack inputs (OBJ/INIT/CAP/FLOW).
+- This skill optimizes interviews for layered spec inputs (OBJ/INIT/CAP/FLOW).
 - Execute interviews in two stages:
   - Stage A: Core interview (mandatory)
   - Stage B: Optional deep dive (triggered)
 - Output path:
-  - `.qfai/discuss/DISCUSS-XXXX/`
+  - `.qfai/discuss/discuss-YYYYMMDDhhmmssSSS/` (Asia/Tokyo)
 - Required files:
   - `00_Summary.md`
   - `01_Objective.md`
@@ -84,8 +84,13 @@ Every major artifact in this stage MUST include this table schema:
   - `05_Policy.md`
   - `06_Stakeholders.md`
   - `07_Open-questions.md`
+- Timestamp format is fixed to `YYYYMMDDhhmmssSSS` (3-digit milliseconds).
+- Legacy `DISCUSS-XXXX` directories are deprecated and may coexist, but new runs MUST use timestamp naming.
 - If user cannot answer, leave `TBD` and create/append an OQ in `07_Open-questions.md`.
 - Do NOT write lower-layer IDs (`AC-*`, `BR-*`, `EX-*`, `TC-*`) in discuss artifacts.
+- `04_Business-flow.md` must include at least one Mermaid `flowchart` or `sequenceDiagram`.
+- If diagrams are written, Mermaid syntax must be inside ` ```mermaid ` fences only.
+- Do not author Business Flow as Gherkin (`*Business-flow*.feature` is deprecated).
 
 ## Goal
 
@@ -98,14 +103,15 @@ Build high-quality interview outputs that can be directly consumed by `/qfai-sdd
 
 ## Mandatory Outputs
 
-- `.qfai/discuss/DISCUSS-XXXX/00_Summary.md`
-- `.qfai/discuss/DISCUSS-XXXX/01_Objective.md`
-- `.qfai/discuss/DISCUSS-XXXX/02_Initiative.md`
-- `.qfai/discuss/DISCUSS-XXXX/03_Capabilities.md`
-- `.qfai/discuss/DISCUSS-XXXX/04_Business-flow.md`
-- `.qfai/discuss/DISCUSS-XXXX/05_Policy.md`
-- `.qfai/discuss/DISCUSS-XXXX/06_Stakeholders.md`
-- `.qfai/discuss/DISCUSS-XXXX/07_Open-questions.md`
+- `.qfai/discuss/discuss-*/00_Summary.md`
+- `.qfai/discuss/discuss-*/01_Objective.md`
+- `.qfai/discuss/discuss-*/02_Initiative.md`
+- `.qfai/discuss/discuss-*/03_Capabilities.md`
+- `.qfai/discuss/discuss-*/04_Business-flow.md`
+- `.qfai/discuss/discuss-*/05_Policy.md`
+- `.qfai/discuss/discuss-*/06_Stakeholders.md`
+- `.qfai/discuss/discuss-*/07_Open-questions.md`
+- review artifacts under `.qfai/review/discuss-*/<layer>/attempt-*/`
 - Reviewer notes (`PASS` or `REVISE`).
 
 ## Core Interview Set (Mandatory)
@@ -140,11 +146,34 @@ Record trigger + rationale in `00_Summary.md`.
 - `01_Objective.md`: objective candidates (use `OBJ-CAND-XXXX` IDs only).
 - `02_Initiative.md`: initiative candidates (use `INIT-CAND-XXXX` IDs only).
 - `03_Capabilities.md`: capability candidates (use `CAP-CAND-XXXX` IDs only).
-- `04_Business-flow.md`: flow narrative and step structure (use `FLOW-CAND-XXXX` IDs only).
+- `04_Business-flow.md`: flow narrative + Mermaid diagram (`flowchart` or `sequenceDiagram`), use `FLOW-CAND-XXXX` IDs only.
 - `05_Policy.md`: decision policy, tie-breaks, emergency override.
 - `06_Stakeholders.md`: users/operators/approvers and responsibilities.
 - `07_Open-questions.md`: unresolved blockers and non-blockers.
 
+## Review Gate Artifacts (RCP)
+
+For each completed layer gate, create:
+
+- `.qfai/review/discuss-*/<layer>/attempt-*/review_request.md`
+- `.qfai/review/discuss-*/<layer>/attempt-*/R01_<reviewer>.md`, `R02_<reviewer>.md`, ...
+- `.qfai/review/discuss-*/<layer>/attempt-*/summary.json`
+
+Required discuss layer gates:
+
+- `objective`
+- `initiative`
+- `capabilities`
+- `business-flow`
+
+RCP rules:
+
+- Use `attempt-01` first, then increment when re-review is required.
+- Compute and store fingerprint (`sha256`) for layer input files in `summary.json`.
+- If any reviewer returns feedback, mark `changes_requested`, fix the layer, increment attempt, and restart reviewer sequence from the first reviewer.
+- `summary.json.aggregate.status` can be `fixed` only when all reviewers are `pass` and total feedback is `0`.
+- Use templates from `.qfai/assistant/skills/qfai-discuss/templates/review/`.
+
 ## Required Coverage Topics
 
 Before completion, confirm all are covered:
@@ -162,7 +191,7 @@ Discuss artifacts are inputs for refinement/planning, not spec outputs.
 Recommended references for `/qfai-sdd`:
 
 - discuss: `01_Objective.md`, `02_Initiative.md`, `03_Capabilities.md`, `04_Business-flow.md`, `05_Policy.md`
-- require: `01_Functional-requirements.md`, `02_Non-functional-requirements.md`, `03_Contracts-boundary.md`, `04_Data-and-glossary.md`, `05_Test-policy.md`
+- require: `require-*/01_sources.md`, `require-*/02_requirement-index.md`, `require-*/03_open-questions.md`
 
 ## Completion Contract (Shared)
 
@@ -175,7 +204,7 @@ Before declaring completion, you MUST:
 
 ## Evidence (MANDATORY)
 
-Create/update: `.qfai/evidence/discuss-DISCUSS-XXXX.md`
+Create/update: `.qfai/evidence/discuss-*.md`
 
 Required sections:
 
@@ -192,7 +221,7 @@ Required sections:
 
 When done, report:
 
-- generated discuss path (`.qfai/discuss/DISCUSS-XXXX/`)
+- generated discuss path (`.qfai/discuss/discuss-*/`)
 - unresolved OQ count
 - reviewer result
 - ready-for-next command (`/qfai-require`)
@@ -204,6 +233,9 @@ When done, report:
 - [ ] Optional deep dive ran only for triggered topics.
 - [ ] All `TBD` items are mirrored in `07_Open-questions.md`.
 - [ ] No lower-layer IDs (`AC/BR/EX/TC`) were written in discuss outputs.
+- [ ] Diagram blocks use ` ```mermaid ` only (no ` ```text ` or language-less fences).
+- [ ] `04_Business-flow.md` includes `flowchart` or `sequenceDiagram`.
+- [ ] Every Scenario in `05_Examples.feature` includes `# Parent:`.
 - [ ] Evidence file exists and includes Work Orders Summary + Reviewer result.
 - [ ] Reviewer returned `PASS`.
 
@@ -213,8 +245,16 @@ When done, report:
 - [ ] Optional deep dive was executed only when triggered (or explicitly marked as not needed).
 - [ ] Unresolved items were logged to `07_Open-questions.md`.
 - [ ] Discuss deliverables `00..07` were produced.
+- [ ] Mermaid fence rules were satisfied when diagrams were used.
 - [ ] The `/qfai-require` handoff sentence was shown as the final line in the user's language.
 
+## Review Cycle Checklist (MUST)
+
+- [ ] Review artifacts were generated for each required discuss layer gate.
+- [ ] All required reviewers completed their reviews for each attempt.
+- [ ] Any feedback triggered return, fix, attempt increment, and full re-review from the first reviewer.
+- [ ] `summary.json` is marked `fixed` only when all reviewers passed with zero feedback.
+
 ## Completion Message & Next Actions (MUST)
 
 You MUST end the user-facing output with a handoff sentence to `/qfai-require` in the active user language.