dflow-sdd-ddd 0.14.0 → 0.15.0

package/templates/brownfield/scaffolding/CLAUDE-md-snippet.md

@@ -114,7 +114,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - `/dflow:new-feature` — 新功能開發
 - `/dflow:new-phase` — 在 active feature 內新增階段
 - `/dflow:modify-existing` — 修改既有功能
-- `/dflow:bug-fix` — 輕量修復
+- `/dflow:bug-fix` — Bug 修復
 - `/dflow:finish-feature` — feature 收尾
 - `/dflow:pr-review` — PR 審查
 - `/dflow:verify` — rules.md ↔ behavior.md 漂移檢查

package/templates/brownfield/scaffolding/Git-principles-gitflow.md

@@ -17,6 +17,8 @@ trunk-based, GitHub Flow), use `Git-principles-trunk.md` instead.
 
 ---
 
+<!-- dflow-generated: git-principles-canonical START -->
+
 ## 1. Branch Structure
 
 | Branch | Naming | Cut from | Merges to |
@@ -24,6 +26,7 @@ trunk-based, GitHub Flow), use `Git-principles-trunk.md` instead.
 | `main` / `master` | `main` | — | release / hotfix only |
 | `develop` | `develop` | — | integration branch for features |
 | feature | `feature/{SPEC-ID}-{slug}` | `develop` | `develop` |
+| bugfix | `bugfix/{BUG-ID}-{slug}` | `develop` | `develop` |
 | release | `release/{version}` | `develop` | `main` + `develop` |
 | hotfix | `hotfix/{version}-hotfix{n}` | `main` | `main` + `develop` |
 
@@ -31,6 +34,17 @@ The `feature/{SPEC-ID}-{slug}` pattern is a **Dflow requirement** (not
 a Git Flow requirement). It ties each feature branch to its
 corresponding `dflow/specs/features/active/{SPEC-ID}-{slug}/` directory.
 
+A **`bugfix/{BUG-ID}-{slug}`** branch is the same shape as a feature branch and
+follows the same topology — cut from the same base, pushed the same way,
+integrated the same way, and **closed out the same way**. It is used when a
+defect owns its own host rather than being picked up by a feature already in
+flight. Its host is a **minimal (zero-phase) host**, so it carries no
+phase-spec: the SPEC-ID lives in the directory name while the branch name
+carries the BUG-NUMBER, and the host `_index.md` `branch:` field is
+authoritative for both. Closeout is not optional because the branch prefix
+differs — `/dflow:finish-feature` runs and the directory is archived to
+`completed/` before the branch merges, exactly as for `feature/`.
+
 ### Feature Branch Workflow
 
 ```bash
@@ -107,10 +121,18 @@ git branch -d hotfix/{version}-hotfix{n}
 ```
 
 **Hotfix spec requirement (team convention)**: Hotfixes often skip the
-upfront SDD cycle for speed. This project commits to writing a
-lightweight spec within **24 hours** after the hotfix lands, documenting
-root cause + fix + (if applicable) a tech-debt entry in
-`dflow/specs/migration/tech-debt.md` if the bug reveals a systemic issue.
+upfront SDD cycle for speed. This project commits to documenting the fix
+within **24 hours** after it lands. Run `/dflow:modify-existing` in
+**post-hoc mode** (`references/modify-existing-flow.md` Step 1.8): it opens a
+minimal host of its own for the fix, records the implementation checkpoint as
+`reconciled ({merged-hotfix-hash})`, and reconciles rather than re-running work
+that is already on the mainline.
+What gets written is whatever the cascade's tier calls for — a **T2** lands a
+lightweight spec (root cause + fix + a `dflow/specs/migration/tech-debt.md` entry
+if the bug reveals a systemic issue); a **T3** lands one `_index.md` Lightweight
+Changes row and no spec file. Step 1.8 admits **T2 / T3 only**: a **T1**
+post-hoc keeps the normal phase-bearing route and documents the merged work
+there.
 This is a **human-to-human commitment** — Dflow / AI cannot track the
 24-hour clock; the team enforces it in retros.
 
@@ -156,7 +178,10 @@ before making key Git operations:
       justification in the spec's notes section)
 - [ ] `_index.md` status reflects the current work (Phase Specs row
       updated, `Resume Pointer` refreshed if the commit reaches a meaningful
-      checkpoint)
+      checkpoint). A **minimal (zero-phase) host** has no Phase Specs row to
+      update — its record is the Lightweight Changes row, and that row must
+      already be written **before** this commit, not after it. Refresh the
+      Resume Pointer as usual.
 
 ### Before merging a feature branch to `develop`
 
@@ -170,6 +195,23 @@ before making key Git operations:
 - [ ] `dflow/specs/migration/tech-debt.md` updated with any debt discovered
 - [ ] Domain layer (`src/Domain/`) has no delivery-framework references
 
