Skip to content

akashic CLI 過期時沒有提示:比照 safari-browser 加 SessionStart 檢查 #775

Closed

Description

@kiki830621

Problem

Original text(maintainer,2026-11-09):
「CLI也要有根safari-brwoser一樣的更新機制吧」

akashic CLI 在本機沒有任何「是不是過期了」的提示。#768 合併後,SKILL 要求 fulltext contract 8,本機的 CLI 卻還是 10 月底建的、只印 6。這件事是在準備跑全文批次、主動去問另一個 session 時才發現的:開 session 時沒有任何訊息,fetch 也還沒跑到。若沒有人問,第一個訊號會是 SKILL 第 0 步拒絕執行,或者更糟,用舊 CLI 跑了。

safari-browser 已有這個機制(plugin 的 SessionStart hook hooks/check-cli.sh):

  • binary 的 --version 印出它建置時的 git describe
  • hook 把它和本機原始碼 checkout 的歷史比,落後就印出「落後 N 個 commit」和安裝指令
  • 不連網、不自動覆蓋已能用的 binary;squash merge、checkout 落後、在別處建置這些情況都有處理(改比檔案時間)

Type

feature

Expected

  1. akashic --version(或同等子命令)印出建置時的 commit(git describe),舊版 CLI 不支援時 hook 要能分辨。
  2. akashic-mcp plugin 加一個 SessionStart hook,比照 safari-browser 的 check-cli.sh:
    • 找不到 CLI:印安裝指令
    • CLI 比原始碼落後:印「落後 N 個 commit」與重建指令(swift build -c release --product akashic,再放到原本的位置)
    • CLI 印出的 fulltext contract 比 plugin 內 SKILL 要求的小:明確說出兩個數字
    • 不連網、不自動安裝
  3. 原始碼 checkout 的位置可設定;沒有 checkout 時只做第 3 點的契約比對。

Actual

本機 CLI 落後時沒有任何提示;契約版本要靠 SKILL 第 0 步或人主動檢查才看得到。

Related


Current Status

Phase: closed
Last updated: 2026-11-12 by idd-close
Dashboard: #775 (comment)

Key Decisions

Scope Changes

Blocking

Commits

