qfai 1.5.2 → 1.5.4

package/README.md

@@ -246,7 +246,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.5.2)
+## Minimal tutorial (v1.5.4)
 
 1. `npx qfai init`
 2. Run `/qfai-discussion` to structure scope, open questions, and produce a discussion pack under `.qfai/discussion/discussion-<ts>/`.
@@ -278,7 +278,8 @@ It does not generate GitHub Actions workflows.
 Configure CI in your own platform and run:
 
 ```bash
-pnpm ci:local
+pnpm ci:gate
+pnpm check-types:future
 # or, minimum gate only:
 npx qfai validate --fail-on error
 ```
@@ -286,6 +287,7 @@ npx qfai validate --fail-on error
 Recommended baseline.
 
 - Keep CI on default/full validation (`qfai validate --fail-on error`); do not use `--phase refinement` in CI.
+- Keep `pnpm check-types:future` as a separate mandatory gate so future TS compatibility runs once without duplicating `pnpm ci:gate`.
 - Add a report step (`npx qfai report`) when you need a human-readable artifact.
 - Tune traceability globs in `qfai.config.yaml` to match your test layout.
 

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

@@ -98,7 +98,8 @@ It is useful for local review but should not pollute version control.
 
 ### R4. Layered specs are runtime SSOT
 
-- Runtime validators and downstream skills consume `_shared/**` and `spec-XXXX/**`.
+- Runtime validators consume `_policies/**` and `spec-XXXX/**`.
+- Execution skills enter from `spec-XXXX/01_Spec.md` and read `_policies/**` only through the spec's Escalation Hook.
 - 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.

package/assets/init/.qfai/assistant/agents/prototyping-coverage-auditor.md

@@ -9,7 +9,7 @@
 - `.qfai/assistant/instructions/*`
 - `.qfai/assistant/steering/*`
 - `.qfai/specs/spec-*`
-- `.qfai/specs/_shared/05_Contracts.md`
+- `.qfai/specs/_policies/05_Contracts.md`
 - prototyping markdown evidence artifact in the evidence directory
 - prototyping json evidence artifact in the evidence directory
 

package/assets/init/.qfai/assistant/instructions/drift-protocol.md

@@ -9,7 +9,7 @@ This file defines mandatory change control for all downstream execution phases.
 Upstream artifacts include, at minimum:
 
 - `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/*` layered artifacts and `11_Contracts.md` (or project-equivalent contract index)
+- `_policies/*` layered artifacts and `11_Contracts.md` (or project-equivalent contract index)
 - `10_Plan.md` and other owner-phase planning outputs
 - Legacy spec-pack SSOT files when present: `spec.md`, `delta.md`, `plan.md`, `traceability-matrix.md`, `scenario.feature`, `case-catalogue.md`, and numbered pack files (for example `01_Spec.md`..`18_delta.md`)
 - contracts and schema decisions owned by earlier phases

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

@@ -12,11 +12,11 @@ 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-*/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)
+1. **Source registry** (`.qfai/require/require-*/01_Sources.md`)
+2. **Requirement index** (`.qfai/require/require-*/03_REQ.md`)
+3. **Input gaps / Open Questions** (`.qfai/require/require-*/08_OQ.md`)
+4. **Policy layer** (`.qfai/specs/_policies/01..04`)
+5. **Capability slices** (`.qfai/specs/spec-*/01..05` minimum)
 6. **ATDD / TDD** (tests + code)
 
 ## Decision rules
@@ -28,32 +28,32 @@ This document is the decision rule SSOT for AI and humans when answering:
 
 ### Rule 2 - Preserve layered ownership
 
-- `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/`.
+- `.qfai/require/` stores only source/index/gap inputs.
+- `.qfai/specs/` is the SSOT for detailed behavior and design decisions.
+- Do not duplicate detailed spec text in `.qfai/require/`.
 
 ### Rule 3 - Keep ambiguity explicit
 
 - Unknowns remain explicit as Open Questions.
