qfai 1.4.18 → 1.4.23

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/status/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/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 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.
+  - 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,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 `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-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.
@@ -94,18 +93,13 @@ end
 
 U->>AG: Run /qfai-require
 AG->>Q: Read .qfai/assistant/skills/qfai-require/SKILL.md
-AG->>R: Create/Update require index docs under require-<ts> (01_sources/02_requirement-index/03_open-questions)
-AG-->>U: Requirement index ready
+AG->>R: Create/Update require-pack under require-<ts> (01_Sources..09_delta)
+AG-->>U: Require-pack 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-sdd
+AG->>Q: Read .qfai/assistant/skills/qfai-sdd/SKILL.md
+AG->>R: Preflight + create/refine layered specs + finalize 10_Plan + delta
+AG-->>U: SDD artifacts ready
 
 U->>AG: Run /qfai-prototyping
 AG->>Q: Read .qfai/assistant/skills/qfai-prototyping/SKILL.md
@@ -154,6 +148,7 @@ Operational notes.
 - 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
 
@@ -184,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)
@@ -215,19 +210,19 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.4.18)
+## 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 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>/`.
+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 `.qfai/status/*.json` (for example, `release.json`); open OQ then becomes error.
+- Release gate: set `release_candidate: true` in the Initiative layer (`03_Initiative.md`); open OQ then becomes error.
 
 ## FAQ
 
@@ -238,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: Keep specs definition-only, then update status in `.qfai/status/*.json` and convert open OQ to `resolved` or `deferred` with 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.18 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:
@@ -269,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
 
@@ -312,9 +307,9 @@ Typical customizations.
 │   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-sdd
 │   │   │   │   └── SKILL.md
-│   │   │   ├── qfai-sdd-refinement
+│   │   │   ├── qfai-sdd-refinement  (deprecated wrapper)
 │   │   │   │   └── SKILL.md
-│   │   │   ├── qfai-sdd-planning
+│   │   │   ├── qfai-sdd-planning    (deprecated wrapper)
 │   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-atdd
 │   │   │   │   └── SKILL.md
@@ -328,9 +323,12 @@ 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
@@ -338,9 +336,9 @@ Typical customizations.
 │   ├── discuss
 │   │   ├── README.md
 │   │   └── discuss-20260215205220203
-│   │       ├── 00_Summary.md
+│   │       ├── 01_Context.md
 │   │       ├── ...
-│   │       └── 07_Open-questions.md
+│   │       └── 09_delta.md
 │   ├── contracts
 │   │   ├── api
 │   │   │   └── README.md
@@ -350,16 +348,22 @@ 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-20260215205220203
-│   │       ├── 01_sources.md
-│   │       ├── 02_requirement-index.md
-│   │       └── 03_open-questions.md
+│   │       ├── 01_Sources.md
+│   │       ├── 02_Scope.md
+│   │       ├── 03_REQ.md
+│   │       ├── ...
+│   │       └── 09_delta.md
 │   ├── review
-│   │   └── README.md
-│   ├── status
 │   │   ├── .gitignore
 │   │   └── README.md
 │   ├── specs

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

@@ -15,16 +15,16 @@ This folder is generated by `qfai init` and designed to be:
 ```mermaid
 flowchart TD
   A[/qfai-discuss/] --> B[/qfai-require/]
-  B --> C[/qfai-sdd-refinement/]
-  C --> D[/qfai-sdd-planning/]
-  D --> E[/qfai-prototyping/]
-  E --> F[/qfai-atdd/]
-  F --> G[/qfai-tdd-red/]
-  G --> H[/qfai-tdd-green/]
-  H --> I[/qfai-tdd-refactor/]
+  B --> C[/qfai-sdd/]
+  C --> D[/qfai-prototyping/]
+  D --> E[/qfai-atdd/]
+  E --> F[/qfai-tdd-red/]
+  F --> G[/qfai-tdd-green/]
+  G --> H[/qfai-tdd-refactor/]
 ```
 
 > Formatting must follow the templates and checklists documented in each directory README.
+> Legacy wrappers `/qfai-sdd-refinement` and `/qfai-sdd-planning` are deprecated and route to `/qfai-sdd`.
 
 ## Directory map
 
@@ -37,21 +37,27 @@ 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_requirement-index.md
-│       └── 03_open-questions.md
+│       ├── 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
-├── status/
-│   ├── README.md
-│   └── .gitignore
 ├── contracts/
 │   ├── README.md
 │   ├── api/
@@ -100,7 +106,7 @@ It is useful for local review but should not pollute version control.
 
 ### R5. init is an empty scaffold
 
-- `qfai init` creates README-centric directories for `discuss`, `require`, `report`, `status`, `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)

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

@@ -11,9 +11,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .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/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,9 +11,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .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/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,9 +10,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .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/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,9 +11,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - Existing discussion records under `.qfai/discuss/`
-- .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/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,9 +10,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - Existing discussion records under `.qfai/discuss/`
-- .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/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,9 +9,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .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/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,9 +9,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .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/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,9 +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-\*/01_sources.md
-- .qfai/require/require-\*/02_requirement-index.md
-- .qfai/require/require-\*/03_open-questions.md (input gaps ledger)
+- .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,9 +10,9 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/specs/spec-\*/spec.md
-- .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/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,9 +9,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .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/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,9 +9,9 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .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/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

@@ -12,9 +12,9 @@ This document is the decision rule SSOT for AI and humans when answering:
 
 ## Canonical order (top -> down)
 
-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`)
+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)
@@ -39,9 +39,9 @@ This document is the decision rule SSOT for AI and humans when answering:
 
 ## How to decompose (mechanical procedure)
 
-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`.
+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.
@@ -50,7 +50,7 @@ This document is the decision rule SSOT for AI and humans when answering:
 
 - 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`
+- Spec slice: `spec-0003/01_Spec.md` through `06_Test-Cases.md`
 
 ## Non-goals
 

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

@@ -50,7 +50,7 @@ Do not proceed without a declared Change Type.
 1. Discussion (optional): clarify idea → requirement seed
 2. Requirements: requirements document in `.qfai/require/`
 3. Specification refinement (SDD): preflight + `_shared` / `spec-XXXX/01..06`
-4. Specification planning (SDD): `plan.md` + `spec-XXXX/10_Plan.md`
+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

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"
+  ]
+}