qfai 1.5.2 → 1.5.3

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.3)
 
 1. `npx qfai init`
 2. Run `/qfai-discussion` to structure scope, open questions, and produce a discussion pack under `.qfai/discussion/discussion-<ts>/`.

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

@@ -15,7 +15,7 @@ This document is the decision rule SSOT for AI and humans when answering:
 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`)
+4. **Policy layer** (`specs/_policies/01..04`)
 5. **Capability slices** (`specs/spec-*/01..05` minimum)
 6. **ATDD / TDD** (tests + code)
 
@@ -35,21 +35,21 @@ This document is the decision rule SSOT for AI and humans when answering:
 ### 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`).
+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`
+- Capability mapping: `CAP-0003` in `_policies/03_Capabilities.md`
 - Spec slice: `spec-0003/01_Spec.md` through `06_Test-Cases.md`
 
 ## Non-goals

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

@@ -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/skills/qfai-atdd/SKILL.md

@@ -33,15 +33,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-prototyping/SKILL.md

@@ -59,9 +59,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 +206,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

@@ -8,7 +8,7 @@ QFAI Skill Body (SSOT)
 
 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]
@@ -94,7 +94,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 +203,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 +226,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 +238,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 +266,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 +279,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 +316,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 +367,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 +397,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 +411,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 +459,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 +495,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/specs/{_shared → _policies}/03_Capabilities.md

@@ -15,5 +15,5 @@
 
 ## Authoring rules
 
-- This file is shared SSOT across all specs.
+- This file is the policy-layer SSOT for capability mapping across all specs.
 - Do not copy spec-level details (US/AC/BR/EX/TC) into this file.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/{_shared → _policies}/04_Business-Flow.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-- Describe the high-level business process as shared SSOT.
+- Describe the high-level business process as policy-layer SSOT.
 - Keep acceptance scenarios in `spec-XXXX/03_Acceptance-Criteria.md`.
 
 ## Actors / Systems

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/{_shared → _policies}/05_Contracts.md

@@ -3,7 +3,7 @@
 ## Purpose
 
 - Keep contracts as SSOT under `.qfai/contracts/**` with deterministic IDs.
-- Use this file as a readable index with short IDs for planning and review.
+- Use this file as a readable policy-layer index with short IDs for planning and review.
 
 ## Contract Index
 

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

@@ -3,13 +3,51 @@
 - Spec: spec-0001
 - Parent: CAP-0001
 
+## Consumer View
+
+- Primary SSOT for execution: `spec-0001/01_Spec.md`
+- Default read set: this file + relevant contracts only
+- `_policies` is read-only escalation context and must not be read by default
+
 ## Scope
 
 - In:
 - Out:
 
+## Applicable NFR
+
+- NFR:
+
+## Applicable Policy
+
+- Policy:
+
+## Evidence Summary
+
+- Evidence:
+
+## Relevant Requirements
+
+- REQ:
+
 ## Entry points
 
 - US range in this spec: US-0001..
 - Primary actors:
 - Notes:
+
+## Escalation Hook (Read \_policies only when needed)
+
+### When to Escalate
+
+- Ambiguous: multiple valid implementations exist.
+- Conflict: NFR / Policy / AC conflict.
+- Missing: required constraints or policy are unclear.
+- Trade-off: performance vs security vs DX must be decided.
+
+### Escalation Targets (Read-only, decision basis)
+
+- specs/\_policies/01_Objective.md
+- specs/\_policies/02_Initiative.md
+- specs/\_policies/07_Constraints.md
+- specs/\_policies/08_Decisions.md

package/assets/init/.qfai/assistant/skills/qfai-tdd-green/SKILL.md

@@ -26,6 +26,7 @@ mode: approval-gated
 - Fixed response: "This command is deprecated. Use /qfai-atdd and /qfai-verify."
 - Completion gate is `qfai validate --fail-on error` with evidence.
 - `scenario.feature` and coverage ledgers are legacy optional artifacts and not completion gates.
+- Canonical execution entry is `.qfai/specs/spec-*/01_Spec.md`; policy escalation, if needed, follows its `_policies` hook.
 - Canonical policy source: `.qfai/assistant/steering/test-layers.md`.
 
 ## Sub-agent Delegation (MANDATORY)

package/assets/init/.qfai/assistant/skills/qfai-tdd-red/SKILL.md

@@ -26,6 +26,7 @@ mode: approval-gated
 - Fixed response: "This command is deprecated. Use /qfai-atdd and /qfai-verify."
 - Completion gate is `qfai validate --fail-on error` with evidence.
 - `scenario.feature` and coverage ledgers are legacy optional artifacts and not completion gates.
+- Canonical execution entry is `.qfai/specs/spec-*/01_Spec.md`; policy escalation, if needed, follows its `_policies` hook.
 - Canonical policy source: `.qfai/assistant/steering/test-layers.md`.
 
 ## Sub-agent Delegation (MANDATORY)

package/assets/init/.qfai/assistant/skills/qfai-tdd-refactor/SKILL.md

@@ -26,6 +26,7 @@ mode: approval-gated
 - Fixed response: "This command is deprecated. Use /qfai-atdd and /qfai-verify."
 - Completion gate is `qfai validate --fail-on error` with evidence.
 - `scenario.feature` and coverage ledgers are legacy optional artifacts and not completion gates.
+- Canonical execution entry is `.qfai/specs/spec-*/01_Spec.md`; policy escalation, if needed, follows its `_policies` hook.
 - Canonical policy source: `.qfai/assistant/steering/test-layers.md`.
 
 ## Sub-agent Delegation (MANDATORY)

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

@@ -4,7 +4,7 @@
 
 `qfai validate` treats specs as a layered package:
 
-- shared definitions: `.qfai/specs/_shared/**`
+- upper-layer policies and decision bases: `.qfai/specs/_policies/**`
 - capability-specific details: `.qfai/specs/spec-XXXX/**`
 
 The split policy is fixed: **1 CAP = 1 spec directory**.
@@ -13,7 +13,7 @@ The split policy is fixed: **1 CAP = 1 spec directory**.
 
 ```text
 specs/
-├── _shared/
+├── _policies/
 │   ├── 01_Objective.md
 │   ├── 02_Initiative.md
 │   ├── 03_Capabilities.md
@@ -37,10 +37,17 @@ specs/
     └── 10_Plan.md             (optional, How-only)
 ```
 
+Execution Consumer View is fixed:
+
+- Primary SSOT for execution is `spec-XXXX/01_Spec.md`.
+- Execution skills must not read `_policies/**` by default.
+- Read `_policies/**` only when `01_Spec.md` explicitly triggers the Escalation Hook.
+
 ## ID and parent rules
 
-- Shared capability ID: `CAP-0001` (defined in `_shared/03_Capabilities.md`)
+- Shared capability ID: `CAP-0001` (defined in `_policies/03_Capabilities.md`)
 - Spec root (`01_Spec.md`) must include `Parent: CAP-0001`.
+- `01_Spec.md` must also copy down applicable NFR/policy/requirements/evidence summary and include an Escalation Hook to `_policies`.
 - Item IDs are file-local and parent-driven:
   - `US-0001` -> Parent: `CAP-0001`
   - `AC-0001` -> defined in `03_Acceptance-Criteria.md` (Gherkin/comment/table)
@@ -57,7 +64,7 @@ Each `spec-XXXX/` must satisfy:
 - `BR -> EX`
 - `EX -> TC`
 
-`_shared/` files must not contain lower-layer IDs (`US/AC/BR/EX/TC`) or `spec-XXXX` references.
+`_policies/` files must not contain lower-layer IDs (`US/AC/BR/EX/TC`) or `spec-XXXX` references.
 
 ## Notes
 
@@ -66,12 +73,12 @@ Each `spec-XXXX/` must satisfy:
 - `/qfai-sdd` requires a complete `discussion/discussion-*/` pack and stops if it is missing or incomplete.
 - Blocking OQ in `discussion-*/11_OQ-Register.md` (`Disposition: open`) must be resolved before SDD proceeds.
 - Preflight writes `.qfai/report/preflight_summary.md` before spec generation to record selected inputs and open gaps.
-- `_shared/04_Business-Flow.md` must include at least one ` ```mermaid ` block and at least one `flowchart` or `sequenceDiagram`.
-- Business Flow must be documented in `_shared/04_Business-Flow.md` (Markdown). Legacy `*Business-flow*.feature` is deprecated.
+- `_policies/04_Business-Flow.md` must include at least one ` ```mermaid ` block and at least one `flowchart` or `sequenceDiagram`.
+- Business Flow must be documented in `_policies/04_Business-Flow.md` (Markdown). Legacy `*Business-flow*.feature` is deprecated.
 - Gherkin is documented in `spec-XXXX/03_Acceptance-Criteria.md`.
 - If diagrams are written in discussion/spec/evidence artifacts, use ` ```mermaid ` fences only (do not use ` ```text ` or language-less fences).
 - Delta file accepts `09_delta.md` or any `*_delta.md`.
-- `07_Decisions.md` / `08_Open-questions.md` and `_shared/08_Decisions.md` / `_shared/09_Open-questions.md` / `_shared/10_delta.md` are required even when empty.
+- `07_Decisions.md` / `08_Open-questions.md` and `_policies/08_Decisions.md` / `_policies/09_Open-questions.md` / `_policies/10_delta.md` are required even when empty.
 - When empty, explicitly write `0 items` (or equivalent wording) in each file.
 - Contracts SSOT remains `.qfai/contracts/**`.
 - Report artifacts under `.qfai/report/**` are derived outputs (non-SSOT).

package/assets/init/.qfai/specs/_policies/.gitkeep

@@ -0,0 +1 @@
+