# flow-notation 記法仕様 v0.4

業務フローを **役割（行）× 時系列（列）** のスイムレーンとしてテキスト記述するための DSL。
ファイル拡張子は `.flow`、中身は **YAML** とする。このファイルが記法の唯一の正。

- v0.1 = 基本語彙（17種）
- v0.2 = 並行 `par` / 合流 `join` / `sla` / `on_overdue` / 外部連携の3値化 を追加

**v0.4.1（2026-08-25）** — 描画規約に**見出しの固定**と**ドラッグでの移動**を追加（§5.1）。
記法そのものは変わらない。

**v0.4（2026-08-23）** — 実ヒアリング（システム開発フロー）で見つかった4つの不足を補った：
`start` / `end` に **`id`**（§3.2）、**成果物の複数指定**（§4.6）、
分岐の枝が前の工程へ戻ることを示す **`back:`**（§3.3 / §3.4）、
補足を書く **`note:` / `notes:`**（§4.7）。

**v0.3（2026-08-20）** — **用語補足**を追加。`glossary:` に業務用語を定義し、
本文中で `[[用語]]` と書くと図の上でマウスオーバー説明（ツールチップ）が出る（§4.5 / §5.8）。

**v0.2 改訂（2026-08-20）** — 実フロー（自動車部品工場）での検証で判明した3点を反映：
条件分岐の遷移先キーを `yes`/`no` → **`then`/`else`** に改名（§3.3）、
並行バーの配置規定を追加（§2.1）、同一セル記述のガイドを追加（§2.2）。

---

## 1. トップレベル構造

```yaml
roles:      [役割, ...]          # 必須。行（レーン）。上から記述順に並ぶ
timeline:   [時点, ...]          # 必須。列。左から記述順に並ぶ
milestones: { 名前: 時点, ... }  # 任意。列上の縦線マーカー
sla:        { 名前: { span: [開始時点, 終了時点], limit: 期間 } }  # 任意(v0.2)
view:       AS-IS | TO-BE        # 任意。既定 AS-IS
glossary:   { 用語: 説明, ... }  # 任意(v0.3)。業務用語の補足（§4.5）
notes:      [補足, ...]          # 任意(v0.4)。図全体への補足（§4.7）
steps:      [ ... ]              # 必須。ノード/分岐/並行の並び（記述順）
```

- **役割** は文字列。末尾に `#社外` `#外部` を付けると社外/外部アクターとして描画する（背景・アイコンが変わる）。
- **時点** は自由文字列（`Day0` `月末` `+3営業日` `2026-04-01` など）。順序は `timeline` の並び順で決まる。
- `milestones` の時点が `timeline` に無い場合、並び順に沿って**間に挿入**される（厳密にしたい場合は `timeline` に含める）。

---

## 2. 配置モデル（座標＝セル）

**座標はピクセルではなく `(役割, 時点)` のペア。** 人間が場所を決め、機械は矢印だけを引く。

1. グリッド ＝ `roles`（行）× `timeline`（列）。
2. 各ステップの `at: [役割, 時点]` が **セル**を一意に決める。
3. **同一セルに複数ノード** → 記述順に縦積み。順序を固定したいときは `at: [役割, 時点, スロット番号]`（1始まり）。
4. マイルストーンは列位置に**縦線**（セルは占有しない）。
5. エッジ（矢印）は `from:` で結ぶ2ノードの**セル中心を自動接続**する。線の引き回しはレンダラ任せ。

### 2.1 分岐・並行・合流の配置（`at` を持たない要素の自動配置）

`cond` / `except` / `par` は `at: [役割, 時点]` を**書いてもよいが、省略できる**。省略時はレンダラが以下で一意に決める（`colHalf = COL_W/2`）：

| 要素 | 既定の配置 |
|------|-----------|
| `cond` / `except` | `from` ノードと**同じレーン**、その**半列右**（`x = colCenter(from) + colHalf`, `y = laneCenter(from)`） |
| `par`（並行開始バー） | `from` ノードの**半列右**に縦バー。`to:` の対象ノードが属する**レーン範囲をまたぐ**高さ |
| `join`（合流バー） | 合流ノード（`from` が配列のノード）の**半列左**に縦バー。合流元ノードのレーン範囲をまたぐ高さ |

