qfai 1.0.1 → 1.0.3

package/README.md

@@ -79,7 +79,7 @@ QFAI が提供するプロンプト資産は次の 2 つに分離します。
 
 同じ相対パスのファイルがある場合は `.qfai/prompts.local` を優先して参照する運用とします。
 
-`report.json` / `doctor.json` は内部表現で互換非保証です。外部連携は `report.md` など Markdown 出力を推奨します。破壊的変更は SemVer で管理しますが、JSON schema を固定する約束はしません。短い例:
+`report.json` / `doctor.json` は内部表現で互換非保証です。外部連携は `report.md` など Markdown 出力を推奨します。破壊的変更は原則 SemVer で管理しますが、プロジェクト方針により例外的に minor/patch で破壊的変更を行う場合があります（CHANGELOG に明記）。JSON schema を固定する約束はしません。短い例:
 
 ```json
 {
@@ -87,7 +87,7 @@ QFAI が提供するプロンプト資産は次の 2 つに分離します。
   "summary": {
     "specs": 1,
     "scenarios": 1,
-    "contracts": { "api": 0, "ui": 1, "db": 0 },
+    "contracts": { "api": 0, "ui": 1, "db": 0, "thema": 0 },
     "counts": { "info": 0, "warning": 0, "error": 0 }
   }
 }
@@ -157,6 +157,8 @@ analyze も `.qfai/prompts.local/**` の overlay 運用に従います。
 Spec では `QFAI-CONTRACT-REF:` 行で参照する契約IDを宣言します（`none` 可）。Spec の先頭 H1 に `SPEC-xxxx` が必須です。
 Scenario では `# QFAI-CONTRACT-REF:` のコメント行で契約参照を宣言します（`none` 可）。
 契約ファイルは `QFAI-CONTRACT-ID: <ID>` を **1ファイル1ID** で宣言します。
+契約IDは UI/API/DB/THEMA（THEMA は 3 桁）です。UI 契約は `themaRef` / `themeOverrides` / `assets` を追加できます。
+`assets.pack` は `ui/` 配下の相対パス、`assets.use` は `assets.yaml` の `items[].id` を参照します。
 `validate.json` / `report` の file path は root 相対で出力します（absolute は出力しません）。
 
 ## Monorepo / サブディレクトリ
@@ -239,7 +241,7 @@ qfai.config.yaml
     spec-0001/
       spec.md
       delta.md
-      scenario.md
+      scenario.feature
   rules/
     conventions.md
     pnpm.md
@@ -278,6 +280,14 @@ qfai.config.yaml
       api-0001-sample.yaml
     ui/
       ui-0001-sample.yaml
+      thema-001-facebook-like.yml
+      assets/
+        ui-0001-sample/
+          assets.yaml
+          snapshots/login__desktop__light__default.png
+        thema-001-facebook-like/
+          assets.yaml
+          palette.png
     db/
       db-0001-sample.sql
   out/

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

@@ -17,11 +17,11 @@ npx qfai report
 
 - `validation.traceability.testFileGlobs` に一致するテストコードで `QFAI:SC-xxxx` を参照する（コメント可）
 - Spec→Contract は `spec.md` の `QFAI-CONTRACT-REF` 行で宣言する
-- Scenario→Contract は `scenario.md` の `# QFAI-CONTRACT-REF` で宣言する（none 可）
+- Scenario→Contract は `scenario.feature` の `# QFAI-CONTRACT-REF` で宣言する（none 可）
 
 ## ディレクトリ概要
 
-- `specs/` : Spec Pack（spec.md / delta.md / scenario.md）
+- `specs/` : Spec Pack（spec.md / delta.md / scenario.feature）
 - `contracts/` : UI / API / DB 契約を置く場所
 - `require/` : 既存要件の集約（validate 対象外）
 - `rules/` : 規約・運用ルール

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

@@ -5,8 +5,10 @@
 ## 置くべきファイル
 
 - UI: `ui/ui-0001-<slug>.yaml` または `.yml`
+- THEMA: `ui/thema-001-<slug>.yml`（3桁）
 - API: `api/api-0001-<slug>.yaml` / `.yml` / `.json`（OpenAPI）
 - DB: `db/db-0001-<slug>.sql`（ID は `DB-xxxx`）
+- assets: `ui/assets/<contract-id>/assets.yaml`（参照整合のみ検証）
 
 ## 契約ID宣言（必須）
 
@@ -23,6 +25,24 @@ id: UI-0001
 name: 受注登録画面
 refs:
   - BR-0001
+themaRef: THEMA-001
+assets:
+  pack: assets/ui-0001-sample
+  use:
+    - UI-0001.desktop.light.default
+```
+
+## 最小例（THEMA）
+
+```yaml
+# QFAI-CONTRACT-ID: THEMA-001
+id: THEMA-001
+name: facebook-like
+tokens:
+  color:
+    background: "#FFFFFF"
+    textPrimary: "#111111"
+    accent: "#1877F2"
 ```
 
 ## 最小例（API）
@@ -63,7 +83,7 @@ CREATE TABLE sample_table (
 ## 依存関係
 
 - Spec → Contracts（spec.md に `QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`。この行が SSOT）
-- Scenario → Contracts（scenario.md に `# QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`）
+- Scenario → Contracts（scenario.feature に `# QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`）
 
 ## 良い例 / 悪い例
 

package/assets/init/.qfai/contracts/ui/assets/thema-001-facebook-like/assets.yaml

@@ -0,0 +1,6 @@
+packId: THEMA-001
+type: thema
+items:
+  - id: THEMA-001.palette.default
+    kind: snapshot
+    path: palette.png

package/assets/init/.qfai/contracts/ui/assets/ui-0001-sample/assets.yaml

@@ -0,0 +1,6 @@
+packId: UI-0001
+type: ui
+items:
+  - id: UI-0001.desktop.light.default
+    kind: snapshot
+    path: snapshots/login__desktop__light__default.png

package/assets/init/.qfai/contracts/ui/thema-001-facebook-like.yml

@@ -0,0 +1,13 @@
+# QFAI-CONTRACT-ID: THEMA-001
+id: THEMA-001
+name: facebook-like
+tokens:
+  color:
+    background: "#FFFFFF"
+    textPrimary: "#111111"
+    accent: "#1877F2"
+components:
+  Button:
+    primary:
+      backgroundToken: "color.accent"
+      textToken: "color.background"

package/assets/init/.qfai/contracts/ui/ui-0001-sample.yaml

@@ -6,3 +6,12 @@ id: UI-0001
 name: Order Registration
 refs:
   - BR-0001
+themaRef: THEMA-001
+themeOverrides:
+  Button:
+    primary:
+      backgroundToken: "color.accent"
+assets:
+  pack: assets/ui-0001-sample
+  use:
+    - UI-0001.desktop.light.default

package/assets/init/.qfai/prompts/makeBusinessFlow.md

@@ -5,7 +5,7 @@ Spec群を読み、Specに明示されている情報のみを根拠として、
 
 ## Inputs
 
-- 対象: `.qfai/specs/spec-*/spec.md` 形式のファイル（Spec Pack の `spec.md`。必要に応じて `scenario.md` / `delta.md` も補助参照）
+- 対象: `.qfai/specs/spec-*/spec.md` 形式のファイル（Spec Pack の `spec.md`。必要に応じて `scenario.feature` / `delta.md` も補助参照）
 
 ## Output (Option)
 

package/assets/init/.qfai/prompts/makeOverview.md

@@ -4,7 +4,7 @@
 
 ## Inputs
 
-- 対象: `.qfai/specs/spec-*/spec.md` 形式のファイル（Spec Pack の `spec.md`。必要に応じて `scenario.md` / `delta.md` も補助参照）
+- 対象: `.qfai/specs/spec-*/spec.md` 形式のファイル（Spec Pack の `spec.md`。必要に応じて `scenario.feature` / `delta.md` も補助参照）
 
 ## Output
 

package/assets/init/.qfai/prompts/qfai-maintain-traceability.md

@@ -9,7 +9,7 @@
 
 ## 必須入力
 
-- `.qfai/specs/**/spec.md` / `scenario.md` / `delta.md`
+- `.qfai/specs/**/spec.md` / `scenario.feature` / `delta.md`
 - `.qfai/out/validate.json`（あれば）
 - `.qfai/out/report.md`（あれば）
 - テストコード（`validation.traceability.testFileGlobs` に一致する範囲）

package/assets/init/.qfai/prompts/require-to-spec.md

@@ -11,7 +11,7 @@
 
 - `.qfai/specs/spec-0001/spec.md`
 - `.qfai/specs/spec-0001/delta.md`
-- `.qfai/specs/spec-0001/scenario.md`
+- `.qfai/specs/spec-0001/scenario.feature`
 - 必要に応じて `.qfai/contracts/{ui,api,db}` 配下
 
 > Spec は `spec-0001` から開始し、必要なら連番で増やすこと。
@@ -23,7 +23,7 @@
 - `spec.md` の必須セクションは `qfai.config.yaml` の設定に従う。
 - BR は `## 業務ルール` にのみ定義し、`- [BR-0001][P1] ...` 形式で書く。
 - `spec.md` に `QFAI-CONTRACT-REF:` を必ず記載する（不要なら `none`）。
