qfai 1.3.18 → 1.4.0

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

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

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

@@ -152,8 +152,8 @@ Rules:
 
 - Do NOT declare completion based on unit/component tests.
 - `plan.md` is the primary How SSOT for execution phases.
-- If only legacy `implementation-brief.md` exists, continue with warning and create a migration task to `plan.md`.
-- If both `plan.md` and legacy `implementation-brief.md` are missing, STOP and run `/qfai-sdd-planning`.
+- `implementation-brief.md` is deprecated and must not be used as How SSOT.
+- If `plan.md` is missing, STOP and run `/qfai-sdd-planning` before proceeding.
 - Acceptance tests must be runnable and Coverage Ledger must be 100% implemented (blocked/skipped require DR + approval).
 - You MUST evaluate layer floors as volume signals (E2E=SC count, API=endpoints, Integration=max(endpoints×K, ΣCASE)).
 - E2E=0 or Integration=0 is forbidden unless a DR + user approval + reviewer PASS explicitly allows it.

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

@@ -157,8 +157,8 @@ Rules:
 
 - This is a legacy entrypoint. You MUST follow `.qfai/assistant/skills/qfai-tdd-green/SKILL.md`.
 - `plan.md` is the primary How SSOT for execution phases.
-- If only legacy `implementation-brief.md` exists, continue with warning and create a migration task to `plan.md`.
-- If both `plan.md` and legacy `implementation-brief.md` are missing, STOP and run `/qfai-sdd-planning`.
+- `implementation-brief.md` is deprecated and must not be used as How SSOT.
+- If `plan.md` is missing, STOP and run `/qfai-sdd-planning` before proceeding.
 - Do NOT write new tests here (use `/qfai-tdd-red` or `/qfai-unit-test`, and `/qfai-atdd` when needed).
 - You MUST produce the required evidence file: `.qfai/evidence/tdd-green-<spec-id>.md`.
 - If refactoring is required, run `/qfai-tdd-refactor` and record `.qfai/evidence/tdd-refactor-<spec-id>.md`.

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

@@ -159,8 +159,8 @@ Rules:
 
 - Do NOT implement acceptance tests or unit tests (that is `/qfai-atdd` and TDD phases).
 - If `plan.md` exists, you MUST follow it as implementation constraints.
-- If only legacy `implementation-brief.md` exists, continue with warning and create a migration task to `plan.md`.
-- If both `plan.md` and legacy `implementation-brief.md` are missing, exploratory prototyping is allowed, but you MUST run `/qfai-sdd-planning` before downstream execution phases.
+- `implementation-brief.md` is deprecated and must not be used as How SSOT.
+- If `plan.md` is missing, STOP and run `/qfai-sdd-planning` before proceeding.
 - You MUST produce the required evidence file: `.qfai/evidence/prototyping-<spec-id>.md`.
   - `.qfai/evidence/` is intentionally NOT tracked by Git (it ships with a local `.gitignore`).
   - Do NOT commit evidence files; summarize key outcomes in the PR description instead.

package/assets/init/.qfai/assistant/skills/qfai-sdd-planning/SKILL.md

@@ -8,7 +8,7 @@ QFAI Skill Body (SSOT)
 
 name: qfai-sdd-planning
 title: QFAI SDD Planning (How SSOT)
-description: "Create plan.md and lock implementation constraints for downstream execution phases."
+description: "Create plan.md and lock implementation constraints for downstream execution phases (optionally mirror to 17_Plan.md)."
 argument-hint: "<spec-id-or-name> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
 roles: [Planner, Architect, QAEngineer, CodeReviewer]
@@ -35,7 +35,7 @@ When unsure, read inputs in this order:
 - P1: `.qfai/assistant/instructions/*`
 - P2: `.qfai/assistant/steering/*`
 - P3: `.qfai/specs/<spec-id>/delta.md`
-- P4: `.qfai/specs/<spec-id>/spec.md`, `scenario.feature`, contracts
+- P4: `.qfai/specs/<spec-id>/spec.md`, `scenario.feature`, `01_Spec.md`, `06_User-stories.md`, `09_Examples.feature`, `16_Traceability-ledger.md`, contracts
 
 ## Sub-agent Delegation (MANDATORY)
 
