@takuma-hirai/hirai-method 0.1.0

package/.claude/rules-details/workflow/reviewer-prompt.md

@@ -0,0 +1,100 @@
+> Layer A: [`workflow.md`](../../rules/workflow.md) §reviewer prompt 共通規約 | 本 file は **明示 Read のみ** (context 自動注入 OFF)
+
+# reviewer prompt 共通規約 詳細 (Layer B)
+
+reviewer prompt 共通規約の必須項目 5 (table) は Layer A 参照。本 file は起源 / 各項目の詳細手順 / OK-NG 例 / 既存規約との関係 / commands 連携 / bypass 運用詳細。
+
+## 起源 (2026-05-28 user 直接指示)
+
+PR #28 merge 後の session で user 直接指示「設計後,テスト設計後レビューする際プロジェクトの内容や、他のタスクの内容も鑑みてレビューするようにプロンプトを修正してください」を反映。task-51 iter 2 reviewer 6 並列レビューでも reviewer が single draft inside-out のみ評価し、他 task 重複 / 既存規範矛盾 / 既存実装再利用機会の検出が弱かった経験を踏まえ、reviewer prompt 共通規約として明文化する。
+
+## 必須項目 5 (詳細手順、Layer A §「reviewer prompt 共通規約」table 補完)
+
+1. **task ledger 確認 (`docs/tasks/list.md`)**:
+   - 🔄 進行中 task: 並行で着手中の作業との重複 / 競合可能性
+   - 🔲 未着手 task: 本対象が前提崩壊させないか / 順序整合性
+   - 📝 計画中 task: master roadmap 経路 B (batch planning) との重複
+   - ✅ 完了 task: 本対象が既に解決済の問題を再発明していないか
+
+2. **依存先 task.md + draft.md (task-management.md 開発開始時必読義務 準拠)**:
+   - 本対象 draft の「依存」section に列挙された task ID 全件
+   - draft §「関連 / 派生」section のリンク先
+   - 各 task の Task ゴール + 完了条件 + 影響範囲を確認
+
+3. **副産物 registry (`docs/tasks/next-actions.md`)**:
+   - 未処理 🔴 緊急 / 🟡 推奨 entry を全件 Read
+   - 本対象が解決 / 関連 / 影響する entry を特定し、findings で「entry #N を本対象で解決可」のように参照
+
+4. **既存規範 (`.claude/rules/*.md` Layer A 全 7 file)**:
+   - `development-process.md` (TDD / 委譲ガード / Bash 制御 / 並列化義務 等)
+   - `task-management.md` (採用 6 条 / parking-lot / 開発開始時必読義務)
+   - `workflow.md` (14/10-stage / W1-W4 / 20 MECE / fan-out registry / 本規約)
+   - `modes.md` (Normal/Loop / 9 遵守事項 / 自律実行禁止 11 カテゴリ)
+   - `self-improvement.md` (L1-L5 + F1/F2)
+   - `why-x5-output.md` (1 行 format)
+   - `git-workflow.md` (branch 命名規約)
+   - 本対象が上記規範と矛盾していないか / 規範更新が必要か判定
+
+5. **プロジェクト構造 / SSoT (`README.md` + `docs/INVENTORY.md`)**:
+   - architecture diagram / Layer A/B Strategy 等の最新版を確認
+   - 本対象が SSoT を破壊していないか / 拡張すべき INVENTORY entry はあるか
+
+6. **既存実装 patterns 探索 (Glob/Grep)**:
+   - `.claude/hooks/` 配下: 類似 hook が既存なら本対象との関係を findings に明記
+   - `.claude/commands/` 配下: 類似 command 再利用 / 拡張で対応可能なら再発明回避を推奨
+   - `.claude/skills/` 配下: 類似 skill 流用 / 拡張可能性
+   - 既存 utility (`.claude/scripts/` `.claude/hooks/lib/`) の流用機会
+
+## OK 例 (適切な findings 反映)
+
+- **「task-51 の Layer A/B 構造と本 draft の規範文書追加方針が整合 (Layer A 要約 + Layer B 詳細の 2 層構造で書く)」** — 既存規範整合性確認
+- **「next-actions.md entry #56 (Layer A/B template 整備) が本 draft で解決される、本 PR merge 時に entry #56 を `→ 解決` status に更新せよ」** — 副産物連動
+- **「既存 `.claude/hooks/task-rule-guard.sh` の Edit/Write block ロジックが本 draft の新 hook と重複、既存 hook 拡張で対応すべき」** — 既存実装再利用機会
+- **「task-21 W3 が UserPromptSubmit 注入数削減を進行中、本 draft の新 hook (`hook-X.sh`) は UserPromptSubmit に注入を追加するため、task-21 W3 の進捗と矛盾」** — 他 task 競合検出
+- **「README.md §2.6 Layer A/B Strategy table と本対象の path 規約が不整合、README 同期更新が必要」** — SSoT 整合性
+
+## NG 例 (不適切なレビュー、本規約違反)
+
+- **「本 draft 内の §3 採用案 architecture が clean (SOLID 準拠)」** — inside-out only、他 task 影響 / 既存実装再利用 等の観点が欠落
+- **「security 観点: 入力検証 OK」** — single draft レベルの security 観点のみで、`.claude/rules/development-process.md` の cross-repo write 例外 / staging 戦略との整合確認なし
+- **「実装提案: 新 file `.claude/hooks/new-hook.sh` を作成」** — 既存 `.claude/hooks/` 内に類似 hook 不在を Glob で確認せずに「新規作成」推奨
+- **「task ledger 確認: 関連なし」 (実際は list.md を Read していない)** — Read 不在のまま「関連なし」と結論
+
+## 既存規約との関係
+
+- **behavior-preserving 原則** ([`module-review.md`](../../commands/module-review.md) Phase 3): 本規約と直交、両方適用。本規約は**レビュー範囲の拡張** (project context)、behavior-preserving は**修正提案の制約** (public API / DB schema 変更禁止)。
+- **末尾 `confidence: 0.X`** (F3 confidence-gate): 本規約遵守度も confidence 算出に反映。項目 5 の Read 不在 / 不充分は confidence 0.6-0.7 程度に留まるべき (高すぎる confidence は不正確)。
+- **採用 6 条 4 テスト設計レビュー** ([`task-management.md`](../../rules/task-management.md) 採用 6 条 4): main agent が reviewer 5+ 動的選定して prompt を構築する際、本規約 項目 5 を必ず含める。
+
+## commands 連携
+
+| command | 規約反映先 |
+|---|---|
+| `/design-review` Phase 3 prompt template | 「対象 draft 全文 + 観点 + findings format + confidence + **項目 5: プロジェクト整合性 + 他 task 影響確認**」 |
+| `/test-design` Phase 3 agent prompt (tdd-guide / test-automator / qa-expert) | 「20 カテゴリ採用推奨 + **項目 5: プロジェクト整合性確認** (他 task のテスト戦略との重複検出 + 既存 test infrastructure 流用機会)」 |
+| `/module-review` Phase 3 | 「3 観点 + 項目 5: モジュール変更が他 task / 既存規範 / SSoT に与える影響」 |
+| `/system-review` Phase 3 | 「system-level 3 観点 + 項目 5 強化 (system 全体の cross-task 影響)」 |
+| 採用 6 条 4 (main ad-hoc dispatch) | main agent が reviewer 5+ subagent dispatch 時、各 prompt 末尾に「**項目 5: プロジェクト整合性確認**: list.md / 依存先 task / next-actions / 既存規範 / README+INVENTORY / 既存実装 Glob を必ず実施」明記 |
+
+## bypass の運用詳細
+
+`HC_REVIEW_PROJECT_CONTEXT_REQUIRED=false` の**正当な使用ケース** (honor system):
+
+- typo 1 行修正の `/module-review`
+- comment-only refactor の review
+- 既に直前の他 review (round-1) で project context 確認済の追加 round (round-2 以降、新規 finding 解消のみ目的)
+- hot fix bypass (緊急障害対応で review skip)
+
+`HC_REVIEW_PROJECT_CONTEXT_REQUIRED=false` の **NG ケース** (bypass 禁止):
+
+- 新規 feature の `/design-review` 初回 (round-1)
+- `.claude/rules/` 編集を含む change の review
+- 採用 6 条 4 のテスト設計レビュー初回 (round-1)
+- 規範変更 (`docs/draft/` 新規起案) の review
+- 設計 / architecture 大幅変更の review
+
+## Loop モード時の動作
+
+Loop モード稼働中 (modes.md 遵守事項 2 例外条項) でも、本規約は**戦術判断扱い** (実装中の方式選択と同等で、user 中間確認不要)。reviewer subagent は Loop モードでも自律で項目 5 の全 Read を実施する。
+
+`HC_REVIEW_PROJECT_CONTEXT_REQUIRED=false` 適用時のみ、reviewer が項目 5 を skip しても block しない (bypass.log に記録)。

package/.claude/rules-details/workflow/session-persistence.md

@@ -0,0 +1,46 @@
+> Layer A: [`workflow.md`](../../rules/workflow.md) §Session 永続化と PM Orchestration | 本 file は **明示 Read のみ** (context 自動注入 OFF)
+
+# Session 永続化詳細 (Layer B)
+
+自前 command 表 / memory key schema 全列挙 / Serena 必須化 / SessionStart 自動 resume の詳細。Layer A は要約のみ。
+
+## 自前 command
+
+| command | 役割 | 主要 Serena tool |
+|---|---|---|
+| [`/save-state`](../../commands/save-state.md) | session 状態を Serena memory に snapshot 保存 | `write_memory` |
+| [`/resume-state`](../../commands/resume-state.md) | 前 session 状態を Serena memory から復元 | `list_memories` / `read_memory` |
+| [`/pm-start`](../../commands/pm-start.md) | PM Agent orchestration + PDCA cycle 永続化 | 全 memory API |
+
+## memory key schema (全列挙)
+
+- `session/context` — 完全 snapshot (TaskList / commits / artifact / 次アクション)
+- `session/last` — 1-2 段落要約
+- `session/checkpoint` — 進捗 checkpoint
+- `plan/<feature>/{hypothesis,architecture,rationale}` (PDCA Plan)
+- `execution/<feature>/{do,errors,solutions}` (PDCA Do)
+- `evaluation/<feature>/{check,metrics,lessons}` (PDCA Check)
+- `learning/{patterns,solutions,mistakes}/<name>` (PDCA Act)
+- `project/{context,architecture,conventions}` (project 全体理解)
+
+## Serena 必須化の設計補足
+
+- 各 command の Phase 1 で `mcp__serena__activate_project` を必須実行し、戻り値 error に `onboarding` / `not performed` を含む場合は onboarding 未済と判定して graceful error で `/onboarding` 案内 + 終了
+- 旧版では `mcp__serena__check_onboarding_performed` を別 step で呼んでいたが、現 Serena MCP には該当 tool が存在しない (2026-05-23 確認、deferred tools list にも無し)
+- `activate_project` の error response で onboarding 未済を検知する形に統合 (`resume-state.md` / `save-state.md` / `pm-start.md` の Phase 1 同期修正済)
+- `.mcp.json` の `serena` entry は採用者側で個別登録 (Claude Code 標準には required marker 機構なし、command-level enforcement で代替)
+
+## 関連 artifact (完全 list)
+
+- [`.claude/commands/save-state.md`](../../commands/save-state.md)
+- [`.claude/commands/resume-state.md`](../../commands/resume-state.md)
+- [`.claude/commands/pm-start.md`](../../commands/pm-start.md)
+- [`.claude/hooks/mode-session-start.sh`](../../hooks/mode-session-start.sh) (W2 拡張済)
+- [`.claude/tests/custom-pm-commands-smoke.sh`](../../tests/custom-pm-commands-smoke.sh) (W5, 6/6 PASS)
+- 設計起源は採用プロジェクト側 `docs/draft/` を参照 (`.claude/` 単独で portable)
+
+## SessionStart 自動 resume の動作詳細
+
+- `.serena/memories/session/context.md` 存在検知 → `<system-reminder>` で `/resume-state` 提案
+- user 入力不要、メインが自動で `/resume-state` 実行 (Loop モード時) or user 承認待ち (Normal モード時)
+- 復元対象: TaskList / 直近 commits / 進行中 artifact / 次アクション / context_used_ratio

