Area External Exit Policy

這份文件整理新 AREA 接回既有世界時的 external exit 規則，目標是避免 map.md spec、生成出的 .roo、既有 boundary room 與 area/directory.lst 各自講各話。

總覽仍以 AREA 開發手冊 為準；這份文件專注在 external exit 的表示方式、雙邊同步責任與最小驗證要求。

What Counts As An External Exit

當某個出口要接到「本次 spec 之外、但 repo 內已存在的既有房號」時，這就是 external exit。

常見情境：

要分清楚兩種情況：

Spec Representation

對既有房號的合法 external exit，應在 mapmd-json 上標示 external: true。

意義：

不要做的事：

Synchronization Contract

一個新 area 若要正式接回既有世界，預設要同步三個面向：

  1. 新 area 的 spec 與 runtime 檔
  2. 既有 boundary room 的 .roo
  3. area/directory.lst

如果只改了其中一側，就容易出現：

Bidirectional Rule

預設 external exit 應為可來回的成對出口。

若要做例外，必須明講原因：

若 runtime intent 就是單向，應在 spec 中明確標示 one_way 或等價意圖，不要只是漏補 reverse exit。

判讀方式如下：

Integration Sequence

建議順序：

  1. 先在單區 plan 固定 external_links
  2. 在 mapmd-json 寫出 external exit
  3. 先跑 --validate-only
  4. 生成 .roo
  5. patch 既有 boundary room
  6. 掛入 area/directory.lst
  7. 做 loader / smoke test

Validation Requirements

至少檢查：

若這輪做了 boundary room patch，成功訊號不能只看 generator；仍必須看 loader 與 run log。

Naming And Documentation Rule

在單區 plan 裡，external_links 應至少寫清楚：

若只寫「接洛陽」而沒寫房號與方向，對後續維護幾乎沒有幫助。

Common Failure Patterns

常見失誤：

Relationship To Other Docs