dflow-sdd-ddd 0.15.0 → 0.16.0

package/templates/brownfield/references/pr-review-checklist.md

@@ -162,7 +162,18 @@ skip one and the boundary is a hole rather than a division of labour.
       checkpoint 1 and closeout. A third, typically a host opened in its own
       commit before the work landed, breaks the two-commit lifecycle while
       every closeout check still passes, because those read only the hashes
-      the record points at. **This count applies to a minimal host only**: a
+      the record points at. A third that comes **after** checkpoint 1 and
+      changes only the host's record text — no implementation path, no new
+      host file — may instead be a correction committed on its own once
+      checkpoint 1 was pushed (`references/finish-feature-record-correction.md`
+      sends the developer that way and asks for it to be named in the PR
+      description). Report which it is: the count still fails, and
+      accepting a correction commit is your call after reading its full
+      diff and the PR description. A correction that touches only a record
+      outside this directory — a baseline capture's document, a follow-up's
+      original `_index.md` — is not in this walk; the PR description is where
+      it is named.
+      **This count applies to a minimal host only**: a
       phase-bearing feature has no fixed number of host commits, so there is
       nothing to count there and this item is N/A.
       This is also where closeout's minimal-host **selector** boundary is
@@ -175,9 +186,23 @@ skip one and the boundary is a hole rather than a division of labour.
       so the developer asserts it and cites what the claim rests on —
       `hotfix-identity:` beside `hotfix-branch:` in a **T2**'s
       lightweight-spec frontmatter, or in the row Description for a **T3**.
