# Spec: サーヴァントのグループ — 一覧の区分け・絆の地図の表示切り替え・グループ単位の起動

- 起票: 2026-09-05
- 状態: **rev2（利用者裁定 2 点 = D4 据え置き / D6 のドラッグ採用 → 査読 2 系統 17 点 →
  採用 15 / 前提を実測で訂正して採用 2。記録は Notes 6）→ 承認（2026-09-05）→ P0 完了
  （`data_contract` 4 箇所 = `AgentGroup` の実体 / `AgentSpec.groupId` / `AgentSnapshot.groupId` /
  `group_contract` 凍結 8 本 + `settings_contract` の `fuseforks.hiddenGroups.v1`）→ P1 完了
  （コア。記録は「P1 実装記録」）→ P2 完了（フロント。記録は「P2 実装記録」。
  vitest 478・typecheck・build 緑）→ P3 完了（台帳。記録は「P3 台帳記録」）→ P4 完了 = Done**
  （2026-09-05。実機検収 12 件すべて利用者が確認。**起票から Done まで同日**。
  記録は「P4 実機記録」）
- 起点: 利用者 —「グループは表示/非表示。非表示は絆に出てこない。またチャットの送信宛先に
  でてこない。ただし非表示でも会話のメッセージには出てくる（委譲や転送の場合）。
  グループは一括起動のスイッチがある。また ON/OFF ボタンもあり、グループ一括で起動もできる。
  複数のグループを跨ぐことは今のところできない。1 エージェントが所属できるのは 1 グループ
  （たぶん跨がせない方がいいと思う。意見を求む）」（2026-09-05）。材料は CLAUDE.md
  「サーヴァントのグループ化と地図の表示切り替え（未起票・材料。2026-09-02）」— 起点は
  Symphony の突き合わせで出た「タスクで配線を切り替える」案を**採らず**、「別系統の
  ノードとエッジを作ればいい → リストをグループ化して絆に見せる見せないを切り替える」へ
  畳んだ裁定

## Goal

サーヴァント一覧を**グループ**（= タスク名）で区分けし、グループごとに **(a) 表示 / 非表示**
**(b) 一括起動に含めるかのスイッチ** **(c) グループ全員の起動 / 停止ボタン** を持たせる。
非表示のグループは**絆の地図と発話の宛先から消える**が、**配送・委譲・転送・予定・統計には
1 ミリも触らない**（隠すのは見え方で、線ではない）。

**やらないこと**: 配線の切り替え（2026-09-02 裁定。履歴の `ask_agent_N` と `Memory.md` の
関係の規則が宙に浮き、ツール集合の変更で入力キャッシュも書き直しになる）/ グループ名を
プロンプトへ入れる（Spec 14 D6 と同じ — 「調査」「リリース」を読んだ個体はその語に寄る。
名前は人が一覧と地図で見るための分類）/ グループごとの設定の雛形（それは役職 = Spec 14 の
仕事）/ 複数グループへの所属（D2）/ 広場ログ・黒板のグループ分け（境界は村と `work_dir` の
まま — 2026-09-02 の材料が数えた 2 つの境界）。

## 起票時の実測（2026-09-05。コードを読んだ）

| 事実 | 場所 | 帰結 |
|---|---|---|
| 個体を列挙する面は **5 つ**: 一覧（`AgentList.vue` の `inListOrder(state.agents)`）/ 地図のノード（`TopologyMap.vue:67`）/ 地図の辺（`state.edges` を `orderOf` で向き付け）/ 会話ペインの絞り込み `<select>`（`ChatPanel.vue:690`）/ Alt+↑↓ の巡回（`agentNav.ts` の `nextAgentId(state.agents, …)`） | 各ファイル | **「非表示」が効くべき面はこの 5 つ**。発話の宛先は `state.selectedAgentId` = 左一覧の選択なので、一覧から消えれば宛先からも消える（宛先の独立した選択 UI は無い） |
| 個体を列挙するが**効かせない**面: 会話の行（`chatRows` は `state.agents` から名前を引くだけ）/ 統計 / 黒板 / 予定の宛先 / `list_topology` の配送 | — | 「非表示でも会話のメッセージには出てくる」は**何もしなければ成立する** — 名前解決は隠さない |
| `AgentSpec.role_id: Option<AgentRoleId>` が**参照方式の前例** — 表示のためだけに持ち、実行経路で読まず、削除しても個体は変わらない（`role_contract` 凍結 7） | `model.rs:453-466` / `world.rs:962-975` | グループの所属は**同じ形**で持てる（`group_id: Option<AgentGroupId>`）。引けなければ無所属として描く |
| 一括起動は 2 軸（含めるか = `batchStart`・動いているか = `status`）で、判定は `batchAction(agents)` の純関数 1 本。`runBatch` は対象を 1 体ずつ `setAgentRunning` | `batchStart.ts` / `useOrchestrator.ts:939` | グループの ▶/■ は**同じ純関数に部分集合を渡すだけ**で書ける。新しい判定を作らない |
| `AgentSnapshot` は `AgentSpec` の投影で、設定ダイアログと一括切り替えは**投影から spec を組み直して保存**する（`snapshotToSpec` の 1 実装） | Spec 14 P1 / Spec 29 D4 | `AgentSpec` に欄を足したら `AgentSnapshot` と `snapshotToSpec` にも要る — 無いと**保存のたびに所属が消える** |
| 端末側の棚は 2 種: 真偽値だけの `useUiSettings`（boolean 以外は既定へ落とす）と、配列を持つ `useWorkDirHistory`（`fuseforks.workDirHistory.v1`） | `useUiSettings.ts` / `useWorkDirHistory.ts` | 非表示グループの集合は**配列の棚**の形（`fuseforks.hiddenGroups.v1`）。`useUiSettings` へ混ぜると真偽値の規律が割れる |
| `world.json` は旧版のバイナリが**未知の欄を黙って削って書き戻す**（`failures.md` #112） | — | `groups` と `group_id` は**旧版で村を開くと消える**。利用者が負う条件として書く（D8） |
| 一覧の並びは `order`（1 本の `VueDraggable`）で、地図の辺の向き付けも `order` を読む | `AgentList.vue:369` / `TopologyMap.vue:88` | 区分けしても **`order` は 1 本のまま**（グループ内の並びに使う）。地図の向き付けは触らない |

