claude-code-conductor 2.31.0__tar.gz → 2.32.0__tar.gz

claude_code_conductor-2.32.0/.claude/hooks/recall_autorebuild.py

@@ -0,0 +1,437 @@
+#!/usr/bin/env python3
+"""Stop hook: automatically rebuild the recall index when it is stale.
+
+Mode 1 (default / Stop hook):
+  Checks if the recall index exists and is stale, then spawns this same
+  script as a detached background worker (Mode 2) and exits immediately
+  (exit 0, no blocking).
+
+Mode 2 (--rebuild-worker):
+  Invoked by Mode 1.  Runs ``c3 recall rebuild --target <repo_root>``
+  via subprocess, then releases the lock in a finally block.
+
+The hook never outputs ``{"decision": "block"}`` and never blocks the
+Claude turn from completing (ADR-5).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+# CLAUDE.md §9-3: reconfigure stdout/stderr to UTF-8 on Windows.
+try:
+    if sys.stdout and hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    if sys.stderr and hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8")
+except AttributeError:
+    pass
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_DISABLE_ENV_VAR = "C3_RECALL_AUTOREBUILD_DISABLE"
+
+# Lock TTL in seconds.  rebuild normally finishes in tens of seconds;
+# 600 s gives a generous safety margin (ADR-3).
+_LOCK_TTL = 600
+
+# Worker subprocess timeout (seconds).
+# Intentionally equal to _LOCK_TTL: the lock becomes reclaimable as stale
+# immediately after the worker timeout fires, preventing a stuck lock state.
+_WORKER_TIMEOUT = 600
+
+# Stale source globs — keep in sync with recall_inject._STALE_SOURCE_GLOBS.
+# CR-L-02: these must mirror c3.recall_index.collect_sources source kinds.
+_STALE_SOURCE_GLOBS = (
+    (Path(".claude") / "memory" / "sessions", "*.tmp"),
+    (Path(".claude") / "agent-memory", "*.md"),
+    (Path(".claude") / "reports" / "archive", "*.md"),
+)
+_STALE_PATTERNS_JSON = Path(".claude") / "memory" / "patterns.json"
+
+
+# ---------------------------------------------------------------------------
+# Pure helper functions (testable without side effects)
+# ---------------------------------------------------------------------------
+
+
+def find_repo_root() -> Path | None:
+    """Return the directory containing ``.claude/``, or None.
+
+    When CLAUDE_PROJECT_DIR is set, only that exact directory is checked
+    (no ancestor traversal).  This prevents false positives when running
+    inside a temp directory whose parent happens to contain ``.claude``.
+
+    When CLAUDE_PROJECT_DIR is not set, searches from cwd upward.
+
+    Note: this intentionally differs from ``recall_inject.find_repo_root``.
+    ``recall_inject`` always walks upward from cwd regardless of
+    CLAUDE_PROJECT_DIR; this hook skips ancestor traversal when the env var
+    is set to avoid false positives in hook context (temp-dir invocations).
+    Cross-reference: .claude/hooks/recall_inject.py ``find_repo_root``.
+    """
+    env_dir = os.getenv("CLAUDE_PROJECT_DIR")
+    if env_dir:
+        try:
+            candidate = Path(env_dir).resolve()
+        except (OSError, ValueError):
+            # L-04 [SR-V-001]: null バイト等の不正パスで resolve() が ValueError を投げる場合
+            # 例外を伝播させず None を返す（ADR-6）。
+            return None
+        if (candidate / ".claude").is_dir():
+            return candidate
+        return None
+    # No env override: walk upward from cwd.
+    here = Path.cwd().resolve()
+    for candidate in [here, *here.parents]:
+        if (candidate / ".claude").is_dir():
+            return candidate
+    return None
+
+
+def index_exists(repo_root: Path) -> bool:
+    """Return True if the recall HNSW index file exists.
+
+    Only ``recall.hnsw`` is checked — not ``recall_meta.json`` — because
+    this hook's purpose is to trigger a rebuild when the index is stale.
+    If the binary index is present (even without a metadata sidecar),
+    the stale check in ``index_is_stale_fast`` is meaningful and we should
+    proceed.  ``recall_inject`` checks both files because it needs a valid
+    meta to run a search; we do not run a search here.
+    """
+    index = repo_root / ".claude" / "state" / "recall.hnsw"
+    return index.exists()
+
+
+def index_is_stale_fast(repo_root: Path) -> bool:
+    """Return True if any recall source file is newer than the index.
+
+    Uses only stat() calls — never reads file contents — to stay fast
+    enough for every-Stop invocation (ADR-1).
+
+    Stale source globs are kept in sync with recall_inject._STALE_SOURCE_GLOBS
+    (CR-L-02: mirror c3.recall_index.collect_sources when adding/removing
+    source kinds).
+
+    Symlinks are skipped to avoid reading mtime of files outside the
+    C3 source tree.
+    """
+    index_path = repo_root / ".claude" / "state" / "recall.hnsw"
+    if not index_path.exists():
+        # Defensive guard for independent callers: main() already checks
+        # index_exists() before calling this function, but callers outside
+        # main() benefit from this early return rather than silently
+        # returning False with no indication of the missing index.
+        return False
+    try:
+        index_mtime = index_path.stat().st_mtime
+    except OSError:
+        return False
+
+    for rel_dir, pattern in _STALE_SOURCE_GLOBS:
+        absolute = repo_root / rel_dir
+        if not absolute.is_dir():
+            continue
+        for path in absolute.rglob(pattern):
+            # Skip symlinks (Cycle2-L-1 guard), non-files, and .gitkeep
+            # (parity with recall_inject.index_is_stale: .gitkeep files are
+            # placeholder markers, not actual recall source content).
+            if path.is_symlink() or not path.is_file() or path.name == ".gitkeep":
+                continue
+            try:
+                if path.stat().st_mtime > index_mtime:
+                    return True
+            except OSError:
+                continue
+
+    patterns_path = repo_root / _STALE_PATTERNS_JSON
+    if patterns_path.is_file() and not patterns_path.is_symlink():
+        try:
+            if patterns_path.stat().st_mtime > index_mtime:
+                return True
+        except OSError:
+            pass
+
+    return False
+
+
+def is_worktree(repo_root: Path) -> bool:
+    """Return True if repo_root is a git worktree (i.e. .git is a file).
+
+    In a normal repository, .git is a directory.
+    In a git worktree, .git is a file containing a ``gitdir:`` pointer.
+    We skip rebuild in worktrees to avoid spurious multi-index rebuilds
+    during parallel-agents runs (ADR-4).
+    """
+    dot_git = repo_root / ".git"
+    return dot_git.is_file()
+
+
+def _lock_path_for(repo_root: Path) -> Path:
+    """Return the canonical lock file path for the given repo root."""
+    return repo_root / ".claude" / "state" / "recall_rebuild.lock"
+
+
+def acquire_lock(lock_path: Path, ttl: int, now: float | None = None) -> Path | None:
+    """Attempt to acquire the rebuild lock atomically.
+
+    Uses os.open(O_CREAT|O_EXCL) for cross-platform atomic creation.
+
+    - If the lock does not exist: create it and return a truthy token.
+    - If the lock exists and mtime + ttl > now (fresh): return None (failed).
+    - If the lock exists and mtime + ttl <= now (stale): remove it,
+      then create a new lock and return a truthy token (ADR-3).
+
+    TOCTOU note: between the stale-lock deletion and the O_EXCL creation,
+    another process may race to create the lock first.  In that case
+    ``os.open`` raises ``FileExistsError`` and this function returns ``None``.
+    Returning ``None`` here is correct and expected behaviour — the other
+    process won the race and will perform the rebuild.
+
+    ``now`` is injectable for deterministic testing.
+    """
+    if now is None:
+        now = time.time()
+
+    # Check for existing lock.
+    if lock_path.exists():
+        try:
+            mtime = lock_path.stat().st_mtime
+        except OSError:
+            mtime = 0.0
+        if mtime + ttl > now:
+            # Fresh lock held by another process — refuse acquisition.
+            return None
+        # Stale lock — remove and fall through to create a new one.
+        try:
+            lock_path.unlink()
+        except OSError:
+            pass
+
+    # Atomic create via O_CREAT|O_EXCL.
+    # L-01 [SR-NEW]: 0o600 を明示してロックファイルを所有者のみ読み書き可能に制限する。
+    # Windows は mode 引数を無視するが、指定しても無害。
+    try:
+        fd = os.open(
+            str(lock_path),
+            os.O_CREAT | os.O_EXCL | os.O_WRONLY,
+            0o600,
+        )
+    except FileExistsError:
+        # Another process won the race.
+        return None
+    except OSError:
+        return None
+
+    try:
+        content = json.dumps({"pid": os.getpid(), "started": now}).encode()
+        os.write(fd, content)
+    finally:
+        os.close(fd)
+
+    return lock_path  # Truthy token.
+
+
+def release_lock(lock_path: Path) -> None:
+    """Remove the lock file.  Safe to call even if the file does not exist."""
+    try:
+        lock_path.unlink()
+    except FileNotFoundError:
+        pass
+    except OSError:
+        pass
+
+
+def build_worker_argv(self_path: Path, repo_root: Path) -> list[str]:
+    """Return the argv list to launch this script as a rebuild worker.
+
+    The resulting command is:
+      python <self_path> --rebuild-worker --target <repo_root>
+    """
+    return [
+        sys.executable,
+        str(self_path),
+        "--rebuild-worker",
+        "--target",
+        str(repo_root),
+    ]
+
+
+def spawn_detached(repo_root: Path) -> None:
+    """Launch this script in worker mode as a detached background process.
+
+    Platform specifics (ADR-2):
+    - Windows: DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW
+    - POSIX: start_new_session=True
+    - Common: close_fds=True, stdin/stdout/stderr=DEVNULL
+    """
+    self_path = Path(__file__).resolve()
+    argv = build_worker_argv(self_path, repo_root)
+    devnull = subprocess.DEVNULL
+
+    # L-02 [SR-K-003]: ANTHROPIC_/CLAUDE_/OPENAI_ プレフィックスの変数を除外した最小 env を構成する。
+    # Note: CLAUDE_PROJECT_DIR も CLAUDE_ プレフィックスで除外されるが、worker は
+    # --target 引数で repo_root を受け取るため CLAUDE_PROJECT_DIR 除外の影響を受けない。
+    _EXCLUDED_PREFIXES = ("ANTHROPIC_", "CLAUDE_", "OPENAI_")
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if not any(k.upper().startswith(p) for p in _EXCLUDED_PREFIXES)
+    }
+
+    kwargs: dict = {
+        "close_fds": True,
+        "stdin": devnull,
+        "stdout": devnull,
+        "stderr": devnull,
+        "env": env,
+    }
+    if sys.platform == "win32":
+        kwargs["creationflags"] = (
+            subprocess.DETACHED_PROCESS
+            | subprocess.CREATE_NEW_PROCESS_GROUP
+            | subprocess.CREATE_NO_WINDOW
+        )
+    else:
+        kwargs["start_new_session"] = True
+
+    subprocess.Popen(argv, **kwargs)
+
+
+def run_rebuild_worker(repo_root: Path) -> None:
+    """Mode 2: run ``c3 recall rebuild --target <repo_root>`` synchronously.
+
+    Releases the lock in a finally block regardless of success or failure
+    (ADR-3).
+    """
+    # M-01 [SR-V-002]: --target パスの .claude/ 存在を検証し、なければ rebuild しない。
+    # 不正なターゲット（シンボリックアタック等）による意図しない rebuild を防止する。
+    if not (repo_root / ".claude").is_dir():
+        return
+
+    # L-03 [SR-R-004]: C3_RECALL_AUTOREBUILD_DEBUG=1 のとき子プロセスの stderr を親に継承させる。
+    # None を渡すと subprocess.run のデフォルト（親 stderr 継承）になる。
+    debug = os.environ.get("C3_RECALL_AUTOREBUILD_DEBUG") == "1"
+    stderr_target = None if debug else subprocess.DEVNULL
+
+    # Windows: 孫プロセス（c3 recall rebuild = console app の python.exe）が
+    # 新しいコンソールウィンドウを確保して一瞬表示されるのを防ぐ。worker 自身は
+    # DETACHED_PROCESS でコンソールを持たないため、明示しないと孫が新規確保する。
+    run_kwargs: dict = {
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+        "stderr": stderr_target,
+        "timeout": _WORKER_TIMEOUT,
+    }
+    if sys.platform == "win32":
+        run_kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+
+    lock_path = _lock_path_for(repo_root)
+    try:
+        subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "c3.cli",
+                "recall",
+                "rebuild",
+                "--target",
+                str(repo_root),
+            ],
+            **run_kwargs,
+        )
+    except Exception as e:
+        sys.stderr.write(f"[recall_autorebuild] worker error: {type(e).__name__}\n")
+    finally:
+        release_lock(lock_path)
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> int:
+    """Stop hook entry point.  Always returns 0 (never blocks Claude turn).
+
+    Flow (ADR-5, ADR-6):
+      1. Check disable env var.
+      2. Read Stop payload from stdin (errors are swallowed).
+      3. Resolve repo root; skip if unknown.
+      4. Skip if inside a git worktree (ADR-4).
+      5. Skip if recall index does not exist.
+      6. Skip if index is not stale (ADR-1).
+      7. Acquire rebuild lock (skip on contention / ADR-3).
+      8. Spawn worker; release lock on spawn failure.
+    """
+    # 1. Disable env var.
+    if os.environ.get(_DISABLE_ENV_VAR) == "1":
+        return 0
+
+    # 2. Read stdin (Stop payload).  Errors are harmless — we don't use
+    #    the payload for anything meaningful here, just consume it.
+    try:
+        sys.stdin.read()
+    except Exception:
+        pass
+
+    try:
+        # 3. Repo root.
+        repo_root = find_repo_root()
+        if repo_root is None:
+            return 0
+
+        # 4. Worktree guard.
+        if is_worktree(repo_root):
+            return 0
+
+        # 5. Index existence.
+        if not index_exists(repo_root):
+            return 0
+
+        # 6. Stale check (stat only — ADR-1).
+        if not index_is_stale_fast(repo_root):
+            return 0
+
+        # 7. Acquire lock.
+        lock_path = _lock_path_for(repo_root)
+        token = acquire_lock(lock_path, _LOCK_TTL)
+        if token is None:
+            return 0
+
+        # 8. Spawn detached worker.
+        try:
+            spawn_detached(repo_root)
+        except Exception:
+            release_lock(lock_path)
+
+    except Exception:
+        pass
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Worker mode dispatch
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    if "--rebuild-worker" in sys.argv:
+        # Mode 2: resolve --target and run rebuild worker.
+        try:
+            idx = sys.argv.index("--target")
+            repo_root = Path(sys.argv[idx + 1]).resolve()
+        except (ValueError, IndexError):
+            sys.exit(0)
+        run_rebuild_worker(repo_root)
+        sys.exit(0)
+    else:
+        # Mode 1: Stop hook.
+        sys.exit(main())

{claude_code_conductor-2.31.0 → claude_code_conductor-2.32.0}/.claude/settings.json

@@ -7,6 +7,7 @@
       "Bash(python .claude/hooks/restore_session.py*)",
       "Bash(python .claude/hooks/permission_handler.py*)",
       "Bash(python .claude/hooks/statusline.py*)",
+      "Bash(python .claude/hooks/recall_autorebuild.py*)",
       "Bash(python .claude/skills/dev-workflow/scripts/review_hint_inject.py*)",
       "Bash(python .claude/skills/dev-workflow/scripts/record_review_decision.py*)",
       "Bash(python .claude/skills/dev-workflow/scripts/record_tier_outcome.py*)",
@@ -214,6 +215,11 @@
             "type": "command",
             "command": "python",
             "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session_stop.py"]
+          },
+          {
+            "type": "command",
+            "command": "python",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/recall_autorebuild.py"]
           }
         ]
       }

{claude_code_conductor-2.31.0 → claude_code_conductor-2.32.0}/.claude/skills/dev-workflow/references/design-rubric.md

@@ -29,6 +29,7 @@ architect は interviewer と異なり**構造化（選択肢付き）**で確
 
 `requirements-report`（コンテキスト内になければ Glob で最新を Read）と既存コード（Glob / Grep）を読み、
 床 4 観点を「判明 / 未判明」でマークする。要件から自明に決まる設計判断は再質問しない。
+ユーザーが設計関連の資料（PDF / 画像 / 既存ドキュメント等）を提示している場合は Read で読み込み、観点の判明マークに反映する（ユーザーに事前執筆は求めない）。
 
 ### Step 2: 技術スタック制約を起点に動的確認
 

{claude_code_conductor-2.31.0 → claude_code_conductor-2.32.0}/.claude/skills/dev-workflow/references/interview-rubric.md

@@ -33,6 +33,7 @@
 ヒアリングを始める前に、**会話コンテキスト**と**既存 `requirements-report`**（あれば Glob で最新を Read）を読み、
 床 5 観点それぞれを「判明 / 未判明」でマークする。
 
+- **ユーザーが資料（PDF / 画像 / 既存の要件定義書・ドキュメント等）を提示している場合は Read で読み込み**、その内容からも観点を判明マークする（資料ドリブンの壁打ち。ユーザーに指示書の事前執筆は求めず、既に持っている資料を土台に未知だけを動的に掘る）。
 - **判明済みの観点は再質問しない**（ユーザーが既に話した内容を聞き返さない）。
 - 判明が部分的なら「未判明（部分）」とし、不足部分だけを後続で確認する。
 

{claude_code_conductor-2.31.0 → claude_code_conductor-2.32.0}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [2.32.0] - 2026-06-07
+
+**recall 索引の自動リビルドを配布物に追加（機能追加・破壊的変更なし）**: 配布元で試作・運用していた Stop hook `recall_autorebuild.py` を配布物（`.claude/hooks/`）へ昇格し、全利用先で**既定有効**にした。セッション終了（Stop）ごとに recall 索引（`.claude/state/recall.hnsw`）が stale かを stat のみで軽量判定し、stale なら `c3 recall rebuild` を detached background プロセスで起動して索引を自動で新鮮化する。LLM 非関与の決定論的 CLI を呼ぶだけなので、過去に `llm_summary.md`（summarize-memory）廃止の真因となった LLM 出力汚染・Stop 自己再トリガーループは原理的に発生しない。
+
+### 追加
+
+- **`.claude/hooks/recall_autorebuild.py`（新規・配布 hook）**: Stop hook。Mode1=判定して detached spawn、Mode2（`--rebuild-worker`）=`python -m c3.cli recall rebuild --target <root>` を実行しロックを finally で解放。多重ガード: 索引未構築なら no-op（`index_exists`）／stale でなければ skip／git worktree では skip（parallel-agents 中の多重リビルド回避）／ロック（`O_CREAT|O_EXCL` + TTL 600s・stale 回収）で多重起動防止／常に exit 0（Claude のターンをブロックしない・`decision:block` を出さない）／spawn 子 env から `ANTHROPIC_`/`CLAUDE_`/`OPENAI_` を除外／Windows は `CREATE_NO_WINDOW`／3 OS 対応。`C3_RECALL_AUTOREBUILD_DISABLE=1` で無効化、`C3_RECALL_AUTOREBUILD_DEBUG=1` で worker stderr 継承。
+- **`.claude/settings.json` の Stop に登録**（`session_stop.py` と並列）し、`Bash(python .claude/hooks/recall_autorebuild.py*)` を allow に追加。
+
+### 後方互換
+
+- 追加 hook のみで公開 API・CLI・DB スキーマ・他 hook に変更なし。recall 索引を構築していない利用先では `index_exists` で no-op となり無影響。既定有効だが `C3_RECALL_AUTOREBUILD_DISABLE=1` でオプトアウト可能。**破壊的変更なし**・migration 不要。
+
+## [2.31.1] - 2026-06-06
+
+**ドキュメント PATCH（コード変更・破壊的変更・migration なし）**: v2.31.0 で導入した動的ヒアリング/設計ルーブリックの Step 1（既知情報の取り込み）に、**資料ドリブンの壁打ち**を明文化した。ユーザーが提示した資料（PDF / 画像 / 既存の要件定義書・ドキュメント等）を Read で読み込み、床観点の判明マークに反映する。ユーザーに指示書の事前執筆を求めず、既に持っている資料を土台に未知だけを動的に掘る方針。
+
+### ドキュメント
+
+- `.claude/skills/dev-workflow/references/interview-rubric.md` / `design-rubric.md` の Step 1 に「ユーザー提示資料があれば Read で読み込み観点を判明マーク（事前執筆は求めない）」を 1 行ずつ追記。
+
+### 後方互換
+
+- reference ファイル本文への追記のみ。`SKILL.md`・公開 API・CLI・DB スキーマ・hook に変更なし。資料は元々会話コンテキストとして読めるため挙動の実体変化はなく、rubric の指示を明示化しただけ。**破壊的変更なし**・migration 不要。
+
 ## [2.31.0] - 2026-06-06
 
 **標準ワークフローのヒアリング/設計フェーズを動的化（機能改善・破壊的変更なし）**: `dev-workflow` のフェーズ A（interviewer）と フェーズ B（architect）の固定 `AskUserQuestion` テンプレ（毎回同じ4択・3択）を、ルーブリック型ハイブリッドの動的生成に置き換えた。「聞く観点カテゴリ＝固定（予測可能）／質問文・選択肢・深掘り＝動的（タスク固有）」を両立させ、固定テンプレでは拾えなかった観点（特に成功条件／受け入れ基準）を掘れるようにする。

{claude_code_conductor-2.31.0 → claude_code_conductor-2.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-conductor
-Version: 2.31.0
+Version: 2.32.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.31.0 → claude_code_conductor-2.32.0}/src/c3/__init__.py

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