PsychQuant · kiki830621 · Aug 12, 2026
diff --git a/docs/applescript-swift-parity.md b/docs/applescript-swift-parity.md
@@ -1,5 +1,11 @@
 # AppleScript–Swift Parity
 
+> 平台聲明
+> - 自動化／活應用程式層：macOS 專屬；狀態為 `design-only`，本文依據 2026-07 的 Excel for Mac 歷史觀察整理設計規則，當時的 macOS 與 Excel 精確版本未記錄，repository 內尚無真實應用程式驗收。
+> - Windows／Linux：AppleScript 與 Apple Events；狀態為 `not-supported`，COM／VSTO 或其他平台橋接須另案設計。
+> - 離線文件處理：不受本規則約束；能力狀態詞彙不適用，其跨平台狀態必須由各自文件聲明。
+> - 證據：PsychQuant/macdoc#135；標示規範見 `docs/platform-support.md`。
+
 一個關於「驅動活 App」類 MCP(che-excel-mcp 起)的設計規則。
 
 ---

diff --git a/docs/opc-zip-surgery.md b/docs/opc-zip-surgery.md
@@ -1,5 +1,11 @@
 # OPC ZIP 手術：VBA 注入與保真契約
 
+> 平台聲明
+> - 格式／離線層：跨平台的 OPC、ZIP 與 OOXML 設計契約；狀態為 `design-only`，#135 的產品實作與可重現測試尚未完成，因此不宣稱目前已有跨平台 runtime 支援。
+> - 自動化／活 Excel 層：macOS 與 Excel for Mac；狀態為 `design-only`，本文引用歷史現場觀察，精確的 macOS 與 Excel 版本未記錄，repository 內尚無真實 Excel 驗收。
+> - Windows／Linux 的活應用程式驗證：Excel 自動化；狀態為 `not-verified`，不由離線格式契約外推支援。
+> - 證據：PsychQuant/macdoc#135、#136、#138；標示規範見 `docs/platform-support.md`。
+
 > 狀態：#135 `che-excel-mcp` 離線 `inject_vba` 能力的設計依據
 >
 > 適用範圍：以受信任的 VBA carrier 將一般 `.xlsx` 轉為 `.xlsm`

