dflow-sdd-ddd 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -6,6 +6,162 @@
 
 ---
 
+## 0.16.0 — 2026-09-28 — 收尾歸檔的機械檢查 `dflow check-closeout`、單 phase 也走 finish-feature、commit 檢查點與 post-hoc 的紀錄、最小 host 更正自己的紀錄
+
+**Proposals**：PROPOSAL-094（`new-feature` 8.4 不再是收尾路）、PROPOSAL-103（`modify-existing` 的 commit 檢查點移到更新文件之後）、PROPOSAL-102（post-hoc 補文件記哪一顆 commit、從哪裡切）、PROPOSAL-104（最小 host 在 checkpoint 1 之後更正它自己的紀錄）、PROPOSAL-105（收尾歸檔的機械檢查 `dflow check-closeout`）
+
+### 從 `0.15.0` 升上來
+
+照 [`docs/upgrading.md`](docs/upgrading.md) 升級：先升 CLI，在專案根目錄跑 `dflow configure-agents`，再跑 `dflow doctor`。這一版另外要注意：
+
+1. **收尾做到一半的 feature，先用你現在這一版收完，再升級。**
+2. **已經走舊 8.4 收掉、commit 進 `completed/` 的 feature：不用改。** 它們是凍結的歷史：`completed/` 裡的 feature
+   不再接受新的規格或變更（follow-up 在原 feature 的 Follow-up Tracking 加列、收尾時翻那一列，這類追蹤更新例外）。
+   這些 feature 會留著兩個過期的欄位：Resume Pointer 停在「new-feature／Step 8」、Phase Specs 表那一列是
+   `in-progress`。`/dflow:status` 不讀它們（它只讀 `active/` 底下的 cursor），`dflow render` 會照原樣畫出來；
+   之後若有人對這樣的 feature 跑 PR review，它會把「Phase Specs 那一列與 phase-spec 的狀態不一致」標出來——那是
+   舊路徑留下的歷史，一樣不用改。
+3. **`_index.md` 範本升成形狀第 3 號**（下面 P-103、P-102 兩項；只改說明文字，段落與欄位都沒變）：`dflow doctor` 看到帶著舊標記的
+   `_index.md` 會多一條 `info`，說明怎麼處理（見下面 P-103 那一項）；`completed/` 底下的 feature 不檢查。
+4. **新子指令 `dflow check-closeout`** 要用才接（pre-commit hook 或 CI），接法見 [`docs/closeout-check.md`](docs/closeout-check.md)；
+   沒接就沒有任何變化。
+5. 其餘各項都沒有遷移動作。dist 投影過的 `0.15.1`–`0.15.5` 都在這一版裡。
+
+**驗證**：發布前 `scripts/check-repo-consistency.sh` 全數通過（含 `npm test` 十支與 `npm pack --dry-run`）。
+
+### 各項變更
+
+- **收尾歸檔的機械檢查：新子指令 `dflow check-closeout`（PROPOSAL-105，dist issue #5）**：
+  `/dflow:finish-feature` 收尾時的一致性檢查全部由 AI 執行；某一步被跳過，不一致的歸檔就會沒人發現地落地——
+  目錄已經搬進 `completed/`，裡面的 `_index.md` 卻還寫著 `status: in-progress`（#5 回報的正是這種：`git mv` 之後的
+  修改沒有 `git add`）。現在多了一個以結束碼當閘的檢查，由團隊自己接到 pre-commit hook 或 CI：
+  - **`dflow check-closeout`**（同 `--staged`，給 pre-commit hook）檢查 index，也就是這顆 commit 要記下的內容；
+    **`--range <base>..<head>`**（給 CI）檢查 merge request 的最終狀態。只看這次變動**新歸檔**的 feature 目錄；
+    已經在 `completed/` 的不回頭讀，只有一個例外：`--staged` 會再檢查一次 `HEAD` 這顆 commit 自己歸檔的（好讓修正
+    收尾 commit 的 amend 也被檢查）。
+  - 每個新歸檔的目錄檢查五項：`_index.md` 與每一份 spec（`lightweight-*`、`BUG-*`、`phase-spec-*`，從出貨範本推導）
+    都寫著 `status: completed`；`active/` 沒有留下副本；Checkpoint Log 有一列真正的 `closeout`，Result 是
+    `committed` 或 `skipped`（範本自帶的佔位列不算，`failed` 擋下）；`--staged` 時，歸檔目錄底下沒有漏 stage、
+    也沒有還沒 add 的檔。
+  - 結束碼 `0` 放行、`1` 擋下，每一條都寫出是哪個目錄、哪裡不對、怎麼修。讀不準的寫法（沒有 frontmatter、較早的
+    closeout 列寫法、不是從 `active/` 同名搬來的目錄——包括替已歸檔的 host 改名……）報成 `[uncertain]`，一樣擋下，
+    不報成通過，由人確認後放行。
+  - **通過不代表收尾是乾淨的**：`/dflow:finish-feature` Step 4 其餘的驗證（對照收尾基準的逐檔比對、收尾 commit
+    只帶准許的路徑、回填 hash 的身分、最小 host 剛好兩顆 commit）仍由 AI 做、由 pr-review 把關。
+  - **接法範本**在新文件 [`docs/closeout-check.md`](docs/closeout-check.md)（英文版 `closeout-check.en.md`）：
+    pre-commit hook（POSIX sh；一般 commit 不啟動 Node；沒裝 `dflow` 的電腦印一行後放行），以及 GitLab 與
+    GitHub Actions 的 CI job（版號取自專案 workflow bundle 的 manifest）。**Dflow 不在你的專案裡安裝任何 hook 或
+    CI 檔**；`dflow doctor` 不變（仍然只回報，結束碼仍是 0）。
+  - 兩軌 `git-integration.md` 的「CI / hook automation」一節改寫成出貨的現況。既有專案再跑一次
+    `dflow configure-agents` 即取得那一節；**沒有遷移動作**，hook 與 CI 要用才接。
+
+- **最小 host 在 checkpoint 1 之後更正它自己的紀錄（PROPOSAL-104，dist issue #8）**：
+  checkpoint 1 之後、關帳之前才發現 checkpoint 1 自己的紀錄寫錯了（規格內文、某一列的文字、baseline capture 寫進的
+  文件、follow-up 在原 feature 寫的反向連結），關帳會擋下，卻沒有任何地方說怎麼辦。現在：
+  - **關帳照舊擋下，並指到新的分支檔 `finish-feature-record-correction.md`**（只在這種情況才打開，平常的關帳不讀它）：
+    還沒 push、而且 checkpoint 1 就是 `HEAD` → 只 stage 更正、`git diff --cached` 確認、`git commit --amend`，再把記
+    checkpoint 1 hash 的格子改成新的 hash；checkpoint 1 之後已經有別的 commit、或已經 push → 停下來交給你決定。
+    另成一顆的更正不加 Checkpoint Log 列，並在 PR 說明裡指名。
+  - **關帳讀每支檔的變動改用 `git diff HEAD -- {path}`**：原本的 `git diff -- {path}` 看不到已經 `git add` 的變動 ——
+    已 stage 的更正在最小 host 的工作樹檢查裡會顯示成沒有變動，可能就這樣搭上關帳那顆 commit。最小 host 的工作樹檢查與
+    關帳 commit 要 stage 哪些變動的那一步（每一種 host）都改了。
+  - **pr-review 的「剛好兩顆 commit」規則不變**：另成一顆的更正碰到 host 目錄時，那一項照樣標出偏離，並說明它可能是
+    這種更正，接不接受由審查的人讀完它的 diff 與 PR 說明之後判斷；只碰 host 目錄以外的紀錄（baseline capture 的文件、
+    原 feature 的 `_index.md`）時，那一項看不到它，只有 PR 說明會提到它。
+  - **post-hoc 補文件記成了別的修正**（關帳時的 item 6）：照同一支分支檔更正 checkpoint 1，並把 Checkpoint Log 的
+    `reconciled (...)` 改記正確那個修正的 commit，再照 item 6 驗一次。`modify-existing` 裡「`reconciled (...)` 不得覆寫」
+    那句同時寫明例外：只有關帳照 item 6 更正它。
+  - **#8 的另一半 —— 改動被 cherry-pick 到第二條長期分支之後 `Commit` 格填哪一顆 —— 不在出貨檔加規則。**
+    GitFlow starter 用 merge 把 hotfix 帶回 `main` 與 `develop`；Dflow 的 host 分支（`feature/`、`bugfix/`）又是在
+    merge 之前就收尾完成，關帳在 host 自己的分支上驗它自己的那一顆。收尾之後再被 cherry-pick 到別的分支，跟著過去的
+    紀錄仍指原本那一顆，那是預期的樣子。`Commit` 格只放一個 hash：寫成 `A / B` 這種多個值，關帳一律當成「從未填入」。
+  - 兩軌對稱（baseline capture 只在 brownfield）。既有專案再跑一次 `dflow configure-agents` 即取得（workflow bundle
+    多一支分支檔）；**沒有遷移動作**。
+
+- **post-hoc 補文件：記哪一顆 commit、文件分支從哪裡切，都寫明了（PROPOSAL-102，dist issue #13）**：
+  急修（hotfix）合併之後才補 Dflow 文件（post-hoc 模式）時，關帳會檢查記下的那顆 commit 是不是文件分支的祖先。
+  但記哪一顆沒有定，文件分支從哪裡切也沒寫，於是 GitFlow 專案照 Dflow 自己的 starter 做 —— 記 `main` 上打 tag
+  的那顆 merge commit、從 `develop` 切文件分支 —— 一路順利，**要到關帳才被擋**，訊息只說「不是祖先」。現在：
+  - **記修正自己的 commit**（修正分成幾顆的，記碰到宣告路徑的最後一顆）：**不記任何 merge commit**，GitFlow 下也不是
+    打 tag 的那顆（合回的是 hotfix 分支，那顆不會跟著進 `develop`）。squash 合併記那顆 squash commit；rebase 合併或
+    cherry-pick 進 base 的，記它落到 base 上的副本。修正自己的 commit 在 base 上時就記它，即使先進來的是副本（例如先
+    cherry-pick、之後才合回）。出處照舊引用 PR／事件／追蹤單，不寫 hash。
+  - **建立任何東西之前先檢查切點**：先 fetch base 所在的 remote，確認那顆是 commit、不是 merge commit、它的改動碰到要宣告的實作路徑、而且已經在
+    要切的 base 上；不在的話說出兩種成因（記錯了顆，或還沒合回），**不要改從 `main` 切**。切的時候不追蹤 base。
+  - **關帳時祖先檢查不過，會說原因並給更正路徑**：記錯了顆 → 只改 Checkpoint Log 那一列，跟著關帳 commit 進去；
+    文件分支切得比修正進 base 還早 → 先把 base 合進來；**絕不把 `main` 或 tag 合進文件分支**。
+  - 關帳對那顆 commit 的路徑檢查寫明為「**至少碰到一條**宣告的路徑」—— 修正分成幾顆 commit 時，記下的那一顆只帶自己那一份。
+  - **pr-review 確認身分：對照出處**。打開出處（PR／事件／追蹤單），確認它指名的是這個修正，以及記下的那一顆（修正自己的
+    commit，或 squash commit）—— 有 PR 時，PR 頁面上直接看得到；沒有 PR 的急修，靠出處與 base 的歷史（hotfix 分支名、
+    commit 訊息裡的編號）認出修正的 commit。修正以副本落到 base 的（rebase 合併、
+    cherry-pick），出處不一定列得到那顆副本：清單寫明 git 證明不了一顆 commit 是另一顆的副本（祖先關係追不到副本；
+    `git cherry` 這類 patch 比對分不出只差在空白的兩個改動），`(cherry picked from commit …)` 那一行只是線索；遇到時
+    照出處跟作者確認，不拿指令輸出當成已確認。
+  - GitFlow starter 的「Hotfix spec requirement」多一句：記 hotfix 自己的 commit，不是打 tag 的那顆（記下的從來不是
+    merge commit，而且第 4 步合回的是 hotfix 分支，打 tag 那顆不會跟著進 `develop`）。tutorial 的 brownfield 範例跟著帶上。
+  - **`_index.md` 範本升成形狀第 3 號**：Lightweight Changes 與 Checkpoint Log 的兩段說明改成指向 post-hoc 分支檔的規則
+    （只改說明文字，段落與欄位都沒變）。`dflow doctor` 對帶著較舊標記的 `_index.md` 照舊只給 `info`：說明改了措辭、
+    不影響結構，要不要同步由你和 AI 決定；還沒收尾的最小 host 請先別動它，`completed/` 底下的 feature 不檢查。
+  - 兩軌對稱。既有專案再跑一次 `dflow configure-agents` 即取得（starter 那一句在可刷新區內）；**沒有遷移動作**。
+
+- **`modify-existing`（含 `/dflow:bug-fix`）的 commit 詢問，移到更新文件那一步做完之後（P-103，issue #7）**：
+  以前在「實作完成」那一關（brownfield Step 5 → Step 6、greenfield Step 4 → Step 5）就問要不要 commit，接著才更新
+  文件（規格標成完成、`rules.md`／`behavior.md` 等）。那一步寫的東西原本要等收尾那一顆 commit 才帶走，但流程在那一步
+  沒講；照直覺另外 commit，就多出一顆——在最小 host（只為一個小改動開的 feature 目錄）上，PR review 的「剛好兩顆」會
+  把它標出來。現在：
+  - 那一關只問要不要進更新文件那一步；**那一步（brownfield Step 6、greenfield Step 5）全部做完、宣告完成時才問要不要
+    commit**。這一顆 checkpoint 1 同時帶著程式、規格和那一步更新的文件，T2 就是這一顆加上收尾那一顆。那一步的驗證
+    因此在 commit 之前做完，驗不過先修再 commit。
+  - 最小 host 的收尾工作分成兩半：規格標成完成、Current BR Snapshot 的最後一次更新在 commit 之前做；commit 之後只補記
+    checkpoint 1 的 hash（Checkpoint Log、`Commit` 欄）與 Resume Pointer。
+  - 在新位置回答 N（不要 AI 代 commit）：程式連同更新好的文件由你自己 commit。之後照舊補帳：最小 host 把 Checkpoint Log
+    那一列從 `skipped` 補成 `committed ({hash})`（post-hoc host 維持 `reconciled (...)`），各列 `Commit` 欄填你那顆 commit
+    的 hash；有 phase 的 feature 底下的變更，那一列照舊記 `skipped`，`Commit` 欄照舊由之後的 commit 補上（最晚在收尾時）。
+  - `/dflow:new-feature`、`/dflow:new-phase` 的檢查點位置不變：它們完成那一步寫的東西，照舊搭這個 feature 的下一顆
+    commit——不管下一顆是什麼：下一個 phase 的第一個檢查點、掛在同一個 feature 底下的小改動那一顆，或收尾。
+  - 照舊時序做完的 feature（在實作完成那一關就 commit、文件等收尾才帶）用新版收尾，照樣過得了檢查。
+- **「commit 帶不了自己的 hash」寫成一條規則（P-103，issue #7）**：記一顆 commit 的 hash 的那幾格（Checkpoint Log 的
+  `committed ({hash})`、Lightweight Changes 的 `Commit` 欄）一律在那顆 commit 之後才寫，搭這個 feature 的下一顆 commit；
+  收尾那一列不填 hash，因為這個 feature 之後再也沒有 commit 會帶上它。以前只有收尾那一列講清楚。
+- **`_index.md` 範本升成形狀第 2 號**：Checkpoint Log 那段說明跟著上面兩項改寫（只改說明文字，段落與欄位都沒變）。
+  `dflow doctor` 看到帶著第 1 號標記的 `_index.md`：`active/` 底下有 phase 的 feature，多一條 `info`，說明那段 `>`
+  說明改了措辭、不影響結構，要不要同步由你和 AI 決定；還沒收尾的最小 host，同一條 `info` 只請你先別動它（收尾後它移到
+  `completed/`，就不再檢查）；`completed/` 底下的 feature 不檢查。
+
+- **單 phase 的 feature 也一律用 `/dflow:finish-feature` 收尾（P-094）**：
+  `/dflow:new-feature` 的 8.4 原本是第二條收尾路——只有一個 phase 的 feature 可以不跑 finish-feature，直接在這裡翻
+  `_index.md` 的 `status`、把目錄 `git mv` 進 `completed/`。但它不把 Resume Pointer 設回 `none`，也沒有 `git add`、
+  沒有 commit：走這條路收掉的 feature，`_index.md` 永遠停在 `Active Workflow: new-feature`／`Current Step: Step 8`。
+  現在 8.4 改名 **Phase completion and handoff**，只做兩件事：
+  - **完成這個 phase**：phase-spec 的 `status`、`_index.md` Phase Specs 表那一列都翻成 `completed`；Current BR Snapshot
+    對照這個 phase-spec 的 Business Rules 對帳（只動這個 phase 自己的列）；Resume Pointer 的 Current Progress、
+    Next Action 兩行都改寫。這四項正是 finish-feature 接手時會檢查、或直接採信的。
+  - **交出去**：還有下一個 phase → `/dflow:new-phase`；沒有了 → `/dflow:finish-feature`，唯一的收尾路。
+    new-feature 不再宣告「feature complete」——那要等 finish-feature 宣告收尾完成才說。
+
+  **你會多遇到的**：單 phase 的 feature 收尾變成 finish-feature 的完整流程——開頭要讀得到 `_conventions.md` 的
+  `## Prose Language`；Step 1 的結構檢查與分支檢查（要在這個 feature 的分支上，或它記錄過的 override 分支；
+  「已經切到別的分支才想起要歸檔」會被擋下）；兩道 Step Gate；收尾 commit checkpoint（AI 問要不要替你 commit——
+  可以選的是誰 commit，不是要不要 commit：選 N 就要自己 commit）與 commit 之後的驗證；AI 先說明收尾驗證是怎麼
+  算出來的，再給最後的 Integration Summary；宣告收尾完成之後，還會列出其他還在進行的 feature 與分支。
+  bounded context 的文件同步會跑兩次：8.3 先依實作同步，finish-feature 的 Step 3 再以 Current BR Snapshot 為準對一次
+  （8.4 已經對過帳，第二次通常只是確認一致）。
+  多 phase feature 的第一個 phase 也照新的 8.4 標成完成——以前沒有任何 flow 替它做，到 finish-feature 時會被 Step 1 擋下、
+  只能手修。
+
+- **merge 前的關統一成同一個「收尾完成」（P-094）**：`git-integration.md` 的 `feature/`、`bugfix/` merge 前清單，
+  與四支 `Git-principles-*.md` starter 的 merge 前清單，原本只看「目錄可以 `git mv`／已經搬了」或「finish-feature 跑過
+  （或 8.4 手動歸檔）」——都擋不住收尾做到一半的 feature：`status` 在 finish-feature 的 Step 2 就翻了，`git mv` 在收尾
+  commit 之前。現在一律是 **Closeout complete**：finish-feature 已宣告收尾完成，也就是收尾 commit 做了、commit 之後的
+  驗證過了；帶 `follow-up-of` 的，Step 6 的追蹤 commit 也做了、驗證過。
+  starter 那一格在 `git-principles-canonical` 區內：採用了 marker 的專案重跑 `dflow configure-agents` 就會刷新——前提是
+  `_conventions.md` 的 `## Git Policy` 讀得到所選的 policy，讀不到時它不刷新這支檔、並說明原因；還沒採用 marker 的，
+  `dflow doctor` 照舊會提示。
+
+- **README 的流程圖**：進 `/dflow:finish-feature` 那條箭頭的標籤改成「沒有下一個 phase」（英文版 `no further phase`），
+  前一格改成「這個 phase 完成」（`Phase done`）；中文版進 `/dflow:new-phase` 那條箭頭跟著改成「還有下一個 phase」。
+  「feature 完成」要等 finish-feature 收尾完成才說。
+
 ## 0.15.0 — 2026-09-27 — 分級改為順序判定、analysis.md 與 render 畫圖、doctor 看不準就直說
 
 **Proposals**：PROPOSAL-077（A1 — spec 人讀可讀性：render 長欄位排版）、PROPOSAL-078 phase 1（formatting convention 投遞與偵測）、PROPOSAL-079（render index completed/ 年度分頁）、PROPOSAL-081（README 瘦身重組＋防過度設計特點露出）、PROPOSAL-082（Tier 邊界語意改為順序 cascade）、PROPOSAL-083（standalone minimal host 生命週期）、PROPOSAL-084（`doctor` 誠實揭露不確定性）、PROPOSAL-085（flow reference 執行期體積）、PROPOSAL-086（受限標頭比讀者窄）、PROPOSAL-087（finish-feature 罕見路徑抽離）、PROPOSAL-090（`Git-principles-*.md` 的 canonical 區改為可刷新）、PROPOSAL-091（`doctor` 的兩條 false-clean 路徑）、PROPOSAL-093（closeout 尾巴的 cursor 矛盾）、PROPOSAL-095（BR Snapshot 範例列移出資料面）、PROPOSAL-096（closeout baseline 的鑰匙改為可推導）、PROPOSAL-099（系統級知識的落點）、PROPOSAL-100（render 把生命週期與流程畫成圖）、PROPOSAL-101（render 首頁改成分組目錄）、PROPOSAL-092（規格文件的形狀版號）

package/CONTRIBUTING.md

@@ -92,6 +92,7 @@ Common shared flows include:
 - `finish-feature-follow-up.md`
 - `finish-feature-minimal-host.md`
 - `finish-feature-post-hoc-hotfix.md`
+- `finish-feature-record-correction.md`
 - `modify-existing-follow-up.md`
 - `modify-existing-post-hoc-hotfix.md`
 - `drift-verification.md`

package/README.en.md

@@ -132,7 +132,7 @@ confirm direction with you — the flow is drawn above in
 
 To name a flow yourself (when you already know this is a new feature, say), or to see
 everything Dflow covers, read the [Command Reference](docs/commands.en.md): the 11
-workflows, how to type them in each AI tool, and the four `dflow` CLI commands.
+workflows, how to type them in each AI tool, and the five `dflow` CLI commands.
 
 For the first adoption pass, use a branch or disposable sample project so your
 team can inspect the generated `dflow/specs/` workspace before bringing the
@@ -287,6 +287,8 @@ Once `/dflow:finish-feature` moves a feature directory into `completed/`, **no d
 
 Why: "completed = frozen history" is a core Dflow guarantee. Accepting post-completion edits would erase the feature-lifecycle endpoint and make `_index.md`'s BR Snapshot unreliable. `/dflow:modify-existing` detects when the target is a completed feature and prompts the developer with three choices: A — follow-up; B — independent concern (**T1** goes to `/dflow:new-feature`; **T2 / T3** stay in `/dflow:modify-existing` and open a standalone minimal host); C (refused, re-directed to A).
 
