## 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`。 - #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 檢查(或 #775 的 hook 涵蓋兩個 plugin 根):CLI 的 `references` 契約不等於 SKILL 要求的值時,說出兩個數字。要求的值只有一份來源(SKILL「開始前」第 1 點),不在 hook 裡另寫一份。 3. 「CLI 落後原始碼」的提示若已由 #775 的 hook 印出,這裡不重複印。 ## Related - #775:akashic-mcp plugin 的同一件事(`fulltext` 契約)。兩張可以共用 hook 的程式,但 plugin 根不同,`plugin-shell-version` 守衛要各自升版。 - #633:CLI 沒有發布管道。 **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 - `plugins/akashic-discovery/**` 由 #617 持有——#617 結案或使用者同意後才實作 - draft PR #758 改同一個 plugin.json 與版號表——合併/關閉後再升版,或照撞號程序處理 - hook 放置(A/B/C)待使用者確認 ### Commits - (none)
Activity
kiki830621 commentedon Nov 10, 2026
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 的契約時,一併把建置指示對齊。kiki830621 commentedon Nov 12, 2026
從 #775 結案時的 doc-sync 帶過來的一處(2026-11-12):
README.md的 akashic-discovery 一段寫「CLI 要在本 reposwift build -c release後自行放上 PATH」。#775 之後,沒有經過scripts/stamp-version.sh建出的 CLI,--version會印unknown,akashic-mcp 的 SessionStart hook 只能改比檔案時間。處理這張 issue 時,這句建置指示可以一併改成經戳記腳本(同akashic-fetch-fulltextSKILL 第 0 步)。見 #775 的結案摘要:#775 (comment)kiki830621 commentedon Nov 16, 2026
Diagnosis
Type
feature(label 無 type;本文
## Type寫 feature)Root Cause / Analysis
需求拆成四件,前兩件對應 Expected 1–2,後兩件是 issue 兩則 comment 帶進來的建置指示對齊:
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 面)。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 會綁在散文措辭上。swift-is-the-implementation-language例外 1:check-cli.sh是以具名例外列入的含判斷殼層,規則寫明「下一支想援用這個例外的殼層,要在這裡另外加列」,所以在plugins/akashic-discovery/新寫一支 hook 需要改規則(使用者裁決);共用同一支檔則不新增殼層。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-fulltextSKILL 第 0 步)。Existing work
unknown:orchestrator 跑過的查詢中,merged-PR 清單碰到 100 筆上限;沒有 open PR 或idd/776-*branch 引用本 issue。feat/620-work-cited-by)改到plugins/akashic-discovery/.claude-plugin/plugin.json與.githooks/plugin-shell-versions.txt,兩者本 issue 也要改。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 指令測試)。Strategy
決策點(unattended 取了預設,見下方 Choice Default Record):akashic-discovery 的檢查放在哪裡。
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 會印)。不新增殼層檔。swift-is-the-implementation-language例外 1(使用者裁決),且兩支會重複「落後原始碼」邏輯。步驟(以 A 為準):
references contract子命令(唯讀,印references-contract <N>)+WriteGateRulings的.readOnly一格 + CLI-only 裁決表一列 + 指令測試references contract檢查(缺子命令=舊 CLI),寫成 hook 可唯一比對的形狀;建置指示改經戳記腳本check-cli.sh:依 plugin 根分流;references 比「不等於」並印兩個數字;needle 抽不到要說出來、不當通過;discovery 根下跳過原始碼比對hooks/symlink 與hooks.jsonCheckCLIHookTests:兩個根、各三種情形(相等、小於、大於)與 needle 抽不到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-referencesSKILL.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
hooks/在 plugin 安裝後是否保留、CLAUDE_PLUGIN_ROOT指向哪裡:既有的rulessymlink 有出貨,但 hook 經 symlink 執行未量測。量法:本機claude plugin install後看 cache 裡的hooks/check-cli.sh是否可執行,開一個 session 看 SessionStart 輸出。swift-is-the-implementation-language例外 1 的具名理由(判斷對象是 binary 本身)對 references 契約同樣成立,但check-cli.sh判斷變多,是否仍屬那個例外由驗證時確認。Residue
(none)
Vagueness Pre-check
fulltext contract、hook 比較「不等於」並說兩個數字、不重複印落後提示),兩則 comment 又具名了兩處建置指示的行號。Choice Default Record
plugin/hooks/check-cli.sh、依 plugin 根分流;B akashic-mcp 的 hook 去找 sibling plugin;C discovery 自己一支新 hook(需改swift-is-the-implementation-language例外 1)rulessymlink 的做法;「落後原始碼」只由 akashic-mcp 根印,符合 Expected 3。這是在 Plan 階段仍可改的設計選擇,沒有寫入任何東西。Blocking
plugins/akashic-discovery/**在 repo 記錄裡由 新 skill akashic-work-references(akashic-discovery plugin):往回——從一篇作品的參考文獻找出該補進 library 的論文,驗證建檔並寫入 relations.cites #617 持有(新 skill akashic-work-references(akashic-discovery plugin):往回——從一篇作品的參考文獻找出該補進 library 的論文,驗證建檔並寫入 relations.cites #617 仍 open;web-access-via-safari-browser規則與 同步 web-access.md 與 akashic-work-references 的外部取得程序(鎖法、中止條款、形狀表) #687 都記著要等 新 skill akashic-work-references(akashic-discovery plugin):往回——從一篇作品的參考文獻找出該補進 library 的論文,驗證建檔並寫入 relations.cites #617 釋出這個目錄)——新 skill akashic-work-references(akashic-discovery plugin):往回——從一篇作品的參考文獻找出該補進 library 的論文,驗證建檔並寫入 relations.cites #617 結案或使用者同意動這個目錄後才能實作。plugin.json與版號表——feat(discovery): 新增唯讀 OpenAlex 被引候選搜尋(#620) #758 合併或關閉後再升版,或實作時照撞號程序處理。Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)
akashic-work-cited-by也會依賴 CLI 的cited-by子命令與它的契約,同一個過期提示問題會再出現一次。本 issue 的 hook 設計若做成「依 plugin 根底下的 SKILL 逐一比對」即涵蓋;不另開(unattended 下 §5.4 implicit (a) skip,且已納入本 issue 的設計要求)。Source: /idd-diagnose #776(batch,unattended)