package/.claude/rules-details/workflow/workflow-guard.md

@@ -0,0 +1,36 @@
+> Layer A: [`workflow.md`](../../rules/workflow.md) §workflow-guard.sh による強制機構 | 本 file は **明示 Read のみ** (context 自動注入 OFF)
+
+# workflow-guard 強制機構 詳細 (Layer B)
+
+`workflow-guard.sh` の発火タイミング・判定 A/B 概要・bypass は Layer A 参照。本 file は判定ロジックの詳細手順と state JSON schema field 表。
+
+## 判定ロジック (構造化 JSON 解析、grep 依存禁止)
+
+1. `tool_name == "Bash"` で `command` に `/finish-task <slug>` パターン (`^[a-z0-9][a-z0-9-]{2,48}$`) 検出
+2. `.claude/.workflow-state/<slug>.json` 読み (不在なら旧 task 互換で silent pass)
+3. `workflow_type` から stage 列を解決
+4. **判定 A**: `current_stage` が stage 列の **最終要素** (new=`finish` / modify=`system-review`)
+5. **判定 B**: `pending_findings.module_review` と `pending_findings.system_review` が **両方とも空配列**
+6. A / B いずれか fail なら **exit 2 (BLOCK)** + stderr に「問題」「推奨アクション」「bypass 手順」出力
+
+stage 名で判定する設計 (round-2 arch-rev H3 反映、step 番号や順序判定ではない)。
+
+## state JSON schema
+
+`.claude/.workflow-state/<slug>.json` 構造定義は [`SCHEMA.md`](../../.workflow-state/SCHEMA.md) が SSoT。主要 field:
+
+| Field | 型 | 説明 |
+|---|---|---|
+| `slug` | string | 機能識別子。ファイル名と一致 |
+| `workflow_type` | `"new" \| "modify"` | どちらの workflow か |
+| `current_stage` | string | 現在進行中の stage 名 |
+| `completed_stages` | string[] | 完了済 stage の配列 (順序保持) |
+| `pending_findings` | object | `module_review` / `system_review` の未解決 findings 配列 |
+| `skip_log` | object[] | skip された stage の audit |
+| `created_at` / `updated_at` | ISO-8601 UTC | timestamp (秒精度、`Z` suffix) |
+
+state JSON 本体 (`<slug>.json`) は `.gitignore` で除外、`SCHEMA.md` / `bypass.log` / `bypass.log.template` のみ git track。
+
+## bypass.log 集計の補足
+
+`harness-audit.py` の `bypass_log_summary()` が `.claude/.workflow-state/bypass.log` を集計し `/harness-audit` で最近 N 日の bypass を表示する。両系統 (env `ECC_WORKFLOW_GUARD_OFF` / config `HC_WORKFLOW_GUARD_ENABLED`) 併存は env と config から独立に bypass 可能とし、片方が誤って enabled なまま放置される事故を防ぐ設計 (round-2 sec-rev H3 反映)。

