devlog-tracker 0.22.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [<your-github-handle>]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,234 @@
+# devlog-tracker
+
+**版本** 0.22.0
+
+在專案中維護一份 `.devlog/devlog.md`，把每一輪對話的請求、決策與結果寫成永久紀錄。對話一 `/clear` 或換 session 就沒了；這份檔案取代那個缺口，讓工作可以中斷再接。沒下過 `/devlog-tracker:start` 時，裝著也不會動任何檔案。
+
+## 這是什麼
+
+把「這輪做了什麼、決定了什麼、下一步是什麼」寫進專案內的 `devlog.md`。Stop hook 保證每輪都寫完才放行；沒明確 `/devlog-tracker:start` 前不會建立或改動 `.devlog/`。
+
+`devlog.md` 只管**跨 session 的交接連續性**（決策軌跡、目前卡點、完成條件、下一步），並作為 **L1**（人觸發 continue／開 session 注入後，agent 只靠 SSOT 接手，且必須把本輪狀態**寫回**本檔）的主入口。不是整個專案的單一真相來源：
+
+- 程式碼／檔案狀態的真相仍是 git
+- 完整逐字過程的真相是對話 transcript（`/clear` 後不存在）
+- 設計決策的真相是 `docs/design/*.md`
+
+這份檔案只是取代「終端機一 clear 就沒了」的缺口，讓工作可以隨時中斷、隨時接續。L2（無人喚醒）與 L3（跨機共享 `.devlog/`）不在範圍；細節見 [`docs/design/devlog-as-ssot-assessment.md`](docs/design/devlog-as-ssot-assessment.md)。
+
+每輪收尾固定寫 `Summary`／`Reply`（對使用者說過的話）／`Handoff`（含未完成時的 `完成條件`）／`Status`。接手＝核對工作區 → 做下一步 → **寫回**；讀而不寫算交接失敗。
+
+## 安裝
+
+作為 Claude Code plugin 安裝（會自動更新）：
+
+```
+/plugin marketplace add gogogohuang/devlog-tracker
+/plugin install devlog-tracker@devlog-tracker
+```
+
+### npx（Cursor／Codex 用）
+
+Claude Code 請用上面的 `/plugin marketplace add` 安裝方式；這個 CLI 不會設定 Claude Code。
+
+```bash
+npx devlog-tracker init
+```
+
+沒帶 `--codex`／`--cursor` 時會互動式問要裝哪個平台；在沒有 TTY 的環境（例如 CI）且沒帶旗標時，`init` 不會詢問，直接安裝所有支援的平台（codex + cursor）。也可以直接指定：
+
+```bash
+npx devlog-tracker init --codex --cursor
+```
+
+會把 `hooks/scripts/`、`codex/hooks/`、`cursor/hooks/`、`skills/`、`commands/`
+複製進專案的 `.devlog-tracker/`，並把對應平台的 `hooks.json` 合併進專案（不覆蓋
+其他工具已設定的 hook）。重新執行 `npx devlog-tracker init` 可以升級到套件目前的
+版本；`npx devlog-tracker status` 可以查目前裝的版本是否落後。
+
+`init` 會把這台機器專屬的絕對路徑寫進 `.codex/hooks.json`、`.cursor/hooks.json` 與
+`.devlog-tracker/env.sh`。如果你把這些檔案 commit 進 git，每位隊友都要在自己的機器上
+跑一次 `npx devlog-tracker init`（路徑每台機器不同）；或者改成把 `.devlog-tracker/` 與
+產生出來的 hooks.json 加進 `.gitignore`。
+
+### Cursor（選用）
+
+Claude Code 仍是主要安裝方式。若要在 Cursor workspace 使用，先設定
+`DEVLOG_TRACKER_ROOT` 為本 plugin 的絕對路徑，再把 `cursor/hooks.json` 的
+`hooks` 合併進專案 `.cursor/hooks.json`。也可以把整個 `cursor/hooks/` 與
+`hooks/scripts/` vendoring 到專案，並調整 command 路徑；兩者的相對目錄必須維持可用。
+
+Cursor cloud agent 不執行 `sessionStart`，因此不會自動注入接手摘要；其他已設定的
+hook 仍依 Cursor 支援的事件執行。
+
+Cursor 沒有 `/devlog-tracker:*` slash 指令面；hooks 裝好後，請用與 Claude commands
+相同的腳本（`commands/*.md` 會優先讀 `CLAUDE_PLUGIN_ROOT`，否則讀
+`DEVLOG_TRACKER_ROOT`）：
+
+```bash
+export DEVLOG_TRACKER_ROOT=/absolute/path/to/devlog-tracker
+export CLAUDE_PROJECT_DIR="$(pwd)"
+bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/start-devlog.sh"
+bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/status-devlog.sh"
+bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/segment-watch-set.sh" 600
+bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/checkpoint-set.sh" 20
+# pause / span-open / span-close / compact / keep-move / clean / resume：見 commands/*.md
+```
+
+### Codex（選用）
+
+Claude Code 仍是主要安裝方式。若要在 Codex CLI 使用，先設定
+`DEVLOG_TRACKER_ROOT` 為本 plugin 的絕對路徑，再把 `codex/hooks.json` 的
+`hooks` 合併進專案（或 `~/.codex/`）的 `hooks.json`。也可以把整個 `codex/hooks/` 與
+`hooks/scripts/` vendoring 到專案，並調整 command 路徑；兩者的相對目錄必須維持可用。
+
+Codex 目前沒有對應「使用者中斷」（Claude Code 的 `PostToolUseFailure`／
+`is_interrupt`）與「這輪異常結束」（`StopFailure`）的事件，這兩種細節狀態在
+Codex 上不會被標記成 `INTERRUPTED`；核心強制記錄機制（`Stop` 事件擋住未寫完的
+輪次）不受影響。
+
+Codex 沒有 `/devlog-tracker:*` slash 指令面；hooks 裝好後，請用與 Claude commands
+相同的腳本（`commands/*.md` 會優先讀 `CLAUDE_PLUGIN_ROOT`，否則讀
+`DEVLOG_TRACKER_ROOT`）：
+
+```bash
+export DEVLOG_TRACKER_ROOT=/absolute/path/to/devlog-tracker
+export CLAUDE_PROJECT_DIR="$(pwd)"
+bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/start-devlog.sh"
+bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/status-devlog.sh"
+bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/segment-watch-set.sh" 600
+bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/checkpoint-set.sh" 20
+# pause / span-open / span-close / compact / keep-move / clean / resume：見 commands/*.md
+```
+
+## 快速開始
+
+在專案裡下一次：
+
+```
+/devlog-tracker:start
+```
+
+之後正常跟 Claude 對話即可，每一輪結束前都會被強制檢查、補上 `.devlog/devlog.md` 的紀錄。`/clear` 之後 context 是空的；要接著做上一題，下 `/devlog-tracker:continue`。暫停、歸檔、具名搬走、狀態與 span 見下方指令表（完整 namespace，plugin 名稱是 `devlog-tracker`）。
+
+## 指令
+
+| 指令 | 做什麼 |
+|---|---|
+| `/devlog-tracker:start` | 跑腳本建立 `.devlog/.enabled`（缺的 state 檔會補上，已有門檻不重置）。讀檔對進度，不自動開工。`.devlog/` 含 prompt，會建議加進 `.gitignore`，要你同意才改。 |
+| `/devlog-tracker:continue` | 讀 `.devlog/devlog.md`，核對最後一輪 Handoff「工作區」後再依下一步接著做。`/clear` 之後要接續用這個。細節見 [`docs/design/continue.md`](docs/design/continue.md)。 |
+| `/devlog-tracker:pause` | 暫停強制記錄，歷史檔不動，之後可再 `start`。 |
+| `/devlog-tracker:compact` | 腳本把較舊的 `DONE` 輪次搬到 `devlog.archive.md`（Checkpoint 與未完成輪留在主檔）。 |
+| `/devlog-tracker:keep` | 掃全檔分主題，一次列出建議，確認後把各段各自搬走成 `devlog.<name>.md`（並在主檔留一個 `## Kept 索引` 指標行，含一句主題描述）；也可抽出一段或合併成全部歷史一檔。不是 compact。細節見 [`docs/design/keep.md`](docs/design/keep.md)。 |
+| `/devlog-tracker:overview` | 讀完所有已 keep 的 `devlog.<name>.md`，整合成跨主題總覽，並列出看起來該進 `CLAUDE.md` 的規範候選。純讀取，不核對工作區、不等確認、不寫檔。細節見 [`docs/design/keep.md`](docs/design/keep.md) Kept index。 |
+| `/devlog-tracker:resume <name>` | 讀具名保存檔的最後一輪與 Handoff，核對「工作區」後提出接續；新工作仍寫回主 `devlog.md`。 |
+| `/devlog-tracker:clean` | 無條件清空 `devlog.md`（含專案摘要與所有 Round 歷史），不搬移、不備份、不可復原；執行前一定會先問，要明確回覆「清空」才動手。只留目前開著的那一輪，重編成 `## Round 1`。 |
+| `/devlog-tracker:status` | 查看強制記錄開關、Span、Checkpoint、Segment Watch、Lessons Mode 工作區漂移計數與最後一輪 Status。 |
+| `/devlog-tracker:span` | 開啟或關閉自動續接長任務使用的 Span Mode（不要手寫 `.span-open` JSON）。 |
+| `/devlog-tracker:segment-watch <時間長度>` | 調整 Segment Watch 的沉默門檻（預設 10 分鐘）。專案還沒 `/devlog-tracker:start` 時回報 `NOT_STARTED`，不會建立任何檔案。 |
+| `/devlog-tracker:checkpoint <輪數>` | 調整 Checkpoint Mode 的沉默門檻（預設 20 輪）。專案還沒 start 時回報 `NOT_STARTED`。 |
+| `/devlog-tracker:lessons-on` | 開啟預設關閉的 Lessons Mode（隸屬主開關，沒 `start` 過會拒絕）。細節見 [`docs/design/lessons-mode.md`](docs/design/lessons-mode.md)。 |
+| `/devlog-tracker:lessons-off` | 關閉 Lessons Mode，不動任何已寫的 `devlog.lessons.*.md` 或索引。 |
+| `/devlog-tracker:lessons [<topic>]` | 沒給 topic：印 `## Lessons 索引`。給 topic：印該主題檔全文。純讀取，不核對工作區、不等確認。 |
+| `/devlog-tracker:lessons-drift <次數>` | 調整 Lessons Mode「工作區漂移重複發生」機制性提醒的門檻（預設 3 次）。隸屬 Lessons Mode，沒開會回報 `LESSONS_NOT_ENABLED`。 |
+
+## 強制記錄開著之後
+
+```mermaid
+sequenceDiagram
+  participant U as 使用者
+  participant H as Hooks
+  participant C as Claude
+  participant D as .devlog/devlog.md
+
+  U->>H: 送出訊息
+  H->>D: 先寫 Round skeleton（User Input + IN_PROGRESS）
+  C->>D: 補 Summary / Reply / Handoff，改 Status
+  C->>H: 這一輪要結束
+  alt 沒寫完、標題是空的，或 Status 不合法
+    H-->>C: 擋住，要求補寫
+  else 寫完了
+    H-->>C: 放行
+  end
+```
+
+每一輪固定：
+
+- **`User Input`** — 送出原文優先（hook 寫入；Claude 不要改寫），常見 token 會遮罩
+- **`Summary`** — 給人掃的結論
+- **`Reply`** — 這輪對使用者說過／答應過的話
+- **`Handoff`** — 給下一輪接手（決策／檔案／工作區／現況／完成條件／下一步）
+- **`Status`** — `DONE` / `IN_PROGRESS` / `BLOCKED` / `INTERRUPTED` 四選一
+
+其中「工作區」是收尾時的 git 快照，進行中／卡住必寫；`DONE` 若「檔案」有內容（宣稱動過／commit 過檔案）也必寫。「完成條件」在進行中／卡住必寫。
+
+Stop hook 會做這些事：
+
+1. 確認 `Summary`／`Reply`／`Handoff` 標題底下有內容、Status 是上述四值之一；Handoff 小節順序為 決策 → 檔案 → 工作區 → 現況 → 完成條件 → 下一步
+2. 進行中／卡住時有「完成條件」與「下一步」；「下一步」不是純黑名單空話（例如整節只寫「繼續完成」；字串比對，非語意評分，細節見 [`docs/design/next-step-blacklist.md`](docs/design/next-step-blacklist.md)）；進行中另做輕量可執行檢查；卡住時「現況」或「下一步」須含缺件句式
+3. 機器核對「工作區」是否跟收尾當下的 git 狀態逐字相符（進行中／卡住一律核對，`DONE` 只在「檔案」非空時核對），避免「已 commit 完成」卻其實沒 commit 這類宣稱跟實際不符
+
+`#### 檔案` 非空時同樣機器核對：commit 區塊要跟該次 commit 的實際內容逐字相符，未 commit 的區塊只要求宣稱的路徑真的存在變更（不要求涵蓋全部，避免把跨輪殘留算成這輪漏列）。
+
+細節見 [`docs/design/summary-handoff.md`](docs/design/summary-handoff.md)、[`docs/design/devlog-as-ssot-assessment.md`](docs/design/devlog-as-ssot-assessment.md)、[`docs/design/files-verify.md`](docs/design/files-verify.md) 和 SKILL.md。
+
+## Hook 會自動做的事
+
+正常規則是「一則使用者訊息 = 一輪，結束前一定要寫完 Summary／Reply／Handoff／Status」。下面四個機制各自放寬這條規則的不同一塊，彼此正交、可以同時存在：
+
+| 機制 | 放寬的是 | 解決的問題 |
+|---|---|---|
+| **Span Mode** | 「每次自動喚醒算不算一輪」 | `/loop`、Workflow 這類被自己排程反覆喚醒、不是使用者手動打字觸發的長任務，每個自動 tick 都強制寫完整 Round，會逼出大量沒意義的紀錄，甚至卡住整條自動化流程 |
+| **Checkpoint Mode** | 「有沒有跨輪的摘要路標」 | 一般互動對話每輪都正常寫，但輪數一多，翻閱的人要逐輪爬完才知道整體進度 |
+| **Reply Fold** | 「一問一答算不算兩輪」 | Claude 用純文字提問、下一則訊息其實是在回答時，預設邏輯（每個 `UserPromptSubmit` 開新 Round）會把這組問答硬拆成兩個不相關的 Round |
+| **Segment Watch** | 「一輪內部要不要留階段性痕跡」 | 一輪做很久（先探索、再決策、再實作、再驗證），憋到最後才寫一次，中途 crash 會把整個過程全部遺失 |
+
+以下是各機制實際觸發時的行為：
+
+#### 自動接續
+
+`SessionStart` hook 在開新 session、resume、`/compact`、`/fork` 時，注入最後一個 Checkpoint（若有）、`## Kept 索引`（若有，不是具名檔內容）加上最近兩輪的 Summary / Handoff / Status，不是整份檔。`/clear` 是真的清空，不注入；要接續請 `/devlog-tracker:continue`（先核對「工作區」再做下一步）。細節見 [`docs/design/continue.md`](docs/design/continue.md)。
+
+#### 同輪工作區漂移偵測
+
+同一條對話送出下一則訊息時，`UserPromptSubmit` 會拿上一輪 Handoff 的「工作區」跟目前 git 狀態比對；不符就注入提示，並讓 `PreToolUse` 擋住非 devlog 工具，直到這一輪補上含實際快照的 `### 段落`（唯讀的 `git status`／`diff`／`log`／`show`／`rev-parse` 不受影響，方便自行核對）。Span 安靜 tick、task-notification 與 `DONE` 不擋。細節見 [`docs/design/continue.md`](docs/design/continue.md) 與 [`docs/design/segment-watch.md`](docs/design/segment-watch.md)。
+
+#### 意外中斷
+
+非 usage 的 API 錯誤、SessionEnd、殘留的 `.round-open` 會把開著的 Round 標成 `INTERRUPTED`。usage 用光不算中斷。中途取消（例如 Esc）通常是在**下一則訊息**或**下次 SessionStart（startup / resume / clear / fork）**才補上；`PostToolUseFailure` 的 `is_interrupt` 若有觸發，只是 best-effort，不能當成一定會立刻蓋章。`Status` 下面會多一行 `[reason: ...]` 內部代號方便之後 debug（例如 `dangling:next_prompt`）；中斷當下如果是卡在等 `AskUserQuestion` 的回答，Summary/Handoff 會直接說明，不會寫成「意外」。細節見 [`docs/design/recording-moments.md`](docs/design/recording-moments.md)。
+
+#### 段落記錄
+
+長輪不要憋到最後，邊做邊寫 `### 段落`。同一輪連續約 10 分鐘沒改 `.round-current.md`，`PreToolUse` hook 會擋住下一個工具；先 Read 再 Edit／StrReplace 追加一段（不要 Write 覆寫整檔）。門檻可用 `/devlog-tracker:segment-watch <時間長度>` 調整。Claude Code subagent／dynamic workflow（PreToolUse 帶 `agent_id`）不套用父輪這道閥。細節見 [`docs/design/segment-watch.md`](docs/design/segment-watch.md)。
+
+#### Checkpoint Mode
+
+累積約 20 輪沒寫跨輪摘要，`Stop` hook 會要求補一段 `## Checkpoint`（門檻可調）。細節見 [`docs/design/checkpoint-mode.md`](docs/design/checkpoint-mode.md)。
+
+#### Span Mode
+
+`/loop`、Workflow 這類自動續接的長任務，不必每個 tick 都寫完整 Round，用 tick 計數當安全閥；崩潰最多漏記固定數量的 tick，不是整段。細節見 [`docs/design/span-mode.md`](docs/design/span-mode.md)。
+
+#### Reply Fold
+
+Claude 用純文字結尾提出問題、下一則訊息才拿到答案時，不用開新 Round——提問前先手動記一段問題原文再跑 `await-open.sh` 標記，下一則訊息（答案）就會自動折進同一個 Round 當一段 `### 段落`，不是拆成兩個不相關的 Round。連續多輪一問一答（例如 grilling）時，中途每題只記問題段落，不必每題重寫 Summary/Reply/Handoff/Status，等整場問答真正結束才收尾一次。`AskUserQuestion` 在同一 turn 內問答，不用 fold，但仍要用 `### 段落（AskUserQuestion）` 記下問題與答案。背景 task-notification（子 agent 完成通知）也會自動走同一套折疊機制，不留原始 XML，只記精簡摘要。細節見 [`docs/design/reply-fold.md`](docs/design/reply-fold.md)。
+
+#### 分支各自的 devlog 檔
+
+同一個工作目錄裡切換分支時，主檔會依目前 checkout 的分支自動分開：`main`／`master` 繼續用 `.devlog/devlog.md`，其他分支各自用 `.devlog/devlog.<branch>.md`（斜線轉成 `-`）。另開一個 `git worktree`（不同目錄）本來就有自己獨立的 `.devlog/`，不受這個機制影響。第一次在某分支偵測到還沒有專屬檔案、且 `devlog.md` 已有內容時，會把它改名（非複製）成該分支的檔案。細節見 [`docs/design/branch-scoped-devlog.md`](docs/design/branch-scoped-devlog.md)。
+
+#### Lessons Mode（預設關閉，不自動）
+
+開著時，Status 從 `BLOCKED` 解開、明顯繞路，或工作區漂移累積達門檻（預設 3 次，`/devlog-tracker:lessons-drift <次數>` 可調）才考慮記一筆開發歷程教訓，per-topic 存成 `devlog.lessons.<topic>.md`，`devlog.md` 只留標題索引。三種訊號都完全不 hook 強制寫入本身、不是知識庫（架構決策仍在 `docs/design/*.md`）。細節見 [`docs/design/lessons-mode.md`](docs/design/lessons-mode.md)。
+
+## 測試
+
+```
+bash hooks/scripts/run-tests.sh
+```
+
+含 Cursor adapter。
+
+## License
+
+Apache-2.0