-- Resolved answers are promoted to `_shared` or `spec-XXXX` artifacts, then OQ status is updated.
+- Resolved answers are promoted to `_policies` or `spec-XXXX` artifacts, then OQ status is updated.
 
 ## How to decompose (mechanical procedure)
 
-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`).
+1. Register source documents and assumptions in `.qfai/require/require-*/01_Sources.md`.
+2. Extract concise requirement index entries in `.qfai/require/require-*/03_REQ.md`.
+3. Capture missing information in `.qfai/require/require-*/08_OQ.md`.
+4. Build `_policies` 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.
 
 ## Example
 
 - 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`
+- Capability mapping: `CAP-0003` in `.qfai/specs/_policies/03_Capabilities.md`
+- Spec slice: `.qfai/specs/spec-0003/01_Spec.md` through `06_Test-Cases.md`
 
 ## Non-goals
 
 - Managing release status flags in specs.
-- Keeping full requirement prose in `require/`.
+- Keeping full requirement prose in `.qfai/require/`.
 - Treating diagrams as mandatory at require stage.

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

@@ -2,7 +2,7 @@
 
 QFAI standardizes work into a fixed pipeline:
 
-**SDD → ATDD → TDD → Verification**
+## SDD -> ATDD -> TDD -> Verification
 
 This file defines the canonical stages and delegation expectations.
 
@@ -49,7 +49,7 @@ 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): unified preflight + `_shared` / `spec-XXXX/01..10`
+3. Specification (SDD): unified preflight + `_policies` / `spec-XXXX/01..10`
 4. Prototyping (optional): contract-aligned implementation skeleton
 5. Acceptance tests (ATDD): runnable E2E/API/Integration tests derived from specs/contracts obligations (`US` / `TC` / `CON-API`)
 6. Verify: run quality gates and provide evidence
@@ -57,7 +57,7 @@ Do not proceed without a declared Change Type.
 Stage 3 (`/qfai-sdd`) target policy:
 
 - With argument (`/qfai-sdd <spec-id-or-name>`): scope is the matched single spec only.
-- Without argument (`/qfai-sdd`): scope is all capabilities from `.qfai/specs/_shared/03_Capabilities.md` in order.
+- Without argument (`/qfai-sdd`): scope is all capabilities from `.qfai/specs/_policies/03_Capabilities.md` in order.
 - For no-argument batch runs, execute Contracts-first and Outline once, then delegate Slice/Plan/Delta in parallel per `spec-XXXX`.
 
 Prototyping stage policy:

package/assets/init/.qfai/assistant/manifest/spec_required_files.json

@@ -8,7 +8,8 @@
     "06_Test-Cases.md",
     "07_Decisions.md",
     "08_Open-questions.md",
