spec-runner 1.0.19 → 1.0.23

package/README.md

@@ -18,6 +18,14 @@ curl -sSL https://raw.githubusercontent.com/TEEE88/spec-runner/main/install.sh |
 
 いずれも、プロジェクト直下に `.spec-runner/` ができる。
 
+あわせて、**未有効時のみ**プロジェクトルートに次が配置される（Material for MkDocs で `docs/` 配下の設計書をプレビューするため）。
+
+- `mkdocs.yml` / `requirements-docs.txt`
+- `docs/index.md`（サイトのホーム）
+- `docs/spec-runner-フロー.md`（`spec-runner` パッケージ同梱の手順書）
+
+`.spec-runner/` がすでにあり **2 回目以降はエラーで止まる** 場合も、**その手前**で上記 MkDocs 用ファイルの不足分だけ補完される（初回導入以前のリポジトリで MkDocs だけ足したいときに便利）。
+
 ---
 
 ## 使い方
@@ -42,6 +50,24 @@ AI から使う場合は、`/spec-runner` のように「spec-runner を実行
 
 ---
 
+## ドキュメントサイト（MkDocs + Material）
+
+### `npx spec-runner` したプロジェクト側
+
+憲章・設計書は `steps.json` どおり `docs/01_憲章/` 〜 `docs/06_API仕様/` に置かれる。`mkdocs.yml` の `docs/` がそのままサイトの文書ルートになるので、**追加コピーなしで**これらの Markdown をナビに載せられる（`nav` で先頭に固定した `index.md` の後ろへ、残りのページが自動で続く）。
+
+プレビュー起動（Python 3 必須・仮想環境 `.venv-docs/` を使用）:
+
+```bash
+./.spec-runner/scripts/docs-serve.sh
+```
+
+`8000` が使用中のとき:
+
+```bash
+DOCS_PORT=8001 ./.spec-runner/scripts/docs-serve.sh
+```
+
 ## 導入後にできるもの
 
 ```
@@ -51,10 +77,13 @@ AI から使う場合は、`/spec-runner` のように「spec-runner を実行
 │   ├── project.json            # 設定（ブランチ命名・必須ドキュメント・テストコマンド等）
 │   ├── phase-locks.json        # フェーズの通過状態
 │   ├── grade-history.json      # グレード（LOOP1 / A / B / C）
-│   ├── scripts/                # spec-runner-core.sh, check, branch, test 等
+│   ├── scripts/                # spec-runner-core.sh, check, branch, docs-serve.sh 等
 │   ├── steps/                  # 憲章・ドメイン設計・仕様策定・曖昧さ解消・テスト設計・実装 等の .md
 │   └── templates/              # UC 仕様書ひな形
 ├── .claude/commands/spec-runner.md   # Claude 用コマンド定義（/spec-runner）
+├── mkdocs.yml                 # MkDocs（未有効時のみ配置）
+├── requirements-docs.txt      # mkdocs / mkdocs-material（未有効時のみ配置）
+├── docs/                      # 設計書（01..06）＋ index.md 等。MkDocs の文書ルート
 └── （AI は Claude Code 前提）
 ```
 
@@ -66,6 +95,7 @@ AI から使う場合は、`/spec-runner` のように「spec-runner を実行
 - jq
 - git
 - bash 4.0+
+- 設計書の MkDocs プレビュー: Python 3（`docs-serve.sh` が `python3` と venv を使用）
 
 ---
 

package/bin/spec-runner.js

@@ -19,6 +19,11 @@
  * - templates/.spec-runner/project.json.example
  * - templates/.spec-runner/templates/phase-locks.json
  * - templates/.spec-runner/templates/grade-history.json
+ *
+ * MkDocs（任意・プロジェクトルート）:
+ * - templates/mkdocs-scaffold/ の mkdocs.yml / requirements-docs.txt / docs/index.md を
+ *   未有効時のみコピー（憲章・設計書は既存の docs/01..06 をそのまま閲覧）
+ * - パッケージ同梱の docs/flow.md を docs/spec-runner-フロー.md としてコピー（未存在時のみ）
  */
 
 const fs = require("fs");