-      **Open that source** — PR, incident, or tracker — and confirm it names
-      this fix and this commit. Closeout already checked that a citation is
-      *present*; only review can check that it *matches*.
+      **Open that source** — PR, incident, or tracker — and confirm that it
+      names **this fix** and the recorded commit: one of the fix's own
+      commits, or the squash commit when the fix was squashed
+      (`references/modify-existing-post-hoc-hotfix.md` item 3). A fix merged
+      without a PR is identified by the source and the base branch's history
+      instead — the hotfix branch's name or the source's number in commit
+      messages.
+      **When the fix landed as a copy** — a rebase merge or a cherry-pick —
+      the recorded commit is that copy, and the source may not name it. Git
+      cannot prove that one commit is a copy of another: ancestry does not
+      follow copies, and patch comparison (`git cherry`, `git patch-id`)
+      cannot tell apart two changes that differ only in whitespace. A
+      `(cherry picked from commit …)` line or a matching subject is a clue,
+      not proof — settle it with the author from the source, and do not
+      report the identity as confirmed from command output alone.
+      Closeout already checked that a citation is *present*; only review can
+      check that it *matches*.
 - [ ] **Hosted `Commit` cell identity — confirm each hash is *that row's own*
       implementation commit** (phase-bearing host only). `finish-feature-flow.md`
       Step 4 instruction 1 orders the value ("each row's own implementation

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

@@ -126,7 +126,11 @@ 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.
+that is already on the mainline. The hash it records is the hotfix's own
+commit, **not** the tagged merge commit on `main` (step 3): the record is
+never a merge commit, and step 4 merges the hotfix **branch**, so the tagged
+commit does not come into `develop` with it.
+`references/modify-existing-post-hoc-hotfix.md` item 3 has the rule.
 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
@@ -185,8 +189,12 @@ before making key Git operations:
 
 ### Before merging a feature branch to `develop`
 
-- [ ] `/dflow:finish-feature` has run (or the equivalent Step 8.4
-      manual archival is complete)
+- [ ] **Closeout complete**: `/dflow:finish-feature` has announced closeout
+      complete for this host — its Local-closeout gate is satisfied (the
+      closeout commit landed and passed post-commit verification) and, if
+      the host carries `follow-up-of`, the Step 6 tracking commit has also
+      landed and been verified. `status: completed` or a directory already
+      under `completed/` does not show this on its own.
 - [ ] `_index.md` status = `completed`, feature directory moved to
       `dflow/specs/features/completed/` via `git mv`
 - [ ] BC layer synced: `dflow/specs/domain/{context}/rules.md` and
@@ -196,8 +204,8 @@ before making key Git operations:
 - [ ] 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
+> **Closeout complete**, `_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,

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

@@ -140,8 +140,12 @@ one is not.
 
 ### Gate Checks — Before merging a feature PR to `main`
 
-- [ ] `/dflow:finish-feature` has run (or the equivalent Step 8.4
-      manual archival is complete)
+- [ ] **Closeout complete**: `/dflow:finish-feature` has announced closeout
+      complete for this host — its Local-closeout gate is satisfied (the
+      closeout commit landed and passed post-commit verification) and, if
+      the host carries `follow-up-of`, the Step 6 tracking commit has also
+      landed and been verified. `status: completed` or a directory already
+      under `completed/` does not show this on its own.
 - [ ] `_index.md` status = `completed`, feature directory moved to
       `dflow/specs/features/completed/` via `git mv`
 - [ ] BC layer synced: `dflow/specs/domain/{context}/rules.md` and
@@ -153,8 +157,8 @@ one is not.
 - [ ] 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
+> **Closeout complete**, `_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,

package/templates/brownfield/templates/_index.md

@@ -6,7 +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 -->
+<!-- dflow-shape: brownfield/_index.md 3 — keep this line: dflow doctor reads it -->
 
 <!--
 Template note (for AI):
@@ -133,8 +133,8 @@ references/new-phase-flow.md。有衝突時以那些檔為準。
 > Description 另外標明這是 hotfix，並寫出識別依據（PR／incident／tracker 編號）
 > ——沒有依據的 hash 會擋下 closeout。此時路徑指的是**已合併的那個 hotfix**
 > 碰到的檔案；本列 `Commit` 欄填的是**補文件那個 commit** 的 hash，不是 hotfix
-> 的 hash（後者記在 Checkpoint Log 的 `reconciled (...)` 列）。兩者來源不同，
-> 不可互填。
+> 的 hash（後者記在 Checkpoint Log 的 `reconciled (...)` 列，記哪一顆見
+> references/modify-existing-post-hoc-hotfix.md item 3）。兩者來源不同，不可互填。
 >
 > Tier 判準見 AI-AGENT-GUIDE.md § Ceremony Scaling 的 ordered cascade（步驟 0–4，先命中者勝）。
 
@@ -190,8 +190,9 @@ references/new-phase-flow.md。有衝突時以那些檔為準。
 > 生命週期 checkpoint 的 commit / skip 時間線（讓三週後回溯不必手動重建）。
 > 每個 checkpoint 無論 commit 或 skip 都記一列。Tier 決定 checkpoint 數：
 > T1 三點（spec 完 / impl 完 / closeout）、T2 兩點（spec+impl 合併 / closeout）、
-> T3 單一實作 commit（其 inline row 與本列的 hash 由 host 的下一個 commit 一併帶進；
+> T3 單一實作 commit（記它 hash 的那幾格由 host 的下一個 commit 帶進；
 > host 若沒有後續 commit，允許一個只動 ledger 的 tracking commit 收尾，該 commit 不另成列）。
+> `modify-existing` 的那一顆在更新文件那一步（Step 6）做完之後才 commit，連同那一步寫的文件一起帶。
 > ⚠ **上面那些「點」在本表 `Checkpoint` 欄各有固定的字面值**：spec 里程碑寫
 > **`spec-baseline`**、實作寫 **`implementation`**、關帳寫 **`closeout`**（下表的
 > `spec-baseline` / `implementation` / `closeout` 三列就是這幾個值；表中另有一列
@@ -204,17 +205,18 @@ references/new-phase-flow.md。有衝突時以那些檔為準。
 > **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**
+> 沒有別的 commit 可以收攏 row，所以**不分 tier 一律記兩個 checkpoint**
 > （implementation——baseline capture 記 `spec-baseline`——然後 closeout），
-> 而且 T3 的 inline row 要**寫進 checkpoint 1 本身**、不是等下一個 commit 帶
-> 進來。上一段「T3 單一實作 commit ／ 由下一個 commit 帶進」講的是**掛在既有
-> feature 底下的** T3，不適用於 minimal host。
+> 而且每一列（T3 的 inline row 也一樣）都要**寫進 checkpoint 1 本身**；之後只補記
+> checkpoint 1 hash 的那幾格，搭 closeout 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` 欄）。完整詞彙見
+> 括號裡是**那個修正的 commit**（記哪一顆見
+> references/modify-existing-post-hoc-hotfix.md item 3），不是本 host 補文件那個
+> commit 的 hash（後者填在 Lightweight Changes 該列的 `Commit` 欄）。完整詞彙見
 > references/git-integration.md § Commit Checkpoints, Branch Gate & AI Commits。
 >
 > **`branch-override` 是紀錄列，不是生命週期 checkpoint。** 在 branch gate 選了
@@ -229,9 +231,11 @@ references/new-phase-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；
+> **checkpoint 的 commit 不可能帶著自己的 hash**：記它 hash 的那幾格（本表那一列的
+> `committed ({hash})`、Lightweight Changes 填同一個 hash 的 `Commit` 格）一律在 commit
+> 實際成功後才寫，搭 host 的**下一個** commit；pre-commit hook reject 或 commit
+> 失敗記 `failed`、不寫假 hash。**例外：closeout 列不填 hash**——這個 host 之後再也
+> 沒有 commit 會帶上它，所以該列於 commit 前寫入、隨歸檔目錄一起進 commit；
 > 溯源用 `git log -1 -- completed/{SPEC-ID}-{slug}` 或選配的
 > `Dflow-Checkpoint` trailer（見 references/git-integration.md）。
 >

package/templates/common/references/flow-rationale-registry.md

@@ -63,9 +63,9 @@ R-FF-CURSOR-02: [finish-feature-flow.md · Step 4 · "The `git mv` and this writ
 
 R-FF-GITMV-01: [finish-feature-flow.md · Step 4 · "`git mv` is mandatory — never use plain `mv` + `git add`"] This preserves git's directory rename detection so `git log --follow` / `git blame` / PR diff quality stays intact across the move.
 
-R-FF-SWEEPKEY-01: [gf · finish-feature-flow.md · Step 4 instruction 2 · "Key it on the flow that produced the change, never on the flow that opened the host"] Those differ, and keying on the host is how the deadlock came back: `modify-existing-flow.md` Step 1.6 opens a **phase-bearing** host for a T1 follow-up, and Step 5.4 puts a T1 new-phase or a T2 lightweight *inside* a host opened by `/dflow:new-feature` — each of those runs Step 5.3 as its own sweep. Ask "which flow opened this host" and a hosted **T2** on a phase-bearing **no-BC** host has no arm at all: half (a) is empty because Step 3 is skipped, and the `glossary.md` rename its Step 5.3 made belongs to a sweep the question refused to look at. Unstaged it fails the clean-tree item; staged it is attributable to nothing. Deriving from *this change's* flow is the fix — not widening the set to "anything dirty".
+R-FF-SWEEPKEY-01: [gf · finish-feature-flow.md · Step 4 instruction 2 · "Key it on the flow that produced the change, never on the flow that opened the host"] Those differ, and keying on the host is how the deadlock came back: `modify-existing-flow.md` Step 1.6 opens a **phase-bearing** host for a T1 follow-up, and Step 5.4 puts a T1 new-phase or a T2 lightweight *inside* a host opened by `/dflow:new-feature` — each of those runs Step 5.3 as its own sweep. Ask "which flow opened this host" and a hosted **T2** on a phase-bearing **no-BC** host has no arm at all: half (a) is empty because Step 3 is skipped, and a `glossary.md` correction to its Step 5.3 sweep, made after its checkpoint 1, belongs to a sweep the question refused to look at. Unstaged it fails the clean-tree item; staged it is attributable to nothing. Deriving from *this change's* flow is the fix — not widening the set to "anything dirty".
 
-R-FF-SWEEPKEY-01: [bf · finish-feature-flow.md · Step 4 instruction 2 · "Key it on the flow that produced the change, never on the flow that opened the host"] Those differ, and keying on the host is how the deadlock came back: `modify-existing-flow.md` Step 1.6 opens a **phase-bearing** host for a T1 follow-up, and Step 6.4 puts a T1 new-phase or a T2 lightweight *inside* a host opened by `/dflow:new-feature` — each of those runs Step 6.3 as its own sweep. Ask "which flow opened this host" and a hosted **T2** on a phase-bearing **no-BC** host has no arm at all: half (a) is empty because Step 3 is skipped, and the `glossary.md` rename its Step 6.3 made belongs to a sweep the question refused to look at. Unstaged it fails the clean-tree item; staged it is attributable to nothing. Deriving from *this change's* flow is the fix — not widening the set to "anything dirty".
+R-FF-SWEEPKEY-01: [bf · finish-feature-flow.md · Step 4 instruction 2 · "Key it on the flow that produced the change, never on the flow that opened the host"] Those differ, and keying on the host is how the deadlock came back: `modify-existing-flow.md` Step 1.6 opens a **phase-bearing** host for a T1 follow-up, and Step 6.4 puts a T1 new-phase or a T2 lightweight *inside* a host opened by `/dflow:new-feature` — each of those runs Step 6.3 as its own sweep. Ask "which flow opened this host" and a hosted **T2** on a phase-bearing **no-BC** host has no arm at all: half (a) is empty because Step 3 is skipped, and a `glossary.md` correction to its Step 6.3 sweep, made after its checkpoint 1, belongs to a sweep the question refused to look at. Unstaged it fails the clean-tree item; staged it is attributable to nothing. Deriving from *this change's* flow is the fix — not widening the set to "anything dirty".
 
 R-FF-SWEEPKEY-02: [finish-feature-flow.md · Step 4 instruction 2 · "do not go looking for a list that host never produced"] ⚠ Keying this on the minimal-host allow-list (`finish-feature-minimal-host.md`) is what deadlocked the one shape where both halves are empty: a **phase-bearing, no-BC** host that swept a global document has nothing from Step 3 *and* no Step 1 allow-list, while this instruction still requires the delta staged and the post-commit path check would then reject it as unpermitted — two mandatory requirements that could not both be met.
 
@@ -95,7 +95,7 @@ R-FF-INFLIGHT-01: [finish-feature-flow.md · Step 5 · "In-flight reminder"] Sur
 
 R-FF-COMMITCELL-01: [finish-feature-minimal-host.md · Step 1 · "Do not collapse the middle case into the first"] it is the one that reads as *filled* to every rule written against empty / non-empty, which is exactly why it survives elsewhere.
 
-R-FF-COMMITCELL-02: [finish-feature-minimal-host.md · Step 1 · "Deliberately not run on a phase-bearing host"] a hosted T3's row rides the host's *next* commit (`references/git-integration.md` § Commit checkpoints), and nothing requires a hosted row to declare implementation paths — so (c) has no defined input there, and demanding it would reject every hosted T3.
+R-FF-COMMITCELL-02: [finish-feature-minimal-host.md · Step 1 · "Deliberately not run on a phase-bearing host"] a hosted T3's row is not asserted against any one commit — only the cells holding its hash are placed, on the host's *next* commit (`references/git-integration.md` § Commit checkpoints) — and nothing requires a hosted row to declare implementation paths — so (c) has no defined input there, and demanding it would reject every hosted T3.
 
 R-FF-BASELINECAP-01: [bf · finish-feature-minimal-host.md · Step 1 · "a `spec-baseline` checkpoint and a `Tier = baseline` row imply each other"] `modify-existing-flow.md` Step 1.7 states the contract: a baseline capture is observation-only, *there is no implementation work*, which is why its checkpoint is not named `implementation`. (1) and (2) alone are the ledger talking about itself; (3) is what makes the claim true of the commit.
 
@@ -105,19 +105,35 @@ R-FF-CKPTCOUNT-02: [finish-feature-minimal-host.md · Step 1 · "the Checkpoint
 
 R-FF-FOLLOWUP-01: [finish-feature-minimal-host.md · Step 1 · "the reverse link was opened, not only closed"] Decidable from one commit and one blob per original, so it stays inside closeout's remit.
 
+R-FF-RECONCILE-01: [finish-feature-minimal-host.md · Step 1 · "Minimal host, hotfix post-hoc only", (c) "touches **at least one** of the implementation paths"] The recorded commit is one of the fix's own commits, or the commit it landed as on the base branch (`modify-existing-post-hoc-hotfix.md` item 3), and a fix made of several commits has no single commit carrying all of it: the record names the last of them that touches a declared path. Requiring every declared path would block that legitimate record. The check is a plausibility test — identity is confirmed by `pr-review-checklist.md` — and "at least one" still rejects a commit unrelated to the declaration. The normal minimal host's "checkpoint 1 is *one* commit" check keeps asking for the declared paths without that qualifier, because there the commit *is* the implementation.
+
+R-FF-RECORDFIX-01: [finish-feature-minimal-host.md · Step 1 · "Checkpoint 1's own record, corrected after checkpoint 1"] The closeout commit cannot take the correction: its closed list admits only what a flow step writes after checkpoint 1, and this is checkpoint 1's own content. So the correction goes into checkpoint 1 itself (an amend) or, once checkpoint 1 is pushed, into a commit of its own that review reports as a departure from the two-commit lifecycle — there is no declared "maintenance" row that makes a third commit legitimate. Such a row would let any third commit through on a label, the stray host-open commit the whole-history count exists to catch included, and a reviewer would still have to judge it.
+
 R-FF-SUMMARY-01: [finish-feature-minimal-host.md · Step 5 · "Zero-phase minimal host — exact fields", on a no-BC host's `Related BR-IDs`] Forcing `none` here would erase a marker the approved zero-phase shape requires.
 
+## finish-feature-record-correction.md
+
+R-FF-RECORDFIX-02: [finish-feature-record-correction.md · "Not pushed, and checkpoint 1 is `HEAD`"] `git commit --amend` rewrites whatever commit is on top; with a later commit there, the amend would miss checkpoint 1 and leave its old hash an ancestor, so hash evidence (b) would no longer catch an entry nobody refilled. The entries holding checkpoint 1's hash are set back to checkpoint 1's state before staging because a hash on the same line as the correction, or on a neighbouring row — a T3 row's text beside its `Commit` cell, a compound host's next row — leaves `git add -p` a hunk it cannot split.
+
 ## init-project-flow.md
 
 R-INIT-DEFERRED-01: [init-project-flow.md · Step 3.1 · "is NOT generated here", both bullets] Init creates neither a per-context `behavior.md` nor either `analysis.md`: an empty file created ahead of its content becomes a stale placeholder.
 
 ## modify-existing-flow.md
 
+R-ME-CKPT-01: [gf · modify-existing-flow.md · Step 4 → Step 5 gate · "checkpoint 1 is offered at the end of Step 5"] Checkpoint 1 waits for the end of the documentation step so that one commit carries the change and the record that step writes: 5.1's verification finds a gap before anything is committed, not after; the documentation the developer confirmed in 5.2 does not sit uncommitted until closeout, which can be weeks away; and a T2 keeps the two commits its tier promises instead of a third, documentation-only one — which on a minimal host is a commit `pr-review-checklist.md`'s two-commit count flags.
+
+R-ME-CKPT-01: [bf · modify-existing-flow.md · Step 5 → Step 6 gate · "checkpoint 1 is offered at the end of Step 6"] Checkpoint 1 waits for the end of the artifact step so that one commit carries the change and the record that step writes: 6.1's verification finds a gap before anything is committed, not after; the documentation the developer confirmed in 6.2 does not sit uncommitted until closeout, which can be weeks away; and a T2 keeps the two commits its tier promises instead of a third, documentation-only one — which on a minimal host is a commit `pr-review-checklist.md`'s two-commit count flags.
+
 R-ME-BASELINE-01: [bf · modify-existing-flow.md · Step 2 · "Systematic Baseline Capture"] Baseline capture looks for system-level knowledge and records it in `analysis.md`, even though it runs only when the feature being modified has no prior spec: it is how a project that adopts Dflow midway gets its existing system into `analysis.md` in bulk, rather than one entry at a time. Every other entry point only records what the change in hand happens to touch; the observation-only route in Part A records without changing anything, but only what that observation reached.
 
+## new-feature-flow.md
+
+R-NF-PHASEDONE-01: [new-feature-flow.md · Step 8 · "8.4 Phase completion and handoff"] § 8.4 reconciles the Current BR Snapshot before handing off because `/dflow:finish-feature` Step 3 syncs the Snapshot into the bounded context as it stands: a Snapshot still holding the rule text planned at Step 4 would overwrite what § 8.3 wrote from the implementation. § 8.4 writes its own four-item list rather than pointing at `new-phase-flow.md` Step 7 because a first phase differs from a later one: its rules are in the phase-spec's Business Rules, not in a Delta; the task list is already handled by § 8.1 and § 8.2, while Step 7 keeps it; and § 8.3 has already synced the bounded context, which Step 7 leaves to closeout.
+
 ## new-phase-flow.md
 
-R-NP-ANALYSIS-01: [new-phase-flow.md · Step 2 · "System-level knowledge?"] Step 2 records into `analysis.md` on the spot rather than leaving it to closeout, because deferring needs two things this flow does not have: somewhere to hold the answer until closeout (the phase-spec template has no section for it), and a closeout step that always runs (a host with no bounded context skips `/dflow:finish-feature` Step 3 entirely). Each track's Step 7 carves these two paths out of its "remain `/dflow:finish-feature` responsibilities" sentence for the same reason. Step 6 re-checks what Step 2 recorded - what the phase was to add or change against what it built, what Step 2 uncovered in the existing system against the system as it now stands, since knowledge Step 2 uncovered was true before the phase began and does not stop being true because the phase built nothing for it - instead of leaving that to closeout as well: no closeout step is sure to reach the entry (`/dflow:new-feature` § 8.4 archives without `/dflow:finish-feature`), and by then a checkpoint has usually committed it, so no diff would show it.
+R-NP-ANALYSIS-01: [new-phase-flow.md · Step 2 · "System-level knowledge?"] Step 2 records into `analysis.md` on the spot rather than leaving it to closeout, because deferring needs two things this flow does not have: somewhere to hold the answer until closeout (the phase-spec template has no section for it), and a closeout step that always runs (a host with no bounded context skips `/dflow:finish-feature` Step 3 entirely). Each track's Step 7 carves these two paths out of its "remain `/dflow:finish-feature` responsibilities" sentence for the same reason. Step 6 re-checks what Step 2 recorded - what the phase was to add or change against what it built, what Step 2 uncovered in the existing system against the system as it now stands, since knowledge Step 2 uncovered was true before the phase began and does not stop being true because the phase built nothing for it - instead of leaving that to closeout as well: no closeout step is sure to reach the entry (a host with no bounded context skips `/dflow:finish-feature` Step 3 entirely), and by then a checkpoint has usually committed it, so no diff would show it.
 
 ## templates/analysis.md
 

package/templates/greenfield/references/finish-feature-flow.md

@@ -26,9 +26,10 @@ state, archives the feature directory, and emits a Git-strategy-neutral
   stance — the AI helps at natural checkpoints, you keep the final say.
 - The BC-layer sync in Step 3 **reuses the existing documentation-sync
   mechanism** from `new-feature-flow` (§ 8.3) and `modify-existing-flow`
-  (Step 5.3) — it does not introduce a new sync flow. Treat it as "lift
-  that step out of the per-phase checklist and run it once at feature
-  closeout, with the `_index.md` Current BR Snapshot as input."
+  (Step 5.3) — it does not introduce a new sync flow. § 8.3 and Step 5.3
+  sync when the work they record completes; Step 3 runs the same mechanism
+  once more at feature closeout, with the `_index.md` Current BR Snapshot as
+  input.
 
 **Step Gates** in this flow (stop-and-confirm before proceeding):
 - Step 1 → Step 2 (validation passed → flip status)
@@ -163,8 +164,9 @@ Step 4's post-commit verification, and to Step 5's Integration Summary fields.
       none. Decide from the artifact, not from a declaration:
       "the feature is intentionally no-BR" is a claim, and the record is what
       settles it. A classic BR-delta spec carrying ADDED / MODIFIED / RENAMED
-      entries **and** an empty Snapshot means finalization never refreshed it
-      (`modify-existing-flow.md` Step 1.7) and **blocks**.
+      entries **and** an empty Snapshot means the completion checklist never
+      refreshed it (`modify-existing-flow.md` Step 5.3, before checkpoint 1)
+      and **blocks**.
 
 If any check fails:
 > "Cannot finish feature `{SPEC-ID}-{slug}` yet — {N} validation issues
@@ -388,10 +390,10 @@ Deltas are the audit trail. **Cross-reference each hosted lightweight-spec's
 recorded delta the same way** — on any host shape, for the reason above.
 
 > Note: this step does NOT read individual phase-specs to re-derive the BR
-> set — that work was already reconciled by `/dflow:new-phase` Step 7 each
-> time a phase completed. We trust `_index.md` Current BR Snapshot as the
-> feature-level truth here. If the developer finds drift between Snapshot
-> and the phase-specs, fix `_index.md` first, then re-run
+> set. `/dflow:new-feature` § 8.4 and `/dflow:new-phase` Step 7 reconcile the
+> Snapshot when they complete a phase, and we trust `_index.md` Current BR
+> Snapshot as the feature-level truth here. If the developer finds drift
+> between Snapshot and the phase-specs, fix `_index.md` first, then re-run
 > `/dflow:finish-feature`.
 
 Also update `architecture/tech-debt.md` / `models.md` / `glossary.md` /
@@ -494,13 +496,13 @@ Then, in this order:
 
 1. **Record the checkpoint row first.** Write one row in the moved
    `_index.md` Checkpoint Log — `closeout | committed` for Y, `closeout |
-   skipped` for N. The closeout row carries **no commit hash**: the closeout
-   commit cannot contain its own hash. Trace it later via
+   skipped` for N. The closeout row carries **no commit hash**: no later
+   commit of this host carries it. Trace it later via
    `git log -1 -- dflow/specs/features/completed/{SPEC-ID}-{slug}` (or the
-   optional `Dflow-Checkpoint` trailer). The "hash only after success" rule
-   still applies to spec / implementation rows — closeout is the documented
-   exception (see `references/git-integration.md` § Commit Checkpoints,
-   Branch Gate & AI Commits).
+   optional `Dflow-Checkpoint` trailer). On any other checkpoint row, a
+   `committed ({hash})` Result is written after its commit and carried by the
+   host's next commit (see `references/git-integration.md` § Commit
+   Checkpoints, Branch Gate & AI Commits).
    **Backfill any unfilled hosted `Commit` cell in the same edit** — a hosted row
    waits for the host's *next* commit and this is it. **Unfilled means empty *or*
    holding a placeholder** — `{hash}`, `{pending}`, `（待 commit）`, anything that
