spec-runner 1.0.7 → 1.0.9

package/README.md

@@ -36,19 +36,26 @@ AI から使う場合は、`/spec-runner` のように「spec-runner を実行
 
 ---
 
+## フロー（全体像）
+
+設計書（`docs/01..06`）と UC 仕様（`docs/02_ユースケース仕様/`）をどんな順で作っていくかは `docs/flow.md` にまとめています。
+
+---
+
 ## 導入後にできるもの
 
 ```
 <プロジェクトルート>/
-└── .spec-runner/
-    ├── spec-runner.sh          # 入口（次のステップ --json）
-    ├── project.json            # 設定（ブランチ命名・必須ドキュメント・テストコマンド等）
-    ├── phase-locks.json        # フェーズの通過状態
-    ├── grade-history.json      # グレード（LOOP1 / A / B / C）
-    ├── scripts/                # spec-runner-core.sh, check, branch, test 等
-    ├── steps/                  # 憲章・ドメイン設計・仕様策定・曖昧さ解消・テスト設計・実装 等の .md
-    ├── templates/             # UC 仕様書ひな形
-    └── docs/                   # フロー全体・振る舞い仕様などの説明
+├── .spec-runner/
+│   ├── spec-runner.sh          # 入口（次のステップ --json）
+│   ├── project.json            # 設定（ブランチ命名・必須ドキュメント・テストコマンド等）
+│   ├── phase-locks.json        # フェーズの通過状態
+│   ├── grade-history.json      # グレード（LOOP1 / A / B / C）
+│   ├── scripts/                # spec-runner-core.sh, check, branch, test 等
+│   ├── steps/                  # 憲章・ドメイン設計・仕様策定・曖昧さ解消・テスト設計・実装 等の .md
+│   └── templates/              # UC 仕様書ひな形
+├── .claude/commands/spec-runner.md   # Claude 用コマンド定義（/spec-runner）
+└── （AI は Claude Code 前提）
 ```
 
 ---
@@ -72,6 +79,14 @@ SPEC_RUNNER_FORCE=1 npx spec-runner
 
 ---
 
+## バージョン運用ルール
+
+- このリポジトリでは、今後 **コミットごとに `package.json` の `version` を更新**する。
+- バージョンは原則として SemVer に従い、迷う場合はパッチ（`x.y.Z`）を 1 つ上げる。
+- 1コミット内で複数の変更をまとめた場合も、コミット単位で 1 回だけ更新する。
+
+---
+
 ## ライセンス
 
 MIT

package/bin/spec-runner.js

@@ -7,13 +7,18 @@
  * ゴール:
  * - `npx spec-runner` または `npm exec spec-runner` を実行すると、
  *   プロジェクト直下に `./.spec-runner/` フォルダを作成する。
- * - `./.spec-runner/spec-runner.sh 次のステップ --json` を叩けば
+ * - Claude Code から `/spec-runner` を実行すれば、
  *   「現在フェーズ」と「やるべきステップ .md」が 1 本だけ返ってくる。
  * - メッセージ・ファイルはすべて日本語のみ。
  *
  * 重要:
  * - すでに `.spec-runner/` が存在する場合はデフォルトでは上書きしない。
  *   上書きしたい場合は、環境変数 `SPEC_RUNNER_FORCE=1` を付けて実行する。
+ *
+ * 必須テンプレ（パッケージ内）:
+ * - templates/.spec-runner/project.json.example
+ * - templates/.spec-runner/templates/phase-locks.json
+ * - templates/.spec-runner/templates/grade-history.json
  */
 
 const fs = require("fs");
@@ -21,10 +26,18 @@ const path = require("path");
 
 const CWD = process.cwd();
 const PKG_DIR = path.resolve(__dirname, "..");
-// パッケージ内の公式テンプレート配置場所
 const TEMPLATE_SPEC_RUNNER_DIR = path.join(PKG_DIR, "templates", ".spec-runner");
-// 展開先（ユーザープロジェクト側）
 const DEST_DIR = path.join(CWD, ".spec-runner");