- `at` を明示した場合はそれを優先する（自動配置より手動指定が勝つ）。
- 分岐/並行が連続して同じ半列位置に重なる場合は、後続を**さらに半列ずつ右**へずらす。

**列幅の下限（必須）** — 自動配置されたひし形は、前後のノードとの間に矢印が通る余白を必要とする。
隣接する2列のノードの間の余白は `COL_W − NODE_W` しかなく、そこにひし形（幅 `DIAMOND_W`）が入る。

```
片側の矢印の長さ = (COL_W − NODE_W − DIAMOND_W) / 2
```

既定値（`COL_W=250` / `NODE_W=150` / `DIAMOND_W=92`）では **片側 4px** しかなく、
**矢印が見えない**（線が引かれていないのと区別がつかない）。したがって：

> **`cond` / `except` を自動配置する図では `COL_W ≥ NODE_W + DIAMOND_W + 2×24 = 290`。既定は 300 とする。**

`COL_W = 300` なら片側 29px の矢印が確保でき、枝ラベルも置ける。分岐が無い図は 250 のままでよい。
横に伸びるのを避けたいときは、`COL_W` を広げる代わりに **`DIAMOND_W` を縮める**か、
`cond` に `at:` を与えて別の列へ逃がす。

**同列・逆行への対処（必須）** — バーは「`from` より右、かつ**すべての** `to` より左」に置けたときだけ、
すべての矢印が左→右に流れる。**分岐先が `from` と同じ列（またはより左）にあると、この条件を満たす x は存在しない**
（どこに置いても、いずれかの矢印が左向きになる）。したがって次のように扱う：

1. **書き方で回避するのが正**（推奨）。並行して始まる作業は `from` **より後ろの列**に置く。
   同じ日に始まるなら §2.2 のとおり**列の粒度を割る**（`Day1` → `Day1午前` / `Day1午後`）。
   時刻の正確さを保ったまま逆行がなくなる。
2. 記述を変えられない場合、レンダラは
   `x = colCenter(from) + colHalf`（既定）にバーを置き、**同列の `to` へは短いスタブで右辺から接続**する。
   さらに**逆行が生じた旨を生成物の本文に注記**する（§7）。図の中に警告色は足さない。
3. 位置を作為的に決めたいときは `par` に `at:` を明示する（手動指定が優先）。

> `join` も同様。合流元のいずれかが合流ノードと**同じ列以降**にある場合は、
> 合流ノードの列を1つ後ろへずらすか、列の粒度を割って解消する。

### 2.2 同一セルの詰まり回避（書き方ガイド）

業務行為（`act`）を**同じ `[役割, 時点]` に複数**置くと縦積みになる。1レーン（既定 172px）に収まるのは
「装飾つきノード1個」または「装飾なしノード2個」までで、**2個積むと成果物チップ・課題バンド・TO-BE が描けない**。

**書くときの指針：**

- **原則、1セル1ノード。** 連続する行為は別の時点（列）に置く。
- **同日に複数の行為が起きる場合**（現実には多い）は、`timeline` の粒度を上げて列を割るのが第一選択。
  例：`[Day1]` → `[Day1午前, Day1午後]`、`[月末]` → `[月末, 月末+1h]`。
  **時刻の正確さを保ったまま**、セルの詰まりを解消できる。
- どうしても同一セルに積む場合は `at: [役割, 時点, スロット番号]`（1始まり）で順序を固定する。
  このときレンダラは**装飾を省略してよい**（§5.7）。省略した内容は `.flow` に残るため情報は失われない。
- 3個以上の同一セル積みは**しない**（レーンに収まらない）。列を割ること。

### 2.3 マイルストーンとノード列の重なり

- マイルストーン（`milestones` / `milestone:`）の時点が既存の**列と一致**する場合、縦線はノードと重なる。**縦線は背面・低不透明度**で描き、ノードの可読性を優先する。

> スコープ外（初版で入れない）：矢印の自動配線最適化、サブフロー分割・参照、RACI。

---

## 3. ステップ種別

`steps:` の各要素は、含まれるキーで種別が決まる。

### 3.1 業務行為（`act`）