## Design

### D1: 所属は村の内容物、表示は端末の都合（置き場を 2 つに割る）

- **`AgentGroup { id, name, batch_start }`** を `PersistedWorld.groups`（`world.json`）へ。
  役職（`roles`）と同じ棚。**村を配ると付いて回る**（グループはタスクの分類で、村の設計の
  一部）。**`id` はコアが発行する UUID v4 で、削除しても再発行しない**（役職と同じ
  `Uuid::new_v4`。rev2、査読 1-3 — 引けない `group_id` を残す D5 と組むと、再利用した id が
  削除前の個体を黙って吸う）。**グループの並びは `groups` の配列順（= 作成順）**で、
  並び替えの UI は持たない（rev2、査読 1-10 / 2-5。要るときに `reorder_groups` を足す —
  空の口を先に作らない）
- **`AgentSpec.group_id: Option<AgentGroupId>`**（`#[serde(default)]`）。**参照**であって
  コピーではない — グループを改名すれば見出しが全部追従する（Spec 14 の「名前は参照」）。
  `AgentSnapshot` にも写す（Spec 14 P1 の教訓）
- **非表示の集合は `localStorage`**（`fuseforks.hiddenGroups.v1` = 隠しているグループ id の
  配列）。**村には入れない** — 2026-09-02 の材料「地図の表示フィルタは端末の見え方。村に
  入れると配った先で『なぜか半分しか見えない』になる」（`autoFitOnResize` と同じ棚）。
  知らない id は読み飛ばす（削除済みのグループを指していても壊れない）

### D2: 所属は 1 つ。跨がない（利用者の見立てに同意 — 意見）

**`Option<AgentGroupId>` で持つ = 構造で 1 つに固定する。** 理由は 3 つで、どれも
「跨がせると規則がもう 1 つ要る」形:

1. **「非表示」の意味が一意でなくなる。** A に居て B にも居る個体は、A を隠して B を出した
   とき見えるのか。和か積かを決める規則が要り、しかもその規則は画面のどこにも書けない
2. **一括起動の門が個体ごとに 1 つに決まらなくなる。** A のスイッチ ON・B のスイッチ OFF の
   個体は全体 ▶ で起きるのか。ここも和か積かの規則がもう 1 つ
3. **`role_id` と同じ形で済む。** `Option<Id>` は `snapshotToSpec` / 投影 / 設定ダイアログの
   select が全部前例どおりに書ける。`Vec<Id>` にした瞬間に UI が multi-select になり、
   1 と 2 の規則を画面へ持ち込むことになる

**跨ぎたい実例は「2 系統で共有するワーカー」だが、所属を跨がなくても接続は跨げる。**
`connected_agents` は不変なので、系統 A の進行役と系統 B の進行役の両方から線を引いた
ワーカーは、どちらの系統の仕事も受ける。**共有ワーカーは無所属にする**のが処方 —
**無所属はどのフィルタでも隠れない**（D3）ので、A だけを見ているときも B だけを見ている
ときも共有ワーカーは地図に居る。失うのは「共有ワーカーが A の見出しの下にも B の見出しの
下にも並ぶ」見た目だけで、それは D2 の 1 と 2 を持ち込んでまで買うものではない。

**頻度を見てから広げる**（#47 の規律）。`Option<Id>` から `Vec<Id>` へは `serde` の
互換で広げられる（1 要素の配列として読む）ので、今狭くしておく代償は無い。

### D3: 非表示が効く面は 5 つ。効かない面は名指しで凍結する

**効く**（隠れたグループの個体を出さない）:

| 面 | 何が変わるか |
|---|---|
| 一覧（`AgentList`） | グループの見出しごと畳む（カードが並ばない）。見出し自体は残す（**隠していることが見える** — 見出しまで消すと「なぜか居ない」になる） |
| 地図のノード | 出さない |
| 地図の辺 | **両端が見えている辺だけ**描く。隠れる辺の数 M = **全辺 − 可視の辺**（片端でも両端でも隠れていれば数える。rev2、査読 2-3）を地図の要約行へ（「隠れているサーヴァント N 体・辺 M 本」）。片端だけ描くと宙に浮いた線になる。**無所属の共有ワーカーはノードとして残るが、隠れたグループへの辺は消えて数に回る**（rev2、査読 1-4 — 例外にしない。辺の終点が無い） |
| 会話ペインの絞り込み `<select>` | 出さない |
| Alt+↑↓ の巡回と発話の宛先 | 見えている個体だけを巡る。**隠した瞬間に選択中だった個体は、見えている先頭へ移す**（`useOrchestrator.ts:396` の「選択が一覧に無ければ先頭」と同じ規則を可視の集合に対して）。**可視が 0 体なら選択は `null`** — それは空の村と同じ状態で、宛先欄は「宛先を選択してください」、`nextAgentId` は `null` を返す（既存の挙動。rev2、査読 1-1 / 2-4）。**選択中のカードを畳んだ区分けへ落としたときも同じ規則で選択が移る**（隠れた相手を宛先に残さない） |