diff --git a/docs/platform-support.md b/docs/platform-support.md
@@ -0,0 +1,94 @@
+# 文件與 issue 的平台聲明規範
+
+> 平台聲明
+> - 規範層：跨平台；能力狀態詞彙不適用，本文件只定義 macdoc 的平台標示規範，不自我認證產品能力。
+> - 執行環境：不適用；能力狀態詞彙不適用，本文件不宣稱任何產品能力已在 macOS、Windows 或 Linux 實作。
+> - 證據：PsychQuant/macdoc#139。
+
+平台標示的目的不是在文件頂端加上一個作業系統名稱，而是把「格式或協定本身的適用
+範圍」和「哪個執行環境真的有實作、測試證據」分開。像 OPC ZIP 是跨平台格式契約，
+AppleScript 驗收卻只可能在 macOS 上執行；兩者不能合併成一句「跨平台支援」。
+
+## 1. 文件宣告格式
+
+新增文件或實質修改既有文件時，應在第一個 H1 標題後立即加入引用區塊。文件同時涉及
+多個層次時，逐層列出，不可只用一個模糊的平台名稱概括：
+
+```markdown
+# 文件標題
+
+> 平台聲明
+> - 格式／離線層：跨平台；狀態為 `design-only`，實作與測試待 #123。
+> - 自動化／活應用程式層：macOS；狀態為 `verified`，已在 macOS 15.6、Excel 16.99 驗證。
+> - Windows／Linux 自動化：活應用程式橋接；狀態為 `not-verified`，本文件不宣稱支援。
+> - 證據：測試命令、報告或 issue 連結。
+```
+
+每一層至少要說明：
+
+1. 適用的平台或「不適用」。
+2. 下節定義的狀態。
+3. 作業系統、應用程式、runtime 與版本；不知道時要明寫「版本未記錄」，不可推測。
+4. 可重現的證據位置；只有歷史觀察時，要明寫「歷史證據」，且不得據此使用
+   `verified`。
+
+### 1.1 最小可檢查結構
+
+為了讓 review 可以用靜態檢查發現漏標，文件 block 採下列固定骨架：
+
+1. 第一行是 H1，第二行空白，第三行必須是 `> 平台聲明`。
+2. 每一個能力層引用列使用 `> - <層名>：<平台／範圍>；狀態為 \`<狀態>\`，<版本與限制>`。
+3. 最後至少有一列 `> - 證據：<可重現證據或明確的歷史證據>`。
+4. 不適用能力狀態的列，必須明寫「能力狀態詞彙不適用」，不可拿 runtime
+   狀態作文件成熟度標記。
+
+Review 至少要檢查 block 位置、狀態是否屬於下節集合、證據列是否存在，以及 issue labels
+是否與 body 的 `Platform Capability Status` 對應。第一版先把這些檢查列為 review gate；
+若後續文件量使人工 gate 不可靠，再新增 repository linter，不以 linter 尚未存在推論文件
+可以省略欄位。
+
+## 2. 狀態詞彙
+
+| 狀態 | 定義 | 可以主張的範圍 |
+|---|---|---|
+| `verified` | 在明列的平台與版本上有可重現測試或正式驗收報告 | 只限列出的環境與驗收面；歷史觀察本身不足以使用此狀態 |
+| `implemented-not-live-verified` | 已有實作與非活應用程式測試，但目前沒有真實應用程式驗收 | 不得寫成端到端已支援 |
+| `design-only` | 只有決策、規格或介面契約，尚未完成產品實作 | 不得寫成 runtime 能力 |
+| `not-verified` | 沒有足夠證據判定 | 不得由相近平台外推 |
+| `not-supported` | 刻意排除，實作應拒絕或另案處理 | 可明確說不在支援範圍 |
+
+「格式規則與作業系統無關」只代表該規則是跨平台的設計事實，不代表目前程式已在每個
+作業系統編譯、執行或通過整合測試。`verified` 也不會自動涵蓋未列出的應用程式版本。
+
+## 3. Issue 標籤
+
+Repository 使用下列可複選標籤：
+
+| 標籤 | 意義 |
+|---|---|
+| `platform:macos` | issue 含 macOS 專屬行為、實作或驗證範圍 |
+| `platform:windows` | issue 含 Windows 專屬行為、實作或驗證範圍 |
+| `platform:linux` | issue 含 Linux 專屬行為、實作或驗證範圍 |
+| `platform:cross` | issue 含不依賴作業系統的格式、規格或實作範圍 |
+
+標籤是索引，不是支援聲明。`platform:cross` 不等於「所有作業系統都已驗證」，而
+Windows 或 Linux 僅被列為未驗證時，也不應為了湊齊平台而加標籤。多層 issue 可以同時
+有 `platform:cross` 與 `platform:macos`；issue body 的 Current Status 或驗收條件仍須
+逐層寫明狀態與證據，並以 body 為準。
+
+## 4. 採用與回填
+
+1. 新增文件一律使用本規範。
+2. 既有文件在內容被實質修改時一併補上平台聲明。
+3. 與 #135、#136、#138 直接相關的 AppleScript 與 OPC 文件立即回填。
+4. 其餘歷史文件逐次整理，不以無語意差異的大量相同標頭取代逐份查證。
+5. 若實測環境改變，只更新有新證據的層次；舊證據仍可保留為有日期的歷史紀錄。
+
+## 5. Review checklist
+
+- [ ] 平台聲明位於第一個 H1 之後。
+- [ ] 格式／離線層與自動化／活應用程式層已分開。
+- [ ] 每一項都有狀態，版本未知時沒有自行推測。
+- [ ] `verified` 具有可重現的測試或正式驗收報告；歷史觀察只作設計證據。
+- [ ] `platform:*` 標籤與 issue body 的實際範圍一致。
+- [ ] 文件沒有把設計、格式相容性或單一平台測試擴張成全面 runtime 支援。