dflow-sdd-ddd 0.13.0 → 0.15.0

package/templates/brownfield/scaffolding/_conventions.md

@@ -30,25 +30,6 @@ dflow/specs/features/active/{SPEC-ID}-{slug}/
 T3 Trivial changes do **not** produce a separate file — they are
 recorded as one row in `_index.md` Lightweight Changes.
 
-## Prose Language
-
-Project prose language: `{prose-language}`
-
-Dflow templates keep canonical English structural language: headings,
-table headers, fixed labels, placeholders, IDs, anchors, and code-facing
-terms remain English.
-
-Free prose written inside those sections should follow the project prose
-language:
-
-- `en`: write free prose in English.
-- `zh-TW`: write free prose in Traditional Chinese.
-- `{xx-XX}`: write free prose in that explicit BCP-47 language.
-
-Do not translate code identifiers, DDD pattern names, BR IDs, SPEC IDs,
-file paths, branch names, anchors, or inline code only to satisfy the
-prose-language setting.
-
 ### SPEC-ID Format
 
 - Pattern: `SPEC-YYYYMMDD-NNN` (e.g. `SPEC-20260421-001`)
@@ -56,6 +37,15 @@ prose-language setting.
 - Once assigned, the SPEC-ID is immutable — it appears in the feature
   directory name, the first phase-spec filename, and the git branch
   name (see `Git-principles-*.md`)
+- **Minimal (zero-phase) host exception.** A host that records a small
+  standalone or follow-up change — or a baseline capture — carries **no
+  phase-spec**, so there is no phase-spec filename for the SPEC-ID to appear
+  in; the directory name and the branch carry it. A **functional bug** host
+  goes one step further: its branch is `bugfix/BUG-{NUMBER}-{slug}`, so it
+  carries the BUG-NUMBER and not the SPEC-ID at all. In every case the host
+  `_index.md` `branch:` field is authoritative, and the SPEC-ID itself stays
+  immutable. Do not create a phase-spec, or rename a branch, to make the
+  three-name rule above hold.
 
 ### Slug Conventions (Project-Specific Fill-In)
 
@@ -69,6 +59,25 @@ prose-language setting.
 - **Length target**: 2–4 English words or 2–6 Chinese characters
   (Dflow skill guidance)
 
+## Prose Language
+
+Project prose language: `{prose-language}`
+
+Dflow templates keep canonical English structural language: headings,
+table headers, fixed labels, placeholders, IDs, anchors, and code-facing
+terms remain English.
+
+Free prose written inside those sections should follow the project prose
+language:
+
+- `en`: write free prose in English.
+- `zh-TW`: write free prose in Traditional Chinese.
+- `{xx-XX}`: write free prose in that explicit BCP-47 language.
+
+Do not translate code identifiers, DDD pattern names, BR IDs, SPEC IDs,
+file paths, branch names, anchors, or inline code only to satisfy the
+prose-language setting.
+
 ---
 
 ## Filling the Templates