**効かない**（凍結）: 会話の行（名前解決は隠さない — 委譲・転送・束ねで隠れた個体の発話が
出る）/ 配送の全経路（人の発話・`ask_*`・`transfer_to_*`・`plan` の波・スケジュール）/
ツールの提示集合（`connected_agents` は不変なので `ask_agent_N` は隠れていても生える）/
統計・黒板・予定の宛先・ステータスバー・`fuseforks.log` / **一括起動**（非表示のグループも
全体の ▶ で起きる。休ませるのは D4 のスイッチの仕事 — 「非表示 = 休ませる」ではない。
見出しのスイッチの説明にそう書く。rev2、査読 1-5）。**隠すのは見え方であって、
提示集合と配送経路には触らない** — Spec 20 で同一性を確認した「提示集合 = 実行フィルタ」の
規律をグループが破らない。

**無所属（`group_id` が `None` か、引けない id）はどのフィルタでも隠れない。** 隠す単位が
グループなので、グループに居ない個体を隠す口が無いのは構造の帰結。

### D4: 一括起動は「含めるか」の門が 2 段になる。判定は既存の 1 本

- **`AgentGroup.batch_start: bool`（既定 true）** = 全体の ▶（一覧ヘッダ）がこのグループの
  個体を対象にするか。**個体の `batchStart` は据え置き**で、全体 ▶ の対象は
  `agent.batchStart && (無所属 || group.batchStart)`。2 段にするのは、系統を丸ごと休ませる
  ときに個体のトグルを N 回押さずに済ませるため（グループが無ければ今までと 1 ミリも
  変わらない）
- **グループの ▶/■**（見出しに置く）= `batchAction(そのグループの個体)` — **既存の純関数に
  部分集合を渡すだけ**。起こせる相手が居れば ▶、全員動いていれば ■、遷移中が居れば無効、
  の規則は全体と同じ。**個体の `batchStart` は効かせる**（「含めるか」の軸を 2 つにしない —
  カードのトグルは全体でもグループでも同じ意味）。**グループのスイッチ（`batch_start`）は
  グループの ▶ には効かない** — 効かせるとスイッチ OFF のグループの ▶ が死んだボタンになる。
  スイッチは**全体 ▶ の門**であってグループ自身の門ではない、と画面の説明に書く
- 実行は既存の `runBatch(targets, running)`。新しい IPC は要らない（`set_agent_running` を
  1 体ずつ）
- **グループの全員が `batchStart` OFF なら、グループの ▶ は無効で、`title` が「対象 0 体」と
  言う**（`batchLabel` の `none` の既存の形。rev2、査読 1-6 / 2-6）。D4 の「死んだボタン」の
  論点とは別 — あちらはグループのスイッチという**別の場所の設定**でボタンが永久に死ぬ形、
  こちらは**すぐ下に並ぶカードのトグル**が理由で、理由が見出しの直下に見えている
- **無所属の見出しにも ▶/■ を置く**（無所属の個体だけを対象に）。目とスイッチは置かない —
  無所属は隠れず、スイッチの保存先（`AgentGroup`）も無い（rev2、査読 2-2）

**採らなかった形**: グループの ▶ が個体の `batchStart` を無視して全員を起こす。
「含めるか」の軸がボタンごとに違う意味になり、カードのトグルが何を意味するか読めなくなる。
**利用者裁定（2026-09-05）: この形でよい —「トグルが効くほうが自然」。**

### D5: 削除は所属を巻き込まない。改名は見出しが追従する

- **削除** = `groups` から消すだけ。個体の `group_id` は**書き換えない**（役職の削除と同じ。
  `remove_role` は `role_id` に触らない）。引けない id は無所属として描かれるので、削除の
  次の瞬間から個体は無所属の並びに戻る。**配った村を旧版で開いた場合と同じ見え方**になる
  （D8）ので、規則が 1 つで済む。**データ上は「引けない id が残る」と「`None`」の 2 つが
  並ぶ**が、id を再発行しない（D1）ので取り違えは起きない。**引けない id は次に所属を
  書く操作で `None` へ正規化する** — 設定ダイアログの select は引けない id を「無所属」と
  して表示し保存で `None` を書く / drop の確定（D6）は無所属の箱へ落ちたとき・無所属の箱の
  中で動かしたときに `None` を書く（rev2、査読 2-7 — 経路で残り方が割れないように）
- **改名** = `name` の書き換え。見出し・地図の要約行が追従する（参照方式の効き所）
- **作成時の名前は空を拒む**（`normalize_user_name` と同じ述語で封筒の予約文字を弾く必要は
  **無い** — 名前はプロンプトに入らない）。重複名は拒まない（id が別なら別のグループ。
  タスク名は重なりうる）

### D6: 入口は 3 つ。作る側・所属を変える側・見る側