@@ -142,15 +142,25 @@ Rules:
 
 ## Delta Rejected Guard (Mandatory)
 
-- Do NOT reintroduce options marked as rejected in delta.md.
+- Do NOT reintroduce options marked as rejected in `delta.md`.
 - If planning must revisit a rejected option, add a `[RE-OPEN]` decision record with explicit approval evidence.
 
+## Workflow Convention (Mandatory)
+
+- Planning owns `plan.md` as runtime How SSOT; `17_Plan.md` is an optional layered mirror.
+- Finalize plan details after at least one user-story slice is grounded in refinement outputs.
+- Keep planning aligned with lower-to-upper reference direction and `@layer-*` policy from `steering/test-layers.md`.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - This phase MUST create or update:
   - `.qfai/specs/spec-XXXX/plan.md`
 - The plan is the How SSOT and must be concise, explicit, and implementation-binding.
-- Required headings must exist in fixed order:
+- Use the runtime template as primary:
+  - `.qfai/templates/spec/plan.md`
+- If layered mode is enabled, keep this optional mirror synchronized:
+  - `.qfai/specs/spec-XXXX/17_Plan.md`
+- Required `plan.md` headings must exist in fixed order:
   1. `Metadata`
   2. `Context & Scope`
   3. `Goals / Non-goals`
@@ -160,11 +170,9 @@ Rules:
   7. `Risks & Mitigations`
   8. `Open Questions / Blockers`
   9. `Done Checklist`
-- `Open Questions / Blockers` should finish with blockers resolved by default.
-- Planning decisions should be appended to delta as `DR-HOW-*` entries when strategy changes.
-- You MUST run full validation:
-  - `qfai validate --fail-on error`
-- CI validation must remain default/full. Do NOT switch CI gates to `--phase refinement`.
+- `Open Questions / Blockers` should end with no unresolved blockers by default.
+- Planning decisions should be appended to `delta.md` when strategy changes.
+- Run full validation after planning updates.
 - Completion must be approved by a reviewer who did not author the plan.
 
 ## Completion Contract (Shared)
@@ -172,49 +180,51 @@ Rules:
 Before declaring completion, you MUST:
 
 - OQ / undefined resolution: remove ambiguity from implementation decisions.
-- Deliverable completeness: verify required headings and concrete constraints.
+- Deliverable completeness: verify required sections and concrete constraints.
 - OQ / placeholder scan: remove unresolved placeholders (`TBD`, `TODO`, `???`, etc.) unless explicitly deferred.
-- Smoke check (if applicable): run the smallest command to prove artifacts are valid.
+- Run checks proving `plan.md` is actionable and references grounded slices.
 
 ## Goal
 
-Transform refined SDD artifacts into a constrained implementation plan that downstream skills must follow.
+Transform refined artifacts into a constrained `plan.md` that downstream execution phases must follow.
 
 ## Non-goals
 
-- Writing production code or tests.
-- Expanding into a full design document beyond required constraints.
+- Writing production code or runnable tests.
+- Re-authoring refinement-owned files unless an approved change request requires it.
 
 ## Mandatory Outputs
 
-- `.qfai/specs/spec-XXXX/plan.md`
+- `.qfai/specs/spec-XXXX/plan.md` (required)
+- `.qfai/specs/spec-XXXX/17_Plan.md` (optional layered mirror; keep in sync with `plan.md`)
 - Updated `.qfai/specs/spec-XXXX/delta.md` when planning decisions changed
+- Updated `.qfai/specs/spec-XXXX/18_delta.md` when layered mirror is used
 - Evidence file: `.qfai/evidence/sdd-planning-<spec-id>.md`
 
 ## Plan Template (Minimum)
 
