# CROSS_SESSION_COORDINATION.md — 兩條(及未來更多)Claude Code session 並行協作協議

> 本文件是方寸仙門**多 AI session 並行運作的中央協議**。任何新 session 啟動前先讀這份。**邏輯線(新機器 / 佐峰王 / 這條 chat)主導**,其他線遵此策略執行。

> **版本**:v1.0,2026-05-13 建立。

---

## 一、為什麼有這份文件

2026-05-13 同一天,方寸仙門 repo 上發生過**三次撞車**:

1. **M78 編號撞** — 美術線(舊機器)推 `93e3dad feat(ui): M75-M78 ink-wash theme`,佔了 M78。邏輯線(新機器)我已寫 M78-idle-pilot spec,只好改名 M79
2. **設計文檔刪除戰** — 邏輯線 `ff4781d` 刪 主框架_v0.* / 細節/*。美術線 `ca7d873` restore + 加 `設計文檔說明.md` 反對刪除
3. **`.bridge/prompts/M78-exec.txt` 雙方都新增** — 兩個 M78 內容衝突,merge 時兩邊都得讓

撞車原因:**兩個 Claude Code session 沒中央協議**,各自憑記憶判斷該動什麼。透過 git 同步是事後補救,事前要靠這份協議。

---

## 二、目前活躍的 session

| 線 | 機器 | hostname | git author | 對話歷史 |
|---|---|---|---|---|
| **邏輯線(主導)** | 新 MacBook Air | `zuofengwangdeMacBook-Air` | `佐峰王 <zuofengwang@...>` | 自 2026-05-13 上午起,Claude Opus 4.7 (1M context) |
| **美術線** | 舊 Mac mini | `duduyuAIdeMac-mini` | `賭賭魚AI <fengbot@...>` | 自 2026-05-12 起,Claude Opus 4.7 (1M context) |

**Co-author 標記**(所有 commit):
```
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
```

兩條都用同款 Claude 但**互不知道彼此狀態**(除非透過 git fetch 看 commit history)。

---

## 三、主導結構(2026-05-13 確立)

### 邏輯線(這條 chat)= 主導

**負責**:
- 寫 / 維護 `docs/` 內所有綜合性權威文檔(ARCHITECTURE.md / GAME_DESIGN.md / BALANCE_DESIGN.md / RELEASE_NOTES_v*.md / 本檔 / README.md)
- 寫 / 維護 `openspec/changes/M*/`(所有 milestone spec)
- 寫 / 維護 `AGENTS.md` / `CLAUDE.md` / `PROGRESS.md` / `REVIEW_QUEUE.md` / `CONVERSATION_DECISIONS.md`
- 跨 milestone 架構決策、衝突仲裁、設計鐵律新增
- 開新 milestone 號(避撞)
- 任何 `src/core/` / `src/store/` / `src/data/` / `src/save-system/` 邏輯改動
- 平衡數值校準(M62-M72 type)
- 測試框架擴充

### 美術線 = implementation arm,**可動任何內容但遵主導策略**

**可動範圍**:
- ✅ `src/renderer/styles/*.css` / `App.css` / 各 component `.css`(美術主場)
- ✅ `src/renderer/components/*.tsx`(只動 className / 結構微調,不動 state / logic / handlers)
- ✅ `src/renderer/styles/theme.css` 內 token 系統
- ✅ `src/i18n/locales/*.json` UI text 微調(同步三語)
- ✅ 美術相關的 `src/data/assets-manifest.ts`
- ✅ PNG / SVG / 字體素材
- ✅ 視覺相關 `openspec/changes/M<n>-<美術 milestone>/`(M75-M78 型)
- ✅ `src/renderer/components/QuestTracker.css` / 動畫 / hover 效果 等

**不可動範圍**(主導線專屬):
- ❌ `docs/` 內任何文件(寫新 doc 必先跟主導線溝通)
- ❌ `openspec/changes/M*/` 內非美術 milestone 的 spec
- ❌ `src/core/` 業務邏輯
- ❌ `src/store/` state / reducer / sub-store engine
- ❌ `src/data/` 內非 assets 相關(buildings / recipes / disciples-pool / dao-techs / quests / achievements 等)
- ❌ `src/save-system/migrations.ts`
- ❌ `src/main/` / `src/preload/` Electron 邊界
- ❌ `AGENTS.md` / `CLAUDE.md` / `PROGRESS.md`
- ❌ `package.json` / `package-lock.json` 改 deps(整體統籌由主導線)
- ❌ 平衡數值常數(`UPGRADE_RATE_MULTIPLIER` / `REALM_BREAKTHROUGH_EXP` 等)
- ❌ 主框架_v*.md / 細節/*.md(歷史層,保留只增不改)

**動到不可動範圍 → STOP + escalate via REVIEW_QUEUE.md**。

### 「動任何內容但遵策略」的意思

字面意義:美術線在**緊急 + 主導線無法即時回應**情境下,可越界動上述「不可動」範圍 — 但**必須**:
1. 在 commit message 內顯式聲明越界
2. 同 PR / commit 內 append `REVIEW_QUEUE.md` 條目讓主導線 audit
3. 跟主導線後續溝通(主導線可要求 revert / 修補)

**預設假設**:美術線 95% 時間在可動範圍內,越界是例外,要 noisy 記錄。

---

## 四、開機 SOP(每條 session 進入工作前)

不論哪條線,新 session / 新一天 / 同 session 切到新 milestone,**必須**先跑:

```bash
cd <repo>
git fetch origin main
git log --oneline HEAD..origin/main  # 看對方推了什麼
git log --oneline origin/main..HEAD  # 看我這邊已 commit 沒 push 的
git status --short                    # 看 working tree
```

如 `origin/main` 比 HEAD 新 → `git pull --rebase origin main`,處理任何 conflict。

接著按各自身份讀:

### 邏輯線(主導)開機

1. 讀 [PROGRESS.md](../PROGRESS.md) — 整體進度
2. 讀本檔(CROSS_SESSION_COORDINATION)— 確認沒新規則
3. 讀當前 milestone 的 `openspec/changes/M<n>/audit.md`(若存在)
4. 跑 `ls openspec/changes/` + `git log --oneline -20` 看美術線最近做了什麼
5. 確認在 [CODEX指揮編排計畫_v1.md](../CODEX指揮編排計畫_v1.md) §3 哪一步

### 美術線開機

1. 讀 [docs/GAME_DESIGN.md](GAME_DESIGN.md) §3 視覺 / 美學部分
2. 讀本檔(CROSS_SESSION_COORDINATION)— 確認沒新邊界
3. 讀當前美術 milestone proposal
4. 跑 `ls openspec/changes/M7*` / `M8*` 看主導線最近 milestone(避免動到他們的 spec 領域)
5. 確認當前美術任務在「可動範圍」內

---

## 五、開新 milestone 編號的協議

### 編號流程(避撞)

開新 milestone 前**強制**:

```bash
git fetch origin main