@@ -31,6 +36,8 @@ 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");
+const MKDOCS_SCAFFOLD_DIR = path.join(PKG_DIR, "templates", "mkdocs-scaffold");
+const FLOW_DOC_SRC = path.join(PKG_DIR, "docs", "flow.md");
 
 /** コピー時はスキップし、FORCE 時は消さない（ユーザー状態を保持） */
 const USER_STATE_BASENAMES = new Set([
@@ -170,6 +177,57 @@ function installClaudeCommandIfPresent() {
   ok(path.relative(CWD, claudeCmd));
 }
 
+/**
+ * MkDocs + Material 用のファイルをプロジェクトルートに配置（未存在時のみ）。
+ * 設計書本体は steps.json どおり docs/01..06 に置かれ、mkdocs の docs_dir でそのまま掲載する。
+ */
+function copyFileIfMissing(src, dest) {
+  if (!exists(src) || exists(dest)) return false;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  ok(path.relative(CWD, dest));
+  return true;
+}
+
+function appendGitignoreVenvDocsIfNeeded() {
+  const gitignorePath = path.join(CWD, ".gitignore");
+  const marker = ".venv-docs/";
+  if (!exists(gitignorePath)) return;
+  const raw = fs.readFileSync(gitignorePath, "utf8");
+  const lines = raw.split(/\r?\n/);
+  if (lines.some((line) => /^\.venv-docs\/?$/.test(line.trim()))) return;
+  fs.appendFileSync(
+    gitignorePath,
+    `\n# spec-runner: MkDocs 用 Python 仮想環境\n${marker}\n`,
+    "utf8",
+  );
+  ok(`${path.relative(CWD, gitignorePath)}（${marker} を追記）`);
+}
+
+function installMkdocsScaffold() {
+  if (!exists(MKDOCS_SCAFFOLD_DIR)) {
+    info("MkDocs テンプレート（templates/mkdocs-scaffold）が見つかりません。スキップします。");
+    return;
+  }
+  info("MkDocs 用ファイル（不足分のみ）をプロジェクトルートに配置します...");
+  copyFileIfMissing(
+    path.join(MKDOCS_SCAFFOLD_DIR, "mkdocs.yml"),
+    path.join(CWD, "mkdocs.yml"),
+  );
+  copyFileIfMissing(
+    path.join(MKDOCS_SCAFFOLD_DIR, "requirements-docs.txt"),
+    path.join(CWD, "requirements-docs.txt"),
+  );
+  copyFileIfMissing(
+    path.join(MKDOCS_SCAFFOLD_DIR, "docs", "index.md"),
+    path.join(CWD, "docs", "index.md"),
+  );
+  if (exists(FLOW_DOC_SRC)) {
+    copyFileIfMissing(FLOW_DOC_SRC, path.join(CWD, "docs", "spec-runner-フロー.md"));
+  }
+  appendGitignoreVenvDocsIfNeeded();
+}
+
 function printBanner() {
   log("");
   log("╔════════════════════════════════════════╗");
@@ -180,6 +238,9 @@ function printBanner() {
 }
 
 function printFooter() {
+  log("");
+  log("設計書プレビュー（MkDocs + Material・プロジェクトルートの docs/）:");
+  log("  ./.spec-runner/scripts/docs-serve.sh");
   log("");
   log("次のステップ（Claude Code 専用）:");
   log("  /spec-runner を実行して");
@@ -189,6 +250,7 @@ function printFooter() {
 function main() {
   printBanner();
   ensureTemplateDirOrExit();
+  installMkdocsScaffold();
   assertDestInstallableOrExit();
 
   info(".spec-runner/ を展開しています...");

package/docs/flow.md

@@ -0,0 +1,213 @@
+# spec-runner の進め方（実装準拠）
+
+このドキュメントは **リポジトリ内の実装**（`templates/.spec-runner/scripts/spec-runner-core.sh`、`steps/steps.json` 等）に沿って書いています。  
+「次のステップ」は **1 本のコマンド**が返す **1 つの `command_file`（`.spec-runner/steps/*.md`）** だけです。
+
+---
+
+## 入口コマンド（毎回）
+
+| 用途 | コマンド（プロジェクトルート） |
+|------|-------------------------------|
+| 次のステップ（人間向けテキスト） | `./.spec-runner/spec-runner.sh` または `./.spec-runner/spec-runner.sh 次のステップ` |
+| 次のステップ（JSON） | `./.spec-runner/spec-runner.sh 次のステップ --json` |
+| Lock 一覧 | `./.spec-runner/spec-runner.sh 次のステップ --lock`（内部では `--status`） |
+| グレード判定ガイド | `./.spec-runner/spec-runner.sh 次のステップ --グレード` |
+
+- **やること**: 出力の `command_file` を開き、その `.md` の指示どおりに作業する。
+- **毎回の検証**: `steps.json` の `common.commands.check` → 既定は `.spec-runner/scripts/check.sh`。
+
+### `--json` の主なフィールド（実装どおり）
+
+| フィールド | 意味 |
+|------------|------|
+| `phase` | 数値（`steps.json` の各 step の `phase` と概ね対応） |
+| `phase_name_ja` | 表示用ラベル（コアが付与） |
+| `step_id` | `steps.json` の `id`（例: `charter`, `uc_spec`, `clarify`） |
+| `command` | ステップの日本語名（`name_ja`） |
+| `command_file` | 絶対パス想定の `.spec-runner/steps/<md_file>` |
+| `grade` | `grade-history.json` の `current_grade` |
+| `check_command` | 毎回のチェック用シェルコマンド |
+| `step_commands` | そのステップ用のコマンド配列（JSON） |
+| `feature_dir` / `feature_spec` | UC ブランチ時、該当 UC のディレクトリ・仕様書パス（取れれば） |
+
+---
+
+## 状態の単一ソース
+
+### `.spec-runner/phase-locks.json`
+
+実際のキーは次のとおり（各オブジェクトに `completed`, `locked_at`, `reviewed_by` 等）。
+
+| キー | 意味 |
+|------|------|
+| `charter` | 憲章フェーズ完了。ゲートでは `reviewed_by` も参照（LOOP1 時） |
+| `domain` | ドメイン設計フェーズ完了 |
+| `architecture` | アーキ（実装計画）フェーズ完了 |
+| `infra` | インフラ詳細（Grade A）完了 |
+| `test_design` | テスト設計ロック（ゲート側で参照） |
+| `uc_discovery` | UC 洗い出し完了（`false` の間は domain に進まない） |
+| `uc_reviewed` | **文字列の配列**。UC 仕様ファイルの **ベース名（拡張子なし）** が入ると「レビュー通過」とみなす（例: `UC-1-foo`） |
+
+### `.spec-runner/grade-history.json`
+
+- `current_grade`: `LOOP1` / `A` / `B` / `C` など（**ブランチ名には含めない**）
+- Grade A のとき、UC レビュー通過後は **インフラ詳細（`infra_plan`）** が先に出る（`infra.completed` が付くまで）
+
+### `.spec-runner/project.json`
+
+- `naming`: ブランチ接頭辞 `branch_prefix`（既定 `feature`）、`uc_id_pattern`、`other_work_prefixes`（例: `work`, `infra`, `cicd`）
+- `required_docs`: ゲート確認時の必須パス（`steps:charter` 形式で `steps.json` の `common.docs` を参照）
+- `test_design.dir` / `test_design.pattern`（既定: `tests`, `*.spec.*`）
+- `test_design.require_uc_prefixed_tests`（既定: キー省略時 **true**）: **TDD 前提**。UC ブランチでは **`UC-N-` で始まり `pattern` に合致するテストファイル**が `test_design.dir` 内に無い限り **`test_design` のまま**（`implement` に進めない）。`false` にすると従来どおり「任意の spec が1つでもあれば実装」。
+- `test_command.run`: **`require-tests-green.sh` が実行するテストコマンド**（実装完了の機械的条件）
+
+---
+
+## 「次のステップ」の分岐（`spec-runner-core.sh` の実際）
+
+ブランチ種別・ロック・UC 有無・`uc_reviewed`・グレード・テストファイル有無で決まります。**紙の上の「常に UC→ドメイン→アーキ」の直線とは一致しません。**
+
+### 1) UC ブランチ上（`feature/<UC-N>-<slug>` 形式）
+
+1. 該当 `UC-N-*.md` が **まだ無い** → **`uc_spec`**（仕様策定）
+2. 仕様はあるが **`uc_reviewed` にベース名が無い** → **`clarify`**（曖昧さ解消・レビュー通過まで）
+3. レビュー済みかつ **`uc_discovery.completed` が false** → **`uc_spec`**（次UC作成）
+4. レビュー済みかつ **Grade A かつ `infra.completed` でない** → **`infra_plan`**
+5. それ以外で **当該 UC 用テストが未準備**（`require_uc_prefixed_tests` が true のときは **`UC-N-*.spec.*` 形式が1つ以上**）→ **`test_design`**
+6. 上記を満たす → **`implement`**（あわせて **テストがグリーン**になるまで完了とみなさないのは `require-tests-green.sh` 側）
+
+※ **ドメイン・アーキのロック未完了でも**、上記 UC ブランチ上では 3〜6 に進めます（コア実装どおり）。
+
+### 2) UC ブランチではない（main 等）
+
+実装では **次の順で最初に当てはまる分岐**が選ばれます（UC ブランチでも `other_work` ブランチでもない場合）。
+
+1. **`charter.completed` でない**
+   - `docs/01_憲章/憲章.md` が無い → **`charter`**
+   - `docs/01_憲章/憲章.md` があり、`quality.clarified.charter` 未記録 → **`clarify`**（憲章の曖昧さ解消）
+   - `docs/01_憲章/憲章.md` があり、`quality.analyzed.charter` 未記録 → **`analyze`**（憲章の分析）
+   - 上記が記録済み → **`charter`**
+2. **ドメイン未ロックかつ `uc_discovery.completed` が false** → **`uc_spec`**（次UC作成）
+3. **ドメイン未ロックかつ `uc_discovery.completed` が true かつ `docs/02_...` に UC が 1 件以上**
+   - `docs/03_ドメイン設計/` に `.md` があり、`quality.clarified.domain` 未記録 → **`clarify`**
+   - `docs/03_ドメイン設計/` に `.md` があり、`quality.analyzed.domain` 未記録 → **`analyze`**
+   - 上記が記録済み、または `.md` が無い → **`domain`**
+4. **ドメイン済みかつアーキ未ロック**
+   - `docs/04_アーキテクチャ/` に `.md` があり、`quality.clarified.architecture` 未記録 → **`clarify`**
+   - `docs/04_アーキテクチャ/` に `.md` があり、`quality.analyzed.architecture` 未記録 → **`analyze`**
+   - 上記が記録済み、または `.md` が無い → **`architecture_plan`**
+5. **`other_work` 用ブランチ**（`feature/<other_work_prefix>/...`）かつ **2〜4 を通過済み** → **`other_work`**
+6. **ドメイン未ロック**（この時点では UC が 0 件）→ **`uc_spec`**
+7. **ドメイン・アーキともロック済み** → **`uc_spec`**（次の UC 開始）
+
+要点:
+
+- **初回**: main で UC がまだ無いと **6** で **`uc_spec`**。
+- **UC がリポジトリに既にあるのにドメイン未ロック**（main で作業）→ `uc_discovery.completed=false` の間は **`uc_spec`** が先（`true` になってから **`domain`**）。
+- **アーキ**は **ドメイン完了後**に **4** で出る。
+
+### 3) 自動では選ばれないステップ（`steps.json` にのみ存在）
+
+次の `id` は **コアの `run_phase` では返しません**。各 `.md`（仕様策定・テスト設計等）の **手順の中で**使う想定です。
+
+- `analyze`（分析）
+- `checklist`（チェックリスト）
+- `task_list`（タスク一覧）
+
+---
+
+## 成果物の置き場所（`steps.json` の `common.docs` と一致）
+
+| キー | パス（既定） |
+|------|----------------|
+| 憲章 | `docs/01_憲章/憲章.md` |
+| UC ルート | `docs/02_ユースケース仕様/<カテゴリ>/UC-N-<slug>.md` |
+| ドメイン | `docs/03_ドメイン設計/`（ユビキタス言語辞書・ドメインモデル・集約 等） |
+| アーキ | `docs/04_アーキテクチャ/` |
+| インフラ | `docs/05_インフラ設計/`（例: `schema.dbml`） |
+| API | `docs/06_API仕様/openapi.yaml` |
+
+- UC ファイル名は **`UC-<N>-<slug>.md`**（`slug` は英数字・ハイフンが無難。ブランチ名も ASCII）。
+- カテゴリフォルダ名は日本語可。
+
+---
+
+## ディレクトリ構成（パッケージテンプレに近い形）
+
+```
+<プロジェクトルート>/
+├── .spec-runner/
+│   ├── spec-runner.sh
+│   ├── project.json              # 初回は project.json.example から
+│   ├── phase-locks.json          # 初回は templates/phase-locks.json から
+│   ├── grade-history.json
+│   ├── scripts/
+│   │   ├── spec-runner-core.sh
+│   │   ├── check.sh              # --every / --full
+│   │   ├── branch/uc-next-start.sh
+│   │   └── test/require-tests-green.sh
+│   ├── steps/                    # *.md + steps.json
+│   ├── templates/                # 憲章・UC・ドメイン雛形等
+│   └── hooks/                    # pre-commit / pre-push（任意）
+├── docs/01_憲章/ … 06_API仕様/
+├── tests/                        # project.json の test_design.dir
+└── src/
+```
+
+- **`npx spec-runner`**: `.spec-runner/` を展開し、**`.claude/commands/spec-runner.md` を配置**（テンプレに存在する場合）。`.cursor/` への自動配置は **インストーラでは行っていない**。
+
+---
+
+## フェーズ番号とステップ（`steps.json`）
+
+| phase | step_id（代表） | 内容 |
+|-------|-----------------|------|
+| 0 | `charter` | 憲章 |
+| 1 | `uc_spec` / `other_work` | UC 仕様・その他ブランチ |
+| 2 | `domain` | ドメイン設計 |
+| 3 | `architecture_plan` | 実装計画（アーキ） |
+| 4 | `infra_plan` | インフラ詳細（Grade A） |
+| 5 | `test_design` | PENDING テスト |
+| 6 | `implement` | 実装・テストグリーン |
+
+`clarify`（曖昧さ解消）と `analyze`（分析）は `phase: null` の任意ステップとして扱い、必要なタイミングで実行できます。
+
+補足: `clarify` / `analyze` の自動実行は `.spec-runner/phase-locks.json` の `quality` によって 1 度ずつ管理します。  
+（UC は `uc_reviewed` 未登録の間、`clarify -> analyze -> clarify ...` の品質ループを回せます）
+
+### 実装完了（Phase 6）の機械的条件
+
+- **手動または CI で** `.spec-runner/scripts/test/require-tests-green.sh` が **exit 0** であること。
+- 中身は `project.json` の **`test_command.run`** のみを `eval` 実行（例: `npm test`）。
+
+### ゲート（`spec-runner-core.sh --gate`）のメモ
+
+ゲートログ上の「Phase 1/2」表現は **ドメイン=Phase 1、アーキ=Phase 2** のように **steps.json の phase 番号と一致しません**。ロック対象は `phase-locks.json` のキーで判断してください。
+
+---
+
+## TDD が「どこまで」強制されるか
+
+| レベル | 内容 |
+|--------|------|
+| **ゲート（次のステップ）** | 上記どおり **先に当該 UC の spec ファイルを置く**まで `implement` を出さない（`require_uc_prefixed_tests: true` 時）。 |
+| **レッド→グリーンの順序** | **コミット順や「本番コードより先にアサーションを書いたか」は機械検査していない**。Phase 5 で PENDING/skip、Phase 6 で実装・グリーン、という **フェーズ順**での強制。 |
+| **完了条件** | `require-tests-green.sh`（`test_command.run` 全通過）。 |
+
+---
+
+## 理想運用 vs コードのギャップ（把握用）
+
+| 観点 | よく言われる理想 | 実コード |
+|------|------------------|----------|
+| UC とドメインの順序 | 常に UC 全部 → ドメイン | `uc_discovery.completed=false` の間は次UC（`uc_spec`）→ `true` になってから domain |
+| UC 実装前にアーキ必須 | あり | **UC ブランチ上では**ドメイン・アーキ未ロックでもテスト設計・実装に進む |
+
+運用で「必ずドメイン→アーキ→UC 実装」にしたい場合は、**ロックを先に済ませてから** UC ブランチに入る、またはコアの分岐変更が必要です。
+
+---
+
+## 日本語ドキュメント
+
+`docs/` 配下の設計書は日本語で問題ありません。**Git 上はブランチ名・UC ファイルの slug は ASCII（kebab-case）推奨**です。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-runner",
-  "version": "1.0.19",
+  "version": "1.0.23",
   "description": "フェーズ駆動で設計先行を強制。npx で .spec-runner を展開し、次のステップ .md に従って進める",
   "license": "MIT",
   "bin": {
@@ -26,6 +26,7 @@
   "files": [
     "bin/",
     "templates/",
+    "docs/flow.md",
     "install.sh",
     "README.md",
     "LICENSE"

package/templates/.spec-runner/scripts/docs-serve.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# MkDocs + Material で docs/ をプレビュー（プロジェクトルートで実行される想定）
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$ROOT"
+
+DOCS_PORT="${DOCS_PORT:-8000}"
+REQ="requirements-docs.txt"
+
+if [[ ! -f "$REQ" ]]; then
+  echo "ERROR: ${REQ} が見つかりません。npx spec-runner を実行して MkDocs 用ファイルを展開してください。" >&2
+  exit 1
+fi
+
+if [[ ! -d .venv-docs ]]; then
+  python3 -m venv .venv-docs
+fi
+
+./.venv-docs/bin/pip install -q -r "$REQ"
+exec ./.venv-docs/bin/mkdocs serve --dev-addr "127.0.0.1:${DOCS_PORT}"

package/templates/.spec-runner/scripts/spec-runner-core.sh

@@ -71,6 +71,7 @@ has_charter_lock=0
 has_domain_lock=0
 has_arch_lock=0
 has_infra_lock=0
+uc_discovery_completed=0
 grade=""
 branch=""
 test_dir=""
@@ -87,6 +88,7 @@ load_state() {
   jq -e '.domain.completed == true' "$LOCK_FILE" >/dev/null 2>&1 && has_domain_lock=1
   jq -e '.architecture.completed == true' "$LOCK_FILE" >/dev/null 2>&1 && has_arch_lock=1
   jq -e '.infra.completed == true' "$LOCK_FILE" >/dev/null 2>&1 && has_infra_lock=1
+  jq -e '.uc_discovery.completed == true' "$LOCK_FILE" >/dev/null 2>&1 && uc_discovery_completed=1
 
   grade=$(jq -r '.current_grade' "$GRADE_FILE")
   [[ -n "$grade" && "$grade" != "null" ]] || die "spec-runner-core: grade-history.json の current_grade が未設定です"
@@ -286,7 +288,11 @@ run_phase() {
     local kind="$1"   # clarified | analyzed
     local scope="$2"  # charter | domain | architecture | uc
     local key="$3"
-    jq -e --arg k "$key" --arg s "$scope" ".quality.${kind}[\$s][]? == \$k" "$LOCK_FILE" >/dev/null 2>&1
+    # 互換性のため、quality には「ベース名」と「.md 付き」の両方を許容する
+    local key_md="${key}.md"
+    jq -e --arg k "$key" --arg km "$key_md" --arg s "$scope" \
+      ".quality.${kind}[\$s][]? | select(. == \$k or . == \$km)" \
+      "$LOCK_FILE" >/dev/null 2>&1
   }
 
   resolve_step() {
@@ -328,21 +334,31 @@ run_phase() {
     else
       phase=0; phase_name_ja="憲章策定"; resolve_step "charter"
     fi
-  elif [[ $has_domain_lock -eq 0 && ${uc_count_total} -gt 0 && $on_uc_branch -eq 0 ]]; then
-    domain_spec="$(first_md_in_dir "$domain_root" || true)"
-    if [[ -n "$domain_spec" ]]; then
-      feature_spec="$domain_spec"
-      feature_dir="$(dirname "$domain_spec")"
-      dkey="$(doc_key "$domain_spec")"
-      if ! quality_done "clarified" "domain" "$dkey"; then
-        phase=2; phase_name_ja="ドメイン設計（曖昧さ解消）"; resolve_step "clarify"
-      elif ! quality_done "analyzed" "domain" "$dkey"; then
-        phase=2; phase_name_ja="ドメイン設計（分析）"; resolve_step "analyze"
+  elif [[ $has_domain_lock -eq 0 && $on_uc_branch -eq 0 ]]; then
+    # UC を洗い出している途中（uc_discovery.completed=false）の間はドメインへ進まない
+    if [[ $uc_discovery_completed -eq 0 ]]; then
+      phase=1; phase_name_ja="ユースケース洗い出し中（次UC作成）"; resolve_step "uc_spec"
+    else
+      # UC が 1 件以上ある場合のみ、ドメイン側の質フローを回す
+      if [[ ${uc_count_total} -gt 0 ]]; then
+        domain_spec="$(first_md_in_dir "$domain_root" || true)"
+        if [[ -n "$domain_spec" ]]; then
+          feature_spec="$domain_spec"
+          feature_dir="$(dirname "$domain_spec")"
+          dkey="$(doc_key "$domain_spec")"
+          if ! quality_done "clarified" "domain" "$dkey"; then
+            phase=2; phase_name_ja="ドメイン設計（曖昧さ解消）"; resolve_step "clarify"
+          elif ! quality_done "analyzed" "domain" "$dkey"; then
+            phase=2; phase_name_ja="ドメイン設計（分析）"; resolve_step "analyze"
+          else
+            phase=2; phase_name_ja="ドメイン設計"; resolve_step "domain"
+          fi
+        else
+          phase=2; phase_name_ja="ドメイン設計"; resolve_step "domain"
+        fi
       else
-        phase=2; phase_name_ja="ドメイン設計"; resolve_step "domain"
+        phase=1; phase_name_ja="ユースケース洗い出し中（次UC作成）"; resolve_step "uc_spec"
       fi
-    else
-      phase=2; phase_name_ja="ドメイン設計"; resolve_step "domain"
     fi
   elif [[ $has_arch_lock -eq 0 && $has_domain_lock -eq 1 ]]; then
     arch_spec="$(first_md_in_dir "$architecture_root" || true)"
@@ -382,7 +398,10 @@ run_phase() {
           phase=1; phase_name_ja="ユースケース仕様（レビュー通過まで）"; resolve_step "clarify"
         fi
       else
-        if [[ "$grade" == "A" ]] && [[ $has_infra_lock -eq 0 ]]; then
+        # UC 洗い出し中は、レビュー済みでも次の UC 作成へ戻す（TDD/実装に進まない）
+        if [[ $uc_discovery_completed -eq 0 ]]; then
+          phase=1; phase_name_ja="ユースケース洗い出し中（次UC作成）"; resolve_step "uc_spec"
+        elif [[ "$grade" == "A" ]] && [[ $has_infra_lock -eq 0 ]]; then
           phase=4; phase_name_ja="インフラ詳細設計"; resolve_step "infra_plan"
         else
           if uc_branch_has_tests_ready_for_implement; then
@@ -429,7 +448,7 @@ run_status() {
   echo "グレード: $grade"
   echo ""
   echo "Lock（.spec-runner/phase-locks.json）:"
-  for sec in charter domain architecture infra test_design; do
+  for sec in charter domain architecture infra uc_discovery test_design; do
     if jq -e --arg s "$sec" '.[$s].completed == true' "$LOCK_FILE" >/dev/null 2>&1; then
       echo "  ✓ $sec"
     else

package/templates/.spec-runner/steps//344/273/225/346/247/230/347/255/226/345/256/232.md

@@ -18,6 +18,7 @@ primary_output: docs/02_ユースケース仕様/<カテゴリ>/UC-N-xxx.md
 ## ユーザー入力
 
 `$ARGUMENTS` が機能説明。空でコマンドしていない限り、繰り返し入力を求めない。
+ただし **`$ARGUMENTS` が空** の場合は停止せず、AI 側で候補提案を行ってユーザー選択に進む。
 
 ```text
 $ARGUMENTS
@@ -41,6 +42,17 @@ $ARGUMENTS
   - まず作る 1 件（最小価値）
 - 合意後は **1 件ずつ** `uc-next-start.sh` で作成する（CRUD は原則別 UC）。
 
+### 0.5. 引数なし時の候補提示（必須）
+
+- 条件: `$ARGUMENTS` が空。
+- 挙動:
+  1. AI がこのプロジェクト向けの機能案を **3〜5 件**提示する。
+  2. 各案は 1 行で、`案N: 目的 / 主な利用者 / 想定カテゴリ` の形式で簡潔に示す。
+  3. 「番号で選択」または「自由入力で別案指定」を案内する。
+  4. **ユーザーが選ぶまで `uc-next-start.sh` を実行しない**。
+- ユーザー回答後:
+  - 選択された案（または自由入力文）を今回の機能説明として扱い、以降のステップを通常どおり実行する。
+
 ### 1. ブランチ用短名（2〜4 語）
 
 - 機能説明からキーワード抽出。**ブランチ名は ASCII のみ**、kebab-case（例: order-placement, user-auth）。
@@ -65,7 +77,7 @@ $ARGUMENTS
 
 ### 4. 本文生成の内訳
 
-1. 入力パース。空なら ERROR「機能説明が指定されていません」
+1. 入力パース。空なら「0.5 引数なし時の候補提示」を実施し、選択後に続行する（即 ERROR にしない）
 2. 重要概念（アクター・アクション・データ・制約）
 3. 不明点: **推測で確定しない** → **`[要確認: ...]`**。付けるのは影響大・解釈複数・デフォルト無しのときのみ。**上限 3 個**。優先: スコープ > セキュリティ > UX > 技術詳細
 4. 「ユーザーシナリオとテスト」を埋める。フロー特定できなければ ERROR
@@ -99,6 +111,8 @@ checklists を使う場合のみ `FEATURE_DIR/checklists/requirements.md` を生
 
 ※ 分解提案を経た場合は、採用された UC 分割案（採用順）も合わせて報告する。
 
+※ **UC 洗い出しが完了したら** `./.spec-runner/phase-locks.json` の `uc_discovery.completed` を `true` にする（以降 `domain` に進む）。
+
 **注**: スクリプトは書き込み前にブランチ作成・チェックアウトと仕様の初期化を行う。
 
 ## 付録 A: 仕様品質チェックリスト例

package/templates/.spec-runner/templates/phase-locks.json

@@ -25,6 +25,11 @@
     "locked_at": null,
     "reviewed_by": null
   },
+  "uc_discovery": {
+    "completed": false,
+    "locked_at": null,
+    "reviewed_by": null
+  },
   "uc_reviewed": [],
   "quality": {
     "_comment": "clarify/analyze の実行済み管理（対象ドキュメントのベース名）",

package/templates/mkdocs-scaffold/docs/index.md

@@ -0,0 +1,32 @@
+# 設計ドキュメント
+
+このサイトは **MkDocs Material** で、プロジェクトの `docs/` 配下にある **憲章・設計書・仕様** をまとめて閲覧するためのものです。
+
+## spec-runner との対応（既定パス）
+
+| 領域 | パス（プロジェクトルートから） |
+|------|------------------------------|
+| 憲章 | `docs/01_憲章/憲章.md` |
+| ユースケース仕様 | `docs/02_ユースケース仕様/` |
+| ドメイン設計 | `docs/03_ドメイン設計/` |
+| アーキテクチャ | `docs/04_アーキテクチャ/` |
+| インフラ設計 | `docs/05_インフラ設計/` |
+| API 仕様 | `docs/06_API仕様/` |
+
+手順・コマンド・ロックの考え方は **[spec-runner のフロー](spec-runner-フロー.md)** を参照してください（`npx spec-runner` 時にコピーされます）。
+
+---
+
+## プレビュー起動
+
+リポジトリルートで次を実行します（Python 3 と `requirements-docs.txt` 用の仮想環境 `.venv-docs/` が使われます）。
+
+```bash
+./.spec-runner/scripts/docs-serve.sh
+```
+
+`8000` 番が使用中の場合はポートを変えられます。
+
+```bash
+DOCS_PORT=8001 ./.spec-runner/scripts/docs-serve.sh
+```

package/templates/mkdocs-scaffold/mkdocs.yml

@@ -0,0 +1,16 @@
+site_name: プロジェクト設計ドキュメント
+site_description: 憲章・ユースケース・ドメイン・アーキテクチャ等（spec-runner の docs/ 配下を閲覧）
+theme:
+  name: material
+  language: ja
+  features:
+    - navigation.sections
+    - navigation.expand
+    - content.code.copy
+markdown_extensions:
+  - admonition
+  - toc:
+      permalink: true
+# 「ホーム」を先頭に固定し、それ以外の Markdown（01_憲章 … など）は MkDocs が自動でナビに追加
+nav:
+  - ホーム: index.md

package/templates/mkdocs-scaffold/requirements-docs.txt

@@ -0,0 +1,2 @@
+mkdocs==1.6.1
+mkdocs-material==9.7.6