Org Setup

---
name: org-setup
description: |
  組織の全ロール（窓口・ディスパッチャー・キュレーター・ワーカー）に必要な
  Claude Code の許可設定・環境変数を一括で配置・更新するスキル。
  「設定して」「許可設定を更新して」「セットアップして」
  「permissions設定」「org-setup」等で発動する。
effort: low
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash(python tools/org_setup_prune.py:*)
  - Bash(py -3 tools/org_setup_prune.py:*)
  - Bash(python tools/check_role_configs.py:*)
  - Bash(py -3 tools/check_role_configs.py:*)
  - Bash(py -3 tools/ensure_projects_registry.py:*)
  - Bash(python3 tools/ensure_projects_registry.py:*)
---

# org-setup: 組織の許可設定を一括配置

組織の各ロールが必要とする permissions allow と環境変数を、
正しいスコープの settings ファイルに配置する。

> **輸送層 両系（`ORG_TRANSPORT`: 既定 `renga` / opt-in `broker`）**: 本スキルが配る messaging MCP の allow は **既定 `renga`**（`ORG_TRANSPORT` 無設定）で `mcp__renga-peers__*` tier。**`references/permissions.md` は renga アンカー（byte 比較対象）として不変**であり、broker への置換は prose ではなく生成/検証ツール側で行う: `tools/org_setup_prune.py`（per-role allow / `--user-common-allowlist`）と `tools/check_role_configs.py` が `ORG_TRANSPORT=broker` のとき `mcp__renga-peers__*` ブロックを broker messaging tier（`mcp__org-broker__*`）に射影する（runtime の `transport_allowlist` descriptor 駆動、Epic #6 E）。**既定 renga は恒等**（生成物 byte 等価・file no-op）なので本スキルの手順・報告文はそのまま使えばよい。設計 SoT は transport-lab `docs/design/ja-migration-plan.md` §5.3、契約面は [`docs/contracts/backend-interface-contract.md`](../../../docs/contracts/backend-interface-contract.md) Surface 8（ratified 2026-06-14）。

## 設定ファイルの配置先とスコープ

Claude Code は**起動ディレクトリの `.claude/` 配下**から設定を読み込む。
サブディレクトリで起動した場合、親ディレクトリの設定は**読み込まれない**。
そのため、ロールごとに独立した設定ファイルが必要になる。

| スコープ | ファイルパス | 対象 |
|---|---|---|
| ユーザー共通 | `~/.claude/settings.json` | 全プロジェクト・全ロール |
| 窓口 | `<repo>/.claude/settings.local.json` | リポジトリルートで起動した窓口 |
| ディスパッチャー | `<repo>/.dispatcher/.claude/settings.local.json` | `.dispatcher/` で起動したディスパッチャー |
| キュレーター | `<repo>/.curator/.claude/settings.local.json` | `.curator/` で起動したキュレーター |
| ワーカー | ワーカーディレクトリの `.claude/settings.local.json` | org-delegate が動的に作成 |

## 各ロールの必要設定

**references/permissions.md** に全ロールのJSON定義がある。以下の手順でこれを参照する。

## 実行手順

### Step 1: 現在の設定を読み取る

以下の4ファイルを読み取る（存在しない場合は空オブジェクト扱い）:

1. `~/.claude/settings.json`
2. `<repo>/.claude/settings.local.json`
3. `<repo>/.dispatcher/.claude/settings.local.json`
4. `<repo>/.curator/.claude/settings.local.json`

### Step 2: 差分を特定する

各ファイルについて、上記「各ロールの必要設定」と比較し、不足しているエントリを特定する。

### Step 3: マージして書き込む

不足分を追加する。既存の設定は**絶対に削除しない**。
`permissions.allow` は配列なので、既存エントリを保持しつつ新規エントリを追加する。
`env` はオブジェクトなので、既存キーを保持しつつ新規キーを追加する。
`sandbox.network.allowedDomains`（窓口・ディスパッチャー。`/work-discovery` 判定段の `api.anthropic.com`）も配列として既存を保持して追加する。`sandbox` の他のキー（`enabled` / `filesystem`）はテンプレートに無いので足さない（理由は [`.claude/skills/org-setup/references/permissions.md`](references/permissions.md) 窓口節の `sandbox.network.allowedDomains` の注記）。

