Skip to content

akashic-discovery 的 akashic-work-references 依賴 CLI 的 references 契約,開 session 時沒有過期提示 (sister concern from #775) #776

Open

Description

@kiki830621

Problem

#775 要給 akashic-mcp plugin 加 SessionStart 檢查,在 akashic CLI 過期或 fulltext contract 不足時提示。同一個 CLI 還有另一個依賴它的 skill,住在另一個 plugin 根:plugins/akashic-discovery 的 akashic-work-references。

它在「開始前」第 1 點要求 akashic references extract 輸出的 contract 恰好是 10(ReferenceListExtractor.contractVersion),比 10 小或比 10 大都停。這個數字目前只有跑到那一步才看得到:

  • CLI 沒有像 akashic fulltext contract 那樣唯讀、不需要輸入檔的契約查詢子命令;要知道版本,得先餵一份全文跑 extract。
  • akashic CLI 過期時沒有提示:比照 safari-browser 加 SessionStart 檢查 #775 的 hook 照 issue 字面放在 akashic-mcp plugin(plugin/),只比 fulltext contract。CLI 的 references 契約跟不上 akashic-discovery 的 SKILL 時,開 session 不會有任何提示。

Type

feature

Expected

  1. CLI 提供一個唯讀、不碰網路、不讀寫檔案的 references 契約查詢(形狀比照 fulltext contract)。
  2. akashic-discovery 有 SessionStart 檢查(或 akashic CLI 過期時沒有提示:比照 safari-browser 加 SessionStart 檢查 #775 的 hook 涵蓋兩個 plugin 根):CLI 的 references 契約不等於 SKILL 要求的值時,說出兩個數字。要求的值只有一份來源(SKILL「開始前」第 1 點),不在 hook 裡另寫一份。
  3. 「CLI 落後原始碼」的提示若已由 akashic CLI 過期時沒有提示:比照 safari-browser 加 SessionStart 檢查 #775 的 hook 印出,這裡不重複印。

Related

Source: surfaced during /idd-diagnose #775 sister concern surfacing (Step 3.6)

Current Status

Phase: diagnosed
Last updated: 2026-11-16 by idd-diagnose

Key Decisions

  • 新增唯讀 akashic references contract(比照 fulltext contract),進 WriteGateRulings 與 CLI-only 裁決表
  • Hook 放置 unattended 預設 A:discovery 的 hooks/ symlink 共用 check-cli.sh、依 plugin 根分流(Choice Default Record,待人確認)
  • references 契約比「不等於」並印兩個數字;建置指示(SKILL、README)改經戳記腳本
  • Complexity: Plan(hard-gate 觸發)

Scope Changes

  • 併入兩則 comment 的建置指示對齊(SKILL 第 20 行、README 第 487 行)

Blocking

Commits

  • (none)

Activity

  1. kiki830621 commented on Nov 10, 2026

    @kiki830621
    MemberAuthor

    Note(2026-11-10):同一份 SKILL 的建置指示也與 akashic-mcp 分岔

    #775 的 verify(PR #783,finding 15:https://github.com/PsychQuant/Akashic-Library/pull/783#issuecomment-6761585437)發現 plugins/akashic-discovery/skills/akashic-work-references/SKILL.md:20 仍叫人用裸 swift build 並「放上 PATH」。#775 把 akashic-mcp 的建置指示改成經 scripts/stamp-version.sh、以 install -m 755 放回原位;照 akashic-discovery 這份建出來的 CLI 印 unknown,#775 的 hook 只能改比檔案時間。處理本 issue 的契約時,一併把建置指示對齊。

  2. kiki830621 commented on Nov 12, 2026

    @kiki830621
    MemberAuthor

    從 #775 結案時的 doc-sync 帶過來的一處(2026-11-12):README.md 的 akashic-discovery 一段寫「CLI 要在本 repo swift build -c release 後自行放上 PATH」。#775 之後,沒有經過 scripts/stamp-version.sh 建出的 CLI,--version 會印 unknown,akashic-mcp 的 SessionStart hook 只能改比檔案時間。處理這張 issue 時,這句建置指示可以一併改成經戳記腳本(同 akashic-fetch-fulltext SKILL 第 0 步)。見 #775 的結案摘要:#775 (comment)

  3. kiki830621 commented on Nov 16, 2026

    @kiki830621
    MemberAuthor

    Diagnosis

    Type

    feature(label 無 type;本文 ## Type 寫 feature)

    Root Cause / Analysis

    需求拆成四件,前兩件對應 Expected 1–2,後兩件是 issue 兩則 comment 帶進來的建置指示對齊:

    1. CLI 沒有唯讀的 references 契約查詢。 ReferenceListExtractor.contractVersion(現值 10)只出現在 references extract/nominate 的 JSON 輸出裡;fulltext 那一側有 FulltextContractCmd(印 fulltext-contract <N>,唯讀、不讀寫檔)。要比照它加 references contract(印 references-contract <N>)。新葉命令要同時進 WriteGateRulings(.readOnly,WriteGateRulingsTests 會對執行期命令樹雙向比對,漏了即紅)與 docs/rulings/mcp-cli-parity.md 的 CLI-only 表(同 references extract/nominate 的理由:skill 的中間運算,無 MCP 面)。
    2. akashic-discovery 沒有 SessionStart 檢查。 plugin/hooks/check-cli.sh 只讀 ${PLUGIN_ROOT}/skills/akashic-fetch-fulltext/SKILL.md 第 0 步的 needle("${v#fulltext-contract }" -ge ),只比 fulltext contract,且比較是 ≥。akashic-work-references「開始前」第 1 點要求的是恰好 10、兩個方向都停——hook 要比「不等於」,並說出兩個數字。要求值的唯一來源是那一點,目前寫成散文(「contract 要恰好是 10」),hook 要從 SKILL 抽;為了抽得穩,那一句最好改成和 fulltext 第 0 步一樣帶一段可唯一比對的指令(例如第 1 點直接寫出 akashic references contract 的比較式),否則 needle 會綁在散文措辭上。
    3. Expected 3(不重複印「CLI 落後原始碼」)決定了 hook 放哪裡。 候選見 Strategy 的決策點;每一種都牽涉 swift-is-the-implementation-language 例外 1:check-cli.sh 是以具名例外列入的含判斷殼層,規則寫明「下一支想援用這個例外的殼層,要在這裡另外加列」,所以在 plugins/akashic-discovery/ 新寫一支 hook 需要改規則(使用者裁決);共用同一支檔則不新增殼層。
    4. 兩處建置指示仍是裸 swift build:plugins/akashic-discovery/skills/akashic-work-references/SKILL.md 第 20 行(「開始前」第 1 點)與 README.md 第 487 行。照它們建出的 CLI --version 印 unknown,hook 只能改比檔案時間。對齊成經 scripts/stamp-version.sh 建置、install -m 755 放回原位(同 akashic-fetch-fulltext SKILL 第 0 步)。

    Existing work

    Impact

    • 影響的檔案(估計):Sources/akashic/ReferencesCommands.swift、Sources/akashic/WriteGateRulings.swift、plugin/hooks/check-cli.sh、akashic-discovery 的 hook 設定(plugins/akashic-discovery/hooks/)、plugins/akashic-discovery/skills/akashic-work-references/SKILL.md、README.md、兩個 plugin 根的 plugin.json 與 .githooks/plugin-shell-versions.txt、docs/rulings/mcp-cli-parity.md、測試(Tests/AkashicCLITests/CheckCLIHookTests.swift 與 references 指令測試)。
    • 影響的使用者流程:開 session 時的 CLI 過期提示;work-references「開始前」第 1 點的檢查方式。

    Strategy

    決策點(unattended 取了預設,見下方 Choice Default Record):akashic-discovery 的檢查放在哪裡。

    • A(預設):plugins/akashic-discovery/hooks 以 symlink 指向 ../../plugin/hooks(比照既有的 plugins/akashic-discovery/rules → ../../plugin/rules),同一支 check-cli.sh 依 PLUGIN_ROOT 底下存在哪一份 SKILL 決定比哪個契約;在 discovery 根下只比 references 契約、不跑「CLI 落後原始碼」那一段(akashic-discovery 的 dependencies 是 akashic-mcp,後者的 hook 會印)。不新增殼層檔。
    • B:akashic-mcp 的 hook 一併找 sibling plugin 的 SKILL。安裝後兩個 plugin 在不同的 cache 位置,路徑推導脆弱。
    • C:discovery 自己一支新 hook。要改 swift-is-the-implementation-language 例外 1(使用者裁決),且兩支會重複「落後原始碼」邏輯。

    步驟(以 A 為準):

    • references contract 子命令(唯讀,印 references-contract <N>)+ WriteGateRulings 的 .readOnly 一格 + CLI-only 裁決表一列 + 指令測試
    • work-references SKILL「開始前」第 1 點:改用 references contract 檢查(缺子命令=舊 CLI),寫成 hook 可唯一比對的形狀;建置指示改經戳記腳本
    • check-cli.sh:依 plugin 根分流;references 比「不等於」並印兩個數字;needle 抽不到要說出來、不當通過;discovery 根下跳過原始碼比對
    • discovery 的 hooks/ symlink 與 hooks.json
    • CheckCLIHookTests:兩個根、各三種情形(相等、小於、大於)與 needle 抽不到
    • README 第 487 行
    • 兩個 plugin 根升版、plugin-shell-versions.txt 加列(合併前後各查 main 一次,避免與 feat(discovery): 新增唯讀 OpenAlex 被引候選搜尋(#620) #758 撞號)

    Conflict Class

    C_shared_module_coord — 與 draft PR #758 共用 plugins/akashic-discovery/.claude-plugin/plugin.json 的版號與 .githooks/plugin-shell-versions.txt(只增的版號表),且 plugins/akashic-discovery/** 在 repo 記錄裡仍由 #617 持有。

    Complexity

    Plan

    Hard-gate: triggered — 同一個概念(references 契約的單一來源與比對)散佈到 ReferencesCommands.swift、WriteGateRulings.swift、check-cli.sh、work-references SKILL.md、CheckCLIHookTests.swift、兩個 plugin.json 與 plugin-shell-versions.txt,超過 5 檔。
    Layer P:decision-heavy(hook 放置 A/B/C 三種做法,影響檔案形狀);觸及 backward-compat(舊 CLI 沒有 references contract,SKILL 與 hook 要把 64 當成舊版)。

    Risks

    • symlink 的 hooks/ 在 plugin 安裝後是否保留、CLAUDE_PLUGIN_ROOT 指向哪裡:既有的 rules symlink 有出貨,但 hook 經 symlink 執行未量測。量法:本機 claude plugin install 後看 cache 裡的 hooks/check-cli.sh 是否可執行,開一個 session 看 SessionStart 輸出。
    • akashic-mcp 被停用而 discovery 啟用時,A 方案在 discovery 根下不印「落後原始碼」,那一句就沒人印。可接受或改成「akashic-mcp 未啟用時才印」,待實作時定。
    • SKILL 要求值若仍寫成散文,hook 的 needle 綁在措辭上,改句子就靜默失效(需要「抽不到就說出來」那一行兜底)。
    • swift-is-the-implementation-language 例外 1 的具名理由(判斷對象是 binary 本身)對 references 契約同樣成立,但 check-cli.sh 判斷變多,是否仍屬那個例外由驗證時確認。

    Residue

    (none)

    Vagueness Pre-check

    • V1: 2 — Expected 1–3 逐條寫出要什麼(唯讀契約查詢、形狀比照 fulltext contract、hook 比較「不等於」並說兩個數字、不重複印落後提示),兩則 comment 又具名了兩處建置指示的行號。
    • V4: 3 — 完成定義可檢查(契約子命令存在、hook 在不相等時印兩個數字),但 hook 的放置(Expected 2 寫「或」)留給實作選。
    • Triggered: no — both axes ≤ 3
    • Hard-gate: triggered — 見 Complexity

    Choice Default Record

    • Reason: unattended-auto-Step-4-choice-default
    • Decision: akashic-discovery 的 SessionStart 檢查放在哪裡
    • Options: A symlink 共用 plugin/hooks/check-cli.sh、依 plugin 根分流;B akashic-mcp 的 hook 去找 sibling plugin;C discovery 自己一支新 hook(需改 swift-is-the-implementation-language 例外 1)
    • Default taken: A。不新增殼層檔、不需要改規則,沿用既有 rules symlink 的做法;「落後原始碼」只由 akashic-mcp 根印,符合 Expected 3。這是在 Plan 階段仍可改的設計選擇,沒有寫入任何東西。

    Blocking

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

    • PR feat(discovery): 新增唯讀 OpenAlex 被引候選搜尋(#620) #758 新增的 akashic-work-cited-by 也會依賴 CLI 的 cited-by 子命令與它的契約,同一個過期提示問題會再出現一次。本 issue 的 hook 設計若做成「依 plugin 根底下的 SKILL 逐一比對」即涵蓋;不另開(unattended 下 §5.4 implicit (a) skip,且已納入本 issue 的設計要求)。

    Source: /idd-diagnose #776(batch,unattended)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions