dflow-sdd-ddd 0.13.0 → 0.15.0

package/README.md

@@ -9,23 +9,48 @@
 >
 > 換句話說，不是「AI 會不會 DDD」，而是「AI 做 DDD 時，你能不能信他」。
 
-具體來說，它是一套 spec-first 的工作流程工具集，專為 AI 輔助軟體開發設計。它為你的 AI 程式設計助理提供具體流程，把變更需求轉成結構化規格、領域語言、實作計畫、漂移檢查、與可審查的程式碼，而不是從 prompt 直接跳到程式碼。
-
-目標不是流程本身，而是讓軟體變更可重複、語意更清楚、規則更不散落、行為更不依賴 prompt。
+具體來說，它是一套 spec-first 的工作流程工具集，專為 AI 輔助軟體開發設計：先把變更需求轉成結構化規格、領域語言與實作計畫，對齊之後才動程式碼，避免 AI 從模糊 prompt 直接生碼、方向錯了才回頭重做。目標不是流程本身，而是讓軟體變更可重複、語意更清楚、規則更不散落、行為更不依賴 prompt。
 
 ## 主要特點
 
 | 特點 | 對工程團隊的幫助 |
 |---|---|
-| **Spec-first 開發** | 把對齊推到實作之前，避免 AI 從模糊 prompt 直接生程式碼後才發現方向錯、回頭重做。 |
-| **Greenfield 與 Brownfield 雙軌** | 不只服務新專案；既有 codebase 不必先做大規模重構，可邊改邊把散落各處的領域規則抽出來。 |
-| **混合式工作流程控制** | 不是 autopilot 也不是純手動 — 明確命令進入、AI 在你忘記啟動時建議切入、重要決策點停下確認。三層共存讓 AI 不會一路跑偏，也不會把每一步都變成繁瑣流程。 |
-| **DDD 語意骨幹** | AI 最容易憑直覺發明業務規則（折扣何時有效、帳號權限邊界），這種錯誤 review 時人眼很難察覺。先把領域語言、邊界、業務規則寫下來，AI 補細節時受專案約束、而不是憑感覺。 |
-| **三層文件模型** | 對應 feature branch 的實際節奏：phase（單次提案-實作循環）/ feature（整條 branch 的累積狀態與接續指引）/ system（跨 feature 的長期知識）。許多 spec 工具只有 phase + system 兩層，多次迭代的 feature branch 跨多個 phase 時就會失真。下方有完整說明。 |
-| **依改動深淺的 Tier 制（T1/T2/T3）** | AI 依改動深淺自動決定規格與驗證量級：改顏色 / typo 只需 `_index.md` 一行；bug fix 用 lightweight spec + 聚焦驗證；新 feature 或動到 bounded context 才走完整 phase-spec + 分層實作計畫 / 驗證。小修改不會被流程拖累。 |
-| **漂移驗證** | `/dflow:verify` 把規格、領域文件、實作、測試、技術債紀錄做交叉比對，找出 PR review 人眼看不出來的「文件還在描述舊行為」漂移。 |
-| **Specs 給 AI 讀、也給人讀（md → HTML）** | 多數 spec-first 工具的規格只有 AI 好讀——密集表格加標記的 Markdown，人翻起來吃力，時間一久規格就沒人 review。`dflow render` 把整棵 specs 樹轉成可瀏覽的靜態 HTML：表格變卡片、AI 專用標記變 badge、跨檔連結可點。Markdown 仍是 AI 讀的 source of truth，人另有一份好讀的投影。下方有對照截圖。 |
-| **多 AI 工具共用一份規則** | Canonical 專案指南 + 各工具薄 shim（`CLAUDE.md` / `AGENTS.md` / Copilot instructions），團隊在 Claude / Codex / Copilot 之間切換時不必維護多份 workflow 規則。三家還共用一份依 agentskills.io 開放標準的 project-level skill，可用自然語言自動觸發對應 workflow（Copilot CLI 需先打 `/dflow` 喚起）。 |
+| **Greenfield 與 Brownfield 雙軌** | 新專案有空間早期塑形架構與領域模型；既有 codebase 不必先做大規模重構，邊改邊把散落各處的領域規則抽出來。 |
+| **AI 指引，不用先學指令** | 你把要做的事講出來，AI 判斷該走哪一條 workflow、要寫多少規格，並主動啟動；想自己指定也可以直接下命令。重要決策點一律停下確認——AI 不會一路跑偏，也不會把每一步都變成繁瑣流程。 |
+| **DDD 語意骨幹** | 先把領域語言、邊界、業務規則寫下來，AI 補細節時受專案約束、而不是憑感覺發明業務規則——那種錯誤 review 時人眼很難察覺。 |
+| **防過度設計內建於引導** | AI 被 DDD 引導後容易全面套用 rich model 與重型 pattern；Dflow 在多個常見的過衝位置寫了反向判準——哪裡不值得深度建模、何時停在最簡階梯。 |
+| **三層文件模型** | phase（單次提案-實作循環）／feature（整條 branch 的累積狀態）／system（跨 feature 長期知識），對應 feature branch 的實際節奏。下方有完整說明。 |
+| **DDD 的模型與規則裝不下的那一塊（`analysis.md`）** | `models.md` 收「存下來的是什麼」、`rules.md` 收「一條規則」、`behavior.md` 收「一個情境」——**沒有一支收「它怎麼動的」**。`analysis.md` 就是那一支，六節：跨 context 的交手順序（`FL-nn`）、一個狀態欄位的生命週期（`LC-nn`）、算出來而不是存下來的數字（`RM-nn`）、單一規則解釋不了的機制（`MX-nn`）、誰碰得到哪個功能的索引，以及一直被繞過的熱點。每一條標明出處（程式碼、資料、誰確認的、推論或假設）。不再只留在對話裡、或跟著 feature 收尾一起凍結；中途採用 Dflow 的既有專案，也靠它把系統現況一塊塊補齊。 |
+| **依改動深淺的 Tier 制（T1/T2/T3）** | AI 依改動深淺自動決定規格與驗證量級：改顏色／typo 這類小修（掛在所屬 feature 下）只需 `_index.md` 一行、功能性 bug fix 用 lightweight spec（T3 顯示層 defect 仍是 `_index.md` 一行）、新 feature 或動到 bounded context 級的變更才走完整 phase-spec。小修改不會被流程拖累。 |
+| **漂移驗證** | `/dflow:verify` 交叉比對規格、領域文件、實作、測試與債務紀錄，抓出「文件還在描述舊行為」這種 PR review 人眼看不出的漂移。 |
+| **Specs 給 AI 讀、也給人讀（md → HTML）** | `dflow render` 把 AI 取向的密集 Markdown specs 轉成可瀏覽的靜態 HTML。`analysis.md` 裡的狀態生命週期與跨 context 流程畫成圖：哪個狀態會繞回去、哪裡是終點，交手在哪幾個 context 之間移動，一眼看出來；其餘表格變卡片、標記變 badge（下方有對照截圖）。Markdown 仍是 AI 讀的 source of truth。 |
+| **多 AI 工具共用一份規則** | Canonical 專案指南＋各工具薄 shim（`CLAUDE.md` / `AGENTS.md` / Copilot instructions），在 Claude / Codex / Copilot 間切換不必維護多份規則；三家共用依 agentskills.io 開放標準的 project-level skill，可自然語言自動觸發（Copilot CLI 需先打 `/dflow` 喚起）。 |
+
+## 你不用先學指令
+
+把要做的事講出來就好，AI 會判斷該走哪一條 workflow、要寫多少規格：
+
+| 你說 | AI 走的路 |
+|---|---|
+| 「幫我加一個報銷單審核的功能」 | 新功能 → 完整規格（T1） |
+| 「這個欄位算錯了」 | 修 bug → 判 tier，多半是輕量規格（T2） |
+| 「把這個按鈕改成藍色」 | 顯示層小修（T3）→ `_index.md` 記一行就好 |
+
+`/dflow:new-feature`、`/dflow:modify-existing`、`/dflow:bug-fix` 這些名字**你可以完全不記得**
+——而且後兩個走的本來就是同一份 flow 文件，選錯也沒有後果。
+
+下面這張圖是你講完需求之後會發生的事。綠色的每一格都是 AI **停下來等你確認**的地方（Step Gate）；
+綠色那一格帶 commit 標記時，那個 Step Gate 會同時問你要不要 commit；藍色那一格帶標記則表示
+那一步會單獨問你要不要 commit——**它一樣會停，只是它不是 Step Gate**。
+⚠ **你會遇到幾個 Step Gate，由 flow 與 tier 一起決定**：不同 flow 不同；同一條 flow 裡，輕的 tier
+還會跳過一些關（`/dflow:modify-existing` 判成 T3 就不跑 DDD 影響評估那一關）；判成 T1 則可能整條
+升到 `/dflow:new-feature`／`/dflow:new-phase`。圖上走的是 `new-feature` 的四個，加上
+`finish-feature` 自己的兩個。
+
+![Dflow 流程圖：從「你講需求」開始，AI 判定要多少規格，分流到新功能或改既有／修 bug，接著沿 T1 完整路徑走過 new-feature 的四個 Step Gate 與兩個 commit 檢查點，最後回到 new-phase，或交給 finish-feature 走它自己的兩個 Step Gate，在歸檔那一步做第三個 commit 檢查點之後凍結歷史](media/ai-guided-flow.zh-TW.png)
+
+要直接指定某條 flow、想糾正 AI 選錯的那一條、或想盤點 Dflow 涵蓋哪些情境，
+見[指令參考](docs/commands.md)。
 
 ## 開始使用
 
@@ -40,7 +65,7 @@ dflow init
 
 init 流程會詢問是 greenfield 或 brownfield、團隊採用的 Git policy（GitFlow / Trunk）、AI commit 的標記方式、以及要設定哪些 AI 工具，接著預覽即將建立的檔案。既有檔案不會被覆寫。Init 只建立 workflow 文件與 AI 指示檔，**不會**檢查、重構、或遷移你的應用程式碼。
 
-有選 AI 工具時，init **預設**同時為選定的工具（Claude / Codex / GitHub Copilot）安裝 project-level skill——自然語言自動觸發的來源（你描述「我要加一個功能」，AI 就主動建議對應 workflow；Copilot CLI 需先打 `/dflow` 喚起）。互動模式會問一題 `(Y/n)`，直接按 Enter 就裝；腳本（非互動）模式不多讀任何答案、直接預設安裝，既有的自動化答案序列照跑不用改。skill 檔是 Dflow 衍生物，建議 gitignore、clone 後重新投影（見下方版控建議表）。
+有選 AI 工具時，init **預設**同時為選定的工具（Claude / Codex / GitHub Copilot）安裝 project-level skill——自然語言自動觸發的來源（你描述「我要加一個功能」，AI 就主動建議對應 workflow；Copilot CLI 需先打 `/dflow` 喚起）。互動模式會問一題 `(Y/n)`、直接按 Enter 就裝；腳本（非互動）模式直接預設安裝，既有的自動化答案序列照跑不用改。skill 檔是 Dflow 衍生物，建議 gitignore、clone 後重新投影（見下方版控建議表）。
 
 若專案已初始化、之後又要加入另一個 AI 程式設計工具，執行：
 
@@ -48,13 +73,13 @@ init 流程會詢問是 greenfield 或 brownfield、團隊採用的 Git policy
 dflow configure-agents
 ```
 
-它對「新選、而且還沒有 skill」的工具問同一題預設 Y 的 skill 安裝問句（非互動同樣直接預設裝），之後加工具也不會漏掉自動觸發。要強制重生成所有選定工具的 skill（例如升級 Dflow 後刷新內容），用 `--skills`：
+它對「新選、而且還沒有 skill」的工具問同一題預設 Y 的安裝問句，之後加工具也不會漏掉自動觸發。要強制重生成所有選定工具的 skill（例如升級 Dflow 後刷新內容），用 `--skills`：
 
 ```bash
 dflow configure-agents --skills
 ```
 
-答 `n` 略過 skill 不代表 AI 完全不會建議 workflow——init 產生的專案指示（shim + canonical 指南）本身就要求 AI 對 spec-impacting 的請求建議對應的 `/dflow:*` 指令。差別在可靠度：那條路靠模型當下記得指示，對話一長就可能漏；skill 把觸發交給工具原生的匹配機制（skill 的觸發描述每回合都在模型面前），觸發才穩定。略過之後隨時可用 `dflow configure-agents --skills` 補裝。
+答 `n` 略過後，AI 仍會依 init 產生的專案指示建議對應 workflow，但觸發可靠度較低——skill 把觸發交給工具原生的匹配機制，比靠模型當下記得指示穩定。略過之後隨時可用 `dflow configure-agents --skills` 補裝。
 
 若還想要工具原生的 `/` 命令 / prompt 選單，再加 `--command-adapters`（可與 `--skills` 並用）：
 
@@ -66,32 +91,22 @@ dflow configure-agents --command-adapters --skills
 
 ### 開始使用 Dflow workflow
 
-完成 init 之後，透過 AI 程式設計助理走 Dflow workflow：
+完成 init 之後，直接把要做的事講給 AI 程式設計助理聽：
 
 ```text
-/dflow:new-feature
-/dflow:modify-existing
-/dflow:bug-fix
-/dflow:new-phase
-/dflow:finish-feature
-/dflow:verify
-/dflow:pr-review
+幫我加一個報銷單審核的功能
 ```
 
-`/dflow:*` 是 Dflow 的 canonical 共同詞彙；各 AI 工具的 `/` parser 行為不同。實際輸入方式如下：
+AI 會判斷該走哪一條 workflow 並主動啟動，然後在每個決策點停下來等你確認——流程見上方
+[你不用先學指令](#你不用先學指令)。
 
-| 工具 | 建議叫法 |
-|---|---|
-| Claude Code（安裝 `--command-adapters` 後） | `/dflow:<id>`，例如 `/dflow:new-feature` |
-| GitHub Copilot（VS Code Chat） | 命令入口用 `/dflow-<id>`（連字號，需 `--command-adapters`）；也可自然語言自動觸發。`/dflow:<id>`（冒號）僅當文字稱呼、非命令 |
-| GitHub Copilot CLI | 沒有 per-id 命令；先打 `/dflow` 喚起 skill，再用自然語言描述 workflow |
-| Codex CLI | 不帶斜線的純文字 `dflow:<id>`，例如 `dflow:new-feature` |
-
-若你的工具不支援自訂 slash command，把 workflow 名稱當成普通對話訊息輸入即可。Dflow 是 Markdown-based 的 workflow 材料加一個 scaffolding CLI，能與任何可讀專案指示與 repo 上下文的 AI 程式設計助理一起運作。
+想自己指定某條 flow（例如你已經確定這是一個新 feature），或想知道 Dflow 總共涵蓋哪些
+情境，見[指令參考](docs/commands.md)：11 條 workflow、各 AI 工具的輸入方式、以及 `dflow`
+CLI 的四個指令。
 
 第一次採用建議用 branch 或一次性試用專案，讓團隊先檢視產生的 `dflow/specs/` 工作區，再把流程引入正式程式碼。
 
-完整評估流程（init 產生哪些檔案、AI 工具支援、模式選擇、30 分鐘試用 playbook）見 [評估 Dflow](docs/evaluating-dflow.md)。Greenfield 與 Brownfield 端到端劇情走完與規格範例見 [`tutorial/`](tutorial/README.md) 索引。
+完整評估流程（init 產生哪些檔案、AI 工具支援、模式選擇、30 分鐘試用 playbook）見 [評估 Dflow](docs/evaluating-dflow.md)。Greenfield 與 Brownfield 端到端劇情走完與規格範例見 [`tutorial/`](https://github.com/weilung/dflow-sdd-ddd/blob/main/tutorial/README.md) 索引（在 source repository，不隨 npm 套件安裝）。
 
 ### 把 specs 轉成人類可讀的 HTML
 
@@ -101,15 +116,19 @@ Dflow 的 specs 是給 AI 讀的 Markdown（表格緊湊、標記密集）。要
 dflow render
 ```
 