+> **Minimal (zero-phase) host.** The items about this host's own record —
+> `/dflow:finish-feature` having run, `_index.md` status `completed`, and the
+> archival move — apply **unchanged**: they are what stops a host merging with
+> its record still open. Every item naming a **Domain or bounded-context
+> artifact** applies only to what this change **actually touched**: a **no-BC**
+> host has no context to sync or document, a **T3** does no Domain work at all,
+> and a **baseline capture** wrote Domain documents directly rather than syncing
+> to them — so for those they read N/A. **Bounded-context-scoped only** —
+> `glossary.md` and `migration/tech-debt.md` belong to no bounded context, stay
+> in a no-BC host's sweep, and are a baseline capture's own capture
+> destinations, so they are **not** N/A for either. **Code invariants are not
+> artifacts** — the items here that state a rule about the **source** rather
+> than name a document to update are **never N/A**: they hold for any change
+> that touches code at all, and a host wrongly claiming to be no-BC is exactly
+> what they catch. Record the N/A; do not create a context, a Domain document,
+> or a BR row to tick a box.
+
 ---
 
 ## 4. Integration Commit Message Conventions
@@ -200,6 +242,31 @@ Related BR-IDs:
 Related SPEC-IDs: {SPEC-ID}{, follow-up SPEC-IDs if any}
 ```
 
+**Zero-phase (minimal host) form.** A minimal host has no phases and may have
+no bounded context, so its Change Scope block carries the values that are
+actually true rather than padded ones:
+
+```
+Change Scope:
+- BC: none                          # or the real context, when the change has one
+- Phase Count: 0
+- Lightweight Changes: 1 T2 + 0 T3  # at least one row, always
+
+Related BR-IDs: {empty, or the per-family no-BR marker this change carries}
+```
+
+`none` and `0` are the honest values here, not placeholders waiting to be
+filled. **`Related BR-IDs` is the exception — never force it to `none`.**
+It reports what this change's own record carries, not what was synced, so it
+takes the same values a BC-bearing host would: empty, or the per-family no-BR
+marker when the T2 carries one. Writing `none` there erases the marker the
+zero-phase shape requires (`references/finish-feature-flow.md` Step 5 states
+the rule, and a baseline host leaves the field empty). A minimal host that genuinely touches a bounded context reports that
+context and its real BR delta exactly as a phase-bearing feature would — the
+zero is the **phase count**, not the significance. A **baseline capture** is
+the one variant that always reports a real `BC:` — capturing it is the whole
+point of the host.
+
 ### Concrete example
 
 ```bash
@@ -252,7 +319,7 @@ release.
 Example entry:
 
 ```markdown
-## [1.2.3] — {YYYY-MM-DD}
+## [1.2.3] — {2026-04-21}
 
 ### Added
 - {SPEC-20260421-001}: JPY currency support in Money value object
@@ -266,6 +333,8 @@ Example entry:
 
 ---
 
+<!-- dflow-generated: git-principles-canonical END -->
+
 ## 6. AI Collaboration Rules (Project Policy)
 
 Three categories:

package/templates/brownfield/scaffolding/Git-principles-trunk.md

@@ -22,6 +22,8 @@ and long-lived release branches.
 
 ---
 
+<!-- dflow-generated: git-principles-canonical START -->
+
 ## 1. Branch Structure
 
 | Branch | Naming | Cut from | Merges to |
@@ -35,6 +37,17 @@ happens on short-lived feature / bugfix branches cut from `main` and
 merged back into `main` quickly (ideally within a day, always
 within a week).
 
+A **`bugfix/{BUG-ID}-{slug}`** branch is the same shape as a feature branch and
+follows the same topology — cut from the same base, pushed the same way,
+integrated the same way, and **closed out the same way**. It is used when a
+defect owns its own host rather than being picked up by a feature already in
+flight. Its host is a **minimal (zero-phase) host**, so it carries no
+phase-spec: the SPEC-ID lives in the directory name while the branch name
+carries the BUG-NUMBER, and the host `_index.md` `branch:` field is
+authoritative for both. Closeout is not optional because the branch prefix
+differs — `/dflow:finish-feature` runs and the directory is archived to
+`completed/` before the branch merges, exactly as for `feature/`.
+
 The `feature/{SPEC-ID}-{slug}` pattern is a **Dflow requirement** (not
 a trunk-based requirement). It ties each feature branch to its
 corresponding `dflow/specs/features/active/{SPEC-ID}-{slug}/` directory.
@@ -76,8 +89,8 @@ Commits must tie back to a SPEC-ID:
 
 ### Conventional Commits style (recommended, optional)
 
-This project {does / does not} require Conventional Commits. When
-adopted, the format is:
+Conventional Commits is optional. **Record whether this project requires it
+in § 6, under "Commit and merge choices".** When adopted, the format is:
 
 ```
 {type}({scope}): {short description}
@@ -103,9 +116,9 @@ Example: `feat(expense): add JPY currency support` with
 ## 3. Merge Strategy (Project Chooses)
 
 Trunk-based strategies typically pick **one** merge style and stick to
-it. This project uses: **{squash | rebase | fast-forward}**. Delete
-the two unused options once decided, or keep all three in the table
-and circle the chosen one.
+it. The table below gives the trade-offs; **record this project's choice
+in § 6, under "Commit and merge choices"** — that section is yours, this
+one is not.
 
 | Strategy | How the feature lands on `main` | When to prefer |
 |----------|--------------------------------|----------------|
