dflow-sdd-ddd 0.15.0 → 0.16.0

package/templates/greenfield/references/git-integration.md

@@ -177,7 +177,8 @@ project's decision (GitFlow → `develop`, Trunk / GitHub Flow → `main`).
 ### Commit checkpoints
 
 At lifecycle milestones the AI offers a commit checkpoint, folded into the
-existing Step Gate prompt (it does not add a separate question):
+prompt the flow already shows there — a Step Gate, or the flow's closing
+announcement (it does not add a separate question):
 
 ```
 ✓ {milestone} complete
@@ -188,25 +189,36 @@ existing Step Gate prompt (it does not add a separate question):
 
 Tier sets how many checkpoints a change has: T1 three (spec / implementation /
 closeout), T2 two (spec+implementation merged / closeout), T3 a single commit.
-"T3 = a single commit" means a single **implementation** commit — its hash is
-only knowable afterwards, so the `_index.md` inline row and checkpoint row are
-swept up by the host's **next** commit (more work, or closeout). If the host has
-no next commit scheduled, one ledger-only tracking commit that references the T3
-hash is allowed. It is bookkeeping, not a lifecycle milestone: it adds no
-Checkpoint Log row of its own (unlike closeout, which is a checkpoint and does get
-a row).
+**What a checkpoint carries follows from where its flow offers it.**
+`references/modify-existing-flow.md` offers its checkpoint at the end of its
+artifact step (Step 5), so a T2's merged commit — and a T3's single commit —
+carries the change together with the documentation that step writes.
+`/dflow:new-feature` and `/dflow:new-phase` offer the implementation checkpoint
+at the gate into their completion step, so what that step writes rides the
+host's next commit, whichever that is — for example the next phase's first
+checkpoint, a hosted lightweight change's commit, or closeout.
+"T3 = a single commit" means a single **implementation** commit. On a hosted T3
+the entries that carry its hash ride the host's **next** commit (more work, or
+closeout), as every checkpoint's do (below). If the host has no next commit
+scheduled, one ledger-only tracking commit that references the T3 hash is
+allowed. It is bookkeeping, not a lifecycle milestone: it adds no Checkpoint Log
+row of its own (unlike closeout, which is a checkpoint and does get a row).
 **Minimal host (zero-phase) exception — there, tier does not set the count.**
 On a minimal host (`references/modify-existing-flow.md` Step 1.7 standalone, or
 its Step 1.6 follow-up minimal variant) there is no later host commit for a row
 to ride, so the count is **two for every tier** — implementation, then closeout
-— and a T3's `_index.md` row is written into checkpoint 1 itself instead of
-sweeping into a later commit. Everything above about "T3 = a single commit"
-describes a **hosted** T3, the case where a later host commit exists.
+— and every row, a T3's included, is written into checkpoint 1 itself; only the
+entries that carry checkpoint 1's hash ride the closeout commit. Everything
+above about "T3 = a single commit" describes a **hosted** T3, the case where a
+later host commit exists.
 Whether you choose Y or N, the AI records one row in the feature `_index.md`
 Checkpoint Log — every checkpoint is accounted for (`committed` / `skipped` /
-`failed`), even when no commit happens. A commit hash is written only after the
-commit succeeds; a hook rejection or failed commit is recorded as `failed`
-(never a fake hash).
+`failed`), even when no commit happens.
+**No checkpoint commit can contain its own hash.** The entries that carry a
+checkpoint's hash — its Checkpoint Log Result `committed ({hash})`, and any
+Lightweight Changes `Commit` cell holding that hash — are written after the
+commit succeeds and ride the host's **next** commit. A hook rejection or failed
+commit is recorded as `failed` (never a fake hash).
 **One further Result value — `reconciled ({merged-hotfix-hash})`.** It records
 that this checkpoint documents a change that was **already merged** before any
 ceremony ran, and it is written only on a post-hoc hotfix host's implementation
@@ -215,8 +227,8 @@ belongs to the **merged hotfix**, not to this host's own documentation commit
 that one goes in the Lightweight Changes row's `Commit` cell, and the two have
 different provenance and must never be swapped. On every other host the three
 values above are the whole vocabulary.
-**Exception — the closeout row**: the closeout commit
-cannot contain its own hash, so the closeout row is written before the commit
+**Exception — the closeout row**: no later commit of this host's lifecycle
+carries it, so the closeout row is written before the commit
 as `closeout | committed` with **no hash** (see
 `references/finish-feature-flow.md` Step 4); trace that commit via
 `git log -1 -- dflow/specs/features/completed/{SPEC-ID}-{slug}` or the optional
@@ -339,12 +351,25 @@ heavily enough that git's similarity index dropped below the rename
 threshold; consider using `git mv` for the move, then making content
 edits in a follow-up commit).
 
-### CI / hook automation (future)
+### CI / hook automation
 
-A pre-commit hook can refuse commits where `dflow/specs/features/active/` or
-`dflow/specs/features/completed/` show paired `D` + `A` instead of `R` for
-the same feature directory. Not part of Dflow today, but compatible
-with the rule.
+Dflow ships `dflow check-closeout`, a gate for the closeout commit. For each
+feature directory newly archived to `dflow/specs/features/completed/` it checks
+that `_index.md` and every spec say `status: completed`, that nothing is left
+under `active/`, that the Checkpoint Log has a real `closeout` row reading
+`committed` or `skipped`, and — with `--staged` — that nothing under the
+archived directory is left unstaged; it exits 1 when one fails. A project wires
+it into a pre-commit hook (`--staged`) or a CI job (`--range <base>..<head>`)
+itself — Dflow installs neither. `dflow check-closeout --help` names the page
+with the hook and CI templates. When the hook refuses a closeout commit, handle
+it as `references/finish-feature-flow.md` Step 4 instruction 3 says.
+
+Passing it is not a clean closeout: the post-commit verification in
+`references/finish-feature-flow.md` Step 4 still applies in full.
+
+A hook that refuses paired `D` + `A` instead of `R` for the same feature
+directory is compatible with the `git mv` rule, but it is not part of
+`check-closeout`.
 
 ## Gate Checks by Branch Type
 
@@ -384,8 +409,12 @@ hotfix, or one added later):
 - [ ] `_index.md` Current BR Snapshot has been synced to BC layer
       (`rules.md` / `behavior.md` / `events.md` / `context-map.md`) —
       typically by `/dflow:finish-feature`
-- [ ] Whole feature directory ready to `git mv` to `dflow/specs/features/completed/`
-      (or already moved if `/dflow:finish-feature` ran)
+- [ ] **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.
 - [ ] Domain layer: zero external dependencies
 - [ ] No business logic outside Domain layer
 - [ ] Domain Events documented in events.md
@@ -394,8 +423,8 @@ hotfix, or one added later):
 - [ ] No ORM/serialization attributes on Domain entities
 
 > **On a minimal (zero-phase) host**, split this list by what each item reads.
-> Items about **this host's own record** — `_index.md` status, archival
-> readiness, and the phase-spec check, which passes vacuously on an empty
+> Items about **this host's own record** — `_index.md` status, **Closeout
+> complete**, and the phase-spec check, which passes vacuously on an empty
 > table — apply **unchanged**: they are what stops a host merging with its
 > record still open. Every item that names a **Domain or bounded-context
 > artifact**, the BR-Snapshot sync included, applies only to what this change
@@ -440,10 +469,15 @@ hotfix, or one added later):
 - [ ] Fix approach is noted (which layer the fix belongs in)
 
 ### bugfix/ — Before Merging (Pre-PR / Pre-Integration)
-- [ ] `_index.md` status: `completed`, and the whole feature directory ready to
-      `git mv` to `dflow/specs/features/completed/` (or already moved if
-      `/dflow:finish-feature` ran). A `bugfix/` host closes out exactly like a
-      `feature/` one; an un-closed-out host must not merge.
+- [ ] `_index.md` status: `completed`
+- [ ] **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.
+      A `bugfix/` host closes out exactly like a `feature/` one; an
+      un-closed-out host must not merge.
 - [ ] **The tier's artifact** has the fix documented — a **T2**'s lightweight
       spec, or for a **T3** the host `_index.md` Lightweight Changes row, which
       is its whole record. Do not ask a T3 for a spec file here either: the

package/templates/greenfield/references/modify-existing-flow.md

@@ -286,6 +286,10 @@ drop the T3 evidence.
    recorded, or a stale branch is still carrying it — and it is settled that
    way with the developer, as duplicate / existing work or branch-history
    cleanup. All identifiers are settled here, before the host exists.
+
+   For a **post-hoc hotfix** (Step 1.8), also run the branch-base check in
+   `references/modify-existing-post-hoc-hotfix.md` item 2 here, before step 3
+   creates anything: step 4 cuts from the base branch it settles.
 3. **Create the minimal `_index.md`** from `templates/_index.md` at
    `dflow/specs/features/active/{SPEC-ID}-{slug}/_index.md`, carrying all
    **seven required sections** that template names — the Metadata front
@@ -329,9 +333,10 @@ skips the Domain / DDD-impact work and records an inline row in
 `_index.md` Lightweight Changes — **one row per atomic T3 change**, so a
 compound request records each of them here (see "minimal means zero-phase,
 not one-artifact" above). The **implementation commit is checkpoint
-1** — the Step 4 → Step 5 commit checkpoint records it in the Checkpoint
-Log. (For a **post-hoc** host, Step 4 is skipped and checkpoint 1 is the
-**documentation** commit instead; see Step 1.8 and Step 4's guard.)
+1** — offered at the end of Step 5 (§ 5.5), after Step 5 has written its
+record, and recorded in the Checkpoint Log. (For a **post-hoc** host, Step 4 is
+skipped and checkpoint 1 is the **documentation** commit instead; see Step 1.8
+and Step 4's guard.)
 
 **Every artifact gets a Lightweight Changes row, and every row is written
 *before* checkpoint 1.** A **T3**'s row *is* its whole record; a **T2**'s row is
@@ -341,8 +346,8 @@ implementation paths. The **only** part that may appear afterwards is the
 `Commit` cell, which cannot exist until its commit does: closeout's allow-list
 admits that cell and no other change **to the row**, so a row added after
 checkpoint 1 **blocks**. (The allow-list separately admits the Checkpoint Log
-rows, the Resume Pointer and the Current BR Snapshot — the finalization edits
-this step makes next.)
+rows, the Resume Pointer and the Current BR Snapshot; the first two are what
+"Finalize + close" writes after checkpoint 1.)
 
 **Name the implementation paths in the artifact.** Closeout's evidence checks
 assert that a commit *touches the implementation paths this change describes* —
@@ -353,14 +358,17 @@ diff — enough to compare a commit against. An artifact that declares none
 leaves that check nothing to compare, and finish-feature treats a missing
 declaration as a **block**, not a pass.
 
-**Finalize + close.** Before `/dflow:finish-feature`, run the Step 5
-completion checklist's minimal-host finalization. For **every** T2: set the
-lightweight-spec `status: completed`, record its commit evidence, and advance
-the Resume Pointer to the closeout-ready state. **Only when that T2 is
-BC-bearing**, additionally refresh the host's Current BR Snapshot — a no-BC T2
-has no snapshot to refresh, but still owes the commit evidence and the Resume
-Pointer. A **T3** has no spec file — record its inline row's commit evidence
-and advance the Resume Pointer.
+**Before checkpoint 1 — Step 5 finalizes the record.** Step 5's completion
+checklist runs before checkpoint 1, so everything it writes rides that commit.
+For **every** T2, 5.3 sets the lightweight-spec `status: completed`. **Only when
+that T2 is BC-bearing**, 5.3 also refreshes the host's Current BR Snapshot — a
+no-BC T2 has no snapshot to refresh. A **T3** has no spec file and no snapshot
+to refresh; Step 5 only re-verifies its row.
+
+**Finalize + close — after checkpoint 1.** Before `/dflow:finish-feature`,
+write what cannot exist until checkpoint 1 does, for every tier: each row's
+commit evidence (the two surfaces below) and the Resume Pointer advanced to the
+closeout-ready state.
 
 **Commit evidence goes to two surfaces, always — every row, every tier.** They
 answer different questions, so filling one is never filling the other, and
@@ -377,16 +385,18 @@ The **mode** changes only *which hash* each surface carries:
 
 - **Normal** (T2 or T3) — Checkpoint Log Result `committed ({hash})` and the
   row's `Commit` cell both name **checkpoint 1**, the single commit that
-  carried the artifact and the implementation together. Two cells, one hash;
-  fill both.
+  carried the artifact, the implementation and Step 5's record together. Two
+  cells, one hash; fill both.
 - **Post-hoc hotfix** (Step 1.8; T2 or T3) — the Checkpoint Log Result stays
-  `reconciled ({merged-hotfix-hash})`, **never overwrite it**, while the row's
-  `Commit` cell carries the **documentation** commit's hash. This is the one
-  mode where the two values genuinely differ (Step 1.8 item 4).
+  `reconciled ({merged-hotfix-hash})`, **never overwrite it** — only closeout
+  corrects it, through `references/modify-existing-post-hoc-hotfix.md` item 6 —
+  while the row's `Commit` cell carries the **documentation** commit's hash.
+  This is the one mode where the two values genuinely differ (Step 1.8 item 4).
 
 **A declined checkpoint still owes its hash.** If the developer answered **N**
-at the checkpoint-1 offer and made that commit themselves, the Checkpoint Log
-row was written `skipped` honestly — the AI did not commit — but it is now
+at the checkpoint-1 offer and made that commit themselves — the change together
+with Step 5's record — the Checkpoint Log row was written `skipped` honestly —
+the AI did not commit — but it is now
 **incomplete, not final**: complete it here to `committed ({hash})` with the
 developer's actual hash. **That completion is for a normal checkpoint 1.** On a
 **post-hoc** host the Result stays
@@ -396,7 +406,8 @@ developer's commit lands, never by overwriting the reconciliation hash, which
 records a different commit entirely. A row left reading `skipped` blocks closeout, and
 finish-feature cannot tell "declined then committed" from "never committed" on
 your behalf. The **closeout** row is the deliberate exception — it carries no
-hash at all, because a commit cannot contain its own. Its **Result is still
+hash at all, because no later commit of this host carries it
+(`references/git-integration.md` § Commit checkpoints). Its **Result is still
 read** afterwards — finish-feature's post-commit gate rejects `failed` there. A
 declined closeout stays `skipped` because that value records the declined offer
 honestly, not because the row goes unread.
@@ -569,9 +580,10 @@ Wait for confirmation before entering Step 4.
 > **Post-hoc hotfix (Step 1.8) — skip this step.** The implementation already
 > landed on the mainline before any ceremony ran; that is the whole premise of
 > post-hoc mode, and Step 1.8 item 2 forbids redoing it. There is nothing to
-> implement here. Go straight to the Step 4 → Step 5 gate and commit
-> **documentation only** — the T2 spec or T3 row plus this host's `_index.md`,
-> and no source. Re-implementing the fix on this branch would satisfy the letter
+> implement here. Go straight to the Step 4 → Step 5 gate and on through Step 5;
+> checkpoint 1 (§ 5.5) then commits **documentation only** — the T2 spec or T3
+> row, this host's `_index.md` and what Step 5 wrote, and no source.
+> Re-implementing the fix on this branch would satisfy the letter
 > of the checkpoint while breaking §8's reconciliation contract, which is why
 > closeout inspects that commit's changed paths.
 
@@ -589,9 +601,7 @@ Even for bug fixes, verify:
 Announce to developer:
 > "Implementation appears complete. Ready to update documentation (spec, models.md, rules.md, events.md, glossary, tech-debt)? `/dflow:next` to proceed."
 
-> Commit checkpoint (per `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI Commits): offer to commit, then record the result in the `_index.md` Checkpoint Log. Tier sets the count — T2 commits the merged spec+implementation here (closeout is the second checkpoint); T3 is a single implementation commit, and its `_index.md` rows ride along on the host's next commit (see `references/git-integration.md` § Commit checkpoints). **Minimal host exception (Step 1.7 standalone *and* the Step 1.6 follow-up variant)**: a minimal host has no later host commit for a T3 row to ride along on, so **the row rides checkpoint 1 itself** — write it into `_index.md` *before* this commit, alongside the implementation, because finish-feature Step 1 reads **checkpoint 1's committed `_index.md`** for it. Only what cannot exist until the commit does — the row's `Commit` cell and the Checkpoint Log Result — is backfilled later and rides the closeout commit. And a minimal host takes a second **closeout** checkpoint too: **every** minimal host records **two** checkpoints (implementation, then closeout), for T3 as well as T2. **Post-hoc hotfix (Step 1.8) — the same two checkpoints, but the first carries no implementation**: the fix is already on the mainline, so checkpoint 1 is the **documentation** commit (spec / row + `_index.md`, no source), and its Checkpoint Log Result is `reconciled ({merged-hotfix-hash})` rather than `committed`. "Commits the merged spec+implementation" above describes a normal host and does **not** apply here.
-
-Wait for confirmation before entering Step 5. This step gate is where the completion checklist is triggered — do not skip.
+Wait for confirmation before entering Step 5. This step gate is where the completion checklist is triggered — do not skip. It offers **no** commit: checkpoint 1 is offered at the end of Step 5 (§ 5.5).
 
 ## Step 5: Update Documentation
 