package/bin/devlog-tracker.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+'use strict';
+const path = require('path');
+
+async function main(argv) {
+  const [command, ...rest] = argv;
+  const pkg = require('../package.json');
+
+  if (command === '--version' || command === '-v') {
+    console.log(pkg.version);
+    return 0;
+  }
+  if (!command || command === '--help' || command === '-h') {
+    console.log('Usage: devlog-tracker <init|status> [--codex] [--cursor]');
+    return 0;
+  }
+  if (command === 'init') {
+    const { run } = require('../cli/init');
+    const { vendorRoot, platforms } = await run(rest, {
+      repoRoot: path.join(__dirname, '..'),
+      targetDir: process.cwd(),
+      version: pkg.version,
+    });
+    console.log(`devlog-tracker installed to ${vendorRoot} for: ${platforms.join(', ')}`);
+    return 0;
+  }
+  if (command === 'status') {
+    const { status } = require('../cli/status');
+    const result = status({ targetDir: process.cwd(), currentVersion: pkg.version });
+    if (!result.installed) {
+      console.log('devlog-tracker is not installed in this project. Run `npx devlog-tracker init`.');
+    } else if (result.upToDate) {
+      console.log(`devlog-tracker ${result.vendoredVersion} is up to date.`);
+    } else {
+      console.log(
+        `devlog-tracker ${result.vendoredVersion} is installed; ${pkg.version} is available. Run \`npx devlog-tracker init\` to upgrade.`
+      );
+    }
+    return 0;
+  }
+  console.error(`Unknown command: ${command}`);
+  return 1;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => { process.exitCode = code; },
+  (err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+  }
+);

