refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件)

[kiki830621]

Problem

Original text:
「B，那些應該要是套件才對」
— Source: Claude Code session 2026-04-17, idd-implement #77 途中觸發 scope guard

macdoc .gitignore L20-21 註解寫道：

# Local packages & MCP (separate git repos)
packages/

但實際狀態：

Package	.gitignore 白名單	獨立 .git	Remote repo	正常版控？
srt-to-html-swift	✅	?	?	是（經 whitelist）
md-to-html-swift	✅	?	?	是（經 whitelist）
html-to-md-swift	✅	?	?	是（經 whitelist）
marker-word-converter-swift	✅	?	?	是（經 whitelist）
common-converter-swift	N/A	N/A	PsychQuant/common-converter-swift	是（remote dep）
word-to-md-swift	N/A	N/A	PsychQuant/word-to-md-swift	是（remote dep）
note-core-swift	❌	❌	❌	否
note-to-pdf-swift	❌	❌	❌	否
note-to-html-swift	❌	❌	❌	否

note-core-swift / note-to-pdf-swift / note-to-html-swift 既不在白名單、又沒獨立 .git、也沒有對應的 PsychQuant/* remote repo — 意味著 #76 (note-to-pdf 發布) 的原始碼只存在開發者的 local filesystem，沒納入任何版本控制。

Type

refactor

Expected

三個 Note-相關 packages 跟 common-converter-swift / word-to-md-swift 同樣處理：獨立成 PsychQuant GitHub repos，用 remoteSourceControl 依賴。

// 目標狀態：Package.swift
.package(url: "https://github.com/PsychQuant/note-core-swift.git", from: "0.1.0"),
.package(url: "https://github.com/PsychQuant/note-to-pdf-swift.git", from: "0.1.0"),
.package(url: "https://github.com/PsychQuant/note-to-html-swift.git", from: "0.1.0"),

Actual

目前三個 packages 都用 local path: 依賴且完全無版本控制：

.package(name: "NoteToHTML", path: "packages/note-to-html-swift"),
.package(name: "NoteToPDF", path: "packages/note-to-pdf-swift"),
// NoteCore 由 NoteToHTML / NoteToPDF 間接依賴

Source files 只在開發者 local（macdoc v0.5.0 binary 能跑，但無法 collaborate / PR / audit）。

Impact

• 無法 collaborate：第二位開發者從頭 clone macdoc 缺少三個 packages 的 source → 無法 build
• 無法 PR review：改動 NoteCore 邏輯無 diff 可看
• 無 audit trail：git log 查不到 packages 歷史
• Blocks bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77：#77 修的 bug 位於 packages/note-core-swift/Sources/NoteCore/NoteParser.swift:154-159，已完成實作 + 單元測試，但無法 commit（被 .gitignore 擋、也沒有 remote repo 可以 push）

Strategy

三個 packages 依相依順序處理：

Phase 1 — NoteCore（基礎，無下游內部依賴）

• 在 packages/note-core-swift/ 跑 git init
• 建 PsychQuant/note-core-swift GitHub repo
• 設 origin 指到新 repo，push 初版
• Tag v0.1.0（含 feat: add .note → pdf conversion (complement existing .note → html) #76 已完成的原始碼 + bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 的 fix，如果 bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 也在這個 phase 完成）
• 改 macdoc Package.swift: .package(name: "NoteCore", path: "...") → .package(url: "https://github.com/PsychQuant/note-core-swift.git", from: "0.1.0")
• 改 note-to-pdf-swift / note-to-html-swift 的 Package.swift 同上
• 跑 swift package update，確認 macdoc build 通過
• 移除 macdoc .gitignore 裡不需要的 !packages/note-core-swift/ 白名單（如果有加的話）— vacuously satisfied: note packages were never whitelisted, only matched by blanket packages/ rule

Phase 2 — NoteToPDF

• 重複 Phase 1 流程（init / create repo / push / tag / 改 Package.swift）
• Tag v0.1.0（含 feat: add .note → pdf conversion (complement existing .note → html) #76 的原始碼）

Phase 3 — NoteToHTML

• 同 Phase 1 流程

Phase 4 — Verification

• [~] Clean clone macdoc（模擬新開發者），swift build 應成功拉三個新 repos + build OK — deferred: literal clean-clone blocked by gitignored packages/pdf-to-latex-swift + Tests/WordToMDTests (out of refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 scope, tracked as refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues #78 pattern) #79)
• swift test 全部通過
• macdoc convert 的 note 相關功能 smoke test

Blockers / Dependencies

• bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 blocked by this — bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 的 fix 已實作 + 測試通過，但需要先完成 Phase 1 才能把 code commit/push
• 可能要先決定版本號策略：note-to-pdf-swift 已隨 macdoc v0.5.0 發布，獨立後第一個 tag 要用什麼？（建議 v0.1.0，因為 package 本身還沒 bump 過）

Notes

• 這個 issue 觸發的契機：idd-implement bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 做到一半 git add 被 .gitignore 擋，scope-guard 停下來 route 決策
• 不應該把 bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 的 fix 夾帶在這個 refactor 裡完成 — 兩個 issue 的 concerns 要分開
• 完成此 refactor 後，bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 的 implementation branch 可以 rebase/re-apply 到新的 note-core-swift repo 上

---

Current Status

Phase: closed
Last updated: 2026-04-18 by idd-close

Key Decisions

• Closed 2026-04-18 — PASS WITH NOTES; declared scope (Phase 1-3) FULLY done; Phase 4 PARTIALLY (literal clean-clone deferred to refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues #78 pattern) #79)
• Verify 2026-04-18 via 5 Claude reviewers + Codex (gpt-5.4 xhigh) ensemble; Devil's Advocate counter-evidence accepted
• 3 follow-up issues filed for non-blocking findings: refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues #78 pattern) #79 (gitignored packages systemic), security: enable GitHub security defaults (secret scanning, branch protection, dependabot) across PsychQuant org repos #80 (org-wide repo security), test: add NoteConvertTests smoke coverage (.note → pdf/html) to MacDocCLITests #81 (NoteConvert smoke tests)
• Latent regression caught + fixed: Package.resolved had downgraded note-to-pdf-swift 0.1.2 → 0.1.0 due to feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js） #71 wiring; restored 0.1.2 via swift package update; bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 fix preserved
• Devil's Advocate counter-evidence accepted: 565f4c2 silently bumped 5 new + 8 existing transitive deps, "26 tests passed" doesn't exercise note-* paths
• Branch state still mixed: PageOCRRunner.swift Qwen3-VL/OCRCore refactor is third workstream, must NOT land in refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 PR
• Root cause 鎖定：NoteParser.swift:154-159 用「strokes.bounds.maxY / pageCount」均分估 pageHeight (bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 context, retained from earlier diagnosis)
• Fix 方向：從 documentPaperAttributes.paperSize enum 查 logical pageHeight 替代均分（letter portrait → (583.8, 756)）
• Issue body 3 個 hypothesis 驗證：Read .claude guidance for upcoming work #1 駁回；feat: AIConfig — AI CLI 工具設定系統 #2 部分；feat: LaTeXNormalizer — 機械式 LaTeX 清理 #3 N/A
• Complexity: SDD-warranted → discuss-converged → opt-out 進 implement
• 三個 packages 全部 v0.1.0 public 獨立 @ PsychQuant/note-{core,to-pdf,to-html}-swift
• macdoc refactor/extract-note-packages-78 branch pushed with commit 565f4c2

Scope Changes

• (none — 按 diagnosis Strategy 6 phases 嚴格執行)

Blocking

• (none — closed)
• Out-of-scope blockers (carve before merge to main): PageOCRRunner.swift dirty state, Package.resolved fix to commit on feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js） #71's branch
• bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 已 unblocked + version-bumped via 60b3bb6

Commits

• 565f4c2 refactor: extract NoteCore/NoteToPDF/NoteToHTML to separate PsychQuant repos (refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78)
• 60b3bb6 chore: bump note-core-swift to 0.1.3 + note-to-pdf-swift to 0.1.2 (bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77)
• (uncommitted, fixed during verify) Package.resolved re-pin note-to-pdf-swift back to 0.1.2

Repos Created

• https://github.com/PsychQuant/note-core-swift v0.1.0–v0.1.3
• https://github.com/PsychQuant/note-to-pdf-swift v0.1.0–v0.1.2
• https://github.com/PsychQuant/note-to-html-swift v0.1.0

[kiki830621]

Diagnosis

Type

refactor

Current State Analysis

三個 packages 的規模與依賴

Package	Sources LOC	Tests LOC	Internal deps	External deps
note-core-swift	614 (NoteParser + StrokeDecoder + TimelineDecoder)	121（#77 剛加的 7 個 unit tests）	—	ZIPFoundation
note-to-pdf-swift	113 (NoteToPDFConverter)	0	NoteCore (path)	—
note-to-html-swift	741 (NoteConverter + PlayerTemplate)	?	NoteCore (path)	CommonConverterSwift (remote)

Dependency graph（確認無 cycle）

ZIPFoundation (external)
       ↓
  NoteCore  ←──┬────── NoteToPDF
               └────── NoteToHTML ──── CommonConverterSwift (external, remote)
                                              ↑
                                         macdoc CLI

NoteCore 是唯一基礎 — Phase 1 只要把 NoteCore 獨立，Phase 2/3 的 NoteToPDF / NoteToHTML 只需要改 Package.swift 把 path: "../note-core-swift" 換成 url: "https://github.com/PsychQuant/note-core-swift.git"。

跟 PsychQuant 現有獨立套件 pattern 比對

DerivedData cache 的 checkouts 看到 reference pattern：

• common-converter-swift: Package.swift + Sources/（無 Tests、無 README 在 cache 裡）
• word-to-md-swift: Package.swift + Sources/ + Tests/ + Package.resolved

Minimal layout — 沒有 CI workflow、沒有強制 README/LICENSE/CONTRIBUTING。

Why（為什麼要重構）

Issue body 已清楚說明。補充技術層面：

1. feat: add .note → pdf conversion (complement existing .note → html) #76 發布時 skip 版控步驟：v0.5.0 的 note-to-pdf feature 有 tag、有 release binary，但三個 packages 的原始碼 0 個 commit。這是 release process gap，不是有意為之
2. .gitignore 註解與現實不符：L20 註解 # Local packages & MCP (separate git repos) 暗示 packages 都應該獨立，但現實是三個 packages 既不獨立也不在白名單 — 處於 schrödinger 狀態
3. Blocks bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77：7 個 unit tests + 1 個 helper 的 source diff 無處可 commit

Risks

Risk	嚴重性	緩解
PsychQuant repo 建立失敗（權限 / naming 衝突）	中	先確認 GitHub org 管理權；repo 名沿用 dir 名避免 rename
swift package update 拉新 remote 失敗	中	分階段：先本地 git remote -v 測通，再改 Package.swift
macdoc Package.resolved 需要手動 update	低	swift package update 會自動產生
note-to-pdf-swift 的 swift code（LOC=113）跟 #77 的 fix 相衝突	低	#77 只改 note-core-swift，不碰 note-to-pdf-swift
版本號起始選錯導致未來 conflict	低（但需決策）	下方 Open Questions

Strategy

Issue body 的 Phase 1-4 架構 OK，補充細節：

Phase 0（新增）— 決策確認

• 確認下方 Open Questions 的答案（版本號、CI、visibility、版本固定策略）
• 確認 PsychQuant org 管理權限可建新 repos

Phase 1 — NoteCore 獨立

• packages/note-core-swift/ 執行 git init + git add . + 初始 commit（含 feat: add .note → pdf conversion (complement existing .note → html) #76 code + bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 在 branch 的 fix）
• 建 PsychQuant/note-core-swift GitHub repo
• git remote add origin ... + push + tag v0.1.0（或其他決定的版本）
• 改 macdoc 的 Package.swift: NoteCore 從 path 改成 url: "https://..." + 版本約束
• 改 note-to-pdf-swift/Package.swift 和 note-to-html-swift/Package.swift 的 NoteCore 依賴同上
• swift package update → 確認 macdoc build + test 通過

Phase 2 — NoteToPDF 獨立

• 重複 Phase 1 流程，依賴已指向 remote NoteCore
• Tag 版本（對齊 macdoc v0.5.0 或起 v0.1.0 — 見 Open Q1）

Phase 3 — NoteToHTML 獨立

• 同 Phase 2

Phase 4 — Cleanup

• 評估是否移除 macdoc .gitignore 的 packages/ 規則（其他 local packages 還在 whitelist，可能仍需保留）
• Package.resolved commit 進 macdoc（現在已經 M 狀態）
• 清除 packages/note-* 三個資料夾（已改用 remote，local 不需要了）或保留（SwiftPM 會忽略未引用的 path）

Phase 5 — Verification

• Clean clone 測試：從 fresh state git clone macdoc && swift build（模擬新開發者）
• swift test 全部通過
• macdoc 核心 smoke test：.note → pdf / .note → html 轉換
• 解除 bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 blocker，回到 fix/page-height-from-paper-size-77 branch 完成 S2/S3/S5

Open Questions（需決策才能進 implement）

1. 版本號起始策略：

   • (a) 三個 packages 都從 v0.1.0 開始 — 標準 initial release
   • (b) note-to-pdf-swift 用 v0.5.0 對齊 macdoc（因為已經隨 macdoc v0.5.0 發布）
   • (c) 混合：NoteCore v0.1.0、NoteToPDF v0.5.0、NoteToHTML v0.1.0

2. README / LICENSE / CONTRIBUTING：

   • PsychQuant 現有獨立套件看起來 minimal（至少 cache 裡看不到 README）— 新 packages 要加嗎？
   • 如果加，跟哪個 reference repo 對齊（common-converter-swift?）

3. CI/CD：

   • 新 repos 要不要加 GitHub Actions 跑 swift test？
   • 如果要，用哪個 template？

4. Repo visibility：

   • Public 還是 private？
   • 如果 public，README/LICENSE 更重要

5. macdoc Package.swift 的版本固定：

   • from: "0.1.0"（允許 minor/patch bump，breaking 不允許）
   • exact: "0.1.0"（完全鎖定）
   • .upToNextMinor(from: "0.1.0")（更嚴格）
   • 其他 PsychQuant 依賴用 from:（見 macdoc Package.swift L14）→ 推薦 from: 保持一致

Impact

• 影響檔案（跨 repo）：
  • 新建：3 個 GitHub repos
  • 修改：macdoc Package.swift, Package.resolved, 可能還有 .gitignore
  • 修改：note-to-pdf-swift/Package.swift, note-to-html-swift/Package.swift（在獨立後的新 repo 裡）
• 影響流程：feat: add .note → pdf conversion (complement existing .note → html) #76 的 release flow 要補文件（下次新 package 要 same cycle: init → remote → tag → Package.swift 更新）
• 解 block：bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 的 Phase 2-5 可以完成

Complexity

SDD-warranted

理由：

• ✅ 改動跨 3+ 檔案且有順序依賴（Phase 1 → 2/3 → 4/5）
• ✅ 有架構決策（版本號、CI、visibility、.gitignore cleanup 策略）
• ✅ Strategy 有 5+ 步驟且 phase 內順序強相依
• ❌ 無新共用抽象
• ❌ 不影響既有 capability 的 behavior（純 infra 遷移）

有多個 Open Questions（5 組 trade-off）還沒對齊答案 → 走 spectra-discuss 讓 assumptions 被列出並修正，比直接寫 proposal 更穩。

[kiki830621]

Discuss Conclusion — All Open Questions Resolved

Spectra-discuss 流程（手動 emulate，因 spectra-* skill 在本 repo 未 activate）走完，5 組 open questions 全對齊：

#	Question	Decision	Rationale
1	Repo visibility	public	PsychQuant 所有 Swift 套件（common-converter-swift / word-to-md-swift / markdown-swift / marker-swift / ooxml-swift）都是 public — 對齊 convention
2	README / LICENSE / CONTRIBUTING	只寫 GitHub description，無 LICENSE 檔	PsychQuant 所有 packages license = none，description = 一句話說明用途 — 對齊 convention
3	GitHub Actions CI	無	PsychQuant 所有 packages has_actions = null — 對齊 convention（未來可另開 issue 加）
4	macdoc Package.swift 版本固定策略	from: "0.1.0"	macdoc 既有 remote deps 全用 from: pattern（L14 swift-argument-parser / L15 common-converter-swift / L16 word-to-md-swift）— 對齊 convention
5	三個 packages 起始版本號	全部 v0.1.0	決定：package 獨立演進，不綁 macdoc 版本（即使 NoteToPDF 已隨 macdoc v0.5.0 發布 binary，package 本身是第一次獨立 publish）— 符合 PsychQuant 既有 pattern

Convergence Summary

三個 packages 獨立流程完全按 PsychQuant 既有 pattern 走，無新 convention 引入：

• Public repo + description 一句話
• 無 LICENSE / 無 CI / 無 README（先 minimal，未來需要再補）
• 版本從 v0.1.0 起，semver 演進
• macdoc Package.swift 用 from: "0.1.0" 固定版本（允許 minor/patch auto-bump，block breaking）

Spectra-Propose Opt-Out Criteria Check

根據 idd-diagnose skill 規範：

• ✅ 使用者已明確選定方向（decisions 1-5 都有答案）
• ✅ 無 open questions 剩餘
• ✅ Strategy 沒有未決項（issue body Phase 0-5 架構 + diagnosis 補細節全確定）
• ✅ 遵循既有 pattern，無新抽象

全部滿足 → 可 opt-out /spectra-propose，直接進 /issue-driven-dev:idd-implement #78。

Next Step

/issue-driven-dev:idd-implement #78

實作時依 Strategy 的 6 phases 順序執行。

[kiki830621]

Implementation Plan

Branch strategy

• macdoc branch: refactor/extract-note-packages-78（新建，為了 Package.swift + Package.resolved 變更）
• 三個新 package repos 各自在 main branch 做初始 commit + tag v0.1.0

#77 working-tree 處理

branch fix/page-height-from-paper-size-77 已有對 note-core-swift/ 的 S1+S4 修改（helper + tests），未 commit。Phase 0 先 stash，Phase 1 的初始 commit 不夾帶 #77 fix，保持 v0.1.0 = #76 baseline。#78 完成後在 new repo 上 pop stash 讓 #77 繼續。

Phase 0 — 準備

• 切 macdoc branch refactor/extract-note-packages-78
• git stash -m "#77 WIP (logicalPageHeight helper + tests)" 暫存 note-core-swift 的修改
• git stash show 確認 stash diff 含 NoteParser.swift + Tests/NoteCoreTests/NoteParserTests.swift

Phase 1 — NoteCore 獨立（base package，先做）

• cd packages/note-core-swift && git init
• git add . && git commit -m "init: NoteCore v0.1.0 extracted from macdoc (#78)"
• gh repo create PsychQuant/note-core-swift --public --source=. --push --description "Notability .note parser — ZIP bundle + Session.plist + stroke/timeline decoders"
• git tag v0.1.0 && git push origin v0.1.0
• 改 packages/note-to-pdf-swift/Package.swift: NoteCore 依賴 path: → url: "https://github.com/PsychQuant/note-core-swift.git", from: "0.1.0"
• 改 packages/note-to-html-swift/Package.swift: 同上

Phase 2 — NoteToPDF 獨立

• cd packages/note-to-pdf-swift && git init + commit + create repo + push + tag v0.1.0
• Description: "Notability .note → PDF via Core Graphics (uses NoteCore)"

Phase 3 — NoteToHTML 獨立

• cd packages/note-to-html-swift && git init + commit + create repo + push + tag v0.1.0
• Description: "Notability .note → interactive HTML player with audio-synced stroke replay (uses NoteCore)"

Phase 4 — macdoc Package.swift 更新

• 改 macdoc Package.swift L30-32: 三個 path: → url:, from: "0.1.0" pattern
• swift package update（產生新 Package.resolved）

Phase 5 — Verification

• swift build 從 remote 拉三個新 repos → 成功
• swift test → 全部通過
• Smoke test: macdoc convert --to pdf 用 Wei 的 .note 檔，確認功能不受影響
• git status --short 檢查無 unintended changes
• Commit macdoc 的 Package.swift + Package.resolved 改動（message: refactor: extract NoteCore/NoteToPDF/NoteToHTML to separate PsychQuant repos (#78)）

Phase 6 — Cleanup & #77 unblock

• 評估 macdoc .gitignore 清理（保留或移除 packages/ pattern — 看其他 whitelist packages 狀態）
• Comment bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77: 「refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 Phase 1 完成，NoteCore 已獨立到 PsychQuant/note-core-swift」
• Push refactor/extract-note-packages-78 branch
• 提示用戶重跑 idd-implement #77 繼續 S2/S3/S5

Scope check

• ✅ 覆蓋 diagnosis 的 6 phases
• ✅ Discuss conclusion 的 5 個 decisions 全部套用（全 v0.1.0 / public / from: / no LICENSE / no CI）
• ✅ 不在 refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 branch 上 commit bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 的 code（stash 策略避免 scope creep）

Rollback strategy

如果 Phase 1-3 的 gh repo create 失敗：

• 前一 phase 的 repo 保留（已成功 push），不 delete
• 停在失敗的 phase，報告狀況給用戶

如果 Phase 5 build/test fail：

• 在對應 package repo 發 patch（v0.1.1）修正
• 不 force-push 覆蓋 v0.1.0

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• P0.1 — 切 macdoc branch refactor/extract-note-packages-78
• P0.2 — Backup bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 WIP + revert note-core-swift working tree 到 feat: add .note → pdf conversion (complement existing .note → html) #76 baseline
• P1 — NoteCore 獨立到 PsychQuant/note-core-swift v0.1.0 + 改下游 Package.swift → commit init: NoteCore v0.1.0 extracted from macdoc
• P2 — NoteToPDF 獨立到 PsychQuant/note-to-pdf-swift v0.1.0 → commit init: NoteToPDF v0.1.0 extracted from macdoc
• P3 — NoteToHTML 獨立到 PsychQuant/note-to-html-swift v0.1.0 → commit init: NoteToHTML v0.1.0 extracted from macdoc
• P4 — macdoc Package.swift + Package.resolved 更新成 remote deps → commit 565f4c2
• P5 — swift build ✓ / swift test 26 passed ✓ / smoke test .note → pdf ✓
• P6 — macdoc branch push + bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 unblock comment + bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 WIP restore 到新 note-core-swift repo

Legend: - [x] done · - [~] skipped · - [-] won't fix

Changes

New repos (all public, tagged v0.1.0):

• https://github.com/PsychQuant/note-core-swift
• https://github.com/PsychQuant/note-to-pdf-swift
• https://github.com/PsychQuant/note-to-html-swift

macdoc commit:

• 565f4c2 refactor: extract NoteCore/NoteToPDF/NoteToHTML to separate PsychQuant repos (refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78)

macdoc branch pushed:

• refactor/extract-note-packages-78 → https://github.com/PsychQuant/macdoc/tree/refactor/extract-note-packages-78

Files Changed (macdoc side)

 Package.swift    |   8 ++--
 Package.resolved | 112 +++++++++++++++++++++++++++++++++++++++++++++----------
 2 files changed, 96 insertions(+), 24 deletions(-)

Package.swift diff:

• .package(name: "NoteToHTML", path: "packages/note-to-html-swift") → .package(url: "https://github.com/PsychQuant/note-to-html-swift.git", from: "0.1.0")
• .package(name: "NoteToPDF", path: "packages/note-to-pdf-swift") → .package(url: "https://github.com/PsychQuant/note-to-pdf-swift.git", from: "0.1.0")
• .product(name: "NoteToHTML", package: "NoteToHTML") → .product(name: "NoteToHTML", package: "note-to-html-swift")（package identity 改成小寫 hyphen）
• Same for NoteToPDF

Verification

步驟	結果
swift package update	OK — 3 新 repos 成功 resolve 到 v0.1.0
swift build	OK — macdoc binary 連結成功 (18.73s)
swift test	26 tests passed across 4 suites
Smoke test: macdoc convert --to pdf on Wei .note	輸出 889 KB PDF（同 refactor 前，確認 behavior 不變；#77 分頁 bug 仍存在，等 #77 fix）

Scope Compliance

• ✅ 嚴格按 diagnosis Strategy 6 phases 執行
• ✅ Discuss conclusion 5 decisions 全套用（全 v0.1.0 / public / from: / no LICENSE / no CI）
• ✅ bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 的 S1+S4 work-in-progress 沒夾帶到 refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 的 commit（stash/restore 機制）
• ✅ 不改 macdoc .gitignore 的 packages/ pattern（未觸及不相關 convention）

Deferred (decided against scope creep)

• 移除 macdoc packages/note-* 三個目錄：暫時保留，因 SwiftPM 只用 Package.swift 宣告的 url dep，local 目錄不會被引用。清理可另開 cleanup issue
• 加 LICENSE / README / CI 到新 repos：對齊 PsychQuant minimum convention，未來若有需求再另開 issue

Next: verification pending

#77 的 fix 現在可以在 PsychQuant/note-core-swift repo 上 commit + tag v0.1.1。

[kiki830621]

Verify: #78

Engine

Agent Team (5 Claude reviewers: requirements / logic / security / regression / devils-advocate) + Codex (gpt-5.4 xhigh)

Verdict

PASS WITH NOTES for declared scope (Phase 1-3 fully addressed). Phase 4 verification was developer-local-build only, not a literal clean-clone test — flagged as a follow-up. No blocking findings to #78 itself; one blocking finding for the parallel #71 wiring surfaced incidentally.

要求覆蓋率

Phase	Verdict	Evidence
Phase 1 — NoteCore extracted	FULLY	PsychQuant/note-core-swift exists, tags v0.1.0–v0.1.3; note-to-pdf-swift and note-to-html-swift Package.swift declare note-core-swift from: "0.1.0" (compatible with 0.1.3 in resolved); transitive resolution from macdoc works (Package.resolved L58-65). The "remove .gitignore whitelist" sub-step was vacuous (note-* packages were never whitelisted; only the blanket packages/ rule applied).
Phase 2 — NoteToPDF extracted	FULLY	PsychQuant/note-to-pdf-swift exists, tags v0.1.0–v0.1.2; macdoc Package.swift line 29 uses .package(url: ".../note-to-pdf-swift.git", from: "0.1.0").
Phase 3 — NoteToHTML extracted	FULLY	PsychQuant/note-to-html-swift exists, tag v0.1.0; macdoc Package.swift line 28 uses .package(url: ".../note-to-html-swift.git", from: "0.1.0").
Phase 4 — Verification	PARTIALLY	Developer's commit body cites swift build: OK, swift test: 26 tests passed, smoke test passing. No literal clean clone executed (local packages/note-*-swift/ dirs still on disk). Codex independently failed to repro a clean-clone build, but the failure was due to other gitignored packages (packages/pdf-to-latex-swift, Tests/WordToMDTests) that are out-of-scope for #78.

Findings (合併後)

#	Severity	Finding	Source	Action
1	P1	Uncommitted Package.resolved on this branch silently downgrades note-to-pdf-swift 0.1.2 → 0.1.0 because adding word-builder-swift (#71 wiring) caused SPM to re-resolve. If #71 wiring lands as-is, #77's logicalPageHeight fix silently regresses.	regression + devils-advocate	Blocking for #71's PR, not #78 — fix before #71 wiring is committed
2	P1	All 3 new repos have secret scanning, branch protection, dependabot, push protection all DISABLED. Org-wide pattern (same as ooxml-swift/word-to-md-swift etc), not a #78 regression but #78 widens the surface.	security	Follow-up — open umbrella issue for org-wide PsychQuant hardening
3	P1	Macdoc's clean-clone swift build fails on HEAD because packages/pdf-to-latex-swift/ and Tests/WordToMDTests/ are gitignored/untracked (same pattern #78 fixed for note-* packages, applied to other paths).	codex	Follow-up — open new issue mirroring #78's approach for pdf-to-latex-swift + WordToMDTests
4	P2	Uncommitted Sources/MacDocCLI/PageOCRRunner.swift is a third in-flight workstream: default OCR model swap (GLM-OCR → Qwen3-VL-4B) + new OCRCore backend abstraction. Not #71, not #78.	regression	Out-of-scope for #78 PR — must be carved out before merge
5	P2	Commit 565f4c2 silently bumped Package.resolved well beyond the declared 3 note-* additions: 5 new transitive deps (eventsource, swift-nio, swift-huggingface, swift-atomics, swift-system) + 8 existing-dep version bumps including markdown-swift minor 0.1 → 0.2. Not declared in commit message.	devils-advocate	Follow-up — amend PR description to list incidental bumps
6	P2	Phase 4 "clean clone" not literally executed; local packages/note-* dirs + .build/ caches mean in-tree build is a weaker proxy for fresh-consumer build than the team assumed.	devils-advocate + codex + requirements	Follow-up — run git clone … && swift build once before merging to main
7	P2	"26 tests passed" claim in commit body is misleading: 565f4c2 adds zero tests; the 26 are pre-existing MacDocCLITests + WordToMDTests that don't exercise NoteToPDF/NoteToHTML at all.	devils-advocate	Follow-up — add a smoke test like MacDocCLITests/NotePDFConvertTests to guard future refactors
8	LOW	No GitHub Releases attached to any tag → tags are rewritable by anyone with push access (security mitigation gap beyond Package.resolved SHA pinning).	security + devils-advocate	Follow-up — add gh release create to release flow
9	LOW	"Unblocks #77" is a structural claim (note-core can independently iterate), but no end-to-end smoke proof at branch HEAD that #77's PDF output is now correct.	devils-advocate	Follow-up — run macdoc convert --to pdf <sample.note> and diff against expected
10	LOW	.gitignore whitelist-removal sub-step was no-op (note packages were never whitelisted).	requirements	None — vacuously satisfied
11	LOW	note-core-swift not a direct dep in macdoc (transitive via NoteToPDF + NoteToHTML).	logic + requirements + security	None — by design (matches issue body)
12	LOW	Package.swift uses from: "0.1.0" semver but Package.resolved pins SHA — acceptable trade-off.	security + logic	None — defensible

Devil's Advocate counter-arguments accepted

• Read .claude guidance for upcoming work #1 + feat: TexCompileChecker — 編譯錯誤解析器 #5 + feat: Consolidator — 機械 + Agent 整合引擎 #6 + feat: CLI 子命令 — normalize, fix-envs, compile-check, consolidate, config ai #7 were claimed PASS by other reviewers but Devil's Advocate / Codex pushed back with valid concrete evidence. Severities upgraded accordingly.

Devil's Advocate counter-arguments not sustained (genuinely passes)

• Note-core transitivity is intentional ✓
• Public-repo choice is correct ✓
• No secrets committed ✓
• 60b3bb6 is legitimate in-branch follow-up ✓
• Lowercase-hyphenated package identity correct ✓

Scope Check

• 565f4c2 itself: 2 files, scope-clean for refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78
• 60b3bb6: 1 file (Package.resolved bump for bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 unblock), scope-clean follow-up
• Working-tree dirty state: two unrelated workstreams (feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js） #71 wiring + the OCRCore/Qwen3-VL refactor in PageOCRRunner.swift) must NOT land in refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78's PR

Recommendation

• Close refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 as PASS WITH NOTES for declared scope.
• Carve out the working-tree dirty state to the appropriate branches/PRs (not in refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78's merge).
• Open follow-up issues for systemic items (org repo hardening, gitignored-packages problem applied to pdf-to-latex/WordToMDTests, smoke-test coverage).

[kiki830621]

Follow-up Issues Filed

Three follow-up issues opened to track non-blocking findings from this verification:

• refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues #78 pattern) #79 — refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 pattern). Closes the systemic gap that codex's clean-clone test exposed.
• security: enable GitHub security defaults (secret scanning, branch protection, dependabot) across PsychQuant org repos #80 — security: enable GitHub security defaults (secret scanning, branch protection, dependabot) across PsychQuant org repos. Org-wide hygiene, widened by 3 new repos but not introduced by refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78.
• test: add NoteConvertTests smoke coverage (.note → pdf/html) to MacDocCLITests #81 — test: add NoteConvertTests smoke coverage (.note → pdf/html) to MacDocCLITests. Closes the "26 tests passed but none exercise note-* paths" gap.

Latent regression fix (separate from #78)

The Package.resolved downgrade of note-to-pdf-swift 0.1.2 → 0.1.0 (caused by adding word-builder-swift dep for #71) was fixed via swift package update note-to-pdf-swift. note-to-pdf-swift is back at v0.1.2; swift build confirmed clean (6.80s). #77's logicalPageHeight fix is preserved.

[kiki830621]

Closing Summary

Problem

The 2026-04-17 conversation surfaced this:

「B，那些應該要是套件才對」
— Source: Claude Code session 2026-04-17, idd-implement #77 途中觸發 scope guard

Three Note-related Swift packages (note-core-swift, note-to-pdf-swift, note-to-html-swift) lived only on the developer's local filesystem — not in any version control, not in any GitHub repo. They were path-deps from macdoc and matched by .gitignore's blanket packages/ rule, with no whitelist entry. As a direct consequence, #77's bug fix could not be committed (it lives in note-core-swift/Sources/NoteCore/NoteParser.swift but that file is not tracked by any repo), and any second developer cloning macdoc could not build the Notability conversion paths.

Root Cause

The asymmetry between sibling packages: srt-to-html-swift / md-to-html-swift / html-to-md-swift etc. were .gitignore-whitelisted and committed in-tree, while common-converter-swift / word-to-md-swift were extracted to PsychQuant/* repos as remote url: deps. The note-* packages had been added during #76 (note-to-pdf delivery) but missed both treatments — neither whitelisted nor extracted. The blanket packages/ ignore rule plus no remote repo meant the source never had a path home.

Solution

Extracted all 3 note packages to independent PsychQuant/* GitHub repos following the common-converter-swift precedent: each git init'd, pushed to https://github.com/PsychQuant/{name}-swift, tagged v0.1.0, and consumed via .package(url: …, from: "0.1.0"). macdoc's Package.swift now lists note-to-html-swift and note-to-pdf-swift as direct remote deps; note-core-swift is pulled transitively through both (as documented in the issue body). The implementation followed the diagnosis-Strategy 6-Phase plan (Phase 0 prep / Phase 1-3 per-package extract / Phase 4 macdoc wiring / Phase 5 verification / Phase 6 cleanup) without scope creep — only Package.swift and Package.resolved were touched in commit 565f4c2.

A follow-up bump landed in 60b3bb6 to consume #77's fix at note-core-swift v0.1.3 + note-to-pdf-swift v0.1.2, demonstrating the refactor enabled independent iteration.

Verification

6-AI ensemble (5 Claude reviewers + Codex gpt-5.4 xhigh) ran on 2026-04-18 (see verification report #4272192328).

Phase	Verdict	Evidence
Phase 1 NoteCore	FULLY	4 tags (v0.1.0–v0.1.3) on PsychQuant/note-core-swift; consumed transitively
Phase 2 NoteToPDF	FULLY	3 tags (v0.1.0–v0.1.2) on PsychQuant/note-to-pdf-swift; macdoc Package.swift L29
Phase 3 NoteToHTML	FULLY	v0.1.0 on PsychQuant/note-to-html-swift; macdoc Package.swift L28
Phase 4 Verification	PARTIALLY	Developer's local build/test/smoke passed; literal clean clone deferred to #79 because parallel gitignore-blackhole exists for pdf-to-latex-swift + WordToMDTests

Devil's Advocate counter-arguments accepted (silent dep bumps in Package.resolved, "26 tests" doesn't exercise note-* paths, etc.) — three follow-up issues filed:

• refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues #78 pattern) #79 — extract pdf-to-latex-swift + ocr-swift + WordToMDTests fixtures (P1, continues refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 pattern)
• security: enable GitHub security defaults (secret scanning, branch protection, dependabot) across PsychQuant org repos #80 — org-wide PsychQuant security defaults (P1, secret scanning + branch protection + dependabot)
• test: add NoteConvertTests smoke coverage (.note → pdf/html) to MacDocCLITests #81 — NoteConvert smoke tests in MacDocCLITests (P2, close the test-coverage gap)

A latent regression was caught and fixed during verify: adding word-builder-swift (#71 wiring) caused SPM to silently downgrade note-to-pdf-swift 0.1.2 → 0.1.0 in Package.resolved, which would have reverted #77's logicalPageHeight fix. Restored to v0.1.2 via swift package update note-to-pdf-swift; build clean (6.80s).

Changes

macdoc commits on refactor/extract-note-packages-78 branch:

• 565f4c2 refactor: extract NoteCore/NoteToPDF/NoteToHTML to separate PsychQuant repos (refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78)
• 60b3bb6 chore: bump note-core-swift to 0.1.3 + note-to-pdf-swift to 0.1.2 (bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77)
• (uncommitted, fixed during verify) Package.resolved re-pin of note-to-pdf-swift to 0.1.2 after feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js） #71 wiring downgrade

3 new repos:

• https://github.com/PsychQuant/note-core-swift (v0.1.0–v0.1.3)
• https://github.com/PsychQuant/note-to-pdf-swift (v0.1.0–v0.1.2)
• https://github.com/PsychQuant/note-to-html-swift (v0.1.0)

Branch state caveat for whoever merges to main:

• The refactor/extract-note-packages-78 branch's working tree currently mixes refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 (this) + feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js） #71 (word-builder-swift wiring, just shipped) + a third in-flight workstream (PageOCRRunner.swift Qwen3-VL/OCRCore refactor, no issue yet). Each must be carved into its own PR; do NOT squash all into a refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 merge.