@@ -534,10 +536,11 @@ Then, in this order:
    `domain/analysis.md`, `architecture/tech-debt.md`) — Step 3 is **skipped
    entirely for a no-BC host**, so this half is empty there; **and**
    **(b)** the **documentation-sweep step of the flow that produced *this
-   change*** — take the paths from that step, not from a list kept here. It runs
-   *after* that flow's implementation checkpoint and *before* closeout, so **that
-   flow** leaves its deltas uncommitted; a later phase's own checkpoints may have
-   committed them since, and staging an already-committed path is a no-op.
+   change*** — take the paths from that step, not from a list kept here. A
+   commit may already have carried them — `modify-existing-flow.md`'s
+   checkpoint 1 carries its own sweep, and a later phase's checkpoint may have
+   carried a `new-feature-flow.md` sweep — and staging an already-committed path
+   is a no-op, so stage them either way.
    Those sweeps reach
    Domain-layer documents under `dflow/specs/domain/`, plus the **global**
    documents `glossary.md`, `domain/analysis.md` and
@@ -575,7 +578,8 @@ Then, in this order:
    admitted. On a **phase-bearing** host there is **no allow-list at all** —
    that check is minimal-host-only and lives in that branch file — so read the
    sweep directly and **do not go looking for a list that host never produced.**