| キー | 必須 | 意味 |
|------|:---:|------|
| `id` | ○ | ステップ識別子（`from:` から参照される） |
| `at` | ○ | `[役割, 時点]`（＋任意でスロット番号） |
| `act` | ○ | 業務行為（「誰が〜する」の〜） |
| `from` | △ | 前ノードの `id`。配列で**合流**（§3.6） |
| `by` | △ | 手段（§4.1。人手/システム/外部 ＋ 手段名） |
| `artifact` | △ | 操作対象＝成果物（Excel / DB / PDF 等）。**リストで複数可**（§4.6・v0.4） |
| `op` | △ | 操作内容（行追加・レコード登録・帳票出力…）。`artifact` がリストなら共通値かリスト（§4.6） |
| `note` | △ | このステップへの補足。事実の注釈であり、課題（`issue`）ではない（§4.7・v0.4） |
| `time` | △ | 所要時間（`30分` `半日`） |
| `freq` | △ | 頻度（`月1回` `随時`） |
| `wait` | △ | このノードの前後に発生する待ち・滞留（`承認1営業日`） |
| `issue` | △ | 課題（⚠印＋内容） |
| `rework` | △ | 手戻り先の `id`（差戻し。点線で戻る） |
| `on_overdue` | △ | SLA超過タイマーedge（§4.3・v0.2） |
| `milestone` | △ | このノード完了で到達するマイルストーン名 |
| `tobe` | △ | TO-BE 改善案（破線ゴーストで併記） |
| `join` | △ | 合流の種別 `all`\|`any`（§3.6・v0.2） |

```yaml
- id: a1
  at: [営業部, 月末]
  act: 案件実績を集計する
  by: 人手/Excel手入力
  artifact: 実績Excel
  op: 行追加
  time: 30分
  freq: 月1回
  issue: 二重入力でミス
  tobe: RPAで自動集計
```

### 3.2 開始 / 終了（`start` / `end`）

```yaml
- start: 月次締め      # ラベル
  at: [営業部, 月初]
  trigger: 毎月1日/自動 # 任意：起動契機
- id: e1              # 任意(v0.4)：他のステップから参照するための識別子
  end: 入金消込へ
  at: [顧客#社外, +5営業日]
  from: a5
  view: 例外終了       # 任意：例外系の終了はこう明示（謝絶・失敗など）
```

**`id` を付ける理由（v0.4）** — `cond` の `then:` / `else:` や `except` の `ok:` / `ng:` から
終了ノードを指したいことがある。`id` が無いとラベルで参照するしかなく、
**同じラベルの終了が複数あると指せない**（「終了（見送り）」が2か所ある等）。
`id` があればラベルは重複してよい。参照は `id` を優先し、無ければラベルで解決する。

### 3.3 条件分岐（`cond`）

```yaml
- id: c1
  cond: 請求額>100万?
  from: a2
  then: a3         # 条件を満たすときの遷移先 id
  else: a4         # 満たさないときの遷移先 id
# 3分岐以上は case を使う
- id: c2
  cond: 種別は?
  from: x
  case: { 個人: p1, 法人: k1, その他: e1 }
```

**枝が前の工程へ戻るとき（`back:`・v0.4）**

分岐の枝が**前の工程に戻る**（やり直し・差し戻し）ことがある。記法上は通常の遷移と同じ形なので、
**戻りであることを明示**する：

```yaml
- id: c1b
  cond: 再提案でも合意しない?
  from: rp1
  then: e1        # 終了
  else: n4        # 見積もりへ戻る
  back: [else]    # ← else は「戻り」である
```

- `back:` には**枝の名前**（`then` / `else` / `case` のキー / `ok` / `ng`）をリストで書く。
- 指定された枝は、`rework:` と**同じ見た目**（赤い破線）で描く（§5.2）。
- ラベルには戻り先を添えてよい（例：「いいえ（見積もりへ戻る）」）。
- **`back` を書かないと、読み手は戻りだと分からない。** 前の列へ向かう枝には必ず付ける。

> **`yes` / `no` は使わない。** YAML では未引用の `yes` / `no` / `on` / `off` が**真偽値**として解釈され、
> キーが `true` / `false` に化けてしまう（v0.2 改訂前の仕様はこの問題を抱えていた）。
> 図には従来どおり「Yes / No」と描いてよい（§5.5）。記述キーだけが `then` / `else`。