# 看 origin/main 最新 milestone 編號
ls openspec/changes/ | grep -E "^M[0-9]+" | sort -V | tail -5

# 同時看美術線最近 commit 提到的 milestone(可能 spec 還沒 push)
git log origin/main --oneline -10 | grep -oE "M[0-9]+"
```

**主導線**:取最新 milestone +1。

**美術線**:取最新 milestone +1 但若邏輯線最近有提及 M+1 或 M+2 規劃(看 REVIEW_QUEUE 或 PROGRESS.md 的「規劃中」段),跳到 +3。

### 慣例

- **邏輯 milestone** 用 single number:`M79-idle-pilot`、`M80-cloud-save`
- **美術 milestone** 用 single number 或 `-ui` suffix:`M78-theme-toggle-polish`、`M82-art-pass-3`
- **緊急 hotfix** 不用 milestone,直接 commit `fix: <desc>`

### 撞號處理

兩條同時開了同編號 → **後 push 者改名 +1**。先到先得 commit hash 為憑。

---

## 六、commit message 慣例

統一 conventional commits 風格:

| Type | 用途 | 例 |
|---|---|---|
| `feat(M<n>)` | 新 milestone | `feat(M79): idle pilot spec` |
| `feat(ui)` | 美術 / UX 整體調整(不限單一 milestone) | `feat(ui): M75-M78 ink-wash theme + light removal` |
| `fix(M<n>)` | bug 修(在 milestone 範圍內) | `fix(M74): add quest i18n locales` |
| `fix` | 通用 bug 修 | `fix: white screen on dev startup` |
| `chore(docs)` | 文件對齊 / 重整 / 刪除 | `chore(docs): align SoT to v1.1` |
| `docs` | 新 doc / 大幅補內容 | `docs: add ARCHITECTURE.md + GAME_DESIGN.md` |
| `refactor` | 不改行為,改結構 | `refactor: split sect.ts into 3 files` |
| `perf` | 性能優化 | `perf: memoize hot path in performance-analysis` |
| `test` | 只動 test | `test: add 8 cases for stacking-bonus` |
| `revert` | 撤銷 | `revert: undo ff4781d (restore design docs)` |
| `chore` | 其他維護 | `chore: bump tsconfig target` |

**所有 commit 必含 co-author trailer**:
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
```

