dflow-sdd-ddd 0.15.0 → 0.16.0

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

@@ -176,7 +176,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
@@ -187,26 +188,37 @@ 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 6), 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, or
-`spec-baseline` for a baseline capture, then closeout — and a T3's `_index.md`
-row is written into checkpoint 1 itself instead of sweeping into a later commit.
+`spec-baseline` for a baseline capture, then closeout — 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
 
@@ -405,8 +430,12 @@ AI should verify:
 - [ ] All `phase-spec-*.md` in the feature directory have `status: completed`
 - [ ] `_index.md` Current BR Snapshot has been synced to BC layer
       (`rules.md` / `behavior.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.
 - [ ] All new business logic is in `src/Domain/` (not delivery/entrypoint code — presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures)
 - [ ] New terms added to `glossary.md`
 - [ ] `rules.md` and `models.md` updated if applicable
@@ -414,8 +443,8 @@ AI should verify:
 - [ ] Domain layer code has no delivery-framework references
 
 > **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
@@ -464,10 +493,15 @@ AI should verify:
 
 ### bugfix/ branch — 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/brownfield/references/modify-existing-flow.md

@@ -68,7 +68,9 @@ the guide states them rather than continuing through the steps below.
   a follow-up (Step 1.6 minimal variant), otherwise it is standalone (Step 1.7) —
   both are tier-exempt, cut `feature/{SPEC-ID}-{slug}`, and record a `Tier = baseline`
   row rather than a change. Do not invent a spec for it, and do not read the
-  cascade's "below workflow" as permission to skip the record.
+  cascade's "below workflow" as permission to skip the record. A baseline
+  minimal host does not stop at the capture: it goes on through Step 6 and
+  offers its first checkpoint (`spec-baseline`) at § 6.5 (Step 1.7 says how).
   A capture about no bounded context at all — the role reach of functions that
   belong to no context yet, say — is not a baseline capture and opens no host:
   with no active feature to attach it to, record it and offer to commit that
@@ -298,6 +300,10 @@ observation-only and carries its own capture alone.
    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
@@ -344,10 +350,13 @@ above). A **baseline capture** is observation-only: it records the capture in
 its BC-layer documents and/or `domain/analysis.md` and one `Tier = baseline`
 row in `_index.md`, and its first checkpoint is named `spec-baseline` with
 Result `committed` (never `implementation` — there is no implementation
-work). Otherwise the **implementation commit is checkpoint 1** — the Step 5 →
-Step 6 commit checkpoint records it in the Checkpoint Log. (For a **post-hoc**
-host, Step 5 is skipped and checkpoint 1 is the **documentation** commit
-instead; see Step 1.8 and Step 5's guard.)
+work). Otherwise the **implementation commit is checkpoint 1**. Either way,
+checkpoint 1 is offered at the end of Step 6 (§ 6.5), after Step 6 has written
+its record, and recorded in the Checkpoint Log. A baseline capture skips Step 5
+— there is nothing to implement — so once the capture is recorded it goes
+through the Step 5 → Step 6 gate into Step 6, not straight to a commit. (For a
+**post-hoc** host, Step 5 is skipped as well and checkpoint 1 is the
+**documentation** commit instead; see Step 1.8 and Step 5'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
@@ -359,7 +368,8 @@ implementation paths (for a baseline, the documents it captured into). The
 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.)
+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* —
@@ -371,16 +381,17 @@ documents it wrote instead; that is its counterpart. 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 6
-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. A **baseline capture** likewise has no spec
-file — record its `Tier = baseline` row's commit evidence and advance the
-Resume Pointer.
+**Before checkpoint 1 — Step 6 finalizes the record.** Step 6's completion
+checklist runs before checkpoint 1, so everything it writes rides that commit.
+For **every** T2, 6.3 sets the lightweight-spec `status: completed`. **Only when
+that T2 is BC-bearing**, 6.3 also refreshes the host's Current BR Snapshot — a
+no-BC T2 has no snapshot to refresh. A **T3** or a **baseline capture** has no
+spec file and no snapshot to refresh; Step 6 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
@@ -397,20 +408,22 @@ 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 6'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).
 - **Baseline capture** — the `spec-baseline` checkpoint's Result
   `committed ({hash})` and the `Tier = baseline` row's `Commit` cell both name
   that capture commit, the one that carried what it captured. Two cells,
   one hash; fill both.
 
 **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 6'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** (or a
 `spec-baseline` one). On a **post-hoc** host the Result stays
@@ -420,7 +433,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.
@@ -673,12 +687,18 @@ Wait for confirmation before entering Step 5.
 > **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 5 → Step 6 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 5 → Step 6 gate and on through Step 6;
+> checkpoint 1 (§ 6.5) then commits **documentation only** — the T2 spec or T3
+> row, this host's `_index.md` and what Step 6 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.
 
+> **Baseline capture (a baseline minimal host, Step 1.7) — skip this step.**
+> There is nothing to implement. Once the capture is recorded, go through the
+> Step 5 → Step 6 gate into Step 6; checkpoint 1 (§ 6.5) is the `spec-baseline`
+> commit of what the capture wrote.
+
 If extracting to Domain layer:
 
 ```csharp
@@ -717,9 +737,10 @@ protected void Calculate()
 Announce to developer:
 > "Implementation appears complete. Ready to update artifacts (spec, rules.md, models.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 — or `spec-baseline` for a baseline — then closeout), for T3, T2, and baseline alike. **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.
+A **baseline capture** implemented nothing, so it announces instead:
+> "Baseline capture recorded. Ready to update artifacts? `/dflow:next` to proceed."
 
-Wait for confirmation before entering Step 6. This step gate is where the completion checklist is triggered — do not skip.
+Wait for confirmation before entering Step 6. 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 6 (§ 6.5).
 
 ## Step 6: Update Artifacts
 
@@ -756,6 +777,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 and baseline: N/A** (no spec file exists; the `_index.md` inline row — a T3 row, or a `Tier = baseline` 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, a T3 and a baseline capture
 - [ ] 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}/`: 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 `migration/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 migration 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
 - [ ] `dflow/specs/domain/{context}/rules.md` — business rules updated
 - [ ] `dflow/specs/domain/{context}/models.md` — domain model updated
@@ -800,3 +822,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 6.3 docs sweep) is done.
+
+### 6.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–6 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 — or `spec-baseline` for a baseline — then closeout), for T3, T2, and baseline alike. **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 6 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/brownfield/references/modify-existing-follow-up.md

@@ -103,7 +103,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/brownfield/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/brownfield/references/new-feature-flow.md

@@ -416,7 +416,7 @@ During implementation, continuously check:
 **→ Step Gate: Step 7 → Step 8**
 
 Announce to developer:
-> "Implementation appears complete. Ready to run the completion checklist (verify against spec, update domain docs, archive the spec)? `/dflow:next` to proceed."
+> "Implementation appears complete. Ready to run the completion checklist (verify against spec, update domain docs, 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.
 
@@ -468,33 +468,51 @@ Ask these one-by-one; do not dump all five at once.
 - [ ] `analysis.md`, at either of its two paths — re-check every entry this feature recorded before building: an entry for what the feature was to add or change against what was built (corrected where the build differs, removed where nothing was built for it), and an entry for something already in the system against the system as it now stands (corrected where this feature changed it, never removed because this feature built nothing for it). Read the entries in the file, not in a diff: a checkpoint may already have committed them.
 - [ ] `dflow/specs/migration/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/brownfield/references/new-phase-flow.md

@@ -338,5 +338,5 @@ 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."