### 3.4 例外・エラー分岐（`except`）

正常系から外れる分岐。赤いひし形で描く。

```yaml
- except: 反社/保証NG?
  from: n6
  ng: 謝絶(終了)   # 異常時の遷移先（id またはラベル）
  ok: n7           # 正常時の遷移先
```

`cond` と同じく **`back:`** が使える（§3.3）。検収NGで開発工程へ戻す場合など：

```yaml
- except: 実業務で運用できる?
  from: n13
  ok: n14
  ng: n12         # 開発へ戻ってやり直し
  back: [ng]
```

### 3.5 並行（`par`）— 同時に始める（v0.2）

1つの流れを複数の流れに**同時分岐**する。図では**「ここから並行」バー**で描く（§5.5）。

```yaml
- par: par1        # 並行ブロックの id
  from: n2         # どこから並行を始めるか
  to: [n4, n5]     # 同時開始するノード id（複数）
```

### 3.6 合流（`join`）— 待ち合わせて次へ（v0.2）

複数の前ノードを1つに**合流**する。業務行為ノードの `from:` を配列にし、`join:` で意味を指定。
図では**「合流」バー**で描く（§5.5）。

```yaml
- id: n6
  at: [審査部, Day3]
  from: [n4, n5]   # 複数の前ノード
  join: all        # all=両方完了で進む(AND・既定) / any=どれかで進む(OR)
  act: 審査結果を取りまとめる
```

---

## 4. 属性の詳細仕様

### 4.1 `by:`（手段 ＋ 人手/システム/外部の区分）

`by:` は **複合フィールド**。`/` で前後に分割する。

```
by: <区分>/<手段名>
```

- **区分**（前半）＝ `人手` | `システム` | `外部` の3値（v0.2 で `外部` を追加）。
  - `人手` → 👤、`システム` → 🖥、`外部` → 🔌（外部システム・API・通知）
- **手段名**（後半）＝ 自由文字列（`Excel手入力` `会計SaaS` `保証会社API` `メール承認`）。

```yaml
by: 人手/Excel手入力
by: システム/会計SaaS
by: 外部/保証会社API
```

### 4.2 `sla:`（期限・SLA）— v0.2

区間に対する時間制約。区間ブラケット＋バッジで描く。

```yaml
sla:
  保証審査: { span: [Day2, Day3], limit: 2営業日 }
```

### 4.3 `on_overdue:`（SLA超過タイマーedge）— v0.2

SLA を超過したときに発火する例外的な遷移。時計マーク付きの点線で描く。

```yaml
- id: n5
  ...
  on_overdue: -> 督促   # 超過時の遷移先（id またはラベル）
```

### 4.4 `issue:` の付与先

`issue:` は原則ノード（ステップ）に付ける。エッジに付けたい場合のみ、そのエッジを持つノードに `from: <id>` と併記して付与する。

---

### 4.5 `glossary:` と `[[用語]]`（用語補足）— v0.3

業務フロー図は、その業務を**知らない人**も読む。専門用語・略語・社内語をその場で確認できるようにする。

**定義（トップレベル `glossary:`）**

```yaml
glossary:
  EDI: 電子データ交換。企業間で受発注や出荷のデータを決まった形式でやり取りする仕組み
  内示: 確定前に示される見込みの注文数量。最終的な確定注文とは数量が変わることがある
  MES: { desc: 製造実行システム。設備や作業者から製造実績を集める仕組み, aka: [製造実行システム] }
```

- **短い形**：`用語: 説明文`（推奨）
- **詳しい形**：`用語: { desc: 説明文, aka: [別名, ...] }`
  `aka` は別名。本文で別名を書いても同じ説明に結び付く。
- 説明文は**1〜2文**。図の上に浮かぶので長すぎると読めない。

**参照（本文中で `[[用語]]`）**

`act` / `by` / `artifact` / `op` / `issue` / `wait` / `cond` / `tobe` など、**文字列を書けるところならどこでも**使える。

```yaml
act: 受注データを[[EDI]]で取り込む
by: システム/生産管理システム([[MRP]])
issue: "[[内示]]と確定数の突合を Excel で手作業している"   # ← 先頭に来るので引用符が必要
tobe: "[[MES]] で設備から実績を自動収集"
```

