# Progress / Change Comprehension Example

User request:

> 請用 `/explain` 說明 Claude Code session「Gamified Japanese learning narrative engine redesign」最近 phase 3-5 到底改了什麼。

Output:

一句話：Phase 3-5 把「新遊戲怎麼開始」從舊的固定世界模板與補救規則，改成先生成一份世界規格，再由這份規格建立可玩的第二版遊戲存檔；同時把新的品質檢查大多先做成觀察報告，而不是立刻阻擋玩家遊玩。

## Evidence checked

- `docs/architecture/japanese-if-game.md`
- `changelog/2026-07-03-featjapaneseifgame-genesis-mainline.md`
- `.workflow/deductive-story-engine-redesign/phase-3-turn-loop-v2/state.json`
- `.workflow/deductive-story-engine-redesign/phase-3-turn-loop-v2/results/package-08-verification.md`
- `.workflow/deductive-story-engine-redesign/phase-4-evaluator-transition/state.json`
- `.workflow/deductive-story-engine-redesign/phase-4-evaluator-transition/results/package-18-verification.md`
- `.workflow/deductive-story-engine-redesign/phase-5-mainline-cleanup/state.json`
- `.workflow/deductive-story-engine-redesign/phase-5-mainline-cleanup/results/package-10-phase-5-exit-audit.md`

## What this is

這是一段「新遊戲產生方式」的替換工作。可以把它想成給 PM 看的 spec explanation：不用讀 code，也不用知道前面 30 輪 session 的所有細節，但要能看懂現在系統的形狀、資料怎麼流、哪些已完成、哪些只是觀察中。

舊方式不是一個正式叫做 `Profile Fallback Engine` 的產品概念，而是 docs 裡多個舊機制的合稱。它的意思是：新遊戲一開始不是先產生一份完整的新世界規格，而是依賴固定的世界設定、文字替換/修復規則，以及測試用的 deterministic 替代內容。白話說，就是「從一組預先寫好的世界形狀和補救規則開始」，所以不同 prompt 常會長得像同一種故事。

新方式在 docs 裡叫 Genesis mainline。它的意思是：新遊戲的正式入口現在會先產生一份世界規格，然後用這份規格建立可玩的第二版遊戲存檔。這份世界規格描述角色、物品、秘密、學習目標、故事節奏和檢查依據；負責建立存檔的後端流程再用它建立 version-2 save。

Phase 3 做的是：讓新世界規格真的能接到可玩的遊戲流程，並在每回合旁邊記錄一些 UI 看不到的檢查資料。Phase 4 做的是：用這些資料產生品質觀察報告，但先不拿來阻擋故事。Phase 5 做的是：把產品的 `/api/new-game` 入口清乾淨，確認它走新路徑；舊路徑只保留給測試、舊存檔修復、品質檢查輔助。

## Why it matters

原本舊的新遊戲流程容易讓不同遊戲長得太像，因為太多結構來自固定世界設定和補救規則。這次改動的重點是讓每一個新遊戲都從一份新生成的世界規格開始，包含自己的規則、角色、學習重點、隱藏真相、故事節奏和品質檢查依據。

但這不代表所有品質檢查都已經變成正式阻擋規則。文件明確保留一個邊界：新遊戲主路徑已經切到「先生成世界規格」的新方式；一些品質檢查，例如故事是否洩漏秘密、角色是否連續、日文學習負荷是否合理，目前多數仍是先記錄和觀察，不直接阻擋玩家。

## Concept model

這裡有三層概念：

- 產品入口：玩家按「新遊戲」時，`/api/new-game` 現在走「先生成世界規格」的新路徑。
- 世界規格：系統先產生一份 UI 看不到的 `worldFile`，作為新遊戲的來源。
- 可玩存檔與檢查資料：後端流程用 `worldFile` 建出第二版遊戲存檔；每回合另外寫入 UI 看不到的檢查資料，給品質檢查產生觀察報告。

```mermaid
classDiagram
  class PlayerUI {
    starts new game
    reads public save DTO
  }

  class NewGameRoute {
    POST /api/new-game
    product entry point
  }

  class OldWorldTemplatePath {
    fixed world profiles
    projection and repair rules
    deterministic fixture fallback
  }

  class GeneratedWorldSpec {
    generated world rules
    entities and items
    secrets and pacing
    learning charter
  }

  class Version2GameSave {
    playable save
    public world shell
    private worldFile
  }

  class HiddenTurnCheckData {
    per-turn declarations
    evidence for later checks
    hidden from UI DTO
  }

  class QualityObservationReports {
    advisory findings
    not enforced yet
  }

  PlayerUI --> NewGameRoute
  NewGameRoute --> GeneratedWorldSpec
  GeneratedWorldSpec --> Version2GameSave
  Version2GameSave --> PlayerUI
  Version2GameSave --> HiddenTurnCheckData
  HiddenTurnCheckData --> QualityObservationReports
  OldWorldTemplatePath ..> QualityObservationReports : fixture / legacy repair only
```

幾個文件裡的原詞，翻成責任會比較清楚：

| 文件裡的詞 | 這裡怎麼理解 |
|---|---|
| `world profile` | 舊系統用來決定故事世界長相的固定世界設定 |
| `fallback` / `fixture fallback` | Codex 或 live generation 不跑時，用 deterministic 測試內容替代 |
| `Genesis world file` | 新系統先生成的世界規格，是新遊戲的來源 |
| `version-2 save` | 用世界規格建出的新格式可玩存檔 |
| `private evidence` / `private lanes` | 寫在 raw save 裡、UI 看不到、給後續品質檢查用的資料 |
| `shadow` / `advisory` | 只記錄問題，不改玩家體驗，也不阻擋回合 |

