@takuma-hirai/hirai-method 0.1.0

package/bin/cli.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+'use strict';
+
+// hirai-method npx CLI — entry point.
+// 外部依存ゼロ (Node 標準のみ)。install.sh をラップし、registry version 比較 (check) を行う。
+//
+// Subcommands:
+//   check            — npm registry の最新版とローカル版を比較 (fail-open)
+//   install <dir>    — install.sh <dir> を実行 (初回 install)
+//   update <dir>     — install.sh --update <dir> を実行 (増分更新)
+//   --version / -v   — ローカル version を出力
+//   --help / -h      — usage を出力
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+// ------------------------------------------------------------
+// 定数 / package root 解決
+// ------------------------------------------------------------
+const PACKAGE_ROOT = path.join(__dirname, '..');
+// install.sh path: env override 可 (test 用)。default は同梱 install.sh で本番挙動不変。
+const INSTALL_SH =
+  process.env.HIRAI_METHOD_INSTALL_SH || path.join(PACKAGE_ROOT, 'install.sh');
+const PKG_JSON_PATH = path.join(PACKAGE_ROOT, 'package.json');
+const REGISTRY_TIMEOUT_MS = 5000;
+const DEFAULT_PKG_NAME = '@takuma-hirai/hirai-method';
+// registry base: env override 可 (test 用)。default は npm registry で本番挙動不変。
+const REGISTRY_BASE =
+  process.env.HIRAI_METHOD_REGISTRY_BASE || 'https://registry.npmjs.org';
+// check の registry response body のサイズ上限 (DoS / 暴走防止、超過で fail-open)
+const MAX_BODY_BYTES = 1024 * 1024;
+
+// install.sh へ透過する flag (allowlist)
+const PASSTHROUGH_FLAGS = new Set([
+  '--force',
+  '--overwrite-all',
+  '--no-mcp',
+  '--no-docs',
+]);
+
+// ------------------------------------------------------------
+// package.json 読み出し (require cache により実 I/O は初回のみ)
+// ------------------------------------------------------------
+function readPkg() {
+  try {
+    return require(PKG_JSON_PATH);
+  } catch (err) {
+    return {};
+  }
+}
+
+function localVersion() {
+  const pkg = readPkg();
+  return typeof pkg.version === 'string' && pkg.version.length > 0
+    ? pkg.version
+    : null;
+}
+
+function packageName() {
+  const pkg = readPkg();
+  return typeof pkg.name === 'string' && pkg.name.length > 0
+    ? pkg.name
+    : DEFAULT_PKG_NAME;
+}
+
+// ------------------------------------------------------------
+// usage / help
+// ------------------------------------------------------------
+function usage() {
+  const name = packageName();
+  return [
+    `${name} — Claude Code harness (HIRAI method) distributor`,
+    '',
+    'Usage:',
+    `  npx ${name} check              registry 最新版とローカル版を比較`,
+    `  npx ${name} install <dir>      <dir> に harness を新規 install`,
+    `  npx ${name} update <dir>       <dir> の harness を増分更新 (install.sh --update)`,
+    `  npx ${name} --version          ローカル version を出力`,
+    `  npx ${name} --help             この usage を出力`,
+    '',
+    'Flags (install / update に透過):',
+    '  --force          既存 .claude / CLAUDE.md を backup せず上書き',
+    '  --overwrite-all  drift した target を SSoT へ強制リセット (settings.local.json のみ温存)',
+    '  --no-mcp         .mcp.json を配置しない',
+    '  --no-docs        docs templates 配置を skip',
+    '',
+    'Note: npx 配布は Unix 系 (bash + rsync) 前提です (Windows 非対応)。',
+  ].join('\n');
+}
+
+function printUsage(stream) {
+  (stream || process.stdout).write(usage() + '\n');
+}
+
+// ------------------------------------------------------------
+// semver 簡易比較 (依存追加禁止のため自前)
+// 戻り値: a > b → 1 / a < b → -1 / a == b → 0
+// prerelease / build metadata は無視 (major.minor.patch のみ)
+// ------------------------------------------------------------
+function parseSemver(v) {
+  if (typeof v !== 'string') return null;
+  const core = v.trim().replace(/^v/, '').split('+')[0].split('-')[0];
+  const parts = core.split('.');
+  // major.minor.patch を超える segment 数は不正 (例: "1.2.3.4")
+  if (parts.length < 1 || parts.length > 3) return null;
+  const nums = [];
+  for (let i = 0; i < 3; i++) {
+    const seg = parts[i];
+    // undefined (segment 不足) は 0 補完 ("1.2" → [1,2,0])
+    if (seg === undefined) {
+      nums.push(0);
+      continue;
+    }
+    // 非空かつ純数字でない segment は不正 (例: "2.x.0" の "x")
+    if (!/^\d+$/.test(seg)) return null;
+    nums.push(parseInt(seg, 10));
+  }
+  return nums;
+}
+
+function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return 1;
+    if (pa[i] < pb[i]) return -1;
+  }
+  return 0;
+}
+
+// ------------------------------------------------------------
+// 環境チェック: bash / rsync
+// ------------------------------------------------------------
+function hasCommand(cmd) {
+  // cmd を script 本体に埋め込まず positional 引数 ($1) で渡し shell 展開を回避
+  const r = spawnSync('bash', ['-c', 'command -v "$1"', '--', cmd], {
+    stdio: 'ignore',
+  });
+  return r.status === 0;
+}
+
+function ensureUnixToolchain() {
+  const missing = [];
+  // bash 自体が無いと spawnSync('bash', ...) も失敗するので個別判定
+  const bashCheck = spawnSync('bash', ['-c', 'exit 0'], { stdio: 'ignore' });
+  if (bashCheck.error || bashCheck.status !== 0) {
+    missing.push('bash');
+  }
+  if (missing.length === 0 && !hasCommand('rsync')) {
+    missing.push('rsync');
+  }
+  if (missing.length > 0) {
+    process.stderr.write(
+      `[hirai-method] error: 必須コマンドが見つかりません: ${missing.join(', ')}\n` +
+        '[hirai-method] npx 配布は Unix 系 (bash + rsync) 前提です。\n' +
+        '[hirai-method] macOS: brew install rsync / Debian: apt install rsync\n',
+    );
+    return false;
+  }
+  return true;
+}
+
+// ------------------------------------------------------------
+// check: registry 最新版を fetch して比較
+// ------------------------------------------------------------
+function fetchLatestVersion(pkgName) {
+  return new Promise((resolve) => {
+    // scoped name の "/" を %2F に encode
+    const encoded = pkgName.replace('/', '%2F');
+    const url = `${REGISTRY_BASE}/${encoded}/latest`;
+    // URL scheme で http / https module を選択 (test 用 http server 対応)
+    const httpLib = url.startsWith('http://') ? require('http') : require('https');
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    const req = httpLib.get(url, { timeout: REGISTRY_TIMEOUT_MS }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume(); // drain
+        finish({ ok: false, reason: `HTTP ${res.statusCode}` });
+        return;
+      }
+      let body = '';
+      let bytes = 0;
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        bytes += Buffer.byteLength(chunk, 'utf8');
+        if (bytes > MAX_BODY_BYTES) {
+          res.destroy();
+          finish({ ok: false, reason: `response body too large (> ${MAX_BODY_BYTES} bytes)` });
+          return;
+        }
+        body += chunk;
+      });
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(body);
+          if (typeof json.version === 'string') {
+            finish({ ok: true, version: json.version });
+          } else {
+            finish({ ok: false, reason: 'no .version in response' });
+          }
+        } catch (e) {
+          finish({ ok: false, reason: `parse error: ${e.message}` });
+        }
+      });
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      finish({ ok: false, reason: `timeout (${REGISTRY_TIMEOUT_MS}ms)` });
+    });
+    req.on('error', (e) => {
+      finish({ ok: false, reason: e.message });
+    });
+  });
+}
+
+async function cmdCheck() {
+  const name = packageName();
+  const local = localVersion();
+  const result = await fetchLatestVersion(name);
+
+  // network fail / timeout / non-200 → fail-open (WARN stderr, exit 0)
+  if (!result.ok) {
+    process.stderr.write(
+      `[hirai-method] WARN: registry 最新版を取得できませんでした (${result.reason})。\n` +
+        '[hirai-method] WARN: network 失敗のため check を skip します (fail-open)。\n',
+    );
+    return 0;
+  }
+
+  const latest = result.version;
+  if (local === null) {
+    process.stdout.write(
+      `[hirai-method] registry 最新版: ${latest} (ローカル version 不明、package.json 未設定)\n` +
+        `[hirai-method] 最新を取り込むには: npx ${name}@latest update <dir>\n`,
+    );
+    return 0;
+  }
+
+  const cmp = compareSemver(latest, local);
+  if (cmp === null) {
+    process.stderr.write(
+      `[hirai-method] WARN: version 比較不能 (local=${local} / latest=${latest})。fail-open。\n`,
+    );
+    return 0;
+  }
+
+  if (cmp > 0) {
+    process.stdout.write(
+      `[hirai-method] 新版 ${latest} あり (現 ${local})。\n` +
+        `[hirai-method] 更新: npx ${name}@latest update <dir>\n`,
+    );
+  } else {
+    process.stdout.write(`[hirai-method] up to date (${local})\n`);
+  }
+  return 0;
+}
+
+// ------------------------------------------------------------
+// install / update: install.sh をラップ
+// ------------------------------------------------------------
+function runInstall(mode, args) {
+  // args = サブコマンド以降 (dir + flags)
+  const positional = [];
+  const flags = [];
+  let endOfOptions = false; // POSIX "--" 以降は全て positional 扱い
+  for (const a of args) {
+    if (endOfOptions) {
+      positional.push(a);
+      continue;
+    }
+    if (a === '--') {
+      endOfOptions = true;
+      continue;
+    }
+    if (a.startsWith('-')) {
+      if (PASSTHROUGH_FLAGS.has(a)) {
+        flags.push(a);
+      } else {
+        process.stderr.write(`[hirai-method] error: 不明な flag: ${a}\n`);
+        return 1;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+
+  if (positional.length === 0) {
+    process.stderr.write(
+      `[hirai-method] error: ${mode} には対象 dir の指定が必須です。\n` +
+        `[hirai-method] 例: npx ${packageName()} ${mode} ./my-project\n`,
+    );
+    return 1;
+  }
+  if (positional.length > 1) {
+    process.stderr.write(
+      `[hirai-method] error: dir は 1 つだけ指定してください: ${positional.join(' ')}\n`,
+    );
+    return 1;
+  }
+
+  if (!ensureUnixToolchain()) {
+    return 1;
+  }
+
+  if (!fs.existsSync(INSTALL_SH)) {
+    process.stderr.write(
+      `[hirai-method] error: install.sh が見つかりません (${INSTALL_SH})。package 同梱不備の可能性があります。\n`,
+    );
+    return 1;
+  }
+
+  const dir = positional[0];
+  // mode=install → install.sh <dir> [flags] / mode=update → install.sh --update <dir> [flags]
+  const shArgs =
+    mode === 'update'
+      ? [INSTALL_SH, '--update', dir, ...flags]
+      : [INSTALL_SH, dir, ...flags];
+
+  const r = spawnSync('bash', shArgs, { stdio: 'inherit' });
+  if (r.error) {
+    process.stderr.write(
+      `[hirai-method] error: install.sh の起動に失敗しました: ${r.error.message}\n`,
+    );
+    return 1;
+  }
+  // exit code を透過 (null = signal 終了は 1 扱い)
+  return typeof r.status === 'number' ? r.status : 1;
+}
+
+// ------------------------------------------------------------
+// main
+// ------------------------------------------------------------
+async function main() {
+  const argv = process.argv.slice(2);
+  const first = argv[0];
+
+  // version / help は最優先
+  if (first === '--version' || first === '-v') {
+    const local = localVersion();
+    if (local === null) {
+      process.stderr.write(
+        '[hirai-method] error: version が package.json に設定されていません。\n',
+      );
+      return 1;
+    }
+    process.stdout.write(local + '\n');
+    return 0;
+  }
+
+  if (first === '--help' || first === '-h') {
+    printUsage(process.stdout);
+    return 0;
+  }
+
+  if (first === undefined) {
+    // 引数なし → usage + exit 1 ではなく exit 0 (help 相当, 引数なしは案内表示)
+    printUsage(process.stdout);
+    return 0;
+  }
+
+  switch (first) {
+    case 'check':
+      return cmdCheck();
+    case 'install':
+      return runInstall('install', argv.slice(1));
+    case 'update':
+      return runInstall('update', argv.slice(1));
+    default:
+      process.stderr.write(`[hirai-method] error: 不明なサブコマンド: ${first}\n\n`);
+      printUsage(process.stderr);
+      return 1;
+  }
+}
+
+// CLI 実行は require.main ガード内のみ。require 時 (test) は実行されず export のみ提供。
+if (require.main === module) {
+  main()
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((err) => {
+      process.stderr.write(`[hirai-method] fatal: ${err && err.stack ? err.stack : err}\n`);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { parseSemver, compareSemver };

package/docs/INVENTORY.md

@@ -0,0 +1,163 @@
+# Inventory — Claude Code ハーネス構成要素
+
+`./claude-code-harness` に含まれるすべての設定ファイル・hook・skill・command の役割表。
+
+## 設定 / 委譲ガード / 通知
+
+| Path | 役割 | ステータス |
+|---|---|---|
+| `CLAUDE.md` | プロジェクトルート用テンプレート。Overview / Autonomous Progression / Rules table / Tech Stack / Critical Operational Lessons の骨格。`<...>` プレースホルダを置換して使う。 | テンプレート |
+| `.claude/settings.json` | Hook 配線 + 共通 deny ルール + 最小 ask リスト。サニタイズ済み: `permissions.ask` から `supabase db push` / `supabase functions deploy` / `vercel env add/rm` を除去。 | サニタイズ済 |
+| `.claude/harness-config.yml` | **Portability SSoT**。`protected_paths` / `task_dir` / `draft_dir` / `bash_whitelist_path` / state dir / `homunculus_root` / 通知音源を集中管理。3 つの guard hook + audit script が `config-loader.sh` 経由で参照。別リポ移植時はここ 1 枚を編集すれば挙動が連動変化する。 | New (2026-05-04) |
+| `.claude/hooks/lib/config-loader.sh` | 純 bash の YAML サブセットパーサ（`yq` 等の外部依存ゼロ）。`harness-config.yml` を読んで `HC_*` 変数として export。tilde 展開対応、fail-open（不在時はハードコード fallback）。 | New (2026-05-04) |
+| `.claude/hooks/delegation-guard.sh` | メインエージェントの保護パス（既定 `src/`/`tests/`/`scripts/`、`harness-config.yml` で上書き可）への直接アクセスを block。bash whitelist を強制。inline 環境変数による Hook バイパスも検出。Edit/Write/Read/Grep/Glob/Bash を 1 スクリプトで集約。 | config 化済 |
+| `.claude/hooks/agent-marker-set.sh` | PreToolUse(Agent\|Task): `.claude/.agent-markers/*.lock` を書き出し、サブエージェント実行中であることを delegation-guard に伝える。 | そのまま |
+| `.claude/hooks/agent-marker-clear.sh` | PostToolUse(Agent\|Task): 当該 session の marker を削除 + 期限切れ marker（>60 分）を sweep。 | そのまま |
+| `.claude/hooks/notify.sh` | Claude が入力を求めた時の macOS 通知 + 音。 | そのまま |
+| `.claude/hooks/stop.sh` | Claude のターン終了時の macOS 通知 + 音。 | そのまま |
+| `.claude/hooks/check-md-mermaid.sh` | PostToolUse(Edit\|Write) on `.md`/`.mdx`: ` ```mermaid ` ブロックを抽出し mermaid@11 パーサーで検証。 | そのまま |
+| `.claude/scripts/check-md-mermaid.mjs` | hook が呼び出す Node スクリプト。mermaid@11 が parse 中に DOMPurify を呼ぶため jsdom shim を仕込む。 | そのまま |
+| `.claude/skills/check-md-mermaid/SKILL.md` | Mermaid 検証スクリプトの手動実行用スキルドキュメント。 | そのまま |
+| `.claude/bash-whitelist.txt` | メインエージェントが実行可能な Bash コマンドの SSoT。1 行 1 正規表現、`^` で先頭固定。**セクションマーカー**で path-aware / path-restricted を区分（W1.2 以降）。 | そのまま |
+| `.claude/bash-whitelist-requests/REQUEST_TEMPLATE.md` | 新規 whitelist エントリ申請用テンプレート（`.claude/bash-whitelist-requests/YYYY-MM-DD-<slug>.md` 形式で配置）。 | そのまま |
+| `.claude/rules/development-process.md` | TDD / サブエージェント委譲 / タスク管理 / 設計→承認→タスク追加フロー。`src/` `tests/` `scripts/` と `docs/tasks/` `docs/draft/` に依存。 | そのまま — パス要適応 |
+
+## 既存スラッシュコマンド
+
+| Path | 役割 | ステータス |
+|---|---|---|
+| `.claude/commands/commit.md` | `/commit`: `git diff` から Conventional Commits 自動生成。scope 自動判定（`src/lib/` → lib、`supabase/migrations/` → db 等）に依存。 | そのまま — scope 要適応 |
+| `.claude/commands/reviewpr.md` | `/reviewpr <pr>`: rules + CI + Critical Operational Lessons との多軸 PR レビュー。 | そのまま — rule リスト要適応 |
+| `.claude/commands/start-task.md` | `/start-task <id>`: `docs/tasks/list.md` + `task-N-*.md` を開く、branch 切替、ステータス in_progress 化。 | そのまま — タスク layout 要適応 |
+| `.claude/commands/finish-task.md` | `/finish-task <id>`: build/test/docs を検証し、done に更新、commit 提案。 | そのまま — タスク layout 要適応 |
+
+## 自己改善 5 層（ECC 由来）
+
+| Path | 役割 | ステータス |
+|---|---|---|
+| `.claude/rules/self-improvement.md` | ECC 5 層自己改善アルゴリズム（L1〜L5）の使い分け規約。タスク受領時・失敗時・完了時の分岐を定義。 | New (2026-05-04) |
+| `.claude/skills/continuous-learning-v2/SKILL.md` | **L4（核心）**: Hook ベース自動学習。Atomic instinct + 信頼度 0.3-0.9 + project-scoped。 | ECC v2.1.0 から複製 |
+| `.claude/skills/continuous-learning-v2/hooks/observe.sh` | PreToolUse/PostToolUse hook。100% 確実観察、git remote 検出、project-scoped 振り分け。 | New (2026-05-04) |
+| `.claude/skills/continuous-learning-v2/instinct-cli.py` | 標準ライブラリのみで動く instinct 管理 CLI。status / projects / evolve / promote / export / import / observe-analyze。 | New (2026-05-04) |
+| `.claude/skills/continuous-learning-v2/config.json` | Observer 設定（Haiku モデル・閾値・confidence 力学パラメータ）。 | New (2026-05-04) |
+| `.claude/skills/eval-harness/SKILL.md` | **L1**: pass@k / pass^k メトリクスと code/rule/model/human grader。 | ECC から複製 |
+| `.claude/skills/continuous-agent-loop/SKILL.md` | **L2**: 6 ループパターン（Sequential / NanoClaw / Infinite / Continuous PR / De-Sloppify / Ralphinho）。 | ECC から複製 |
+| `.claude/skills/gan-style-harness/SKILL.md` | **L2+**: Planner / Generator / Evaluator 3 エージェントが 4 基準スコアで収束。 | ECC から複製 |
+| `.claude/skills/agent-introspection-debugging/SKILL.md` | **L5**: 失敗時の 4 フェーズ自己診断（Capture / Diagnose / Recover / Report）。 | ECC から複製 |
+| `.claude/commands/instinct-status.md` `/projects.md` `/evolve.md` `/promote.md` `/instinct-export.md` `/instinct-import.md` `/learn.md` | L4 操作系スラッシュコマンド 7 本。 | New (2026-05-04) |
+| `.claude/commands/eval.md` | L1 操作（define / check / report）。 | New (2026-05-04) |
+| `.claude/commands/gan-design.md` `/gan-build.md` | L2+ Planner / Generator-Evaluator 起動。 | New (2026-05-04) |
+| `.claude/commands/agent-introspect.md` | L5 起動。 | New (2026-05-04) |
+
+## 事実検証レイヤー（F1 / F2）
+
+| Path | 役割 | ステータス |
+|---|---|---|
+| `.claude/skills/gateguard/SKILL.md` | **F1 事前ゲート**: 初回 Edit/Write/破壊的 Bash で 4 種の事実を強制要求。+2.25/10 ポイントの品質改善（A/B 実測）。 | ECC から複製 |
+| `.claude/skills/gateguard/.gateguard.yml` | GateGuard 設定（gate 対象・除外パス・破壊的コマンドパターン）。 | New (2026-05-04) |
+| `.claude/hooks/gateguard.sh` | PreToolUse hook（Edit/Write/Bash matcher で発火）。state file で 2 回目以降を通過させる。 | New (2026-05-04) |
+| `.claude/skills/verification-loop/SKILL.md` | **F2 事後検証**: build / type / lint / test / security / diff の 6 phase 検証。 | ECC から複製 |
+| `.claude/commands/verify.md` `/gate-status.md` `/gate-clear.md` `/gate-bypass.md` | F1/F2 操作系スラッシュコマンド 4 本。 | New (2026-05-04) |
+| `.claude/.gitignore` | `.gateguard-state/` `.agent-markers/` を git から除外。 | New (2026-05-04) |
+
+## タスク管理
+
+| Path | 役割 | ステータス |
+|---|---|---|
+| `.claude/hooks/init-tasks-on-start.sh` | SessionStart hook。`docs/tasks/list.md` 等が未存在ならテンプレから生成。 | そのまま |
+| `.claude/hooks/task-rule-guard.sh` | PreToolUse(Edit\|Write)。`docs/tasks/` への新規 Write を draft 不在 / ID 重複で BLOCK。 | そのまま |
+| `.claude/templates/docs/tasks/list.md` | タスク台帳ひな型（凡例・依存関係図・更新ルール込み）。 | そのまま |
+| `.claude/templates/docs/tasks/parking-lot.md` | 保留タスクひな型（必須 7 項目フォーマット込み）。 | そのまま |
+| `.claude/templates/docs/tasks/_TASK_TEMPLATE.md` | 個別タスクひな型。 | そのまま |
+| `.claude/templates/docs/draft/_DRAFT_TEMPLATE.md` | 設計 draft ひな型。 | そのまま |
+| `.claude/commands/init-tasks.md` `/new-draft.md` `/new-task.md` `/start-task.md` `/finish-task.md` `/task-bypass.md` | タスク管理スラッシュコマンド 6 本。 | そのまま |
+
+## 自己診断 / 観測（W2 で追加）
+
+| Path | 役割 | ステータス |
+|---|---|---|
+| `.claude/hooks/failure-loop-detect.sh` | PostToolUse(`*`)。同種エラー 3 連続を検出して `/agent-introspect` を `additionalContext` で提案。 | New (W2.1) |
+| `.claude/scripts/harness-audit.py` | ハーネス健全性レポートを実測値で出力（observations.jsonl / GateGuard / TaskGuard / failure-window）。 | New (W2.2) |
+| `.claude/commands/harness-audit.md` | `/harness-audit`: 上記スクリプトを起動して結果を整形。 | New (W2.2) |
+
+## 規範文書の Layer A/B Strategy (2026-05-28、task-51)
+
+`.claude/rules/*.md` (規範文書) は **Layer A (要約、context 自動注入) + Layer B (詳細、明示 Read のみ)** の 2 層構造で運用する。
+
+| Path | 役割 | 物理配置 | context 注入 |
+|---|---|---|---|
+| `.claude/rules/<rule>.md` | **Layer A** — 要約版 (採用 N 条 / 遵守事項 / table / bypass env 1-2 行 / Layer B link / 起源 1 行) | `.claude/rules/` (Claude Code 再帰 discover 対象) | claudeMd 経由で常時注入 |
+| `.claude/rules-details/<rule>/<topic>.md` | **Layer B 断片** — topic 別詳細 (OK/NG 例 / history / SUPERSEDED / bypass 詳細 / 起源 / 5 層強制機構詳細 / 関連 artifact 完全 list) | `.claude/rules-details/<rule>/` (別 dir + subdir、Claude Code discover 対象外) | **非注入** (Read tool で明示参照のみ) |
+
+> **設計経緯 (2026-05-28 A 案 redesign)**: 当初は `.claude/rules/<rule>.details.md` + frontmatter `paths: []` で非注入を狙ったが、Claude Code 公式仕様 (code.claude.com/docs/en/memory.md) で「`.claude/rules/*.md` は再帰 discover + startup load」「`paths:` は path match 時の**追加適用** (除外機構ではない)」が確定 (claude-code-guide subagent + 公式 doc、confidence 0.95)。token 実測でも `paths: []` 配置で context は逆に増加 (153K vs before ~146K) したため、Layer B を別 dir へ物理移動して除外を実現。
+
+**現状の 2 層分割対象** (task-51 Step 3+5b で 2 層化、task-67 で Layer B を topic 別断片化、6 rule):
+
+| Layer A (`.claude/rules/`) | Layer B 断片 (`.claude/rules-details/<rule>/`) | Layer A 抜粋 keyword |
+|---|---|---|
+| `self-improvement.md` | `self-improvement/` (4 断片) | L1-L5 + F1/F2 規約 / 5 + 3 層 |
+| `development-process.md` | `development-process/` (8 断片) | TDD / 委譲ガード 7 必須要件 / staging 戦略 / cross-repo write 例外 / Confidence Gate (F3) |
+| `task-management.md` | `task-management/` (8 断片) | 採用 6 条 / メイン専任 / 開発開始時必読義務 / parking-lot |
+| `workflow.md` | `workflow/` (12 断片) | 14-stage / 10-stage / W1-W4 / 20 MECE / fan-out reviewer-registry |
+| `modes.md` | `modes/` (5 断片) | Normal/Loop / 9 遵守事項 / 自律実行禁止 11 カテゴリ / 5 層強制機構 |
+| `why-x5-output.md` | `why-x5-output/` (4 断片) | v10 1 行 format (`<何のため> のため、<何をやる> を行う`) |
+
+`git-workflow.md` は ~1K で退避不要 (Layer A のみ)。
+
+**Layer B Read trigger 4 条件** (Layer A 冒頭に admonition 配置):
+1. 違反検出時 (hook BLOCK / warn 注入受領 / regex 不一致)
+2. 規範変更時 (rule 編集 / draft 起案 / 採用 N 条改定)
+3. 新規事案 (初遭遇 keyword / 例外パターン疑い)
+4. 学習 / dogfood (task 着手前依存先必読 / harness audit / 副産物整理)
+
+通常運用は Layer A のみで判断、Layer B Read skip (token 節約)。
+
+**規約** (task-67 断片版): Layer A → Layer B 断片 link は断片ファイル直リンク (`[<rule>/<topic>.md](../rules-details/<rule>/<topic>.md)`、anchor 方式廃止)。Layer B 断片 → A back-link は `../../rules/<rule>.md` (2 階層上り)。dangling 0 は `.claude/tests/rule-architecture-smoke.sh` で機械検証。
+
+**機械強制**:
+- `install.sh` `rsync -a .claude/` で `.claude/rules-details/` 配下も自動同期 (RSYNC_EXCLUDES 不在、4 リポへ配布)
+- `.claude/tests/layer-b-context-isolation-smoke.sh` (8 cases) + `.claude/tests/rule-architecture-smoke.sh` (3 asserts: dangling 0 / auto-load isolation / back-link 健全性) で Layer B 物理 dir / link 存在 / install.sh sync pattern 等を検証
+
+**起源**: task-51 (context-bloat-reduction、2026-05-28)、設計 draft `docs/draft/context-bloat-reduction.md` §3 (Q2) + A 案 redesign (2026-05-28、smoke 実測で `paths: []` 無効判明 → Layer B 物理移動)。
+
+## 外部インポート（コミュニティ由来）
+
+### Agents（[VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) MIT）
+
+`.claude/agents/<category>/<name>.md` 形式で **144 agents / 10 categories** を配置。
+
+| Category | 件数 | 主な内容 |
+|---|---:|---|
+| `01-core-development` | 11 | api-designer / backend-developer / frontend-developer / mobile-developer など |
+| `02-language-specialists` | 30 | python / typescript / golang / rust / java / kotlin / swift など各言語 pro |
+| `03-infrastructure` | 16 | devops / kubernetes / terraform / cloud-architect など |
+| `04-quality-security` | 16 | code-reviewer / security-auditor / penetration-tester / qa-expert など |
+| `05-data-ai` | 13 | data-scientist / ml-engineer / nlp-engineer / mlops-engineer など |
+| `06-developer-experience` | 14 | tooling-engineer / build-engineer / dx-optimizer / cli-developer など |
+| `07-specialized-domains` | 13 | blockchain / iot / game-developer / embedded-systems など |
+| `08-business-product` | 12 | product-manager / scrum-master / business-analyst など |
+| `09-meta-orchestration` | 11 | multi-agent-coordinator / task-distributor / workflow-orchestrator など |
+| `10-research-analysis` | 8 | research-analyst / market-researcher / trend-analyst など |
+
+### Skills（[ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills)）
+
+`.claude/skills/<name>/` に **32 skills** を配置（既存 9 と衝突なし）。
+
+主要グループ:
+- **コンテンツ生成**: `artifacts-builder` `brand-guidelines` `canvas-design` `theme-factory` `tailored-resume-generator`
+- **ドキュメント変換**: `document-docx` `document-pdf` `document-pptx` `document-xlsx`
+- **ビジネス自動化**: `changelog-generator` `internal-comms` `invoice-organizer` `meeting-insights-analyzer`
+- **リサーチ**: `content-research-writer` `developer-growth-analysis` `lead-research-assistant` `competitive-ads-extractor`
+- **ユーティリティ**: `file-organizer` `image-enhancer` `video-downloader` `webapp-testing` `domain-name-brainstormer` `raffle-winner-picker`
+- **メタ**: `skill-creator` `skill-share` `template-skill` `mcp-builder`
+- **連携**: `connect` `connect-apps` `langsmith-fetch` `slack-gif-creator` `twitter-algorithm-optimizer`
+
+### 除外したもの
+
+- `composio-skills/` — 832 個の Composio platform 連携サブスキル（platform 依存が強すぎ）
+- `connect-apps-plugin/` — plugin 形式（commands のみで SKILL.md なし）
+
+### ライセンス
+
+- VoltAgent: **MIT License** — 各 agent ファイル末尾の attribution は temp ファイル参照ではないため改変不要
+- ComposioHQ: 個別 skill により異なる（`SKILL.md` frontmatter の `license:` フィールドおよび `LICENSE.txt` を確認）