@@ -120,7 +133,10 @@ and circle the chosen one.
       justification in the spec's notes section)
 - [ ] `_index.md` status reflects the current work (Phase Specs row
       updated, `Resume Pointer` refreshed if the commit reaches a meaningful
-      checkpoint)
+      checkpoint). A **minimal (zero-phase) host** has no Phase Specs row to
+      update — its record is the Lightweight Changes row, and that row must
+      already be written **before** this commit, not after it. Refresh the
+      Resume Pointer as usual.
 
 ### Gate Checks — Before merging a feature PR to `main`
 
@@ -136,6 +152,23 @@ and circle the chosen one.
 - [ ] CI green
 - [ ] PR has at least one review approval
 
+> **Minimal (zero-phase) host.** The items about this host's own record —
+> `/dflow:finish-feature` having run, `_index.md` status `completed`, and the
+> archival move — apply **unchanged**: they are what stops a host merging with
+> its record still open. Every item naming a **Domain or bounded-context
+> artifact** applies only to what this change **actually touched**: a **no-BC**
+> host has no context to sync or document, a **T3** does no Domain work at all,
+> and a **baseline capture** wrote Domain documents directly rather than syncing
+> to them — so for those they read N/A. **Bounded-context-scoped only** —
+> `glossary.md` and `migration/tech-debt.md` belong to no bounded context, stay
+> in a no-BC host's sweep, and are a baseline capture's own capture
+> destinations, so they are **not** N/A for either. **Code invariants are not
+> artifacts** — the items here that state a rule about the **source** rather
+> than name a document to update are **never N/A**: they hold for any change
+> that touches code at all, and a host wrongly claiming to be no-BC is exactly
+> what they catch. Record the N/A; do not create a context, a Domain document,
+> or a BR row to tick a box.
+
 ---
 
 ## 4. Integration Commit Message Conventions
@@ -170,6 +203,31 @@ Related BR-IDs:
 Related SPEC-IDs: {SPEC-ID}{, follow-up SPEC-IDs if any}
 ```
 
+**Zero-phase (minimal host) form.** A minimal host has no phases and may have
+no bounded context, so its Change Scope block carries the values that are
+actually true rather than padded ones:
+
+```
+Change Scope:
+- BC: none                          # or the real context, when the change has one
+- Phase Count: 0
+- Lightweight Changes: 1 T2 + 0 T3  # at least one row, always
+
+Related BR-IDs: {empty, or the per-family no-BR marker this change carries}
+```
+
+`none` and `0` are the honest values here, not placeholders waiting to be
+filled. **`Related BR-IDs` is the exception — never force it to `none`.**
+It reports what this change's own record carries, not what was synced, so it
+takes the same values a BC-bearing host would: empty, or the per-family no-BR
+marker when the T2 carries one. Writing `none` there erases the marker the
+zero-phase shape requires (`references/finish-feature-flow.md` Step 5 states
+the rule, and a baseline host leaves the field empty). A minimal host that genuinely touches a bounded context reports that
+context and its real BR delta exactly as a phase-bearing feature would — the
+zero is the **phase count**, not the significance. A **baseline capture** is
+the one variant that always reports a real `BC:` — capturing it is the whole
+point of the host.
+
 Example:
 
 ```
@@ -208,11 +266,17 @@ losing the feature-level summary.
 
 ### 4.3 Fast-forward (feature has exactly 1 commit)
 
-If the entire feature was a single commit (common for T2 / T3-only
-features or minimal features), fast-forward is fine. Use the commit
+If the entire feature was a single commit (a hosted T2 / T3 whose work and
+record landed together), fast-forward is fine. Use the commit
 message format from § 4.1 (squash) for that single commit — it already
 reads as the feature's single narrative.
 
+**A minimal (zero-phase) host is never this case.** It records **exactly two**
+commits — the implementation (or `spec-baseline`) checkpoint, then the closeout
+commit that carries the archival `git mv` — so it does not arrive here with
+one. A minimal host showing a single commit has not closed out: run
+`/dflow:finish-feature` first rather than fast-forwarding it as it stands.
+
 ```bash
 git checkout main
 git pull --ff-only origin main
@@ -244,6 +308,8 @@ style.
 
 ---
 
+<!-- dflow-generated: git-principles-canonical END -->
+
 ## 6. AI Collaboration Rules (Project Policy)
 
 Three categories:
@@ -292,6 +358,14 @@ can always decline. If your team also wants vendor attribution, appending the
 assistant's documented line (e.g. `Co-Authored-By: Claude
 <noreply@anthropic.com>`) is an independent, optional convention on top.
 
+### Commit and merge choices
+
+Dflow does not choose these for you; §§ 2-3 give the trade-offs. Record what
+this project settled on:
+
+- **Conventional Commits**: {required / not required — fill in}
+- **Merge strategy**: {squash / rebase / fast-forward — fill in}
+
 ---
 
 ## 7. CI / CD

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