### Step 3.5: operator-local な生成ファイルを配置する（未配置時のみ）

許可設定と同じく、fresh clone 直後に無い operator-local ファイルをここで揃える。
いずれも**既存があれば上書きしない**（operator の実データが入っているため）。

`registry/projects.md`（プロジェクトレジストリ、Issue #811）— コミットされているのは
テンプレート `registry/projects.example.md` の方で、実体は git 管理外:

```bash
python3 tools/ensure_projects_registry.py     # Mac/Linux
py -3 tools/ensure_projects_registry.py       # Windows native
```

- 冪等。`created:` なら新規生成、`ok:` なら既存のまま
- `header drift:` はテンプレートに増えた列が手元ファイルに無い warning（exit 0、非 fatal）。
  表示された列名をユーザーに伝え、手元ファイルの表ヘッダーへの追記を案内する
- [`/org-start`](../org-start/SKILL.md) の Step 0 でも同じコマンドが走るので、
  どちらを先に実行しても実体は揃う。既存 checkout の移行手順は
  [`docs/operations/registry-projects-migration.md`](../../../docs/operations/registry-projects-migration.md)

### Step 4: 結果を報告する

変更があった場合:
```
設定を更新しました:
- ~/.claude/settings.json: renga, renga-peers の許可を追加
- .dispatcher/.claude/settings.local.json: claude 起動コマンドの許可を追加
- (変更なし: .curator/.claude/settings.local.json)
```

変更がなかった場合:
```
全ての設定は最新です。変更はありません。
```

### Step 5: drift を解消する（`--prune` モード）

通常の Step 1〜3 は **additive-only**（不足分を追加するだけで既存は削除しない）。
過去に蓄積した広すぎる allow や旧エントリは残り続けるため、
`permissions.md` を SOT として `settings.local.json` を**完全に書き換える** prune モードを用意している。

実行は `tools/org_setup_prune.py` を使う:

```bash
# 差分プレビュー（書き換え無し）
python tools/org_setup_prune.py --role secretary --dry-run
python tools/org_setup_prune.py --all --dry-run

# 実行（タイムスタンプ付き .bak を自動生成 → 書き換え）
python tools/org_setup_prune.py --role secretary
python tools/org_setup_prune.py --all
```

対象ロール: `secretary` / `dispatcher` / `curator`。
（`user_common` は `~/.claude/settings.json` で他プラグインと同居するため対象外。
ワーカーは org-delegate が動的生成するため対象外。）

#### user 拡張の保護: `settings.local.override.json`

prune は `permissions.md` の role テンプレートで丸ごと書き換えるため、
個人で追加した allow / env / hook をそのままにすると消えてしまう。
これを避けるため、各 settings ファイルと**同じディレクトリ**に
`settings.local.override.json` を置くと、prune 時に deep-merge される。

例: 窓口で `Bash(my-private-tool:*)` を恒久的に許可したい場合は
`.claude/settings.local.override.json` に以下を書く（このファイルは
prune ツールが読むだけで、書き換えはしない）:

```json
{
  "permissions": {
    "allow": ["Bash(my-private-tool:*)"]
  }
}
```

マージ規則:
- `permissions.allow` / `permissions.deny`: base 順を保ったまま和集合
- `env`: キー単位 merge（override 側が勝つ）
- `hooks.PreToolUse[]` 等: 等値判定で重複排除した上で append
- それ以外のスカラー: override が勝つ

`.gitignore` 対象（個人設定のため。`.gitignore:23-25` で `.claude/settings.local.override.json` と
`.claude/settings.local.json.bak.*` を ignore 済み。`.curator/.claude/` と `.dispatcher/.claude/`
配下はディレクトリごと ignore のため自動的に対象）。チームで共有したい設定は
`permissions.md` 側に追加し、schema (`tools/org_extension_schema.json`) も同時に更新する。