package/cli/init.js

@@ -0,0 +1,55 @@
+'use strict';
+const readline = require('readline');
+const { vendor } = require('./vendor');
+const codex = require('./platforms/codex');
+const cursor = require('./platforms/cursor');
+
+const PLATFORMS = { codex, cursor };
+
+function parseArgs(argv) {
+  const platforms = [];
+  for (const arg of argv) {
+    if (arg === '--codex') platforms.push('codex');
+    else if (arg === '--cursor') platforms.push('cursor');
+    else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg} (supported: --codex, --cursor)`);
+    }
+  }
+  return { platforms };
+}
+
+function promptPlatforms() {
+  if (!process.stdin.isTTY) return Promise.resolve(Object.keys(PLATFORMS));
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question('要裝哪個平台？(codex/cursor，逗號分隔，留空=全部): ', (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      if (!trimmed) return resolve(Object.keys(PLATFORMS));
+      resolve(
+        trimmed
+          .split(',')
+          .map((s) => s.trim())
+          .filter((s) => PLATFORMS[s])
+      );
+    });
+  });
+}
+
+async function run(argv, { repoRoot, targetDir, version }) {
+  const { platforms } = parseArgs(argv);
+  const selected = platforms.length > 0 ? platforms : await promptPlatforms();
+  const vendorRoot = vendor({ repoRoot, targetDir, version });
+  for (const name of selected) {
+    try {
+      PLATFORMS[name].install({ repoRoot, targetDir, vendorRoot });
+    } catch (err) {
+      throw new Error(
+        `Installed files to ${vendorRoot} but failed to configure ${name}: ${String(err.message).replace(/\.$/, '')}. Fix the issue and re-run \`devlog-tracker init\` (safe to re-run).`
+      );
+    }
+  }
+  return { vendorRoot, platforms: selected };
+}
+
+module.exports = { run, parseArgs, PLATFORMS };

