claude-code-conductor 2.19.0__tar.gz → 2.20.0__tar.gz

{claude_code_conductor-2.19.0 → claude_code_conductor-2.20.0}/.claude/breaking-changes.txt

@@ -5,3 +5,4 @@
 # Lines starting with '#' are comments. Blank lines ignored.
 
 v2.11.0|summarize-memory agent + skill removed; replaced by `c3 recall`|summarize-memory エージェント / skill を完全廃止。代替は `c3 recall` の意味検索。
+v2.20.0|hooks/schema.sql removed; SQLite schema is now managed by c3/migrations/ (auto-applied at session_start)|hooks/schema.sql を削除しました。SQLite スキーマは c3/migrations/ (wheel 内) で管理され session_start で自動適用されます。

{claude_code_conductor-2.19.0 → claude_code_conductor-2.20.0}/.claude/deletions.txt

@@ -37,3 +37,6 @@ skills/phase-c-plan/SKILL.md
 skills/phase-d-implement/SKILL.md
 skills/phase-debug/SKILL.md
 skills/phase-e-review/SKILL.md
+
+# ---- v2.20.0: schema.sql を c3/migrations/ へ移行 ----
+hooks/schema.sql

{claude_code_conductor-2.19.0 → claude_code_conductor-2.20.0}/.claude/docs/config-policy.md

@@ -24,6 +24,7 @@
 .dev/hooks/                            配布元専用 hook（配布されない）
 src/c3/_excludes.py                    wheel 除外パターン（配布元のビルド制御）
 hatch_build.py                         _excludes.py の重複定義（ビルド時専用）