+const TEMPLATES_DIR = path.join(TEMPLATE_SPEC_RUNNER_DIR, "templates");
+const PHASE_LOCKS_TEMPLATE = path.join(TEMPLATES_DIR, "phase-locks.json");
+const GRADE_HISTORY_TEMPLATE = path.join(TEMPLATES_DIR, "grade-history.json");
+
+/** コピー時はスキップし、FORCE 時は消さない（ユーザー状態を保持） */
+const USER_STATE_BASENAMES = new Set([
+  "project.json",
+  "phase-locks.json",
+  "grade-history.json",
+]);
 
 function log(msg) {
   console.log(msg);
@@ -51,6 +64,47 @@ function exists(p) {
   }
 }
 
+function ensureTemplateDirOrExit() {
+  if (!exists(TEMPLATE_SPEC_RUNNER_DIR)) {
+    error("パッケージ内に templates/.spec-runner テンプレートが見つかりません。");
+    process.exit(1);
+  }
+  if (!exists(path.join(TEMPLATE_SPEC_RUNNER_DIR, "project.json.example"))) {
+    error("必須テンプレ project.json.example が見つかりません。");
+    process.exit(1);
+  }
+  if (!exists(PHASE_LOCKS_TEMPLATE)) {
+    error("必須テンプレ templates/phase-locks.json が見つかりません。");
+    process.exit(1);
+  }
+  if (!exists(GRADE_HISTORY_TEMPLATE)) {
+    error("必須テンプレ templates/grade-history.json が見つかりません。");
+    process.exit(1);
+  }
+}
+
+function assertDestInstallableOrExit() {
+  const force = process.env.SPEC_RUNNER_FORCE === "1";
+  if (!exists(DEST_DIR)) return;
+  if (force) {
+    info("既存の .spec-runner/ を上書きします（SPEC_RUNNER_FORCE=1）。");
+    return;
+  }
+  error(".spec-runner/ フォルダがすでに存在します。");
+  info("上書きする場合は、環境変数 SPEC_RUNNER_FORCE=1 を付けて実行してください。");
+  info("例: SPEC_RUNNER_FORCE=1 npx spec-runner");
+  process.exit(1);
+}
+
+/** FORCE 時: テンプレから消えたファイルも反映できるよう、保持対象以外を削除 */
+function wipeDestExceptUserState() {
+  if (!exists(DEST_DIR) || process.env.SPEC_RUNNER_FORCE !== "1") return;
+  for (const entry of fs.readdirSync(DEST_DIR, { withFileTypes: true })) {
+    if (USER_STATE_BASENAMES.has(entry.name)) continue;
+    fs.rmSync(path.join(DEST_DIR, entry.name), { recursive: true, force: true });
+  }
+}
+
 function copyDirRecursively(src, dest, options = {}) {
   const { skipNames = new Set() } = options;
   if (!exists(src)) return;
@@ -76,160 +130,74 @@ function copyDirRecursively(src, dest, options = {}) {
   }
 }
 