Activity

  1. kiki830621 commented on Nov 9, 2026

    @kiki830621
    MemberAuthor

    Diagnosis

    Type

    feature

    Root Cause / Analysis

    現況(2026-11-09 量)

    • ~/bin/akashic 是 2026-10-28 建置的。akashic --version 回 Error: Unknown option '--version'、結束碼 64(ArgumentParser 的用法錯誤);akashic fulltext contract 印 fulltext-contract 6、結束碼 0。
    • origin/main 的 FulltextFetch.contractVersion 是 8;plugin/skills/akashic-fetch-fulltext/SKILL.md 第 0 步要求 -ge 8。
    • akashic-mcp plugin(plugin/)沒有 hooks/ 目錄,也就是沒有任何 SessionStart 檢查。

    需求拆解

    1. CLI 說得出自己是哪一次建置:akashic --version 印建置時的 commit;沒有戳記的建置印 unknown;舊 CLI 回 64,hook 據此分辨。
    2. akashic-mcp plugin 加 SessionStart hook,比照 safari-browser 的 hooks/check-cli.sh:找不到 CLI、落後原始碼、契約不足三種情形各自印出;不連網、不自動安裝、不覆蓋現有 binary。
    3. 原始碼 checkout 的位置可設定;沒有 checkout 時只比契約。

    與 safari-browser 不同、要在 plan 階段裁決的五點

    # 問題 候選 代價
    a 比對基準 safari-browser 比 checkout 的 HEAD。這個 repo 的工作在 worktree 與 PR 上進行,主 checkout 不常 pull:本機主 checkout 的 main 實測落後 origin/main 308 個 commit。候選:比 refs/remotes/origin/main(不連網,fetch 過就新),沒有這個 ref 時退回 HEAD,訊息寫明用的是哪一個 沒 fetch 時同樣落後;比 HEAD 則在這個 repo 幾乎恆落後
    b 編譯輸入的範圍 Sources、Package.swift、Package.resolved、submodule repos/biblatex-apa-swift(AkashicExport 依賴它)。Sources 也含 akashic-mcp、AkashicAppKit、akashic-guards、tractatus-doc 等不進 CLI 的 target 接受過報(只動那些 target 的 commit 也算「落後」),訊息寫「動到 package 原始碼」;或維護一份排除清單(會與 Package.swift 分岔)
    c 建置戳記的方法 A:照 safari-browser,包裝腳本在建置期間把 git describe 寫進受追蹤的佔位檔、建完還原。B:連結時以 -Xlinker -sectcreate 放進 Mach-O section,執行時以 getsectiondata 讀 A 已在 safari-browser 驗證;建置期間有一個受追蹤檔被改著(共用工作樹時可能被別的 commit 掃進去),且每次都重編 akashic module。B 不碰任何受追蹤檔;兩個 repo 都沒用過,SwiftPM 的增量連結行為要量
    d 裸 swift build SKILL 現有的建置指示是裸的 swift build -c release --product akashic,不經包裝,建出的 CLI 印 unknown 改 SKILL 的建置指示改用包裝腳本,或接受 unknown、由 hook 走檔案時間
    e 殼層規則 戳記包裝與 hook 都只能是 shell:hook 要在 binary 不存在或過舊時判斷那個 binary,判斷者不能是被判斷的 binary。swift-is-the-implementation-language 例外 1 目前「恰為四個檔」,且要求「只做串接」;hook 含判斷(祖先關係、檔案時間退路、契約比對) 要顯式修改例外 1、寫明理由(CLAUDE.md Rules 第 2 條),不能從既有四個檔類推

    契約要求的數字只能有一份:目前只寫在 SKILL 第 0 步的 -ge 8。hook 若另寫一個 8,就是 no-compat-fallback 說的第二份描述。候選:hook 從 plugin 內的 SKILL 抽出那個數字(要有測試釘住抽取與 SKILL 一致、抽不到時具名說出來),或 SKILL 與 hook 改讀同一個資料檔(要動 SKILL)。

    Existing work

    • unknown:check-existing-work.sh 的 merged PR 清單到了上限 100,更早的 merged PR 沒有查。沒有 open PR 引用 akashic CLI 過期時沒有提示:比照 safari-browser 加 SessionStart 檢查 #775。
    • 另一條工作線先前開過 branch idd/775-cli-stale-check,停在閱讀階段、沒有任何改動;本機 branch 與 worktree 已刪,遠端從沒有過。本次在同名 branch 上從頭開始(從 origin/main dad21f86 分出)。

    Impact

    • 新增:plugin/hooks/hooks.json、plugin/hooks/check-cli.sh、CLI 的版本旗標(Sources/akashic/)、建置戳記腳本、Swift 測試(Process 執行 hook,假 HOME、假 checkout、假 CLI;不新增 shell 或 Python 測試)。
    • 修改:plugin/.claude-plugin/plugin.json(升 version)、.githooks/plugin-shell-versions.txt(加一列)、plugin/CHANGELOG.md、.claude/rules/swift-is-the-implementation-language.md(例外 1)、docs/rulings/mcp-cli-parity.md(--version 的兩面裁決:它是 CommandConfiguration(version:) 的旗標,既不是 subcommand 也不是 ParsableArguments,三種稽核都枚舉不到,要手動加列;MCP 面的對應物是 wrapper 依 binary_version 下載),視 (d) 的裁決改 SKILL 第 0 步的建置指示。
    • 使用者流程:每個 Claude Code session 開始時,akashic-mcp plugin 印一行 CLI 狀態,過期時多幾行。推上 main 就是發布 plugin(本 repo 是 marketplace)。
    • 不動 ~/bin/akashic,不取代 [feature] akashic CLI 沒有發布管道,但依賴它的 skill 已有 5 個 (tangential from #617) #633。

    Strategy

    • plan 階段裁決 (a)–(e) 與契約數字的來源
    • CLI:CommandConfiguration(version:) 讀建置戳記,沒有戳記印 unknown
    • 建置戳記腳本:git describe --always --dirty(排除 idd-*-baseline 等 tag)、戳記、swift build -c release --product akashic、印出 bin 路徑;不安裝
    • hook:探測 --version(4 秒上限、自己的 process group、暫存檔在任何結束方式下都清掉);比對 (a) 選定的基準;比不出祖先關係時說明原因並退回比檔案時間;比 fulltext contract 與 SKILL 要求的數字;沒有 checkout 時只比契約;任何失敗都 exit 0
    • hooks.json、plugin.json 升版、版號表加列、plugin/CHANGELOG.md
    • 規則例外 1、mcp-cli-parity 裁決列
    • Swift 測試:缺 CLI、舊 CLI(--version 回 64)、落後 N 個 commit、squash 之後內容相同、checkout 比建置舊、印 unknown、契約不足、沒有 checkout、--version 卡住
    • 跑 plugin-shell-version、official-validate 等守衛與相關測試

    Conflict Class

    B_resource_serialize — 共享資源:plugin/.claude-plugin/plugin.json 的 version 與 .githooks/plugin-shell-versions.txt(只增、版號依序)。其他工作線同期在升 plugin 版號,同時改會衝突,合併前要 rebase 並重算那一列。

    Complexity

    Plan

    Hard-gate: triggered — 同一個概念(CLI 過期提示)散佈到 ≥5 檔:plugin/hooks/check-cli.sh、plugin/hooks/hooks.json、Sources/akashic/ 的版本旗標、建置戳記腳本、plugin/.claude-plugin/plugin.json、.githooks/plugin-shell-versions.txt、.claude/rules/swift-is-the-implementation-language.md、docs/rulings/mcp-cli-parity.md、Swift 測試

    • Layer 1:未命中(交付物是程式與 hook,不是敘述)
    • Layer 2/3:--version 是 CLI 的新旗標,但不改任何既有 spec 的規範行為、不影響多份 spec → 不是 Spectra
    • Layer P:decision-heavy(戳記方法 A/B、比對基準、契約數字的來源);Strategy 超過 5 個依序步驟

    Risks

    • hook 在每個 session 開始時都跑:卡住或報錯會干擾所有 session。要有探測上限、任何失敗 exit 0。
    • 過報((b))會讓人學會忽略提示。
    • 契約數字若從 SKILL 文字抽,SKILL 第 0 步改寫就抽不到;抽不到時要說出來,不得靜默當成通過。
    • 推上 main 就發布 plugin,hook 一出錯就到所有使用者手上。
    • 方案 B 的 SwiftPM 增量連結行為未驗證。

    Residue

    Vagueness Pre-check

    • V1: 2 — Expected 列出三項具體行為(--version 印 git describe、hook 的三種情形各印什麼、checkout 位置可設定),沒有「改善」「優化」這類無標的動詞。
    • V4: 2 — 每一種情形都有可測的輸出(找不到 → 安裝指令;落後 → N 與重建指令;契約不足 → 兩個數字)與兩條禁止(不連網、不自動安裝)。
    • Triggered: no — both axes ≤ 3

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

  2. kiki830621 commented on Nov 9, 2026

    @kiki830621
    MemberAuthor

    🎯 Decision

    Original (2026-11-09):
    「戳記方法:照 safari-browser(推薦)/比對基準:origin/main,沒有才用 HEAD(推薦)/殼層規則:修例外 1,收這兩個檔(推薦)/契約來源:hook 從 SKILL 抽出(推薦)」

    決定

    Diagnosis 列出的五個待裁決點與契約數字的來源,依上面四題的選擇定案:(c) 照 safari-browser,用建置期間改寫、建完還原的受追蹤佔位檔;(d) SKILL 的建置指示改用那支戳記腳本,裸 swift build 建出的 CLI 印 unknown,由 hook 改比檔案時間;(a) 比對基準是 refs/remotes/origin/main,沒有這個 ref 才用 checkout 的 HEAD,訊息寫明用了哪一個;(e) 修改 swift-is-the-implementation-language 的例外 1,收 plugin/hooks/check-cli.sh 與戳記腳本;契約要求的數字由 hook 從 akashic-fetch-fulltext SKILL 第 0 步抽出,測試釘住抽到的值等於 SKILL 那一行,抽不到時具名說出來。(b) 沒有另外問,採 Diagnosis 寫的預設:編譯輸入取整個 Sources、Package.swift、Package.resolved 與 submodule repos/biblatex-apa-swift,接受過報,提示文字寫「動到 package 原始碼」。

    Rationale

    戳記方法選已在 safari-browser 用過、有測試的那一種,代價是建置期間有一個受追蹤檔被改著;連結期 section 雖然不碰受追蹤檔,但兩個 repo 都沒用過,SwiftPM 的增量連結行為要另外量,這一輪不承擔那個未知。比對基準不照 safari-browser 用 HEAD,因為這個 repo 的工作都在 worktree 與 PR 上,主 checkout 很少 pull(實測落後 origin/main 308 個 commit),拿 HEAD 當尺會系統性地少報落後。殼層規則選擇顯式改規則而不是類推:hook 要判斷的就是 akashic binary 在不在、新不新,判斷者不能住在被判斷的 binary 裡,而規則要求這種情況寫明理由加列。契約數字留在 SKILL 一處,是 no-compat-fallback「同一件事只能有一份描述」的直接應用;另一個選項(兩邊改讀同一個資料檔)要改 SKILL 第 0 步的指令,範圍較大,這一輪不採。

    Related

    #775 Diagnosis、#776(akashic-discovery 的 references 契約,sister concern)、#633(CLI 的發布管道)

  3. kiki830621 commented on Nov 9, 2026

    @kiki830621
    MemberAuthor

    Implementation Plan (Plan tier)

    依 Diagnosis 與 2026-11-09 的 decision comment 定案的方向寫成。branch idd/775-cli-stale-check(從 origin/main dad21f86 分出),走 PR;推送、開 PR、合併都另外問。

    Files & Changes

    • Sources/akashic/BuildVersion.swift(新)— 受追蹤的佔位檔:enum BuildVersion { static let value = "unknown" }。平常的 swift build/swift test 讀到的就是 unknown,不會失敗。

    • Sources/akashic/CLI.swift — 根命令的 CommandConfiguration 加 version: BuildVersion.value。akashic --version 印那一行、結束碼 0;舊 CLI 對同一個旗標回 64,hook 據此分辨。

    • scripts/stamp-version.sh(新,100755)— 移植 safari-browser 的 scripts/stamp-version.sh:在 repo 根目錄執行;先算版本再動檔(否則每次都是 -dirty);改寫佔位檔、以子行程執行後面的命令並等它結束;成功、失敗、INT/TERM/HUP/QUIT 都從備份還原佔位檔。版本字串取 git describe --always --dirty --abbrev=12 --exclude='*',也就是裸的 <hash>[-dirty]:這個 repo 的 tag 是 akashic-mcp-v*、idd-*-baseline 等,沒有一個描述 CLI 的建置。白名單之外的字元與任何 git 失敗一律 unknown;所在目錄不是自己 repo 的根時也是 unknown(防止被外層 repo 的 tag 冒充)。

    • plugin/hooks/hooks.json(新)— SessionStart 執行 ${CLAUDE_PLUGIN_ROOT}/hooks/check-cli.sh。

    • plugin/hooks/check-cli.sh(新,100755)— 移植 safari-browser 的 hooks/check-cli.sh,三處不同:

      1. CLI 位置:command -v akashic,沒有才看 $HOME/bin/akashic(後者時多說一句「不在 PATH 上」,因為 SKILL 呼叫的是裸的 akashic)。找不到 → 印建置指令,沒有原始碼目錄時先印 clone 指令。
      2. 契約比對(有沒有原始碼 checkout 都做):要求的數字從 ${CLAUDE_PLUGIN_ROOT}/skills/akashic-fetch-fulltext/SKILL.md 第 0 步那一行 "${v#fulltext-contract }" -ge <N> 抽出,必須恰好一處;CLI 的 fulltext contract 輸出要是 fulltext-contract <數字>。CLI 沒有那個子命令(回 64)→ 說「CLI 沒有 fulltext contract,要求 ≥ N」;數字比 N 小 → 兩個數字都說出來;SKILL 抽不到 → 一行「讀不到 SKILL 要求的契約版本,沒有比對」,不當成通過。
      3. 落後比對的基準:原始碼目錄取 ${AKASHIC_SOURCE_DIR:-$HOME/Developer/Akashic-Library},是 git 工作樹(含 worktree,.git 是檔)才比。基準取 refs/remotes/origin/main,沒有這個 ref 才用 HEAD,訊息寫明用的是哪一個(origin/main 是上次 fetch 時的狀態)。編譯輸入:Sources、Package.swift、Package.resolved、repos/biblatex-apa-swift。比對流程照 safari-browser:建置 commit 是基準的祖先 → 數之後動到編譯輸入的 commit;不是祖先但編譯輸入與基準相同(squash merge 的常態)→ 視為最新;基準比建置舊 → 說明並改比檔案時間;其他 → 說明原因並改比檔案時間;unknown 或舊 CLI → 直接比檔案時間(binary 的修改時間 vs 基準上最後一個動到編譯輸入的 commit)。

      共通:--version 與 fulltext contract 各以 4 秒為上限、在自己的 process group 執行,逾時整組 kill,暫存檔在任何結束方式下都刪掉;--version 逾時就不再跑契約探測(最壞情形約 4 秒,不是 8 秒)。印出的版本字串只收白名單字元、128 字元以內。任何失敗都 exit 0、不寫 stderr。重建指令:

      cd <原始碼目錄>
      git pull && git submodule update --init repos/biblatex-apa-swift
      scripts/stamp-version.sh Sources/akashic/BuildVersion.swift -- swift build -c release --product akashic
      install -m 755 "$(swift build -c release --show-bin-path)/akashic" <CLI 的位置>
      

      (install 先刪掉目的檔再寫入,換成新的 inode;原地 cp 覆寫已簽章的 binary 會在下次執行時被系統終止。)

    • plugin/skills/akashic-fetch-fulltext/SKILL.md — 第 0 步錯誤訊息裡的建置指示改成上面四行的寫法(經戳記腳本、以 install 放回原位)。

    • .claude/rules/swift-is-the-implementation-language.md — 例外 1「目前恰為四個檔」改成六個,加 scripts/stamp-version.sh(建置前就得跑的串接)與 plugin/hooks/check-cli.sh。後者含判斷(祖先關係、檔案時間退路、契約比對),要寫明為什麼仍列為例外而不是移進 Swift:它判斷的對象就是 akashic binary 本身(不存在、過舊、卡住),判斷者不能住在被判斷的 binary 裡;它的行為測試寫在 Swift test target。〈觸發過的實例〉加一列;〈語言組成〉加一行新量測(不改舊的那一行)。

    • docs/rulings/mcp-cli-parity.md — CLI-only 裁決表加一列「根層旗標 --version(akashic CLI 過期時沒有提示:比照 safari-browser 加 SessionStart 檢查 #775)」:有理由缺席。它既不是 subcommand 也不是 ParsableArguments,三種稽核都枚舉不到,所以手動加列;MCP 面的 server binary 由 wrapper 依 binary_version 下載,版本由那裡管,--version 只服務本機的 SessionStart 檢查。第一欄不加反引號(parity-table-drift 會把反引號裡的第一個詞當成命令名)。

    • plugin/.claude-plugin/plugin.json — version 0.13.12 → 0.13.13(hooks/ 底下的檔是送出的內容)。

    • .githooks/plugin-shell-versions.txt — 加一列 plugin 0.13.13 <摘要>,摘要由 akashic-guards plugin-shell-version 算出。

    • plugin/CHANGELOG.md — 0.13.13:新的 SessionStart 檢查、AKASHIC_SOURCE_DIR、SKILL 第 0 步的建置指示。

    • Tests/…/CheckCLIHookTests.swift(新)— 照 WrapperDownloadTests 的做法:暫存 HOME、暫存的原始碼 repo(git init 後做幾個動到 Sources 與只動文件的 commit,另建 refs/remotes/origin/main)、假 CLI(shell 腳本,依環境變數印 --version 與 fulltext contract,或回 64、或卡住)、把真的 hook 與真的 SKILL 複製到暫存 plugin 根,以 /bin/bash 執行。

    • Tests/…/StampVersionTests.swift(新)— 在暫存 git repo 裡跑 scripts/stamp-version.sh:命令看到的是戳記值、結束後佔位檔還原(命令成功、失敗、收到 TERM 三種)、有未 commit 修改時帶 -dirty、不在 repo 根時是 unknown。

    • Tests/AkashicCLITests/… — 測試建置的 akashic --version 印 unknown、結束碼 0。

    Family-wide scope (shared-abstraction hard-gate trigger only)

    n/a — 硬閘因「同一概念散佈 ≥5 檔」命中,不是 shared abstraction。

    Sequencing & Dependencies

    1. BuildVersion.swift + CLI.swift 的 version:(先寫 --version 印 unknown 的測試,RED → GREEN)。
    2. scripts/stamp-version.sh + 它的測試:hook 的測試要用「印出某個 commit 的 CLI」,這個格式由這一步定。
    3. plugin/hooks/check-cli.sh + hooks.json + hook 測試(先寫測試)。
    4. SKILL 第 0 步的建置指示(hook 的重建指令與 SKILL 的要一致)。
    5. 規則例外 1 與裁決表。
    6. 最後才升 plugin.json 版號、算摘要、加版號表那一列、寫 CHANGELOG——摘要涵蓋 plugin 底下所有送出的檔,任何 plugin 檔之後再改都要重算。
    7. 跑全部測試與 run-guards.sh(含 plugin-shell-version、official-validate、parity-table-drift、受保護清單棘輪)。

    Decision Points

    已由使用者裁決(見 decision comment):戳記照 safari-browser 用受追蹤佔位檔;基準 origin/main,沒有才 HEAD;修改例外 1;契約數字由 hook 從 SKILL 抽;編譯輸入取整個 Sources,接受過報。

    本計畫另外定的細節:

    • 版本字串只用裸 hash(--exclude='*'):hook 只需要解析 <hash>[-dirty] 一種形狀;safari-browser 那種 v<tag> 分支在這個 repo 用不到。
    • 契約測試釘在 FulltextFetch.contractVersion:測試用真的 SKILL,假 CLI 印 contractVersion - 1 時要求兩個數字都出現、印 contractVersion 時不出聲。這同時釘住兩件事:hook 抽得到 SKILL 的數字,以及 SKILL 第 0 步的數字等於 CLI 的契約常數。後者是新增的不變式:日後升契約版本卻忘了改 SKILL,這支測試會紅。
    • 環境變數名 AKASHIC_SOURCE_DIR:與既有的 AKASHIC_HOME(store 位置)同一個前綴、不同意思。

    Risks & Mitigations

    • 每個 session 都跑(不只 Akashic 專案,plugin 是全域的):探測上限、逾時就不再探第二次、任何錯誤 exit 0 且不寫 stderr;只跑 git 指令,不呼叫 swift。
    • 建置期間佔位檔被改著:同一個工作樹裡別的 session 在這幾分鐘內 commit,可能把戳記值掃進去。腳本檔頭與 CHANGELOG 寫明:在沒有別的工作線 commit 的 checkout 上建置。戳記值只有 hash,就算被 commit 進去也看得出來(佔位值應為 unknown),並有測試確保還原。
    • 過報:只動 akashic-mcp、App、guards 的 commit 也算「落後」;訊息寫「動到 package 原始碼」,不說「CLI 的程式碼」。
    • origin/main 沒 fetch 就是舊的:訊息寫明基準是「上次 fetch 時的 origin/main」。
    • 推上 main 就是發布 plugin:hook 一出錯就到所有使用者手上。測試涵蓋找不到 CLI、卡住、沒有 checkout、SKILL 抽不到等降級路徑。
    • plugin 版號與版號表和其他工作線衝突:合併前 rebase,必要時重算摘要(Conflict Class B)。

    Test Plan

    測試 改動 RED 時 GREEN 時
    --version 印 unknown CLI.swift 結束碼 64、Unknown option 印 unknown、0
    戳記值、還原(成功/失敗/TERM)、-dirty、非 repo 根 stamp-version.sh 腳本不存在 命令讀到 <hash>;結束後檔案回到佔位值
    找不到 CLI hook hook 不存在 印「找不到」與建置指令,0
    舊 CLI(--version 64、契約 6) hook — 說出 6 與要求值;改比檔案時間
    建置 commit 是祖先、之後 2 個 Sources commit + 1 個只改文件 hook — 「落後 2 個」,不是 3
    squash 後編譯輸入相同 hook — 不印落後
    基準比建置舊 hook — 說明「基準比建置舊」並改比檔案時間
    unknown:binary 比最後一個編譯輸入 commit 舊/新 hook — 舊 → 提示;新 → 不出聲
    HEAD 落後 origin/main hook — 以 origin/main 計數,訊息寫明
    沒有原始碼目錄 hook — 只有契約比對,沒有落後訊息
    --version 卡住 hook — 約 4 秒內結束,印出不含版本的一行,0
    真 SKILL × 假 CLI 印 contractVersion - 1/contractVersion hook + SKILL — 前者兩個數字都在;後者不出聲
    SKILL 沒有第 0 步那一行 hook — 「讀不到 SKILL 要求的契約版本」

    Out-of-scope (will NOT be touched)

    Tangential Observations (filed mid-plan, v2.42.0+ #524)

    none surfaced — 看到的兩件都已有記錄:check-existing-work.sh 在 merged PR 超過 100 筆時回 unknown(PsychQuant/issue-driven-development#471);fulltext 子命令群在 docs/rulings/mcp-cli-parity.md 已有裁決列。本機主 checkout 落後 origin/main 是環境狀態,不是 repo 的缺陷。

  4. kiki830621 commented on Nov 9, 2026

    @kiki830621
    MemberAuthor

    Implementation Complete

    branch idd/775-cli-stale-check(已 rebase 到 origin/main 8f8859c0),11 個 commit,尚未推送。

    Checklist (synced from TaskList)

    • Sources/akashic/BuildVersion.swift + 根命令 version::akashic --version 印建置時的 commit,未戳記印 unknown → 283e640d
    • scripts/stamp-version.sh:建置期間寫入、任何結束方式都還原;排除所有 tag,只印裸 <hash>[-dirty] → b6718e30
    • plugin/hooks/check-cli.sh + hooks.json:找不到 CLI/契約不足/落後原始碼三種提示,基準 origin/main 沒有才用 HEAD → c21d3682、236a1f6f、1be7fc48
    • akashic-fetch-fulltext SKILL 第 0 步的建置指示改經戳記腳本 → 27833693
    • swift-is-the-implementation-language 例外 1 四個檔改六個(hook 以具名例外列入);docs/rulings/mcp-cli-parity.md 加「根層旗標 --version」 → cec5fecc
    • plugin 殼升版、版號表、CHANGELOG(版號是 0.13.14,見 Scope Changes) → e6927a60、886ce15e
    • Swift 測試:CLIVersionTests(1)、StampVersionTests(8)、CheckCLIHookTests(18) → 同上各 commit
    • 全套測試、守衛、實機驗證 → 見下方 Verification;repo changelog changelog/2026-11-09-cli-stale-check-775.md → 7854f899、36a966f1

    Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)

    Scope Changes

    • 版號改為 0.13.14:實作期間 feat: 取得全文——Find Full Text 缺口的 plugin skill(akashic-fetch-fulltext) #613 b49 先把 plugin 殼 0.13.13 發布上 main(同一個 Conflict Class B 資源)。rebase 之後保留 main 的 0.13.13,本 issue 升 0.13.14。b49 同時把 fulltext 契約升到 9;hook 的契約測試釘的是 CLI 自己的常數,跟著對上,沒有改測試。
    • 動到兩支既有測試(都是新功能的直接後果,不是順手修):WriteGateRulingsTests 把 ArgumentParser 自帶的 --version 與 --help 一起排除在「寫入腿」之外(根命令設了 version: 之後它出現在每個子命令上);GitSpawnHygieneTests 登記兩支新測試檔(它們 spawn git,環境已剝除 GIT_*)。
    • hook 第一版的 UTF-8 bug:實機第一次跑時數字全成亂碼——UTF-8 locale 下 bash 把緊接在變數名後的全形標點當成名字的一部分。測試因為跑在 C locale 而全綠。修法:hook 的程式碼行一律 ${名字};hook 測試固定在 LANG=C.UTF-8 下跑,並斷言輸出沒有 U+FFFD(修 hook 之前同一組測試在這個環境下出現 21 個失敗)。

    Verification

    • 嚴格建置(-Xswiftc -warnings-as-errors)與全套 swift test -Xswiftc -warnings-as-errors 在 rebase 後的 886ce15e 上:0 個錯誤(最大的 bundle 927 支)。bash .githooks/run-guards.sh 在 HEAD 36a966f1 上 rc=0(5/5 PASS、觸發點覆蓋無缺口)。
    • 負對照:hook 八個(不用 origin/main、計數不限 package 原始碼、squash 後同內容不當最新、契約不比、逾時仍探契約、不看 $HOME/bin、檔案時間不比、dirty 不說),戳記腳本兩個(不排除 tag、拿掉 TERM 的 trap)——每個都讓對應的測試轉紅,檔案已從備份位元組相同地還原。
    • 戳記建置實跑:以本 branch 經 scripts/stamp-version.sh 建 release 版、install 到暫存目錄:--version 印 886ce15e5cf1,等於 HEAD;建完工作樹乾淨、佔位檔已還原;hook 讀到版本並說明「比 origin/main 新」。
    • 本機 ~/bin/akashic(只讀,這一輪沒有覆蓋):
      • rebase 前(10-28 建置)hook 印出「fulltext 契約是 6,要求 ≥ 8」與「binary 2026-10-28,origin/main 最後一次動到 package 原始碼是 2026-11-09」並附重建指令——正是本 issue 的情境。
      • 之後它已由另一條工作線以 b49 的程式碼重建(11-10 00:50,契約 9)。hook 只印一行 ✓,判斷正確:契約 9 ≥ 9,修改時間晚於 origin/main 最後一次動到 package 原始碼。

    Files Changed

     .claude/rules/swift-is-the-implementation-language.md  |  15 +-
     .githooks/plugin-shell-versions.txt                    |   1 +
     Sources/akashic/BuildVersion.swift                     |   9 +
     Sources/akashic/CLI.swift                              |   2 +
     Tests/AkashicCLITests/CLIVersionTests.swift            |  14 +
     Tests/AkashicCLITests/CheckCLIHookTests.swift          | 338 +++
     Tests/AkashicCLITests/StampVersionTests.swift          | 167 ++
     Tests/AkashicCLITests/WriteGateRulingsTests.swift      |   6 +-
     Tests/AkashicKitTests/GitSpawnHygieneTests.swift       |   2 +
     changelog/2026-11-09-cli-stale-check-775.md            |  42 +
     docs/rulings/mcp-cli-parity.md                         |   1 +
     plugin/.claude-plugin/plugin.json                      |   2 +-
     plugin/CHANGELOG.md                                    |   8 +
     plugin/hooks/check-cli.sh                              | 239 +++
     plugin/hooks/hooks.json                                |  14 +
     plugin/skills/akashic-fetch-fulltext/SKILL.md          |   2 +-
     scripts/stamp-version.sh                               |  85 +
     17 files changed, 941 insertions(+), 6 deletions(-)
    

    Scope Compliance

    所有改動都對應 #775 的 Expected 或其直接後果(見 Scope Changes)。akashic-discovery 的 references 契約在 #776,CLI 的發布管道在 #633,都沒有動。

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

    Next: verification pending

    推送 branch、開 PR 都等使用者確認後才做;之後 /idd-verify #775。

  5. kiki830621 commented on Nov 9, 2026

    @kiki830621
    MemberAuthor

    📊 For Reviewer / Collaborator

    現在:已結案。根因是 CLI 說不出自己是哪一次建置、plugin 也沒有開 session 時的檢查;改成 akashic --version 印建置 commit,加上 SessionStart hook 說出找不到 CLI、契約不足、落後原始碼三種情形。PR #783 已 squash 合併(8fc7fc0b),plugin 殼發布為 0.13.15。
    Blocking:無
    你該做什麼:無。本機的 akashic 要不要重建由你決定;verify 留下的界線在 #778、#784、#785、#786、#788–#793,發布管道在 #633。

    last-updated by idd-close at closed, 2026-11-12

  6. kiki830621 commented on Nov 10, 2026

    @kiki830621
    MemberAuthor

    Verify (via PR #783)

    Result: FAIL — 3 blocking(MEDIUM:比不出祖先關係時安靜漏報、git 呼叫沒有中和設定與環境、並行戳記留下戳記值)、1 項待使用者裁決(SessionStart 輸出進模型 context、畫面上不一定看得到)
    Full report: #783 (comment)

    This issue's findings: see "#775" section in the linked report.

  7. kiki830621 commented on Nov 10, 2026

    @kiki830621
    MemberAuthor

    Verify r2 — FAIL(報告在 PR #783)

    完整報告:#783 (comment)

    受審的是 r1 之後的三個修正 commit(本機,還沒推上 PR)。六席都交回報告。

    • 3 個 blocking:PR 被 squash 合併後又被 revert 時落後安靜漏報;core.fsmonitor 設定的程式會被 diff-tree 執行;戳記腳本在檢查與備份之間的空檔仍會把戳記留在受追蹤的檔裡。
    • 1 個修正輪造成的迴歸:PATH 上的 akashic 是包裝腳本時,探測拿到的是收窄過的 PATH,被報成執行失敗。
    • 其餘 12 項 LOW/INFO 這一輪一併修;5 項另開 issue 或寫成界線。

    下一步:修完再做一輪只看這批修正的複審(r3),通過才推上 PR。

  8. kiki830621 commented on Nov 10, 2026

    @kiki830621
    MemberAuthor

    Verify r3 — FAIL(報告在 PR #783)

    完整報告:#783 (comment)

    受審的是 r2 之後的三個修正 commit(本機,連同 r1 的三個都還沒推上 PR)。六席都交回報告。

    • r2 的三個 blocking(B1、B2、B3)都已關上,各有實跑的證據;落後判定試了 60 多個歷史形狀,找不到新的漏報。
    • 2 個 MEDIUM,都落在 r2 修正輪新寫的程式上:探測用的 /bin/sh -p 在 /bin/sh 指向 dash 的機器上每次都失敗(預設的 macOS 指向 bash,不受影響);兩者分岔時算交集的成本是兩份清單長度的乘積,歷史長到幾千個 commit 時可能撞上 hook 的 30 秒上限。
    • 9 項 LOW,多數是界線沒寫清楚或文件措辭。
    • 嚴格建置與全套測試通過(7 個 bundle、5,639 支、0 失敗)。

    下一步:照 r2 報告的預告停損,這一輪不推、不再自行加新機制;分岔比對成本的處置先請使用者決定。

  9. kiki830621 commented on Nov 10, 2026

    @kiki830621
    MemberAuthor

    Verify r4 — PASS(停損輪,報告在 PR #783)

    完整報告:#783 (comment)

    受審的是 r3 之後的三個 commit。兩席 Claude、Codex 與 Devil's Advocate 都沒有 MEDIUM 以上的問題。找到的都是 r3 修正輪新寫的句子不成立,已照各席給的實測與句子改字(12b04e72,不碰判定邏輯)。其中一項更正了 M2 的成本數字:原本是在 UTF-8 locale 下量的,hook 跑在 C locale,實際約是四分之一(#793 已同步更正)。

    下一步:推送到 PR 分支;合併另外問。

  10. kiki830621 commented on Nov 12, 2026

    @kiki830621
    MemberAuthor

    Closing Summary

    Problem

    本機的 akashic CLI 過期時沒有任何提示。#768 合併後,SKILL 要求 fulltext contract 8,本機 10 月底建的 CLI 只印 6;開 session 時沒有訊息,第一個訊號會是 SKILL 第 0 步拒絕執行,或者用舊 CLI 跑了。safari-browser 已有同類機制(--version 加 SessionStart hook)。

    Root Cause

    CLI 說不出自己是哪一次建置(沒有 --version,舊 CLI 回結束碼 64),akashic-mcp plugin 也沒有任何 SessionStart 檢查,所以落後原始碼與契約不足都要等到執行時才看得到。

    Solution

    • akashic --version 印建置時的 commit(裸 <hash>[-dirty],排除所有 tag);沒有戳記的建置印 unknown。
    • scripts/stamp-version.sh:建置期間把 commit 寫進受追蹤的佔位檔,任何結束方式都還原;佔位檔不是原樣就拒絕、寫入失敗就中止、package 路徑下有未追蹤檔算 -dirty。
    • plugin/hooks/check-cli.sh(SessionStart):找不到 CLI、契約不足、落後原始碼三種情形各自說出來;不連網、不自動安裝,重建由使用者決定。
      • 落後的基準是 origin/main,沒有才用 HEAD。判定看基準上每個不在建置歷史裡、動到 package 原始碼的 commit,所以 squash 合併、revert、分支沒 rebase 這些情形都分得出來。
      • git 只用 plumbing 指令,並關掉會執行外部程式的設定(fsmonitor、replace、外部 diff、textconv)與繼承的 GIT_*;探測 CLI 用 /bin/bash -p 加 8 秒上限。
    • SKILL 第 0 步的建置指示改經戳記腳本;swift-is-the-implementation-language 的例外 1 收入 hook 與戳記腳本。
    • plugin 殼 0.13.14 → 0.13.15(0.13.14 由 取全文 #777 拆出:兩件待裁寫成「待使用者裁決」、b52 的文字殘留照現行行為改正 #779 先發布)。

    Verification

    Changes

    • 8fc7fc0b feat: akashic --version 印建置 commit,plugin 開 session 時檢查 CLI 是否過期 (akashic CLI 過期時沒有提示:比照 safari-browser 加 SessionStart 檢查 #775) (feat: akashic --version 印建置 commit,plugin 開 session 時檢查 CLI 是否過期 (#775) #783) —— main 上的 squash merge,使用者 2026-11-12 確認合併
    • 分支 idd/775-cli-stale-check:22 個 commit(283e640d … 6a112fc2),分支保留
    • 改到的檔(18):Sources/akashic/BuildVersion.swift、Sources/akashic/CLI.swift、scripts/stamp-version.sh、plugin/hooks/check-cli.sh、plugin/hooks/hooks.json、plugin/skills/akashic-fetch-fulltext/SKILL.md、plugin/.claude-plugin/plugin.json、plugin/CHANGELOG.md、.githooks/plugin-shell-versions.txt、.claude/rules/swift-is-the-implementation-language.md、docs/rulings/mcp-cli-parity.md、README.md、changelog/2026-11-09-cli-stale-check-775.md,以及測試 CLIVersionTests、StampVersionTests、CheckCLIHookTests、WriteGateRulingsTests、GitSpawnHygieneTests

    已知界線與 follow-up

    Residue Acknowledgement

    Acknowledged as still residue, tracked in #633(CLI 沒有發布管道):

    兩項都在 #633 的範圍內:它若改成 release 下載,hook 的比對基準可以換成 release 版本,沒有 checkout 的使用者也就能知道自己落後。所以不另開 follow-up。

    Doc-sync 檢查

    main 上 3 份文件(README.md、CLAUDE.md、docs/tractatus/README.md)都看過。CLAUDE.md 與 docs/tractatus/README.md 不受這次改動影響;README.md 的環境變數表已在本 PR 加了 AKASHIC_SOURCE_DIR。

    有一處沒有改:README.md 的 akashic-discovery 一段寫「CLI 要在本 repo swift build -c release 後自行放上 PATH」。沒有經過 scripts/stamp-version.sh 建出的 CLI,--version 印 unknown,hook 只能改比檔案時間,所以那句話已不是最好的建置方式。改它要推到 main,不在這次結案的範圍內,留給 #776(同一個 skill 的過期提示)一併處理。

    Distribution Sync

  11. added a commit that references this issue on Nov 12, 2026
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