@@ -632,6 +642,7 @@ Ask these one-by-one.
 > **Table-cell formatting**: keep table cells concise — separate multiple short items with `<br>` (never chain them into one line with ；/; separators), and move long narrative detail out of the cell into a document section (full convention: the formatting comment at each spec doc's head).
 
 - [ ] Update or create the feature / bug spec; set `status: completed` — **T3: N/A** (no spec file exists; the `_index.md` inline row is the record, and the host's own status is not touched)
+- [ ] **BC-bearing T2, on every host** — refresh the host `_index.md` Current BR Snapshot from this spec's final delta (`templates/_index.md` regenerates it when a T2 lightweight-spec is finalized; on a minimal host this is the refresh Step 1.7 places before checkpoint 1). A spec with no BR delta leaves the Snapshot as it is. N/A for a no-BC T2 and a T3
 - [ ] The items below are the Domain sweep — **N/A for a T3**. For a **no-BC change** (one whose host Goals & Scope says it touches no bounded context) the **BC-scoped** items are N/A — everything under `dflow/specs/domain/{context}/` plus `context-map.md`: there is no `{context}` to sweep, and inventing one plants the fiction Step 2's no-BC guard refuses. The **global** documents are *not* covered by that: `glossary.md`, `domain/analysis.md` and `architecture/tech-debt.md` belong to no bounded context, and a no-BC operational T2 can genuinely rename a term, change which roles reach a function, or discover architecture debt — judge those three from the actual change, as always. For a no-BR family T2 only the *BR-derived* items are N/A; run each remaining item where this change actually touches that document (an added event field still lands in `events.md`)
 - [ ] `dflow/specs/domain/{context}/models.md` — Aggregate structure updates
 - [ ] `dflow/specs/domain/{context}/analysis.md` — lifecycles, derived figures or mechanisms no single rule explains this change found or altered, in the owning context's copy, which may not be this host's; any spot this change worked around pending a domain decision, in those or in a rule or unrecorded knowledge that belongs there; and any open row there this change settled (created from `templates/analysis.md` the first time there is something to record; N/A when there is none)
@@ -678,3 +689,7 @@ directory — the closeout `git mv` happens at `/dflow:finish-feature` time
 
 Only announce "change complete" after the appropriate archival step
 above (or the Step 5.3 docs sweep) is done.
+
+### 5.5 Commit checkpoint (checkpoint 1)
+
+> Commit checkpoint (per `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI Commits): fold the offer into the "change complete" announcement, then record the result in the `_index.md` Checkpoint Log. This commit is **checkpoint 1**: it carries the change — the spec or row plus the implementation — **and** everything Steps 2–5 wrote. Tier sets the count — T2 commits the merged spec+implementation here (closeout is the second checkpoint); T3 is a single implementation commit. The entries that carry this commit's hash — the Checkpoint Log Result and each Lightweight Changes `Commit` cell naming it — are written after the commit and ride the host's next commit; on a phase-bearing host, `/dflow:finish-feature` Step 4 backfills any `Commit` cell still unfilled at closeout. **Minimal host exception (Step 1.7 standalone *and* the Step 1.6 follow-up variant)**: a minimal host takes no host commit between checkpoint 1 and closeout, so **every row rides checkpoint 1 itself** — a T3 row included, written into `_index.md` *before* this commit, because finish-feature Step 1 reads **checkpoint 1's committed `_index.md`** for it. Only the entries that carry the hash come later: Step 1.7's "Finalize + close" writes them, and they ride the closeout commit. And a minimal host takes a second **closeout** checkpoint too: **every** minimal host records **two** checkpoints (implementation, then closeout), for T3 as well as T2. **Post-hoc hotfix (Step 1.8) — the same two checkpoints, but the first carries no implementation**: the fix is already on the mainline, so checkpoint 1 is the **documentation** commit (spec / row, `_index.md` and what Step 5 wrote, no source), and its Checkpoint Log Result is `reconciled ({merged-hotfix-hash})` rather than `committed`. "Commits the merged spec+implementation" above describes a normal host and does **not** apply here.

package/templates/greenfield/references/modify-existing-follow-up.md

@@ -87,7 +87,8 @@ hardcoded `feature/` branch). Step 1.7's **step 1 does not apply**: it is the
 standalone-classification gate, and this caller has already been classified as
 a follow-up. Everything Step 1.7 states **after** step 4 *does* apply
 unchanged — every artifact's row written before checkpoint 1, the
-implementation-path declaration, tier-aware "Finalize + close", and the two
+implementation-path declaration, the finalization before checkpoint 1 and
+"Finalize + close" after it, and the two
 commit-evidence surfaces — because finish-feature reads for all of it on a
 follow-up host exactly as on a standalone one. Then record the change's
 artifacts — a T2 lightweight-spec, one

package/templates/greenfield/references/modify-existing-post-hoc-hotfix.md

@@ -32,6 +32,10 @@ If you arrived here with a T1, go back to Part A's routing.
      includes *a related feature that is still in flight* — see above for why
      it cannot be the host.
 
+   Make the choice here, and **act on it only after item 2's branch-base
+   check**: on either route, nothing is opened, linked or cut before that
+   check.
+
    Do not skip this choice. If a feature that was in flight turns out to have
    touched the same code, that is a **merge** question, settled when the
    branches actually meet — see `finish-feature-flow.md` Step 5.
@@ -42,11 +46,69 @@ If you arrived here with a T1, go back to Part A's routing.
    1.6's delegation to it) like any other minimal host — that branch *is* the
    **post-hoc branch** the rest of this step names, and the value `_index.md`
    `branch:` records.
+
+   **Branch-base check — run it before Step 1.7 step 3 creates anything**
+   (on the follow-up route: before Step 1.6 opens the host and writes the
+   reverse link). It settles which base branch this host's branch is cut
+   from. Closeout requires the commit item 3 records to be an ancestor of
+   this branch, so a branch cut from a base that does not contain that commit
+   yet passes every step until closeout and is blocked there. Settle that
+   commit with the developer first (item 3), then:
+   1. Settle the base branch and fetch it. The developer decides which
+      branch is the base — Dflow does not know it, though the project may
+      record it under `_conventions.md` § Git Policy — and it is the branch
+      Step 1.7 step 4 cuts from anyway. `{base-ref}` is that branch's latest
+      ref (for example `origin/develop`). Fetch the remote it belongs to
+      (`git fetch origin` for `origin/develop`; `git fetch --all` when
+      unsure): a bare `git fetch` updates only the default remote, so a base
+      on another remote stays stale and the steps below misjudge it. The fix
+      is merged and pushed by now, and it often reached the base on the
+      server — a PR merge or a squash — that this clone has not fetched yet.
+   2. Run `git cat-file -t {hash}`. It must print `commit`. If it prints
+      anything else or fails, and step 1's fetch failed, the commit may only
+      be missing from this clone: stop, say the check needs the fetch, and
+      run it again once the remote is reachable. Otherwise the hash is
+      mistyped, names an object that is not a commit, or names a commit that
+      remote does not have — stop and ask the developer. Do not guess.
+   3. Run `git show --stat {hash}`. At least one path it lists must be an
+      implementation path this record will declare. If none is, stop and
+      settle the commit with the developer — closeout's (c) would block it.
+      A last commit that touches only tests does this. Then run
+      `git rev-list --parents -n 1 {hash}`: more than two hashes means a
+      merge commit — for example the one a PR page shows as its merged
+      commit. Item 3 never records one, and a merge usually passes the path
+      check above, so stop here and settle the commit with the developer.
+   4. Run `git merge-base --is-ancestor {hash} {base-ref}`:
+      - **Exit `0`** — cut this host's branch from `{base-ref}` at Step 1.7
+        step 4. Do **not** let the new branch track the base: run
+        `git checkout -b {branch} --no-track {base-ref}`, or update the local
+        base branch the way the project normally does and cut from that. A
+        branch that tracks `origin/develop` can, under some push settings,
+        push its documentation commits straight to `develop`.
+      - **Exit `1`** — the fix is not in that base yet. Tell the developer
+        both causes. **The fix has not been merged back yet**: merge it back
+        first (under GitFlow, into `develop`). **The recorded commit is not
+        the one item 3 names**: under a squash or rebase merge, or a
+        cherry-pick into the base, the fix's own commits never reach it —
+        record the commit the fix landed as (item 3).
+        ⚠ Do **not** cut from `main` instead to make the check pass: the
+        documentation branch would carry `main`'s merge commits into
+        `develop` when it merges, and its documents would start from
+        `main`'s older Domain documents and conflict there.
+      - **Any other exit code** — a mistyped ref or a failed command. Stop
+        and show the developer the output.
+      - **If step 1's fetch failed** (offline): exit `0` is still
+        trustworthy — the ref you cut from does contain the commit. Exit `1`
+        may only mean the local ref is behind; treat it as provisional and
+        say so.
 3. **Implementation checkpoint Result = `reconciled ({merged-hotfix-hash})`.**
    In the host's Checkpoint Log the implementation row's Result is
    `reconciled (...)` — the value meaning "this checkpoint documents an
-   already-merged change" — carrying the merged hotfix commit's hash. It sits
-   alongside the usual `committed` / `skipped` / `failed` Results (see
+   already-merged change" — carrying the hash of **one of the fix's own
+   commits**, or of **the commit the fix landed as** when it reached the base
+   branch by a squash, a rebase or a cherry-pick — a commit on the base
+   branch this host's branch is cut from (item 2).
+   It sits alongside the usual `committed` / `skipped` / `failed` Results (see
    `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI
    Commits). That hash belongs to the **hotfix**, so it is **not** evidence
    that this host's own first commit landed — the documentation work still owes
@@ -54,12 +116,27 @@ If you arrived here with a T1, go back to Part A's routing.
    Committing the documentation together with closeout collapses the host to
    one commit and fails finish-feature Step 1.
 
+   **Which commit that is depends on how the fix reached the base branch:**
+
+   | The fix reached the base branch by | Record |
+   |---|---|
+   | a merge (under GitFlow, merging the hotfix branch back into `develop`) or a fast-forward | the last of **the fix's own commits** that touches a declared implementation path — never a merge commit, and under GitFlow never the tagged merge commit on `main`, which the back-merge does not bring into `develop` |
+   | a squash merge | the squash commit on the base branch |
+   | a rebase merge or a cherry-pick | the last of the fix's commits **as they landed on the base branch** that touches a declared implementation path |
+
+   When the fix's own commits are on the base branch, record one of them even if
+   a copy of the fix got there first. Closeout accepts a commit that touches only
+   some of the declared paths: it asks for at least one. The hotfix branch's own
+   name still goes in `hotfix-branch:` (item 4).
+
    **You are asserting this hash, not deriving it.** Nothing in the repository
    records which commit was the hotfix, so no check in this flow can confirm
    it — finish-feature's reconciliation gate is explicit that it tests
    plausibility only. So state the identity
    and **cite what it rests on**: the PR, incident, or tracker reference that
-   identifies this fix. Record the citation alongside the per-tier trace
+   identifies this fix. **Cite the source, not the hash** — a corrected hash
+   (item 6) then never has to touch the citation. Record the citation
+   alongside the per-tier trace
    (item 4). An **uncited** hash blocks closeout —
    `references/pr-review-checklist.md` is what confirms the identity, and it
    needs something to confirm against.
@@ -80,3 +157,44 @@ If you arrived here with a T1, go back to Part A's routing.
 5. **Branch equality** for the host is asserted against the **post-hoc
    documentation branch** (the `_index.md` `branch:` value), never the deleted
    hotfix branch.
+6. **Closeout: (b) fails on the `reconciled (...)` hash.**
+   `references/finish-feature-minimal-host.md`'s `Minimal host, hotfix
+   post-hoc only` check sends you here. Report which cause it is — never only
+   "not an ancestor" — and give the developer the repair for that cause. First
+   fetch the remote `{base-ref}` belongs to (item 2 step 1) and find the
+   commit item 3 says to record, then test where it is. If the fetch fails, a
+   result that depends on `{base-ref}`, or on a commit this clone does not
+   have, is provisional — say so, as item 2 does:
+   - **It is already on this branch** (`git merge-base --is-ancestor
+     {its-hash} HEAD` exits `0`) — the record names the right fix but the
+     wrong commit — for example the tagged merge commit on `main`. Correct
+     only the Checkpoint Log hash. The citation (item 3 cites the source, not
+     the hash), `hotfix-branch:` and the declared paths stay as they are, so
+     the correction rides the closeout commit — closeout's closed list admits
+     Checkpoint Log rows. Checkpoint 1 is not touched.
+   - **It is on the base branch but not on this branch** (`git merge-base
+     --is-ancestor {its-hash} {base-ref}` exits `0`) — this branch was cut
+     before the fix reached the base, so correcting the hash is not enough.
+     Merge `{base-ref}` into this branch — or, if nothing is pushed yet,
+     rebase this branch onto it and refill every Lightweight Changes row's
+     `Commit` cell — then record that commit. Set closeout's uncommitted
+     finalization edits aside first with `git stash push --include-untracked`
+     (a plain `git stash` leaves newly created files behind), check that
+     `git status --porcelain` prints nothing, and restore them afterwards
+     with `git stash pop`: `git rebase` refuses to run over uncommitted
+     edits, and `git merge` refuses when the base changed the same files. If
+     `git stash pop` reports a conflict — it can when the base changed the
+     same part of a file those edits touch — resolve it before closeout
+     continues.
+   - **It is not on the base branch either** — the fix was never merged back.
+     Merge it back first (under GitFlow, into `develop`), then take the case
+     above.
+   - ⚠ **Never merge `main` or the tag into this branch to make (b) pass.** It
+     lets the wrongly recorded commit pass unchanged, and it carries `main`'s
+     commits into `develop` when this branch merges.
+   - **The record names a different fix** (the citation, the hotfix branch and
+     the declared paths are all wrong) — checkpoint 1's own record is wrong,
+     and closeout cannot repair that. Follow
+     `references/finish-feature-record-correction.md`: it says when
+     checkpoint 1 can be amended and when to stop for the developer, and it
+     covers `reconciled (...)`, which names the wrong fix too.

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

@@ -449,7 +449,7 @@ During implementation, continuously verify:
 **→ Step Gate: Step 7 → Step 8**
 
 Announce to developer:
-> "Implementation appears complete across all four layers. Ready to run the completion checklist (verify against spec, update domain docs + context-map, ensure test coverage, archive the spec)? `/dflow:next` to proceed."
+> "Implementation appears complete across all four layers. Ready to run the completion checklist (verify against spec, update domain docs + context-map, ensure test coverage, complete the phase)? `/dflow:next` to proceed."
 
 > Commit checkpoint (T1 milestone 2 of 3): offer to commit the implementation, then record the result in the `_index.md` Checkpoint Log. Milestone 3 (closeout) is the `/dflow:finish-feature` checkpoint.
 
@@ -507,33 +507,51 @@ Ask these one-by-one; do not dump all six at once.
 - [ ] `dflow/specs/domain/context-map.md` — updated if cross-context interaction was added or changed
 - [ ] `dflow/specs/architecture/tech-debt.md` — tech debt discovered during implementation recorded
 
-### 8.4 Archival
-
-For a single-phase feature, this is the closeout point. If the feature has
-later phases still ahead, this phase is complete but the feature is not —
-don't archive yet; run `/dflow:new-phase` to start the next phase, not
-`/dflow:finish-feature` yet. For a multi-phase feature, the developer
-typically reaches this point at the end of the final phase — at which time
-`/dflow:finish-feature` is the recommended trigger (it bundles steps 8.1 /
-8.2 verification, BC sync, and archival into one explicit ceremony). Either
-path is acceptable; pick the one that matches the developer's habit.
-
-- [ ] `_index.md` `status` field changed to `completed`
-- [ ] All `phase-spec-*.md` files in the feature directory have `status:
-      completed` in their frontmatter
-- [ ] **Whole feature directory** moved from `dflow/specs/features/active/`
-      to `dflow/specs/features/completed/` using `git mv` (preserves rename
-      tracking — see `references/git-integration.md` § "Directory Moves
-      Must Use git mv"):
-      ```
-      git mv dflow/specs/features/active/{SPEC-ID}-{slug} \
-             dflow/specs/features/completed/{SPEC-ID}-{slug}
-      ```
-
-> **Recommended path for multi-phase features**: instead of doing
-> 8.1–8.4 manually at the end of every phase, run `/dflow:finish-feature`
-> once the feature's last phase is complete. It executes the same checks
-> + BC sync + `git mv` + emits an Integration Summary. See
-> `references/finish-feature-flow.md`.
-
-Only announce "feature complete" after 8.4 is done.
+### 8.4 Phase completion and handoff
+
+This step completes the phase and hands the feature on. It does not close the
+feature out: `/dflow:finish-feature` is the only closeout path — it flips the
+`_index.md` `status`, moves the feature directory to `completed/`, and takes
+the closeout commit checkpoint.
+
+**Complete this phase** — all four items, whether or not another phase
+follows:
+
+- [ ] This phase-spec's frontmatter `status` changed from `in-progress` to
+      `completed`
+- [ ] This phase's row in the `_index.md` Phase Specs table changed from
+      `in-progress` to `completed`
+- [ ] `_index.md` Current BR Snapshot reconciled against this phase-spec's
+      **Business Rules** section — this is the feature's first phase, so it
+      has no Delta from prior phases. If implementation changed a rule, update
+      the phase-spec first, then reconcile. Touch only this phase's rows: a
+      row that another change in this host wrote — a lightweight change
+      hosted under this feature, for example — stays as it is. Where this
+      phase and such a change both changed the same rule, keep the later
+      change's text; if the host's record does not show which change came
+      later, ask the developer which text is current instead of choosing.
+- [ ] `_index.md` Resume Pointer: rewrite **both** narrative lines — Current
+      Progress says this phase is completed, and Next Action names the
+      command the handoff below picks. Step 4 wrote "phase-1 in progress:
+      drafting phase-spec." and "finish phase-spec, then implement …" into
+      these two lines; either one left standing reads as open work.
+
+`/dflow:finish-feature` relies on these four whenever the feature reaches it,
+next or after later phases. Its Step 1 checks the phase-spec `status`, the
+Phase Specs row and the Resume Pointer, and stops closeout on a stale one.
+Its Step 3 syncs the Current BR Snapshot into the bounded context as it
+stands, without re-deriving it from the phase-specs.
+
+`Implementation Tasks` is not on this list: 8.1 verified it, and 8.2 may have
+collapsed or removed it by team convention. BC document sync is not on it
+either: 8.3 did it.
+
+**Hand off:**
+
+- Another phase is still ahead → run `/dflow:new-phase` next.
+- No further phase — a single-phase feature, or this was the last phase →
+  run `/dflow:finish-feature` next. It is the only closeout path.
+
+Announce that this phase is completed and name the next command. Do not
+announce the feature as complete: `/dflow:finish-feature` announces that once
+its closeout is complete.

package/templates/greenfield/references/new-phase-flow.md

@@ -347,5 +347,5 @@ state or archive the whole feature from `/dflow:new-phase`.
 
 After completion, summarize for the developer:
 > "Phase {N+1} is implemented and marked completed. `_index.md` is refreshed.
-> If another slice is needed, run `/dflow:new-phase`; if the feature is done,
-> run `/dflow:finish-feature`."
+> If another slice is needed, run `/dflow:new-phase`; if there is no further
+> phase, run `/dflow:finish-feature` to close the feature out."

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

@@ -160,7 +160,17 @@ 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 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
@@ -173,9 +183,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