-   Read each delta (`git diff -- {path}`) and scope every one to *this change*;
+   Read each delta (`git diff HEAD -- {path}`, which includes what is already
+   staged) and scope every one to *this change*;
    staging only "what Step 3 wrote" leaves a no-BC host's global delta dirty and
    the post-commit clean-tree check fails.
 3. **Commit (Y) or stop (N).** For Y the AI commits. If a pre-commit hook
@@ -625,10 +629,9 @@ every item:
       only when the baseline became unreadable *during* closeout.
       Step 1 blocks unless every
       spec in the host already reads `status: completed`, so those flips are
-      already **in** the baseline whichever step made them: a **minimal** host's
-      come from `modify-existing-flow.md` Step 1.7's finalization, a
-      **phase-bearing** host's from its phases completing — no phase-bearing
-      host runs Step 1.7, whichever flow opened it. Either way the
+      already **in** the baseline whichever step made them: a lightweight-spec's
+      comes from `modify-existing-flow.md` Step 5.3, a phase-spec's from its
+      phase completing. Either way the
       flips are not differences this check admits; they are part of what it
       compares against. (They are differences only from the *pre-flip* record,
       which is not the baseline.)
@@ -760,8 +763,8 @@ itself, state in the conversation *how* Step 4's post-commit verification
 reached its result — not that it passed, but how it was computed:
 
 1. **The baseline** — the tree Step 1 read, and which step put each spec's