`tools/check_role_configs.py` は同じ override ファイルを読み、その allow を
closed-world 検証から除外する（`_load_override_allow`）。よって override に追加した
個人 allow は CI / `--include-local` で `unknown allow entry` にならない。
ただし `forbidden_allow_exact`（`Bash(git *)` 等の wide allow）と
`disallow_allow_regex`（旧 `mcp__claude-peers__*`、現 `renga-peers` 等）は override 側にあっても
従来通り ERROR となる。安全契約は override で迂回できない。

#### `{claude_org_path}` の解決（窓口 / dispatcher / worker）

窓口・dispatcher・worker のテンプレートには `{claude_org_path}` プレースホルダがある
（hook command を絶対パスで固定するため。相対パスだと cwd が org ルート以外のロールで
hook が解決されず、ガードが無言で無効化する）。prune ツールは以下の優先順で解決する:

1. `--claude-org-path <abs>` 引数
2. 既存 `settings.local.json` の `env.CLAUDE_ORG_PATH`
3. 既存 hook command 内の `bash "<abs>/.hooks/..."` の `<abs>`
4. audit root（`--root`、既定はリポジトリルート）。`<root>/.hooks/` に schema の
   `required_hook_scripts` が**全て実在する場合のみ**採用する

窓口テンプレートには `env.CLAUDE_ORG_PATH` が無いため、初回実行では 2 も 3 も取れず 4 で解決される。
4 の条件を満たさない（org checkout ではない）場合は `unresolved placeholders` で中断するので、
誤った `--root` の内容が黙って書き込まれることはない。`.hooks/` ディレクトリの実在だけを条件に
すると、たまたま同名ディレクトリを持つ無関係なプロジェクトを org root として受理し、
存在しないスクリプトを指す hook（＝生成時点で死んでいるガード）を書いてしまうため。

いずれも取れない場合（fresh install など）は `--claude-org-path` を明示する:

```bash
python tools/org_setup_prune.py --role dispatcher --claude-org-path "C:/Users/me/work/claude-org"
```

#### バックアップ

書き換え前に `settings.local.json.bak.YYYYMMDD-HHMMSS` を同ディレクトリに作成する。
失敗時はこの `.bak` を `mv` で戻せば原状復帰できる。
不要であれば `--no-backup` で抑止できる。

### Step 6: ユーザー共通の sandbox denyRead 補強（`--user-common-sandbox`、Issue #429 Task B / C）

> **⚠️ main pull 後の 1 回必須**: 本リポジトリを clone / pull した後に **`python tools/org_setup_prune.py --user-common-sandbox` を 1 回実行する**。Issue #429 Task C で共有 `.claude/settings.json` から個人 path（`~/.config/gh/hosts.yml` および `Read(~/.ssh/*)` / `Read(~/.aws/*)`）を除去したため、未実行だと **個人環境の sandbox denyRead 補強が一時的に弱くなる**。

`--user-common-sandbox` は `~/.claude/settings.json` の `sandbox.filesystem.denyRead` に対してのみ idempotent な union-merge を行う専用モード（他キーは無触）:

```bash
# diff プレビュー
python tools/org_setup_prune.py --user-common-sandbox --dry-run

# 実行（既存があれば .bak 自動生成、上書き候補がない場合は no-op）
python tools/org_setup_prune.py --user-common-sandbox
```

対象ディレクトリ（`~/.ssh` / `~/.aws` / `~/.config/gh` / `~/.kube` / `~/.gnupg` / `~/.docker` / `~/.config/aws-vault`）のうち、**実在し、かつ realpath が HOME を escape しない symlink でない** ものだけが追加される。WSL2 + DriveFS の `~/.aws → /mnt/c/...` のようなケースは自動 skip（bwrap bootstrap 失敗の予防）。

仕様詳細は [`.claude/skills/org-setup/references/permissions.md`](references/permissions.md) の「ユーザー共通の sandbox denyRead 補強」節を参照。

## 注意事項

- `settings.local.json` は `.gitignore` に入っている前提（個人設定のため）
- ユーザーレベルの `~/.claude/settings.json` は既存の設定（plugins 等）を壊さないよう注意する
- ワーカーの設定はこのスキルでは配置しない（org-delegate が担当）
- prune の挙動は `tools/org_setup_prune.py` の docstring と `tools/test_org_setup_prune.py` のテストが正典