---

## 七、衝突解決流程

### 情境 1:你 push 被 reject(對方有新 commit)

```bash
git fetch origin main
git log --oneline HEAD..origin/main  # 看對方新 commit
```

**判斷**:
- 對方 commit 跟你動的檔案**無交集** → `git pull --rebase origin main` 後 push
- 對方 commit 跟你動同檔案 → 看 §7 情境 2

### 情境 2:rebase 出現 conflict

```bash
git pull --rebase origin main
# CONFLICT (content) in <file>
```

**處理**:
- 看哪邊改的更實質。優先保留實質改動
- 雙方都實質改:**保留兩邊都的 intent**,人類介入合併

主導線可決定 force rebase + `git push --force-with-lease`(只在 commit hash 仍是對方那邊預期的最新時生效,**永遠不用 `--force` 裸版**)。

### 情境 3:你刪了對方在意的檔案(像 ff4781d → ca7d873)

對方 restore 是合法 reaction。主導線需:
1. 拉對方 restore 的 commit
2. 反思:該檔案真的該刪嗎?
3. 若 yes → 跟對方溝通(REVIEW_QUEUE 或本檔的「決策日誌」段)達共識,**第二次刪**
4. 若 no → 接受 restore + 更新 governance(像我 2026-05-13 已做)

### 情境 4:兩條同時佔同 milestone 編號

晚 push 者改名 +1(見 §5)。

### 情境 5:跨檔案的設計矛盾(spec A 跟 spec B 互斥)

REVIEW_QUEUE.md append blocking=yes 條目,**雙方 STOP 等主導線 verdict**。

---

## 八、共享 escalation channel

| Channel | 路徑 | 用途 | 規範 |
|---|---|---|---|
| A — REVIEW_QUEUE | `REVIEW_QUEUE.md` | async escalation | 兩線都 append `## REVIEW NEEDED — <ISO> — <linename> M<n>` 條目;主導線 verdict 寫 `**Verdict**:` |
| B — `ask-claude.sh` | `~/.codex/skills/claude-review/scripts/` | sync headless 純查詢 | 美術線僅在不確定動「邊界附近」內容時用 |
| C — `wake-orchestrator.sh` | 同上 | 戳進主導線 live chat | 每 milestone 上限 1 次,觸發後在 REVIEW_QUEUE append 對應條目 |
| D — 本檔「決策日誌」 | `docs/CROSS_SESSION_COORDINATION.md` §11 | 重大邊界 / 主導決定 永久紀錄 | 主導線寫,兩線都讀 |

---

## 九、文檔擁有權(整合後)