-它把 `dflow/specs/` 鏡像成一棵靜態 HTML 樹（預設輸出 `dflow-specs-html/`，可用 `--src` / `--out` / `--title` 調整）：記錄型表格逐列轉成卡片、AI 專用註解標記變成 badge / chip、gherkin 區塊關鍵字高亮、樹內 `.md` 連結與檔名提及自動改連對應 HTML 頁。開啟輸出目錄的 `index.html` 即可瀏覽（`file://` 直開、免 server）。
+它把 `dflow/specs/` 鏡像成一棵靜態 HTML 樹（預設輸出 `dflow-specs-html/`，可用 `--src` / `--out` / `--title` 調整）：記錄型表格逐列轉成卡片、AI 專用註解標記變成 badge、gherkin 關鍵字高亮、樹內連結自動改連對應 HTML 頁；`analysis.md` 裡填好的生命週期與流程，另外在卡片上方畫成圖。開啟輸出目錄的 `index.html` 即可瀏覽（`file://` 直開、免 server）：首頁是分組目錄——Features、Domain、架構與遷移、共用文件、其他——各組先收起、點開才展開（只有一組時直接展開），附一句用途說明與「怎麼讀這些文件」；Domain 一個 context 一列，feature 一個目錄一列。塞進單一儲存格的超長敘述會自動改善呈現：該卡片撐滿整列、特別長的欄位先摺疊、點「展開全文」再看（純 CSS、列印一律全展開）。`features/completed/` 封存區不會攤平在首頁——首頁只放年度連結、一年一頁，封存再多年首頁也不會變長。`--src` 指到的不是 Dflow 的 specs 根目錄（沒有 `shared/_conventions.md`）時，首頁是照路徑排列的目錄樹。
 
 同一份 spec 的兩種讀法——左：AI 讀的 Markdown 源（密集表格 + `<!-- phase-2 ADDED -->` 這類 AI 專用標記）；右：`dflow render` 產出的 HTML（逐列變卡片、標記變 badge）：
 
 ![同一份 models.md：左為 AI 讀的 Markdown 源，右為 dflow render 產生的 HTML 頁面](media/render-side-by-side.png)
 