-    "09_delta.md"
+    "09_delta.md",
+    "10_Plan.md"
   ],
   "shared_dir": [
     "01_Objective.md",

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

@@ -1,22 +1,33 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-atdd
 title: QFAI ATDD (Executable acceptance tests)
 description: "Implement automated acceptance tests (E2E/API/Integration) aligned with US/TC/CON-API obligations from specs and contracts."
 argument-hint: "<spec-id> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [Orchestrator, TestVolumeEstimator, ATDDE2EImplementer, ATDDAPIImplementer, ATDDIntegrationImplementer, QAEngineer, TestEngineer, BackendEngineer, FrontendEngineer, Reviewer, RuntimeGatekeeper, DevOpsCIEngineer, CodeReviewer]
+roles:
+  - Orchestrator
+  - TestVolumeEstimator
+  - ATDDE2EImplementer
+  - ATDDAPIImplementer
+  - ATDDIntegrationImplementer
+  - QAEngineer
+  - TestEngineer
+  - BackendEngineer
+  - FrontendEngineer
+  - Reviewer
+  - RuntimeGatekeeper
+  - DevOpsCIEngineer
+  - CodeReviewer
 mode: execution-focused
-
 ---
 
-# /qfai-atdd — Implement Automated Acceptance Tests (ATDD)
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-atdd — Implement Automated Acceptance Tests (ATDD)
 
 [DRIFT-PROTOCOL:MANDATORY]
 
@@ -33,15 +44,30 @@ When unsure, read inputs in this order:
 
 - P1: `.qfai/assistant/instructions/*`
 - P2: `.qfai/assistant/steering/*`
-- P3: `.qfai/specs/<spec-id>/09_delta.md` (Decision Records; if no spec yet, state "not applicable")
+- P3: `.qfai/specs/<spec-id>/01_Spec.md` (Primary SSOT / Consumer View)
 - P4: specs/contracts obligations
   - `.qfai/specs/<spec-id>/02_User-stories.md` (US)
+  - `.qfai/specs/<spec-id>/03_Acceptance-Criteria.md` (AC)
+  - `.qfai/specs/<spec-id>/05_Examples.md` (EX)
   - `.qfai/specs/<spec-id>/06_Test-Cases.md` (TC)
   - `.qfai/contracts/api/**` (CON-API)
-- P5: legacy artifacts (optional only)
+- P5: `.qfai/specs/<spec-id>/09_delta.md` (Decision Records; if no spec yet, state "not applicable")
+- P6: legacy artifacts (optional only)
   - `.qfai/specs/<spec-id>/scenario.feature`
   - coverage ledger files
 
+## Read Set Contract (Mandatory)
+
+- Default Mode:
+  - `.qfai/specs/<spec-id>/01_Spec.md`
+  - `.qfai/specs/<spec-id>/03_Acceptance-Criteria.md`
+  - `.qfai/specs/<spec-id>/05_Examples.md`
+  - `.qfai/specs/<spec-id>/06_Test-Cases.md`
+- Escalation Mode:
+  - allowed only when `01_Spec.md` Escalation Hook signals ambiguity / conflict / missing constraint / trade-off
+  - read only `.qfai/specs/_policies/01_Objective.md` and `.qfai/specs/_policies/08_Decisions.md`
+- Do not read `_policies/**` by default.
+
 ## Sub-agent Delegation (MANDATORY)
 
 This section is mandatory and overrides any conflicting fallback text in this file.

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

@@ -1,11 +1,4 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-configure
 title: QFAI Configure (Tune qfai.config.yaml)
 description: "Analyze the repository and tune qfai.config.yaml (testFileGlobs, exclude globs, optional specSections)."
@@ -13,10 +6,15 @@ argument-hint: "[--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task]
 roles: [DevOpsCIEngineer, QAEngineer, CodeReviewer, Planner]
 mode: evidence-focused
-
 ---
 
-# /qfai-configure - Configure QFAI for this repository
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-configure - Configure QFAI for this repository
 
 [DRIFT-PROTOCOL:MANDATORY]
 
@@ -148,7 +146,9 @@ Rules:
 ## Delta Rejected Guard (Mandatory)
 
 - Do NOT reintroduce options marked as rejected in 09_delta.md.
-- If a rejected option must be reconsidered, create a **[RE-OPEN]** Decision Record in 09_delta.md that references the prior DR-ID, states what changed + new criteria, and includes explicit approval (user or instructions/steering).
+- If a rejected option must be reconsidered, create a **[RE-OPEN]** Decision
+  Record in 09_delta.md that references the prior DR-ID, states what changed +
+  new criteria, and includes explicit approval (user or instructions/steering).
 
 ## CRITICAL CONSTRAINTS (Read First)
 
@@ -166,8 +166,15 @@ Before declaring completion, you MUST:
 
 - OQ / undefined resolution: detect undefined or ambiguous items; resolve them or explicitly defer them with documented rationale and (when required by this prompt) user approval.
 - Deliverable completeness: verify every expected artifact listed in this prompt (and required README templates) exists and is fully populated; no missing required sections.
-- OQ / placeholder scan: scan all generated artifacts (including evidence) for placeholders such as "TBD", "TODO", "TBA", "TBC", "XXX", "???", "OQ", "OPEN QUESTION", "UNDEFINED", "PLACEHOLDER", and localized equivalents in the user's language. Resolve or explicitly defer; do not leave silent placeholders.
-- Smoke check (if applicable): when the prompt produces runnable code/tests/configs, execute the smallest command that proves basic run/start/operate and record evidence. If not applicable, state "not applicable" with a short rationale.
+- OQ / placeholder scan: scan all generated artifacts (including evidence) for
+  placeholders such as "TBD", "TODO", "TBA", "TBC", "XXX", "???", "OQ",
+  "OPEN QUESTION", "UNDEFINED", "PLACEHOLDER", and localized equivalents in
+  the user's language. Resolve or explicitly defer; do not leave silent
+  placeholders.
+- Smoke check (if applicable): when the prompt produces runnable code, tests,
+  or configs, execute the smallest command that proves basic run/start/operate
+  and record evidence. If not applicable, state "not applicable" with a short
+  rationale.
 
 ## Goal
 

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

@@ -1,12 +1,4 @@
-````skill
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-discussion
 title: QFAI Discussion (Unified Discuss + Require)
 description: "Run structured discussion that merges discuss and require into a single 15-file discussion pack with OQ-driven exit."
@@ -14,10 +6,15 @@ argument-hint: "<idea-or-problem> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
 roles: [Researcher, Facilitator, Interviewer, RequirementsAnalyst, QAEngineer, Planner]
 mode: interactive-by-default
-
 ---
 
-# /qfai-discussion - Unified Discuss + Require
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-discussion - Unified Discuss + Require
 
 [DRIFT-PROTOCOL:MANDATORY]
 
@@ -333,5 +330,3 @@ You MUST end the user-facing output with a handoff sentence to `/qfai-sdd` in th
   Action: continue discussion loops until OQ states are explicit and complete.
 - Need additional risk analysis before SDD:
   Action: update `03_Story-Workshop.md` and `11_OQ-Register.md` with additional findings.
-
-````

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/review/Rxx_reviewer.md

@@ -1,9 +1,9 @@
 # Reviewer Result
 
-- reviewer_id: `<qa-lead>`
-- reviewer_role: `<Quality Lead>`
+- reviewer_id: `Rxx`
+- reviewer_role: `qa-lead`
 - verdict: `PASS` <!-- PASS | FAIL | N/A -->
-- reviewed_at: `<YYYY-MM-DDThh:mm:ssZ>`
+- reviewed_at: `YYYY-MM-DDThh:mm:ssZ`
 
 ## Checked
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/review/summary.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0",
-  "created_at": "2026-03-03T12:00:00+09:00",
+  "created_at": "YYYY-MM-DDThh:mm:ssZ",
   "target": {
     "kind": "discussion",
     "path": ".qfai/discussion/discussion-YYYYMMDDhhmmssSSS"

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

@@ -1,22 +1,31 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-prototyping
 title: QFAI Prototyping (All-spec runnable skeleton gate)
 description: "Implement a minimum runnable skeleton for ALL specs and block DONE until evidence + validate gate pass."
 argument-hint: "[--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [FullStackEngineer, BackendEngineer, FrontendEngineer, DBEngineer, DevOpsCIEngineer, QAEngineer, RuntimeGatekeeper, UIUXReviewer, CodeReviewer]
+roles:
+  [
+    FullStackEngineer,
+    BackendEngineer,
+    FrontendEngineer,
+    DBEngineer,
+    DevOpsCIEngineer,
+    QAEngineer,
+    RuntimeGatekeeper,
+    UIUXReviewer,
+    CodeReviewer,
+  ]
 mode: execution-focused
-
 ---
 
-# /qfai-prototyping
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-prototyping
 
 [DRIFT-PROTOCOL:MANDATORY]
 
@@ -59,9 +68,20 @@ When unsure, read inputs in this order:
 
 - P1: `.qfai/assistant/instructions/*`
 - P2: `.qfai/assistant/steering/*`
-- P3: `.qfai/specs/spec-*/09_delta.md` (Decision Records)
-- P4: `.qfai/specs/_shared/05_Contracts.md` and each `spec-*/11_Contracts.md`
-- P5: `.qfai/contracts/**` and existing evidence
+- P3: `.qfai/specs/spec-*/01_Spec.md` (Primary SSOT / Consumer View)
+- P4: `.qfai/contracts/ui/**`, `.qfai/specs/_policies/05_Contracts.md`, and each `spec-*/11_Contracts.md`
+- P5: `.qfai/specs/spec-*/09_delta.md` (Decision Records)
+- P6: existing evidence
+
+## Read Set Contract (Mandatory)
+
+- Default Mode:
+  - `.qfai/specs/spec-*/01_Spec.md`
+  - relevant `.qfai/contracts/ui/**`
+- Escalation Mode:
+  - allowed only when `01_Spec.md` Escalation Hook signals ambiguity / conflict / missing constraint / trade-off
+  - read only `.qfai/specs/_policies/01_Objective.md`, `.qfai/specs/_policies/07_Constraints.md`, `.qfai/specs/_policies/08_Decisions.md`
+- Do not read `_policies/**` by default.
 
 ## Sub-agent Delegation (MANDATORY)
 
@@ -195,7 +215,7 @@ Build the minimum runnable vertical slice for **all specs** so `/qfai-atdd` can
 ## Scope SSOT (ALL contracts -> ALL specs)
 
 1. Enumerate all specs from `.qfai/specs/spec-*`.
-2. Resolve each spec's contracts via `_shared/05_Contracts.md` and/or `spec-*/11_Contracts.md`.
+2. Resolve each spec's contracts via `_policies/05_Contracts.md` and/or `spec-*/11_Contracts.md`.
 3. Do not declare completion while any spec lacks contract assignment.
 
 ## Preflight (required)

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

@@ -1,22 +1,30 @@
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
-
 ---
-
 name: qfai-sdd
 title: QFAI SDD Unified (Outline/Slice/Plan/Delta)
-description: "Create and update layered SDD artifacts (\_shared + spec-XXXX) in one workflow."
+description: "Create and update layered SDD artifacts (\_policies + spec-XXXX) in one workflow."
 argument-hint: "[<spec-id-or-name>] [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [Planner, Architect, RequirementsAnalyst, SpecWriter, TraceabilityBuilder, TestStrategist, QAEngineer, CodeReviewer]
+roles:
+  [
+    Planner,
+    Architect,
+    RequirementsAnalyst,
+    SpecWriter,
+    TraceabilityBuilder,
+    TestStrategist,
+    QAEngineer,
+    CodeReviewer,
+  ]
 mode: approval-gated
-
 ---
 
-# /qfai-sdd - Unified SDD Workflow
+<!--
+QFAI Skill Body (SSOT)
+- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
+- Keep wrappers thin and route users to this skill body.
+-->
+
+## /qfai-sdd - Unified SDD Workflow
 
 [DRIFT-PROTOCOL:MANDATORY]
 
@@ -94,7 +102,7 @@ Every major artifact in this stage MUST include a `## Work Orders Summary` secti
 ### No-argument batch delegation (MUST)
 
 - If `/qfai-sdd` is invoked without `<spec-id-or-name>`, treat the run as an all-capability batch.
-- Enumerate targets from `.qfai/specs/_shared/03_Capabilities.md` and keep `spec-0001..N` mapping stable by Capability order.
+- Enumerate targets from `.qfai/specs/_policies/03_Capabilities.md` and keep `spec-0001..N` mapping stable by Capability order.
 - In batch mode, run Contracts-first and Outline exactly once as shared outputs.
 - Delegate Slice in parallel per spec:
   - `SpecWriter + TraceabilityBuilder` own `spec-XXXX/01..08`.
@@ -203,14 +211,14 @@ Rules:
 - **Upper-to-lower references are forbidden. Lower-to-upper references are allowed.**
 - **Connections between layers MUST be represented by IDs and required edges (`US->AC->BR->EX->TC`).**
 - **Plan finalize MUST happen after at least one user-story slice is grounded.**
-- **Unresolved items MUST be moved to `08_Open-questions.md` (spec scope) or `_shared/09_Open-questions.md` (shared scope).**
+- **Unresolved items MUST be moved to `08_Open-questions.md` (spec scope) or `_policies/09_Open-questions.md` (shared scope).**
 
 ## Arguments and Target Selection (Mandatory)
 
 - With argument (`/qfai-sdd <spec-id-or-name> [--auto]`): update only the matched single spec target.
-- Without argument (`/qfai-sdd`): target all capabilities listed in `_shared/03_Capabilities.md`.
-- If `_shared/03_Capabilities.md` does not exist, bootstrap shared templates first, then enumerate capabilities.
-- Capability order in `_shared/03_Capabilities.md` is SSOT for `spec-0001..N` assignment and ID stability.
+- Without argument (`/qfai-sdd`): target all capabilities listed in `_policies/03_Capabilities.md`.
+- If `_policies/03_Capabilities.md` does not exist, bootstrap shared templates first, then enumerate capabilities.
+- Capability order in `_policies/03_Capabilities.md` is SSOT for `spec-0001..N` assignment and ID stability.
 - Reordering capability-to-spec mapping is a Change Request decision and must not be done implicitly.
 - Batch policy (no argument):
   - Contracts-first/Outline: once per batch.
@@ -226,7 +234,7 @@ Rules:
 - Always write `.qfai/report/preflight_summary.md` before generating shared/spec artifacts.
 - Contracts are contract-first mandatory outputs in this skill:
   - create/update `.qfai/contracts/(api|db|ui)/**` before shared/spec slices
-  - `_shared/05_Contracts.md` must include a Contract Index with short IDs (`DB-001`, `API-001`, `UI-001`)
+  - `_policies/05_Contracts.md` must include a Contract Index with short IDs (`DB-001`, `API-001`, `UI-001`)
   - every indexed short ID must map to a declared file with `QFAI-CONTRACT-ID`:
     - `DB-001 -> CON-DB-0001 -> db-0001-<slug>.sql`
     - `API-001 -> CON-API-0001 -> api-0001-<slug>.yaml`
@@ -238,7 +246,7 @@ Rules:
 - `/qfai-sdd` must stop when discussion-pack is missing/incomplete or has blocking OQ (guide to `/qfai-discussion` first).
 - Review roster is fixed by `.qfai/assistant/steering/review-roster.yml` and must be executed in full.
 - RCP wording must be sourced from `.qfai/assistant/skills/qfai-sdd/references/rcp_footer.md`.
-- `_shared/04_Business-Flow.md` must be Markdown and include at least one Mermaid `flowchart` or `sequenceDiagram`.
+- `_policies/04_Business-Flow.md` must be Markdown and include at least one Mermaid `flowchart` or `sequenceDiagram`.
 - Business Flow must not be authored as Gherkin (`*Business-flow*.feature` is deprecated).
 - If diagrams are written in discuss/require/spec/evidence artifacts, Mermaid syntax must be inside ` ```mermaid ` fences only.
 - `05_Examples.md` must include `EX-ID` and `BR-Ref` mappings.
@@ -266,12 +274,12 @@ Create/update:
 - `.qfai/contracts/api/**`
 - `.qfai/contracts/db/**`
 - `.qfai/contracts/ui/**`
-- `_shared/05_Contracts.md` Contract Index table (DB/API/UI short IDs)
+- `_policies/05_Contracts.md` Contract Index table (DB/API/UI short IDs)
 
 Rules:
 
 - This phase MUST complete before Outline/Slice.
-- If `_shared/05_Contracts.md` lists an ID, the corresponding declared contract file MUST exist.
+- If `_policies/05_Contracts.md` lists an ID, the corresponding declared contract file MUST exist.
 - If a contract is empty, create a valid minimal stub and include `QFAI-CONTRACT-ID`.
 - `none` is allowed only when there is no contract impact and rationale is written.
 
@@ -279,22 +287,22 @@ Rules:
 
 Create/update:
 
-- `_shared/01_Objective.md`
-- `_shared/02_Initiative.md`
-- `_shared/03_Capabilities.md`
-- `_shared/04_Business-Flow.md`
-- `_shared/05_Contracts.md`
-- `_shared/06_Glossary.md`
-- `_shared/07_Constraints.md`
-- `_shared/08_Decisions.md`
-- `_shared/09_Open-questions.md`
-- `_shared/10_delta.md`
+- `_policies/01_Objective.md`
+- `_policies/02_Initiative.md`
+- `_policies/03_Capabilities.md`
+- `_policies/04_Business-Flow.md`
+- `_policies/05_Contracts.md`
+- `_policies/06_Glossary.md`
+- `_policies/07_Constraints.md`
+- `_policies/08_Decisions.md`
+- `_policies/09_Open-questions.md`
+- `_policies/10_delta.md`
 
 Rules:
 
-- Temporary `TBD` is allowed, but each `TBD` must be mirrored into `_shared/09_Open-questions.md`.
-- `_shared/04_Business-Flow.md` must include Mermaid and keep diagram syntax inside ` ```mermaid ` fences.
-- `_shared/08_Decisions.md` and `_shared/10_delta.md` must exist even when empty, and must explicitly state `0 items`.
+- Temporary `TBD` is allowed, but each `TBD` must be mirrored into `_policies/09_Open-questions.md`.
+- `_policies/04_Business-Flow.md` must include Mermaid and keep diagram syntax inside ` ```mermaid ` fences.
+- `_policies/08_Decisions.md` and `_policies/10_delta.md` must exist even when empty, and must explicitly state `0 items`.
 
 ### Phase 2 - Slice (slice-first)
 
@@ -316,6 +324,7 @@ Slice gate (must pass before Phase 3):
 - For each TC, EX reference must exist.
 - `SC` tags must align with the target `spec-XXXX` namespace.
 - `07_Decisions.md` and `08_Open-questions.md` must exist even when empty and include explicit `0 items` statements.
+- `01_Spec.md` is the execution Primary SSOT and MUST copy down applicable NFR, policy, evidence summary, relevant requirements, and an Escalation Hook to `_policies`.
 
 ### Phase 3 - Plan finalize
 
@@ -366,16 +375,16 @@ Create or update layered SDD artifacts in one run so downstream execution phases
 
 ## Mandatory Outputs
 
-- `.qfai/specs/_shared/01_Objective.md`
-- `.qfai/specs/_shared/02_Initiative.md`
-- `.qfai/specs/_shared/03_Capabilities.md`
-- `.qfai/specs/_shared/04_Business-Flow.md`
-- `.qfai/specs/_shared/05_Contracts.md`
-- `.qfai/specs/_shared/06_Glossary.md`
-- `.qfai/specs/_shared/07_Constraints.md`
-- `.qfai/specs/_shared/08_Decisions.md`
-- `.qfai/specs/_shared/09_Open-questions.md`
-- `.qfai/specs/_shared/10_delta.md`
+- `.qfai/specs/_policies/01_Objective.md`
+- `.qfai/specs/_policies/02_Initiative.md`
+- `.qfai/specs/_policies/03_Capabilities.md`
+- `.qfai/specs/_policies/04_Business-Flow.md`
+- `.qfai/specs/_policies/05_Contracts.md`
+- `.qfai/specs/_policies/06_Glossary.md`
+- `.qfai/specs/_policies/07_Constraints.md`
+- `.qfai/specs/_policies/08_Decisions.md`
+- `.qfai/specs/_policies/09_Open-questions.md`
+- `.qfai/specs/_policies/10_delta.md`
 - `.qfai/specs/spec-XXXX/01_Spec.md`
 - `.qfai/specs/spec-XXXX/02_User-stories.md`
 - `.qfai/specs/spec-XXXX/03_Acceptance-Criteria.md`
@@ -396,7 +405,7 @@ Create or update layered SDD artifacts in one run so downstream execution phases
 2. If readiness checks fail, stop and show blockers with `/qfai-discussion`.
 3. Analyze repository context, existing artifacts, constraints, and open decisions.
 4. Write `.qfai/report/preflight_summary.md` from `templates/report/preflight_summary.md`.
-5. Execute Phase 0 (Contracts-first) and ensure `_shared/05_Contracts.md` index and `.qfai/contracts/**` are aligned.
+5. Execute Phase 0 (Contracts-first) and ensure `_policies/05_Contracts.md` index and `.qfai/contracts/**` are aligned.
 6. Execute Phase 1 (Outline) in layer-first order.
 7. Execute Phase 2 (Slice) and pass slice gate for each target spec (single target: at least one user-story slice; no-argument batch: all enumerated specs).
 8. Execute Phase 3 (Plan finalize) and make every target `10_Plan.md` actionable as How-only.
@@ -410,8 +419,9 @@ Create or update layered SDD artifacts in one run so downstream execution phases
 
 Run static checks:
 
-- Confirm required `_shared` and `spec-XXXX` layered files exist.
-- Confirm `_shared/04_Business-Flow.md` includes Mermaid and at least one `flowchart` or `sequenceDiagram`.
+- Confirm required `_policies` and `spec-XXXX` layered files exist.
+- Confirm `_policies/04_Business-Flow.md` includes Mermaid and at least one `flowchart` or `sequenceDiagram`.
+- Confirm `01_Spec.md` includes copy-down context and Escalation Hook to `_policies`.
 - Confirm Mermaid syntax is not written in ` ```text ` or language-less fences.
 - Confirm `05_Examples.md` provides `EX-ID` + `BR-Ref` mappings.
 - Confirm `06_Test-Cases.md` provides `TC-ID` + `EX-Ref` + `AC-Refs`.
@@ -457,11 +467,11 @@ When declaring DONE, include:
 - [ ] CRITICAL CONSTRAINTS were followed.
 - [ ] `.qfai/report/preflight_summary.md` was generated before spec authoring.
 - [ ] Contracts-first -> Outline -> Slice -> Plan finalize -> Delta update order was preserved.
-- [ ] `_shared/05_Contracts.md` index and `.qfai/contracts/**` declared files are aligned.
+- [ ] `_policies/05_Contracts.md` index and `.qfai/contracts/**` declared files are aligned.
 - [ ] Upper-to-lower references were not introduced.
 - [ ] At least one user-story slice passed gate before plan finalization.
-- [ ] Required `_shared` + `spec-XXXX` outputs exist and are internally consistent.
-- [ ] `_shared/04_Business-Flow.md` is Markdown + Mermaid (`flowchart` or `sequenceDiagram`).
+- [ ] Required `_policies` + `spec-XXXX` outputs exist and are internally consistent.
+- [ ] `_policies/04_Business-Flow.md` is Markdown + Mermaid (`flowchart` or `sequenceDiagram`).
 - [ ] Mermaid syntax was not written in ` ```text ` or language-less fences.
 - [ ] `10_Plan.md` is finalized with implementation/test strategy (How-only).
 - [ ] `specs/plan.md` was not created.
@@ -493,6 +503,6 @@ When this skill is complete, provide a final user-facing completion message and
 - Test-first path: `/qfai-atdd`.
   Action: implement acceptance tests from the finalized spec pack.
 - Contracts status:
-  Action: confirm contracts were created/updated under `.qfai/contracts/**` and referenced by `_shared/05_Contracts.md`.
+  Action: confirm contracts were created/updated under `.qfai/contracts/**` and referenced by `_policies/05_Contracts.md`.
 - Spec pack needs correction: rerun `/qfai-sdd`.
-  Action: fix layered `_shared + spec-XXXX` consistency and decision records, then regenerate evidence.
+  Action: fix layered `_policies + spec-XXXX` consistency and decision records, then regenerate evidence.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/report/preflight_summary.md

@@ -16,4 +16,4 @@
 
 ## Next Commands
 
-- /qfai-discussion
+- /qfai-sdd