yellowadmin/pp-qa-km
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: convert --verify 對帳 + 修復 CRLF 使 hash 失準 + raw/** .gitattributes #1

Merged
yellowadmin merged 2 commits from feat/convert-verify-reconcile into main 2026-07-23 02:27:47 +00:00
Conversation 0 Commits 2 Files Changed 4 +158 -4
yellowadmin commented 2026-07-23 00:33:34 +00:00
Owner
Copy Link

目的

convert 後檔案被手動刪除／就地改動時，提供正規的稽核與修復途徑；並修掉一個讓「還原後 re-hash 比對」在 Windows 失效的既有 bug。

變更

  • convert.py --verify（純唯讀對帳）：re-hash 全部登記檔、掃未登記檔，回報 missing / mismatch / unregistered，不一致以退出碼 1 表示（可當 CI／排程閘門）。converted/assets/* 與 .gitkeep 正確略過。
  • 修 CRLF 使 hash 失準：write_text 在 Windows 把 \n→\r\n，但登記的 SHA-256 算在 \n bytes 上 → 磁碟 bytes 與帳本永遠對不上（converted md + web 快照原始檔）。改為 write_bytes 寫入所登記的那份 bytes。
  • .gitattributes（raw/** -text）：core.autocrlf=true 下 checkout 會在 git 層重新引入 CRLF，抵銷上一項修復；關閉 raw 的換行正規化，把「登記 hash == 磁碟 bytes」不變式延伸到 git checkin/checkout。
  • selfcheck：補 clean / missing / mismatch / unregistered 四情境（全程唯讀斷言；clean 案例含未入帳本的 assets，順帶證明不誤報）。
  • AGENTS.md：新增 §14「raw 完整性與修復（對帳）」，並於 §1.4 補「登記 hash == 磁碟 bytes」不變式與 .gitattributes 機制。

驗證

.venv/Scripts/python.exe tools/convert/selfcheck.py → ALL PASS。

備註

--verify 是唯讀稽核工具，不改任何檔（含 manifest），符合 §7「lint 絕不擅自刪改」精神。修復決策（可衍生 vs 信任根、先 git restore 不改帳本、動 manifest 走 PR）詳見 AGENTS.md §14。

🤖 Generated with Claude Code

## 目的 `convert` 後檔案被手動刪除／就地改動時，提供正規的稽核與修復途徑；並修掉一個讓「還原後 re-hash 比對」在 Windows 失效的既有 bug。 ## 變更 - **`convert.py --verify`（純唯讀對帳）**：re-hash 全部登記檔、掃未登記檔，回報 missing / mismatch / unregistered，不一致以退出碼 1 表示（可當 CI／排程閘門）。`converted/assets/*` 與 `.gitkeep` 正確略過。 - **修 CRLF 使 hash 失準**：`write_text` 在 Windows 把 `\n`→`\r\n`，但登記的 SHA-256 算在 `\n` bytes 上 → 磁碟 bytes 與帳本永遠對不上（converted md + web 快照原始檔）。改為 `write_bytes` 寫入所登記的那份 bytes。 - **`.gitattributes`（`raw/** -text`）**：`core.autocrlf=true` 下 checkout 會在 git 層重新引入 CRLF，抵銷上一項修復；關閉 raw 的換行正規化，把「登記 hash == 磁碟 bytes」不變式延伸到 git checkin/checkout。 - **selfcheck**：補 clean / missing / mismatch / unregistered 四情境（全程唯讀斷言；clean 案例含未入帳本的 assets，順帶證明不誤報）。 - **AGENTS.md**：新增 §14「raw 完整性與修復（對帳）」，並於 §1.4 補「登記 hash == 磁碟 bytes」不變式與 `.gitattributes` 機制。 ## 驗證 `.venv/Scripts/python.exe tools/convert/selfcheck.py` → `ALL PASS`。 ## 備註 `--verify` 是唯讀稽核工具，不改任何檔（含 manifest），符合 §7「lint 絕不擅自刪改」精神。修復決策（可衍生 vs 信任根、先 `git restore` 不改帳本、動 manifest 走 PR）詳見 AGENTS.md §14。 🤖 Generated with [Claude Code](https://claude.com/claude-code)
yellowadmin added 2 commits 2026-07-23 00:33:34 +00:00
feat: convert 新增 --verify 對帳模式 + 修復 Windows CRLF 使 hash 失準 f9a0cd2369 
- convert.py --verify：純唯讀 re-hash 全部登記檔並掃未登記檔，
  報 missing/mismatch/unregistered，不一致退出碼 1（供刪除/竄改後稽核）
- 修 write_text 在 Windows 轉 \n→\r\n 使磁碟 bytes 與登記 SHA-256 不符
  （converted md 與 web 快照原始檔），改 write_bytes 寫入所登記的那份 bytes
- selfcheck 補 clean/missing/mismatch/unregistered 四情境（全程唯讀斷言）
- AGENTS.md §14 raw 完整性與修復流程 + §1.4 hash==磁碟 bytes 不變式

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
fix: 加 .gitattributes 對 raw/** 關閉換行正規化 d41cb49a45 
core.autocrlf=true 下，已 commit 的 raw/converted/*.md 於 Windows checkout
會被 git 轉成 CRLF，使磁碟 bytes 與 manifest 登記的 LF-hash 不符、--verify
誤報 mismatch——在 git 層抵銷了轉換器的 write_bytes 修復。以 `raw/** -text`
把「登記 hash == 磁碟 bytes」的不變式延伸到 git 的 checkin/checkout。
AGENTS.md §1.4 補記此機制。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
yellowadmin merged commit 356ae9367c into main 2026-07-23 02:27:47 +00:00
yellowadmin deleted branch feat/convert-verify-reconcile 2026-07-23 02:27:47 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
CLAUDE_AI yellowadmin
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: yellowadmin/pp-qa-km#1
Delete Branch "feat/convert-verify-reconcile"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?