表示文字を変えたいときは `[[表示文字|用語]]` と書く（例：`[[段取り替え|段取り]]` → 「段取り替え」と表示し、用語「段取り」の説明を出す）。

> **注意（YAML の制約）** — 値の**先頭**が `[[` だと YAML がリスト開始と解釈して壊れる。
> **先頭に置くときは必ず引用符で囲む**（`issue: "[[内示]]と…"`）。文中に現れる分には引用符は要らない。

- `glossary:` に無い用語を `[[...]]` で参照したら、レンダラは**そのまま文字を出し、生成物の本文に注記**する（§7）。
- 用語は**使うところ全部に付けなくてよい**。1つの図の中で**最初に出るところだけ**にすると読みやすい。

### 4.6 成果物が複数あるとき（v0.4）

1つの行為で**複数の成果物**が同時に出ることがある（例：現状業務フロー・理想業務フロー・課題マッピングを
まとめて提出する）。`artifact:` は**リストで書ける**：

```yaml
# 操作内容が共通のとき
artifact: [現状業務フロー, 理想業務フロー, 課題マッピング]
op: 提出

# 成果物ごとに操作内容が違うとき（同じ長さのリストで対応させる）
artifact: [見積書, 議事録]
op:       [提示,   共有]
```

- 図では**成果物ごとにチップを1つ**描き、縦に並べる。1行に詰め込まない。
- 縦のスペースが足りないときは §5.7 の省略順に従う（2つ目以降のチップから省略し、注記する）。
- 3つを超えるなら、行為の分割を検討する（1つの行為で4つ以上の成果物が出るのは、たいてい粒度が粗い）。

### 4.7 補足（`note:` / `notes:`）— v0.4

**事実の注釈**を書く。課題（`issue`）とは別物なので混ぜない。

| 書く場所 | 用途 | 描画 |
|---------|------|------|
| ステップの `note:` | その行為への補足 | ノードの下に **ⓘ の中立色チップ**（灰〜青系。赤は使わない） |
| トップレベルの `notes:` | 図全体への補足 | 図の下の「**補足**」カードに箇条書き |

```yaml
notes:
  - 弊社はシステム開発までに2段階の発注を行っている

steps:
  - id: n5
    act: 第1回を発注するか判断する
    note: この時点では、システム開発まで行うかは判断しなくてよい
```

- **`note` は「課題」ではない。** 困りごとは `issue`、事実の補足は `note`。
  色も分ける（`issue` は赤、`note` は中立色）。
- 長い背景説明は `notes:`（全体）へ。ノードに長文を貼らない。

## 5. 描画規約（レンダラが守る）

`flow-visualize` はこの規約に従って `.flow` を HTML（インラインSVG）へ変換する。

### 5.1 レイアウト

- 上部に時系列ヘッダ、左に役割ラベル。レーン背景は交互色。社外/外部レーンは色を変える。
- グリッドのセル中心にノードを置く（§2）。

**見出しは固定する（必須）** — 業務フローは横にも縦にも伸びる。
スクロールすると「今どの役割の、いつの列を見ているのか」が分からなくなるため、
**時系列ヘッダは上に、役割ラベルは左に固定**し、**本体だけをスクロール**させる。

図は4つの領域に分ける。**座標系は共通**で、領域ごとに `viewBox` で切り出す。

| 領域 | 位置 | スクロール |
|------|------|-----------|
| 角 | 左上 | しない |
| 時系列ヘッダ | 上 | 本体の**横**スクロールに追従 |
| 役割ラベル | 左 | 本体の**縦**スクロールに追従 |
| 本体 | 右下 | **縦横ともスクロールする（唯一）** |

- レーンの背景色は**役割ラベル側と本体側の両方**に描く（左右で色が途切れないように）。
- 画面が狭いときは本体の高さに上限をかけ、図の外（ページ全体）を横スクロールさせない。

**掴んで動かせるようにする** — 大きい図はスクロールバー操作だけだと辛い。
本体は**左ドラッグでパン**できるようにする。ドラッグ中は既定の文字選択を抑止し、
カーソルを掴める形（`grab` / `grabbing`）にして、動かせることが分かるようにする。