-- Use `.qfai/templates/spec/plan.md` as the single source of truth.
+- Use `.qfai/templates/spec/plan.md` as the runtime source of truth.
+- If layered mode is used, keep `.qfai/assistant/skills/qfai-sdd-planning/templates/spec-pack/17_Plan.md` synchronized as a mirror.
 - Do not duplicate the template content in this workflow file.
 
 ## Change Control During Execution
 
 If execution discovers a conflicting implementation path:
 
-1. STOP implementation.
-2. Create a Change Request with at least 3 options + recommendation.
+1. STOP execution planning.
+2. Create a Change Request with at least 3 options plus recommendation.
 3. Wait for explicit user approval.
 4. Re-run the owner skill to update upstream artifacts (do not patch upstream directly from downstream).
-5. Re-run full validation after approved updates.
+5. Re-run full validation and reviewer gate after approved updates.
 
 ## Quality Gate
 
-Run:
-
-```bash
-qfai validate --fail-on error
-```
+Run checks:
 
-This phase must pass default/full validation.
+- Confirm `plan.md` exists and required sections are present in order.
+- Confirm plan references at least one grounded user-story slice from refinement outputs.
+- Confirm verification strategy aligns with `steering/test-layers.md`.
+- Confirm strategy changes are reflected in `delta.md` (and `18_delta.md` if mirror is used).
 
 ## Evidence (MANDATORY)
 
@@ -235,16 +245,17 @@ Required sections:
 When declaring DONE, include:
 
 - Referenced inputs and spec-id
-- `DR-HOW-*` IDs added or updated
-- Full validation result
+- `DELTA-*` IDs added or updated in `delta.md` (and `18_delta.md` when mirrored)
+- Static planning gate result
 - Confirmation that downstream phases must follow the plan
 
 ## FINAL CHECKLIST (Check Last)
 
 - [ ] CRITICAL CONSTRAINTS were followed.
 - [ ] `plan.md` exists and matches required heading order.
-- [ ] Any planning strategy change is recorded in delta decisions.
+- [ ] Any planning strategy change is recorded in `delta.md`.
+- [ ] If `17_Plan.md` exists, it is synchronized with `plan.md`.
 - [ ] Blockers are resolved, or approved exceptions are recorded.
-- [ ] Full validation passed (`qfai validate --fail-on error`).
+- [ ] Planning static gate checks are recorded in evidence.
 - [ ] Evidence file exists and is complete.
 - [ ] Reviewer approval is recorded.

package/assets/init/.qfai/assistant/skills/qfai-sdd-planning/templates/spec-pack/17_Plan.md

@@ -0,0 +1,58 @@
+# 17 Plan
+
+## Metadata
+
+| Key        | Value         |
+| ---------- | ------------- |
+| Spec ID    | SPEC-XXXX     |
+| Plan owner | <role/person> |
+| Created    | YYYY-MM-DD    |
+| Updated    | YYYY-MM-DD    |
+
+## Context and Scope
+
+- Related objective:
+- Related initiative:
+- In scope for execution:
+- Out of scope for execution:
+
+## Execution Strategy
+
+- Reference completed user-story slices from `06` to `16`:
+  - Slice:
+  - Why this order:
+- Drift Protocol checkpoints:
+- Change request policy:
+
+## Milestones
+
+| Milestone | Output   | Exit criteria |
+| --------- | -------- | ------------- |
+| M1        | <output> | <criteria>    |
+
+## Verification and Gates
+
+- Layer policy source: `.qfai/assistant/steering/test-layers.md`
+- Required checks:
+  - AC coverage by EX and TC
+  - ledger trace to objective intent
+  - critical risks covered by tests
+- Gate record location: `.qfai/evidence/sdd-planning-<spec-id>.md`
+
+## Risks and Mitigations
+
+| Risk   | Impact   | Mitigation   | Owner   |
+| ------ | -------- | ------------ | ------- |
+| <risk> | <impact> | <mitigation> | <owner> |
+
+## Open Questions
+
+- [OQ-SPEC-0001-0001] <question>
+
+## Done Checklist
+
+- [ ] Required sections are filled
+- [ ] At least one grounded user-story slice is referenced
+- [ ] Verification and gate conditions are explicit
+- [ ] Major strategy decisions are reflected in `delta.md` (and `18_delta.md` when layered mirror is used)
+- [ ] Reviewer approval is recorded