package/cli/init.test.js

@@ -0,0 +1,37 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { parseArgs, run } = require('./init');
+
+test('parseArgs accepts --codex and --cursor', () => {
+  assert.deepEqual(parseArgs(['--codex']), { platforms: ['codex'] });
+  assert.deepEqual(parseArgs(['--codex', '--cursor']), { platforms: ['codex', 'cursor'] });
+  assert.deepEqual(parseArgs([]), { platforms: [] });
+});
+
+test('parseArgs throws a clear error for unknown options', () => {
+  assert.throws(
+    () => parseArgs(['--claude']),
+    { message: 'Unknown option: --claude (supported: --codex, --cursor)' }
+  );
+  assert.throws(() => parseArgs(['--codex', '-x']), /Unknown option: -x/);
+});
+
+test('run wraps platform install failures with vendoring context', async () => {
+  const repoRoot = path.join(__dirname, '..');
+  const targetDir = fs.mkdtempSync(path.join(os.tmpdir(), 'devlog-tracker-init-'));
+  fs.mkdirSync(path.join(targetDir, '.codex'), { recursive: true });
+  fs.writeFileSync(path.join(targetDir, '.codex', 'hooks.json'), '{ not json');
+  await assert.rejects(
+    () => run(['--codex'], { repoRoot, targetDir, version: '0.0.0' }),
+    (err) => {
+      assert.match(err.message, /Installed files to .*\.devlog-tracker but failed to configure codex: /);
+      assert.match(err.message, /Cannot parse existing/);
+      assert.match(err.message, /re-run `devlog-tracker init` \(safe to re-run\)/);
+      return true;
+    }
+  );
+});