-- `scenario.md` は Gherkin で書き、Feature に `@SPEC-xxxx` を付与する。
+- `scenario.feature` は Gherkin で書き、Feature に `@SPEC-xxxx` を付与する。
 - 各 Scenario は `@SC-xxxx` を **ちょうど1つ**、`@BR-xxxx` を **1つ以上**持つこと。
 - 契約ファイルには `QFAI-CONTRACT-ID: <ID>` を宣言する。
 - 契約 ID（UI/API/DB）を Scenario で参照する場合はタグまたは本文に明示する。

package/assets/init/.qfai/samples/analyze/analysis.md

@@ -12,7 +12,7 @@
 ## 入力（貼り付けたもの）
 
 - Spec: <spec.md / delta.md の該当範囲>
-- Scenario: <scenario.md の該当範囲>
+- Scenario: <scenario.feature の該当範囲>
 - Contract（任意）: <該当契約>
 - validate/report 要約: <report.md または validate.json の要約>
 - 差分: <PR diff / 変更ファイル一覧>

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

@@ -6,7 +6,7 @@
 
 - `spec-0001/spec.md`（必須）
 - `spec-0001/delta.md`（必須）
-- `spec-0001/scenario.md`（必須・Gherkin）
+- `spec-0001/scenario.feature`（必須・Gherkin）
 
 > `spec-0001` は **4桁連番**。Spec ID も **4桁（SPEC-0001）** です。
 
