docs(starpuff): T7-C 設計文件 SSOT 收斂——主題拆分、取代對照與 #871 漂移修正 - #880
Conversation
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a9029f09a6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| - **基礎星彈恆可通關**：混合星、變身、增益、精英與彩蛋全部是加成路徑，永不為破關必需。 | ||
| - **魔王關須有多種可行破關策略**（每王 ≥3 條，見 §58）。 | ||
| - **難度循序漸進，永不無限卡關**：關卡難度以分級 bot 勝率量化驗收（普通 ≥40%、熟練 ≥80%）。 |
There was a problem hiding this comment.
請勿把普通 ≥40%、熟練 ≥80% 宣告為所有關卡的跨檔硬不變式；這兩個數字目前只是 design/03-enemies-bosses.md §63 的 Noctra 調參結果，而真正的全域 SSOT src/game/logic/difficulty.ts 僅規定 EX 低階通過率 <20%、高階 ≥60%，level-audit.mjs 也沒有一般／熟練全關勝率閘。後續新增或調整任一關卡若依此索引驗收，就會套用不存在且與實作不一致的發布門檻；應限縮適用範圍，或先在難度 SSOT 與稽核 CLI 正式建立該門檻。
AGENTS.md reference: AGENTS.md:L148-L152
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
需 PM 裁決／follow-up docs PR
稽核 main@HEAD：GAME_DESIGN.md 硬不變式仍寫「普通 ≥40%、熟練 ≥80%」為跨檔恆成立。
Codex 指稱此口徑實為 Noctra 調參（design/03-enemies-bosses.md §63），全域 SSOT difficulty.ts 僅規定 EX 門檻。
建議： 限縮索引表述或移回 §63，避免維護者誤用。可併入 #876／docs follow-up。監控席保留 thread 至文件 PR 合併。
| - **基礎星彈恆可通關**：混合星、變身、增益、精英與彩蛋全部是加成路徑，永不為破關必需。 | ||
| - **魔王關須有多種可行破關策略**（每王 ≥3 條，見 §58）。 | ||
| - **難度循序漸進，永不無限卡關**：關卡難度以分級 bot 勝率量化驗收（普通 ≥40%、熟練 ≥80%）。 | ||
| - **telegraph 可讀性紅線 ≥600ms**：EX 差分只縮體不縮窗。 |
There was a problem hiding this comment.
請補上此紅線的適用範圍；目前寫成「跨檔恆成立」會涵蓋全遊戲 telegraph，但現行 SSOT 明確保留多個 500ms 前搖，例如 enemyFsm.ts 的 Splatta aimMs、Twinkla shimmerMs，以及 updraft.ts 的噴口預警。difficulty.ts 的 600ms 門檻實際由魔王稽核事實表使用，因此未限縮的索引會讓維護者誤判這些合法規格皆違反硬不變式；應明示為魔王／受稽核攻擊 telegraph，或同步調整既有機制與測試。
AGENTS.md reference: AGENTS.md:L148-L152
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
需 PM 裁決／follow-up docs PR
main@HEAD 仍將「telegraph ≥600ms」寫為跨檔恆成立，但 runtime 保留多處 500ms 前搖（Splatta/Twinkla/updraft 等）。
600ms 門檻實際用於魔王稽核（difficulty.ts 事實表）。建議索引限縮為「魔王招式」或列例外清單。
監控席保留 thread 至 docs follow-up（可併 #876）。
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1ea062990e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
審查收斂輪完成（必修 3 項＋Nits 4 項全數落地）commit 鏈 必修 1：取代標註方向反轉（採納 Grok 判斷）掃過全 10 個設計檔，統一成一條鐵律：主句永遠是現行規則，舊規則降級為獨立附註。 格式固定為（可 grep、已被守門機械化）： - 同系星彈 ≥3 且在地面時，按 SP 鍵點按立即變身；再按 SP 提前解除。
> **已廢止**（v19 起，現行見 §109.2）：地面長按吸入鍵 0.6s 觸發、再長按 0.6s 解除。共產生 35 條「已廢止」附註：01 檔 10 條、03 檔 7 條、02 檔 6 條、05／06 各 3 條、00／04 各 2 條、07／08 各 1 條。涵蓋 Sonnet 抽查清單全部（§4／§21／§23／§34／§36／§38／§40／§62／§70／§87／§89）並額外補到 §1／§3／§6／§7／§15／§30／§35／§44／§54／§57／§63／§68／§74／§77／§82／§95／§109／§112／§113／§118。 具體例（Grok 點名的 §57）：主句已從「地面長按吸入鍵 0.6s 觸發／再長按 0.6s 解除」改為「按 SP 鍵點按立即變身／再按 SP 提前解除」，舊規格移入附註。 同時把幾條方向相反的誤導一併修正：§60／§65 標題原本寫「已由 §65／§76 取代」，但兩席都同意其關卡列仍是現行規格——改為「下表 L8／L9（L10–L12）為現行關卡規格；當時的總數宣告已由 §84／§78 取代」。 紀律落點： 驗證： 必修 2：01 檔頭 — 選「收窄聲明」理由：SP 情境鍵的裁決
必修 3：守門腳本新增
掛載三路： 實跑輸出 守門上線即抓到真漏：我改了 §60／§65 標題卻忘了更新索引表，腳本第一次跑就擋下——正是你指出的失效模式，已修。 五種故障注入實證守門非空轉（皆 exit 1）：
另補 4 個 vitest 案（含負向案，確保規則語意不被誤放寬）： 一個自找的坑，誠實記錄：腳本自身含錨點偵測字面值，未入版控時 Nits（4/4）
驗證
002 記分行需要你裁決一件事聚合數字變了，原先的 +248 約定要更新：
rebase 順序仍等你裁決。未自行合併，等派複審。 |
複審收斂完成（HIGH 1 項＋MEDIUM 3 項，另評估並採納守門擴充建議）commit 鏈 必修 HIGH：§60 L8 hint 主句主句改為與 舊文案降級為已廢止附註。你的判斷完全正確——這句因為沒有帶任何取代標註，首輪的 sweep（找 必修 MEDIUM 1：
|
| 注入 | 輸出 |
|---|---|
| 綁定引述抄舊值（本次 HIGH 原始樣態） | 引述與 levels.ts 不符（逐字比對失敗）：「…地面長按吸入鍵 0.6 秒…」——文件抄了舊值或來源已改，請同步 |
| 無標記的過期抄寫（本次真漏網樣態） | 疑似過期的關卡 hint 引述：「…地面長按吸入鍵 0.6 秒…」——現行值為「…站在地面按 SP 鍵…」；若為刻意不同的文案請改寫，若是引述請加綁定標記 |
| 綁定指向不存在來源檔 | 引述綁定指向不存在的來源檔 nope.ts |
第二列就是這次漏掉的那句——現在守門抓得到了。
其他常數的評估（誠實說明未做的部分）
- 字串類（浮字、toast、UI 文案）：機制已通用，加標記即可納管，無需再寫程式碼。本輪先收了已知的 4 處。
- 數值類（HP 52、telegraph 720ms、難度門檻等）：本輪不做。這類值不是
「」引述，而是散在敘述句裡（「HP 52」「telegraph 0.72s」），要機械化就得解析 TS 物件字面值並在文件端建立「值 ↔ 欄位路徑」對映，成本比字串綁定高一個量級；而且數值漂移通常伴隨鄰近上下文一起變（像 §63.1 那張前後對照表），可讀性上比較容易被人眼發現。投入產出不成比例，如果 PM 認為值得，建議另開卡評估而不是塞進本 PR。
全閘門輸出
$ pnpm --filter @app/starpuff verify:docs
主題檔 9 個、章節 118 章、索引 118 列
設計文件守門通過：索引與章節一致、主句紀律成立、引述與 src 逐字相符、零錨點引用
$ pnpm --filter @app/starpuff test:run
Test Files 69 passed (69)
Tests 937 passed (937)
$ pnpm --filter @app/starpuff typecheck → tsc --noEmit 無輸出（綠）
$ pnpm --filter @app/starpuff lint → 綠（僅既有 react 版本 warning）
$ pnpm format → All matched files use Prettier code style!
$ git diff --stat origin/main...HEAD -- 'apps/*/src' → 空（零 src 變更）
pre-push 另跑全工作區 typecheck ＋ test ＋ build:ratewise。
002
本 PR 共 10 條（reward 8、penalty 0、neutral 2），淨 +8，檔頭 累計總分：+250（= main 基準 242 + 8）。
跨 PR 對帳更新：上一輪我報 +250 是「本 PR +5 與 #877 +3 的合計」；本輪我又加了 3 條 reward，所以數字再變：
- 本 PR 單獨：+8、累計 +250
- fix(starpuff): 生產站 commit 指紋根修＋存檔寫入失敗提示（#868）＋v14 驗證腳本 SSOT（#872） #877 單獨：+3
- 兩者都合併後的終值：+253（後合併者 rebase 時以此為準）
未自行合併，等派複審。
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 92305bedea
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| - 招池（**加權表驅動** `noctraMoveTable`，§111.1；telegraph 數值不變，P2 起另有主題招式 | ||
| 「蝕月斗篷」§111.3）： | ||
| - P1 `bomb（盤旋投彈 ×3，落點預警先行）`、`dive（俯衝：telegraph＋shake＋變色前搖 |
There was a problem hiding this comment.
當維護者依拆分後的現行 SSOT 調整或驗收 Noctra 時，這裡會要求 P1 每次投 3 顆，但 src/game/logic/noctraFsm.ts 的 NOCTRA.bombCountP1 明確為 2，noctraBombCount('p1') 與單測也以該值為準；3 顆僅是 P2/P3 的現值，照本文實作會無意提高 P1 壓力，因此應把此處改為 ×2。
AGENTS.md reference: AGENTS.md:L148-L152
Useful? React with 👍 / 👎.
| - P1 單體（總血 >66%）招池：`idle(1.5s)`、`晶柱衝擊（地面尖晶 ×3，落點預警 0.95s）`、 | ||
| `折射光束（橫掃一次，預示線 0.5s）` |
There was a problem hiding this comment.
在把本節作為加權選招 SSOT 使用時，這行把 idle(1.5s) 列成 P1 招池成員，但 prismixMoveTable('p1') 實際只回傳 pillar 與 beam，1.5 秒 idle 是每次選招前後的固定 FSM 節奏而非可抽中的招式；若後續依文件同步表格，會加入隨機空招並改變攻擊頻率，應把 idle 改述為固定招間等待而非招池項目。
AGENTS.md reference: AGENTS.md:L148-L152
Useful? React with 👍 / 👎.
- 建立 docs/starpuff-t7c-split 分支與隔離 worktree - 後續處理 GAME_DESIGN.md 拆分與 issue #871 文件漂移 測試：無（空 commit 活性錨，不含程式碼變更） Co-authored-by: Cursor <cursoragent@cursor.com>
- §62 慈悲補血改確定性 pity 參數表：受傷／低血雙門檻＋魔王 bossPityHurts=2，移除 35%／60% 擲骰 - 新增 §118 記載 sp-settings 單鍵 SSOT、統一設定頁、存檔備援 checksum 與 PWA 更新套用閘 - §9／§34／§35／§36／§38／§63.1／§70／§87／§89／§95／§101 舊敘述加註取代標記 - 三個 legacy 散鍵全檔不再作為現行規格敘述，僅保留為 migration 來源 - docs/dev/002 新增 reward 條目並更新記分行 測試：先讀 mercyHeal.ts／settings.ts／save.ts／pwaUpdateGate.ts 實作核對，prettier 3.8.1 格式通過；純文件變更未跑 vitest Co-authored-by: Cursor <cursoragent@cursor.com>
- 2436 行單檔按 §NN 邊界機械拆為 design/00-08 九個主題檔，各檔開頭聲明職責範圍與邊界 - 新增 design/99-superseded.md：取代對照表（權威索引）＋版本列車沿革＋已失效內容搬遷區 - GAME_DESIGN.md 改為索引入口——章號對照表、主題檔一覽、硬不變式；路徑不變故外部引用不斷 - 章號 §N 不重新編號（src 註解直接引用），索引表負責章號到檔案的解析 - §15 v2 直向配置表、§43 v6 攻略表、§30 空中疾衝規格三塊全失效內容移入歷史檔並留指路句 測試：逐章比對驗證 118 章零遺失（115 章逐字元相同、3 章為刻意搬遷且規格行全數落在歷史檔）， prettier 3.8.1 通過，全 repo grep 確認零錨點引用 Co-authored-by: Cursor <cursoragent@cursor.com>
- WALKTHROUGH 慈悲補血改述保底計數（非抽獎），補設定頁段落與 v21–v23 落後聲明 - README 修正變身觸發面（SP 鍵非長按）、補星暴 2.0、EX 五王 P4、設定頁與成就系統 - 大缺口不擅改：#874 魔王主題招式需真機實測、#875 六模組註解誤引 §5、#876 PRD 漂移待裁決 - 002 檔頭記分行改為本 PR 聚合淨變化（squash merge 對齊） 測試：以 mercyHeal.ts／transform.ts／settingsPage.ts／achievements.ts 核對每項敘述， prettier 3.8.1 通過；攻略打法未重測故不新增打法敘述，改以聲明標示落後範圍 Co-authored-by: Cursor <cursoragent@cursor.com>
- 依 AGT-VER-01 與 docs-only patch 先例補建 changeset，描述玩家可見的說明錯誤修正 - 002 新增 neutral 條目並更新記分行計數（reward 3、neutral 1，本 PR 淨 +3） 測試：prettier 3.8.1 通過；純文件與 changeset 變更，無行為影響故未跑 vitest Co-authored-by: Cursor <cursoragent@cursor.com>
- 全 10 個設計檔主句改寫為現行有效規則，舊規則降級為 35 條「已廢止」附註 - 99-superseded 新增「主句紀律」章立為鐵律，索引同步聲明，附註格式固定可 grep - 01 檔頭收窄職責為「輸入＋與輸入直接連動的彈匣／蓄能狀態機」並說明為何不拆 §109.3 - 02 檔頭加星暴指路（現行規格在 §109.3），§63.1 歷史表 60% 去粗體並標 v9 限定 - 99 補回 §43 原引導句；002 新增 reward 條目 測試：prettier 3.8.1 通過；grep 抽驗 854×480／HP 70／168±14／35%／60% 等舊值全數 仍保留於附註內未遺失；純文件變更未跑 vitest Co-authored-by: Cursor <cursoragent@cursor.com>
- 新增 scripts/verify-design-docs.mjs：索引存在性/檔名/零重複/零缺號/標題同步、 每檔職責聲明、主句紀律附註格式、全 repo 零錨點引用共六類檢查 - 同名 .test.mjs 掛進 vitest（include 增 scripts/**/*.test.mjs），另設 pnpm verify:docs - 守門上線即抓到我漏更的 §60/§65 索引標題，已同步修正 測試：pnpm --filter @app/starpuff test:run 69 檔 936 案全綠（新增 4 案）； 四種故障注入實證守門非空轉（漏登新章／索引指錯檔／重複章號／行內取代標註回歸）皆 exit 1 Co-authored-by: Cursor <cursoragent@cursor.com>
- 掃描器內含 GAME_DESIGN 錨點偵測字面值，入版控後被自己掃出三筆偽陽性 - 自身路徑改由 import.meta.url 推導後排除（非硬編，搬移改名仍成立） 測試：pnpm --filter @app/starpuff test:run 69 檔 936 案全綠； 另注入他檔錨點驗證自我排除未削弱偵測（07-art-audio-fx.md 仍被抓出） Co-authored-by: Cursor <cursoragent@cursor.com>
- 新增 neutral 條目記錄 verify-design-docs 自我檢舉偽陽性的成因與修法 - 檔頭記分行重算：本 PR 共 7 條（reward 5、penalty 0、neutral 2），淨 +5、累計 +247 測試：prettier 3.8.1 通過；純文件變更未跑 vitest Co-authored-by: Cursor <cursoragent@cursor.com>
- 主句改為與 levels.ts:613 逐字一致的「站在地面按 SP 鍵星化變身」並加綁定標記 - 舊文案「地面長按吸入鍵 0.6 秒」降級為已廢止附註 - 該句原本無取代標註，故首輪 sweep 與守門的行內標註規則皆掃不到 測試：verify-design-docs 通過；逐字比對 levels.ts hint 與文件引述一致；prettier 通過 Co-authored-by: Cursor <cursoragent@cursor.com>
- 02 檔頭不再宣稱 §23／§40 星暴敘述皆為歷史值——§23 主句已是現行的自動結晶＋SP - §50／§60／§65／§76 正文的「七／九／十二／十六節點單頁鋸齒」改為中性的新增節點敘述 - 舊佈局降級為已廢止附註（現行五區分頁見 §78）；§50／§76 補齊引導句與 §60／§65 同構 測試：verify-design-docs 通過；rg 確認正文零殘留節點總數宣告；prettier 通過 Co-authored-by: Cursor <cursoragent@cursor.com>
- INLINE_SUPERSESSION 補被動語態「已被」，負向測試改參數化鎖三式（已由／已於／已被） - 新增引述綁定：文件標註「引述」（`來源檔.ts` 說明）後守門逐字比對 src，抄舊值即失敗 - 新增 hint 近似網攔截無標註的過期抄寫（Dice bigram，門檻 0.5 依實測校準並以單測鎖住） - 四處既有程式碼字串引述（L8 hint、變身首教浮字、結晶／帶星 toast）全數補上綁定標記 測試：verify-design-docs 通過；三種故障注入皆 exit 1（綁定抄舊值／無標記過期抄寫／ 綁定指向不存在來源檔）；vitest 該檔 5 案全綠 Co-authored-by: Cursor <cursoragent@cursor.com>
- 校準註解改實測值：全量 218 筆引述、近似網實際受檢 200 筆，並註明綁定後受檢集最高 0.182 - §76 已廢止附註補回「854 寬間距 ≈51px 單頁可容納」與「20 節點單頁確定放不下」 - 門檻 0.5 與 0.558／0.412 兩側校準值不變，仍由單測鎖住 測試：verify-design-docs 通過；守門單測 5 案綠；數值 token 逐檔比對全 10 檔零規格值遺失 Co-authored-by: Cursor <cursoragent@cursor.com>
- 併入 main 對 §99 的 SHA 來源鏈修正（#877），依主句紀律改寫並移入 00-foundations - 002 條目雙方時間序全保留零刪除；檔頭重算為 reward 9／neutral 2、淨 +9、累計 +260 測試：002 六項驗算全通過（條目數／前綴計數／N=a-b／T=main 251+9／ID 唯一／零刪除） Co-authored-by: Cursor <cursoragent@cursor.com>
92305be to
d0001a1
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d0001a15f4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| > **已廢止**（v21 起，現行見 §111）：P1/P2 依固定循環出招（可背板）。 | ||
|
|
||
| - P1（HP > 50%）招池：`idle(1.2s) → jellyRain(5 顆拋物線彈) → idle → slam(跳起落地雙向地面震波) → idle → …` |
There was a problem hiding this comment.
當維護者依拆分後的現行 SSOT 調整 Jellord 時，這裡把 idle 列入 P1 招池並保留固定的 idle → jellyRain → idle → slam 次序，但 JELLORD_MOVES.p1 實際只會加權抽選 jellyRain 與 slam，idleMs 是每次攻擊之間的固定 FSM 等待；照本文同步會加入隨機空招或恢復可背板循環，應將此處改成兩招的加權招池，另述固定 1.2 秒招間等待。
AGENTS.md reference: AGENTS.md:L148-L152
Useful? React with 👍 / 👎.
| - P2（66-33%）：**潮汐入場**（phase 事件觸發 startTide，沿 §71 管線）；循環 | ||
| `熔糖滴落（天花板 ×4 預警光斑 0.7s → 直墜）→ 吟唱僵直 2.0s → 召喚 Bubbla（上限 2， | ||
| 雷化鏈電可中斷 §58 慣例）→ 噴泉加密 ×4 → …` | ||
| - P3（≤33%）：**大沸騰**（boilTide：潮汐週期 -30%、漲頂 +24px）；循環 | ||
| `全場糖漿波（邊緣起浪 0.9s → 單向橫越 250px/s，跳越可躲）→ 波後僵直 2.0s → |
There was a problem hiding this comment.
在以本節作為 Syrona 現行規格時，P2/P3 仍被寫成依箭頭順序執行的固定「循環」，但 syronaMoveTable 實際上會在 P2 加權抽選 drip／fountain／summon，並在 P3 加權抽選 wave／overload，每招之間才進入 idle；照這段實作會撤銷 v22 的隨機選招並重新產生可背板順序，應把兩段列為招池與各自的固定招間僵直。
AGENTS.md reference: AGENTS.md:L148-L152
Useful? React with 👍 / 👎.
| - **P1 王座戰（>70%）**：pull 重力牽引（漣漪 telegraph＋水平 positional drift | ||
| 110px/s 恆低於玩家全速）→ ring 星屑彈環 ×6 → claw 虛空爪擊（落點紫紋 0.6s、 | ||
| 鎖定不修正）；收爪僵直 2.5s 固定輸出窗。 |
There was a problem hiding this comment.
當維護者從 §82 重建或驗收 Voidra P1 時，這裡仍指定 pull → ring → claw 的固定次序且完全漏掉 siphon，但現行 voidraMoveTable('p1') 是 pull／ring／claw 各權重 3、siphon 權重 2 的加權招池；依本文同步會同時恢復已退場的固定循環並移除一般模式可遇到的星光虹吸，應改列完整四招與權重。
AGENTS.md reference: AGENTS.md:L148-L152
Useful? React with 👍 / 👎.
已合併 ✅merge commit 合併後 main 的 002 累計值：+260後續 PR（#883／#884／#857）的重算基準即為 251 → 260。 全檔 530 條、零重複 ID。 兩處微修
順帶做了一次全域數值 token 稽核（以反轉前的 Rebase 與 002 驗算rebase 至 衝突處理（禁 stash，全程未用）：
全閘門CI 全綠後才合併：Quality Checks pass（7m54s）、CodeQL ×3 pass、Dependency Review pass、E2E／Lighthouse 依 path filter skip。合併後在 main 上複跑 部署確認
沒有 deployment race——前一個 SHA 在我們成功後 1 秒才被標為 inactive，順序正確。本 PR 為純文件＋腳本，不需驗生產站行為，僅確認部署本身沒中斷： 給 #885 的補充資料（本輪未處理，依指示）Sonnet 找到的第二個同族案例 |
1 participant
摘要
T7-C 純文件任務。把 2436 行、118 章、靠「對舊章加取代標註」堆疊的
GAME_DESIGN.md拆成主題檔並建立取代對照 SSOT，同時修掉 issue #871 的兩處實作漂移。未碰任何src/**。GAME_DESIGN.md→docs/design/00-08九個主題檔 ＋99-superseded.md取代對照表拆分後結構
GAME_DESIGN.md路徑不變，改為索引入口（章號對照表＋主題檔一覽＋硬不變式），既有外部引用不會斷。design/00-foundations.mddesign/01-controls-input.mddesign/02-combat-star.mddesign/03-enemies-bosses.mddesign/04-levels-world.mddesign/05-save-settings.mddesign/06-ui-shell-pwa.mddesign/07-art-audio-fx.mddesign/08-safety-nets.mddesign/99-superseded.md每檔開頭都有「職責範圍／不在本檔」聲明，讀者不需要猜。
兩個關鍵設計決策
src/**有 60+ 處註解直接引用（例// 慈悲補血愛心決策（GAME_DESIGN §62…）），重編會全數失效。改由索引表負責「章號 → 檔案」解析，並在各檔頭與99-superseded.md明文立為紀律。99-superseded.md的取代對照表擔任權威索引——這才是「這段還算不算數」的單一查詢點。#871 漂移修正前後對照
漂移一 — 慈悲補血（§62）
logic/mercyHeal.ts）bossPityHurts=2／低血 15sexMaxPerLife=1§63.1 調參表與 §70 的 60% 敘述一併加註取代標記。
漂移二 — UserSettings（§38 等）
core/settings.ts）sp-muted／sp-rotation／sp-key-layout三散鍵為現行規格sp-settings單鍵 SSOT；三散鍵僅為一次性 migration 來源，落盤成功即刪除sp-save」sp-save與sp-save-backup（否則會自備援恢復舊進度）新增 §118 完整記載 T7-A 這批零文件的運行時功能：UserSettings SSOT、統一設定頁與震屏/減少動態偏好落地（
cameraFxGate）、存檔備援與 checksum、PWA 更新套用閘（順帶取代 §35「reload 蓋過暫停選單」的已知邊界敘述——該競態已被閘根治）。驗收標準 4 達成：全檔 grep 三個 legacy 鍵，殘留處皆已標註為 migration 來源或歷史敘述。
零內容遺失驗證
拆分以一次性腳本按
## N.邊界機械切割，並逐章比對拆分前後：3 章的差異是刻意搬遷，且腳本強制驗證「被移除的規格行（表格列與數值）必須逐字出現在
99-superseded.md」。另外拆分腳本本身也做過一次preamble + interstitial + sections重建與原檔的逐位元組比對。被刻意捨棄的只有原檔第 4 行那條把每個版本列車塞成一整段的「版本」巨型摘要——它是衍生內容且正是可讀性元兇；其分組資訊已改以
99-superseded.md的「版本列車沿革」表保留。錨點引用檢查（grep 證據）
全 repo 沒有任何指向
GAME_DESIGN.md的錨點連結——所有引用都是GAME_DESIGN §N形式，由索引表解析。索引完整性另以腳本驗證：其他文件交叉核對
直接修（小、可從實作直接核對）
WALKTHROUGH.md：慈悲補血「隨機出現」→ 保底計數並補實際門檻；新增設定頁段落；頁首加上 v21–v23 落後範圍聲明apps/starpuff/README.md：變身觸發面（長按吸入鍵 0.6 秒 → SP 鍵）、補星暴 2.0、EX 五王 P4、主選單「按鈕配置」→「設定」、成就系統、桌機 C 鍵開 issue（大或不在本 PR 可修範圍）
GAME_DESIGN §5（角色設定），應為 §111–§113src/**，本任務明令禁碰sp-rotation.claude/在.gitignore內，無法隨 PR 修正；且涉及規劃基準需 PM 裁決驗證
prettier --check .全綠（pre-commit 每 commit 執行）pnpm typecheck全綠、pnpm test全綠（pre-push 每 commit 執行；starpuff 932 案）git diff --stat origin/main...HEAD -- 'apps/*/src'為空 → 零src/**變更待 PM 裁決
不自行合併。另附 patch changeset（依
bfdf65585docs-only 先例），若 PM 認為純文件不應升版可直接刪除該檔。Made with Cursor