**拡大・縮小できるようにする（必須）** — 列が増えるほど等倍では全体像がつかめない。
図の上に操作列（縮小 / 倍率＝押すと等倍に戻る / 拡大 / 幅に合わせる）を置き、
`Ctrl`（Mac は `⌘`）＋ホイール・トラックパッドのピンチでも変えられるようにする。
素のホイールはスクロールのまま残す。

- 4領域は座標系が共通なので、**各領域の表示サイズと役割ラベルの幅・時系列ヘッダの高さへ
  同じ倍率を掛ける**だけで、見出しと本体の対応は崩れない。`viewBox` は触らない。
- そのため各領域の `<svg>` には **`width` / `height` 属性を実寸で入れておく**（倍率計算の基準になる）。
- **倍率を変えた後に枠の位置を取り直す。** 役割ラベルの幅も一緒に伸びるため本体の左上が動く。
  取り直さないと、カーソル位置を基準にしたつもりの拡大がその移動ぶんだけずれる。
- 下限は「幅に合わせる」で**全体が1画面に収まる**値まで許す（例：0.15）。上限は 2.5 程度。
- 縮小時に枠の高さも縮むよう、枠の高さの上限は**時系列ヘッダを含めた高さ**で頭打ちにする。

### 5.2 種別ごとの見た目

| 要素 | 形 | 色（枠/背景） |
|------|----|--------------|
| 業務行為 | 角丸箱 | 青 `#2563eb` / `#eff6ff` |
| 開始・終了 | スタジアム（角丸端） | 灰 `#475569`（終了・入金は緑、例外終了は赤） |
| 条件分岐 | ひし形 | 黄 `#d97706` / `#fffbeb` |
| 例外分岐 | ひし形 | 赤 `#dc2626` / `#fef2f2` |
| 外部連携ノード | 角丸箱 | 水色 `#0891b2` / `#ecfeff` ＋🔌 |
| 並行開始 / 合流（`par`/`join`） | 同期バー（縦の太線）＋日本語ラベル（§5.5） | slate `#334155` |
| SLA 区間 | ブラケット＋バッジ | 青 `#2563eb` |
| マイルストーン | 縦の破線＋ラベル | 紫 `#7c3aed` ★ |
| 成果物・操作内容 | チップ | 緑 `#059669` / `#ecfdf5` |
| 手段 | ピル | 灰 `#f1f5f9` |
| 課題 | 赤帯/⚠ | 赤 `#dc2626` |
| 待ち・滞留 | ピル ⏳ | 橙 `#ea580c` |
| 手戻り（`rework:` / `back:` の枝） | 点線矢印 | 赤 `#dc2626` |
| 補足（`note:`） | チップ ⓘ | 青灰 `#64748b` / `#f8fafc` |
| on_overdue | 点線矢印 ⏰ | 琥珀 `#d97706` |
| TO-BE ゴースト | 破線箱 | 紫 `#7c3aed` |

### 5.3 マイルストーン★とテキストの扱い

- `milestone:` の★は、**そのノードの枠に接する角**に置く。ノードとチップの中間に浮かせると、
  どちらの節目か読めなくなる。
- ノードの外に置く補足文（`trigger` の説明など）は、**矢印と交差しない位置**に置く。
  交差しそうなら文を線の反対側へずらす。

### 5.4 アイコン

👤人手 / 🖥システム / 🔌外部 ・ ⏱所要時間 / ⏳待ち / ⚠課題 / ★マイルストーン / ⏰タイマー。

### 5.5 図中の文言は日本語（重要）

**図は業務担当者（非エンジニア）が読むもの。** `fork` / `join` のような専門語を図に出さない。
DSL のキー（`par` / `join: all`）は書き手向けの構文なので変えないが、**描画するラベルは下表の日本語に固定**する。

| 要素 | 図に描くラベル | 補足 |
|------|---------------|------|
| `par`（並行開始バー） | **ここから同時に進む** | バーの近くに縦書き/横書きで添える |
| `join: all` | **すべて終わったら次へ** | 既定。合流元が2つなら「両方終わったら次へ」でもよい |
| `join: any` | **どれか1つ終わったら次へ** | バーに「○」印を併記 |
| `cond` の分岐ラベル | **はい / いいえ**（または条件を短く言い換えた語） | 記述キーは `then` / `else`（§3.3） |
| `except` の分岐ラベル | **OK / NG**（または「正常 / 異常」） | |
| `sla` | **期限：〇〇** | 例「期限：2営業日」 |
| `on_overdue` | **⏰ 期限超過 → 〇〇** | |

