Skip to content

來源受理 #2:端點寫成純 URL、method 在散文裡——窄化辨識規則 #97

Description

@CarlLee1983

來源受理面盤點(2026-08-16 grill)排序第 2 名。頻率極高(十三案中八案),靜默度高(有警告但不擋,且已噪音化)。

現況

九個帶 SOURCE_FACTS_UNSCANNED 的 benchmark case 中有八個是同一個形狀:來源是結構良好的 Markdown,但端點寫成純 URL,method 只出現在散文裡(綠界、藍新、TapPay 皆是)。見 docs/RELEASE_NOTES_0.36.0.md:44-54docs/adr/0007-...md:19-29

也就是說語意完備性 gate 對實際母體的大多數是空轉的,而原因不是格式——這些來源的結構完全倖存,是端點宣告寫法不匹配 METHOD /path 這個鍵。

兩份 ADR 目前互相矛盾

  • ADR 0007 拒絕辨識這類寫法,理由是那需要「推論 method」(docs/adr/0007-...md:40-43)。
  • ADR 0009 對 GitBook 的 `GET` + `/a` 配對做出相反判斷,標為 "A gap, not a decision",並寫明「出現一份使用該寫法的來源就是補洞的觸發點」(docs/adr/0009-...md:52-58)。

0007 隱含地把「推論 method」與「method 字面上就寫在旁邊、只是沒排成 METHOD /path」當成同一件事,0009 沒有。母體裡有八份使用近親寫法的來源,0009 的觸發條件實質上已經成立,只是當初它的視野限在 GitBook。

決定(grill 定案)

窄化重開:只放寬到同行內同時出現完整 URL 與大寫 HTTP method 字面值才算端點宣告,不匹配就維持沉默。明確否決放寬到散文推論——假 fact 會擋掉正確的 extraction,那是比 gate 空轉更壞的失敗方向。

用新 ADR 補充 0007,不 supersede:0007 的核心主張(不推論 method、不擴大到啟發式)在窄化方案下依然成立,supersede 會讓後人以為那個立場被推翻。新 ADR 要回答 0007 沒回答的問題——字面上寫著 method 但沒排成 METHOD /path,算不算「推論」——並把 0009 那格標為已觸發。不改 0007 內文(會讓落款日期與其主張對不上)。

注意:這個改動不觸發 0007 的證偽條件(仍只吃 Markdown,fact_coverage.py 仍照常回報),只是範圍變了。

不新增 benchmark case:用既有八案當實測基線——它們是真實來源、真實形狀,且現狀是已知的失敗基線,改動後有幾案警告消失就是實測效果。新增 case 需要新的真實快照與 operator 本機 source-quality/ 包,成本高而證明力不增。

正反例釘進單元測試:比照 tests/source_facts/test_scanner_divergence.py 釘 ADR 0009 的做法。benchmark 只告訴你警告消失了,不告訴你哪些寫法被接受、哪些被拒絕——而窄且可證偽正是這個方案的全部重點,那條線該釘在測試裡而不是活在 ADR 散文中。

產出

  • source_facts/markdown.py 的窄化辨識規則
  • 正反例單元測試(釘住邊界)
  • ADR:補充 0007,顯性化與 0009 的矛盾並選邊
  • 更新 docs/adr/0009 該格為已觸發
  • 既有八案的 SOURCE_FACTS_UNSCANNED 前後對照
  • 同 commit 更新 AGENTS.md 相關段落

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions