qfai 0.5.0 → 0.6.0

package/README.md

@@ -21,13 +21,16 @@ npx qfai report
 - `npx qfai init` によるテンプレート生成（specs/contracts に加え、`.qfai/require/README.md`、`.qfai/rules/pnpm.md`、`.qfai/prompts/require-to-spec.md`、`.qfai/prompts/qfai-generate-test-globs.md`、`.qfai/prompts/qfai-maintain-traceability.md`、`.qfai/prompts/qfai-maintain-contracts.md`、`.qfai/prompts/qfai-classify-change.md`、`.qfai/promptpack/` を含む）
 - `npx qfai validate` による `.qfai/` 内ドキュメントの整合性・トレーサビリティ検査
 - `npx qfai validate` による SC→Test 参照の検証（`validation.traceability.testFileGlobs` に一致するテストファイルから `QFAI:SC-xxxx` を抽出）
+- `npx qfai doctor` による設定/探索/パス/glob/validate.json の事前診断
 - `npx qfai report` によるレポート出力
 
 ## Usage
 
 `validate` は `--fail-on` / `--strict` によって CI ゲート化できます。`validate` は常に `.qfai/out/validate.json`（`output.validateJsonPath`）へ JSON を出力し、`--format` は表示形式（text/github）のみを制御します。
 `report` は `.qfai/out/validate.json` を読み、既定で `.qfai/out/report.md` を出力します（`--format json` の場合は `.qfai/out/report.json`）。出力先は `--out` で変更できます。入力パスは固定です。
+`doctor` は validate/report の前段で設定/探索/パス/glob/validate.json を診断します。`--format text|json`、`--out` をサポートします。
 `init --yes` は予約フラグです（現行の init は非対話のため挙動差はありません）。既存ファイルがある場合は `--force` が必要です。
+`report.json` は experimental（互換保証なし）として扱います。`reportFormatVersion` を含み、破壊的変更時のみ増分します。
 
 設定はリポジトリ直下の `qfai.config.yaml` で行います。
 命名規約は `docs/rules/naming.md` を参照してください。
@@ -35,15 +38,16 @@ npx qfai report
 ## Contracts
 
 Spec では `QFAI-CONTRACT-REF:` 行で参照する契約IDを宣言します（`none` 可、宣言行は必須）。
+Scenario では `# QFAI-CONTRACT-REF:` のコメント行で契約参照を宣言します（`none` 可、宣言行は必須）。
 契約ファイルは `QFAI-CONTRACT-ID: <ID>` を **1ファイル1ID** で宣言します。
 Contract ID prefix は `UI-0001` / `API-0001` / `DB-0001` です。
 宣言では大文字（`UI-0001`）、ファイル名は小文字（`ui-0001-...`）を使用します。
 
 契約関連の検証は `validation.traceability` で制御します。
 
-- `validation.traceability.allowOrphanContracts`: Spec から参照されない契約の許可（default: `false`）
+- `validation.traceability.orphanContractsPolicy`: Spec から参照されない契約の扱い（default: `error`、`error` / `warning` / `allow`）
 - `validation.traceability.unknownContractIdSeverity`: Scenario が参照した契約 ID が存在しない場合の severity（default: `error`、`error` / `warning` のみ）
-- Spec の `QFAI-CONTRACT-REF` が未知 ID を参照した場合は常に error（`QFAI-TRACE-021`）
+- Spec の `QFAI-CONTRACT-REF` が未知 ID を参照した場合は常に error（`QFAI-TRACE-024`）
 - `unknownContractIdSeverity` は Scenario 側（`QFAI-TRACE-008`）のみを制御
 
 `npx qfai init` は `.qfai/contracts/` 配下に UI/API/DB のサンプルを生成します。

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

@@ -9,10 +9,14 @@ npx qfai validate --fail-on error --format github
 npx qfai report
 ```
 
+`validate.json` が無い場合は `npx qfai report --run-validate` を使うか、
+`--in <path>` で入力ファイルを指定してください。
+
 ## トレーサビリティ（SC→Test）
 
 - `validation.traceability.testFileGlobs` に一致するテストコードで `QFAI:SC-xxxx` を参照する（コメント可）
 - Spec→Contract は `spec.md` の `QFAI-CONTRACT-REF` 行で宣言する
+- Scenario→Contract は `scenario.md` の `# QFAI-CONTRACT-REF` で宣言する（none 可）
 
 ## ディレクトリ概要
 
