qfai 0.2.5 → 0.2.6

package/README.md

@@ -1,4 +1,4 @@
-# QFAI Toolkit (v0.2.5)
+# QFAI Toolkit (v0.2.6)
 
 Single-package distribution for QFAI.
 

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

@@ -0,0 +1,42 @@
+# QFAI Project Kit (.qfai)
+
+このディレクトリは QFAI の成果物を集約する専用領域です。`.qfai` 配下だけを見れば「何を書くか」「どこから始めるか」が分かる構成にしています。
+
+## 最短成功（init → validate → report）
+
+```bash
+npx qfai validate --fail-on error --format github --json-path .qfai/out/validate.json
+npx qfai report --json-path .qfai/out/validate.json --out .qfai/out/report.md
+```
+
+## ディレクトリ概要
+
+- `spec/` : 仕様・シナリオ・ADR（意思決定）を置く場所
+- `contracts/` : UI / API / DB 契約を置く場所
+- `prompts/` : 生成プロンプト資産（自動読取はしない）
+- `out/` : `validate` / `report` の出力先（gitignore 推奨）
+
+詳細は各 README を参照してください。
+
+- `spec/README.md`
+- `spec/decisions/README.md`
+- `contracts/README.md`
+- `prompts/README.md`
+- `out/README.md`
+
+## 設定と CI
+
+- 設定ファイル: `qfai.config.yaml`（リポジトリ直下）
+- CI テンプレ: `.github/workflows/qfai.yml`
+
+## Prompts の使い方（重要）
+
+`prompts/` は **人間が手動で使う資産**です。v0.2.6 では自動読取を行いません。
+
+例:
+
+- Copilot: `.github/copilot-instructions.md` に要旨を転記
+- Claude: `CLAUDE.md` に要旨を転記
+- Codex: `AGENTS.md` に要旨を転記
+
+詳細は `prompts/README.md` を参照してください。

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