-function writeJsonPretty(destPath, obj) {
-  fs.mkdirSync(path.dirname(destPath), { recursive: true });
-  fs.writeFileSync(destPath, JSON.stringify(obj, null, 2) + "\n", "utf8");
-  ok(path.relative(CWD, destPath));
+function expandTemplateTree() {
+  copyDirRecursively(TEMPLATE_SPEC_RUNNER_DIR, DEST_DIR, {
+    skipNames: USER_STATE_BASENAMES,
+  });
 }
 
-function main() {
-  log("");
-  log("╔════════════════════════════════════════╗");
-  log("║        spec-runner インストーラ        ║");
-  log("║     フェーズ駆動 / 次のステップ方式     ║");
-  log("╚════════════════════════════════════════╝");
-  log("");
-
-  if (!exists(TEMPLATE_SPEC_RUNNER_DIR)) {
-    error("パッケージ内に templates/.spec-runner テンプレートが見つかりません。");
-    process.exit(1);
-  }
-
-  if (exists(DEST_DIR) && process.env.SPEC_RUNNER_FORCE !== "1") {
-    error(".spec-runner/ フォルダがすでに存在します。");
-    info("上書きする場合は、環境変数 SPEC_RUNNER_FORCE=1 を付けて実行してください。");
-    info("例: SPEC_RUNNER_FORCE=1 npx spec-runner");
-    process.exit(1);
-  }
-
-  if (exists(DEST_DIR) && process.env.SPEC_RUNNER_FORCE === "1") {
-    info("既存の .spec-runner/ を上書きします（SPEC_RUNNER_FORCE=1）。");
-  }
-
-  info(".spec-runner/ を展開しています...");
-  const skipNames = new Set([
-    "project.json",
-    "phase-locks.json",
-    "grade-history.json",
-  ]);
-  copyDirRecursively(TEMPLATE_SPEC_RUNNER_DIR, DEST_DIR, { skipNames });
-
-  // 2. project.json を project.json.example から生成（存在すれば）
+function bootstrapProjectJson() {
   const examplePath = path.join(TEMPLATE_SPEC_RUNNER_DIR, "project.json.example");
   const projectJsonDest = path.join(DEST_DIR, "project.json");
-  if (exists(examplePath)) {
-    const content = fs.readFileSync(examplePath, "utf8");
-    fs.writeFileSync(projectJsonDest, content, "utf8");
-    ok(path.relative(CWD, projectJsonDest));
-  } else {
-    // フォールバック（最低限の既定値）
-    const fallback = {
-      naming: {
-        branch_prefix: "feature",
-        uc_id_pattern: "UC-[0-9]{3}",
-        uc_spec_basename: "{uc_id}-{slug}.md",
-        adr_basename: "MMDD-{title}.md",
-        docs_05_categories: true,
-        other_work_prefixes: ["work", "infra", "cicd"],
-      },
-      required_docs: {
-        charter: ["docs/01_憲章/憲章.md"],
-      },
-      test_design: {
-        dir: "tests",
-        pattern: "*.spec.*",
-      },
-      test_command: {
-        run: "npm test",
-      },
-    };
-    writeJsonPretty(projectJsonDest, fallback);
+  fs.writeFileSync(projectJsonDest, fs.readFileSync(examplePath, "utf8"), "utf8");
+  ok(path.relative(CWD, projectJsonDest));
+}
+
+/**
+ * フェーズ用 JSON は templates/.spec-runner/templates/*.json を正とする。
+ * .spec-runner/ 直下に無いときだけコピー（既存のロックは上書きしない）。
+ */
+function writeInitialLocksAndGrade() {
+  const locksDest = path.join(DEST_DIR, "phase-locks.json");
+  if (!exists(locksDest)) {
+    fs.copyFileSync(PHASE_LOCKS_TEMPLATE, locksDest);
+    ok(path.relative(CWD, locksDest));
   }
 
-  // 3. phase-locks.json / grade-history.json を初期状態で作成
-  const phaseLocksDest = path.join(DEST_DIR, "phase-locks.json");
-  const gradeHistoryDest = path.join(DEST_DIR, "grade-history.json");
-
-  const phaseLocks = {
-    _comment:
-      "フェーズ完了状態の単一ソース。初期状態ではすべて未完了。レビュー状態もここで管理する。",
-    charter: {
-      completed: false,
-      phase: 0,
-      phase_name: "憲章策定",
-      locked_at: null,
-      reviewed_by: null,
-      document: "docs/01_憲章/憲章.md",
-      version: "v0.0.0",
-    },
-    domain: {
-      completed: false,
-      phase: 1,
-      phase_name: "ドメイン設計",
-      locked_at: null,
-      reviewed_by: null,
-      documents: [
-        "docs/02_ドメイン設計/ユビキタス言語辞書.md",
-        "docs/02_ドメイン設計/ドメインモデル.md",
-        "docs/02_ドメイン設計/集約.md",
-      ],
-    },
-    architecture: {
-      completed: false,
-      phase: 2,
-      phase_name: "アーキテクチャ選択",
-      locked_at: null,
-      reviewed_by: null,
-      documents: [
-        "docs/03_アーキテクチャ/パターン選定.md",
-        "docs/03_アーキテクチャ/インフラ方針.md",
-        "docs/03_アーキテクチャ/設計判断記録",
-      ],
-    },
-    infra: {
-      completed: false,
-      phase: 4,
-      phase_name: "インフラ詳細設計",
-      locked_at: null,
-    },
-    test_design: {
-      completed: false,
-    },
-    uc_reviewed: [],
-  };
-
-  const gradeHistory = {
-    current_grade: "LOOP1",
-    history: [],
-  };
-
-  writeJsonPretty(phaseLocksDest, phaseLocks);
-  writeJsonPretty(gradeHistoryDest, gradeHistory);
+  const gradeDest = path.join(DEST_DIR, "grade-history.json");
+  if (!exists(gradeDest)) {
+    fs.copyFileSync(GRADE_HISTORY_TEMPLATE, gradeDest);
+    ok(path.relative(CWD, gradeDest));
+  }
+}
 
+function installClaudeCommandIfPresent() {
   const commandTmpl = path.join(PKG_DIR, "templates", "spec-runner-command.md");
-  if (exists(commandTmpl)) {
-    const cmdContent = fs.readFileSync(commandTmpl, "utf8");
-    const claudeCmd = path.join(CWD, ".claude", "commands", "spec-runner.md");
-    const cursorCmd = path.join(CWD, ".cursor", "commands", "spec-runner.md");
-    fs.mkdirSync(path.dirname(claudeCmd), { recursive: true });
-    fs.mkdirSync(path.dirname(cursorCmd), { recursive: true });
-    fs.writeFileSync(claudeCmd, cmdContent, "utf8");
-    fs.writeFileSync(cursorCmd, cmdContent, "utf8");
-    ok(path.relative(CWD, claudeCmd));
-    ok(path.relative(CWD, cursorCmd));
-  }
+  if (!exists(commandTmpl)) return;
+  const claudeCmd = path.join(CWD, ".claude", "commands", "spec-runner.md");
+  fs.mkdirSync(path.dirname(claudeCmd), { recursive: true });
+  fs.writeFileSync(claudeCmd, fs.readFileSync(commandTmpl, "utf8"), "utf8");
+  ok(path.relative(CWD, claudeCmd));
+}
 
+function printBanner() {
   log("");
-  log("次のステップ:");
-  log("  1. プロジェクトルートで:");
-  log("");
-  log("       ./.spec-runner/spec-runner.sh 次のステップ --json");
+  log("╔════════════════════════════════════════╗");
+  log("║        spec-runner インストーラ        ║");
+  log("║     フェーズ駆動 / 次のステップ方式     ║");
+  log("╚════════════════════════════════════════╝");
   log("");
-  log("  2. 出力の command_file（.spec-runner/steps/*.md）を開き、その指示に従う。");
-  log("  3. 終わったら再度上記を実行して次に進む。");
+}
+
+function printFooter() {
   log("");
-  log("  AI では「/spec-runner を実行して」と伝えればよい。");
+  log("次のステップ（Claude Code 専用）:");
+  log("  /spec-runner を実行して");
   log("");
 }
 
+function main() {
+  printBanner();
+  ensureTemplateDirOrExit();
+  assertDestInstallableOrExit();
+
+  info(".spec-runner/ を展開しています...");
+  wipeDestExceptUserState();
+  expandTemplateTree();
+  bootstrapProjectJson();
+  writeInitialLocksAndGrade();
+  installClaudeCommandIfPresent();
+  printFooter();
+}
+
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-runner",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "フェーズ駆動で設計先行を強制。npx で .spec-runner を展開し、次のステップ .md に従って進める",
   "license": "MIT",
   "bin": {
@@ -30,11 +30,6 @@
     "README.md",
     "LICENSE"
   ],
-  "dependencies": {
-    "chalk": "^4.1.2",
-    "enquirer": "^2.3.6",
-    "ora": "^5.4.1"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TEEE88/spec-runner.git"

package/templates/.spec-runner/hooks/pre-commit

@@ -6,28 +6,42 @@ REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
 [[ -n "$REPO_ROOT" ]] || exit 0
 
 branch=$(git branch --show-current)
-bp="feature"
-other_work="work/.+|infra/.+|cicd/.+"
-if [[ -f "$REPO_ROOT/.spec-runner/project.json" ]] && command -v jq >/dev/null 2>&1; then
-  p=$(jq -r '.naming.branch_prefix // empty' "$REPO_ROOT/.spec-runner/project.json" 2>/dev/null); [[ -n "$p" ]] && bp="$p"
-  ow=$(jq -r '.naming.other_work_prefixes[]? | . + "/.+"' "$REPO_ROOT/.spec-runner/project.json" 2>/dev/null | tr '\n' '|' | sed 's/|$//'); [[ -n "$ow" ]] && other_work="$ow"
-fi
-valid_pattern="^(main|develop|${bp}/(UC-[0-9]{3}-.+|${other_work})|fix/UC-[0-9]{3}-.+|release/[0-9]+\.[0-9]+\.[0-9]+.*|hotfix/[0-9]+\.[0-9]+\.[0-9]+-.+)$"
+
+pj="$REPO_ROOT/.spec-runner/project.json"
+[[ -f "$pj" ]] || { echo "pre-commit: project.json がありません: $pj" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { echo "pre-commit: jq が必要です（brew install jq）" >&2; exit 1; }
+bp="$(jq -r '.naming.branch_prefix // "feature"' "$pj" 2>/dev/null)"
+uc_id_pat="$(jq -r '.naming.uc_id_pattern // "UC-[0-9]+"' "$pj" 2>/dev/null)"
+other_work="$(jq -r '.naming.other_work_prefixes[]? | . + "/.+"' "$pj" 2>/dev/null | tr '\n' '|' | sed 's/|$//')"
+[[ -z "$other_work" ]] && other_work="work/.+|infra/.+|cicd/.+"
+valid_pattern="^(main|develop|${bp}/(${uc_id_pat}-.+|${other_work})|fix/${uc_id_pat}-.+|release/[0-9]+\\.[0-9]+\\.[0-9]+.*|hotfix/[0-9]+\\.[0-9]+\\.[0-9]+-.+)$"
 
 if ! echo "$branch" | grep -qE "$valid_pattern"; then
   echo "❌ ブランチ名が規則違反: $branch"
   echo "   正しい形式:"
-  echo "     ${bp}/UC-{NNN}-{kebab-description}   （新規UC、接頭辞は project.json の branch_prefix）"
+  if [[ -f "$REPO_ROOT/.spec-runner/project.json" ]] && command -v jq >/dev/null 2>&1; then
+    bp=$(jq -r '.naming.branch_prefix // "feature"' "$REPO_ROOT/.spec-runner/project.json" 2>/dev/null || echo "feature")
+  else
+    bp="feature"
+  fi
+  echo "     ${bp}/{UC-ID}-{kebab-description}   （新規UC、UC-IDは project.json の uc_id_pattern）"
   echo "     ${bp}/cicd/xxx  ${bp}/infra/xxx      （その他作業、project.json の other_work_prefixes）"
-  echo "     fix/UC-{NNN}-{kebab-description}        （修正）"
+  echo "     fix/{UC-ID}-{kebab-description}        （修正）"
   echo "     release/{semver}                        （リリース）"
   echo "     hotfix/{semver}-{kebab-description}     （緊急修正）"
   exit 1
 fi
 
 # 命名規則チェック（.spec-runner スクリプトがある場合のみ実行）
-if [[ -x "$REPO_ROOT/.spec-runner/scripts/check/naming.sh" ]]; then
-  "$REPO_ROOT/.spec-runner/scripts/check/naming.sh" || exit 1
+if [[ -d "$REPO_ROOT/src" ]]; then
+  while IFS= read -r dir; do
+    [[ -z "$dir" ]] && continue
+    base=$(basename "$dir")
+    if ! echo "$base" | grep -qE '^[a-z][a-z0-9-]*$'; then
+      echo "NAMING: フォルダ名「$dir」はkebab-caseで命名してください" >&2
+      exit 1
+    fi
+  done < <(find "$REPO_ROOT/src/" -type d 2>/dev/null || true)
 fi
 
 exit 0

package/templates/.spec-runner/project.json.example

@@ -1,23 +1,25 @@
 {
-  "_comment": "init-project.sh または AI との対話で作成。other_work_prefixes は UC 以外の作業用ブランチ（例: feature/cicd/xxx）。",
+  "_comment": "AI が編集して作成。other_work_prefixes は UC 以外の作業用ブランチ（例: feature/cicd/xxx）。",
+  "_comment_required_docs": "required_docs は steps.json を単一ソースにするため、\"steps:<common.docsキー>[/suffix]\" を指定できる（例: steps:openapi, steps:domain_root/集約.md）。",
   "naming": {
     "branch_prefix": "feature",
-    "uc_id_pattern": "UC-[0-9]{3}",
+    "uc_id_pattern": "UC-[0-9]+",
     "uc_spec_basename": "{uc_id}-{slug}.md",
     "adr_basename": "MMDD-{title}.md",
     "docs_05_categories": true,
     "other_work_prefixes": ["work", "infra", "cicd"]
   },
   "required_docs": {
-    "charter": ["docs/01_憲章/憲章.md"],
-    "domain": ["docs/02_ドメイン設計/ユビキタス言語辞書.md", "docs/02_ドメイン設計/ドメインモデル.md", "docs/02_ドメイン設計/集約.md"],
-    "architecture": ["docs/03_アーキテクチャ/パターン選定.md", "docs/03_アーキテクチャ/インフラ方針.md", "docs/03_アーキテクチャ/設計判断記録"],
-    "grade_a": ["docs/04_インフラ設計/schema.dbml"],
-    "gate3_openapi": ["docs/06_API仕様/openapi.yaml"]
+    "charter": ["steps:charter"],
+    "domain": ["steps:domain_root/ユビキタス言語辞書.md", "steps:domain_root/ドメインモデル.md", "steps:domain_root/集約.md"],
+    "architecture": ["steps:architecture_root/パターン選定.md", "steps:architecture_root/インフラ方針.md", "steps:architecture_root/設計判断記録"],
+    "grade_a": ["steps:infra_root/schema.dbml"],
+    "gate3_openapi": ["steps:openapi"]
   },
   "test_design": {
     "dir": "tests",
-    "pattern": "*.spec.*"
+    "pattern": "*.spec.*",
+    "require_uc_prefixed_tests": true
   },
   "test_command": {
     "run": "npm test"

package/templates/.spec-runner/scripts/branch/uc-next-start.sh

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
-# 次の UC を開始する: main に切り替え、feature/UC-NNN-xxx ブランチを作成する。
+# 次の UC を開始する: main に切り替え、feature/UC-N-xxx ブランチを作成する。
 # 使用例:
 #   ./uc-next-start.sh                    # 次 UC 番号を自動検出。説明はプロンプトまたは "next-uc" で作成
 #   ./uc-next-start.sh task-update        # 次 UC 番号 + 説明 "task-update" でブランチ作成
-#   ./uc-next-start.sh UC-002 task-update # 指定 UC + 説明
+#   ./uc-next-start.sh task-update 認証    # 次 UC 番号 + 説明 + カテゴリ
+#   ./uc-next-start.sh UC-2 task-update   # 指定 UC + 説明
+#   ./uc-next-start.sh UC-2 task-update 認証 # 指定 UC + 説明 + カテゴリ
 #   ./uc-next-start.sh --yes task-update  # 確認なしで実行
 # 実行後は次のステップに進む旨を案内する。
 
@@ -21,15 +23,50 @@ for a in "$@"; do
   esac
 done
 
-# 次 UC 番号を取得
-NEXT_UC=$("$BRANCH_DIR/uc-next-id.sh")
+PROJECT_JSON="$REPO_ROOT/.spec-runner/project.json"
+[[ -f "$PROJECT_JSON" ]] || { echo "uc-next-start: project.json がありません: $PROJECT_JSON" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { echo "uc-next-start: jq が必要です（brew install jq）" >&2; exit 1; }
+UC_ID_RE="$(jq -r '.naming.uc_id_pattern' "$PROJECT_JSON")"
+BRANCH_PREFIX="$(jq -r '.naming.branch_prefix' "$PROJECT_JSON")"
+[[ -n "$UC_ID_RE" && "$UC_ID_RE" != "null" && -n "$BRANCH_PREFIX" && "$BRANCH_PREFIX" != "null" ]] || {
+  echo "uc-next-start: project.json の naming.uc_id_pattern / branch_prefix が未設定です" >&2
+  exit 1
+}
+
+next_uc_id() {
+  # docs/02_ユースケース仕様/<カテゴリ>/UC-*.md から次に使う UC-N を返す
+  local dir="$REPO_ROOT/docs/02_ユースケース仕様"
+  mkdir -p "$dir"
+  local max=0
+  for f in "$dir"/*/UC-*.md; do
+    [[ -e "$f" ]] || continue
+    base=$(basename "$f" .md)
+    if [[ "$base" =~ ^(${UC_ID_RE})- ]]; then
+      uc_id="${BASH_REMATCH[1]}"
+      digits=$(echo "$uc_id" | tr -cd '0-9')
+      [[ -z "$digits" ]] && continue
+      n=$((10#$digits))
+      [[ $n -gt $max ]] && max=$n
+    fi
+  done
+  printf "UC-%d\n" $((max + 1))
+}
+
+NEXT_UC="$(next_uc_id)"
 DESC=""
+CATEGORY=""
 
-if [[ ${#ARGS[@]} -ge 2 ]] && [[ "${ARGS[0]}" =~ ^UC-[0-9]{3}$ ]]; then
+# ファイル題名は日本語優先にするため、スクリプト引数の「生の説明」を保持する
+RAW_DESC=""
+if [[ ${#ARGS[@]} -ge 2 ]] && [[ "${ARGS[0]}" =~ ^${UC_ID_RE}$ ]]; then
   NEXT_UC="${ARGS[0]}"
   DESC="${ARGS[1]}"
+  RAW_DESC="${ARGS[1]}"
+  CATEGORY="${ARGS[2]:-}"
 elif [[ ${#ARGS[@]} -ge 1 ]]; then
   DESC="${ARGS[0]}"
+  RAW_DESC="${ARGS[0]}"
+  CATEGORY="${ARGS[1]:-}"
 fi
 
 # 説明が無ければデフォルト（next-uc や UC 番号ベース）
@@ -39,14 +76,37 @@ if [[ -z "$DESC" ]]; then
   else
     echo "次の UC 用ブランチを作成します。"
     echo "  UC: $NEXT_UC"
-    echo -n "  説明（英小文字・ハイフン。Enter で \"next-uc\"）: "
+    echo -n "  説明（英数字・ハイフン推奨。日本語のみの場合は uc-001 等にフォールバック。Enter で \"next-uc\"）: "
     read -r DESC
     DESC="${DESC:-next-uc}"
   fi
 fi
 
-DESC=$(echo "$DESC" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
-BRANCH_NAME="feature/${NEXT_UC}-${DESC}"
+# 説明は英小文字・ハイフン（Git ブランチ名は ASCII のみ）。日本語など非 ASCII はサニタイズで除去される
+# macOS(BSD sed) でも動くように、連続ハイフンは 's/--*/-/g' で圧縮する
+DESC=$(echo "$DESC" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-*//' | sed 's/-*$//')
+# サニタイズ後に空（日本語のみの説明など）の場合は UC 番号ベースのスラグでフォールバック
+[[ -z "$DESC" ]] && DESC="uc-$(echo "$NEXT_UC" | sed 's/^UC-//')"
+BRANCH_NAME="${BRANCH_PREFIX}/${NEXT_UC}-${DESC}"
+
+# UC 仕様書ファイル名は必ず日本語にする（題名が ASCII のみなら「要確認」にする）
+DOC_TITLE="$RAW_DESC"
+if [[ -z "$DOC_TITLE" ]]; then
+  DOC_TITLE="要確認"
+else
+  # 非ASCIIが無い（= 英数字/記号のみ）なら、日本語題名が無い扱いにして要確認へ
+  if echo "$DOC_TITLE" | LC_ALL=C grep -q '^[ -~]*$'; then
+    DOC_TITLE="要確認"
+  fi
+fi
+# ファイル名に危険な文字が入らないように除去（日本語は許可）
+DOC_TITLE=$(echo "$DOC_TITLE" | sed 's/[\\\\\\/\\:\\*\\?\\\"\\<\\>\\|]/ /g' | sed 's/[[:space:]]\\+/ /g' | sed 's/^ *//; s/ *$//')
+[[ -z "$DOC_TITLE" ]] && DOC_TITLE="要確認"
+
+# カテゴリ（省略時はデフォルト）。日本語カテゴリは許可し、危険文字だけ除去。
+CATEGORY="${CATEGORY:-ユースケース}"
+CATEGORY=$(echo "$CATEGORY" | sed 's/[^a-zA-Z0-9_ーぁ-んァ-ン一-龥\-]//g')
+[[ -z "$CATEGORY" ]] && CATEGORY="ユースケース"
 
 if git rev-parse --verify "$BRANCH_NAME" >/dev/null 2>&1; then
   echo "Error: ブランチ '$BRANCH_NAME' は既に存在します。" >&2
@@ -76,6 +136,37 @@ fi
 
 git checkout "$MAIN_BRANCH"
 git pull --ff-only 2>/dev/null || true
-"$BRANCH_DIR/create-uc-branch.sh" "$NEXT_UC" "$DESC"
+
+# ブランチ作成 + UC 仕様書作成（統合）
+UC_ID_PATTERN="^${UC_ID_RE}$"
+if ! echo "$NEXT_UC" | grep -qE "$UC_ID_PATTERN"; then
+  echo "Error: UC-ID が命名規則に合いません: $NEXT_UC（期待: $UC_ID_PATTERN）" >&2
+  exit 1
+fi
+valid_uc_pattern="^${BRANCH_PREFIX}/${UC_ID_RE}-[a-z0-9-]+\$"
+if ! echo "$BRANCH_NAME" | grep -qE "$valid_uc_pattern"; then
+  echo "Error: ブランチ名が命名規則に合いません: $BRANCH_NAME（期待: ${BRANCH_PREFIX}/<UC-ID>-kebab-description）" >&2
+  exit 1
+fi
+
+git checkout -b "$BRANCH_NAME"
+echo "Created branch: $BRANCH_NAME"
+
+FEATURE_DIR="docs/02_ユースケース仕様/${CATEGORY}"
+UC_DOC="${FEATURE_DIR}/${NEXT_UC}-${DOC_TITLE}.md"
+mkdir -p "$FEATURE_DIR"
+# UC ごとの判断ログ置き場（任意だが、作成しておくと運用が安定する）
+mkdir -p "${FEATURE_DIR}/判断記録"
+# テンプレ: 修正・改善は .spec-runner/templates/UC-N-ユースケース名.md を編集。プレースホルダ UC-N → UC番号, {ユースケース名} → 題名
+TEMPLATE="$REPO_ROOT/.spec-runner/templates/UC-N-ユースケース名.md"
+if [[ -f "$TEMPLATE" ]]; then
+  sed "s/UC-N/${NEXT_UC}/g; s/{ユースケース名}/${DOC_TITLE}/g" "$TEMPLATE" > "$UC_DOC"
+  echo "Created: $UC_DOC"
+else
+  touch "$UC_DOC"
+  echo "# ${NEXT_UC}: ${DOC_TITLE}" >> "$UC_DOC"
+  echo "Created: $UC_DOC"
+fi
+
 echo ""
 echo "次の UC 用ブランチの準備ができました。次のステップに進んでください。"