@@ -44,6 +48,7 @@ npx qfai report
 
 - 設定ファイル: `qfai.config.yaml`（リポジトリ直下）
 - CI テンプレ: `.github/workflows/qfai.yml`
+- monorepo では `paths.outDir` をパッケージ単位に分けて衝突を避ける
 
 ## Prompts の使い方（重要）
 
@@ -63,3 +68,4 @@ npx qfai report
 
 - 入口: `promptpack/constitution.md`
 - 手動配置の例: Copilot/Claude/Codex 向けの指示ファイル
+- PromptPack は非契約です（互換保証なし）。編集する場合はラップ運用や差分管理を推奨します。

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

@@ -1,6 +1,6 @@
 # Contracts (UI / API / DB)
 
-契約は「システム外部との約束」を明文化する場所です。Spec（spec.md）の `QFAI-CONTRACT-REF` による参照が必須で、これが Spec→Contract 対応の SSOT になります。Scenario からの参照は任意です。
+契約は「システム外部との約束」を明文化する場所です。Spec（spec.md）の `QFAI-CONTRACT-REF` による参照が必須で、これが Spec→Contract 対応の SSOT になります。Scenario は `# QFAI-CONTRACT-REF` で契約参照を宣言します（none 可）。
 
 ## 置くべきファイル
 
@@ -63,7 +63,7 @@ CREATE TABLE sample_table (
 ## 依存関係
 
 - Spec → Contracts（spec.md に `QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`。この行が SSOT）
-- Scenario → Contracts（UI/API/DB の参照は任意。付けるなら関連が強い箇所に限定）
+- Scenario → Contracts（scenario.md に `# QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`）
 
 ## 良い例 / 悪い例
 

package/assets/init/.qfai/promptpack/steering/traceability.md

@@ -8,7 +8,8 @@
 - 「Hard Gate」: `--fail-on error` で CI を止める領域
 
 - Spec は QFAI-CONTRACT-REF で契約IDを宣言する（none可、宣言行は必須）
-- Scenario は @SPEC-xxxx / @SC-xxxx / @BR-xxxx を持つ（契約ID参照は任意）
+- Scenario は @SPEC-xxxx / @SC-xxxx / @BR-xxxx を持つ
+- Scenario は `# QFAI-CONTRACT-REF` で契約参照を宣言する（none 可、宣言行は必須）
 - テスト/コードは QFAI:SC-xxxx で SC を参照する
 - Spec はテスト/実装（src/tests）を参照しない
 

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

@@ -25,7 +25,7 @@
 
 - 既存の Contract ID を無断で変更しない
 - ID 形式（`UI|API|DB-0001`）を崩さない
-- allowOrphanContracts の変更を無断で行わない
+- orphanContractsPolicy の変更を無断で行わない
 
 ## 出力フォーマット
 

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

@@ -45,6 +45,8 @@ QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
 ## Scenario（scenario.md）最小要件
 
 - **Gherkin 記法**（Given/When/Then）
+- **1ファイル = 1 Scenario**（Scenario Outline 含む）
+- `# QFAI-CONTRACT-REF: ...` をコメント行で **必須宣言**（参照なしは `none`）
 - `@SPEC-xxxx` は Feature レベルに **ちょうど1つ**必要
 - Scenario / Scenario Outline には `@SC-xxxx` が **ちょうど1つ**必要
 - Scenario / Scenario Outline には `@BR-xxxx` が **1つ以上**必要
@@ -53,6 +55,6 @@ QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
 
 - Spec: 必須セクション、SPEC/BR ID、BR Priority、ID 形式、Contract 参照の実在性、Contract 参照の必須宣言
 - Delta: 変更区分（互換/変更）のチェック状態
-- Scenario: Feature/Scenario の存在、タグ要件、Given/When/Then
+- Scenario: Feature/Scenario の存在、タグ要件、Given/When/Then、契約参照の宣言/形式
 - Traceability: BR→SC、Spec→Contract、SC→Test の接続、BR の所属 SPEC 整合
 - IDs: 定義 ID の重複検知（Spec/Scenario/Contracts）

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

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

package/assets/init/root/qfai.config.yaml

@@ -27,7 +27,7 @@ validation:
       - src/**/*.spec.ts
     testFileExcludeGlobs: []
     scNoTestSeverity: error
-    allowOrphanContracts: false
+    orphanContractsPolicy: error
     unknownContractIdSeverity: error
 output:
   validateJsonPath: .qfai/out/validate.json