-   `status: completed` flip into it (Step 1.7's finalization on a minimal host;
-   the phases completing on a phase-bearing one, which never runs Step 1.7).
+   `status: completed` flip into it (`modify-existing-flow.md` Step 5.3 for a
+   lightweight-spec; the phase completing for a phase-spec).
 2. **The differences you derived, each with the step that ordered it** —
    Step 2, Step 4's terminal Resume Pointer write, or Step 4 instruction 1. This
    is the set the check *derives* instead of listing, so printing it is what

package/templates/greenfield/references/finish-feature-minimal-host.md

@@ -140,14 +140,16 @@ A `✗` here stops closeout there, on the same terms.
       `Commit` must still name the **same single documentation commit**.
 - [ ] **Minimal host (zero-phase) only** — **nothing that constitutes the change
       itself is still uncommitted.** This is deliberately not "the host
-      directory is clean": **checkpoint 1 carries the change, the closeout
-      commit carries the record the flow writes afterwards.** Checkpoint 1 sits
-      at `modify-existing-flow.md`'s Step 4 → Step 5 gate and holds the change
-      itself — for a **T2** its lightweight-spec plus the implementation source,
-      for a **T3** its `_index.md` row plus the implementation source. What the
-      flow writes *after* that gate — Step 5's completion checklist and Step
-      1.7's "Finalize + close" — is derived record and rides into the closeout
-      commit.
+      directory is clean": **checkpoint 1 carries the change and the record
+      Step 5 writes; the closeout commit carries what the flow writes after
+      checkpoint 1.** Checkpoint 1 is offered at the end of
+      `modify-existing-flow.md`'s Step 5 (§ 5.5) and holds the change itself —
+      for a **T2** its lightweight-spec plus the implementation source, for a
+      **T3** its `_index.md` row plus the implementation source — together with
+      Step 5's completion checklist. What the flow writes *after* checkpoint 1 —
+      Step 1.7's "Finalize + close" — is derived record and rides into the
+      closeout commit, and so may a correction to Step 5's record made after
+      checkpoint 1.
       **A post-hoc host (Step 1.8) inverts the source half, and this is where
       the reconciliation contract is enforced.** Its change is the *already
       merged* hotfix; checkpoint 1 is the **documentation** commit. So that