package/assets/init/.qfai/assistant/skills/qfai-sdd-refinement/SKILL.md

@@ -36,7 +36,7 @@ When unsure, read inputs in this order:
 
 - P1: `.qfai/assistant/instructions/*`
 - P2: `.qfai/assistant/steering/*`
-- P3: `.qfai/specs/<spec-id>/delta.md` (if present)
+- P3: `.qfai/specs/<spec-id>/delta.md` (if present, runtime SSOT)
 - P4: other artifacts (require/specs/contracts/evidence)
 
 ## Sub-agent Delegation (MANDATORY)
@@ -144,23 +144,40 @@ Rules:
 
 ## Delta Rejected Guard (Mandatory)
 
-- Do NOT reintroduce options marked as rejected in delta.md.
+- Do NOT reintroduce options marked as rejected in `delta.md`.
 - If a rejected option must be reconsidered, add a `[RE-OPEN]` decision record with explicit approval evidence.
 
+## Workflow Convention (Mandatory)
+
+Apply this flow only while authoring spec packs:
+
+- **Layer-first** for upper layers: `02_Objective.md`, `03_Initiative.md`, `04_Capability.md`, `05_Business-flow.feature`.
+- **Slice-first** for lower layers: `06_User-stories.md` -> `07_Acceptance-criteria.md` -> `08_Business-rules.md` -> `09_Examples.feature` -> `10_Test-cases.md` -> `16_Traceability-ledger.md` (matching rows).
+- `plan.md` is owned by planning and must be finalized after at least one user-story slice is grounded.
+
+US slice completion gate:
+
+- For each AC, examples count is at least one and test cases count is at least one.
+- Ledger rows can be traced back to objective intent.
+- `@layer-*` tags in examples align with `steering/test-layers.md`.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - This phase defines Why/What/Examples/Rules. It MUST NOT lock implementation details.
 - `plan.md` MUST NOT be created in this phase.
-- `case-catalogue.md` MUST use category-based Markdown tables (not bullet lists).
-- `case-catalogue.md` rows MUST keep all legacy information (no-loss), including a dedicated `Case title` column.
+- Use only skill-local templates:
+  - `.qfai/assistant/skills/qfai-sdd-refinement/templates/spec-pack/`
+- Scenario specification in `09_Examples.feature` is strict:
+  - exactly one `Feature:`
+  - one or more tagged `Scenario:`
+  - each scenario includes `@EX-XXXX @AC-XXXX @layer-*`
+- Respect reference direction rules from `.qfai/specs/README.md`:
+  - upper-to-lower references are forbidden
+  - lower-to-upper references are allowed
 - Ambiguity is forbidden:
-  - Ask the user when a decision is not at least 95% certain.
-  - If uncertainty remains, convert it to a documented Spike (timebox, success criteria, deliverable).
-- You MUST produce the required evidence file: `.qfai/evidence/sdd-refinement-<spec-id>.md`.
-- You MUST run the refinement gate:
-  - `qfai validate --phase refinement --fail-on error`
-- The refinement gate is local-stage validation. CI pipelines MUST use default/full validation (`qfai validate --fail-on error`).
-- Waivers may only suppress `warning` / `info` findings; never use waivers to suppress `error` findings.
+  - ask the user when certainty is below the threshold
+  - unresolved decisions become explicit open questions or spikes
+- You MUST produce the evidence file: `.qfai/evidence/sdd-refinement-<spec-id>.md`.
 - Completion must be approved by a reviewer who did not author the artifacts.
 
 ## Completion Contract (Shared)
@@ -170,27 +187,44 @@ Before declaring completion, you MUST:
 - OQ / undefined resolution: resolve ambiguities or explicitly defer with rationale and approval evidence.
 - Deliverable completeness: verify all required artifacts and sections are present.
 - OQ / placeholder scan: remove unresolved placeholders (`TBD`, `TODO`, `???`, `OPEN QUESTION`, etc.) unless explicitly deferred.