package/.claude/scripts/agent-stocktake.py

@@ -0,0 +1,421 @@
+#!/usr/bin/env python3
+"""agent-stocktake.py — `.claude/agents/` 配下のエージェント棚卸しレポート生成。
+
+claude-code-harness の 144 agents（VoltAgent 由来 10 カテゴリ）について
+- frontmatter (name / description / model / tools)
+- 直近 N 日のサブエージェント起動回数（~/.claude/projects 走査）
+- 機能カテゴリ・粒度（micro / medium / macro）の自動分類
+- オーバーラップ候補（共通キーワード Jaccard）
+- 削除候補フラグ（起動 0 + オーバーラップ + 適合度）
+
+を集約して Markdown / JSON で出力する。読み取り専用・標準ライブラリのみ。
+
+Usage:
+    python3 .claude/scripts/agent-stocktake.py              # Markdown stdout
+    python3 .claude/scripts/agent-stocktake.py --json       # JSON stdout
+    python3 .claude/scripts/agent-stocktake.py --window=90  # 直近 N 日（default 90）
+    python3 .claude/scripts/agent-stocktake.py --target=44  # 削除候補数の目安
+    python3 .claude/scripts/agent-stocktake.py --out=path   # ファイル書き出し
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from collections import Counter, defaultdict
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+ROOT = Path.cwd()
+AGENTS_DIR = ROOT / ".claude" / "agents"
+HOMUNCULUS_ROOT = Path.home() / ".claude" / "homunculus"
+TRANSCRIPTS_ROOT = Path.home() / ".claude" / "projects"
+
+GRANULARITY_BY_MODEL = {
+    "haiku": "micro",
+    "sonnet": "medium",
+    "opus": "macro",
+}
+
+FUNCTION_KEYWORDS: dict[str, list[str]] = {
+    "design": ["design", "designer", "architect", "wireframe"],
+    "implement": ["developer", "specialist", "engineer", "implementation"],
+    "test": ["test", "qa", "tester", "automator"],
+    "review": ["review", "reviewer", "audit", "auditor"],
+    "security": ["security", "penetration", "compliance", "hardening", "vulnerab"],
+    "infra": ["infra", "devops", "kubernetes", "terraform", "docker", "cloud", "deployment", "sre", "platform", "network"],
+    "data": ["data", "ml", "ai", "machine-learning", "nlp", "llm", "prompt", "reinforcement"],
+    "ops": ["incident", "ops", "responder", "monitor", "performance"],
+    "orchestration": ["orchestrat", "coordinator", "distributor", "context-manager"],
+    "research": ["research", "researcher", "analyst", "trend", "competitive", "market", "scientific"],
+    "doc": ["documentation", "documenter", "readme", "writer", "technical-writer"],
+    "language": ["python", "typescript", "javascript", "golang", "rust", "java", "kotlin", "swift", "php", "csharp", "dotnet", "powershell", "elixir", "react", "vue", "angular", "nextjs", "node", "rails", "django", "fastapi", "spring", "laravel", "symfony", "flutter", "expo", "cpp", "sql"],
+    "business": ["product-manager", "business-analyst", "scrum", "customer", "sales", "legal", "license", "marketer", "wordpress"],
+    "domain": ["blockchain", "fintech", "healthcare", "iot", "embedded", "game", "payment", "quant", "risk", "seo", "m365", "azure", "windows"],
+    "tooling": ["dx", "build-engineer", "cli-developer", "tooling", "dependency", "git-workflow", "mcp", "modernizer", "refactor", "slack", "module-architect", "ui-architect"],
+}
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+SUBAGENT_RE = re.compile(r'"subagent_type"\s*:\s*"([^"]+)"')
+
+LOW_FIT_KEYWORDS = {
+    "blockchain-developer", "fintech-engineer", "embedded-systems", "iot-engineer",
+    "game-developer", "quant-analyst", "risk-manager",
+    "ad-security-reviewer", "powershell-security-hardening", "powershell-5.1-expert",
+    "powershell-7-expert", "powershell-module-architect", "powershell-ui-architect",
+    "windows-infra-admin", "azure-infra-engineer", "m365-admin",
+    "dotnet-framework-4.8-expert", "elixir-expert", "rails-expert", "symfony-specialist",
+    "spring-boot-engineer", "java-architect", "csharp-developer", "dotnet-core-expert",
+    "kotlin-specialist", "swift-expert", "expo-react-native-expert", "flutter-expert",
+    "cpp-pro", "rust-engineer", "angular-architect", "vue-expert", "django-developer",
+    "laravel-specialist", "fastapi-developer", "php-pro", "healthcare-admin",
+    "scientific-literature-researcher", "reinforcement-learning-engineer",
+    "chaos-engineer", "incident-responder", "devops-incident-responder",
+    "terragrunt-expert",
+}
+
+
+def parse_frontmatter(text: str) -> dict:
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    out: dict = {}
+    for raw in m.group(1).splitlines():
+        line = raw.rstrip()
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        key = key.strip()
+        value = value.strip()
+        if value.startswith('"') and value.endswith('"'):
+            value = value[1:-1]
+        out[key] = value
+    return out
+
+
+def collect_agents() -> list[dict]:
+    rows: list[dict] = []
+    if not AGENTS_DIR.exists():
+        return rows
+    for f in sorted(AGENTS_DIR.rglob("*.md")):
+        category = f.parent.name
+        name = f.stem
+        text = f.read_text(encoding="utf-8", errors="replace")
+        fm = parse_frontmatter(text)
+        rows.append({
+            "name": fm.get("name") or name,
+            "file_name": name,
+            "category": category,
+            "model": fm.get("model", "sonnet"),
+            "tools": fm.get("tools", ""),
+            "description": fm.get("description", ""),
+            "path": str(f.relative_to(ROOT)),
+            "desc_len": len(fm.get("description", "")),
+        })
+    return rows
+
+
+def count_invocations(window_days: int) -> tuple[Counter, dict]:
+    counter: Counter = Counter()
+    stats = {
+        "transcripts_scanned": 0,
+        "homunculus_lines_scanned": 0,
+        "subagent_total": 0,
+        "window_start_iso": "",
+    }
+    window_start = datetime.now(timezone.utc) - timedelta(days=window_days)
+    stats["window_start_iso"] = window_start.isoformat()
+
+    if TRANSCRIPTS_ROOT.exists():
+        for jsonl in TRANSCRIPTS_ROOT.glob("*/*.jsonl"):
+            try:
+                mtime = datetime.fromtimestamp(jsonl.stat().st_mtime, tz=timezone.utc)
+            except OSError:
+                continue
+            if mtime < window_start:
+                continue
+            stats["transcripts_scanned"] += 1
+            try:
+                with jsonl.open("r", encoding="utf-8", errors="replace") as fh:
+                    for line in fh:
+                        for match in SUBAGENT_RE.findall(line):
+                            counter[match] += 1
+                            stats["subagent_total"] += 1
+            except OSError:
+                continue
+
+    if HOMUNCULUS_ROOT.exists():
+        for jsonl in HOMUNCULUS_ROOT.glob("projects/*/observations.jsonl"):
+            try:
+                with jsonl.open("r", encoding="utf-8", errors="replace") as fh:
+                    for line in fh:
+                        stats["homunculus_lines_scanned"] += 1
+                        for match in SUBAGENT_RE.findall(line):
+                            counter[match] += 1
+                            stats["subagent_total"] += 1
+            except OSError:
+                continue
+
+    return counter, stats
+
+
+def infer_function_category(agent: dict) -> str:
+    name_lower = agent["name"].lower()
+    desc_lower = agent["description"].lower()
+    haystack = f"{name_lower} {desc_lower}"
+    scores: Counter = Counter()
+    for cat, keywords in FUNCTION_KEYWORDS.items():
+        for kw in keywords:
+            if kw in haystack:
+                scores[cat] += 1
+    if not scores:
+        return "other"
+    return scores.most_common(1)[0][0]
+
+
+def infer_granularity(agent: dict) -> str:
+    model = (agent.get("model") or "").lower()
+    base = GRANULARITY_BY_MODEL.get(model, "medium")
+    if base == "medium" and agent["desc_len"] < 80:
+        return "micro"
+    if base == "medium" and agent["desc_len"] > 240:
+        return "macro"
+    return base
+
+
+STOPWORDS = {
+    "use", "this", "agent", "when", "you", "need", "to", "the", "and", "for",
+    "with", "from", "across", "into", "that", "your", "their", "user", "users",
+    "comprehensive", "system", "systems", "code", "based", "case", "cases",
+    "expert", "specialist", "design", "implement", "tasks", "task",
+}
+
+
+def keywords_of(agent: dict) -> set[str]:
+    text = f"{agent['name']} {agent['description']}".lower()
+    tokens = re.findall(r"[a-z][a-z0-9\-]{2,}", text)
+    return {t for t in tokens if t not in STOPWORDS}
+
+
+def jaccard(a: set, b: set) -> float:
+    if not a or not b:
+        return 0.0
+    return len(a & b) / len(a | b)
+
+
+def find_overlaps(agents: list[dict], threshold: float = 0.32) -> list[tuple[str, str, float]]:
+    keys = [keywords_of(a) for a in agents]
+    pairs: list[tuple[str, str, float]] = []
+    n = len(agents)
+    for i in range(n):
+        for j in range(i + 1, n):
+            same_cat = agents[i]["category"] == agents[j]["category"]
+            n1 = agents[i]["name"].split("-")
+            n2 = agents[j]["name"].split("-")
+            name_overlap = (n1[0] == n2[0]) or (n1[-1] == n2[-1])
+            if not (same_cat or name_overlap):
+                continue
+            score = jaccard(keys[i], keys[j])
+            if score >= threshold:
+                pairs.append((agents[i]["name"], agents[j]["name"], round(score, 3)))
+    pairs.sort(key=lambda p: -p[2])
+    return pairs
+
+
+def mark_deletion_candidates(
+    agents: list[dict],
+    invocations: Counter,
+    overlaps: list[tuple[str, str, float]],
+    target: int,
+) -> list[dict]:
+    overlap_count: Counter = Counter()
+    for a, b, _ in overlaps:
+        overlap_count[a] += 1
+        overlap_count[b] += 1
+
+    scored: list[tuple[float, str, list[str]]] = []
+    for a in agents:
+        reasons: list[str] = []
+        score = 0.0
+        invk = invocations.get(a["name"], 0) + invocations.get(a["file_name"], 0)
+        a["invocations"] = invk
+        if invk == 0:
+            score += 1.0
+            reasons.append("zero-invocations")
+        if overlap_count[a["name"]] >= 2:
+            score += 1.0
+            reasons.append(f"overlap×{overlap_count[a['name']]}")
+        elif overlap_count[a["name"]] == 1:
+            score += 0.5
+            reasons.append("overlap×1")
+        if a["file_name"] in LOW_FIT_KEYWORDS:
+            score += 1.0
+            reasons.append("low-fit-domain")
+        if a["file_name"] in {"code-reviewer", "debugger"}:
+            score += 0.3
+            reasons.append("near-builtin")
+        scored.append((score, a["name"], reasons))
+
+    scored.sort(key=lambda x: (-x[0], x[1]))
+    delete_set: dict[str, list[str]] = {}
+    for score, name, reasons in scored:
+        if len(delete_set) >= target:
+            break
+        if score >= 1.0:
+            delete_set[name] = reasons
+
+    for a in agents:
+        a["delete_flag"] = a["name"] in delete_set
+        a["delete_reasons"] = delete_set.get(a["name"], [])
+        a["overlap_count"] = overlap_count[a["name"]]
+
+    return agents
+
+
+def render_markdown(
+    agents: list[dict],
+    invocations: Counter,
+    overlaps: list[tuple[str, str, float]],
+    stats: dict,
+    target: int,
+) -> str:
+    lines: list[str] = []
+
+    delete_candidates = [a for a in agents if a["delete_flag"]]
+    zero_invk = [a for a in agents if a["invocations"] == 0]
+    by_category: dict[str, list[dict]] = defaultdict(list)
+    for a in agents:
+        by_category[a["category"]].append(a)
+
+    lines.append("# Agent Stocktake — 2026-05-04")
+    lines.append("")
+    lines.append("> Auto-generated by `.claude/scripts/agent-stocktake.py`. 144 agents (VoltAgent/awesome-claude-code-subagents 由来) を対象に、")
+    lines.append("> 起動実績・粒度・オーバーラップ・適合度を集計し、144→100 を目標に削除候補 44 件を提案する。")
+    lines.append("")
+    lines.append("## 1. サマリ")
+    lines.append("")
+    lines.append(f"- **対象 agent 総数**: {len(agents)}")
+    lines.append(f"- **起動 0 件**: {len(zero_invk)} ({len(zero_invk)*100//max(len(agents),1)}%)")
+    lines.append(f"- **オーバーラップ疑いペア**: {len(overlaps)}")
+    lines.append(f"- **削除候補（target {target}）**: {len(delete_candidates)}")
+    lines.append("")
+    lines.append("### 集計データソース")
+    lines.append("")
+    lines.append(f"- transcripts (`~/.claude/projects/**/*.jsonl`) 走査: {stats['transcripts_scanned']} 件")
+    lines.append(f"- homunculus observations 走査: {stats['homunculus_lines_scanned']} 行")
+    lines.append(f"- 集計ウィンドウ開始: {stats['window_start_iso']}")
+    lines.append(f"- 検出サブエージェント呼び出し総数: {stats['subagent_total']}")
+    lines.append("")
+    if stats["subagent_total"] == 0:
+        lines.append("> **重要発見**: 直近ウィンドウ内で `Task(subagent_type=<name>)` 形式で起動された")
+        lines.append("> 144 agents の **記録は 0 件**。built-in `general-purpose` / `Explore` / `Plan` のみが使われている。")
+        lines.append("> → VoltAgent 由来 agents は事実上 dormant ライブラリ。30% 削減ではなく **大幅削減 + 用途明示** が現実的。")
+        lines.append("")
+
+    lines.append("## 2. カテゴリ別使用率")
+    lines.append("")
+    lines.append("| Category | 件数 | 起動 0 件 | 削除候補 | 主な機能カテゴリ |")
+    lines.append("|---|---:|---:|---:|---|")
+    for cat in sorted(by_category):
+        items = by_category[cat]
+        zero = sum(1 for a in items if a["invocations"] == 0)
+        delc = sum(1 for a in items if a["delete_flag"])
+        fcat = Counter(a.get("function_category", "other") for a in items).most_common(3)
+        fcat_str = ", ".join(f"{k}×{v}" for k, v in fcat)
+        lines.append(f"| `{cat}` | {len(items)} | {zero} | {delc} | {fcat_str} |")
+    lines.append("")
+
+    lines.append("## 3. 集計表（144 agents）")
+    lines.append("")
+    lines.append("| # | Category | Agent | Invk | Function | Granularity | Overlap | Delete |")
+    lines.append("|---:|---|---|---:|---|---|---:|:---:|")
+    for i, a in enumerate(sorted(agents, key=lambda x: (x["category"], x["name"])), 1):
+        flag = "X" if a["delete_flag"] else ""
+        lines.append(
+            f"| {i} | `{a['category']}` | `{a['name']}` | {a['invocations']} | "
+            f"{a.get('function_category','other')} | {a.get('granularity','medium')} | "
+            f"{a['overlap_count']} | {flag} |"
+        )
+    lines.append("")
+
+    lines.append("## 4. オーバーラップ疑いペア（Jaccard >= 0.32）")
+    lines.append("")
+    if not overlaps:
+        lines.append("（該当なし）")
+    else:
+        lines.append("| Agent A | Agent B | Jaccard |")
+        lines.append("|---|---|---:|")
+        for a, b, score in overlaps[:60]:
+            lines.append(f"| `{a}` | `{b}` | {score} |")
+        if len(overlaps) > 60:
+            lines.append("")
+            lines.append(f"... 他 {len(overlaps) - 60} 件は `--json` で取得")
+    lines.append("")
+
+    lines.append(f"## 5. 削除候補リスト（target 144→{144-target}、{target} 件）")
+    lines.append("")
+    lines.append("| # | Agent | Category | Invk | Reasons |")
+    lines.append("|---:|---|---|---:|---|")
+    for i, a in enumerate(sorted(delete_candidates, key=lambda x: (x["category"], x["name"])), 1):
+        reasons = " / ".join(a["delete_reasons"]) or "—"
+        lines.append(f"| {i} | `{a['name']}` | `{a['category']}` | {a['invocations']} | {reasons} |")
+    lines.append("")
+
+    lines.append("## 6. 推奨アクション")
+    lines.append("")
+    lines.append("1. **未使用 Language specialists の整理**: 当プロジェクトの主要技術に近い 5〜7 件のみ残し、それ以外は archive 候補。")
+    lines.append("2. **未使用領域の除外**: プロジェクトで使わないスタック（例: `powershell-*` `windows-*` `dotnet-*` `csharp-*` 等）は一括 archive 候補。")
+    lines.append("3. **オーバーラップ統合**: `code-reviewer` × `architect-reviewer` × `qa-expert`、`security-auditor` × `penetration-tester` × `compliance-auditor` などはルーター 1 本に集約。")
+    lines.append("4. **dormant 状態の根因対処**: subagent_type=`general-purpose` への流入を named agents に振り分ける Skill or Hook（`agent-router`）を別タスクで設計。")
+    lines.append("5. **承認後の実作業**: `git mv .claude/agents/<cat>/<agent>.md docs/archive/agents/<cat>/<agent>.md` で履歴を残しつつ無効化。")
+    lines.append("")
+
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Agent stocktake report")
+    parser.add_argument("--json", action="store_true", help="emit JSON instead of Markdown")
+    parser.add_argument("--window", type=int, default=90, help="invocation window in days")
+    parser.add_argument("--target", type=int, default=44, help="delete candidate target count")
+    parser.add_argument("--out", type=str, default="", help="write to file (default stdout)")
+    args = parser.parse_args(argv)
+
+    if not AGENTS_DIR.exists():
+        print(f"ERROR: agents dir not found: {AGENTS_DIR}", file=sys.stderr)
+        return 2
+
+    agents = collect_agents()
+    if not agents:
+        print("ERROR: no agents found", file=sys.stderr)
+        return 2
+
+    invocations, stats = count_invocations(args.window)
+    for a in agents:
+        a["function_category"] = infer_function_category(a)
+        a["granularity"] = infer_granularity(a)
+    overlaps = find_overlaps(agents)
+    agents = mark_deletion_candidates(agents, invocations, overlaps, args.target)
+
+    if args.json:
+        payload = {
+            "stats": stats,
+            "agents": agents,
+            "overlaps": [{"a": a, "b": b, "jaccard": s} for a, b, s in overlaps],
+            "delete_candidates": [a["name"] for a in agents if a["delete_flag"]],
+        }
+        out = json.dumps(payload, indent=2, ensure_ascii=False)
+    else:
+        out = render_markdown(agents, invocations, overlaps, stats, args.target)
+
+    if args.out:
+        Path(args.out).write_text(out, encoding="utf-8")
+    else:
+        sys.stdout.write(out)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))