reviewer

SPEC-31 — Per-File Hash Diffing 架構分析報告

Agent: reviewer (reviewer)
Confidence: 65%
Cost: $0.4415
Duration: 1m 37s
Task ID: 0afa85af-818b-4e3c-a41f-17974515dc73

只有一個呼叫端，確認完畢。現在撰寫審查報告。

SPEC-31 — Per-File Hash Diffing 架構分析報告

概述

SPEC-31 修改品質良好，邏輯正確，測試覆蓋充分。核心改動是將 diffFingerprints() 的呼叫從 src/index.ts（呼叫端）內聯拉到 verifySoulIntegrity() 內部，簡化了呼叫端的使用方式，同時保持了向後相容性。

分析詳情

1. src/safety/soul-integrity.ts — 核心邏輯 ✅

改動：verifySoulIntegrity() 新增可選參數 storedFileHashes?: Record<string, string> | null（第 142 行），mismatch 時呼叫 diffFingerprints(storedFileHashes ?? null, fp)（第 174 行）。

  • 參數使用 ? 可選標記 + | null，完美相容三種情況：undefined（legacy 不傳）、null（明確無值）、Record（正常值）
  • diffFingerprints() 已正確匯出（第 197 行），可供外部使用也可供內部使用
  • diffFingerprints() 對 legacy fallback 處理正確：null/undefined/{} 都返回全部 CRITICAL_FILES（第 201 行）
  • 迴圈中對 !storedHash（第 210 行）的檢查處理了 stored hashes 缺少某個檔案 key 的邊界情況

結論：邏輯嚴謹，無問題。

2. src/index.ts — 呼叫端簡化 ✅

改動：Phase 1.6 從 9 行手動 diff 邏輯簡化為 2 行（第 136-137 行）。

  • 移除了 diffFingerprints 的 import（因為已內聚到 verifySoulIntegrity 內）
  • 移除了 mismatch 分支中重複的 computeSoulFingerprint() 呼叫（之前要呼叫兩次）
  • getFileHashes() 提前到呼叫前取得，直接傳入 — 合理且清晰
  • setFingerprint(fp.value.hash, fp.value.files)（第 159 行、第 191 行）兩處呼叫保持不變，與 vitals.ts 介面吻合

結論：減少了重複邏輯和冗餘 I/O，改善了可維護性。

3. tests/unit/soul-integrity.test.ts — 測試覆蓋 ✅

11 個新測試覆蓋場景：

# 場景 驗證
1-2 diffFingerprints legacy fallback（null / {}） ✅ 返回全部檔案
3 全部 hash 匹配 ✅ 空陣列
4 單檔案變動 ✅ 僅返回該檔案
5 多檔案變動 ✅ 返回正確子集
6 stored 中缺少某些檔案 ✅ 缺少的被視為「已變動」
7 first boot (null expected) ✅ valid=true
8 hash 匹配時的整合測試 ✅ valid=true
9 精確定位單檔案變動 ✅ 核心場景
10-11 legacy（不傳/傳 null storedFileHashes） ✅ 降級到全部
  • Mock 層級正確：mock node:fs/promises 的 readFile，非 mock 更底層或更上層
  • setupFileContents helper 簡潔實用
  • beforeEach 有 vi.clearAllMocks()，測試隔離充分

結論：測試質量高，場景覆蓋全面。

4. 跨檔案一致性驗證 ✅

  • verifySoulIntegrity 在整個 codebase 只有 src/index.ts:137 一個呼叫點 — 已正確更新
  • setFingerprint(hash, files) 簽名（vitals.ts:181）接受可選的 fileHashes — 與呼叫端一致
  • getFileHashes() 返回 Record<string, string> | null（vitals.ts:190-192）— 類型匹配
  • vitals.json 中的 identity_file_hashes 欄位已在 computeFileHash 的 strip list 中（第 75 行）— 避免循環 hash

風險評估

  • 🟢 低風險：改動範圍小且內聚，只觸及 3 個檔案
  • 🟢 低風險：向後相容性完整（storedFileHashes 可選，legacy 路徑有測試）
  • 🟢 低風險：無新外部依賴引入

驗收結論

所有驗收標準達成：

  • per-file hashes 存入 checkpoint
  • mismatch 精確報告變動檔案
  • legacy checkpoint 不 crash
  • unit test 覆蓋核心場景
  • tsgo --noEmit 通過
  • 全量測試通過

審查結果：✅ 通過

—HANDOFF—
TO: secretary
INTENT: handoff
ARTIFACT_TYPE: review
SUMMARY: SPEC-31 審查通過 — commit message 建議：feat(safety): SPEC-31 — per-file hash diffing in verifySoulIntegrity