-範例取自本 repo 的 Expense 教學規格（[`tutorial/01-greenfield/outputs`](tutorial/01-greenfield/outputs/)），clone、`npm install` 後可用 `node bin/dflow.js render --src tutorial/01-greenfield/outputs/dflow/specs` 自行重現。
+`analysis.md` 的生命週期也是同樣的兩種讀法——左：狀態表與轉移表；右：render 在卡片上方畫出的圖（`Rejected` 繞回 `Draft` 的重編迴圈、`Approved` 是終點，一眼就看得出來）：
+
+![同一個生命週期 LC-01：左為 analysis.md 的狀態表與轉移表，右為 dflow render 畫出的狀態圖](media/render-lifecycle-diagram.png)
+
+兩張範例都取自本 repo 的 Expense 教學規格（[`tutorial/01-greenfield/outputs`](https://github.com/weilung/dflow-sdd-ddd/tree/main/tutorial/01-greenfield/outputs)），clone、`npm install` 後可用 `node bin/dflow.js render --src tutorial/01-greenfield/outputs/dflow/specs` 自行重現。
 
-分工模型：**Markdown 是 AI 閱讀的 source of truth；HTML 是人類閱讀投影**。specs 一變就重跑一次 `dflow render` 即刷新（每次執行都是全量重建）。輸出目錄由 render 管理——以 `.dflow-render-manifest.json` 記帳，來源刪除 / 改名後重跑會清掉對應的舊 HTML，非 render 產生的檔案永不會被動到——屬可重生成的衍生物，建議加進 `.gitignore`：
+分工模型：**Markdown 是 AI 閱讀的 source of truth；HTML 是人類閱讀投影**。specs 一變就重跑一次 `dflow render` 即刷新（每次執行都是全量重建）。輸出目錄由 render 管理、**非 render 產生的檔案永不會被動到**——屬可重生成的衍生物，建議加進 `.gitignore`：
 
 ```gitignore
 dflow-specs-html/
@@ -140,8 +159,8 @@ Dflow 採用混合設計，user 跟 AI 互動有三個層面：
 
 | 層 | 用途 |
 |---|---|
-| **命令進入** | 開發者主動以 `/dflow:new-feature`、`/dflow:modify-existing` 等命令開始工作。 |
-| **自動偵測安全網** | 當對話明顯指向某個 feature、phase、bug fix、verification、review 時，AI 應主動建議對應的 Dflow flow。 |
+| **自然語言進入（預設）** | 你描述要做的事，AI 判斷這指向哪個 feature、phase、bug fix、verification 或 review，並主動啟動對應的 flow。多數時候這就是全部。 |
+| **命令進入（想自己指定時）** | 已經知道要走哪一條，就直接下 `/dflow:new-feature`、`/dflow:modify-existing` 等命令。名稱與各工具的輸入方式見[指令參考](docs/commands.md)。 |
 | **透明的決策檢查點** | AI 在工作的關鍵節點（flow 進入、Step Gate、重要內部步驟）會停下來告知並等開發者確認方向，避免一路自動跑下去。 |
 
 ### Workflow 內部結構
@@ -159,13 +178,18 @@ Dflow 依改動深淺自動決定規格、實作計畫與驗證的量級（T1 /
 
 | Tier | 典型用途 | 預期份量 |
 |---|---|---|
-| **T1 Heavy** | 新 feature、新 phase、新 Aggregate / Bounded Context、架構變更、新業務規則 | 完整 phase-spec、領域建模、行為例子、實作計畫、驗證與收尾檢查 |
-| **T2 Light** | Bug fix（邏輯錯誤）、UI 驗證調整、有 BR（business rule）delta 的小幅修改 | Lightweight spec、聚焦驗證、確認修復落在正確架構層 |
-| **T3 Trivial** | 按鈕顏色、文案 typo、純 formatting — **不動業務規則、不動 Domain 概念、不動資料結構** | `_index.md` 一行紀錄，不另開 spec 檔 |
+| **T1 Heavy** | 新 feature、新 phase、新 Aggregate / Bounded Context、架構變更、新業務規則、資料結構變更（table／欄位／關聯／索引），以及會讓呼叫端壞掉的契約變更（API／event，或必填的環境變數／CLI 參數／exit code） | 完整 phase-spec、領域建模、行為例子、實作計畫、驗證與收尾檢查 |
+| **T2 Light** | Bug fix（邏輯錯誤）、UI 驗證調整、有 BR（business rule）delta 的小幅修改、不破壞呼叫端的契約調整、純效能調整 | Lightweight spec、聚焦驗證、確認修復落在正確架構層 |
+| **T3 Trivial** | 局部、語意保持的顯示文案／外觀小修（按鈕顏色、文案 typo／措辭、版面 polish）— **不動業務規則、Domain 概念、資料結構**，也非高後果內容。「局部」指**單一畫面／元件上的元素層級，或單一獨立閱讀的頁面／檔案**（例如公開 README、公開 API reference 頁）：整頁改版、或同一處掃過多個畫面，都升 T2，跨頁的掃改同理 | 掛在所屬 feature：其 `_index.md` 一行紀錄，不另開 spec 檔。沒有所屬 feature 時，`/dflow:modify-existing` 會開一個 minimal（zero-phase）host，把該行記在那裡 |
+
+> 這張表是**摘要**，方便你快速理解量級差異。實際判定的唯一依據是
+> `AI-AGENT-GUIDE.md` § Ceremony Scaling 的 ordered cascade（步驟 0–4，先命中者
+> 勝）——邊界情況（新功能 vs 既有功能修改、什麼真的不用進 Dflow、T3 能涵蓋多大範
+> 圍、契約軸怎麼判）都在那裡定案。
 
 tier 不是每次都 user 決定 — `/dflow:new-feature` 與 `/dflow:new-phase` 預設一律 T1，`/dflow:modify-existing` 與 `/dflow:bug-fix` 才由 AI 依改動內容判 T1/T2/T3。
 
-**不是每個變更都走 Dflow**：純 typo、純 formatting commit（例如 `prettier` / `dotnet format` 自動跑）連 T3 inline 紀錄都不需要，直接 `git commit` 即可。Dflow 是給有業務語意或結構變動的修改用的。
+**不是每個變更都走 Dflow**：純 formatting commit（例如 `prettier` / `dotnet format` 自動跑）、內部註解、內部文件的 typo 連 T3 inline 紀錄都不需要，直接 `git commit` 即可（使用者看得到的 typo 依 cascade 判：單一畫面、或單一獨立閱讀頁面上的顯示文案是 T3，掃過多個畫面／頁面或高後果內容升 T2）。反過來，**人眼看不到不代表不用追蹤**：machine-consumed contract（structured log／匯出欄位／API／event）、security／CVE 與 compliance 工作、以及 runtime 效能／資源／SLA 變更都仍在 Dflow 內。
 
 透明的決策檢查點與 Tier 制有關但獨立：檢查點控制 AI 如何溝通 workflow；Tier 控制變更需要多少規格、實作計畫與驗證。
 
@@ -177,7 +201,7 @@ tier 不是每次都 user 決定 — `/dflow:new-feature` 與 `/dflow:new-phase`
 |---|---|---|---|
 | **Phase Delta** | `phase-spec-{date}-{slug}.md`（或 lightweight spec） | 紀錄此次循環改了什麼、為什麼、怎麼實作與驗證 | feature branch 內的一次 milestone 區間 |
 | **Feature Snapshot** | `_index.md`（每個 feature 目錄內） | feature 級 dashboard：phase 列表、cumulative BR Snapshot、Resume Pointer | feature branch 自己的「目前進度」 |
-| **System State** | `rules.md` / `behavior.md` / `glossary.md` / `context-map.md` | 跨 feature 的長期知識：術語、業務規則、模型、慣例、技術債 | main / trunk 累積下來的「系統現在實際是什麼」 |
+| **System State** | `rules.md` / `behavior.md` / `glossary.md` / `context-map.md` / `analysis.md` | 跨 feature 的長期知識：術語、業務規則、模型、流程與生命週期、慣例、技術債 | main / trunk 累積下來的「系統現在實際是什麼」 |
 
 `_index.md` 是關鍵的中間層。很多 spec 工具只有 phase + system 兩層，但 feature branch 跨多次 phase 是常態，少了中間層就會遇到三個痛點：
 
@@ -187,6 +211,12 @@ tier 不是每次都 user 決定 — `/dflow:new-feature` 與 `/dflow:new-phase`
 
 Dflow 用 `_index.md` 解決這三點：Current BR Snapshot 每完成一個 phase 就 regenerate、Resume Pointer 寫接續指引、整個 feature 目錄是自然的歸檔單位。`/dflow:finish-feature` 收尾時，把 `_index.md` 的 BR Snapshot reconcile 到 `rules.md` / `behavior.md`（feature 層晉升到 system 層），然後 `git mv` 整個 feature 目錄到 `completed/`。
 
+### completed feature 是凍結歷史
+
+當 `/dflow:finish-feature` 把 feature 目錄 `git mv` 到 `completed/` 後，**該 feature 不接受任何直接寫入**，無論是新 phase-spec、lightweight-spec、還是 `_index.md` inline 一行（唯一 sanctioned 例外：Follow-up Tracking 段的 derived metadata——有 follow-up feature 連回時，其 reverse-link 列由 `in-progress` 翻 `completed`；specs、BR Snapshot、inline change history 仍凍結）。如果之後要再改它，必須建一個 follow-up feature：新 feature 目錄、新 SPEC-ID、`_index.md` 用 `follow-up-of: {原 SPEC-ID}` metadata 連回原 feature。
+
+理由：「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）。
+
 ## Init 產生的檔案
 
 典型初始化專案會建立 `dflow/` workspace：
@@ -208,6 +238,8 @@ dflow/
         └── completed/
 ```
 
+`analysis.md` 不在 init 產生之列：跨 context 的記在 `domain/analysis.md`、單一 context 擁有的記在 `domain/{context}/analysis.md`，都是第一次有東西要記時才從範本建立。
+
 Dflow 也會為你的 AI 程式設計助理建立或更新專案指示檔；確切檔名取決於目標工具與既有專案設定。Dflow 不覆寫既有專案指示中的自訂內容。
 
 選擇 AI agent 設定時，Dflow 把 `dflow/specs/shared/AI-AGENT-GUIDE.md` 作為 canonical 專案指南，並為每個 AI 工具建立**小型的指向檔**（俗稱 shim，內容很短，只是把該工具引導去讀 canonical 指南）：
@@ -218,15 +250,9 @@ Dflow 也會為你的 AI 程式設計助理建立或更新專案指示檔；確
 | Claude Code | `CLAUDE.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
-若這些檔案已存在，Dflow 不會覆蓋自訂內容；已是 Dflow-generated shim 的檔案
-會原地刷新，其他已指向 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過。
-若檔案尚未指向 guide，預設會在確認 preview 顯示並於檔案末尾附加帶有
-`<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block，重跑會
-原地更新同一段且不重複。只有檔案內有衝突或 malformed Dflow markers 時，
-才會改寫 fallback merge snippet 到 `dflow/specs/shared/`。專案指南保持單一
-source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。
+若這些檔案已存在，Dflow 不會改寫你的自訂內容。尚未指向 canonical 指南的既有檔案，會在你確認整體 preview 後於檔尾附加一段帶 `<!-- dflow-generated: agent-shim START/END -->` markers 的管理區塊（重跑會原地更新同一段、不重複）；**已自行指向指南的自寫檔，init 不動它、僅提示**——之後互動執行 `dflow configure-agents` 時才會徵詢是否加掛 marker 區塊（預設不加），非互動一律略過並警告。完整的檔案狀態對照（pristine shim、各類 marker 損壞的處理等）見[升級指南](docs/upgrading.md)。專案指南保持單一 source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。
 
-之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim——它會對新選且尚無 skill 的工具問預設 Y 的安裝問句（非互動直接預設裝），自動觸發不會漏；若需要 Claude / Copilot 的工具原生命令入口，改用 `dflow configure-agents --command-adapters`；要強制重生成所有選定工具的 skill（例如升級 Dflow 後刷新），用 `dflow configure-agents --skills`。
+之後團隊採用新 AI 程式設計助理時，隨時跑 `dflow configure-agents` 新增 shim 即可；skill 與工具原生命令入口的加裝方式見上方[開始使用](#開始使用)。
 
 ### 產生物的版控政策（建議預設）
 
@@ -241,9 +267,7 @@ source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow
 
 這是**建議**，不是唯一正解。若團隊希望 clone 後立即有原生 `/` 選單、或 CI / 開發環境不裝 npm，**版控 adapter** 也是合理選擇——代價是升級若改了命名，要重投影並 commit 刪除舊檔。關鍵原則：**同一專案對所有工具採一致策略**，別像常見的踩雷一樣一邊 ignore、一邊版控。
 
-升級 dflow 後重跑 `dflow configure-agents --command-adapters`，adapter 會用**新版的 command registry** 重投影；但**不會**覆寫已存在的 `dflow/specs/shared/AI-AGENT-GUIDE.md`（canonical guide 已存在則保留）。「重投影 adapter」與「升級 canonical guide」是兩件事；升級時請用**相同的 dflow CLI 版本**重投影，避免 registry 與 guide 版本錯位。各工具的 `.gitignore` 片段、glob 副作用、`git rm --cached` 切換步驟與升級細節見 per-tool 指南。
-
-**升級既有專案的 caveat**：`configure-agents` 只重投影 Dflow 自己擁有的自動層（workflow bundle、command / skill adapters，以及既有 agent 檔內帶 marker 的區塊）。它**不會**刷新 canonical 指南（`AI-AGENT-GUIDE.md`）與其他 user-owned 層（如 `_conventions.md`、shim marker 以外的文字）——這些檔在 init 後即歸專案所有、刻意不被覆寫。代價是：當新版把內容加進 canonical 指南時，既有專案不會自動拿到，可能與該版的 canonical 形狀 silent drift。升級既有專案後，建議手動 reconcile，並以「在別處跑一個**同 edition、同答案的全新 `dflow init`**、再與你的專案逐檔 diff」當驗證基準：每個差異都應能歸類為「你的 user content」或「已知 marker 以外」，否則就是漏修。
+**升級既有專案**：`configure-agents` 只重投影 Dflow 自己擁有的自動層——workflow bundle 與各檔案中帶 marker 的區塊（command adapters 與既有 skill 需分別加 `--command-adapters` / `--skills` 才重生成）；你自己撰寫的內容不會被自動遷移。升級後先跑 `dflow doctor`——它以唯讀方式回報漂移（版本落後、參照斷裂、格式漂移），是第一道檢查；要更徹底的驗證，用「在別處跑同 edition、同答案的全新 `dflow init`、再與你的專案逐檔 diff」當基準。完整說明（各檔案的 ownership 與 flag 對照表、狀態矩陣、逐步驗證）見[升級指南](docs/upgrading.md)。
 
 特定工具的 init 寫入內容與 Dflow workflow 命令呈現方式，見 `docs/` 內的 per-tool 指南：
 
@@ -251,88 +275,15 @@ source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow
 - [在 Codex CLI 中使用 Dflow](docs/using-with-codex.md)
 - [在 GitHub Copilot 中使用 Dflow](docs/using-with-github-copilot.md)
 
-Init 不會把 `tutorial/` 目錄複製進你的專案。[`tutorial/`](tutorial/README.md) 目錄存放在本 source repository，作為理解 Dflow 如何在 Greenfield / Brownfield 劇情中運作的評估材料。
-
-## 主要 Flow
-
-Dflow 指令依角色分四類。「我要做的事」對應到指令的速查表附在最後。
-
-### 入口指令（從這裡開始一個 workflow）
-
-啟動一次 workflow run；可在沒有任何既有 feature 的狀態下使用。三者彼此獨立、不互為前置。
-
-| Flow | 何時用 | 典型產出 |
-|---|---|---|
-| `/dflow:new-feature` | 完全新功能、新增一條系統要實現的業務規則 | feature 目錄 + `_index.md` + 第 1 份 phase-spec（一律 T1） |
-| `/dflow:modify-existing` | 改既有行為 — **不確定改動屬於哪類**時用，AI 內部會分流 | T1 → 升 new-phase / new-feature；T2 → lightweight-spec；T3 → `_index.md` inline 一行 |
-| `/dflow:bug-fix` | 可清楚陳述預期行為的 defect | AI 判 tier（多為 T2 lightweight-spec）。Orphan bug 會自建最小 feature 目錄 |
-
-### Feature 內指令（限 active feature）
-
-只在已啟動的 active feature 內可用。指向 `completed/` 的 feature 會被拒絕。
-
-| Flow | 何時用 | 典型產出 |
-|---|---|---|
-| `/dflow:new-phase` | active feature 需要再一個實作切片 | 新一份 `phase-spec-{date}-{slug}.md` + Implementation Tasks + 程式實作 / 驗證 + phase 標記完成（一律 T1） |
-| `/dflow:finish-feature` | feature 全部 phase 完成、要收尾 | `git mv` 整個 feature dir 到 `completed/`、sync BR Snapshot 到 BC 層、Integration Summary（不 auto-merge） |
-
-### 流程控制（管理進行中的 workflow run）
-
-| Flow | 何時用 |
-|---|---|
-| `/dflow:status` | 看現在在哪個 workflow / Step / 進度 |
-| `/dflow:next` | 確認過 Step Gate（等同自然語言「OK」/「繼續」） |
-| `/dflow:cancel` | 放棄目前 workflow run、回到自由對話。已建立的 artifacts 保留 |
-
-### 獨立工具（任何時候可呼叫，不綁定 feature 或 workflow）
-
-| Flow | 何時用 | 典型產出 |
-|---|---|---|
-| `/dflow:verify` | 需要確認文件、程式、測試、債務紀錄是否一致 | 跨規格、領域文件、實作、測試、債務的 drift report |
-| `/dflow:pr-review` | 變更已準備接受審查 | SDD/DDD 合規 review 清單，含風險、缺口、後續項目 |
-| `/dflow:report-dflow-feedback` | 你或 AI 在使用中發現 Dflow 本身的問題 | sanitized 的本地草稿，逐欄對齊上游 issue 表單可直接貼上；不自動送出 |
-
-### 該選哪個指令（rule of thumb）
-
-| 我要做的事 | 直接下指令 |
-|---|---|
-| 完全新功能（與現有 feature 無關） | `/dflow:new-feature` |
-| 為 active feature 加規劃中的下一個 phase | `/dflow:new-phase` |
-| 修一個明確的 bug | `/dflow:bug-fix` |
-| **不確定**怎麼分類、反正是改既有的 | `/dflow:modify-existing` |
-| feature 全部 phase 都完成、要收尾 | `/dflow:finish-feature` |
-| 跑變更 review | `/dflow:pr-review` |
-| 檢查文件與程式碼 drift | `/dflow:verify` |
-
-### completed feature 是凍結歷史
-
-當 `/dflow:finish-feature` 把 feature 目錄 `git mv` 到 `completed/` 後，**該 feature 不接受任何直接寫入**，無論是新 phase-spec、lightweight-spec、還是 `_index.md` inline 一行。如果之後要再改它，必須建一個 follow-up feature：新 feature 目錄、新 SPEC-ID、`_index.md` 用 `follow-up-of: {原 SPEC-ID}` metadata 連回原 feature。
-
-理由：「completed = 凍結歷史」是 Dflow 的核心保證；若接受 post-completion 修改，feature lifecycle 就失去明確終點、`_index.md` BR Snapshot 也無法可信。`/dflow:modify-existing` 偵測到目標是 completed feature 時會主動詢問 user 三個選項：A 走 follow-up、B 改用 `/dflow:new-feature` 當獨立新需求、C（被拒絕，重新引導至 A）。
+Init 不會把 `tutorial/` 目錄複製進你的專案，npm 套件裡也沒有它。[`tutorial/`](https://github.com/weilung/dflow-sdd-ddd/blob/main/tutorial/README.md) 目錄存放在 source repository，作為理解 Dflow 如何在 Greenfield / Brownfield 劇情中運作的評估材料。
 
 ## 為什麼 DDD 在 AI 時代更重要
 
-AI 助理擅長把缺少的細節補起來。如果缺少的是「靠規則或慣例就能推出來」的東西（例如命名、樣板語法），這是優點；但如果缺少的是**業務語意**（什麼樣的折扣才算有效、帳號不能做什麼），模型可能會發明一個看起來合理、實際錯誤的規則，而且這種錯誤在 review 時很難一眼察覺。
-
-Dflow 把 DDD 當成規格背後的語意結構：ubiquitous language 讓命名一致、bounded context 防止語意跨領域漏氣、領域規則在實作開始之前先定義什麼是正確、允許、禁止。
-
-在 code-first workflow 裡，設計常常在類別、handler、測試完成後才浮現。在 AI-assisted workflow 裡，規格必須成為產生程式碼的前置條件。實務流程變成：
-
-```text
-領域意義 → 結構化規格 → AI 實作 → 程式碼即產出
-```
-
-更詳細的說明見 [為什麼 AI 時代 DDD 更重要](docs/why-ddd-for-ai.md)。
+AI 助理擅長把缺少的細節補起來。缺的是「靠規則或慣例就能推出來」的東西（例如命名、樣板語法）時，這是優點；缺的是**業務語意**（什麼樣的折扣才算有效、帳號不能做什麼）時，模型可能發明一個看起來合理、實際錯誤的規則——而且這種錯誤 review 時很難一眼察覺。Dflow 把 DDD 當成規格背後的語意結構：ubiquitous language 讓命名一致、bounded context 防止語意跨領域漏氣、領域規則在實作開始之前先定義什麼是正確、允許、禁止。完整論述見[為什麼 AI 時代 DDD 更重要](docs/why-ddd-for-ai.md)。
 
 ## 為什麼用 Dflow（即使 AI 已經會 DDD）
 
-常見的質疑是：「現在的 AI 已經懂 DDD，叫它『用 DDD 建一個 feature』它就會做，再加一層 process 是過度工程。」這句話對了一半——AI 確實能說出對的 DDD 答案。但「能說出對的答案」和「在 review 時看得到它怎麼想、查得出它有沒有漏」是兩回事。所以該比的不是「AI 工具 vs process」，而是 **AI alone vs AI + scaffold**：差別不是更聰明的 AI，是**更可審查的 AI**。
-
-而且 Dflow 的引導是從真實盲區回灌的、補上後模型真的會沿用。一個實例：模型自己建模時，把「同時只能有一筆 active」這類唯一性規則只用 aggregate 內的 in-memory check 保護——教科書上對、但並發下兩個請求會各自通過檢查、破壞不變式（modeling-correct、production-broken）；把這個盲區寫成一段引導補進 Dflow 後，換一個 domain 重跑，同一個模型就主動引用它、補上 DB 層保護（unique index + concurrency token + 409）。Dflow 的價值就在這：把「AI 自己會漏的盲區」固化成可重用、會被遵循的引導。
-
-對需要 audit 的領域（醫療、金融、合規、任何「上線出包代價高」的場景），這個差異是 deal-breaker。成本要分兩塊看：**產出** DDD 文件已經不是徒手做 DDD 的年代——AI 幫你生規格、決策紀錄與領域模型，邊際成本主要是多花一些 token 與走一遍流程；而且光是「生成時被領域模型約束」就已讓產出更穩（如前面那個並發盲區），這部分就算你沒深讀紀錄也拿得到。但要再兌現「可審查」這份價值，得有人實際去 review 那份紀錄——那才是人力與紀律的成本。所以取捨仍在：高風險、需 audit、要長期維護時，這筆投資明顯划算；你不會去 review、失敗成本低、迭代又快時，AI alone 仍可能更實際。
-
-完整的迴路（盲區怎麼變成引導、為什麼這歸到引導內容而非 domain / framing 的差異）、其他幾個「Dflow 強制留檔、AI 自己容易漏」的觀察，以及自己動手驗證的步驟，見 [為什麼用 Dflow](docs/why-dflow.md)。
+常見的質疑是：「現在的 AI 已經懂 DDD，再加一層 process 是過度工程。」這句話對了一半——AI 確實能說出對的 DDD 答案，但「能說出對的答案」和「review 時看得到它怎麼想、查得出它有沒有漏」是兩回事；該比的不是「AI 工具 vs process」，而是 **AI alone vs AI + scaffold**——差別不是更聰明的 AI，是**更可審查的 AI**。一個我們觀察到的實例（第一方觀察、樣本小）：模型自己建模時，把「同時只能有一筆 active」的唯一性規則只用 in-memory check 保護——教科書上對、並發下會破功；把這個盲區寫成引導收進 Dflow 後換一個 domain 重測，該次模型主動引用了那段引導、補上 DB 層保護。引導也不只往「多做」推：Dflow 在多個常見的過衝位置寫了反向判準——哪裡不值得深度建模、何時停在最簡階梯、何時該質疑既有模型——防盲區與防過度設計是同一套引導的兩面。完整的迴路說明、成本取捨、限制與自行驗證步驟，見[為什麼用 Dflow](docs/why-dflow.md)。
 
 ## Repo 結構
 
@@ -340,10 +291,9 @@ Dflow 把 DDD 當成規格背後的語意結構：ubiquitous language 讓命名
 |---|---|
 | `bin/` | CLI 進入點 |
 | `lib/` | CLI runtime 實作（init / configure-agents / doctor / render） |
-| `templates/` | init 指令複製的檔案 |
+| `templates/` | workflow 內容唯一來源；`dflow init` / `dflow configure-agents` 由此投影到你的專案 |
 | `test/` | 產出物的 smoke test |
 | `tutorial/` | 引導式學習劇情與預期產出 |
-| `sdd-ddd-*-skill/` | AI 程式設計助理消化的 workflow 來源材料 |
 
 ## 貢獻與發布
 
@@ -351,20 +301,15 @@ issue 與 pull request 指引見 [CONTRIBUTING.md](CONTRIBUTING.md)。Pull reque
 
 ## 狀態
 
-Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.13.0`，涵蓋：
-
-- 專案初始化（`dflow init`）與 idempotent 升級重投影（`dflow configure-agents`）
-- Workflow 文件（`/dflow:*` 流程）＋隨專案 vendored 的 workflow bundle
-- 多 AI agent 設定：canonical 指南 + 各工具薄 shim（CLAUDE.md / AGENTS.md / Copilot instructions）；既有 agent 檔以帶 marker 的區塊自動注入、零手動合併
-- 三家原生 project-level skill（Claude / Codex / GitHub Copilot），**init 預設安裝**（0.13）、共用 agentskills.io 開放標準、支援自然語言自動觸發（Copilot CLI 仍需先打 `/dflow` 喚起）
-- 選配工具原生命令入口（`--command-adapters`）；`--skills` 補裝 / 強制重生成 skill
-- `dflow render`：specs Markdown → 可瀏覽的靜態 HTML 鏡像（給人讀；`file://` 直開、免 server；0.13）
-- AI agent 可讀的 SDD/DDD 指引，含深化的 DDD 戰術建模指引與模型生命週期閉環（長時流程與模型重審；0.11–0.12）
-- `dflow doctor` 唯讀專案健康檢查
-- 公開 onboarding：evaluator 指南，Claude Code / Codex CLI / GitHub Copilot 的 per-tool walkthrough
+Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.15.0`，提供：
+
+- 專案 scaffolding 與升級：`dflow init`（初始化）、`dflow configure-agents`（idempotent 升級重投影）、`dflow doctor`（唯讀健康檢查與漂移偵測）、`dflow render`（specs → 人類可讀 HTML）
+- 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）
 
-GitHub 上的 source 可能包含 `0.13.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
+GitHub 上的 source 可能包含 `0.15.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 授權
 

package/TEMPLATE-COVERAGE.md

@@ -6,6 +6,8 @@ This file is a maintenance contract for Dflow, not the runtime brain. `SKILL.md`
 
 The matrix lists Brownfield / Greenfield logical template parity so reviewers can check which templates should remain aligned and which differences are intentional.
 
+**Shape markers (PROPOSAL-092).** Every template an adopter doc is created from — each track's `templates/*.md` and `scaffolding/_overview.md` — carries one `<!-- dflow-shape: {track}/{template} {number} — keep this line: dflow doctor reads it -->` line: the first line, or the line after the frontmatter. The number is that template's shape, and `lib/doc-shapes.json` records what each number looks like (`##` / `###` headings and their order, table header rows, frontmatter fields, and — as digests — the `>` notes and HTML comments of each section), what changed from the number before, and where flows create the doc. **Changing a template's shape means a new number** — a heading, a header row, a frontmatter field, a note, a comment or the order of the sections (re-wrapping a note or comment is not a change); bump the marker and register it. `test/doc-shapes.mjs` fails until you do, and prints the skeleton and digest to register. It also fails when the shape and `dflow render` read a template differently — a table, a `>` note or a comment render shows that the shape does not record — so such content has to take a form the shape reads; and two sibling sections may not share a name, because the shape keys sections by name. Rows below that say "byte-identical" compare the templates without that line.
+
 ## Matrix
 
 | Logical document | Generated / maintained path | Brownfield template | Greenfield template | Parity requirement | Allowed differences | Section anchors |
@@ -13,14 +15,15 @@ The matrix lists Brownfield / Greenfield logical template parity so reviewers ca
 | Feature dashboard | `dflow/specs/features/{active\|completed}/{SPEC-ID}-{slug}/_index.md` | `templates/_index.md` | `templates/_index.md` | Required sections same | Greenfield may mention Aggregate / Domain Events | `current-br-snapshot`, `lightweight-changes` |
 | Phase spec | `dflow/specs/features/active/{SPEC-ID}-{slug}/phase-spec-YYYY-MM-DD-{slug}.md` | `templates/phase-spec.md` | `templates/phase-spec.md` | Lifecycle sections same | Greenfield has layer-by-layer plan + Domain Events | `implementation-tasks`, `behavior-scenarios`, `open-questions` |
 | Lightweight spec | `dflow/specs/features/active/{SPEC-ID}-{slug}/lightweight-YYYY-MM-DD-{slug}.md` or `BUG-{NUMBER}-{slug}.md` | `templates/lightweight-spec.md` | `templates/lightweight-spec.md` | T2 structure and task checklist intent same | Layer tags differ | `implementation-tasks` |
-| Glossary | `dflow/specs/domain/glossary.md` | `templates/glossary.md` | `templates/glossary.md` | Same columns | none | - |
-| Bounded Context definition | `dflow/specs/domain/{context}/context-definition.md` | `templates/context-definition.md` | `templates/context-definition.md` | Same purpose / structural sections | Greenfield may reference Aggregate / Domain Service / Repository Interface | - |
+| Glossary | `dflow/specs/domain/glossary.md` | `templates/glossary.md` | `templates/glossary.md` | Byte-identical apart from the shape marker line | the shape marker line (it names its own track) | - |
+| Bounded Context definition | `dflow/specs/domain/{context}/context.md` | `templates/context-definition.md` | `templates/context-definition.md` | Same purpose / structural sections | Greenfield may reference Aggregate / Domain Service / Repository Interface | - |
 | Rules index | `dflow/specs/domain/{context}/rules.md` | `templates/rules.md` | `templates/rules.md` | BR-ID / anchor / status format same | Greenfield may include Aggregate column | `business-rules` |
 | Models catalog | `dflow/specs/domain/{context}/models.md` | `templates/models.md` | `templates/models.md` | Same purpose | Greenfield has Aggregate / Specification depth | - |
-| Aggregate worksheet | `dflow/specs/domain/{context}/aggregates/{name}.md` (per Aggregate, on demand) | n/a | `templates/aggregate-design.md` | Greenfield only | Brownfield does not use the Aggregate worksheet | - |
+| Aggregate worksheet | `dflow/specs/features/active/{SPEC-ID}-{slug}/aggregate-design.md` (in the feature directory that introduces the Aggregate, on demand) | n/a | `templates/aggregate-design.md` | Greenfield only | Brownfield does not use the Aggregate worksheet | - |
 | Behavior snapshot | `dflow/specs/domain/{context}/behavior.md` | `templates/behavior.md` | `templates/behavior.md` | BR anchor and drift-verification structure same | Greenfield may reference Domain Events | `behavior-scenarios` |
 | Events catalog | `dflow/specs/domain/{context}/events.md` | n/a | `templates/events.md` | Greenfield only | Brownfield does not require event catalog | - |
 | Context map | `dflow/specs/domain/context-map.md` | `templates/context-map.md` optional | `templates/context-map.md` mandatory | Similar concept | Brownfield optional / emergent | - |
+| Domain analysis | `dflow/specs/domain/analysis.md` and `dflow/specs/domain/{context}/analysis.md` (both created on demand, the first time a session records system-level knowledge that belongs there) | `templates/analysis.md` | `templates/analysis.md` | Byte-identical apart from the shape marker line | the shape marker line (it names its own track) | - |
 | Tech debt | Brownfield: `dflow/specs/migration/tech-debt.md`; Greenfield: `dflow/specs/architecture/tech-debt.md` | `templates/tech-debt.md` | `templates/tech-debt.md` | Same backlog intent | Brownfield migration focus; Greenfield architecture focus | - |
 | ADR guide | `dflow/specs/architecture/decisions/README.md` | n/a | `scaffolding/architecture-decisions-README.md` | Greenfield only | Brownfield not applicable | - |
 | Project AI guide | `dflow/specs/shared/AI-AGENT-GUIDE.md` when at least one AI agent is selected during init | `scaffolding/AI-AGENT-GUIDE.md` | `scaffolding/AI-AGENT-GUIDE.md` | Same canonical tool-neutral workflow guide and source-of-truth pointers | Track-specific seeded values and available source-of-truth paths may differ | - |
@@ -29,11 +32,15 @@ The matrix lists Brownfield / Greenfield logical template parity so reviewers ca
 
 ## Reference Flow Parity
 
-Common reference flows under `sdd-ddd-brownfield-skill/references/` and
-`sdd-ddd-greenfield-skill/references/` must stay synchronized unless a
-track-specific difference is explicit. This includes
-`dflow-feedback-flow.md`; it is a governance/support flow and should not grow
-GitHub CLI submission behavior without a separate proposal.
+Common reference flows under `templates/brownfield/references/` and
+`templates/greenfield/references/` must stay synchronized unless a
+track-specific difference is explicit.
+
+Anything under `templates/common/references/` is outside that pairing: it is
+single-sourced there and projected into both editions, so there is no pair to
+keep synchronized. `dflow-feedback-flow.md` is one of them, and it remains a
+governance/support flow that should not grow GitHub CLI submission behavior
+without a separate proposal.
 
 ## Section Anchors
 

package/TEMPLATE-LANGUAGE-GLOSSARY.md

@@ -40,7 +40,17 @@ The "使用位置" column refers to file paths where the term appears structural
 | Lightweight Change | 輕量修改 | `_index.md`, `lightweight-spec.md`, Git principles | T2 / small change 類型的固定術語 |
 | Lightweight Changes | 輕量修改紀錄 | `_index.md` | `_index.md` 中登記 T2 外連 + T3 inline 的 section heading |
 | Resume Pointer | 接續入口 | `_index.md` | `_index.md` 末段「目前進展 + 下一動作」的 section heading |
-| Behavior Delta | 行為變更 | `lightweight-spec.md` | lightweight-spec 中 BR delta 段的 section heading |
+| Behavior Delta | 行為變更 | `lightweight-spec.md` | lightweight-spec 中 BR delta 段的 section heading；no-BR 家族改在本段放單行 BR 宣告（`BR: none — {family}`，家族 (e) 為 `BR Delta:` + `Governing BR-IDs:` 兩行）而非 ADDED / MODIFIED / REMOVED / RENAMED 子段 |
+| Output Footprint | 輸出足跡 | `lightweight-spec.md` | no-BR 家族 (a) presentation 取代 Root Cause 的證據段：這次變更實際觸及哪些畫面 / 輸出（含高後果內容改成什麼） |
+| Contract Delta | 契約變更 | `lightweight-spec.md` | no-BR 家族 (b) machine-consumed contract 的證據段 |
+| Downstream consumers | 下游消費者 | `lightweight-spec.md` | Contract Delta 段內指出誰在讀這個 contract 的 inline bold label |
+| Operational Rationale | 操作面理由 | `lightweight-spec.md` | no-BR 家族 (c) operational / security 的證據段（security / compliance 理由） |
+| Trace | 追溯紀錄 | `lightweight-spec.md` | Operational Rationale 段內的 inline bold label（advisory / ticket / audit 出處） |
+| Performance Delta | 效能變更 | `lightweight-spec.md` | no-BR 家族 (d) performance 的證據段 |
+| SLA / resource context | SLA / 資源脈絡 | `lightweight-spec.md` | Performance Delta 段內說明 SLA 與資源影響的 inline bold label |
+| Governing BR-IDs | 治理中的 BR-ID | `lightweight-spec.md` | no-BR 家族 (e) implementation defect 專用欄：這個缺陷歸哪幾條既有規則管（真的無對應規則時記 `none`）；與 `BR Delta:` 分開兩欄，「沒有 BR delta」不等於「沒有治理規則」 |
+| Change Rationale | 變更理由 | `lightweight-spec.md` | no-BR 家族 (f) intentional change 的證據段（含 `Before` / `After` 行為描述） |
+| Regression | 迴歸驗證 | `lightweight-spec.md` | Change Rationale 段內說明如何防迴歸的 inline bold label |
 | Current Progress | 目前進展 | `_index.md` | Resume Pointer 段內描述當下狀態的 inline bold label（per F-04 / DD-A Path A）|
 | Next Action | 下一個動作 | `_index.md` | Resume Pointer 段內描述下一動作的 inline bold label（per F-04 / DD-A Path A）|
 | Before | 原本 | `lightweight-spec.md`, `phase-spec.md`, `references/modify-existing-flow.md` | Behavior Delta MODIFIED 段內描述變更前狀態的 inline bold label（per F-08 / DD-A Path A）|
@@ -51,3 +61,7 @@ The "使用位置" column refers to file paths where the term appears structural
 | Structural language | 結構性語言 | Templates, generated specs, `TEMPLATE-COVERAGE.md` | 固定文件結構語言，例如 headings、table headers、labels、placeholders、IDs、anchors；Dflow 保持 canonical English |
 | Canonical English | 標準英文結構 | Templates, scaffolding, generated specs | Dflow 固定使用的英文結構詞彙，用於穩定 AI 導航、anchor 定位與跨檔維護 |
 | Code-facing terms | 面向程式碼的術語 | Templates, generated specs, `_conventions.md` | 不應只為符合 prose 語言而翻譯的內容，例如 code identifiers、DDD pattern names、BR IDs、SPEC IDs、file paths、branch names、anchors、inline code |
+| Evidence | 證據 / 出處 | `analysis.md` | 每一條 entry 都帶：敘事節的子節結尾一行 `Evidence:`，表格的每一列放在 `Evidence` 欄（生命週期的狀態表除外，理由見 rationale registry 的 `R-ANALYSIS-EVIDENCE-01`）；值只有六個：`code`／`data`／`confirmed by {role}`／`document`／`inferred`／`assumed`；值維持英文，其後的複查入口照 `Prose Language` 寫 |
+| Lifecycles | 生命週期 | `analysis.md`, `modify-existing-flow.md` | 一個狀態欄位有哪些值、從哪一個轉到哪一個、誰觸發、要滿足什麼；狀態欄位本身作為存下來的屬性仍在 `models.md`，單次轉移准不准發生是 `rules.md` 的一條規則 |
+| Read Models and Derived Figures | 讀取模型與衍生數字 | `analysis.md`, `modify-existing-flow.md` | 算出來、而不是存下來的數字：定義、計入條件、切換點；存下來的實體與值物件仍在 `models.md` |
+| Hotspots | 熱點 | `analysis.md`, `modify-existing-flow.md` | 專案一直在繞過、要靠一個還沒做的領域決定才解得掉的地方（卡在 `analysis.md` 收的知識、一條業務規則，或還沒記下的知識上）；要改程式才解得掉的屬技術債 |

package/bin/dflow.js

@@ -51,6 +51,14 @@ Without --skills, selecting an agent that has no project-level skill yet
 prompts to install it (default yes) on an interactive terminal; non-interactive
 runs install it by default without reading an extra stdin answer. Agents whose
 skill file already exists are not re-asked and not regenerated.
+
+On upgrade re-runs the command also refreshes the marker-guarded canonical
+region of dflow/specs/shared/AI-AGENT-GUIDE.md (content outside the markers,
+including "## Project Context", is kept) and advances the "> Dflow Version:"
+last-reconciled line in _conventions.md. A pre-marker guide, or an agent file
+you edited yourself, is never rewritten silently: interactive runs offer
+marker adoption (default No); non-interactive runs skip and warn. (A pristine,
+unedited Dflow shim is still regenerated in place, as before.)
 `);
 }
 
@@ -59,9 +67,13 @@ function printRenderHelp() {
   dflow render [--src <dir>] [--out <dir>] [--title <text>]
 
 Renders the Markdown specs tree into a mirrored static HTML tree for human
-reading (record tables become cards, AI markers become badges), plus an
-index.html file tree at the output root. Open index.html directly in a
-browser; file:// works, no server needed.
+reading (record tables become cards, AI markers become badges; the filled
+lifecycle and flow tables in analysis.md are also drawn as diagrams), plus
+an index.html at the output root: a grouped directory of the specs (each
+group collapsed until you open it; a lone group starts open) when --src is
+a Dflow specs root (it holds shared/_conventions.md), or a plain file tree
+otherwise. Open index.html directly in a browser; file:// works, no server
+needed.
 
 Markdown stays the AI-facing source of truth. Re-run this command whenever
 the sources change; every run is a full rebuild.
@@ -92,7 +104,27 @@ function printDoctorHelp() {
 Read-only health check for the current project. Reports findings such as:
 
   - dflow/specs/shared/_conventions.md missing the Dflow Version
-    front-matter line
+    front-matter line, or recording an older last-reconciled version
+  - policy sections (Git Policy / AI Commit Policy / Prose Language)
+    missing or no longer machine-readable
+  - AI-AGENT-GUIDE.md frozen at an older Dflow version (missing or
+    malformed guide-canonical markers, stale canonical content) and
+    dangling "AI-AGENT-GUIDE.md § ..." references from the workflow bundle
+  - AI-AGENT-GUIDE.md "## Project Context" missing the machine-readable
+    Tech stack / Migration rows that context inference reads
+  - init-only starters drifted (missing or edited Git-principles file
+    for the selected policy)
+  - active feature _index.md files created from an older template shape
+  - root agent files (AGENTS.md / CLAUDE.md / copilot-instructions.md)
+    with malformed Dflow markers or unmanaged Dflow wording
+  - workflow bundle orphans, a bundle projected by an older Dflow, and a
+    bundle manifest that is present but unreadable
+  - a partly installed set of /dflow:* command files, or ones still using
+    the Dflow 0.5.0 filename
+  - a Dflow-generated SKILL.md that has fallen behind this CLI
+
+Doctor reports only on command and skill files that are already present:
+whether this project should have them is intent, which nothing records.
 
 Doctor never modifies files.
 `);