| 何を | どこで | 前例 |
|---|---|---|
| グループの作成 | **一覧の最下段の点線エリア**（押すと名前の入力に変わり、Enter で作られた見出しが上に生える。**P4 の実機で利用者が裁定** — 初版はヘッダのボタンだったが「無い方がいい。点線エリアのほうがスッキリする」） | 役職の作成は `RoleDialog` の中だが、グループは**一覧そのものの区分け**なので一覧の中に入口を置く |
| グループの改名・削除 | 見出しの鉛筆 → `GroupDialog.vue`（一覧 ⇄ 下書きの二層。dirty 確認なし）。**スイッチはここに置かない**（見出しだけ — 二重管理にしない。rev2、査読 1-9） | `RoleDialog.vue`（Spec 14 P3）。**タイトルバーには置かない** — 役職は「村のカテゴリ」（条例の右）だったが、グループは一覧の区分けそのもの |
| 個体の所属 | `AgentSettingsDialog` の select（無所属 + グループ一覧）と、区分けをまたぐドラッグ（下） | 役職の select（Spec 14 P4 の「既存の個体に付ける入口」の教訓 — **作成フォームと編集フォームの両方に置く**） |
| 表示 / 非表示・グループの ▶/■・スイッチ | 一覧の各見出し。**グループの見出し** = 目 + ▶/■ + スイッチ + 体数 / **無所属の見出し** = ▶/■ + 体数だけ（rev2、査読 2-2） | 一覧ヘッダの ▶（`batchStart.ts`） |

**一覧の描画は「無所属」→ グループ順（配列順）の区分け。** 各区分けの中は `order` 順。
**グループが 1 つも無い村では見出しを出さない**（今の一覧と 1 ミリも変わらない）。

**`order` の意味は「一覧に並ぶ位置」のまま**（`kizunaEdges.ts` の doc が「左ペインの
並びそのもの」と書いている定義を動かさない）。区分けが入ると一覧の並びは
「無所属 → グループ順、各区分けの中は `order`」になるので、**最初のドラッグで `order` が
その連結へ書き直される**（一度きりの正規化）。地図への効きは**双方向の辺の描画上の始点
だけ**で、一方向の矢は `drawDirection` が触らない（**査読 1-2 / 2-1b の「辺の向きが
一斉に反転する」は当たらない** — 両端に矢を持つ 1 本の始点が入れ替わるだけで、矢の意味は
変わらない。rev2、前提を実装で訂正して採用: 正規化が起きること自体は明記する）。

**区分けをまたぐドラッグで所属が変わる**（利用者裁定 2026-09-05 —「並び順はグループ順・
グループ内並び順になるので、そのグループのエリアにドロップされたらグループも変わるほうが
自然。動きをみたい」）。形は**区分けごとに 1 つの `VueDraggable`**で、全部に同じ
`group` 名を与えて箱をまたげるようにする（Sortable の共有グループ）。**1 本の箱に見出しを
混ぜる形は採らない** — Sortable の `oldIndex` / `newIndex` は `draggable` 選択子に一致する
子だけを数えるので、見出しを配列に混ぜると `update:model-value` の splice 位置がずれる
（型検査にも lint にも掛からない種類の結合）。

- **確定は end で 1 回**（Spec 21 の保留コミットの形は据え置き）。`update:model-value` は
  箱ごとに保留し（出た箱と入った箱の 2 回飛ぶ）、end の `evt.to` が指す箱の区分けを
  **動かしたカードの新しい `group_id`** に、全箱の並びを連結したものを新しい `order` にする。
  **連結の材料は `state` から組んだ全区分け**（畳んだ区分けの個体も含む — DOM に無くても
  `state.agents` には居る）で、保留された箱だけをその並びで差し替える。**畳んだ区分けの
  個体が `order` から漏れる形は構造的に無い**（rev2、査読 2-1a）
- **コアへは新設の IPC 1 本 `commit_agent_drop { order, regroup }`** で渡す — 世界ロックの
  中で並びと所属を**一緒に**書いて 1 回で永続化する。`reorder_agents` + `update_agent` の
  2 本に割ると、片方だけ通ったとき「並びは新しい区分けの位置、所属は旧グループ」が
  `world.json` に残る（rev2、査読 1-7）。既存の `reorder_agents` は据え置き（一括切り替えの
  再同期など他の呼び手が居る）
- **地図のノードで終わった drop は今までどおり絆を張り、並びも所属も確定しない**
  （差し戻しは `evt.from` と `oldIndex` が箱単位で来るのでそのまま効く）。**共有 `group` の
  Sortable が地図への drop を横取りしないかは P2 で実測する**（査読 1-8 — 起票時の読みでは
  地図は Sortable の箱ではないので横取りされないが、`force-fallback` の分身の座標で
  `elementFromPoint` を引く経路は箱が増えても同じ）
- **畳んだ区分け（非表示のグループ）にも落とせる。** 見出しの直下に薄い落とし場を残し、
  落ちたカードは畳まれた中の**末尾**へ入る（見出しの体数が 1 増えるので消えていないと
  読める）。**畳んだ中のカードは掴めない**（描画されていない）ので、**出す手段は一度
  表示に戻すことだけ** — 非対称だが、隠したまま動かす操作は「見えないものを動かす」
  形なので塞いでよい（rev2、査読 1-8）。「見えないところへしまう」は正当な操作なので
  塞がない。**動きは P4 で見る** — ここが利用者の「動きをみたい」の本体で、違和感が出たら
  落とし場を閉じる側へ倒す
- `holdReorder` / `onDragEnd` は箱の数だけ増えない — 純関数
  `commitDrop(sections, pendingBySection, toSectionKey, movedId)` が
  `{ order: AgentId[], regroup: { id, groupId: GroupId | null } | null }` を返し、
  コンポーネントはそれを IPC 1 本へ流すだけ。**単体で留めるのは 3 つ**: 同じ箱の中の移動は
  `regroup` が `null` / 無所属の箱へ落ちたら `regroup.groupId` が `null`（引けない id の
  正規化。D5）/ 畳んだ区分けの個体が `order` に残る