## Mechanism

玩家按新遊戲時，資料流大致是這樣：

```mermaid
sequenceDiagram
  participant U as Player UI
  participant R as /api/new-game route
  participant G as World spec generator
  participant S as Save creation flow
  participant W as Story turn generator
  participant E as Quality reports

  U->>R: request new game
  R->>G: create and validate world file
  G-->>R: generated world file
  R->>S: create version-2 playable save
  S->>W: ask for first story turn using current writer schema
  W-->>S: first turn plus private declarations, if present
  S->>S: store playable save and hidden check data
  S-->>U: return sanitized save DTO
  E->>S: read hidden check data later
  E-->>E: produce observation reports, not player-blocking gates
```

這個流程有兩個重要邊界：

- UI 邊界：UI 仍然只讀整理過的 save DTO，不直接看到完整 `worldFile` 或 UI 看不到的檢查資料。
- enforcement 邊界：Phase 4 的新品質檢查多數只產生報告，不會直接讓故事回合失敗。

## Boundaries / not included

這個 section 的目的不是挑毛病，而是把概念框清楚：這次 work 到底交付了什麼，以及哪些讀者可能會誤以為已經有、但文件裡沒有證明已經完成的東西。

| 讀者可能以為 | 實際邊界 | 為什麼重要 |
|---|---|---|
| 新路徑等於已經有一套可讓 PM 選擇的預設世界模組庫 | 我沒有在 checked evidence 看到這次交付包含「可選擇的預設世界模組庫」。這次交付的主軸是：新遊戲入口先生成世界規格，再用它建立存檔。 | 否則容易把「生成一份世界規格」誤解成「產品已經有一組可管理、可挑選、可重用的世界模組」。 |
| 生成世界規格後，系統就能自動保證無限劇情延伸 | 文件沒有把這次 work 定義成「無限劇情延伸」能力。它比較接近：讓遊戲從更完整的世界規格開始，並留下檢查資料，方便後續驗證長線一致性。 | 世界規格提供故事延伸的基礎，但長線品質仍需要 live multi-world / 50-turn 之類的證據來證明。 |
| Phase 4 的品質檢查已經會正式阻擋壞故事 | 多數新的品質檢查目前是 observation/advisory：記錄問題、產生報告，不一定阻擋玩家回合。 | 這影響 PM 對「已上線品質保證」的理解；現在比較像先建立儀表與證據，不是所有規則都已 enforce。 |
| 舊的固定世界模板與 fallback 模組已經全部刪掉 | Phase 5 的重點是讓 public `/api/new-game` 不再走舊路徑；舊 modules 仍保留在 fixture、evaluator、legacy repair 等用途。 | 這避免把「產品主路徑切換」誤解成「所有 legacy code 都消失」。 |
| 舊存檔已經正式 sunset | checked evidence 沒有顯示這次完成舊存檔 sunset。文件反而保留 legacy repair 相關定位。 | 新遊戲入口變新，不代表既有玩家存檔的生命週期已經被關閉。 |
| mock matrix 或 package green 等於玩家體驗已完全證明 | 文件明確提醒 mock matrix 不能等同 live player-facing 品質；multi-world live 50-turn clean probe 仍是 follow-up。 | 測試結果能證明某些機制可跑，但還不能直接證明所有真實玩家路徑都穩。 |

## Status table

| Phase | 白話目標 | 現在狀態 | 不能過度解讀的地方 |
|---|---|---|---|
| Phase 3 | 讓新世界規格接到可玩的遊戲流程，並記錄每回合檢查資料 | Package 08 closed；route-based 20/50-turn locked-room evidence 在 current code 下 green | live multi-world 50-turn 仍是 follow-up；曾發生 active-save incident，已保存 evidence 並刪除 polluted save |
| Phase 4 | 建立品質觀察報告，判斷新檢查訊號是否可靠 | Package 18 completed；目前可玩的主流程可繼續前進 | 一些新檢查還不能變成正式阻擋規則，例如秘密洩漏、故事承諾、角色連續性、日文學習負荷 |
| Phase 5 | 清理產品入口，避免舊路徑還藏在 `/api/new-game` | Package 10 exit-ready；`/api/new-game` 是 Genesis-only | 舊 modules 還存在，但定位是 fixture/evaluator/repair，不是 public new-game engine |

## Worked example

如果 Marcus 今天打開網站按「新遊戲」，期望不是從一個固定的舊世界模板開局。現在 public route 會先產生世界規格，再把它變成第二版遊戲存檔，最後把第一回合和整理過的 save DTO 回給 UI。

同一回合背後會多出 UI 看不到的檢查資料。例如故事產生器可能宣告「這回合提到了哪個秘密、改變了哪個持久狀態、用了哪個物品」。後端流程會把這些宣告存在 raw save。品質檢查之後可以檢查「可見的日文文字是否真的支持這些宣告」。但如果品質檢查找到問題，現階段大多只是寫進觀察報告，不會直接擋住玩家回合。

## What to notice

- 這段 work 的主軸是替換新遊戲入口，不是把所有 evaluator 都升級成正式 gate。
- 舊系統的問題不是「不能產生故事」，而是太多故事結構來自固定世界設定和補救規則，容易長得像。
- 新系統的核心是 `世界規格 -> 第二版遊戲存檔 -> UI 可讀的 save DTO`，這是最應該記住的架構。
- Phase 4 的結果是「可以繼續用新的新遊戲主流程」，不是「所有觀察中的品質檢查都可以變成正式阻擋規則」。
- mock matrix 分數不能等同 live player-facing 品質；文件特別提醒 multi-world live 50-turn clean probe 還不是已完成證據。