- 凡例（§5.9）の項目名も同じ日本語を使う。
- 枝ラベルに説明を足して長くしない（置き場所が無くなる。§5.6）。
- 英字を出してよいのは、業務側が日常的に使う固有名詞（EDI・ASN・MRP 等）だけ。

### 5.6 分岐ラベルの位置（重要）

`cond` / `except` の枝ラベル（「はい」「いいえ」「合格」「不合格」）は、**分岐図形（ひし形）の
"出口の頂点" のすぐ外側**に置く。矢印の中点には置かない。

**理由：** 分岐の次のノードが隣の列にあると、ひし形と次のノードの隙間は数 px しかない
（`colCenter + colHalf` に置かれるひし形の右端と、次の列のノード左端が接するため）。
矢印の中点に置く方式ではラベルが入る余地が無く、離れた場所に浮いて**どちらの枝か読めなくなる**。

| ラベル | 置き場所 |
|-------|---------|
| 左へ抜ける枝 | ひし形の左下、**ノードとひし形の間の下側**の余白 |
| 右へ抜ける枝 | ひし形の右上〜右下の**すぐ外側**（次のノードに掛からない範囲） |
| 上／下へ抜ける枝 | その頂点の**真横**にずらして置く |

- ラベルは**短く**（§5.5 の語）。修飾語を足して長くしない（「はい（差異あり）」ではなく「はい」）。
- **枝の向きは「次のノードがどちらにあるか」で決める。** ひし形から見て左上のノードへ向かう枝のラベルは左上側に置く。
  出口の頂点だけを見て機械的に置くと、向きが逆になることがある。
- **枝の向きとラベルの向きを一致させる。** 左に抜ける枝のラベルを右側に置かない。
- 矢印そのものに重ねない。線から 6px 以上離す。

同じ考え方を、矢印に添える注記（「やり直し」「再検査へ」など）にも適用する。
線の上に重ねず、線の外側に置く（必要なら `text-anchor` を `end` にして左側へ逃がす）。

### 5.7 装飾の省略順（スペースが足りないとき）

同一セル積み（§2.2）などで縦のスペースが足りない場合、**次の順で省略**し、省略したことが分かる印を残す：

1. `artifact` が複数あるときは**2つ目以降のチップ**を省略（何件省略したかを注記に書く）
2. `tobe`（TO-BE ゴースト）を省略
3. `note` チップを省略
4. `artifact` / `op` チップを省略
5. `issue` バンドを**⚠バッジ**（ノード角の小さな印）に縮退
6. `wait` ピルを**⏳**アイコンのみに縮退

ノード本体（`act` と `by` の副行）は**省略しない**。省略した内容は `.flow` に残っているため情報は失われない。
省略が発生したら、生成物の本文に注記する（§7）。

> **部分的に切り詰めてはならない（重要）。** 省略は**項目単位**で行う。
> 文の途中で打ち切る・要約する・句点で切る、はすべて禁止。
> 課題文の後半が落ちると意味が変わる（「日報が紙。実績入力は翌朝まとめて」で切ると、
> 本当の問題である「実績がリアルタイムに見えない」が消える）。
> 長い文は**折り返して2行**にするほうが、切るより良い。

### 5.8 用語ツールチップの描画（v0.3）

`[[用語]]` は、次の3つをセットで用意する。**JavaScript が動かない環境でも意味が伝わること**を条件とする。

1. **見た目の合図** … 用語部分に**点線の下線**を引き、少し濃い色にする（`#1d4ed8` 目安）。
   マウスを乗せられることが分かるようにする。
2. **説明の表示** … マウスオーバーで説明を出す。SVG の該当要素に `<title>` を必ず入れる
   （ブラウザ標準のツールチップ。JS 不要・確実に動く）。
   加えて、見やすい吹き出しを出す小さなスクリプトを添えてもよい（外部依存なしで完結させる）。
3. **用語集カード** … 図の下に**その図で使った用語の一覧**を置く。
   マウスが使えない環境（印刷・スマホ）でも読めるようにするため、これは省略しない。

