bug: clean clone baseline regressed through ignored word-to-md-swift path dependency

[kiki830621]

Problem

Observed clean-clone failure:
error: the package at '<clean-clone>/packages/word-to-md-swift' cannot be accessed (... doesn't exist in file system)
— Source: reproducible swift test on origin/main at b66d98c

A clean clone of PsychQuant/macdoc cannot resolve the root Swift package graph. Package.swift declares word-to-md-swift as a local path dependency, while the blanket packages/ ignore rule excludes that directory and no matching whitelist tracks it.

This regresses the clean-clone guarantee previously repaired and verified by #12.

Type

bug

Priority

P1 — blocks reproducible baseline verification for every implementation issue.

Expected

• git clone https://github.com/PsychQuant/macdoc.git
• cd macdoc
• swift test

The package graph should resolve without requiring developer-local directories.

Actual

SwiftPM exits before planning the build because packages/word-to-md-swift is absent from the clean clone.

Root-cause evidence

• Commit c3003ca changed the dependency from the remote PsychQuant/word-to-md-swift package to .package(name: "word-to-md-swift", path: "packages/word-to-md-swift") as a temporary compatibility override.
• .gitignore still excludes packages/word-to-md-swift.
• The upstream repository now has a public v1.0.0 tag, so the original “until upstream publishes” condition is no longer true.
• The developer checkout masks the regression because it contains the ignored package directory locally.

Impact

• Fresh contributors and CI cannot run the root build/test baseline.
• Local verification can pass only because of hidden filesystem state.
• Repository-wide IDD verification cannot distinguish regressions from an already-broken baseline without a workaround.

Clarity Surface(idd-clarify run 2026-08-23T19:48:42Z, unattended)

Type	Source	Question for you	Status
(none)	—	no issues detected	passed

---

Current Status

Phase: closed
Last updated: 2026-09-01 by idd-close (batch)

Key Decisions

• Restore the published WordToMD v1.0.0 dependency; remove the ignored local override.
• Keep macdoc follows ooxml-swift's main branch instead of the version it declares #162's ooxml-swift branch governance as a separate serialized issue.

Scope Changes

• (none)

Blocking

• (none — verify-gated PASS; awaiting PR review/merge)

Commits

• 02193ce — restore clean-clone WordToMD dependency

[kiki830621]

Diagnosis

Type

bug

Root Cause / Analysis

我認為 root cause 是 commit c3003ca 留下的暫時性本機 path override 沒有在上游發布後撤回，因為：

• Package.swift 目前指定 .package(name: "word-to-md-swift", path: "packages/word-to-md-swift")。
• .gitignore 的 blanket packages/ 規則沒有 whitelist 該 package；乾淨 clone 因此必定缺目錄。
• 開發者工作目錄剛好有被忽略的本機 checkout，所以日常增量測試遮蔽了問題。
• PsychQuant/word-to-md-swift 現已有 v1.0.0 tag；其 Package.swift 接受 ooxml-swift 2.0.0..<4.0.0，與 macdoc 現行 from: "3.0.0" 相容。

可重現證據：在 origin/main b66d98c 的乾淨 clone 執行 swift test，SwiftPM 在 build planning 前因缺少 packages/word-to-md-swift 結束。

Impact

• 影響的檔案：root Package.swift、更新後的 Package.resolved。
• 影響的使用者流程：fresh clone、CI、repo-wide IDD baseline verification。
• 與 macdoc follows ooxml-swift's main branch instead of the version it declares #162 共用 root package graph／dependency resolution surface，兩者實作必須序列化。

Strategy

• 先保留目前乾淨 clone 的 swift test 失敗輸出作為 RED 證據。
• 把 word-to-md-swift 改回遠端 GitHub dependency，使用已存在且相容的 v1.0.0 下限。
• 重新 resolve package graph，確認沒有 branch-tracking 或本機 path 殘留。
• 在乾淨隔離環境執行 swift package resolve 與 root swift test。
• 檢查 diff 僅包含 manifest／lockfile 的必要變更。

Conflict Class

C_shared_module_coord

共享資源是 root Package.swift 與 Package.resolved；#20、#72、#148、#162 也可能修改同一套 package graph，需相鄰序列化。

Complexity

Simple

Root cause 已確定，production change 是既有遠端 dependency pattern 的小幅復原；同一概念預期只觸及 manifest 與 lockfile。Layer 2／Layer P 未命中。

Risks

• v1.0.0 可能帶入新的 transitive resolution；必須以完整 resolve/test 證明相容。
• 若 lockfile 更新意外升降其他 dependency，需縮回只保留必要 pin 變更。
• 不能用複製本機 ignored package 的方式驗證，否則會再次掩蓋 clean-clone contract。

Residue

(none)

Vagueness Pre-check

• V1: 1 — WHAT 明確指定為讓 clean clone package graph 可解析。
• V4: 2 — Acceptance 有可直接執行的 clean-clone resolve／test命令。
• Triggered: no — both axes ≤ 3
• Hard-gate: not triggered — 同一概念預期只修改 root Package.swift 與 Package.resolved，沒有 ≥5 檔散佈或共用程式抽象。

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

• (none newly filed) macdoc follows ooxml-swift's main branch instead of the version it declares #162 已追蹤同一 root package graph 的 branch/version 漂移；本 issue 只處理 ignored local path 的 clean-clone regression。

[kiki830621]

Implementation Plan

• Preserve the clean-clone swift test failure as RED evidence: SwiftPM cannot access the ignored packages/word-to-md-swift path.
• Replace the obsolete local override with the published PsychQuant/word-to-md-swift dependency from v1.0.0.
• Resolve the graph and record the v1.0.0 revision in Package.resolved.
• Run the full root suite from the isolated clean clone.
• Confirm the diff is limited to Package.swift and Package.resolved.

Path: PR (idd/164-clean-clone-baseline), unattended orchestration.

[kiki830621]

Implementation Complete

Checklist (synced from execution)

• Preserve the clean-clone failure as RED evidence.
• Replace the ignored local WordToMD path with the published remote v1.0.0 dependency.
• Resolve and commit the exact v1.0.0 revision in Package.resolved.
• Run the full root test suite from the isolated clean clone.
• Confirm the diff is limited to the manifest and lockfile.

Changes

• 02193ce — restore clean-clone WordToMD dependency.

Files Changed

• Package.swift
• Package.resolved

TDD evidence

• RED: root swift test stopped before planning because packages/word-to-md-swift did not exist in a clean clone.
• GREEN: root swift test completed with 31 XCTest + 26 Swift Testing tests, 0 failures, 4 environment skips.

Scope Compliance

No unrelated dependency pin changed; #162 remains a separate dependency-governance issue.

Sister Bugs Filed (mid-impl, v2.44.0+ #526)

• (none newly filed) macdoc follows ooxml-swift's main branch instead of the version it declares #162 already tracks the remaining ooxml-swift branch/version drift.

Next: verification complete

[kiki830621]

Verify: #164

Engine

Manual fan-out: 4 independent reviewers (requirements, logic, security, regression) → sequenced Devil’s Advocate → coordinator evidence review.

Process Gap

• The current Codex harness exposes only the GPT/Codex model family for subagents, so this run does not claim Claude-vs-Codex cross-model diversity. Five independent reviewer contexts plus coordinator evidence were used; the limitation is explicit rather than counted as a cross-model PASS.

Frozen snapshot

• Commit: 02193ceeaa4060c6fd1f73ff5310482d3a046f1c
• Diff: 2 files, 10 insertions, 4 deletions
• Freshness: HEAD and diff remained unchanged during review.

Requirements coverage

4 / 4 fully addressed:

1. Clean clone no longer requires the ignored packages/word-to-md-swift directory.
2. Manifest uses the published PsychQuant/word-to-md-swift v1.0.0 range.
3. Lockfile pins v1.0.0 revision 53a451f2f0ed0f769ead03afc7ec9354ef8b6909, matching the remote tag.
4. Scope is limited to Package.swift and Package.resolved.

Test evidence

• swift package resolve: PASS.
• swift package show-dependencies --format json: WordToMD resolves from GitHub at v1.0.0.
• Full swift test: 31 XCTest + 26 Swift Testing, 0 failures, 4 skips.
• git diff --check: PASS.
• Commit auto-close trailer scan: no hit.

Findings

Severity	Finding	Action
—	Requirements, logic, security, and regression reviewers found no defects.	PASS
—	Devil’s Advocate could not refute the PASS after checking identity, tag/revision, OOXML constraints, local-vs-remote source parity, and clean-clone resolution.	PASS

Scope Check

No scope creep. The remaining ooxml-swift branch pin is pre-existing and tracked by #162.

Verdict

verify-gated PASS — 0 blocking, 0 follow-up. Ready for human PR review; this workflow does not merge or close the issue.