+src/c3/migrations/                     SQLite schema migration SQL ファイル群（Python package・wheel 同梱・.claude/ 配下ではないため 3 ファイル同期対象外）
 ```
 
 ### 1-2. 利用先プロジェクト（C3 ユーザー向け）
@@ -111,7 +112,7 @@ hatch_build.py                         _excludes.py の重複定義（ビルド
 
 | # | カテゴリ | 配布 | c3 update が更新 | 理由 |
 |---|---|---|---|---|
-| 1 | `.claude/hooks/*.py` | ○ | ○ | Claude Code lifecycle hook の実体。配布先で動作する。例外: `subagent_log.py` のみ除外（個人デバッグ用） |
+| 1 | `.claude/hooks/*.py` | ○ | ○ | Claude Code lifecycle hook の実体。配布先で動作する。例外: `subagent_log.py` のみ除外（個人デバッグ用）。v2.20.0 で `hooks/schema.sql` を削除し SQLite スキーマは `src/c3/migrations/` に移管 |
 | 2 | `.claude/agents/*.md` | ○ | ○ | ペルソナ定義。配布先で読まれる。例外: `tdd-develop.md` のみ除外（v2.1.0 廃止） |
 | 3 | `.claude/skills/*/` | ○ | ○ | オーケストレーション/ユーティリティ skill 定義（`scripts/` / `templates/` 等サブディレクトリ含む）。例外: `worktree-tdd-workflow/*` のみ除外（v2.1.0 廃止） |
 | 4 | `.claude/rules/*.md` | ○ | ○ | C3 配布デフォルトルール（常時注入対象） |

{claude_code_conductor-2.19.0 → claude_code_conductor-2.20.0}/.claude/hooks/session_start.py

@@ -12,22 +12,23 @@
 設計判断:
 - 旧 3 ファイルを統合することで SessionStart hook は本ファイル 1 本のみで完結
 - init-session SKILL.md からの手動 2 回呼び出しが不要になる
-- 旧 init_c3_db.py の `apply_schema()` / `SCHEMA_VERSION` は test 互換性のため
-  module レベルでそのまま公開する
+- v2.20.0 で apply_schema() を c3.migrate.apply_pending_migrations() に委譲。
+  SCHEMA_VERSION / SCHEMA_PATH 定数および schema.sql は廃止。
 """
 
 from __future__ import annotations
 
 import json
+import logging
 import os
 import shutil
-import sqlite3
 import sys
 import tempfile
-from datetime import datetime, timezone
 
 from session_utils import is_worktree
 
+logger = logging.getLogger(__name__)
+
 try:
     sys.stdin.reconfigure(encoding="utf-8")
     sys.stdout.reconfigure(encoding="utf-8")
@@ -71,7 +72,11 @@ def _run_clear_file_history() -> None:
         except FileNotFoundError:
             pass  # already deleted by another process between listdir and unlink/rmtree
         except Exception as e:
-            print(f'[clear-file-history] 削除に失敗: {name} ({e})', file=sys.stderr)
+            # [SR-R-001] shutil.rmtree / os.unlink のエラーメッセージには失敗したパス
+            # （FILE_HISTORY_DIR はホームディレクトリ配下のためユーザー名を含む）が
+            # 含まれる可能性がある。main() の SR M-1 修正と一貫して例外型名のみ出力する。
+            logger.debug('[clear-file-history] delete failed: %s', name, exc_info=True)
+            print(f'[clear-file-history] 削除に失敗: {name} ({type(e).__name__})', file=sys.stderr)
 
     print(f'[clear-file-history] {deleted} 件削除しました。')
 
@@ -113,7 +118,9 @@ def _run_enable_sandbox() -> None:
         try:
             settings = json.load(f)
         except json.JSONDecodeError as e:
-            print(f'[enable-sandbox] settings.json の JSON 解析に失敗しました: {e}')
+            # [SR-R-001] 一貫性のため例外型名のみ出力（JSONDecodeError 自体はパスを含まない
+            # が、SR M-1 / _run_clear_file_history と方針を統一する）。
+            print(f'[enable-sandbox] settings.json の JSON 解析に失敗しました: {type(e).__name__}')
             return
 
     if settings.get('sandbox', {}).get('enabled') is True:
@@ -132,7 +139,14 @@ def _run_enable_sandbox() -> None:
                 json.dump(settings, tmp_f, ensure_ascii=False, indent=2)
                 tmp_f.write('\n')
         except Exception:
-            os.close(fd)
+            # [CR-E-001] os.fdopen 成功後の書き込み例外では with __exit__ が既に
+            # fd を閉じているため、ここでの os.close(fd) は OSError(Bad file
+            # descriptor) を raise し元の例外を上書きしてしまう。os.fdopen 自体が
+            # 失敗して with に入らなかった場合のみ fd 解放が必要なので OSError を無視する。
+            try:
+                os.close(fd)
+            except OSError:
+                pass
             raise
         os.replace(tmp_path, settings_path)
         tmp_path = None  # os.replace が成功したので finally でのクリーンアップ不要
@@ -147,19 +161,10 @@ def _run_enable_sandbox() -> None:
 # 3. C3 SQLite DB 初期化（旧 init_c3_db.py）
 # =============================================================================
 
-# 現行スキーマバージョン。schema.sql に破壊的変更を入れたら +1 して
-# マイグレーションロジックを apply_schema() に追加する。
-SCHEMA_VERSION = 3  # v2.0.0 で PO 廃止に伴い po_results / po_status を削除
-
 _HOOKS_DIR = os.path.dirname(os.path.abspath(__file__))
 _CLAUDE_DIR = os.path.dirname(_HOOKS_DIR)
 STATE_DIR = os.path.join(_CLAUDE_DIR, 'state')
 DB_PATH = os.path.join(STATE_DIR, 'c3.db')
-SCHEMA_PATH = os.path.join(_HOOKS_DIR, 'schema.sql')
-
-
-def _now_iso() -> str:
-    return datetime.now(timezone.utc).astimezone().isoformat(timespec='seconds')
 
 
 def _ensure_state_dir() -> None:
@@ -167,38 +172,36 @@ def _ensure_state_dir() -> None:
     os.makedirs(STATE_DIR, exist_ok=True)
 
 
-def apply_schema(db_path: str = DB_PATH, schema_path: str = SCHEMA_PATH) -> None:
-    """schema_path の DDL を db_path の SQLite に適用する。
+def apply_schema(db_path: str = DB_PATH) -> list[str]:
+    """SQLite DB にスキーマ migration を適用する。
 
-    - WAL モードに切り替える
-    - schema.sql の CREATE TABLE IF NOT EXISTS 等を実行
-    - schema_version テーブルに現行バージョンを INSERT OR IGNORE
+    v2.20.0+: 実体は c3.migrate.apply_pending_migrations() に委譲。
+    schema.sql は廃止され、src/c3/migrations/ の連番 SQL ファイルで管理される。
 
-    冪等: 既存 DB に何度呼んでもエラーにならない。
+    戻り値: 今回新たに適用した migration version のリスト（例: ['001']）
     """
-    with open(schema_path, 'r', encoding='utf-8') as f:
-        ddl = f.read()
-
-    conn = sqlite3.connect(db_path, timeout=30)
+    from c3.migrate import apply_pending_migrations
     try:
-        # WAL モードを有効化（reader が writer をブロックしない）
-        conn.execute('PRAGMA journal_mode=WAL')
-        # 全 DDL を一括実行（CREATE TABLE IF NOT EXISTS なので冪等）
-        conn.executescript(ddl)
-        # スキーマバージョンを記録（既存なら無視）
-        conn.execute(
-            'INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)',
-            (SCHEMA_VERSION, _now_iso()),
+        return apply_pending_migrations(db_path)
+    except FileNotFoundError:
+        # migrations ディレクトリ不在（wheel が壊れている等）でもセッションは続行。
+        # [SR-R-001] 例外 e にはインストールパス（ユーザー名含む）が含まれるため
+        # stderr には固定文言のみ出力する。詳細は内部 logger（DEBUG）に残す。
+        logger.debug('apply_schema: migrations directory not found', exc_info=True)
+        print(
+            'warning: c3 migrations directory not found (wheel may be corrupted)',
+            file=sys.stderr,
         )
-        conn.commit()
-    finally:
-        conn.close()
+        return []
 
 
 def _run_init_c3_db() -> None:
     """C3 SQLite DB を初期化する."""
     _ensure_state_dir()
-    apply_schema()
+    # [CR-M-003] apply_schema() の戻り値（適用した migration version の list[str]）は
+    # 現状ログ・利用しない。セッション開始を妨げないことを最優先し、適用結果の通知は
+    # 行わない設計（将来 welcome メッセージ等で利用する場合はここで受ける）。
+    _ = apply_schema()
 
 
 # =============================================================================
@@ -222,7 +225,14 @@ def main() -> int:
             handler()
         except Exception as e:
             # 各ハンドラ失敗時は警告のみ（次のハンドラを継続）
-            print(f'[session_start:{label}] failed: {e}', file=sys.stderr)
+            # [SR-R-001] 例外メッセージには db_path 等のプロジェクトパスが含まれる
+            # 可能性がある（例: sqlite3.OperationalError）。stderr には例外型名のみ
+            # 出力し、詳細は内部 logger（DEBUG）に残す。
+            # NOTE(SR Info-2): exc_info=True は現状ハンドラ未設定で出力されないが、
+            # 将来 logging ハンドラを追加する場合はスタックトレースにインストールパスが
+            # 含まれる点に留意する。
+            logger.debug('[session_start:%s] handler failed', label, exc_info=True)
+            print(f'[session_start:{label}] failed: {type(e).__name__}', file=sys.stderr)
     return 0
 
 

{claude_code_conductor-2.19.0 → claude_code_conductor-2.20.0}/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## [2.20.0] - 2026-05-25
+
+**SQLite schema migration 枠組み導入**: `.claude/hooks/schema.sql` の「冪等 DDL 一発実行」から、`src/c3/migrations/` の「連番 NNN_xxx.sql migration runner」へ移行する基盤を整備する。
+v2.18.0 の `deletions.txt` 機構・v2.19.0 の `breaking-changes.txt` 機構の初の実運用ドッグフーディングでもある。
+
+### 機能追加
+
+- **`src/c3/migrate.py`（新規）**: SQLite migration runner。
+  公開 API `apply_pending_migrations(db_path, migrations_dir=None) -> list[str]` および例外クラス `MigrationError(RuntimeError)` を提供。
+  `src/c3/migrations/` 配下の連番 SQL ファイルを昇順に適用し、適用済み migration を `schema_migrations` テーブルで管理する。
+  WAL モード / busy_timeout=5000ms を冒頭で設定（既存 `c3.db.BUSY_TIMEOUT_MS` を SSOT として参照）。
+
+- **`src/c3/migrations/001_initial.sql`（新規）**: 既存 `hooks/schema.sql` の DDL を逐語移植 + bootstrap。
+  `schema_migrations` テーブル新設、旧 `schema_version` テーブル DROP、`BEGIN;` / `COMMIT;` 明示記述による transaction 境界保証を含む。
+
+- **`src/c3/migrations/__init__.py`（新規）**: Python package marker（wheel 自動同梱のため）。
+
+- **`src/c3/migrations/README.md`（新規）**: 命名規約（`NNN_xxx.sql`）・`BEGIN;`/`COMMIT;` 必須運用ルール・002 以降の追加手順を記載。
+
+- **`schema_migrations` テーブル（新規）**: 適用済み migration の一覧を保持（`version TEXT PK`, `applied_at TIMESTAMP`）。
+  旧 `schema_version (version INTEGER PK, applied_at TEXT)` を置換。
+
+### 変更
+
+- **`.claude/hooks/session_start.py`**: `apply_schema(db_path)` の実体を `c3.migrate.apply_pending_migrations()` に委譲。
+  戻り値が `None` → `list[str]`（適用した migration version のリスト）に変更。
+  migrations_dir 不在時は `FileNotFoundError` を warning として stderr に出力し、セッションは続行する（exit 0 維持の既存方針踏襲）。
+
+- **`src/c3/__init__.py`**: `__version__` を `"2.19.0"` から `"2.20.0"` に更新。
+
+### 破壊的変更
+
+- **`hooks/schema.sql` 削除**: `.claude/hooks/schema.sql` をリポジトリから削除。
+  SQLite スキーマは `src/c3/migrations/` (wheel 内) で管理され、`session_start` で自動適用される。
+  利用先からの削除は `deletions.txt` 機構（v2.18.0）によって `c3 update` 実行時に処理される。
+
+- **`apply_schema` の `schema_path` 引数削除**: `session_start.py::apply_schema()` から `schema_path` 引数を完全削除（deprecation 期間なし）。
+  呼び出し側で `schema_path=` を渡している場合は削除が必要（`c3 update` 実行後のテストコード等）。
+
+### ドキュメント
+
+- **`.claude/docs/config-policy.md`**:
+  - §1-1 配布元ディレクトリ表に `src/c3/migrations/` を追加（Python package・wheel 同梱・3 ファイル同期対象外）
+  - §3 カテゴリ #1 hooks 備考に「v2.20.0 で `hooks/schema.sql` を削除、SQLite スキーマは `src/c3/migrations/` に移管」を追記
+
+- **`.claude/breaking-changes.txt`**: v2.20.0 エントリ追記（`hooks/schema.sql` 削除）
+
+- **`.claude/deletions.txt`**: `hooks/schema.sql` 追記（利用先からの自動削除を `c3 update` 経由で実現）
+
+### ドッグフーディング
+
+- **v2.18.0 `deletions.txt` 機構**: `hooks/` 配下の非テスト SQL ファイル削除の初の実運用事例（過去は `agents/` / `skills/` の `.md` のみ）。
+- **v2.19.0 `breaking-changes.txt` 機構**: v2.20.0 エントリを新規追加して MINOR bump 表示路を初通過させる。
+- **`scripts/extract_breaking_changes.py`**: `--dry-run` / 通常実行 / `--check` のフルライフサイクル運用。
+
+### 影響
+
+- **既存利用先**: `c3 update` 実行時に v2.20.0 breaking change が表示される（v2.19.0 以降の利用先）。
+  `.claude/hooks/schema.sql` は `c3 update` 実行時に自動削除される。
+  次回セッション開始時に `apply_pending_migrations` が `schema_migrations` テーブルを新設し 001 を適用する。
+  既存データ（`review_decisions` 等）は保持される。`schema_version` テーブルは削除される。
+
+---
+
 ## [2.19.0] - 2026-05-24
 
 **基盤整備リリース第 3 弾**: `c3 update` 実行時に breaking changes 表示 + MAJOR 承認プロンプトを導入する。

{claude_code_conductor-2.19.0 → claude_code_conductor-2.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-conductor
-Version: 2.19.0
+Version: 2.20.0
 Summary: Multi-agent orchestration framework for Claude Code with Codex/Cursor adapters (C3)
 Project-URL: Homepage, https://github.com/satoh-y-0323/claude-code-conductor
 Project-URL: Repository, https://github.com/satoh-y-0323/claude-code-conductor

{claude_code_conductor-2.19.0 → claude_code_conductor-2.20.0}/src/c3/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Conductor (C3) - multi-agent orchestration framework for Claude Code."""
 
-__version__ = "2.19.0"
+__version__ = "2.20.0"

claude_code_conductor-2.20.0/src/c3/migrate.py

@@ -0,0 +1,260 @@
+"""C3 SQLite migration runner (v2.20.0 新規)。
+
+公開 API:
+  - apply_pending_migrations(db_path, migrations_dir=None) -> list[str]
+  - MigrationError(RuntimeError)
+
+命名規約:
+  migrations/ 配下の NNN_xxx.sql ファイル（NNN は 3 桁ゼロパディング連番）を
+  昇順で適用する。適用済みの version は schema_migrations テーブルで管理する。
+
+落とし穴 (architecture §10.4):
+  executescript() は内部で自動 COMMIT を発行するため、SQL ファイル内に BEGIN;
+  を書かないとステートメント単位の autocommit になり ROLLBACK が効かない。
+  各 migration ファイルは必ず BEGIN; で始まり COMMIT; で終わること。
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import sqlite3
+import warnings
+from pathlib import Path
+
+from c3.db import BUSY_TIMEOUT_MS
+
+logger = logging.getLogger(__name__)
+
+# migration ファイル名の命名規約パターン: NNN_説明.sql (ASCII 小文字・数字・アンダースコア)
+_MIGRATION_FILENAME_RE = re.compile(r"^(\d{3})_[a-z0-9_]+\.sql$")
+
+# デフォルト migrations ディレクトリ: このファイルと同階層の migrations/
+_DEFAULT_MIGRATIONS_DIR = Path(__file__).parent / "migrations"
+
+
+class MigrationError(RuntimeError):
+    """Migration の適用に失敗したことを示す例外。
+
+    raise されるのは _run_migration() 内のみ。発生時:
+    - 当該 migration の transaction は ROLLBACK 済み
+    - schema_migrations への INSERT も未実行（version 列に当該 version は無い）
+    - これより後ろの pending migration は適用されない
+    """
+
+
+def apply_pending_migrations(
+    db_path: Path | str,
+    migrations_dir: Path | None = None,
+) -> list[str]:
+    """未適用の migration を順次適用し、適用した version のリストを返す。
+
+    Args:
+        db_path: c3.db の絶対パス。文字列でも Path でも受け付ける。
+        migrations_dir: migration SQL を置くディレクトリ。省略時は
+            Path(__file__).parent / "migrations"（= src/c3/migrations/）。
+
+    Returns:
+        今回新たに適用した version のリスト（適用順）。
+        全 migration が既に適用済みなら空リスト。
+
+    Raises:
+        MigrationError: いずれかの migration の実行に失敗した場合。
+        FileNotFoundError: migrations_dir が存在しない場合。
+        sqlite3.Error: db_path が SQLite として開けない等の場合。
+
+    Note:
+        本関数を C3 runtime の session_start.py 経由（apply_schema()）で呼んだ場合、
+        MigrationError は session_start.py::main() の except Exception で warning 出力に
+        変換され exit 0 が維持される（architecture §3.2）。Python から直接呼んだ場合は
+        上記 Raises のとおり例外が伝播する。
+    """
+    if migrations_dir is None:
+        migrations_dir = _DEFAULT_MIGRATIONS_DIR
+
+    # migrations_dir 不在は早期 raise（wheel が壊れている兆候）
+    if not migrations_dir.exists():
+        raise FileNotFoundError(
+            f"migrations_dir が存在しません: {migrations_dir}"
+        )
+
+    # migration ファイル一覧取得（FileNotFoundError は伝播させる）
+    migrations = _list_migrations(migrations_dir)
+
+    conn = sqlite3.connect(str(db_path))
+    try:
+        # PRAGMA はパラメータバインドできないため int() で型を強制する
+        # （PRAGMA インジェクション防御 [SR-INJ-001] の踏襲）
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute(f"PRAGMA busy_timeout={int(BUSY_TIMEOUT_MS)}")
+
+        # schema_migrations テーブルを事前に作成する
+        # （_get_applied_versions の SELECT が失敗しないよう先行して CREATE）
+        _ensure_schema_migrations_table(conn)
+
+        applied_versions = _get_applied_versions(conn)
+
+        newly_applied: list[str] = []
+        for version, path in migrations:
+            if version in applied_versions:
+                continue
+            _run_migration(conn, version, path)
+            newly_applied.append(version)
+
+        return newly_applied
+    finally:
+        conn.close()
+
+
+def _list_migrations(migrations_dir: Path) -> list[tuple[str, Path]]:
+    """migrations_dir 内の NNN_xxx.sql ファイルを version 昇順で返す。
+
+    Args:
+        migrations_dir: migration SQL を置くディレクトリ。
+
+    Returns:
+        [(version, path), ...] を version の文字列昇順にソートしたリスト。
+        命名規約に違反するファイルはスキップ（warning ログを出す）。
+        version 重複の場合は最初の 1 件のみ採用（warning ログを出す）。
+
+    Raises:
+        FileNotFoundError: migrations_dir が存在しない場合。
+            apply_pending_migrations() から呼ばれる場合は呼び出し元 (L70) で先に
+            exists チェックされるため到達しない。本チェックは _list_migrations を
+            単独で利用するケースのための防衛的チェック。
+    """
+    if not migrations_dir.exists():
+        raise FileNotFoundError(
+            f"migrations_dir が存在しません: {migrations_dir}"
+        )
+
+    result: list[tuple[str, Path]] = []
+    seen_versions: dict[str, Path] = {}
+
+    for path in sorted(migrations_dir.glob("*.sql")):
+        if path.is_symlink():  # [SR-V-002] symlink は信頼境界外のため無視
+            logger.warning("シンボリックリンクをスキップします: %s", path.name)
+            continue
+        m = _MIGRATION_FILENAME_RE.match(path.name)
+        if not m:
+            logger.warning(
+                "命名規約違反のファイルをスキップします: %s "
+                "(期待パターン: NNN_description.sql, 例: 001_initial.sql)",
+                path.name,
+            )
+            continue
+
+        version = m.group(1)
+        if version in seen_versions:
+            logger.warning(
+                "version '%s' が重複しています: %s と %s。最初の 1 件のみ採用します。",
+                version,
+                seen_versions[version].name,
+                path.name,
+            )
+            continue
+
+        seen_versions[version] = path
+        result.append((version, path))
+
+    # version の文字列昇順でソート（= 連番昇順と一致）
+    result.sort(key=lambda t: t[0])
+    return result
+
+
+def _ensure_schema_migrations_table(conn: sqlite3.Connection) -> None:
+    """schema_migrations テーブルが存在しなければ作成する。
+
+    _get_applied_versions() の SELECT が失敗しないよう、事前に呼び出す。
+    テーブルが既に存在する場合は何もしない（IF NOT EXISTS）。
+    """
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS schema_migrations (
+            version    TEXT PRIMARY KEY,
+            applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+        )
+        """
+    )
+    conn.commit()
+
+
+def _get_applied_versions(conn: sqlite3.Connection) -> set[str]:
+    """schema_migrations テーブルから適用済み version の集合を返す。
+
+    Args:
+        conn: SQLite 接続。
+
+    Returns:
+        適用済み version の集合。テーブルが存在しない場合は空集合（防御的挙動）。
+        通常は apply_pending_migrations() 内で _ensure_schema_migrations_table()
+        を先行呼び出しするため、テーブル不在には到達しない。
+    """
+    try:
+        rows = conn.execute(
+            "SELECT version FROM schema_migrations"
+        ).fetchall()
+        return {row[0] for row in rows}
+    except sqlite3.OperationalError:
+        # schema_migrations テーブルが存在しない場合（防御的挙動）
+        logger.debug(
+            "_get_applied_versions: schema_migrations テーブルが見つかりません。"
+            "空集合を返します。"
+        )
+        return set()
+
+
+def _run_migration(
+    conn: sqlite3.Connection,
+    version: str,
+    path: Path,
+) -> None:
+    """1 件の migration SQL ファイルを実行し、schema_migrations に記録する。
+
+    Args:
+        conn: SQLite 接続（PRAGMA 設定済みであること）。
+        version: migration の version 文字列（例: '001'）。
+        path: migration SQL ファイルのパス。
+
+    Raises:
+        MigrationError: SQL 実行失敗 / schema_migrations への INSERT 失敗。
+
+    Notes:
+        SQL ファイル内に BEGIN; / COMMIT; を明示記述すること（architecture §10.4）。
+        executescript() は autocommit モードで動作するため、ファイル内 BEGIN;
+        がないとステートメント単位の autocommit になり ROLLBACK が効かない。
+
+        schema_migrations への INSERT は SQL ファイルの executescript() 後に
+        Python 側の別 transaction として実行する。SQL ファイル内に
+        INSERT OR IGNORE を書いている場合（001_initial.sql の bootstrap）と
+        二重になるが OR IGNORE で吸収される。
+
+        注意: executescript() 内の COMMIT; が発行された後に schema_migrations への
+        INSERT が失敗した場合、続く except 節の conn.rollback() は SQL 本体には作用しない
+        （SQL 本体は既に commit 済み）。この場合 schema_migrations への記録のみ未実行となり、
+        次回 session_start で同 version が再適用される。001_initial.sql の IF NOT EXISTS /
+        INSERT OR IGNORE による冪等設計で整合性を回復する（architecture §7.1 既知の落とし穴）。
+    """
+    sql = path.read_text(encoding="utf-8")
+
+    try:
+        # executescript() は内部で BEGIN を発行しないため、SQL ファイル内の
+        # BEGIN; ... COMMIT; の transaction 境界をそのまま尊重する。
+        conn.executescript(sql)
+
+        # schema_migrations への記録（SQL 本体とは別 transaction）
+        conn.execute(
+            "INSERT OR IGNORE INTO schema_migrations (version) VALUES (?)",
+            (version,),
+        )
+        conn.commit()
+
+    except sqlite3.Error as e:
+        # SQL 本体または INSERT が失敗した場合は ROLLBACK して MigrationError を raise
+        try:
+            conn.rollback()
+        except sqlite3.Error:
+            pass  # rollback 自体が失敗しても元の例外を優先する
+        raise MigrationError(
+            f"migration '{version}' ({path.name}) の適用に失敗しました: {e}"
+        ) from e

claude_code_conductor-2.19.0/.claude/hooks/schema.sql → claude_code_conductor-2.20.0/src/c3/migrations/001_initial.sql

@@ -1,15 +1,13 @@
--- C3 SQLite schema (duckdb-hybrid: DuckDB ハイブリッド構成の基盤)
+-- C3 SQLite migration 001: 初期スキーマ定義
 --
--- このファイルは session_start.py の _run_init_c3_db ハンドラから読まれ、
--- `.claude/state/c3.db` に対して冪等に CREATE TABLE IF NOT EXISTS で適用される。
--- WAL モードへの切り替えは session_start.py 側で PRAGMA journal_mode=WAL を実行する。
+-- .claude/hooks/schema.sql (v2.19.0 まで使用) の DDL を逐語移植し、
+-- schema_migrations テーブル (v2.20.0 新規) を追加する。
+-- 旧 schema_version テーブルは末尾で DROP する。
 --
 -- 書き込みは Python の sqlite3 経由、読み・分析は DuckDB の sqlite_scanner で
 -- ATTACH してアクセスする想定（書き込みフローは sqlite3 に統一する）。
---
--- スキーマ変更時は schema_version を上げて、session_start.py の apply_schema()
--- にマイグレーション処理を追加すること（CREATE TABLE IF NOT EXISTS だけで
--- 表現できない変更が必要になった場合の備え）。
+
+BEGIN;
 
 -- ---------------------------------------------------------------------------
 -- v2.0.0 マイグレーション: PO（Parallel Orchestra）廃止に伴うテーブル削除
@@ -20,12 +18,15 @@ DROP TABLE IF EXISTS po_results;
 DROP TABLE IF EXISTS po_status;
 
 -- ---------------------------------------------------------------------------
--- スキーマバージョン管理
+-- スキーマバージョン管理 (v2.20.0 新規)
 -- ---------------------------------------------------------------------------
+-- 旧 schema_version (version INTEGER PK) の代わりに、適用済み migration の
+-- 一覧を保持する schema_migrations テーブルを定義する。
+-- version は NNN_xxx.sql のファイル名先頭 3 桁の文字列（例: '001'）。
 
-CREATE TABLE IF NOT EXISTS schema_version (
-    version     INTEGER PRIMARY KEY,
-    applied_at  TEXT NOT NULL
+CREATE TABLE IF NOT EXISTS schema_migrations (
+    version    TEXT PRIMARY KEY,
+    applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
 
 -- ---------------------------------------------------------------------------
@@ -101,3 +102,20 @@ CREATE INDEX IF NOT EXISTS idx_agent_runs_session
     ON agent_runs(session_id, ts DESC);
 CREATE INDEX IF NOT EXISTS idx_agent_runs_agent
     ON agent_runs(agent_id, ts DESC);
+
+-- ---------------------------------------------------------------------------
+-- bootstrap: この migration 自体を schema_migrations に記録する
+-- ---------------------------------------------------------------------------
+-- apply_pending_migrations() の Python 側でも INSERT OR IGNORE を実行するが、
+-- 既存 DB（schema_version あり）からの初回 upgrade 時に SQL 内で先行記録しておく。
+-- Python 側の INSERT と二重になるが OR IGNORE で吸収される。
+INSERT OR IGNORE INTO schema_migrations (version) VALUES ('001');
+
+-- ---------------------------------------------------------------------------
+-- 旧 schema_version テーブルの削除 (v2.19.0 以前の DB からの upgrade)
+-- ---------------------------------------------------------------------------
+-- v2.19.0 以前の c3.db には schema_version (version INTEGER PK) が存在する。
+-- v2.20.0 では schema_migrations に一本化するため DROP する。
+DROP TABLE IF EXISTS schema_version;
+
+COMMIT;