### D7: 触る契約と台帳

`data_contract.yaml`: `AgentGroup` の実体（`roles` の隣）/ `AgentSpec.groupId` /
`AgentSnapshot.groupId` / `group_contract`（凍結: 所属 1 つ・表示は端末・効く面 5 つと
効かない面・削除は巻き込まない・プロンプトに入れない・実行経路で読まない）/ `settings_contract`
の端末側の鍵に `fuseforks.hiddenGroups.v1`。`ipc_contract.rs` の literal（`AgentSnapshot` に
欄）。DETAIL 日英（画面構成の左ペインの行 + 層の説明）/ README 3 言語（「何ができるか」に
1 行）。**grep 網の外**: Qiita 記事は一覧を触れているので画面が変われば古くなる（嘘には
ならない — 見出しが増えるだけ）。LP は一覧の見た目に触れていない。

### D8: 利用者が負う条件

- **旧版のバイナリで村を開くと `groups` と `group_id` が消える**（#112。`#[serde(default)]` は
  「欠けても読める」だけで「消さない」を保証しない）。**未知の欄を保持して書き戻す側は
  今も未起票** — この Spec で欄を足すので、その判断をここで問う（Notes 3）
- **非表示は端末ごと**。村を配っても、別の端末で開いても、全部見える状態から始まる

## Stories

- S1 「調査」と「リリース」の 2 グループを作り、個体を振り分けると、一覧が 2 つの見出しで
  区切られ、地図には全員が居る
- S2 「リリース」を隠すと、地図から「リリース」の個体と、その個体へ向かう辺が消え、
  要約行に「隠れているサーヴァント N 体・辺 M 本」が出る。一覧の見出しは残り、畳まれている
- S3 隠れている個体に進行役が委譲すると、会話ペインにその個体の発話が普通に出る
  （隠れているのは見え方で、線ではない）
- S4 「リリース」の見出しの ▶ を押すと、そのグループの個体だけが起きる。全体の ▶ は
  「リリース」のスイッチが OFF なら「リリース」を飛ばす
- S5 共有ワーカーを無所属にしておくと、どちらのグループを隠していても地図に**ノードとして**
  残る。隠したグループへ向かう辺は消えて要約行の数に回る（誰と繋がっているかは、そのグループを
  出したときに見える）

## Phases

- **P0** — `data_contract` の凍結（D7 の契約側）
- **P1** — コア: `AgentGroup` / `PersistedWorld.groups` / `World` の CRUD（`upsert_group` /
  `remove_group` / `group` / **`commit_agent_drop`**）/ `AgentSpec.group_id` +
  `AgentSnapshot` の投影 / IPC 4 本（`list_groups` / `upsert_group` / `delete_group` /
  `commit_agent_drop`。設定ダイアログからの所属の変更は既存の `update_agent` に乗る）。
  結合 4 本（所属が保存を往復して残る / グループ削除で個体の `group_id` が**変わらない** /
  旧い `world.json`（`groups` 無し）が読める / **`commit_agent_drop` は並びと所属を 1 回の
  永続化で書く** — 途中で落とす変異で片方だけ残らない）。**実行経路で読まないことは
  走査テストで留める**（`orchestrator/` の本体に `group_id` が 0 件 — `pricing` が `budget` を
  読まない網と同じ形）
- **P2** — フロント: `lib/agentGroups.ts`（純関数: 区分け `sectionize(agents, groups)` /
  可視の集合 `visibleAgents(agents, groups, hidden)` / 全体 ▶ の対象 `batchEligible` /
  地図の辺のフィルタと隠れた数 / **drop の確定 `commitDrop`**）+ 単体 / `useHiddenGroups.ts`
  （配列の棚）/ `AgentList.vue` の**区分けごとの `VueDraggable`**（同じ `group` 名）と見出し
  （目・▶/■・スイッチ・体数）/ `GroupDialog.vue` / `AgentSettingsDialog` の select /
  `TopologyMap.vue` のノードと辺のフィルタ + 要約行 / `ChatPanel.vue` の `<select>` /
  `agentNav.ts` の巡回を可視の集合へ / `snapshotToSpec` に `groupId` / 辞書 ja/en。
  **ミューテーション**: `visibleAgents` を素通しに → 地図と一覧の単体が赤 / 全体 ▶ の門から
  グループのスイッチを外す → `batchEligible` の単体が赤 / `commitDrop` が箱をまたいでも
  `regroup` を `null` に → drop の単体が赤
- **P3** — 台帳（D7）
- **P4** — 実機検収

## P1 実装記録（2026-09-05）

`model.rs`: `AgentGroupId`（`fresh()` = UUID v4）/ `AgentGroup { id, name, batch_start }` /
`AgentSpec.group_id` / `AgentSnapshot.group_id`。`world.rs`: `PersistedWorld.groups`（`Vec` —
配列順が見出しの並び。役職は順序を持たないので `BTreeMap` だが、グループは違う）/
`create_group`（id の発行と空名の拒否）/ `upsert_group`（配列の位置を保つ）/ `remove_group`
（個体に触らない）/ `groups` / `commit_agent_drop`（所属 → 並びの順。所属の個体が未登録なら
並びも触らない）。`error.rs`: `GroupNotFound` / `InvalidGroupName`。`lifecycle.rs` に包み 5 本
（System 行は出さない — 名前がプロンプトに入らないので改名しても個体の見え方は変わらない）。
IPC は **5 本**（rev2 の 4 本 + `create_group` — id をコアが発行するので、作成と更新を
1 本の upsert に畳めない。役職は id を人が打つ形だったので upsert 1 本で済んでいた）。
`ipc_contract.rs` の 2 リストへ `groupId`。

