git log --grep="#N" false-positives on upstream oMLX issue numbers (tangential from #2)

[kiki830621]

Problem

這個 repo 的 issue 編號是個位／兩位數，而它引用的上游 oMLX issue 編號是四位數
（#2715、#2716、#2349），散布在 README.md、CLAUDE.md、bin/claude-local 註解與
commit message 裡。於是任何用 git log --grep="#N" 找「引用本 issue 的 commit」的工具，對小
編號都會誤中：

$ git log --oneline --grep="#2"
93a7622 docs: distinguish the two ways to use a local model, and ship the usage-1 wrapper

$ git log -1 --format=%B 93a7622 | grep -o '#[0-9]*' | sort -u
#2715
#2716

93a7622 完全沒有引用 issue #2 —— 它是被 #2715 / #2716 的前綴命中的。正確查法：

$ git log --oneline --grep='#2\([^0-9]\|$\)'
(0 筆)

Type

docs

Expected

CLAUDE.md 加一段短警告：本 repo 找「引用某 issue 的 commit」時必須用帶邊界的 pattern
（'#N\([^0-9]\|$\)'），因為上游 oMLX 的四位數 issue 編號會讓裸 #N 產生假陽性。

Actual

沒有任何地方記載這件事。實際踩到的時點是 2026-08-17 跑 /idd-update #2 的 Step 3
（Related Commits），差一步就把 93a7622 當成 #2 的相關 commit 寫進 issue body。

Impact

方向不對稱，而且錯的那一邊是安靜的。 假陽性會讓 issue 的 Related Commits 出現一筆與它
無關的 commit——沒有任何錯誤訊息，讀的人也沒有理由懷疑。idd-close 的 closing summary 蒐集
related commits 時走同一條路，所以這個假資料會被寫進審計軌跡。

編號會持續碰撞：本 repo 走到 #23 / #27 / #234… 時，#2349 / #2715 / #2716 仍在文件裡。
這不是一次性巧合，是這個 repo 長期的性質。

Source: surfaced during /idd-plan #2 tangential sweep (Step 2.5)

Clarity Surface

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

---

Current Status

Phase: verified
Last updated: 2026-09-01 by idd-all (direct-commit, attended)

Key Decisions

• issue 把成因歸給上游，實測顯示主因是本地：裸 --grep="#1" 12 筆全錯，全來自本 repo 自己的 A user-supplied --settings lands after ours and nothing detects it #10-make test-headed has a runner but no trigger — nothing reaches it without a person remembering (residue from #17) #18；上游只佔 #2 的 2 筆
• 文件刻意以本地成因開頭 — 上游框架會誘導出「沒引用 oMLX 就安全」的錯誤推論
• 點名活的 consumer：idd-close Step 1／1.6 與 idd-list PR scan（後者今天現場撞到）
• 誠實邊界：這是文件修正，沒有修好那些工具（它們住在 IDD plugin）

Scope Changes

• (none)

Blocking

• (none) — verified, awaiting close

Commits

299f4e8 docs: git log --grep="#N" needs a boundary here, and the cause is local (#5)

[kiki830621]

Diagnosis

Type

docs

Root Cause / Analysis

The premise holds, and the issue understates it in two ways. Measured against the current
history rather than the state it was filed in:

query	bare --grep="#N"	boundary-anchored	false positives
#1	12	0	12 — all of them
#2	23	21	2
#4	1	1	0
#9	1	1	0

Understatement 1 — the dominant cause is local, not upstream. The issue attributes this to
oMLX's four-digit numbers. Those account for the two #2 false positives. Every one of #1's
twelve comes from this repository's own issues — #10, #11, #12, #13, #16, #17,
#18. The repo crossed into two digits and started colliding with itself. Upstream made the
problem visible; local numbering made it the norm.

Understatement 2 — there is a live consumer, and it is IDD's own tooling. idd-close
Step 1 runs git log --oneline --grep="#$NUMBER" to answer "are there commits referencing this
issue", and Step 1.6's semantic gate uses the same query to check that a - [x] bullet has
backing commits. For #1 that returns twelve unrelated commits. The gate would report a
well-supported issue and be wrong about every line of its evidence.

idd-list's PR-ref scan is a second consumer, hit live in this session: PR #7's cluster was
computed as #2 #6 #2715 #2716, pulling two upstream numbers in as if they were local issues.

Impact

• CLAUDE.md — a short warning with the correct pattern
• No code changes here. The tooling consumers live in the IDD plugin, not this repo; naming
  them is what a future reader needs.

Strategy

• Add the warning to CLAUDE.md with the boundary-anchored pattern
• Lead with the local cause — an upstream-only framing invites "we don't cite oMLX in
  this commit, so a bare grep is fine", which is false
• Give the measured numbers, not an assertion — #1 returning 12/12 wrong is the argument
• Name the consumers (idd-close Step 1 and 1.6, idd-list PR scan) so the reader knows
  this is not hypothetical
• Verify the recommended pattern actually returns 0 for #1

Conflict Class

A_parallel_safe — one documentation file, no shared mutable resource.

Complexity

Simple

Risks

• Writing it as an upstream quirk. That was the issue's framing and it is the wrong lesson:
  a reader would conclude the bare form is safe in commits that do not mention oMLX, and #1's
  twelve false positives are all from commits that do not.
• Documenting the pattern without naming the consumers. A warning nobody connects to a tool
  they actually run gets read as trivia.

Residue

The fix here is documentation; the tooling that has the bug lives in the IDD plugin and is not
this repo's to change. Writing the warning does not stop idd-close from returning twelve wrong
commits for #1 — it only means whoever reads the output has a chance of recognising it.
Naming that so "documented" is not read as "fixed".

[kiki830621]

Implementation Complete

Checklist

• CLAUDE.md 加上帶邊界的 pattern 警告
• 以本地成因開頭，而非上游 — 上游框架會讓人推論「這個 commit 沒引用 oMLX 所以裸 grep 安全」，而 Evaluate delegation quality, not just code correctness — the 18 existing tests are all stubbed #1 的 12 筆假陽性全來自沒引用 oMLX 的 commit
• 給實測數字而非斷言 — #1 12 筆全錯是整個論證
• 點名 consumer（idd-close Step 1 與 1.6、idd-list PR scan）
• 驗證推薦的 pattern 對 #1 真的回 0

Commits

-—299f4e8 docs: git log --grep="#N" needs a boundary here, and the cause is local (#5)

[kiki830621]

Verify

Result: PASS

#	Check	Result
1	裸 --grep="#1"	12 筆
2	文件推薦的帶邊界形式	0 筆 — 12/12 皆為假陽性
3	假陽性來源	本 repo 自己的 #10 #11 #12 #13 #16 #17 #18，非上游
4	#2 的上游成因	2 筆（#2715/#2716），是較小的一半
5	make test	✓

誠實邊界：這是文件修正，不是修好那些工具。idd-close 與 idd-list 的 bug 住在 IDD plugin，不是本 repo 能改的。文件只讓讀到那些輸出的人有機會認出數字是錯的 — 這點在 CLAUDE.md 的段落裡也明寫了。

Verification method

6-AI ensemble 未跑（本 session 有「未經要求不呼叫 review agent」的限制）；上表每一列都是有可檢查輸出的指令。