+**Advanced: wire the closeout check into a hook or CI.** The AI runs the closeout's consistency checks; when a step is skipped, an inconsistent archive (the directory in `completed/` while the `_index.md` inside it still says `in-progress`) can land without anyone noticing. To have git stop it mechanically on the closeout commit or the merge request, see [Checking the closeout commit](docs/closeout-check.en.md): `dflow check-closeout` plus pre-commit hook and GitLab / GitHub CI templates, which your team wires in itself.
+
 ## Files Created by Init
 
 A typical initialized project receives a `dflow/` workspace:
@@ -423,15 +425,16 @@ Publish Checklist](docs/npm-publish-checklist.md).
 ## Status
 
 Dflow is currently published as `dflow-sdd-ddd` on npm. The latest published
-npm package is `0.15.0`, providing:
+npm package is `0.16.0`, providing:
 
 - Project scaffolding and upgrades: `dflow init` (initialization), `dflow configure-agents` (idempotent upgrade re-projection), `dflow doctor` (read-only health check with drift detection), `dflow render` (specs → human-readable HTML)
+- A mechanical closeout check: `dflow check-closeout` (its exit code is the gate; your team wires it into a pre-commit hook or CI — see [`docs/closeout-check.en.md`](docs/closeout-check.en.md))
 - Workflow documentation (the 11 `/dflow:*` flows) plus the project-vendored workflow bundle and multi-AI-tool setup (canonical guide, thin per-tool shims, project-level skill installed by default)
 - Public evaluation material inside the package: evaluator guide and per-tool walkthroughs for Claude Code / Codex CLI / GitHub Copilot (all under `docs/`)
 - Greenfield / Brownfield scenario tutorials and worked spec examples: **in the source repository, not in the npm package** (the tarball does not include `tutorial/`) — see [`tutorial/`](https://github.com/weilung/dflow-sdd-ddd/tree/main/tutorial)
-- A verification-only CI workflow (it does not execute publish)
+- A verification-only CI workflow (it does not execute publish): **in the source repository, not in the npm package**
 
-The GitHub source may include post-`0.15.0` repository changes before the
+The GitHub source may include post-`0.16.0` repository changes before the
 next npm release is published. See [CHANGELOG.md](CHANGELOG.md) for full
 release history.
 

package/README.md

@@ -102,7 +102,7 @@ AI 會判斷該走哪一條 workflow 並主動啟動，然後在每個決策點
 
 想自己指定某條 flow（例如你已經確定這是一個新 feature），或想知道 Dflow 總共涵蓋哪些
 情境，見[指令參考](docs/commands.md)：11 條 workflow、各 AI 工具的輸入方式、以及 `dflow`
-CLI 的四個指令。
+CLI 的五個指令。
 
 第一次採用建議用 branch 或一次性試用專案，讓團隊先檢視產生的 `dflow/specs/` 工作區，再把流程引入正式程式碼。
 
@@ -217,6 +217,8 @@ Dflow 用 `_index.md` 解決這三點：Current BR Snapshot 每完成一個 phas
 
 理由：「completed = 凍結歷史」是 Dflow 的核心保證；若接受 post-completion 修改，feature lifecycle 就失去明確終點、`_index.md` BR Snapshot 也無法可信。`/dflow:modify-existing` 偵測到目標是 completed feature 時會主動詢問 user 三個選項：A 走 follow-up、B 當獨立新需求（**T1** 走 `/dflow:new-feature`；**T2／T3** 留在 `/dflow:modify-existing`，開一個 standalone minimal host）、C（被拒絕，重新引導至 A）。
 
+**進階：把收尾檢查接到 hook／CI。** 收尾的一致性檢查由 AI 執行；某一步被跳過時，不一致的歸檔（目錄已在 `completed/`，裡面的 `_index.md` 卻還是 `in-progress`）會沒人發現地落地。想讓 git 在收尾 commit 或 merge request 上機械地擋下它，見[收尾 commit 的機械檢查](docs/closeout-check.md)：`dflow check-closeout` 加上 pre-commit hook 與 GitLab／GitHub CI 的接法範本，由你的團隊自己接。
+
 ## Init 產生的檔案
 
 典型初始化專案會建立 `dflow/` workspace：
@@ -301,15 +303,16 @@ issue 與 pull request 指引見 [CONTRIBUTING.md](CONTRIBUTING.md)。Pull reque
 
 ## 狀態
 
-Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.15.0`，提供：
+Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.16.0`，提供：
 
 - 專案 scaffolding 與升級：`dflow init`（初始化）、`dflow configure-agents`（idempotent 升級重投影）、`dflow doctor`（唯讀健康檢查與漂移偵測）、`dflow render`（specs → 人類可讀 HTML）
+- 收尾歸檔的機械檢查：`dflow check-closeout`（以結束碼當閘，由團隊自己接到 pre-commit hook 或 CI；接法見 [`docs/closeout-check.md`](docs/closeout-check.md)）
 - Workflow 文件（11 個 `/dflow:*` 流程）＋隨專案 vendored 的 workflow bundle＋多 AI 工具設定（canonical 指南、各工具薄 shim、預設安裝的 project-level skill）
 - 套件內的公開評估材料：evaluator 指南、Claude Code / Codex CLI / GitHub Copilot per-tool walkthrough（都在 `docs/`）
 - Greenfield / Brownfield 劇情教學與規格範例：**在 source repository，不在 npm 套件裡**（tarball 不含 `tutorial/`）——見 [`tutorial/`](https://github.com/weilung/dflow-sdd-ddd/tree/main/tutorial)
-- 僅驗證的 CI workflow（不執行 publish）
+- 僅驗證的 CI workflow（不執行 publish）：**在 source repository，不在 npm 套件裡**
 
-GitHub 上的 source 可能包含 `0.15.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
+GitHub 上的 source 可能包含 `0.16.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 授權
 

package/bin/dflow.js

@@ -14,6 +14,7 @@ Usage:
   dflow configure-agents  Add or update AI agent instruction shims
   dflow doctor            Read-only project health check
   dflow render            Render the specs Markdown tree to browsable HTML
+  dflow check-closeout    Gate a closeout commit (for a pre-commit hook or CI)
   dflow --help            Show this help
   dflow --version         Show the CLI version
 `);
@@ -130,6 +131,62 @@ Doctor never modifies files.
 `);
 }
 
