qfai 1.4.9 → 1.4.23

package/README.md

@@ -33,7 +33,7 @@ npx qfai report
 - `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`.
 - `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 artifacts (`.qfai/review/review-*/summary.json` + minimum schema), writes `.qfai/report/validate.json`, and appends run logs to `.qfai/report/run-*/`; 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,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-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 a fixed 9-file require-pack (`01_Sources.md`..`09_delta.md`) under `.qfai/require/require-<ts>/`.
+- **qfai-sdd**: Unified SDD entrypoint with require-pack preflight guard (missing/incomplete/blocking OQ causes stop + next action guidance).
+- **qfai-sdd-refinement / qfai-sdd-planning (deprecated wrappers)**: Legacy entrypoints that return a fixed deprecation notice and route to `/qfai-sdd` only (no direct artifact generation).
 - **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,17 +88,17 @@ 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-pack under require-<ts> (01_Sources..09_delta)
+AG-->>U: Require-pack 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->>R: Preflight + create/refine layered specs + finalize 10_Plan + delta
 AG-->>U: SDD artifacts ready
 
 U->>AG: Run /qfai-prototyping
@@ -146,6 +147,8 @@ 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`.
+- Review roster SSOT is defined in `.qfai/assistant/steering/review-roster.yml`.
 
 ## Configuration
 
@@ -176,7 +179,7 @@ validation:
 
 Notes.
 
-- `validate.json`, `report.json`, and `doctor.json` are internal exports and are not a stable external contract; prefer `report.md` for integrations that must survive tool upgrades.
+- `validate.json`, `report.json`, `doctor.json`, and `run-*` JSON logs are internal exports and are not a stable external contract; prefer `report.md` for integrations that must survive tool upgrades.
 - Scenario files are expected to use the Gherkin extension `*.feature` (not `*.md`).
 
 ## Specifications and contracts (SDD)
@@ -207,18 +210,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.23)
 
 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 a require pack (`01_Sources`..`09_delta`) under `.qfai/require/require-<ts>/`.
+4. Run `/qfai-sdd` to build layered specs and finalized plans.
+5. For each completed review cycle, append artifacts under `.qfai/review/review-<timestamp>/`.
+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 the Initiative layer (`03_Initiative.md`); open OQ then becomes error.
 
 ## FAQ
 
@@ -229,11 +233,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, use `.qfai/report/run-*` as execution logs, 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.23 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:
@@ -260,7 +264,7 @@ Waiver policy.
 Typical customizations.
 
 - Add a `doctor` step before validate if you want to fail fast on path/glob/config issues.
-- Publish `.qfai/report/validate.json` and `report.md` as CI artifacts.
+- Publish `.qfai/report/validate.json`, `report.md`, and relevant `.qfai/report/run-*/` logs as CI artifacts.
 
 ## Generated structure
 
@@ -303,6 +307,10 @@ Typical customizations.
 │   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-sdd
 │   │   │   │   └── SKILL.md
+│   │   │   ├── qfai-sdd-refinement  (deprecated wrapper)
+│   │   │   │   └── SKILL.md
+│   │   │   ├── qfai-sdd-planning    (deprecated wrapper)
+│   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-atdd
 │   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-tdd-red
@@ -315,18 +323,22 @@ Typical customizations.
 │   │   │       └── SKILL.md
 │   │   ├── skills.local
 │   │   │   └── README.md
+│   │   ├── templates
+│   │   │   └── rcp_footer.md
 │   │   ├── steering
 │   │   │   ├── README.md
+│   │   │   ├── review-gate.rules.yml
+│   │   │   ├── review-roster.yml
 │   │   │   ├── product.md
 │   │   │   ├── structure.md
 │   │   │   └── tech.md
 │   │   └── README.md
 │   ├── discuss
 │   │   ├── README.md
-│   │   └── DISCUSS-0001
-│   │       ├── 00_Summary.md
+│   │   └── discuss-20260215205220203
+│   │       ├── 01_Context.md
 │   │       ├── ...