@@ -187,8 +189,9 @@ A `✗` here stops closeout there, on the same terms.
       to both phase-spec and lightweight-spec"): ticking the tasks this change
       completed and labelling each unchecked one as follow-up (5.1), and — when
       the developer accepted the offer — collapsing or removing the section
-      (5.2). On a minimal host that checklist necessarily runs *after*
-      checkpoint 1, so these edits are uncommitted here by construction;
+      (5.2). That checklist runs before checkpoint 1, so these edits are
+      normally committed already; this admits a correction to them made after
+      checkpoint 1;
       (iii) the Domain-layer documents **this change's Step 5.3 sweep** updates
       — under `dflow/specs/domain/`, plus
       `dflow/specs/architecture/tech-debt.md` — scoped to *this change's*
@@ -200,11 +203,23 @@ A `✗` here stops closeout there, on the same terms.
       documents (`glossary.md`, `domain/analysis.md`,
       `architecture/tech-debt.md`) belong to no bounded context, stay in its
       sweep, and therefore still qualify under (iii).
-      Read each delta (`git diff -- {path}`) — do not infer it from the
-      filename. **The list is closed** — if a later change adds another
+      Read each delta with `git diff HEAD -- {path}` — plain `git diff` hides
+      what is already staged — and do not infer it from the filename.
+      **The list is closed** — if a later change adds another
       finalization field, add it here explicitly; "a host file is dirty" is never
       on its own a reason to pass. (Unrelated work in progress elsewhere is
       fine; say which files you judged unrelated.)