- 用語集カードは `glossary:` の**定義順**ではなく、**図に登場した順**に並べる。
- 図中で参照されていない `glossary:` の項目は、用語集カードに出さない（凡例と同じ考え方＝§5.9）。

### 5.9 凡例

図中に使われた要素だけの**凡例を自動生成**する。

### 5.10 補足カード（v0.4）

トップレベルの `notes:` があれば、図の下に「**補足**」カードを作り、箇条書きで並べる。
凡例と注記（§7）とは別のカードにする（役割が違うため）。`notes:` が無ければカードごと出さない。

---

## 6. 語彙一覧（v0.1 〜 v0.4）

| # | 分類 | 語彙 | DSL | 版 |
|---|------|------|-----|:--:|
| 1 | 軸 | 役割レーン | `roles` | 0.1 |
| 2 | 軸 | 時系列列 | `timeline` | 0.1 |
| 3 | 軸 | マイルストーン | `milestones` / `milestone:` | 0.1 |
| 4 | ノード | 開始/終了 | `start` / `end` | 0.1 |
| 5 | ノード | 業務行為 | `act` | 0.1 |
| 6 | ノード | 成果物 | `artifact` | 0.1 |
| 7 | ノード | 操作内容 | `op` | 0.1 |
| 8 | ノード | 条件分岐 | `cond` ＋ `then`/`else` | 0.1 |
| 9 | ノード | 例外分岐 | `except` | 0.1 |
| 10 | ノード | 課題 | `issue` | 0.1 |
| 11 | ノード | 待ち・滞留 | `wait` | 0.1 |
| 12 | エッジ | 矢印 | `from` | 0.1 |
| 13 | エッジ | 手段 | `by`（後半） | 0.1 |
| 14 | エッジ | 手戻り | `rework` | 0.1 |
| 15 | 属性 | 人手/システム | `by`（前半） | 0.1 |
| 16 | 属性 | 所要時間/頻度 | `time` / `freq` | 0.1 |
| 17 | 属性 | AS-IS/TO-BE | `view` / `tobe` | 0.1 |
| 18 | 制御 | 並行（同時に始める） | `par` | 0.2 |
| 19 | 制御 | 合流（待ち合わせて次へ） | `join: all\|any` | 0.2 |
| 20 | 属性 | 期限・SLA | `sla` | 0.2 |
| 21 | エッジ | SLA超過タイマー | `on_overdue` | 0.2 |
| 22 | 属性 | 外部連携（区分3値化） | `by: 外部/…` | 0.2 |

| 23 | 補足 | 用語集 | `glossary:` | 0.3 |
| 24 | 補足 | 用語参照（ツールチップ） | `[[用語]]` / `[[表示\|用語]]` | 0.3 |
| 25 | 制御 | 開始/終了の識別子 | `id:`（`start`/`end` に付与） | 0.4 |
| 26 | ノード | 成果物の複数指定 | `artifact: [A, B, C]` | 0.4 |
| 27 | エッジ | 枝が前の工程へ戻る | `back: [else]` / `back: [ng]` | 0.4 |
| 28 | 補足 | 注釈 | `note:` / `notes:` | 0.4 |

**見送り（初版で入れない）：** サブフロー参照 / 成果物の入出力方向（read/write）/ 版管理。

---

## 7. 生成物への注記

レンダラは、次のいずれかが起きたら生成物（HTML）の本文に**注記カード**を出す：

- 記法にないキー・未対応の指定があった（§1 の語彙表に無いもの）
- `[[用語]]` が `glossary:` に定義されていなかった（§4.5）
- 装飾を省略した（§5.7）
- 自動配置が逆行を招くため §2.1 の代替規則を適用した

注記は「どのノードで・何を・なぜ」を1行で書く。図そのものには警告色を混ぜない（凡例の意味と衝突するため）。

---

## 8. 完全な例

| ファイル | 内容 |
|---------|------|
| `examples/01-auto-parts-factory/` | 自動車部品工場の受注→出荷。ヒアリングから起こした実寸大の例。記法の語彙をひととおり含む（`.html` 付き） |

各フォルダには `シナリオ概要.md`、（ヒアリング由来なら）`ヒアリング時の会話.md`、`.flow`、`.html` を置く。
一覧は `examples/README.md`。