**走査テストの網は `mod.rs` まで含める。** 最初 `mod.rs` の共通 import へ
`AgentGroup` を足したら走査が自分で赤になった — 型を CRUD の包み（`lifecycle.rs`）だけが
読む形にし、`mod.rs` の import には入れない。**実行経路に型が見えないこと**まで留めている。

単体 4（`world.rs`）+ 結合 4 + 走査 1。ワークスペース全緑・clippy 警告ゼロ。
**ミューテーション 2 回（予測を先に書いて）**: `mod.rs` の import へ `AgentGroup` を戻す →
走査 1 本だけ赤（予測どおり）/ `commit_agent_drop` を「並び → 所属」の順にする →
`a_drop_writes_order_and_membership_in_one_step` だけ赤（予測どおり。所属の失敗で並びが
残る形を留めている）。

## P2 実装記録（2026-09-05）

**規則は `lib/agentGroups.ts` の純関数 7 本に閉じた** — `sectionKeyOf`（引けない id は
無所属）/ `sectionize`（無所属 → 配列順、空の区分けも返す = 見出しは落とし場）/
`isHidden` / `visibleAgents` / `settleSelection`（可視 0 体なら `null`）/ `batchEligible`
（2 段の門・非表示を見ない）/ `visibleEdges` / `commitDrop`（`state` から組んだ全区分けを
材料に、保留のある箱だけ差し替える。同じ箱なら `regroup: null`、無所属の箱では引けない id を
`null` へ正規化）。コンポーネントは配線だけ。

**非表示の棚は `useHiddenGroups.ts`**（`fuseforks.hiddenGroups.v1`。`useWorkDirHistory` と
同じ形。`parseHidden` / `toggleHidden` は純関数）。**選択の落ち着き先は `App.vue` の watch 1 本**
（個体・グループ・非表示のどれが動いても `settleSelection` で数え直す）。

**一覧は区分けごとに 1 つの `VueDraggable`**（同じ `group="agents"`・`data-section-key`）。
`holdReorder` は箱ごとに保留し、**畳んだ区分け**では Sortable が返すのが落ちたカードだけなので
「畳まれた中の個体 → 落ちたカード（末尾）」に組み直す。`onDragEnd` は `evt.from` / `evt.to` の
`data-section-key` から区分けを引き、地図のノードなら差し戻し（`evt.item.parentElement` から
外す — 箱をまたいだ後は `evt.from` の子ではない）、それ以外は `commitDrop` → IPC 1 本。
見出し = 目（無所属には無い）+ 名前 + 体数 + ▶/■（`batchAction(section.agents)`）+
スイッチ（無所属には無い）。**グループが無い村では見出しを出さない**（今までの一覧のまま）。

**触った面**: `types.ts` / `ipc.ts`（5 本）/ `agentSpec.ts`（`groupId` を写す）/
`useOrchestrator.ts`（`state.groups`・`fetchAndAssign`・action 4 本）/ `GroupDialog.vue`（新設。
作成・改名・削除だけ）/ `AgentList.vue` / `AgentSettingsDialog.vue`（select。引けない id は
「無所属」を選んだ状態で出し、保存で `null`）/ `TopologyMap.vue`（`visible` / `visibleEdges` /
要約行の「非表示: N / M」）/ `ChatPanel.vue`（絞り込み）/ `App.vue`（巡回と選択の watch）/
辞書 ja/en（`agentList` 12・`agentSettings` 3・`groups` 18・`map` 1・`orchestrator.op` 4）。

**起動の網が働いた** — `fetchAndAssign` が `list_groups` を引くようになった瞬間、
`useOrchestrator.*.test.ts` の 6 本が赤になった（モックに無い IPC）。Spec 25 P3 と同じ形で、
9 ファイルへ `listGroups` のモックを足して緑。**型検査も 2 箇所を指した**（`AgentSnapshot` の
fixture 2 つ — 欄を足した側が気づけない場所）。

**ミューテーション 3 回（予測を先に書いて）**: `visibleAgents` を素通し → visibility の 2 本
（予測どおり）/ `batchEligible` からグループの門を外す → 1 本（予測どおり）/ `commitDrop` が
箱をまたいでも `regroup: null` → 箱またぎ 1 本 + 無所属の正規化 1 本（予測どおり）。

**起票時の読み（Notes 7）は試していない** — 「1 本の箱に見出しを混ぜる」形は P2 で試さず、
最初から区分けごとの箱で書いた。`vue-draggable-plus` の splice が index を見出しごと数えるかは
**未実測のまま**。区分けごとの箱で動くなら、それでよい。

## P3 台帳記録（2026-09-05）

DETAIL 日英に「グループ」の節（役職の直後・予定の直前）と、画面構成の左ペインの行、
ディレクトリ木 3 行（`lib/agentGroups.ts` / `GroupDialog.vue` / `composables/useHiddenGroups.ts`）。
README 3 言語の「何ができるか」表へ 1 行（役職の直後。**行数は 166 / 167 / 162** —
上限 160 の意図「新しく来た人が最初に探すもの」の側なので許容。次に削るなら別の節から）。
CLAUDE.md の「Spec の状態」と現在地。`data_contract` は P0 で済み。
**PRIVACY 日英は変えない**（外へ送るものは増えない）。**grep 網の外**: Qiita 記事は一覧を
触れているが「見出しが増える」だけで嘘にならない / LP は一覧の見た目に触れていない。

## P4 実機記録（2026-09-05〜。利用者検証）