-- Smoke check (if applicable): run the smallest command that proves artifacts are machine-checkable.
+- Run static checks that prove the pack can be reviewed without validator support.
 
 ## Goal
 
-Create or update an SDD spec pack that is clear, testable, and ready for planning.
+Create or update an SDD spec pack in the layered format so planning can produce a constrained `plan.md`.
 
 ## Non-goals
 
-- Writing production code or tests.
+- Writing production code or runnable tests.
 - Creating `plan.md` (belongs to planning).
 - Bypassing unresolved ambiguity.
 
 ## Mandatory Outputs
 
-- `.qfai/specs/spec-XXXX/spec.md`
-- `.qfai/specs/spec-XXXX/delta.md`
-- `.qfai/specs/spec-XXXX/scenario.feature`
-- `.qfai/specs/spec-XXXX/case-catalogue.md`
-- `.qfai/specs/spec-XXXX/traceability-matrix.md`
-- Updated contracts under `.qfai/contracts/**` (when required)
-- `.qfai/require/open-questions.md`
+- `.qfai/specs/spec-XXXX/spec.md` (runtime compatibility)
+- `.qfai/specs/spec-XXXX/delta.md` (runtime decision/guardrail SSOT)
+- `.qfai/specs/spec-XXXX/scenario.feature` (runtime compatibility)
+- `.qfai/specs/spec-XXXX/case-catalogue.md` (runtime compatibility)
+- `.qfai/specs/spec-XXXX/traceability-matrix.md` (runtime compatibility)
+- `.qfai/specs/spec-XXXX/01_Spec.md`
+- `.qfai/specs/spec-XXXX/02_Objective.md`
+- `.qfai/specs/spec-XXXX/03_Initiative.md`
+- `.qfai/specs/spec-XXXX/04_Capability.md`
+- `.qfai/specs/spec-XXXX/05_Business-flow.feature`
+- `.qfai/specs/spec-XXXX/06_User-stories.md`
+- `.qfai/specs/spec-XXXX/07_Acceptance-criteria.md`
+- `.qfai/specs/spec-XXXX/08_Business-rules.md`
+- `.qfai/specs/spec-XXXX/09_Examples.feature`
+- `.qfai/specs/spec-XXXX/10_Test-cases.md`
+- `.qfai/specs/spec-XXXX/11_Contracts.md`
+- `.qfai/specs/spec-XXXX/12_Glossary.md`
+- `.qfai/specs/spec-XXXX/13_Constraints.md`
+- `.qfai/specs/spec-XXXX/14_Decisions.md`
+- `.qfai/specs/spec-XXXX/15_Open-questions.md`
+- `.qfai/specs/spec-XXXX/16_Traceability-ledger.md`
+- `.qfai/specs/spec-XXXX/18_delta.md` (optional layered mirror; sync with `delta.md`)
+- Updated contracts under `.qfai/contracts/**` when required
+- `.qfai/require/open-questions.md` when unresolved items remain
 - Evidence file: `.qfai/evidence/sdd-refinement-<spec-id>.md`
 
 ## Required Process
@@ -201,24 +235,21 @@ Create or update an SDD spec pack that is clear, testable, and ready for plannin
    - Can-Decide
    - Spike
 3. Resolve questions in loop (ask one at a time when interactive).
-4. Build/update contracts first when contracts are in scope.
-5. Produce or refine spec pack artifacts.
-6. Update delta decisions and rejected options.
-7. Run refinement gate and record outputs.
+4. Draft upper layers in layer-first order.
+5. Execute at least one user-story slice in slice-first order.
+6. Update contracts index and contract files when references are needed.
+7. Append adoption/rejection rationale in `delta.md` and sync layered `18_delta.md` when used.
+8. Run static refinement checks and record outcomes in evidence.
 
 ## Refinement Quality Gate
 
-Run:
-
-```bash
-qfai validate --phase refinement --fail-on error
-```
-
-Interpretation:
+Run static checks (no validator hard gate for this layout stage):
 