**主導線維護**(美術線**只讀**,改動需 escalate):
- `docs/ARCHITECTURE.md` / `docs/GAME_DESIGN.md` / `docs/BALANCE_DESIGN.md`
- `docs/RELEASE_NOTES_v*.md` / `docs/MANUAL_TEST_PLAYBOOK.md` / `docs/README.md`
- 本檔 `docs/CROSS_SESSION_COORDINATION.md`
- `AGENTS.md` / `CLAUDE.md` / `PROGRESS.md`
- `CONVERSATION_DECISIONS.md` / `REVIEW_QUEUE.md`(內主導線寫 verdict)
- `REMAINING_TASKS.md` / `CODEX指揮編排計畫_v1.md` / `STEAM_RELEASE.md`
- `HOWTO_RUN_M1.md`(已刪)、`HOWTO_RUN.md`(未來若補)
- `.bridge/` 內所有 doc(`SYSTEM_DEPENDENCY_MAP.md` / `NUMBERS_DESIGN.md` / `FLOW_STATE_DESIGN.md` 等)
- `openspec/changes/M*/proposal.md` + `design.md` + `specs/*` + `tasks.md` + `audit.md`
- `.bridge/prompts/M*-exec.txt`(主導線寫 prompt)

**美術線主寫,主導線審**(歷史美術 milestone):
- `openspec/changes/M75-M78/`(已 ship)及未來美術 milestone
- `.bridge/prompts/M75-M78-exec.txt`

**歷史層**(雙方都不改,只保留):
- `主框架設計_v0.1.md` ~ `v0.3.1.md`
- `細節/01-06_*.md`
- `設計文檔說明.md`
- `方寸仙門_設計文檔_v0.7.html`

**code 真實狀態**(雙方都可改,各自範圍內):
- `src/` 內各檔(依 §三 「可動範圍」表)
- `tests/` 對應檔
- `package.json`(deps 改動 主導線統籌)

---

## 十、未來新並行線怎麼加

若要再開第三條 / 第四條 session(例如「音效線」「平衡線」「敘事線」):

1. **必先讀本檔**
2. **在本檔 §二 註冊**:加 hostname + git author + role + 對話起點
3. **主導線批 PR**:新線提案 commit 範圍 + 不可動清單。主導線發 verdict
4. **commit message 加 line tag**:
   - 音效:`feat(audio)` / `fix(audio)`
   - 平衡:`balance(M<n>)`
   - 敘事:`narrative(M<n>)`
5. **共享同個 REVIEW_QUEUE**

**主導線數量**:始終 = 1(這條 chat)。其他都是 implementation arm。

---

## 十一、決策日誌(append-only,主導線寫)

### 2026-05-13 確立兩線主導結構(這條 chat 主導)

**背景**:三次撞車後使用者要求「文檔整合 由我們主導」。

**決策**:
1. 邏輯線(新機器 / 佐峰王 / 這條 chat)為主導
2. 美術線(舊機器 / 賭賭魚AI)為 implementation arm
3. 美術線**可動任何內容但遵主導策略**;預設只在 §三「可動範圍」內動,越界需 escalate

**理由**:過去 5 天美術線跑得很好(M75-M78 ink-wash 完整 ship),邏輯線同時推進 balance overhaul + 文檔結構。問題是中央協議缺失導致撞車。將主導集中在邏輯線(這條 chat 對話歷史最完整),美術線專注美術 + 必要時越界但要 noisy。

**生效**:本檔 commit 後立即生效。

### 2026-05-13 設計文檔保留為歷史層