+function printCheckCloseoutHelp(specGlobs, docUrl) {
+  process.stdout.write(`Usage:
+  dflow check-closeout [--staged]
+  dflow check-closeout --range <base>..<head>
+
+A gate for the closeout commit of /dflow:finish-feature: it checks the
+feature directories newly archived to dflow/specs/features/completed/ and
+exits 1 when one is inconsistent, so a pre-commit hook or a CI job can stop
+the commit or the merge request. It reads git only and never modifies
+anything. Run it from the directory that holds dflow/specs/ (the project may
+sit below the repository root).
+
+Modes:
+  --staged (default)       Check the index (what git commit will record),
+                           for a pre-commit hook. A host the HEAD commit
+                           itself archived is checked too unless HEAD is a
+                           merge, so amending a closeout commit is checked;
+                           the commit after a closeout re-checks that host.
+  --range <base>..<head>   Check the final state of <head> against its merge
+                           base with <base>, for CI on a merge request or
+                           pull request. Needs the full history.
+
+In scope: a directory under completed/ that has files after the change and
+had none before. One that was in active/ under the same name (for --range:
+at the merge base or in any commit of the range) is checked. Any other —
+renamed on the way, created directly in completed/, or an archived host
+renamed — is reported as uncertain, for a person to confirm. Hosts that were
+already in completed/ are not read again, except the ones --staged re-checks
+because the HEAD commit archived them.
+
+Checked for each newly archived host:
+  1. _index.md exists and its frontmatter says status: completed
+  2. nothing is left under features/active/<host>/ (moved, not copied)
+  3. every spec file (${specGlobs.join(', ')}) says status: completed
+  4. the Checkpoint Log has a closeout row (not the template's placeholder)
+     whose Result is committed or skipped
+  5. --staged only: nothing under the archived directory is left unstaged
+     or untracked in the working tree
+
+Not checked, and still up to the AI's Step 4 verification and pr-review: the
+file-by-file comparison with the closeout baseline, that the commit carries
+only the paths closeout may write, the identity of hosted Commit cells, and a
+minimal host's hash evidence and exactly-two-commits rule. Passing does not
+mean the closeout is clean.
+
+Exit status: 0 when no host is in scope or every one passes; 1 when a check
+fails, a shape cannot be read with confidence ([uncertain]), or the check
+cannot run (not a git repository, no dflow/specs/ here, bad arguments).
+
+Hook and CI templates, and how to handle [uncertain]:
+${docUrl}
+(offline: docs/closeout-check.en.md in the installed package; Traditional
+Chinese: docs/closeout-check.md)
+`);
+}
+
 async function main() {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     printHelp();
@@ -217,6 +274,24 @@ async function main() {
     });
   }
 