-- This gate validates upstream consistency.
-- How-specific checks and SC-to-Test enforcement are intentionally relaxed in this phase.
-- This gate is for local refinement iterations, not for CI.
+- Confirm `01..16` and `18` files exist in the target spec pack.
+- Confirm `09_Examples.feature` has exactly one `Feature:` block.
+- Confirm each scenario in `09_Examples.feature` has `@EX`, `@AC`, and `@layer-*` tags.
+- Confirm reference direction follows lower-to-upper only.
+- Confirm at least one ledger row can be traced to objective intent.
 
 ## Evidence (MANDATORY)
 
@@ -240,16 +271,17 @@ Required sections:
 When declaring DONE, include:
 
 - Referenced inputs and spec-id
-- Decision record IDs touched
+- Decision record IDs touched in `delta.md`
 - Confirmation that no rejected option was reintroduced (or list RE-OPEN IDs)
-- Refinement gate result
+- Refinement static gate result
 
 ## FINAL CHECKLIST (Check Last)
 
 - [ ] CRITICAL CONSTRAINTS were followed.
 - [ ] `plan.md` was NOT created in this phase.
-- [ ] `case-catalogue.md` uses category-based tables with `Case title` and no information loss.
+- [ ] Runtime compatibility files and layered `01..16`/`18` outputs exist.
+- [ ] `09_Examples.feature` uses one `Feature:` and tagged `Scenario:` entries.
 - [ ] OQ ambiguity is resolved or deferred with explicit approval evidence.
-- [ ] Refinement gate passed (`qfai validate --phase refinement --fail-on error`).
+- [ ] Refinement static gate checks are recorded in evidence.
 - [ ] Evidence file exists and is complete.
 - [ ] Reviewer approval is recorded.

package/assets/init/.qfai/assistant/skills/qfai-sdd-refinement/templates/spec-pack/01_Spec.md

@@ -0,0 +1,28 @@
+# 01 Spec - Metadata and SSOT
+
+## Metadata
+
+| Key     | Value                          |
+| ------- | ------------------------------ |
+| Spec ID | SPEC-XXXX                      |
+| Title   | <title>                        |
+| Status  | Draft \| In Review \| Approved |
+| Owner   | <role/person>                  |
+| Created | YYYY-MM-DD                     |
+| Updated | YYYY-MM-DD                     |
+
+## Reading Order
+
+Use the file order `01` to `18` for review.
+
+## SSOT Declarations
+
+- Objective SSOT: `02_Objective.md`
+- Traceability SSOT: `16_Traceability-ledger.md`
+- Plan SSOT: `plan.md` (planning owned; `17_Plan.md` may mirror in layered mode)
+- Contracts index is non-SSOT: `11_Contracts.md`
+
+## Reference Rule
+
+- Upper-to-lower references are forbidden.
+- Lower-to-upper references are allowed.

package/assets/init/.qfai/assistant/skills/qfai-sdd-refinement/templates/spec-pack/02_Objective.md

@@ -0,0 +1,23 @@
+# 02 Objective
+
+## Intent
+
+- Primary user value:
+- Business value:
+
+## Success Metrics
+
+| Metric   | Target   | Measurement      |
+| -------- | -------- | ---------------- |
+| <metric> | <target> | <how to measure> |
+
+## Decision Policy
+
+- Priority order for trade-offs:
+- What to optimize first:
+- What can be sacrificed:
+
+## Reference Rule
+
+- This layer must not reference lower layers.
+- Lower layers may reference this objective.

package/assets/init/.qfai/assistant/skills/qfai-sdd-refinement/templates/spec-pack/03_Initiative.md

@@ -0,0 +1,26 @@
+# 03 Initiative
+
+## Scope Boundary
+
+### In Scope
+
+- <item>
+
+### Out of Scope
+
+- <item>
+
+## Assumptions
+
+- <assumption>
+
+## Risks
+
+| Risk   | Impact   | Mitigation   |
+| ------ | -------- | ------------ |
+| <risk> | <impact> | <mitigation> |
+
+## Reference Rule
+
+- This layer must not reference lower layers.
+- Lower layers may reference initiative constraints.