@@ -79,11 +88,14 @@ Dflow ships these templates (do **not** re-inline their content here
 | Template | Used when |
 |----------|-----------|
 | `templates/_index.md`          | Creating a feature directory (every feature) |
-| `templates/phase-spec.md`      | T1 Heavy — new feature / new phase / architectural change |
-| `templates/lightweight-spec.md`| T2 Light — bug fix / small tweak with BR Delta |
+| `templates/phase-spec.md`      | T1 Heavy |
+| `templates/lightweight-spec.md`| T2 Light — classic BR-delta form, or one of the no-BR family variants (presentation, non-breaking contract, operational / security, performance, implementation defect, intentional change) |
 | `templates/context-definition.md` | When a new Bounded Context is introduced |
 | `templates/behavior.md`        | BC-level consolidated behavior spec |
 
+Which tier applies is decided by the cascade in `AI-AGENT-GUIDE.md` § Ceremony
+Scaling, never by this table — these rows only say which template a tier uses.
+
 Project-specific guidance when filling these templates:
 
 - {e.g. "Always reference existing BRs in the BR Snapshot inherited
@@ -99,20 +111,30 @@ Project-specific guidance when filling these templates:
 
 ## Ceremony Scaling (Project Application)
 
-Dflow defines three tiers — **T1 Heavy / T2 Light / T3
-Trivial**. See `AI-AGENT-GUIDE.md` § Ceremony Scaling for the full
-criteria table. We do not re-define the tier criteria here; this
+Dflow defines three tiers — **T1 Heavy / T2 Light / T3 Trivial** — plus a
+below-workflow level. See `AI-AGENT-GUIDE.md` § Ceremony Scaling for the
+full ordered cascade. We do not re-define the tier criteria here; this
 section records how *this* project applies them in borderline
 situations.
 
+**The cascade result is a floor: rows in this section may only escalate a
+tier, never lower it.** A row may take a change Dflow would call T2 and
+make it T1 for this project; no row may lower a T1, and no row may move a
+tracked change below workflow.
+
+Write `T<n> (project convention)` in the Tier column when this project raises the
+tier, and `cascade result` when it adds an obligation but no tier change. Do not
+write a bare tier — that restates the cascade instead of recording a decision,
+and it is how the two drift apart.
+
 | Situation (project-specific) | Tier we default to | Why |
 |------------------------------|--------------------|-----|
-| {e.g. Year-end reporting tweak without BR change} | T2 | Touches logic path even though no new BR; extract to `lightweight-spec.md` for trace |
-| {e.g. Pure label / display text translation} | T3 | No BR change; inline row in `_index.md` |
-| {e.g. UI refresh across multiple entrypoints} | T1 (project convention) | We treat multi-entrypoint UI/API refresh as T1 for this project even though Dflow default would be T2, because these changes often leak into business logic embedded in delivery/entrypoint code (presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures) |
+| {e.g. Year-end reporting tweak without BR change} | cascade result + a `lightweight-spec.md` trace | No tier change — we want the trace even when the cascade would not require a spec file, because the reporting logic path is where our defects hide |
+| {e.g. Pure label / display text wording polish on one screen} | cascade result + note in the extraction log | No tier change — we add the note so the delivery-layer sweep can find it later |
+| {e.g. UI refresh across multiple entrypoints} | T1 (project convention) | We escalate multi-entrypoint UI/API refresh above whatever the cascade returns, because these changes often leak into business logic embedded in delivery/entrypoint code (presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures) |
 
 If the team disagrees on tier classification for a specific change,
-run through the T3 four-criteria checklist (in `AI-AGENT-GUIDE.md` §
+run through the ordered cascade (in `AI-AGENT-GUIDE.md` §
 Ceremony Scaling) and record the decision here the first time it arises.
 
 ---

package/templates/brownfield/scaffolding/_overview.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/_overview.md 1 — keep this line: dflow doctor reads it -->
 <!-- Seeded by Dflow. -->
 
 # System Overview — {System Name}

package/templates/brownfield/templates/_index.md

@@ -6,6 +6,7 @@ created: {YYYY-MM-DD}
 branch: feature/{SPEC-ID}-{slug}
 # follow-up-of: {原 SPEC-ID}    # 選用：本 feature 為某個已 completed feature 的 follow-up 時填入
 ---
+<!-- dflow-shape: brownfield/_index.md 1 — keep this line: dflow doctor reads it -->
 
 <!--
 Template note (for AI):
@@ -36,7 +37,21 @@ Template note (for AI):
   Minimal usage:
     For a 1-commit / 1-phase feature this template can be ~30 lines —
     fill metadata + a short Goals & Scope + one row in Phase Specs +
-    initial BR Snapshot + Resume Pointer. The other sections can stay empty.
+    Resume Pointer, and the BR Snapshot **only when this host carries a BR
+    delta** — a phase-bearing host whose phase-specs establish none leaves it
+    empty, and that section states the rule. The other sections can stay empty.
+
+  Minimal HOST usage (zero-phase) — a different shape, not a smaller one:
+    A minimal host (references/modify-existing-flow.md Step 1.7 standalone, or
+    its Step 1.6 follow-up minimal variant, or Step 1.8's post-hoc hotfix, whose
+    linkage resolves to one of those two) carries NO phase-spec, and its
+    Phase Specs table stays EMPTY. Its record lives in Lightweight Changes
+    instead — at least one row, written before the first commit. Do NOT add a
+    Phase Specs row or create a phase-spec to make the "1-phase" wording above
+    fit: a host that carries a phase is certified as phase-bearing whatever it
+    was intended to be, and closeout then checks it as one
+    (references/finish-feature-flow.md Step 1). A baseline capture uses this
+    same zero-phase shape, with a `Tier = baseline` row.
 -->
 
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
@@ -71,24 +86,103 @@ Template note (for AI):
 > 歷史由各 phase-spec 的「Delta from prior phases」段串接閱讀；feature
 > 完成時 `/dflow:finish-feature` 把本表推進到對應 BC 的 `rules.md` /
 > `behavior.md`（延續 Step 8.3 既有 sync 機制）。
+>
+> ⚠ **這張表在範本裡是空的（只有表頭），那是對的 —— 不要為了讓它看起來有東西而造一列。**
+> 只有這個 host 真的帶著 BR delta 時才會有列（`/dflow:new-feature` 會拿第一個 phase
+> 規劃中的 BR 初始化它；phase-specs 沒有帶出 BR delta 的 host 就留空）；**BC-bearing
+> 的 follow-up host** 另外會從 `rules.md` 繼承 in-scope 的列
+> （見 references/modify-existing-follow-up.md）。
+> ⚠ **`Tier = baseline` 的 capture host 是例外：本表留空，而且不繼承** —— 即使它是
+> BC-bearing 的 follow-up 也一樣（見 references/modify-existing-follow-up.md 的
+> baseline 例外，與 references/finish-feature-minimal-host.md 的 baseline 檢查）。
 
 | BR-ID | Current Rule | First Seen (phase) | Last Updated (phase) | Status |
 |---|---|---|---|---|
+
+<!--
+欄位範例（**這不是資料，是給 AI 看的範例**；它在註解裡，所以不會被當成本表的列）：
+
 | BR-01 | {規則描述} | phase-1 / inherited from rules.md | phase-N | active / removed |
 
+⚠ 本區塊不是規範。`First Seen` ／ `Last Updated` ／ `Status` 的權威語義在既有
+flow 規則裡：
+`First Seen` 的 `inherited from rules.md` 見 references/modify-existing-follow-up.md；
+`Status` 的 `active` / `removed` 見 references/finish-feature-flow.md Step 3 與
+references/new-phase-flow.md。有衝突時以那些檔為準。
+-->
+
 <!-- dflow:section lightweight-changes -->
 ## Lightweight Changes
 
 > T2 行：描述含「見 `lightweight-{date}-{slug}.md`」外連
 > T3 行：inline 完整描述一句話 + 標籤（如 `[cosmetic]` / `[text]` /
->        `[format]`）；T3 不產獨立 spec 檔
+>        `[appearance]`）；T3 不產獨立 spec 檔
+>
+> **minimal（zero-phase）host 的每一列都要能指出這次變更碰到的原始碼路徑**
+> （寫到能和一個 commit 比對的粒度即可，不是貼 diff）。T2 由它的
+> lightweight-spec `## Implementation Paths` 段承載，row 只要外連過去；**T3 沒有
+> spec 檔，路徑就直接寫在 Description 裡**，接在一句話描述與標籤後面。
+> `/dflow:finish-feature` 會拿 checkpoint 1 的 diff 和這些路徑比對；
+> **一個路徑都沒宣告會擋下 closeout**，不會當成通過。
+> **掛在 phase-bearing feature 底下的列不受此限**——closeout 對它們不跑這項檢查
+> （`references/finish-feature-flow.md` Step 1 明寫此例外，理由是 hosted row 本來
+> 就沒有被要求宣告路徑）。寫上去仍是好習慣，但那裡沒有 gate、也不會擋。
+> baseline capture 的 `Tier = baseline` 列同理，寫它實際寫入的 BC 層文件或 `domain/analysis.md` 的路徑。
+>
+> **post-hoc hotfix 的 T3 列**（見 references/modify-existing-flow.md Step 1.8）：
+> Description 另外標明這是 hotfix，並寫出識別依據（PR／incident／tracker 編號）
+> ——沒有依據的 hash 會擋下 closeout。此時路徑指的是**已合併的那個 hotfix**
+> 碰到的檔案；本列 `Commit` 欄填的是**補文件那個 commit** 的 hash，不是 hotfix
+> 的 hash（後者記在 Checkpoint Log 的 `reconciled (...)` 列）。兩者來源不同，
+> 不可互填。
 >
-> Tier 判準見 AI-AGENT-GUIDE.md § Ceremony Scaling 三層表。
+> Tier 判準見 AI-AGENT-GUIDE.md § Ceremony Scaling 的 ordered cascade（步驟 0–4，先命中者勝）。
 
 | Date | Tier | Description | Commit |
 |---|---|---|---|
 | {YYYY-MM-DD} | T2 | bug fix XYZ — 見 [`lightweight-{date}-{slug}.md`](./lightweight-{date}-{slug}.md) | {hash} |
-| {YYYY-MM-DD} | T3 | 按鈕顏色從藍改綠 `[cosmetic]` | {hash} |
+| {YYYY-MM-DD} | T3 | 按鈕顏色從藍改綠 `[cosmetic]` — `src/Web/Checkout/PayButton.cs` | {hash} |
+
+> ⚠ **`Commit` 還沒填就留空 —— 不要寫佔位字串。** 上面的 `{hash}` 是**範本佔位符**
+> （代表「這裡放一個 commit hash」），不是可以留在真實 `_index.md` 裡的值。
+> 自己發明 `{pending}`、`（待 commit）` 這類字樣會讓那一格變成**非空**，而
+> **凡是照「空／非空」判的規則都會把它讀成已經填好**。在 phase-bearing host 上更徹底：
+> `_index.md` 對 checkpoint 1 的那些證據檢查全都標明「minimal host（zero-phase）限定」，
+> 所以**關帳（closeout）那條線上**沒有任何檢查會去看那一格 —— 要到下面說的回填與
+> PR review 才有人真的去讀它。
+> ⚠ **抓得到它的判準是「那條檢查會不會去解析這個值」**，不是照空／非空判的那些。
+> 目前這樣的檢查有：`references/finish-feature-flow.md` **Step 1**（minimal host 的
+> 關帳檢查：把佔位字串判為「**從未填入**」，與「空」和「填錯 hash」分成三種不同訊息，
+> 一律**擋**）、同檔 **Step 4 指令 1**（hosted 列回填：unfilled 指「空**或**放著佔位
+> 字串」，兩者以同一種方式回填）、以及 `references/pr-review-checklist.md` 的**兩項**
+> ——存在性那項要 `git cat-file -t` 逐個 resolve，hosted identity 那項再用
+> `git show --stat` 確認那個 hash 真的是該列自己的實作 commit（該檔明寫這兩項
+> 「不可互換」）。⚠ 另有數處**複述**同一條規則但把執行交給上面那些檢查（例如
+> `references/modify-existing-flow.md` 的「Commit evidence goes to two surfaces」），
+> 那些是指標、不是額外的關卡。**日後新增的檢查照同一個判準算，這裡列幾項不是重點。**
+> 別把它們的存在讀成「所以放佔位字串沒差」：在它們之前，每一條機械規則都已經把
+> 那一格當成填好了。
+> **留空是有名字的狀態；佔位字串不是。**
+
+> **post-hoc hotfix 的列自成一個 host，不會和上面的一般列並存**
+> （見 references/modify-existing-flow.md Step 1.8）：上面兩列的 checkpoint 1
+> **必須**碰到它們宣告的實作路徑，而 post-hoc host 的 checkpoint 1 是**補文件那個
+> commit**、按約定**不得**碰任何已宣告的實作路徑，同一個 commit 不可能兩者兼具
+> （`references/finish-feature-flow.md` Step 1）；Checkpoint Log 的實作列 Result
+> 也只能二擇一（`committed (...)` 或 `reconciled (...)`）。post-hoc host 本身仍
+> **可以是 compound**——多個 post-hoc 列共用同一個補文件 commit——不能混的是一般列：
+>
+> | Date | Tier | Description | Commit |
+> |---|---|---|---|
+> | {YYYY-MM-DD} | T3 | 首頁公告錯字修正 `[text]` — `src/Web/Home/Notice.cs`；post-hoc hotfix，識別依據 INC-2031 | {hash} |
+
+> **baseline capture 的表長這樣，而且只有這一列**（bf 專屬）——closeout 對
+> baseline host 要求 Lightweight Changes 表**恰好一列**，所以它不會和上面的
+> T2／T3 列並存：
+>
+> | Date | Tier | Description | Commit |
+> |---|---|---|---|
+> | {YYYY-MM-DD} | baseline | 盤點 Expense 既有行為並寫入 BC 層 — `dflow/specs/domain/expense/rules.md`、`behavior.md` | {hash} |
 
 <!-- dflow:section checkpoint-log -->
 ## Checkpoint Log
@@ -96,18 +190,65 @@ Template note (for AI):
 > 生命週期 checkpoint 的 commit / skip 時間線（讓三週後回溯不必手動重建）。
 > 每個 checkpoint 無論 commit 或 skip 都記一列。Tier 決定 checkpoint 數：
 > T1 三點（spec 完 / impl 完 / closeout）、T2 兩點（spec+impl 合併 / closeout）、
-> T3 單一 commit。
+> T3 單一實作 commit（其 inline row 與本列的 hash 由 host 的下一個 commit 一併帶進；
+> host 若沒有後續 commit，允許一個只動 ledger 的 tracking commit 收尾，該 commit 不另成列）。
+> ⚠ **上面那些「點」在本表 `Checkpoint` 欄各有固定的字面值**：spec 里程碑寫
+> **`spec-baseline`**、實作寫 **`implementation`**、關帳寫 **`closeout`**（下表的
+> `spec-baseline` / `implementation` / `closeout` 三列就是這幾個值；表中另有一列
+> `branch-override`——本例排在最前——是紀錄列、不是生命週期 checkpoint，見下方說明）。散文裡的
+> 「spec 完」是在說那個里程碑，**不是欄位值** —— 不要照著它造一個 `spec` 出來。
+> ⚠ 這條只管**本表的 `Checkpoint` 欄**。`references/git-integration.md` 的選配 trailer
+> `Dflow-Checkpoint: {SPEC-ID} {spec|impl|closeout}` 有它自己的三個角色名（其中就有
+> `spec`）——那是另一個地方的詞彙，**不要拿本條去「修正」一個寫對的 trailer**。
+>
+> **Minimal host（zero-phase）例外**——見 references/modify-existing-flow.md
+> Step 1.7（standalone）、Step 1.6 的 follow-up minimal 變體，或 Step 1.8 的
+> post-hoc hotfix（其 linkage 落在前兩者之一）：這種 host 之後
+> 沒有別的 commit 可以收攏 T3 的 row，所以**不分 tier 一律記兩個 checkpoint**
+> （implementation——baseline capture 記 `spec-baseline`——然後 closeout），
+> 而且 T3 的 inline row 要**寫進 checkpoint 1 本身**、不是等下一個 commit 帶
+> 進來。上一段「T3 單一實作 commit ／ 由下一個 commit 帶進」講的是**掛在既有
+> feature 底下的** T3，不適用於 minimal host。
+>
+> Result 的合法值是 `committed ({hash})` / `skipped` / `failed`，外加
+> **`reconciled ({merged-hotfix-hash})`**——只給 post-hoc hotfix（Step 1.8）的
+> implementation 列用，意思是「本 checkpoint 記錄的是一個已經合併的變更」。
+> 括號裡是**那個 hotfix 的 hash**，不是本 host 補文件那個 commit 的 hash
+> （後者填在 Lightweight Changes 該列的 `Commit` 欄）。完整詞彙見
+> references/git-integration.md § Commit Checkpoints, Branch Gate & AI Commits。
+>
+> **`branch-override` 是紀錄列，不是生命週期 checkpoint。** 在 branch gate 選了
+> 「override and stay」時記一列（references/git-integration.md § Branch gate
+> 定義形狀）：Checkpoint 寫 `branch-override`、Result 寫
+> `override ({你留下來的分支})`。它**不是 commit**、**不計入 tier 的 checkpoint
+> 數**。closeout 的分支檢查會看**有沒有任何一列**指名你現在所在的分支（不是只看最近
+> 一列——一個 host 可能在不同 phase override 到不同分支，而 closeout 自己不觸發 branch
+> gate、不會補寫新列）。括號裡必須是**分支名**，沒寫分支的紀錄豁免不了任何東西。
+> `branch:` 欄位本身永遠不因 override 而改寫。
+> ⚠ **只會出現在 phase-bearing host。** references/modify-existing-flow.md 對
+> **minimal host**（Step 1.6 follow-up 變體／Step 1.7 standalone／Step 1.8
+> post-hoc）**不提供**這個選項——那些 host 正是拿 `branch:` 當權威來斷言分支相等的。
 >
 > commit hash 只在 commit 實際成功後填入；pre-commit hook reject 或 commit
 > 失敗記 `failed`、不寫假 hash。**例外：closeout 列不填 hash**——closeout
 > commit 無法自含自身 hash，該列於 commit 前寫入、隨歸檔目錄一起進 commit；
 > 溯源用 `git log -1 -- completed/{SPEC-ID}-{slug}` 或選配的
 > `Dflow-Checkpoint` trailer（見 references/git-integration.md）。
+>
+> ⚠⚠ **下表示範的是欄位值，不是這張表的起始狀態——一列都不要預先放。** 每一列
+> 都在它那個 checkpoint **實際走到的當下**才新增（`branch-override` 在 branch gate
+> 選了 override 時；`closeout` 由 references/finish-feature-flow.md Step 4 指令 1
+> 在關帳當下寫入）。
+> ⚠ **尤其不要預先放一列空的 `closeout` 佔位**：minimal host（zero-phase）的關帳
+> 檢查要求 Checkpoint Log 在關帳前**恰好一列**
+> （references/finish-feature-minimal-host.md Step 1），預先放下的那一列會**擋下**
+> 關帳。
 
 | Timestamp | Checkpoint | Result |
 |---|---|---|
+| {YYYY-MM-DD HH:MM} | branch-override | override ({branch-you-stayed-on}) |
 | {YYYY-MM-DD HH:MM} | spec-baseline | committed ({hash}) / skipped / failed |
-| {YYYY-MM-DD HH:MM} | implementation | committed ({hash}) / skipped / failed |
+| {YYYY-MM-DD HH:MM} | implementation | committed ({hash}) / skipped / failed / reconciled ({merged-hotfix-hash}) |
 | {YYYY-MM-DD HH:MM} | closeout | committed / skipped / failed |
 
 ## Resume Pointer
@@ -117,7 +258,10 @@ Template note (for AI):
 > 下方四個 cursor 欄位是 workflow 進度的**存放層（宣告，claim）**：
 > 進入 flow 時設 Active Workflow；**每過一個 step gate** 更新 Current Step /
 > Gates Passed / Awaiting（與該 gate 既有的 `_index.md` 更新合併，不另加儀式）；
-> closeout / `/dflow:cancel` 時 Active Workflow 設回 `none`。
+> `/dflow:cancel` 時 Active Workflow 設回 `none`；closeout 也設回 `none`，但**是在
+> 歸檔那一步**——`finish-feature-flow.md` Step 4 的 `git mv` 之後緊接著寫，**不是**
+> closeout 一開始就寫。在那之前 closeout 本身仍是進行中的 workflow，後面還有 step
+> gate 要過。
 > `/dflow:status` 讀 cursor 後會與推導證據（Checkpoint Log、phase-spec
 > status、git log）交叉，不一致會明確報 mismatch——cursor 是宣告、證據優先。
 > Phase 粒度進度由上方 Phase Specs 表承載；cursor 只補 workflow step / gate

package/templates/brownfield/templates/analysis.md

@@ -0,0 +1,79 @@
+<!-- dflow-shape: brownfield/analysis.md 1 — keep this line: dflow doctor reads it -->
+<!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+<!-- Placement: this template fills two paths. Cross-Context Flows and Function / Role Index are always written in the domain-root copy, `dflow/specs/domain/analysis.md`, whoever owns what they describe, and left as they are in a per-context copy - including in a project that has only one context. A hotspot row goes in the copy that holds the knowledge it is stuck on, and a question row in the copy that will hold its answer, as Open Questions and Hotspots says. For every other entry, ask who owns what the entry describes. A status field is owned by the context whose entity stores it - the entity that context's models.md defines, or will define. A derived figure is owned by the context that computes it, not the ones it reads from. A mechanism is owned by the context whose behavior it explains. One context owns it: the entry goes in that context's `dflow/specs/domain/{context}/analysis.md`, and it stays there even when another context reads the field, triggers a transition or supplies data it reads. No one context owns it - two contexts own it equally, or a mechanism explains behavior in several contexts equally: it goes in the domain-root copy. -->
+<!-- Entry ids: every entry carries one. The prefix is the section's - `FL` flows, `LC` lifecycles, `RM` read models, `MX` mechanisms, `FN` function rows, `HS` hotspot rows - and the number is sequential within this copy and never reused; an entry keeps its id for as long as it stays in this copy. A subsection carries its id in its heading (`### LC-01: {name}`); in the two tables that have an ID column, each row carries it there. Cite an entry in this file by its id alone. Cite one in the other copy, or from any other document, as path then id: `domain/{context}/analysis.md LC-01`. Until what a citation points at has an entry of its own, write its name instead of an id; whenever you update this file, replace any such name whose entry now exists. An entry that moves to the other copy takes a new id there: update whatever cited the old one - search for its path and id together, and for the bare id in the file it left. -->
+<!-- Referring to a rule: a cell that names what a business rule decides refers to that rule and holds nothing else; a cell decided by no rule holds the value itself. Refer to a rule by its BR-ID alone only from the copy of the context whose rules.md holds it; anywhere else - always in the domain-root copy - write its path then its id: `domain/{context}/rules.md BR-001`. A cell holding a BR-ID, alone or after its path, is a reference; anything else is a recorded value. Until a rule has a BR-ID, write the rule's name; whenever you update this file, replace any rule name whose BR-ID now exists. -->
+<!-- Evidence convention: every entry carries its evidence in the form `{code | data | confirmed by {role} | document | inferred | assumed} - {what to open to re-check} ({date})`. A subsection ends with one line that reads `Evidence: ` followed by it; a table row puts it in its Evidence column. For `data`, the middle slot also carries the counting rule the number used. `document` is a written source outside the code - a regulation, an internal policy, a ticket, an existing spec. When you take a claim from one of these rather than re-checking it yourself, the date is the one that source gives, not the day you copied it. `inferred` is a conclusion drawn from code or data rather than read off either one: name what it was drawn from. A question nobody has answered yet is not an entry: record it where the Open Questions and Hotspots section says. A value that rests on nothing a reader can open is `assumed`: a guess, or a fact whose only home is a private note, a chat log, or one person's AI memory. Say what it rests on, and record the question of confirming it where the Open Questions and Hotspots section says. -->
+
+# Domain Analysis
+
+> System-level knowledge that no single bounded-context document holds: flows
+> that cross contexts, the lifecycle a status field moves through, how derived
+> figures are computed, the mechanisms behind observed behavior, who reaches
+> which function, and the spots in them this project keeps working around.
+> Where an entry relies on a rule, a model, or a context relationship, link it
+> by BR-ID, model name, or section instead of restating it. Where this project
+> has already written one of these somewhere else, leave that text where it is
+> and give it a row or a subsection here that says where to read it.
+
+## Cross-Context Flows
+
+<!-- Global file only. One subsection per ordered flow whose steps are owned by more than one context; the table is the record, one row per step in order. A flow that stays inside one context is not recorded here: its scenarios belong in behavior.md. A statement about two contexts that holds without an order - which one is upstream, how they integrate, what data passes between them - belongs in context-map.md: link it instead of repeating it. A derived figure is not a flow, however many contexts it reads from - it goes in Read Models and Derived Figures. Keep one row per step and no branches: where the flow genuinely forks, either write the fork as its own flow or record the condition as a rule in rules.md and link it. -->
+
+### FL-01: {流程名稱}
+
+| # | From | To | Handed over | State change | Evidence |
+|---|---|---|---|---|---|
+| 1 | {Context A} | {Context B} | {交出去的是什麼：欄位、識別鍵或事件} | {造成什麼狀態變化} | {code｜data｜confirmed by {role}｜document｜inferred｜assumed} - {複查入口} ({date}) |
+
+## Lifecycles
+
+<!-- One subsection per status field: name the field and where it is stored, list every value it can hold, then one row per transition. List the values even when the code admits more than the workflow uses: a value seen only in stored data is still a state. A transition triggered from another context stays here - name that flow in Cross-Context Flows and cite it rather than restating the handover (from a per-context copy: `domain/analysis.md FL-01`). Whether a single transition is allowed to happen is a business rule: it belongs in rules.md and the Guard cell carries its BR-ID. One scenario played out end to end belongs in behavior.md. The entity that stores the field is defined in models.md. The Means cell says what the state allows or blocks next; when the value's name is also a term the business uses elsewhere, its definition belongs in glossary.md and this cell stays short. Evidence sits on the transitions, not on the state list. -->
+
+### LC-01: {狀態欄位名稱}（`{存放位置：資料表.欄位，或 Aggregate 屬性}`）
+
+| State | Means |
+|---|---|
+| `{狀態值}` | {這個狀態允許或擋住接下來的什麼} |
+
+| From | Trigger | To | Guard | Evidence |
+|---|---|---|---|---|
+| `{原狀態}` | {誰做了什麼} | `{新狀態}` | {決定它的 BR-ID；沒有規則決定就寫必須成立的條件，都沒有就留空} | {code｜data｜confirmed by {role}｜document｜inferred｜assumed} - {複查入口} ({date}) |
+
+## Read Models and Derived Figures
+
+<!-- One subsection per figure or read model: its definition, which records or states it counts, and the point at which an amount moves from one figure to another. A stored entity or value object is defined in models.md; this section holds what is computed from them. Say what a missing, duplicated or stale record does to the figure. -->
+
+### RM-01: {數字或 read model 名稱}
+
+{定義、計入條件、切換點}
+
+Evidence: {code | data | confirmed by {role} | document | inferred | assumed} - {要開哪一支才能複查} ({date})
+
+## Mechanisms
+
+<!-- One subsection per mechanism: how the system produces a behavior that no single rule explains - versioned records, deferred updates, recalculation on read. A behavior that one rule or one Given/When/Then scenario can state belongs in rules.md / behavior.md instead. The Affects line lists what this mechanism changes the meaning of - BR-IDs and entry ids, each cited as Entry ids and Referring to a rule say. -->
+
+### MX-01: {機制名稱}
+
+{運作方式與影響}
+
+Affects: {BR-ID 與 FL-／LC-／RM- 編號（照檔頭的引用規則帶路徑；還沒有編號的寫名稱），逗號分隔；沒有就寫 none}
+Evidence: {code | data | confirmed by {role} | document | inferred | assumed} - {要開哪一支才能複查} ({date})
+
+## Function / Role Index
+
+<!-- Global file only. One row per function: which roles reach it and the data scope each one sees. When a business rule decides who may use the function or what a role sees, that rule is the source of truth: write its BR-ID in that cell instead of restating the rule. Write roles or a data scope directly only where no rule decides them - a menu entry every role sees, a report anyone can run. -->
+
+| Function | ID | Entry point | Bounded Context | Roles | Data scope | Evidence |
+|---|---|---|---|---|---|---|
+| {功能名稱} | FN-01 | `{route / page / job}` | {Context name} | {角色，或決定它的 BR-ID（帶路徑）} | {看得到的資料範圍，或決定它的 BR-ID（帶路徑）} | {code｜data｜confirmed by {role}｜document｜inferred｜assumed} - {複查入口} ({date}) |
+
+## Open Questions and Hotspots
+
+<!-- One row per hotspot: a spot in the knowledge above this project keeps working around until a domain decision settles it. It goes in whichever copy of this file holds the knowledge it is stuck on - or, when that is a business rule or knowledge not recorded yet, the copy the Placement question gives it - and the Affects column names that knowledge by id, cited as Entry ids and Referring to a rule say. Also one row per question that comes up while writing an entry here and whose own answer will be a cross-context flow, a lifecycle, a derived figure, a mechanism or role reach. A question the current feature must answer before it can finish stays in that feature's spec, and a question whose answer belongs to another document's subject stays in that document's own Open Questions section - a term in glossary.md, a business rule in the owning context's rules.md, and a context boundary, an integration responsibility or the question of which context owns a rule in context-map.md. A question that stays in this file goes in the copy that will hold its answer - the copy Placement gives that answer - whichever copy the entry that raised it is in. When a code change would settle an item - a missing check, a known shortcut - it is tech debt: record it in tech-debt.md instead. A hotspot whose pending decision is recorded elsewhere links to it. A settled item stays as a resolved row that says what settled it, with the settling decision in its Evidence cell. -->
+
+| Item | ID | Affects | Why it matters | Status | Evidence |
+|---|---|---|---|---|---|
+| {待確認事項或熱點} | HS-01 | {FL-／LC-／RM-／MX-／FN- 編號或 BR-ID（照檔頭的引用規則帶路徑；還沒有編號的寫名稱）} | {影響} | open / resolved | {code｜data｜confirmed by {role}｜document｜inferred｜assumed} - {複查入口} ({date}) |

package/templates/brownfield/templates/behavior.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/behavior.md 1 — keep this line: dflow doctor reads it -->
 # {Bounded Context} — Behavior Specification
 
 > **Purpose**: Consolidated source of truth for this context's current behavior.

package/templates/brownfield/templates/context-definition.md

@@ -4,6 +4,7 @@ chinese-name: {中文名稱}
 owner: {負責的開發者或團隊}
 created: {YYYY-MM-DD}
 ---
+<!-- dflow-shape: brownfield/context-definition.md 1 — keep this line: dflow doctor reads it -->
 
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 

package/templates/brownfield/templates/context-map.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/context-map.md 1 — keep this line: dflow doctor reads it -->
 <!-- Seeded by Dflow. -->
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
@@ -27,7 +28,7 @@
 
 ## Integration Notes
 
-- {跨 context 的資料流、權責邊界或 legacy coupling}
+- {沒有先後順序也成立的跨 context 資料交換、權責邊界或 legacy coupling；有先後順序的跨 context 交手流程記在 analysis.md}
 
 ## Open Questions
 

package/templates/brownfield/templates/glossary.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/glossary.md 1 — keep this line: dflow doctor reads it -->
 <!-- Seeded by Dflow. -->
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->