@@ -15,7 +15,7 @@
 ```md
 # SPEC-0001: 注文登録の最小要件
 
-QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
+QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001, THEMA-001
 
 ## 背景
 
@@ -42,7 +42,7 @@ QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
 - 互換維持 / 仕様変更の **どちらか1つ**に必ずチェックする
 - 根拠と影響範囲を明記する
 
-## Scenario（scenario.md）最小要件
+## Scenario（scenario.feature）最小要件
 
 - **Gherkin 記法**（Given/When/Then）
 - **1ファイル = 1 Scenario**（Scenario Outline 含む）

package/assets/init/.qfai/specs/spec-0001/delta.md

@@ -16,7 +16,7 @@
 ## 影響範囲（Impact）
 
 - 仕様（spec.md）:
-- シナリオ（scenario.md）:
+- シナリオ（scenario.feature）:
 - 契約（contracts）:
 - 実装（src）:
 - テスト（tests）:

package/assets/init/.qfai/specs/spec-0001/{scenario.md → scenario.feature}

@@ -3,7 +3,7 @@ Feature: 注文登録
 
 Rule: 承認者が存在する
 
-    # QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
+    # QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001, THEMA-001
     @SC-0001 @BR-0001
     Scenario: 承認者が承認するまで注文は確定しない
       Given ...

package/assets/init/.qfai/specs/spec-0001/spec.md

@@ -1,6 +1,6 @@
 # SPEC-0001: 注文登録の最小仕様（サンプル）
 
-QFAI-CONTRACT-REF: API-0001, UI-0001, DB-0001
+QFAI-CONTRACT-REF: API-0001, UI-0001, DB-0001, THEMA-001
 
 > このテンプレは **最小例** です。実際の仕様に合わせて書き換えてください。