package/cli/merge-hooks.js

@@ -0,0 +1,60 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const MARKER = '.devlog-tracker/';
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function readExisting(targetPath) {
+  if (!fs.existsSync(targetPath)) return {};
+  const text = fs.readFileSync(targetPath, 'utf8');
+  if (text.trim() === '') return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      `Cannot parse existing ${targetPath}: ${err.message}. Fix or move the file, then re-run \`devlog-tracker init\` (safe to re-run).`
+    );
+  }
+  if (parsed === null) return {};
+  if (!isPlainObject(parsed)) {
+    throw new Error(`Existing ${targetPath} must contain a JSON object at the top level; fix or move the file, then re-run \`devlog-tracker init\` (safe to re-run).`);
+  }
+  if ('hooks' in parsed && parsed.hooks !== null && !isPlainObject(parsed.hooks)) {
+    throw new Error(`Existing ${targetPath}: "hooks" must be a JSON object; fix or move the file, then re-run \`devlog-tracker init\` (safe to re-run).`);
+  }
+  return parsed;
+}
+
+function mergeHooksTemplate({ templatePath, targetPath, vendorRoot }) {
+  const escapedRoot = JSON.stringify(vendorRoot).slice(1, -1);
+  const rawTemplate = fs.readFileSync(templatePath, 'utf8').split('${DEVLOG_TRACKER_ROOT}').join(escapedRoot);
+  const template = JSON.parse(rawTemplate);
+
+  const existing = readExisting(targetPath);
+  if (!existing.hooks) existing.hooks = {};
+
+  for (const key of Object.keys(template)) {
+    if (key === 'hooks') continue;
+    if (!(key in existing)) existing[key] = template[key];
+  }
+
+  for (const event of Object.keys(template.hooks)) {
+    const templateEntries = template.hooks[event];
+    const currentEntries = existing.hooks[event] === undefined || existing.hooks[event] === null ? [] : existing.hooks[event];
+    if (!Array.isArray(currentEntries)) {
+      throw new Error(`Existing ${targetPath}: hooks.${event} must be an array; fix or move the file, then re-run \`devlog-tracker init\` (safe to re-run).`);
+    }
+    const kept = currentEntries.filter((entry) => !JSON.stringify(entry).includes(MARKER));
+    existing.hooks[event] = kept.concat(templateEntries);
+  }
+
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, `${JSON.stringify(existing, null, 2)}\n`);
+}
+
+module.exports = { mergeHooksTemplate, MARKER };