+  if (args[0] === 'check-closeout') {
+    // Loaded only for this subcommand. It reads lib/doc-shapes.json when it runs,
+    // never when it loads, so a damaged registry cannot stop `dflow doctor` from
+    // starting and reporting it; here a damaged registry is an error.
+    const closeoutCheck = require('../lib/closeout-check');
+    if (args.length > 1 && (args[1] === '--help' || args[1] === '-h')) {
+      printCheckCloseoutHelp(await closeoutCheck.specFileGlobs(), closeoutCheck.CLOSEOUT_CHECK_DOC_URL);
+      return 0;
+    }
+
+    return await closeoutCheck.runCheckCloseout({
+      cwd: process.cwd(),
+      args: args.slice(1),
+      stdout: process.stdout,
+      stderr: process.stderr
+    });
+  }
+
   process.stderr.write(`Unsupported subcommand: ${args[0]}\n\n`);
   printHelp();
   return 1;

package/docs/closeout-check.en.md

@@ -0,0 +1,204 @@
+# Checking the closeout commit: `dflow check-closeout`
+
+> [繁體中文](closeout-check.md) | **English**
+
+> This page tracks the source `main` branch. `dflow check-closeout` first ships in Dflow `0.16.0` (the public source has it from `0.15.5`); if `dflow check-closeout --help` answers `Unsupported subcommand`, your installed CLI predates it. `@latest` installs the latest **published** CLI, which does not guarantee that a feature on this page has been released — the changelog of a published release says what it includes.
+
+`/dflow:finish-feature` closes a feature out: it marks the feature directory completed, moves it from `dflow/specs/features/active/` to `dflow/specs/features/completed/` with `git mv`, records the closeout in its `_index.md`, and commits — then checks the commit. Every one of those steps is an instruction the AI follows. When one is skipped, an inconsistent archive can land without anyone noticing: the directory is in `completed/` while the `_index.md` inside it still says `status: in-progress`, or a copy is left behind in `active/`. Nothing reads an archive after that.
+
+`dflow check-closeout` moves the mechanical part of that check from "the AI remembers to run it" to "git runs it": a command whose **exit code is a gate**, for a pre-commit hook or a CI job that you set up once. Dflow does not install either for you — the templates are below.
+
+## What it checks
+
+It looks only at feature directories **newly archived** by the change: a directory under `dflow/specs/features/completed/` that has files after the change and had none before. Whether git pairs the files as a rename (`R`) or as a delete plus an add (`D` + `A`) does not matter.
+
+- A directory that was in `active/` under the same name is a newly archived host, and is checked. For `--range`, "was in `active/`" means at the merge base or at any commit in the range — a feature branch usually opens its host and archives it.
+- Any other new directory — renamed on the way from `active/`, created directly in `completed/`, or an archived host renamed inside `completed/` — is reported as `[uncertain]`: `/dflow:finish-feature` moves a host without renaming it, so the gate does not guess which of these a directory is, and a person confirms it.
+
+For each newly archived host:
+
+1. `_index.md` exists and its frontmatter says `status: completed`.
+2. Nothing is left under `dflow/specs/features/active/<host>/` — the host was moved, not copied.
+3. Every spec in the host says `status: completed`. The spec files are the ones the shipped templates put in a feature directory with a `status` field: `lightweight-*.md`, `BUG-*.md` and `phase-spec-*.md`. A document your project adds to a host is not checked, whatever its frontmatter says.
+4. The `## Checkpoint Log` in `_index.md` has a `closeout` row whose Result is `committed` or `skipped`. The template's own placeholder row (Timestamp `{YYYY-MM-DD HH:MM}`, Result `committed / skipped / failed`) does not count. A Result of `failed` blocks: the commit you are making would record that its own commit failed — usually a hook refused an earlier attempt and the flow flipped the row.
+5. With `--staged` only: nothing under the archived directory is left out of the commit — a tracked file edited or deleted but not staged, or a new file that is neither added nor ignored.
+
+It reads the standard shapes exactly — the template's frontmatter, including a trailing `# in-progress | completed` comment and a quoted value; CRLF line endings; a byte-order mark; a directory name in any language. A document copied whole from a template's projected copy under `dflow/specs/shared/dflow-workflows/templates/` starts with `<!-- dflow-generated: workflow-bundle -->`; the frontmatter under that line is not frontmatter (to `dflow render` and `dflow doctor` either), so it fails, with the repair named: delete the line and the blank line after it.
+
+## What it does not check
+
+The rest of `/dflow:finish-feature`'s post-commit verification needs the closeout baseline and judgement, so it stays with the AI and with pr-review:
+
+- the file-by-file comparison of the archive against the closeout baseline;
+- that the closeout commit carries only the paths closeout may write;
+- that a backfilled `Commit` cell holds that row's own implementation hash;
+- for a minimal (zero-phase) host: that checkpoint 1 still carries the hash Step 1 verified, and that the host has exactly two commits. `--range` looks at the final state, so a minimal host repaired by a third commit passes here; pr-review's whole-history item counts it.
+
+It does not re-read hosts archived before the change, with one exception: `--staged` checks once more a host the `HEAD` commit itself archived (see "Running it" below). An archive made before this gate existed may be inconsistent, or written in an older shape; checking every old archive would block commits and merge requests that have nothing to do with it.
+
+**Passing does not mean the closeout is clean.** It means the parts a machine can judge are consistent.
+
+## Running it
+
+Run it from the directory that holds `dflow/specs/`. The project may sit below the repository root.
+
+```bash
+dflow check-closeout                          # the same as --staged
+dflow check-closeout --staged                 # a pre-commit hook: checks the index — what the commit will record
+dflow check-closeout --range <base>..<head>   # CI: checks the final state of <head> against its merge base with <base>
+```
+
+- `--staged` also checks a host the `HEAD` commit itself archived (unless `HEAD` is a merge commit). A pre-commit hook cannot tell `git commit --amend` from a new commit, and amending is how a minimal host repairs its closeout commit, so a host already in `HEAD` has to stay in scope. The cost: the commit right after a closeout checks that host once more, and passes when it is still consistent.
+- `--range` checks the **final state** of `<head>`, not each commit on the way: a closeout repaired by a later commit on the branch passes. It needs the full history (`git merge-base` has to find the base).
+
+### Exit status
+
+| Exit | Meaning |
+|---|---|
+| `0` | No feature directory is newly archived, or every one passed. |
+| `1` | A check failed (`[fail]`), a shape could not be read with confidence (`[uncertain]`), or the check could not run: not a git repository, no `dflow/specs/` in the current directory, bad arguments. |
+
+Each problem names the host, what is wrong, and how to fix it.
+
+### When it says `[uncertain]`
+
+An `[uncertain]` result blocks too: the gate will not report something it cannot read as passing. It appears for a shape the gate does not guess about — a spec with no frontmatter, or with two `status:` fields; no `## Checkpoint Log`, or one without `Checkpoint` and `Result` columns; a closeout row written in an older way (the explanation and the checkpoint in one cell, such as `closeout（/dflow:finish-feature）：…`); a new directory that was never in `active/` under its name — including an archived host you renamed.
+
+1. **Fix the shape if you can.** The message says how: restore the template's `status:` line, rewrite the row as Checkpoint `closeout` and Result `committed` or `skipped`. That is the durable fix — the next run reads it.
+2. **If you read it and it is right,** let that one commit through: `git commit --no-verify` for the hook; for CI, whatever your team uses to accept a merge request with a known failing job.
+
+⚠ Because of the amend rule above, a host that `HEAD` moved from `active/` is checked once more by the commit after it. So when you let such a host through with `--no-verify`, the next commit is blocked by it again; fixing the shape avoids that, otherwise that commit needs `--no-verify` too. (A directory reported because it was never in `active/` is not checked again.)
+
+## Pre-commit hook
+
+```sh
+#!/bin/sh
+# dflow check-closeout pre-commit hook
+# https://github.com/weilung/dflow-sdd-ddd/blob/main/docs/closeout-check.en.md
+#
+# If the Dflow project is not at the repository root, uncomment and set this:
+# cd path/to/project || exit 1
+
+# The same "before" that dflow check-closeout --staged uses: HEAD's parent when
+# HEAD is an ordinary commit (so amending a closeout commit is still checked),
+# HEAD itself when it is a merge or the first commit, and the empty tree before
+# any commit exists.
+if head=$(git rev-list --parents -n 1 HEAD 2>/dev/null); then
+  set -- $head
+  if [ $# -eq 2 ]; then before=HEAD^; else before=HEAD; fi
+else
+  before=$(git hash-object -t tree /dev/null)
+fi
+
+# Nothing under completed/ changed: an ordinary commit, and Node is not started.
+if git diff --cached --quiet "$before" -- dflow/specs/features/completed/; then
+  exit 0
+fi
+
+if ! command -v dflow >/dev/null 2>&1; then
+  echo "dflow check-closeout skipped: no dflow CLI on this machine (a CI job is the second line)." >&2
+  exit 0
+fi
+
+exec dflow check-closeout --staged
+```
+
+What it does, in order:
+
+1. It compares the index with the same "before" as `--staged`. When nothing under `completed/` changed, it exits at once — an ordinary commit costs a couple of git calls and never starts Node. A message-only amend of a closeout commit still reaches the gate, and so does the commit right after a closeout.
+2. When the `dflow` CLI is not installed on this machine, it says so in one line and lets the commit through: not everyone on a team has the CLI, and a CI job is the second line.
+3. Otherwise it runs `dflow check-closeout --staged`, and its exit code decides.
+
+**Installing it** — pick one:
+
+- **Shared with the team.** Save it as `.githooks/pre-commit` in the repository, make it executable (`chmod +x .githooks/pre-commit`), commit it, and have every clone run once:
+
+  ```bash
+  git config core.hooksPath .githooks
+  ```
+
+- **This clone only.** Save it as `.git/hooks/pre-commit` and make it executable.
+- **You already use a hook manager.** Save the script in the repository (for example `.githooks/dflow-closeout.sh`) and call it from the manager's configuration:
+  - husky — add a line to `.husky/pre-commit`: `sh .githooks/dflow-closeout.sh`
+  - lefthook — in `lefthook.yml`:
+
+    ```yaml
+    pre-commit:
+      commands:
+        dflow-closeout:
+          run: sh .githooks/dflow-closeout.sh
+    ```
+
+  - pre-commit — in `.pre-commit-config.yaml`:
+
+    ```yaml
+    repos:
+      - repo: local
+        hooks:
+          - id: dflow-closeout
+            name: dflow check-closeout
+            entry: sh .githooks/dflow-closeout.sh
+            language: system
+            pass_filenames: false
+            always_run: true
+    ```
+
+    ⚠ The pre-commit framework sets unstaged edits to tracked files aside before it runs hooks, so check 5 does not see those there. Checks 1–4 read what is being committed either way.
+
+On Windows, Git for Windows runs the hook with its own `sh`. When the Dflow project is below the repository root, uncomment the `cd` line: a hook starts at the repository root.
+
+## CI
+
+The CI job is the second line: it catches what reached the branch without the hook — a clone that never set it up, a machine without the CLI, a `--no-verify`. Both templates run the CLI with `npx`, taking the version from your project's workflow bundle (`"version"` in `dflow/specs/shared/dflow-workflows/.dflow-bundle-manifest.json`), so the gate follows the rules of the Dflow version your project uses — and follows it again after you upgrade. That version must include `check-closeout`; a CLI of another version judges by its own rules. The job needs Node 22 or later (`package.json` `engines`), and the full history.
+
+### GitLab (merge request pipeline)
+
+```yaml
+dflow-closeout:
+  image: node:22
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  variables:
+    GIT_DEPTH: "0"
+  script:
+    # - cd path/to/project   # if the Dflow project is not at the repository root
+    - DFLOW_VERSION=$(node -p "require('./dflow/specs/shared/dflow-workflows/.dflow-bundle-manifest.json').version")
+    # A merged results pipeline builds on a merge commit; the source branch head is what this merge request archived.
+    - npx --yes "dflow-sdd-ddd@$DFLOW_VERSION" check-closeout --range "$CI_MERGE_REQUEST_DIFF_BASE_SHA..${CI_MERGE_REQUEST_SOURCE_BRANCH_SHA:-$CI_COMMIT_SHA}"
+```
+
+The image needs `git` as well as Node — `node:22` has it; an Alpine image does not.
+
+### GitHub Actions (pull request)
+
+```yaml
+name: Dflow closeout check
+on: pull_request
+jobs:
+  closeout:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - name: dflow check-closeout
+        # working-directory: path/to/project   # if the Dflow project is not at the repository root
+        env:
+          PR_BASE: ${{ github.event.pull_request.base.sha }}
+          PR_HEAD: ${{ github.event.pull_request.head.sha }}
+        run: |
+          DFLOW_VERSION=$(node -p "require('./dflow/specs/shared/dflow-workflows/.dflow-bundle-manifest.json').version")
+          npx --yes "dflow-sdd-ddd@$DFLOW_VERSION" check-closeout --range "$PR_BASE..$PR_HEAD"
+```
+
+`--range` uses the pull request's head commit, not the merge commit GitHub checks out: a merge commit also carries whatever reached the base branch in the meantime, and someone else's archive should not decide your pull request.
+
+## What is left open
+
+- **Nothing is protected until it is set up.** This is set up once per repository (CI) and once per clone (the hook); it is never on by default.
+- **It can be bypassed:** `git commit --no-verify`, or a machine without the CLI. Only a CI job closes that.
+- **Only the mechanical part is checked** (above). The AI's verification in `/dflow:finish-feature` and pr-review still carry the rest.
+- **It follows the templates.** If a later template changes how `status` or the Checkpoint Log is written, the gate changes with it in the same release; a CLI and a bundle of different versions can disagree.