| name | concept-roundtrip |
| description | 對特定程式透過 Semorphe 管線執行目標性 round-trip 測試。 驗證：原始碼 → lift → SemanticTree → generate → 原始碼 → 執行 → 比較 stdout。 用於驗證特定概念、除錯已知失敗或回歸測試。支援任何語言。
|
| user-invocable | true |
語言指示：所有輸出文件（報告、摘要、註解）必須使用當前對話的語言撰寫。下方模板僅為結構參考，實際用語應配合使用者的語言設定。
⛔ 調用要求
此 skill 必須透過 Skill tool 調用，不可手動替代。當由 /concept.pipeline 編排時，pipeline 會使用 Skill tool 調用此 skill。
完成時必須輸出完成標記（見最後一節）。
概念 Round-Trip 測試
使用者輸入
$ARGUMENTS
參數可以是：
- 一段程式碼片段（內嵌或檔案路徑），語言從副檔名或語法推斷
{lang} {concept_name} 格式（例如 cpp if、python while_loop）{lang} {difficulty} 格式（例如 cpp easy、python hard）{lang} all 測試該語言所有支援的概念
背景
不同於 /concept.fuzz（使用資訊隔離的代理進行探索），此 skill 執行目標性的、感知實作的 round-trip 測試。你可以完整存取 Semorphe 的原始碼，並應利用這些知識來製作精確的測試案例，涵蓋特定的程式碼路徑。
前置作業
閱讀以下檔案以理解目前的管線：
src/core/types.ts — SemanticNode、ConceptId、所有型別定義src/languages/{lang}/core/blocks.json 和 src/languages/{lang}/std/*/blocks.json — 所有 block spec JSON 檔案（了解支援的概念）src/languages/{lang}/core/generators/ — 程式碼產生器（了解輸出格式）src/languages/{lang}/core/lifters/ — 提升器（了解輸入處理）src/core/projection/code-generator.ts — 主要的產生入口點src/core/lift/pattern-lifter.ts — 主要的提升入口點
工作流程
步驟一：決定測試範圍
根據 $ARGUMENTS，決定語言和要測試的程式：
如果是程式碼片段或檔案路徑：
- 直接使用提供的程式碼
- 從副檔名（
.cpp、.py、.java、.js）或語法推斷語言
如果是概念名稱：
- 產生 3-5 個代表性程式來練習該概念
- 包含該概念特有的邊界案例
如果是難度等級：
- 產生涵蓋對應 Topic 層級樹深度所有概念的程式
- easy：Topic 層級樹根節點的概念（如 var_declare、arithmetic、if、while_loop、print）
- medium：第一層分支的概念（如 func_def、func_call、count_loop、break、continue）
- hard：第二層以上分支的概念（如 array_declare、array_access 及語言特定的進階概念）
- 使用
getVisibleConcepts(topic, enabledBranches) 取得對應分支的可見概念集
如果是 all：
- 為每個支援的概念產生一個典範程式
- 再產生 3 個混合多個概念的組合程式
步驟二：執行原始程式
對每個測試程式，使用對應語言的工具鏈編譯/執行：
mkdir -p /tmp/semorphe-roundtrip/
timeout 5 {run_command} > /tmp/semorphe-roundtrip/test_{id}_expected.txt 2>&1
如果執行失敗，報告錯誤並跳過（測試程式本身無效）。
步驟三：執行 Semorphe 管線
建立 Node.js runner 腳本來執行 lift→generate round-trip。先閱讀專案既有的測試基礎設施，了解如何初始化該語言的管線：
grep -r "Lifter\|PatternLifter\|register" tests/ --include="*.ts" -l
然後建立並執行 round-trip 腳本：
npx tsx /tmp/semorphe-roundtrip/runner.ts
步驟四：執行產生的程式碼
對每個產生的檔案，用同樣的語言工具鏈編譯/執行，記錄 stdout。
步驟五：比較結果
對每個測試，執行三個層級的比較：
層級一 — Stdout 等價性（最重要）：
diff /tmp/semorphe-roundtrip/test_{id}_expected.txt /tmp/semorphe-roundtrip/test_{id}_actual.txt
層級二 — 語義樹完整性（P1 投影定理）：
- 將 SemanticTree dump 為 JSON
- 檢查沒有節點有
confidence: 'raw_code'（除非該概念確實不支援）
- 概念身分驗證（CONCEPT_IDENTITY）：對每個被測概念，斷言語義樹中存在對應的概念節點，且使用的是正確的 conceptId（而非退化到
var_declare 等通用概念）。此驗證防止 lifter 用錯誤概念但碰巧生成正確程式碼的假陽性。範例：
expect(gen).toContain('int* ptr = &x')
const ptrs = findConcepts(sem!, 'cpp_pointer_declare')
expect(ptrs.length).toBeGreaterThan(0)
expect(ptrs[0].properties.type).toBe('int')
- 二次 round-trip 驗證：對產生的程式碼再次 lift，比較兩次語義樹是否結構等價（節點類型、屬性、子節點結構相同），驗證 P1 可逆性
- 統計
raw_code/unresolved 節點佔總節點的比例
- 信心等級分布：統計語義樹中各信心等級的節點數量（
high/warning/inferred/raw_code）。如果有 composite pattern 匹配但 warning 為 0，標記為可疑（P1 §2.1 合規性警告）。在報告中輸出：
信心分布：high={N} | warning={N} | inferred={N} | raw_code={N}
層級三 — 多分支鷹架行為（P4 漸進式揭露）：
- 對同一個語義樹，使用不同的
enabledBranches 集合產生程式碼（例如只啟用根節點、啟用到第一層、啟用全部分支）
- 驗證各分支組合的輸出都能編譯/執行
- 驗證未啟用分支的概念不會出現在輸出中（鷹架正確隱藏）
- 比較各分支組合的 stdout 輸出（應該相同或等價）
層級四 — 層級轉換穩定性（§2.4）：
- 驗證 L₁ 可見概念在 L₂ 的呈現不變——只增不改
層級五 — 積木-程式碼一致性（§1.4 Sc4）：
- 積木行為和生成的程式碼一致——BlockSpec message 與 generator 輸出語義一致
層級六 — 程式碼結構比較（僅供參考）：
- 比較原始和產生的程式碼結構（不是精確文字 — 格式可能不同）
- 記錄任何顯著的結構差異
步驟六：分類並報告
分類每個測試結果：
| 結果 | 符號 | 意義 |
|---|
| PASS | ✅ | Stdout 匹配，乾淨的語義樹 |
| STDOUT_DIFF | ❌ | Stdout 不同 — 語義 bug |
| COMPILE_FAIL | ❌ | 產生的程式碼無法執行 — generator bug |
| LIFT_FAIL | ⚠️ | Lifter 當掉或產生 null 樹 |
| DEGRADED | 🟡 | 程式碼被降級為 raw_code — 覆蓋缺口 |
| SCAFFOLD_LEAK | ❌ | 低層級輸出包含高層級概念語法 — P4 違規 |
| ROUNDTRIP_DRIFT | ❌ | 二次 round-trip 語義樹結構不同 — P1 違規 |
| WRONG_CONCEPT | ❌ | 語義樹使用了錯誤的概念（如指標宣告用了 var_declare 而非 cpp_pointer_declare）— 概念身分違規 |
| TIMEOUT | ❌ | 產生的程式碼掛住 — 可能的無窮迴圈 |
| STRUCTURE_DIFF | 🔵 | Stdout 匹配但程式碼結構顯著不同 |
步驟七：輸出報告
將報告儲存到 tests/reports/roundtrip-{lang}-{concept|difficulty}-{timestamp}.md（目錄不存在時自行建立），同時印出摘要表格：
## Round-Trip 測試結果（{language}）
| # | 程式 | 概念 | 結果 | 細節 |
|---|------|------|------|------|
| 1 | basic_if | if, compare, print | ✅ PASS | |
| 2 | nested_loop | while_loop, count_loop | ❌ STDOUT_DIFF | 缺少遞增 |
摘要：8/10 PASS、1 STDOUT_DIFF、1 LIFT_FAIL
對每個失敗，包含：原始程式碼、語義樹、產生的程式碼、diff、根本原因假設。
步驟八：產生永久測試（必要）
所有測試案例都必須留存為可重複執行的 Vitest 測試檔，不可用完即丟。
- PASS 的測試：在
tests/integration/ 建立測試檔（檔名 roundtrip-{lang}-{concept}.test.ts），包含所有 PASS 的測試程式作為 round-trip 回歸測試。每個測試必須同時驗證：
- lift → generate → 再 lift 的語義樹結構等價性
- 概念身分（CONCEPT_IDENTITY）：語義樹中被測概念使用了正確的 conceptId，而非退化到通用概念（如
var_declare）。使用 findConcepts(sem, 'expected_concept_id') 斷言節點存在且屬性正確。
- 失敗的測試（❌）：同樣建立測試檔（檔名加
roundtrip- 前綴），但用 it.skip 或 it.todo 標記，附上失敗原因註解，待修復後啟用。
- Runner 腳本不可作為驗證手段：
/tmp/ 下的臨時 runner 僅用於探索性執行。最終驗證結果必須轉化為 Vitest 測試案例，確保 CI 可重複捕捉回歸。
- 如果目標概念已有測試檔（如
tests/integration/cmath-roundtrip.test.ts），將新案例追加到既有檔案中，避免重複建檔。
執行 npm test 確認新測試通過。
Bug 修復義務（強制）
發現 bug 就必須修復，或嚴格註記以確保後續必修。
- 能修的立刻修：根因已定位且修復不超出當前範疇的 bug，必須當場修復。修復後將
it.todo / it.skip 轉為正式 it(...) 測試並驗證通過。
- 不能立刻修的必須嚴格註記：必須在測試註解中寫明為什麼不能現在修和何時應該修，確保相關概念 pipeline 執行時回頭啟用。
- 測試檔不可少：任何被測試過的程式都必須有對應的永久測試案例，絕對不允許「發現問題但不留測試」。
- 零 todo 為目標：除有正當理由（依賴尚未實作的概念等），所有
it.todo 都應在當次修復。
快速模式
快速迭代時，對單一片段執行最小 round-trip：
/concept.roundtrip `int main() { int x = 5; if (x > 3) { cout << "yes"; } return 0; }`
/concept.roundtrip `print("hello" if True else "bye")`
跳過報告產生，直接顯示：PASS/FAIL + 如果失敗則顯示 diff。
設定
- 每個程式逾時：5 秒
- 暫存目錄：
/tmp/semorphe-roundtrip/
- 成功執行後清理暫存檔（失敗時保留以供除錯）
完成標記（強制）
此 skill 完成後，必須輸出以下格式的完成標記：
🏁 SKILL_COMPLETE: concept-roundtrip | {lang} | {target} | {N}/{M} PASS | 測試檔：{test_file_path}
如果未輸出此標記，pipeline 不會繼續下一階段。