**最初の実機で指摘 2 件**（どちらも同日に直した）:

- **スイッチを ON にするとノブが消える。** 初版は `translate-x-*` でノブを動かしていたが、
  ON で見えなくなった。カードのトグル（`AgentCard`）は `left-*` で置いており正しく出ている
  ので、**同じ書き方に揃えた**（`left-0.5` / `left-3`）。**同じ部品を 2 通りに書いた**のが
  原因で、以後トグルはカードの書き方を写す
- **ヘッダの「グループ」ボタンは無い方がいい。** 利用者 —「リストの一番下にグループ追加の
  点線エリアをつけてそこをクリックすると上にグループが作成されるという感じのほうが
  スッキリする」。作成の入口を**一覧の最下段の点線エリア**へ移し（押すと名前の入力に変わる）、
  改名・削除は**見出しの鉛筆**から `GroupDialog` へ。ヘッダのボタンは撤去。D6 の表を書き換えた

**検収 1〜12 すべて OK**（利用者の報告 —「動きも問題ありません。数なども大丈夫です」）。
起票時の読みで唯一未実測だった **Sortable の共有グループが地図への drop を横取りしない**
（検収 9）と、**畳んだ区分けへ落とせて末尾に入る**（検収 10）が実機で通った。要約行の
「非表示: サーヴァント N / 絆 M」の数（検収 2）も一致。**旧版で村を開くと `groups` と
`group_id` が消える**（検収 7）は #112 の形の再演として意図的に踏み、次に `world.json` へ
欄を足す Spec で「未知の欄を保持して書き戻す」を判断する材料になった。

## 検収項目（各項目に到達経路を書く）

| # | 何を見るか | 到達経路 |
|---|---|---|
| 1 | グループを 2 つ作り 3 体ずつ振り分ける → 一覧が「無所属 / A / B」の見出しで区切られ、`world.json` に `groups` 2 件と各個体の `groupId` | 一覧ヘッダの「グループ」+ 各個体の設定ダイアログ。ファイルで裏取り |
| 2 | B を隠す → 地図から B の 3 体と、片端でも B に掛かる辺が消え、要約行に「隠れているサーヴァント 3 体・辺 M 本」。一覧の B の見出しは畳まれて残る | 一覧の見出しの目。M = `list_topology` の全辺 − 画面に残った辺（B の中で閉じた辺も数に入る。手で数える） |
| 3 | B が隠れたまま、A の進行役に「B の X に聞いて」と頼む → 会話ペインに X の発話が出て、`fuseforks.log` に `turn start: agent=X` | 隠すのは見え方で線ではない、の対照。**ログの行が証拠** |
| 4 | B が隠れたまま Alt+↓ を回す → A と無所属だけを巡り、B の個体には止まらない | Spec の「効く面」の 5 つ目 |
| 5 | B の見出しの ▶ → B の 3 体だけ `starting`。全体の ▶ は B のスイッチ OFF なら A と無所属だけ | ボタンの `title` が対象数を言う（`batchLabel` の既存の形） |
| 6 | B を削除 → B の 3 体が無所属の並びへ戻り、`world.json` の各個体の `groupId` は B の id のまま残る | D5 の「巻き込まない」。ファイルで裏取り |
| 7 | 旧版（v0.1.15）のバイナリで同じ村を開いて閉じる → `groups` が消える（**負う条件の実物**。開発機でだけ踏む） | #112 の再演を意図的に。**次に `world.json` へ欄を足す Spec で「保持して書き戻す」を判断する材料** |
| 8 | A のカードを B の区分けへドラッグして落とす → カードが B の見出しの下へ移り、`world.json` の `groupId` が B に、`order` が連結した並びに | D6 の本体。**同じ区分けの中で動かしたときは `groupId` が変わらない**（対照） |
| 9 | 検収 8 の途中で地図のノードへ落とす → 絆が張られ、カードは元の区分け・元の位置へ戻り、`groupId` も変わらない | Spec 21 の drop が箱を割った後も生きていること |
| 10 | B を隠したまま A のカードを B の見出しの直下へ落とす → カードが消えて B の見出しの体数が 1 増え、B を出すと**末尾**に居る。落としたカードが選択中なら、選択は見えている先頭へ移る | 「見えないところへしまう」。**動きの違和感はここで見る** |
| 11 | 無所属 0 体で全グループを隠す → 一覧は見出しだけ、地図は空、宛先欄が「宛先を選択してください」、Alt+↑↓ で何も起きない。1 つ出すと先頭が選ばれる | 可視 0 体 = 空の村と同じ状態（D3） |
| 12 | 全体の ▶ → B のスイッチが ON なら B が隠れていても B の個体が起きる | 「非表示 = 休ませる」ではない（D3 の効かない面） |

## 追補（2026-09-08。Done の後に実機で出た 1 件）

- **隠して 2 体だけにすると Fit が左上へ寄る**（`failures.md` #122）。真因は v-network-graph の
  `fitToContents` が上限を超える zoom を要求したとき zoom だけを丸めて pan を丸めないこと
  （残った個体の広がりが小さいほど要求 zoom が上がる = 隠すほど出る）。処方は `fitMargin`
  （`lib/kizunaFit.ts`）で余るぶんを余白へ回し、要求 zoom を上限ちょうどに留める。
  読み込み時の Fit も同じ `fit()` へ。**先に書いた 2 つの処方（`visibleLayouts` / `:key`）は
  真因を外していた**が、幽霊の座標を渡さない衛生と「隠した直後に Fit し直す」として残す。
  P2 の「座標は `layouts` に全個体ぶん保つ」は覆したまま（座標の真実は `topologyPositions`）。
  凍結 8 本は不変。**実機で確認 = 利用者「直りました。動きは完璧です」**（2026-09-08）