@@ -0,0 +1,59 @@
+# Contracts (UI / API / DB)
+
+契約は「システム外部との約束」を明文化する場所です。Scenario から参照される前提で作成します。
+
+## 置くべきファイル
+
+- UI: `ui/ui-0001-<slug>.yaml` または `.yml`
+- API: `api/api-0001-<slug>.yaml` / `.yml` / `.json`（OpenAPI）
+- DB: `db/db-0001-<slug>.sql`（ID は `DATA-xxxx`）
+
+## 最小例（UI）
+
+```yaml
+id: UI-0001
+name: 受注登録画面
+refs:
+  - BR-0001
+```
+
+## 最小例（API）
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Sample API
+  version: 0.1.0
+paths:
+  /health:
+    get:
+      operationId: API-0001
+      responses:
+        "200":
+          description: OK
+```
+
+## 最小例（DB）
+
+```sql
+-- DATA-0001
+CREATE TABLE sample_table (
+  id INTEGER PRIMARY KEY
+);
+```
+
+## CI でチェックされること（抜粋）
+
+- UI: YAML 解析、`id` が `UI-` で始まる
+- API: OpenAPI 定義があること
+- DB: 危険 SQL（DROP/TRUNCATE 等）の警告
+- 共通: ID 形式の検証
+
+## 依存関係
+
+- Scenario → Contracts（UI/API/DATA のいずれかへ接続）
+
+## 良い例 / 悪い例
+
+- 良い例: `@SC-xxxx` から `UI-xxxx` が参照されている
+- 悪い例: 契約が Scenario から一切参照されない

package/assets/init/{qfai → .qfai}/contracts/api/api-0001-sample.yaml

@@ -1,3 +1,6 @@
+# OpenAPI contract sample (API-0001)
+# - 必須: openapi, info, paths
+# - 参照: BR/SC の ID を x-qfai-refs に記載
 openapi: 3.0.0
 info:
   title: QFAI Sample API

package/assets/init/{qfai → .qfai}/contracts/db/db-0001-sample.sql

@@ -1,5 +1,6 @@
--- DATA-0001
+-- DATA-0001 (DB contract sample)
+-- 破壊的 SQL (削除/破棄系) は警告対象
 CREATE TABLE sample_table (
   id INTEGER PRIMARY KEY,
   name VARCHAR(255) NOT NULL
-);
+);

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

@@ -0,0 +1,6 @@
+# UI contract sample (UI-0001)
+# - 必須: id (例: UI-0001), name, refs
+id: UI-0001
+name: Order Registration
+refs:
+  - BR-0001

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

@@ -0,0 +1,17 @@
+# Output (.qfai/out)
+
+`qfai validate` と `qfai report` の出力先です。
+
+## 生成されるファイル
+
+- `validate.json` : 検証結果（JSON）
+- `report.md` / `report.json` : レポート
+
+## 運用メモ
+
+- 原則として **コミットしない** ことを推奨します
+- `.gitignore` への追記例:
+
+```
+.qfai/out/
+```

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

@@ -0,0 +1,32 @@
+# Prompts (手動利用)
+
+このディレクトリのプロンプトは **手動で使う資産**です。v0.2.6 では自動読取を行いません。
+
+## 目的
+
+- Spec から overview / Business Flow を生成するための素材
+- 将来（v0.9）の adapter/emit 実装に備えた配布物
+
+## 使い方（例）
+
+1. 目的のプロンプトを開く（例: `makeOverview.md`）
+2. そのまま AI エージェントに貼り付ける
+3. 指示された出力先に生成結果を保存する
+
+### エージェント別の手動導線（例）
+
+- Copilot: `.github/copilot-instructions.md` に要旨を転記
+- Claude: `CLAUDE.md` に要旨を転記
+- Codex: `AGENTS.md` に要旨を転記
+
+※ いずれも **自動生成はしません**。必要に応じて人手で同期してください。
+
+## 出力先の例
+
+- Overview: `docs/specs/overview.md`
+- Business Flow: `docs/flows/bf-0001-<slug>.md`
+
+## CI との関係
+
+- プロンプト自体は CI の検査対象ではありません
+- 生成物をレビューし、Spec/Scenario/Contracts と整合しているかを確認してください

package/assets/init/{qfai → .qfai}/prompts/makeBusinessFlow.md

@@ -5,7 +5,7 @@ Spec群を読み、Specに明示されている情報のみを根拠として、
 
 ## Inputs
 
-- 対象: qfai/spec/spec.md と qfai/spec/spec-0001-\*.md 形式のファイル（4 桁の数字 + ハイフン + slug。実際のパターン: `spec-\d{4}-[^/\\]+\.md`。存在するもの全て）
+- 対象: .qfai/spec/spec-0001-\*.md 形式のファイル（4 桁の数字 + ハイフン + slug。実際のパターン: `spec-\d{4}-[^/\\]+\.md`。存在するもの全て）
 
 ## Output (Option)
 

package/assets/init/{qfai → .qfai}/prompts/makeOverview.md

@@ -4,7 +4,7 @@
 
 ## Inputs
 
-- 対象: qfai/spec/spec.md と qfai/spec/spec-0001-\*.md 形式のファイル（4 桁の数字 + ハイフン + slug。実際のパターン: `spec-\d{4}-[^/\\]+\.md`。存在するもの全て）
+- 対象: .qfai/spec/spec-0001-\*.md 形式のファイル（4 桁の数字 + ハイフン + slug。実際のパターン: `spec-\d{4}-[^/\\]+\.md`。存在するもの全て）
 
 ## Output
 

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

@@ -0,0 +1,77 @@
+# Spec / Scenario / Decisions
+
+このディレクトリは「仕様（Spec）」「シナリオ（Scenario）」「意思決定（ADR）」の入口です。
+
+## 置くべきファイル
+
+- Spec: `spec-0001-<slug>.md`（必須）
+- Scenario: `scenarios/*.feature`
+- Decisions: `decisions/ADR-0001.md` など
+
+## 最小例（Spec）
+
+```md
+# SPEC-0001: 注文登録の最小要件
+
+## 背景
+
+- 例: 受注の登録ルールを明文化し、手戻りを減らすため
+
+## スコープ
+
+- 例: 新規受注の登録と承認
+
+## 非ゴール
+
+- 例: 既存受注の履歴移行は対象外
+
+## 用語
+
+- 例: 受注 = 顧客からの注文情報
+
+## 前提
+
+- 例: 承認者は1名以上配置されている
+
+## 決定事項
+
+- 例: 承認は1段階で完了とする
+
+## 業務ルール
+
+- [BR-0001] 受注は承認者が承認するまで確定しない
+- [BR-0002] 承認済みの受注のみ出荷依頼に進める
+```
+
+## BR の書き方（重要）
+
+- **1 ルール = 1 BR** を守る
+- 小項目がある場合は **別 BR を採番**する（`BR-0001.1` は使わない）
+- 参照は常に BR ID を使う
+
+## Scenario の最小要件
+
+- `@SC-xxxx` / `@SPEC-xxxx` / `@BR-xxxx` をタグで明示
+- `Given / When / Then` を含める
+- UI/API/DATA 契約に接続する（トレーサビリティのエラー回避）
+
+## CI でチェックされること（抜粋）
+
+- Spec: 必須セクションの有無、SPEC/BR ID の存在、ID 形式
+- Scenario: SC/SPEC/BR の参照、Given/When/Then の有無
+- Traceability: BR→SC、SC→契約（UI/API/DATA）の接続
+
+## 依存関係
+
+- Spec → Scenario → Contracts
+- Decisions（ADR）→ Spec / BR
+
+## 良い例 / 悪い例
+
+- 良い例: `BR-0001` が Scenario で参照され、UI/API/DATA のいずれかに接続している
+- 悪い例: Spec に `SC-xxxx` を書く（Spec は SC を参照しない）
+
+## 良い運用 / 悪い運用
+
+- 良い運用: Spec/Scenario/Contracts を同じ ID でつなぐ
+- 悪い運用: Spec の BR が Scenario に出てこない（孤立）

package/assets/init/.qfai/spec/decisions/ADR-0001.md

@@ -0,0 +1,9 @@
+# ADR-0001: 承認フローは1段階にする
+
+> このファイルは「なぜその判断をしたか」を残すためのテンプレです。
+
+- Status: Proposed
+- Context: 承認者を増やすと運用が複雑になる
+- Decision: v0.2.6 では1段階の承認に固定する
+- Consequences: 多段承認が必要な場合は拡張が必要
+- Related: BR-0001, SPEC-0001

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

@@ -0,0 +1,36 @@
+# ADR (Architecture Decision Record)
+
+ADR は「なぜその判断をしたか」を記録するための軽量な意思決定ログです。
+
+## いつ書くか
+
+- 仕様の前提や制約が変わるとき
+- 技術選定や設計方針を決めたとき
+- 重要なトレードオフがあるとき
+
+## 最小例
+
+```md
+# ADR-0001: 承認フローは1段階にする
+
+- Status: Proposed
+- Context: 承認者を増やすと運用が複雑になる
+- Decision: v0.2.6 では1段階の承認に固定する
+- Consequences: 多段承認が必要な場合は拡張が必要
+- Related: BR-0001, SPEC-0001
+```
+
+## CI でチェックされること（抜粋）
+
+- ID 形式（`BR-xxxx` / `SPEC-xxxx` など）
+- 参照 ID の整合性（トレーサビリティ）
+
+## 依存関係
+
+- ADR は Spec / BR と一緒に参照される
+- Scenario/Contracts から参照されることは少ない
+
+## 良い例 / 悪い例
+
+- 良い例: Context/Decision/Consequences が簡潔に書かれている
+- 悪い例: Decision が空のまま放置されている

package/assets/init/.qfai/spec/scenarios/scenarios.feature

@@ -0,0 +1,6 @@
+@SC-0001 @BR-0001 @SPEC-0001 @UI-0001 @API-0001 @DATA-0001
+Feature: Order registration
+  Scenario: Register a new order
+    Given no order exists for the customer
+    When the user submits a new order
+    Then the order is created as pending approval

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

@@ -0,0 +1,36 @@
+# SPEC-0001: 注文登録の最小仕様（サンプル）
+
+> このテンプレは **最小例** です。実際の仕様に合わせて書き換えてください。
+
+## 背景
+
+- 例: 受注の登録ルールを統一し、手戻りを減らす
+
+## スコープ
+
+- 例: 新規受注の登録と承認
+
+## 非ゴール
+
+- 例: 既存受注の履歴移行は対象外
+
+## 用語
+
+- 例: 受注 = 顧客からの注文情報
+
+## 前提
+
+- 例: 承認者は1名以上配置されている
+
+## 決定事項
+
+- 例: 承認は1段階で完了とする
+
+## 業務ルール
+
+- [BR-0001] 受注は承認者が承認するまで確定しない
+
+### 書き方メモ
+
+- BR は **原子ルール** として採番する（`BR-0001.1` は使わない）
+- Spec では **SC ID** を参照しない

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

@@ -1,12 +1,12 @@
 paths:
-  specDir: qfai/spec
-  decisionsDir: qfai/spec/decisions
-  scenariosDir: qfai/spec
-  rulesDir: qfai/rules
-  contractsDir: qfai/contracts
-  uiContractsDir: qfai/contracts/ui
-  apiContractsDir: qfai/contracts/api
-  dataContractsDir: qfai/contracts/db
+  specDir: .qfai/spec
+  decisionsDir: .qfai/spec/decisions
+  scenariosDir: .qfai/spec/scenarios
+  rulesDir: .qfai/rules
+  contractsDir: .qfai/contracts
+  uiContractsDir: .qfai/contracts/ui
+  apiContractsDir: .qfai/contracts/api
+  dataContractsDir: .qfai/contracts/db
   srcDir: src
   testsDir: tests
 validation:

package/dist/cli/index.cjs

@@ -131,9 +131,9 @@ function error(message) {
 async function runInit(options) {
   const assetsRoot = getInitAssetsDir();
   const rootAssets = import_node_path3.default.join(assetsRoot, "root");
-  const qfaiAssets = import_node_path3.default.join(assetsRoot, "qfai");
+  const qfaiAssets = import_node_path3.default.join(assetsRoot, ".qfai");
   const destRoot = import_node_path3.default.resolve(options.dir);
-  const destQfai = import_node_path3.default.join(destRoot, "qfai");
+  const destQfai = import_node_path3.default.join(destRoot, ".qfai");
   const rootResult = await copyTemplateTree(rootAssets, destRoot, {
     force: options.force,
     dryRun: options.dryRun
@@ -169,14 +169,14 @@ var import_node_path4 = __toESM(require("path"), 1);
 var import_yaml = require("yaml");
 var defaultConfig = {
   paths: {
-    specDir: "qfai/spec",
-    decisionsDir: "qfai/spec/decisions",
-    scenariosDir: "qfai/spec",
-    rulesDir: "qfai/rules",
-    contractsDir: "qfai/contracts",
-    uiContractsDir: "qfai/contracts/ui",
-    apiContractsDir: "qfai/contracts/api",
-    dataContractsDir: "qfai/contracts/db",
+    specDir: ".qfai/spec",
+    decisionsDir: ".qfai/spec/decisions",
+    scenariosDir: ".qfai/spec/scenarios",
+    rulesDir: ".qfai/rules",
+    contractsDir: ".qfai/contracts",
+    uiContractsDir: ".qfai/contracts/ui",
+    apiContractsDir: ".qfai/contracts/api",
+    dataContractsDir: ".qfai/contracts/db",
     srcDir: "src",
     testsDir: "tests"
   },
@@ -582,8 +582,7 @@ async function exists2(target) {
 }
 
 // src/core/discovery.ts
-var LEGACY_SPEC_NAME = "spec.md";
-var SPEC_NAMED_PATTERN = /^spec-\d{4}-[^/\\]+\.md$/i;
+var SPEC_NAMED_PATTERN = /^spec-\d{4}-[^/\\]+\.md$/;
 async function collectSpecFiles(specRoot) {
   const files = await collectFiles(specRoot, { extensions: [".md"] });
   return files.filter((file) => isSpecFile(file));
@@ -607,7 +606,7 @@ async function collectContractFiles(uiRoot, apiRoot, dataRoot) {
 }
 function isSpecFile(filePath) {
   const name = import_node_path6.default.basename(filePath).toLowerCase();
-  return name === LEGACY_SPEC_NAME || SPEC_NAMED_PATTERN.test(name);
+  return SPEC_NAMED_PATTERN.test(name);
 }
 
 // src/core/ids.ts
@@ -668,8 +667,8 @@ var import_promises4 = require("fs/promises");
 var import_node_path7 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 async function resolveToolVersion() {
-  if ("0.2.5".length > 0) {
-    return "0.2.5";
+  if ("0.2.6".length > 0) {
+    return "0.2.6";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -1068,10 +1067,11 @@ async function validateSpecs(root, config) {
   const specsRoot = resolvePath(root, config, "specDir");
   const files = await collectSpecFiles(specsRoot);
   if (files.length === 0) {
+    const expected = "spec-0001-<slug>.md";
     return [
       issue3(
         "QFAI-SPEC-000",
-        "Spec \u30D5\u30A1\u30A4\u30EB\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002",
+        `Spec \u30D5\u30A1\u30A4\u30EB\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002\u914D\u7F6E\u5834\u6240: ${config.paths.specDir} / \u671F\u5F85\u30D1\u30BF\u30FC\u30F3: ${expected}`,
         "info",
         specsRoot,
         "spec.files"