+      **Checkpoint 1's own record, corrected after checkpoint 1, is outside the
+      list** — the spec's content beyond (ii)'s edits, a row's own text, or the
+      reverse-link row a follow-up wrote into its original's `_index.md`. It
+      blocks: the closeout commit does not carry checkpoint 1's content. The
+      dispatch right after this item gives the repair.
+
+**Open `references/finish-feature-record-correction.md` and follow it there.**
+Do this only when the check above blocked on a correction to checkpoint 1's own
+record: the repair depends on where checkpoint 1 stands now, and that file gives
+it for each case. Otherwise go on to the next check.
+
 - [ ] **Minimal host (zero-phase), no-BC only** — **the host did not commit a
       bounded context it does not have.** This file's `nothing that constitutes
       the change itself is still uncommitted` check reads the *working
@@ -273,10 +288,11 @@ A `✗` here stops closeout there, on the same terms.
       assertion.
       The plausibility conditions, all required: the
       `reconciled ({merged-hotfix-hash})` value passes hash evidence — (a) and
-      (b) as usual, and for **(c)** its diff touches the implementation paths
-      the T2 lightweight-spec or the T3 row **declares** (Step 1.7 requires that
-      declaration; an artifact naming none leaves (c) nothing to compare and
-      **blocks** rather than passing vacuously). It must also **differ**
+      (b) as usual, and for **(c)** its diff touches **at least one** of the
+      implementation paths the T2 lightweight-spec or the T3 row **declares**
+      (Step 1.7 requires that declaration; an artifact naming none leaves (c)
+      nothing to compare and **blocks** rather than passing vacuously). It
+      must also **differ**
       from the Lightweight Changes row's documentation-commit hash (different
       provenance; see Step 1.8). The per-tier trace must exist too: a **T2**
       carries `hotfix-branch:` in its lightweight-spec frontmatter, a **T3** has
@@ -288,6 +304,10 @@ A `✗` here stops closeout there, on the same terms.
       for a **T3**. An uncited hash **blocks** closeout: it leaves pr-review
       nothing to confirm against, and this gate is not a substitute for that
       confirmation.
+      **When (b) fails for the `reconciled (...)` hash, do not report only
+      "not an ancestor".** Open `references/modify-existing-post-hoc-hotfix.md`
+      item 6: it names the causes and the repair for each; report the one that
+      is true.
 
 > **Zero-phase minimal host (`modify-existing-flow.md` Step 1.7 / the Step 1.6
 > minimal variant / Step 1.8's post-hoc hotfix, whose linkage resolves to one of

package/templates/greenfield/references/finish-feature-record-correction.md

@@ -0,0 +1,45 @@
+# Correcting Checkpoint 1's Own Record — Greenfield Clean Architecture
+
+Branch file of `references/finish-feature-minimal-host.md`. It **adds** the
+repair for one case that file's working-tree check blocks; it does not restate
+or override anything in that file.
+
+**You are here because** that file's `nothing that constitutes the change
+itself is still uncommitted` check blocked on a correction to checkpoint 1's
+own record — it owns that judgement — or because
+`references/modify-existing-post-hoc-hotfix.md` item 6 found that a post-hoc
+record names a different fix.
+
+The correction belongs in checkpoint 1 itself, and whether it can go there
+depends on where checkpoint 1 stands now. Report the case that is true and give
+the developer its repair:
+
+- **Not pushed, and checkpoint 1 is `HEAD`** (`git rev-parse HEAD` prints
+  checkpoint 1's hash) — first set every entry that holds checkpoint 1's hash
+  back to what checkpoint 1 has (`git show HEAD:{path}`); the refill below
+  writes them again. Then stage the correction alone (in `_index.md`, `git add
+  -p` only its hunk: the Resume Pointer rides the closeout commit), check that
+  `git diff --cached` shows nothing else, and `git commit --amend`. Then write
+  the new hash into every entry that names checkpoint 1 — the Checkpoint Log
+  `committed (...)` and each row's `Commit` cell. An entry left on the old hash
+  fails hash evidence (b).
+- **Not pushed, but a later commit sits on top of checkpoint 1** — stop:
+  rewriting an earlier commit is the developer's to do.
+- **Already pushed** — stop and leave it to the developer. Rewriting a pushed
+  commit is the team's call (refill the entries as above if they do). The other
+  way is to commit the correction on its own: add no Checkpoint Log row for it
+  (a second row blocks), and ask for it to be named in the PR description — it
+  departs from the two-commit lifecycle, and
+  `references/pr-review-checklist.md`'s whole-history item sees it only when it
+  touches this host's directory.
+
+**A post-hoc host's `reconciled (...)`** names the hotfix, not checkpoint 1, so
+refilling after an amend leaves it as it is — **unless the correction changes
+which fix the record names** (`references/modify-existing-post-hoc-hotfix.md`
+item 6, "The record names a different fix"). Then `reconciled (...)` names the
+wrong fix too. Item 3 wrote it before checkpoint 1, so checkpoint 1 carries it:
+correct it to the right fix's commit — the one item 3 says to record — as part
+of the same correction, whichever way that lands (the amend, the developer's
+rewrite, or the correction's own commit). Put that commit through item 6's test
+before closeout continues; that item gives the repair if (b) fails for it as
+well.