## Notes

1. **意見（D2）— 跨がせないのが正しい。** 利用者の見立てに同意する。根拠は「跨がせると
   和か積かの規則が 2 つ要り、どちらも画面に書けない」こと。跨ぎたい実例（共有ワーカー）は
   無所属で足りる。**狭いほうから始めて広げるのは `serde` の互換で安く、広いほうから
   狭めるのは村のデータを壊す** — 向きが非対称なので狭いほうから
2. **グループ名はプロンプトに入れない**（Spec 14 D6 と同じ裁定を 2026-09-02 に先取り済み）。
   顔ぶれの行にも載せない。**ただし 1 つだけ検討の余地がある** — `plan` の撒き先を
   「同じグループの接続先」に絞る案。これは配送に触るので**本 Spec では採らない**
   （やらないことの「配線の切り替え」と同じ側）。要るなら別 Spec で、`connected_agents` の
   部分集合をどう提示するかから
3. **`world.json` の未知の欄を保持して書き戻す**（#112 の未起票）は、この Spec が欄を
   2 つ足す最初の機会。**本 Spec では作らない** — 効くのは今後足す欄だけで、配布済みの旧版は
   直せない。ただし検収 7 で実物を踏むので、頻度ではなく実害の形で判断材料が出る
4. **`planReview` / `allowHandoff` は個体の属性ではなく系統での役割の属性**（Spec 43 凍結 10
   の帰結・2026-09-02 の材料）。グループ側へ移す案はあるが、本 Spec では触らない — 移すと
   「グループが無い村では設定できない」形になり、既存の村の設定を動かす
5. **利用者裁定 2 点（2026-09-05・起票の同日）**: D4 の形（グループの ▶ も個体の
   `batchStart` を効かせる）は**据え置き** —「トグルが効くほうが自然」。D6 の区分けを
   またぐドラッグは**採用へ反転** —「そのグループのエリアにドロップされたらグループも
   変わるほうが自然。動きをみたい」。rev1 の初版は「頻度を見てから」と書いていたが、
   並び順がグループ順・グループ内順になる以上、ドラッグの終点がグループを指すのは
   構造の帰結で、select だけにすると「見た目の場所」と「所属」が食い違う操作が残る
6. **査読の反映（rev2・2026-09-05。2 系統 17 点）**

   | 系統-# | 指摘 | 扱い | 根拠 |
   |---|---|---|---|
   | 1-1 / 2-4 | 可視 0 体のときの選択が未定義 | 採用 | `null` を許す — 空の村と同じ状態で、`ChatPanel` は「宛先を選択してください」、`nextAgentId` は `null`（既存の挙動を確認）。検収 11 |
   | 1-2 / 2-1b | `order` が連結へ書き直され、地図の辺の向きが一斉に変わる | **前提を実装で訂正して採用** | `drawDirection` は**双方向の辺の描画上の始点**だけを `order` で決め、一方向の矢は触らない。反転は起きない。正規化が一度起きること自体は D6 に明記 |
   | 1-3 | 引けない id と `None` が並び、id 再利用で吸われる | 採用 | id は UUID v4 で再発行しない（D1）。正規化の経路を D5 に |
   | 1-4 | 共有ワーカーの辺が消える | 採用 | 例外にしない（辺の終点が無い）。S5 と D3 に「ノードは残るが辺は数に回る」と明記 |
   | 1-5 | 非表示でも全体 ▶ で起きる | 採用 | 効かない面に一括起動を明記 + 見出しの説明文。検収 12 |
   | 1-6 / 2-6 | 全員 OFF のグループの ▶ | 採用 | 無効 + `title`「対象 0 体」（`batchLabel` の既存の形） |
   | 1-7 | 2 IPC で非原子 | 採用 | `commit_agent_drop` を新設して 1 回で永続化 |
   | 1-8 | 畳んだ区分けの非対称・挿入位置・Sortable の横取り | 採用 | 掴めない = 出すには表示へ戻す / 挿入は末尾 / 横取りは P2 で実測 |
   | 1-9 | スイッチが 2 箇所 | 採用 | 見出しだけ。`GroupDialog` は作成・改名・削除 |
   | 1-10 / 2-5 | グループの並びが未定義 | 採用 | `groups` の配列順（作成順）。並び替え UI は持たない |
   | 2-1a | 畳んだ区分けの個体が `order` の連結から漏れる | 採用 | 連結の材料は `state` から組んだ全区分け。単体で留める |
   | 2-2 | 無所属の見出しに目とスイッチは置けない | 採用 | ▶/■ + 体数だけ |
   | 2-3 | 隠れる辺の定義 | 採用 | 全辺 − 可視の辺。検収 2 を訂正 |
   | 2-7 | 引けない id の残り方が経路で割れる | 採用 | 次に所属を書く操作（select の保存 / 無所属の箱への drop・箱内の移動）で `None` へ正規化 |

7. **Sortable の共有グループを選んだ理由は index の数え方。** `oldIndex` / `newIndex` は
   `draggable` 選択子に一致する子だけを数えるので、1 本の配列に見出しを混ぜると
   `vue-draggable-plus` の splice 位置がずれる。**起票時の読みで、実測ではない** —
   P2 で 1 本の箱に見出しを混ぜる形を試して通るなら、そちらのほうが `holdReorder` が
   1 つで済む。**予測を先に書いてから確かめる**