-│   │       └── 07_Open-questions.md
+│   │       └── 09_delta.md
 │   ├── contracts
 │   │   ├── api
 │   │   │   └── README.md
@@ -336,13 +348,23 @@ Typical customizations.
 │   │   │   └── README.md
 │   │   └── README.md
 │   ├── report
-│   │   └── README.md
+│   │   ├── .gitignore
+│   │   ├── README.md
+│   │   └── run-20260218123456789
+│   │       ├── run.json
+│   │       ├── validator.json
+│   │       ├── traceability.json
+│   │       └── summary.md
 │   ├── require
 │   │   ├── README.md
-│   │   ├── REQUIRE-0001
-│   │   │   ├── 00_Summary.md
-│   │   │   ├── ...
-│   │   │   └── 07_Open-questions.md
+│   │   └── require-20260215205220203
+│   │       ├── 01_Sources.md
+│   │       ├── 02_Scope.md
+│   │       ├── 03_REQ.md
+│   │       ├── ...
+│   │       └── 09_delta.md
+│   ├── review
+│   │   ├── .gitignore
 │   │   └── README.md
 │   ├── specs
 │   │   └── README.md

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

@@ -24,6 +24,7 @@ flowchart TD
 ```
 
 > Formatting must follow the templates and checklists documented in each directory README.
+> Legacy wrappers `/qfai-sdd-refinement` and `/qfai-sdd-planning` are deprecated and route to `/qfai-sdd`.
 
 ## Directory map
 
@@ -36,9 +37,26 @@ flowchart TD
 │   ├── skills/               # canonical skills (SSOT)
 │   ├── skills.local/         # project-specific overrides
 │   ├── agents/               # sub-agent missions
-│   ├── steering/             # project steering inputs
+│   ├── templates/            # shared assistant templates (RCP footer SSOT)
+│   ├── steering/             # project steering inputs and review roster
 │   └── instructions/         # workflow and guardrail docs
 ├── require/
+│   ├── README.md
+│   └── require-YYYYMMDDhhmmssSSS/
+│       ├── 01_Sources.md
+│       ├── 02_Scope.md
+│       ├── 03_REQ.md
+│       ├── 04_NFR.md
+│       ├── 05_Glossary.md
+│       ├── 06_Constraints.md
+│       ├── 07_Policy.md
+│       ├── 08_OQ.md
+│       └── 09_delta.md
+├── report/
+│   ├── .gitignore
+│   └── README.md
+├── review/
+│   ├── .gitignore
 │   └── README.md
 ├── contracts/
 │   ├── README.md
@@ -79,15 +97,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`, `contracts`, and `specs`.
 - Sample artifacts are provided under skill templates (for example, `assistant/skills/qfai-sdd/templates/contracts/`).
 
 ## Skills (SSOT)
@@ -98,7 +117,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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-\*/03_REQ.md
+- .qfai/require/require-\*/08_OQ.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-*/03_REQ.md`)
+3. **Input gaps / Open Questions** (`require/require-*/08_OQ.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-*/03_REQ.md`.
+3. Capture missing information in `require-*/08_OQ.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): `spec-XXXX/10_Plan.md` (How-only)
+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/manifest/spec_required_files.json

@@ -0,0 +1,25 @@
+{
+  "spec_dir": [
+    "01_Spec.md",
+    "02_User-stories.md",
+    "03_Acceptance-Criteria.md",
+    "04_Business-Rules.md",
+    "05_Examples.md",
+    "06_Test-Cases.md",
+    "07_Decisions.md",
+    "08_Open-questions.md",
+    "09_delta.md"
+  ],
+  "shared_dir": [
+    "01_Objective.md",
+    "02_Initiative.md",
+    "03_Capabilities.md",
+    "04_Business-Flow.md",
+    "05_Contracts.md",
+    "06_Glossary.md",
+    "07_Constraints.md",
+    "08_Decisions.md",
+    "09_Open-questions.md",
+    "10_delta.md"
+  ]
+}