doc↔code 同步守門的覆蓋缺口：非 hint 字串與數值常數仍會靜默漂移

[s123104]

摘要

PR #880 建立了 doc↔code 同步守門（引述綁定逐字比對 ＋ hint 近似網），有效消滅了「文件抄寫關卡 hint 但實作已改」這類漂移。但覆蓋範圍僅限 LevelSpec.hint（9 條）與 4 處 opt-in 綁定的引述，其餘引述 src 常數的文件內容仍會靜默漂移。

背景與證據

這道守門的起因是一次真實漏網：04-levels-world.md 的 §60 L8 hint 主句寫著「地面長按吸入鍵 0.6 秒星化變身」，但 levels.ts:613 的實際值早已改為 SP 鍵。它沒有帶任何取代標註，所以既不在人工 sweep 的搜尋範圍（找 已由／已於／已被），也不被守門的行內標註規則涵蓋——是純粹的無標記過期抄寫。

複審席的故障注入證實缺口仍在：

注入：未綁定的錯誤 toast「星力結晶！長按 B 鍵引爆」
結果：verify:docs exit 0（漏）

影響

GAME_DESIGN 系列設計文件是接手者的 SSOT。無標記的過期抄寫比有標記的更危險——讀者沒有任何線索知道該去查證。目前只有 hint 這一類受保護，toast、技能浮字、UI 標籤、數值常數（HP、telegraph 時長、難度門檻）都在覆蓋範圍外。

範圍

分兩類，成本與作法不同：

A. 字串類（toast、技能浮字、UI 標籤） — 成本較低。複審席建議的方向是把「長引述強制綁定」寫成慣例並由守門執行，而非對短標籤做全面 exact-match（後者會誤傷「世界地圖」這類通用詞彙造成大量偽陽性）。需先盤點有多少處值得納管。

B. 數值常數（HP、telegraph、難度門檻） — 成本高一個量級。這類值不是「」引述而是散在敘述句裡，機械化需解析 TS 物件字面值並建立「值 ↔ 欄位路徑」對映。原作者評估後決定不做，理由是數值漂移通常伴隨鄰近上下文一起變、人眼較容易發現。此判斷需要在本卡重新評估是否成立。

待修的既有小瑕疵

scripts/verify-design-docs.mjs:30-31 的校準敘述寫「211 筆」，與現況計數（約 204 非廢止／218 含廢止）不符；「其餘 ≤0.20」也略大於實測的未綁定集合。門檻 0.5 的分離帶結論不受影響（實測 bound 0.412 vs stale 0.558），但註解數字應更新為實測值或改為「約 N」。

驗收標準

1. 決定 A 類的納管範圍與機制，實作後以故障注入證明能擋（至少涵蓋複審席用的錯誤 toast 樣態）
2. 重新評估 B 類是否值得做，結論寫進文件（做或不做都要有依據）
3. 慣例（哪些內容必須綁定、綁定格式）寫進 99-superseded.md 或貢獻指引，不能只存在於守門程式碼裡
4. 修正 verify-design-docs.mjs:30-31 的校準計數註解

[s123104]

第二個真實案例（PR #880 終態複審發現）

複審席獨立交叉比對全部設計文件的引號短句與 src 全部中文字面值後，找到一個與 §60 漏網結構同構的缺口：

apps/starpuff/docs/design/03-enemies-bosses.md:31 引述 bossRoom.ts 的 JUMP_HINT_TEXT（魔王前室反制提示），既無綁定標記，也不在 hint 近似網的覆蓋範圍（近似網僅涵蓋 LevelSpec.hint）。

故障注入實證：改動 src 中的該字串後，verify:docs 仍然綠燈。

這與 §60 L8 hint 是同一失效模式——文件抄寫了 src 常數，但沒有任何機制保證兩者同步。差別只在 §60 那次剛好被人眼發現，這一處還沒有。

對本卡的意義

兩個真實案例都落在 A 類（字串類），而且都是「魔王／關卡的玩家可見提示文字」這個族群。這強化了本卡的優先級判斷：A 類不是理論風險，是已經發生兩次的實際漂移來源。

建議 A 類的納管盤點從這個族群開始——玩家可見的提示／教學／toast 文字，這些既容易被文件引述，又容易在調整手感時被改動。

已知的兩處具體目標

1. 03-enemies-bosses.md:31 ↔ bossRoom.ts 的 JUMP_HINT_TEXT（本次發現）
2. 錯誤 toast「星力結晶！長按 B 鍵引爆」樣態（第二輪複審的故障注入用例，exit 0 漏掉）

[s123104]

實作提示：綁定機制是通用的，第一個案例不需改程式碼

PR #880 的作者補充了一個對本卡有用的資訊：

03-enemies-bosses.md:31 的 JUMP_HINT_TEXT 確實落在覆蓋缺口內（無綁定標記，且不屬 LevelSpec.hint 九條所以近似網不覆蓋）。但引述綁定機制本身是通用的——這一處只要在文件加上 （`bossRoom.ts` 跳越提示） 標記就會立刻納管，不需要動守門程式碼。

這把本卡的決策收斂得更清楚

真正需要裁決的不是「怎麼做」，而是範圍與策略：

1. opt-in 綁定的盤點與補標（低成本、立即可做）：找出所有引述 src 常數的文件位置，逐一加上綁定標記。機制已存在，純粹是盤點工作。
2. 近似網要不要從 LevelSpec.hint 擴大到其他字串常數集（需要設計決策）：擴大會提高自動偵測率，但也要為每個新來源集重新校準門檻、並評估偽陽性。這才是本卡真正的技術問題。

建議先做 1（能立刻消滅已知的兩個案例），再依 1 的盤點結果評估 2 是否值得——如果 opt-in 綁定就能覆蓋絕大多數，近似網的擴大可能不划算。