**背景**:邏輯線 `ff4781d` 刪 主框架_v0.* + 細節/*。美術線 `ca7d873` restore + 加 `設計文檔說明.md` 反對。

**決策**:這批文檔**保留**,作為:
1. 歷史 audit trail(設計演進)
2. 後續 EA 後界階內容規劃參考
3. 新成員入門讀物

衝突時以當前 SoT(`docs/BALANCE_DESIGN.md` / `openspec/changes/M*/` / `src/data/`)為準。

**生效**:`7ed4f5d` 後。

### 2026-05-14 M80 Ship-Readiness Audit Iter2 — 16 OVERTURN 全採納

**背景**:2026-05-13 跑 M80 audit iter1(70 分)+ iter2(96 分),17 位專家提出 16 條 OVERTURN 提案(推翻 / 修正現有設計)。使用者 2026-05-14 review 後全採納。

**16 條 OVERTURN 決議**:

#### 強烈採納(7 條,設計重大改善)

| # | 提案 | 影響範圍 | timing |
|---|---|---|---|
| 1 | 🎮 M37 主線敘事「Boss 戰」→「5 個天劫關鍵時刻」整合 M49,6000 字 narrative 投到弟子 lore | M37 + M49 spec 重寫 | Patch 1 |
| 1A | 🎮 桌寵頭頂「待辦氣泡」(🟢收成/🟠招募/🟣突破/🔵新事件)→ 30 秒小循環核心 | M79 + 美術 + 邏輯線 | 立刻 |
| 2 | 🏗️ INITIAL_AUTO_FLAGS 重做:FTUE 完即自動 set 核心 auto-* = true,M79 master toggle | M79 spec + sect.ts | M79 |
| 5 | ⚖️ profile reframe:passive-only / auto-pilot-no-tut / auto-pilot-with-tut / optimal | balance/simulator | M79 配套 |
| 7 | 🔁 1 月「信封 letter」(代替 3 分鐘蒙太奇):動態生成內容 | retention 系統 | M84 |
| 8 | 🔊 BGM 4 條獨立 → 1 主旋律 + 12 时辰變奏 + 1 飛升($5,980 精算)| Audio 外包合約 | 立刻找音樂家 |
| 12 | ⚖️ EA 期完全本地,不接雲端(GDPR/CCPA 負擔 -90%)| 法務 + M55 stub | EA |

#### 採納(9 條)

| # | 提案 | timing / 注意 |
|---|---|---|
| 3 | 🎨 emoji → SVG icon set(game UI,60-80 icons)| ship 前完(noun project $200 或外包 $3200)|
| 3B | 🎨 Steam capsule「水墨 + 朱砂印章」辨識色 | W-6 trailer 之前 |
| 4 | 🖥️ 14 系統頁 → 6 主面板 + drawer | **EA 後 v1.2 做**(ship 前優先 a11y)|
| 6 | ✅ Beta 30 → 100 人 × 4 週 | W-7 ~ W-3 |
| 9 | 🌐 EN_GLOSSARY.md 命名約定 120+ idiom | i18n complete 前提,W-4 |
| 11 | 📣 EA $9.99(首發 -25% = $7.49)/ 1.0 $14.99 / 不收 DLC | Steam Pipe 設 |
| 14 | 💼 EA 路線(不直接 1.0)| 確定 |
| 16 | 🔒 save 不加密(接受 JSON 可看)+ Settings「編輯器模式」toggle + 作弊 achievement | Anti-cheat 注定失敗 |

#### 不採納(1 條)

| # | 提案 | 為什麼不採納 |
|---|---|---|
| 10 | 📦 不簽 macOS,接受 Gatekeeper | $99/年 投資 vs $500+/年 損失。Mac 玩家 ARPU 高 30%,**簽** |

**生效**:本檔 commit 後立即生效。所有後續 spec / docs / code 改動依此 16 條走。M80 audit-report-v2 為依據,本檔為決議 record。

**影響後續 milestone**:
- **M79 idle pilot**:必修 OVERTURN #1A + #2 + #5(原 spec 不夠完整)
- **M37 主線敘事**:整段 spec 重寫(Boss → 心境試煉,整合 M49)
- **M81 Audio**:外包合約按 OVERTURN #8 寫(1+12+1 BGM)
- **M82-M88**(待開):依 11 週 Critical Path

---

## 十二、相關文件

- [README.md](README.md) — docs/ 導航
- [ARCHITECTURE.md](ARCHITECTURE.md) — 技術架構權威
- [GAME_DESIGN.md](GAME_DESIGN.md) — 玩法設計權威
- [../AGENTS.md](../AGENTS.md) — Codex 規則 + SoT 階層(本檔由其引用)
- [../CLAUDE.md](../CLAUDE.md) — Orchestrator 守則
- [../PROGRESS.md](../PROGRESS.md) — milestone 進度
- [../REVIEW_QUEUE.md](../REVIEW_QUEUE.md) — 雙向 escalation queue
- [../CONVERSATION_DECISIONS.md](../CONVERSATION_DECISIONS.md) — 口頭決策翻譯