dflow-sdd-ddd 0.13.0 → 0.15.0

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

@@ -15,25 +15,35 @@ state, archives the feature directory, and emits a Git-strategy-neutral
   own. Merge strategy follows the team's selected Git policy (`gitflow` /
   `trunk`, recorded in `dflow/specs/shared/_conventions.md` § Git Policy).
 - Closeout is split into two gates so it works offline: a **Local-closeout
-  gate** (Steps 1–4: validation, status flip, BC sync, archive + an optional
-  commit checkpoint — all doable with no network) and an **Integration / PR
+  gate** (Steps 1–4: validation, status flip, BC sync, archive + the closeout
+  commit checkpoint — all doable with no network; what is optional is **who**
+  runs that commit, not whether it happens, see Step 4) and an **Integration / PR
   gate** (Step 5: push / merge / PR — needs network; the AI only runs
   `git push` / `gh pr create` when you explicitly ask).
 - At the archive checkpoint the AI may offer to commit using your Git identity;
   you can always decline. The commit marker mode is read from `_conventions.md`
   § AI Commit Policy. This replaces Dflow's earlier "the AI never commits"
   stance — the AI helps at natural checkpoints, you keep the final say.
-- The BC-layer sync in Step 3 **reuses the existing Step 8.3 mechanism**
-  from `new-feature-flow` — it does not introduce a new sync flow. Treat
-  it as "lift Step 8.3 out of the per-phase checklist and run it once at
-  feature closeout, with the `_index.md` Current BR Snapshot as input."
+- The BC-layer sync in Step 3 **reuses the existing documentation-sync
+  mechanism** from `new-feature-flow` (§ 8.3) and `modify-existing-flow`
+  (Step 6.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 Gates** in this flow (stop-and-confirm before proceeding):
 - Step 1 → Step 2 (validation passed → flip status)
 - Step 3 → Step 4 (BC sync done → archive)
-- Step 5 → Step 6 (Integration Summary emitted → optional follow-up reverse-link)
 
-All other step transitions are **step-internal**: announce "Step N complete,
+**Step 5 → Step 6 is deliberately not a step gate, and when the host carries a
+`follow-up-of` field it also stops and waits.** It is this flow's
+**post-Local-closeout confirmation**: by the time it is reached the archive has
+landed and this feature's cursor reads `none`, so the step-gate protocol —
+`/dflow:next` and `/dflow:cancel`, and the cursor update a step gate carries —
+does not apply to it. **Step 5 states what it accepts.** Do not treat it as a
+step gate because it waits, and do not treat it as step-internal because it is
+not a gate.
+
+**Every other step transition is step-internal**: announce "Step N complete,
 entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow
 Transparency for the full transparency protocol and confirmation signals.
 
@@ -48,12 +58,55 @@ AI runs mechanical checks first. Report `✓` / `✗` for every item; if any
 `✗` appears, **stop here** and ask the developer to address them before
 proceeding (do not flip status, do not archive, do not emit summary).
 
+**What these checks do and do not prove.** They catch the mistakes that actually
+happen — work left uncommitted, a placeholder hash never replaced, a row copied
+from another feature — not a record deliberately built to look right.
+Whole-history assertions ("no stray host-open commit exists anywhere on this
+branch") are **review's** job, not closeout's: they belong to
+`references/pr-review-checklist.md`.
+
+> **Reconcile a mainline hotfix BEFORE you run these checks.** If a T2 / T3
+> post-hoc hotfix (`modify-existing-flow.md` Step 1.8) landed on the mainline
+> while this feature was in flight and the two touched the same code, settle the
+> overlap **now, before the checklist below** — anything *recorded into this
+> host* after the checks have passed has bypassed them.
+>
+> **Open `references/finish-feature-post-hoc-hotfix.md` and follow it there.**
+> What you classify, where the merge-resolution delta may be recorded, and what
+> must not be routed mid-closeout are decided there.
+
+**What "Minimal host (zero-phase) only" selects, and what that does not prove.**
+A minimal host takes extra checks and extra field rules. Decide it from the
+**persisted shape**: an **empty Phase Specs table and no `phase-spec-*` file**
+in the host directory. There is no other selector — closeout runs in a fresh
+session and cannot know which flow step created the host. So a host that
+*carries* a phase is certified as **phase-bearing**, whatever it was intended to
+be, and takes the ordinary checks rather than these. This gate does **not**
+prove "this host was opened as minimal and stayed that way"; that is a claim
+about history, and it belongs with the whole-history assertion already assigned
+to `references/pr-review-checklist.md`.
+
+**Open `references/finish-feature-minimal-host.md` and follow it there.** Do
+this only when this host is minimal; a **phase-bearing** host does not open it
+at all. Its rules live in that file and are not repeated here, and it stays open
+for the whole closeout — it adds to this checklist, to Step 3's sync input, to
+Step 4's post-commit verification, and to Step 5's Integration Summary fields.
+
 - [ ] Locate the feature directory at `dflow/specs/features/active/{SPEC-ID}-{slug}/`
-- [ ] `_index.md` exists and parses (YAML front matter intact, seven required
-      sections present, including the Checkpoint Log)
+- [ ] `_index.md` exists and parses (YAML front matter intact, and all seven
+      required sections present — the Metadata front matter, Goals & Scope,
+      Phase Specs, Current BR Snapshot, Lightweight Changes, Checkpoint Log,
+      Resume Pointer; `Follow-up Tracking` is `templates/_index.md`'s optional
+      eighth section and appears only when this feature has follow-ups)
 - [ ] Every row in `_index.md` Phase Specs table has Status = `completed`
 - [ ] Every phase-spec file referenced in the Phase Specs table exists at
       the path the table claims
+- [ ] **And the other direction, for every host shape: every spec file in the
+      host directory is named by a row** — each `phase-spec-*` by a Phase Specs
+      row, each `lightweight-*.md` / `BUG-*.md` by a `Tier = T2` Lightweight
+      Changes row. An orphan file **blocks** — either it belongs to a phase or
+      change whose row is missing, or it belongs to nothing and does not belong
+      in the host.
 - [ ] Every phase-spec file's frontmatter has `status: completed`
 - [ ] Every Tier = T2 row in `_index.md` Lightweight Changes references an
       existing `lightweight-*.md` / `BUG-*.md` file in the feature directory
@@ -61,8 +114,54 @@ proceeding (do not flip status, do not archive, do not emit summary).
       `status: completed`
 - [ ] `_index.md` has no obvious open items in Resume Pointer (e.g. "phase-N
       drafting" / "implementation pending" / "TODO" markers)
-- [ ] Current BR Snapshot table is non-empty (or feature is intentionally
-      a no-BR feature — confirm with developer if uncertain)
+- [ ] **You are on this host's branch — or on a branch this host recorded a
+      sanctioned override for.** `git rev-parse --abbrev-ref HEAD`
+      equals `_index.md`'s `branch:` value — that field is authoritative for the
+      whole host — and for a **T2** the lightweight-spec's frontmatter `branch:`
+      equals it too. Steps 1–4 run *before* the merge / PR gate, so a mismatch
+      means you are closing out somewhere other than where the work was
+      finished, and it **blocks**. A hash check does not cover this: any sibling
+      branch descended from checkpoint 1 carries the same commits, so every hash
+      this host's record names still resolves and is still an ancestor. For a
+      **post-hoc** host this compares against the **documentation** branch,
+      never `hotfix-branch:`, which names the already-merged hotfix.
+      **Before blocking on a mismatch, read the Checkpoint Log for a
+      `branch-override` row.** `references/git-integration.md` § Branch gate
+      offers "override and stay" as a sanctioned third option and defines that
+      row's shape. If **any** such row's Result names the branch `HEAD` is on,
+      the mismatch is one this host recorded deliberately and this item
+      **passes**. `branch:` itself is still never rewritten — the override is a
+      record beside it, not a correction of it.
+      ⚠ **The row must name *this* branch** — that is the whole test.
+      ⚠ **What this cannot decide, stated rather than patched:** whether a
+      recorded override is still the current intent. **Nothing expires a row at
+      all** — not when the developer moves back to the host's own branch, not
+      when a later override supersedes it, and not with distance from closeout.
+      So *any* branch this host ever recorded an override for stays acceptable
+      here: closing out on the base branch after the feature branch was merged
+      passes, and so does closing out on an abandoned spike branch that an
+      override named two phases ago. Closeout cannot separate either from a
+      legitimate override. **Which branch the closeout commit actually landed on
+      is visible in the PR**, and it is judged by
+      `references/pr-review-checklist.md`'s **"A recorded branch override still
+      matches where the closeout landed"** item.
+      **When it passes this way, say so in the conversation** — name the row and
+      the branch, e.g. *"HEAD differs from `branch:`; found a recorded
+      `branch-override` for `{branch}` in the Checkpoint Log — verified and
+      passing."*
+- [ ] Current BR Snapshot table is non-empty — **or this host's own record
+      carries no BR delta**, which is what makes an empty one legitimate.
+      That condition is the check; the shapes below are illustrations of it,
+      not the list of them: a **T3** host; a **no-BR family T2** whose Behavior
+      Delta is a `BR:` / `BR Delta:` none line; a **baseline capture**
+      (observation-only, so it has no BR delta to record); a **phase-bearing**
+      host — **including a T1** — whose phase-specs establish no BR delta,
+      which the cascade explicitly allows; or a shape added later that likewise
+      carries 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**.
 
 If any check fails:
 > "Cannot finish feature `{SPEC-ID}-{slug}` yet — {N} validation issues
@@ -74,6 +173,50 @@ If any check fails:
 > Address these (run `/dflow:new-phase` to add missing work, or fix the
 > stale status manually), then re-run `/dflow:finish-feature`."
 
+**Once every item above — and every item this host's branch file added — reads
+`✓`, record the baseline the post-commit check compares against.** Capture
+**exactly the set the closeout commit will carry**:
+
+```bash
+git ls-files --cached --others --exclude-standard -- dflow/specs/features/active/{SPEC-ID}-{slug}
+```
+
+⚠ **Both halves of that command are load-bearing, because it has to agree with
+`git add`.** It **excludes** ignored files, which `git add` also skips and the
+span can never carry. It **includes** untracked files that are not ignored,
+which `git add` **does** stage — a host file created during this feature and
+never committed still rides into the closeout commit, so a baseline without it
+reports that file as added after Step 1 and blocks a correct closeout.
+
+Run `git hash-object -w {path}` for each and build the `path → blob` list, one
+entry per line. **Strip the host-directory prefix**: that command prints paths
+from the repository root, and Step 4 matches on the path *relative to the host
+directory*.
+⚠ **The `-w` is mandatory.** It writes each blob into the object database, so
+Step 4 can read the baseline's **content** back; without it the list is
+fingerprints only, and Step 4's comparison cannot run.
+
+**Then anchor the list itself where Step 4 can recompute its name** — pipe the
+list into `git hash-object -w --stdin`, then:
+
+```bash
+git update-ref refs/dflow/closeout-baseline/{SPEC-ID}-{slug} {list blob}
+```
+
+**That ref is the baseline.** Step 4 resolves it by recomputing the same name
+from this host's own `{SPEC-ID}-{slug}`; if `git check-ref-format` rejects that
+name, say so and stop.
+⚠ **Trim both fields of every entry, on write and on read.** A shell that
+writes CRLF leaves a trailing `\r` on each line, and `git cat-file -p` on a blob
+id carrying one fails as an invalid object name — which would report a healthy
+baseline as unreadable.
+⚠ **`refs/dflow/**` is local by construction.** A default `git push`, `git fetch`
+and a plain `git clone` all leave it behind; an explicit refspec or
+`clone --mirror` does carry it. Do not add it to any refspec.
+⚠ **`HEAD^` is not a substitute** — at this point the working tree legitimately
+carries uncommitted finalization edits, so comparing against the parent commit
+reports every one of them as a difference no step ordered.
+
 **→ Step Gate: Step 1 → Step 2**
 
 If all checks pass:
@@ -93,43 +236,121 @@ spec-id: SPEC-{YYYYMMDD}-{NNN}
 slug: {slug}
 status: completed         # ← flipped from in-progress
 created: {YYYY-MM-DD}
-branch: feature/{SPEC-ID}-{slug}
+branch: {unchanged — keep the host's existing value}   # feature/{SPEC-ID}-{slug} or bugfix/BUG-{NUMBER}-{slug}; never rewrite
 ---
 ```
 
-Also update the **Resume Pointer** to reflect closeout — this writes the
-cursor's terminal state (after closeout no workflow is active on this
-feature; do not edit the cursor again after the Step 4 closeout commit):
+**Flip `status` only — never rewrite `branch:`.** The `branch:` field is
+authoritative and stays exactly as opened: a bugfix host keeps its
+`bugfix/BUG-{NUMBER}-{slug}` value, a **non-bug** standalone / follow-up host —
+and every baseline capture, which is never a functional bug — keeps its
+`feature/{SPEC-ID}-{slug}` value. The branch follows the **change class**, not
+how the host was opened — a functional-bug standalone or follow-up host **is** a
+bugfix host and keeps `bugfix/BUG-*` (the branch-by-class rule at
+`modify-existing-flow.md` Step 1.7 step 4). Overwriting it to `feature/...` at
+closeout would break branch equality for a bugfix host.
+
+Also update the **Resume Pointer** — to the state closeout is actually in, which
+is **not** the terminal state. **Step 4 writes the terminal value**, immediately
+after the `git mv`:
 
 ```
-**Current Progress**: feature completed ({date}); all phase-specs status = completed.
-**Next Action**: integration — push / merge / PR per the selected Git policy.
-**Active Workflow**: none
-**Current Step**: n/a
-**Gates Passed**: n/a
-**Awaiting**: none
+**Current Progress**: status flipped to `completed` ({date}); closeout in progress.
+**Next Action**: continue closeout — sync the BR Snapshot to the BC layer (Step 3).
+**Active Workflow**: finish-feature
+**Current Step**: Step 3 — sync BR Snapshot to BC layer
+**Gates Passed**: 1→2
+**Awaiting**: none (mid-step)
 ```
 
+⚠ **`Awaiting` is `none (mid-step)`, never `gate 3→4`.** Step 3 has not run at
+this point, and a cursor that says otherwise sends the next session to
+`/dflow:next`, **skipping the BC sync**. `none (mid-step)` is the existing
+convention for this position.
+
 **→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (status flipped). Entering Step 3: Sync BR Snapshot to BC layer." and continue.
 
 ## Step 3: Sync `_index.md` Current BR Snapshot to BC Layer
 
-This step **reuses the existing sync mechanism** from `new-feature-flow`
+**First, branch on what this host actually carries** — "zero-phase" (no
+phase-spec) is independent of whether a bounded context exists, so a minimal
+host may still touch a real BC, or none at all:
+
+- **(i) BC-bearing** — the host touched a real bounded context, **whether or
+  not it carries a BR delta** (BC presence and BR presence are independent). Run
+  the sync below **for the documents this host actually changed**: a BR delta
+  updates `rules.md` / `behavior.md`; a no-BR family that touched a documented
+  behaviour still updates `behavior.md`. Fill the Integration Summary's BC field
+  with the context, and its BR-IDs with whatever applies — a real set, the
+  per-family no-BR marker, or empty. Do **not** skip, and do **not** manufacture
+  a BR delta a no-BR host does not have. (A host whose **entire** payload is a
+  baseline capture is **(iii)**, not this case.)
+- **(ii) no-BC** — the host touched **no** bounded context at all (a display
+  T3, an appearance sweep). **Skip this sync entirely** — do **not** create
+  `rules.md` / `behavior.md`, and do not invent a BC to sync into. Its
+  Integration Summary sets the field that **reports a sync** — `BC` — to
+  `none`. **`Related BR-IDs` is not one of those**: it reports what this
+  change's own record carries, so it stays empty or keeps the per-family no-BR
+  marker. Step 5's "exact fields" block is the authority on the shape; do not
+  flatten it to "all BR fields are none" here.
+- **(iii) baseline pre-captured** — this host's **entire** payload is the
+  baseline capture: a **zero-phase minimal host** whose only Lightweight Changes
+  row is the `Tier = baseline` one. That capture already wrote its
+  documents when it ran (`modify-existing-flow.md` Step 1.7), so there is
+  **nothing more to sync**; the Integration Summary's BC field names the
+  captured context (not `none`). A **phase-bearing** host carrying a baseline row
+  alongside other work takes **(i)** instead and syncs everything except the
+  baseline. A *minimal* host cannot be in that position at all —
+  `references/finish-feature-minimal-host.md`'s `baseline only` check blocks a
+  `spec-baseline` host that carries anything beyond its capture.
+
+For a **BC-bearing host (case i only)**, continue with the sync. This step **reuses the
+existing sync mechanism** from `new-feature-flow`
 Step 8.3 (`dflow/specs/domain/{context}/rules.md` + `behavior.md` updates). The
 input is the feature's `_index.md` Current BR Snapshot table; the output
 is the BC's `rules.md` and `behavior.md` updated to reflect the
 feature's net effect.
 
-Before syncing, ensure required BC files exist. If missing, create from templates:
+**Minimal host — sync input.** A minimal host reads "phase-spec" differently
+here, and a phase-bearing host must not apply that reading. The rule is
+`references/finish-feature-minimal-host.md` § Step 3.
+
+**Every host — lightweight-spec deltas are a sync input too.** A host of **any**
+shape may carry hosted Lightweight Changes rows: the two `Tier = T2` checks in
+Step 1 carry no host-shape restriction, so they run on a phase-bearing host as
+well. So a
+phase-bearing host can hold a hosted T2 whose delta belongs in this sync, and
+**the steps below name phase-specs only**. Read them as *this feature's
+phase-specs **and** its hosted lightweight-specs' recorded deltas*.
+⚠ **Where this bites hardest is a no-BR family**, because the BR-driven sections
+below cannot reach it at all: with no BR-ID there is no Current BR Snapshot row
+to iterate, so a hosted T2 that changed only a documented behaviour is visible
+**solely** in its own recorded delta. Miss it and `behavior.md` silently loses a
+change that a phase-bearing closeout had no other instruction to look for.
+⚠ This does not reach a **baseline** row: case (iii) above already wrote the
+capture when it ran, so there is nothing left for this sync to take from
+it.
+
+Before syncing, ensure the BC files **this sync actually writes** exist; create a
+missing one from its template **only when this host's delta writes to it**. Case
+(i) above syncs "the documents this host actually changed", so a document this
+host does not touch is **not** created — a BC-bearing **T3**, or a no-BR family
+that touched only one of them, leaves the others absent, exactly as case (ii)
+does for a no-BC host. Creating one anyway plants the same fiction the no-BC
+guard refuses:
 - `dflow/specs/domain/{context}/rules.md` → `templates/rules.md`
 - `dflow/specs/domain/{context}/behavior.md` → `templates/behavior.md`
 
-For each row in Current BR Snapshot where Status = `active`:
+> **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).
 
-- If the BR-ID is **not yet in `rules.md`** → add it (new ADDED rule
-  introduced by this feature)
-- If the BR-ID is **already in `rules.md`** but the rule text differs →
-  update it (MODIFIED rule, reflect the new text)
+For each row in Current BR Snapshot — **every** row, not only the `active` ones.
+The branch below is selected by the row's own Status, and a `removed` row is
+exactly what the REMOVED branch needs:
+
+- Status `active`, and the BR-ID is **not yet in `rules.md`** → add it (new
+  ADDED rule introduced by this feature)
+- Status `active`, and the BR-ID is **already in `rules.md`** but the rule text
+  differs → update it (MODIFIED rule, reflect the new text)
 - If the BR-ID was previously in `rules.md` and is now in Current BR
   Snapshot with Status = `removed` → remove the corresponding section in
   `rules.md` (REMOVED rule)
@@ -151,7 +372,8 @@ rules.md ↔ behavior.md drift check (see `references/drift-verification.md`).
 
 Cross-reference each phase-spec's Delta-from-prior-phases section to
 double-check the net result; the Snapshot is the SSOT but the per-phase
-Deltas are the audit trail.
+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
@@ -160,10 +382,12 @@ Deltas are the audit trail.
 > and the phase-specs, fix `_index.md` first, then re-run
 > `/dflow:finish-feature`.
 
-Also update `migration/tech-debt.md` / `models.md` / `glossary.md` as
-discovered during the feature (the same items listed in
-`new-feature-flow.md` Step 8.3) — these may have been touched per phase
-already; this is the closeout sweep.
+Also update `migration/tech-debt.md` / `models.md` / `glossary.md` /
+`analysis.md` as discovered during the feature (the same items listed in
+`new-feature-flow.md` Step 8.3; `analysis.md` is two files — the owning
+context's and the domain-root one — each created from `templates/analysis.md`
+the first time there is something to record) — these may have been touched per
+phase already; this is the closeout sweep.
 
 **→ Step Gate: Step 3 → Step 4**
 
@@ -172,25 +396,83 @@ already; this is the closeout sweep.
 > updated, `last-updated` set to {date}. Ready to archive the feature
 > directory? `/dflow:next` to proceed."
 
+For a **no-BC host** (case ii) the sync was skipped — do **not** announce a
+sync that did not happen. Say instead: "No BC-scoped sync was performed (no-BC
+host). Ready to archive the feature directory? `/dflow:next` to proceed." Do
+**not** say "nothing was written to the Domain layer" — a no-BC host may still
+have updated a **global** document (`glossary.md`, `domain/analysis.md`,
+`migration/tech-debt.md`); those belong to no bounded context and Step 4 must
+still stage them.
+
+For a **baseline host** (case iii) the BC was already captured at baseline —
+nothing further to sync. Say instead: "BC `{context}` was pre-captured at
+baseline; nothing further to sync. Ready to archive the feature directory?
+`/dflow:next` to proceed."
+
 Wait for confirmation before entering Step 4.
 
 ## Step 4: Archive — `git mv` the Feature Directory
 
-AI runs:
+**First, confirm the baseline is still readable — before anything irreversible:**
+
+```bash
+git cat-file -p refs/dflow/closeout-baseline/{SPEC-ID}-{slug}
+```
+
+If it does not resolve, or the list it prints names a blob that does not read
+back, **stop here** and say the baseline is unavailable: closeout restarts from
+Step 1, which re-captures it. **Nothing is committed yet and the host is still in
+`active/`** — that is what this position buys.
+⚠ **This does not prove the baseline is the *right* one** — only that it is
+readable. Reading back and *judging* is the post-commit item's job.
+
+Then AI runs:
 
 ```bash
 git mv dflow/specs/features/active/{SPEC-ID}-{slug} \
        dflow/specs/features/completed/{SPEC-ID}-{slug}
-git status   # confirm rename detection AND check for `RM` — an `M` next to
-             # a rename means unstaged edits you must re-add before committing
 ```
 
-`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. See
+`git mv` is mandatory — never use plain `mv` + `git add`. See
 `references/git-integration.md` § "Directory Moves Must Use git mv" for
 the full rule set.
 
+**Immediately after the `git mv`, write the Resume Pointer's terminal value into
+the moved `_index.md`.** Write both prose lines and all four cursor fields —
+all six lines of the Resume Pointer — because this write sets each line's final
+value:
+
+```
+**Current Progress**: feature completed ({date}); all phase-specs status = completed.
+**Next Action**: integration — push / merge / PR per the selected Git policy.
+**Active Workflow**: none
+**Current Step**: n/a
+**Gates Passed**: n/a
+**Awaiting**: none
+```
+
+⚠⚠ **The `git mv` and this write are one uninterruptible pair.** Nothing goes
+between them — not the Y / N prompt below, not a question to the developer, not
+a tool call that can wait on input, and not the `git status` check below.
+
+⚠ **From here the cursor is terminal and closeout does not edit it again** — not
+when the developer declines the commit (N), not when the commit fails, not when
+the post-commit verification below reports `✗`. **Do not restore it to an
+in-progress value on any of those paths.** What surfaces a closeout that failed
+after this point is `git status` — the staged rename plus the uncommitted
+`_index.md` edits — not the cursor, which no global scan reads once the host has
+left `active/`.
+
+**Now check the rename landed**, with the terminal cursor already written:
+
+```bash
+git status --short   # confirm rename detection AND check for `RM` — an `M`
+                     # next to a rename means unstaged edits you must re-add
+                     # before committing. --short is required: the default long
+                     # format lists the rename and the modification separately
+                     # and never prints a two-column `RM`.
+```
+
 **Closeout commit checkpoint** (completes the offline Local-closeout gate):
 
 ```
@@ -211,6 +493,14 @@ Then, in this order:
    still applies to spec / implementation rows — closeout is the documented
    exception (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
+   `git cat-file -t` cannot resolve; both are backfilled the same way, and the
+   placeholder case matters more because the cell is **non-empty** and therefore
+   invisible to every rule written against empty / non-empty. Write each row's own
+   implementation hash, never the closeout hash. After closeout there is no next
+   commit, which is why `references/pr-review-checklist.md` asserts it there.
 2. **Stage the whole archived feature directory:**
 
    ```bash
@@ -218,13 +508,72 @@ Then, in this order:
    ```
 
    This is required, not optional: `git mv` stages the rename with the
-   **last-committed** content, so working-tree edits made earlier in this
-   flow to the moved files — the Step 2 status flip and Resume Pointer
-   update, plus the checkpoint row you just wrote — stay **unstaged** until
-   this `git add`. In `git status`, the moved `_index.md` showing `RM`
-   instead of plain `R` is exactly this signal. Then also `git add` the
-   files updated in Step 3 (the updated `rules.md`, `behavior.md`,
-   `glossary.md`, `tech-debt.md`, etc.) into the same stage.
+   **last-committed** content, so **every** working-tree edit to the moved files
+   stays **unstaged** until this `git add` — Step 2's status flip and its
+   in-progress cursor, whatever gate 3 → 4 wrote to the cursor, the terminal
+   cursor value written just after the `git mv`, and **everything instruction 1
+   ordered**: the checkpoint row *and* every hosted `Commit` cell it backfilled.
+   Take that last part from instruction 1 itself, not from this sentence — it is
+   the step that orders those edits, and a copy kept here would go stale the
+   next time it changes. In `git status --short`, the moved `_index.md` showing
+   `RM` instead of plain `R` is exactly this signal — the same `--short`
+   requirement as the rename check above. Then also `git add`
+   **every external document this closeout carries.** That set is defined
+   here, once, and it covers **every** host shape — take it from this
+   instruction, not from a list kept somewhere else:
+   **(a)** whatever Step 3 wrote (`rules.md`, `behavior.md`, `models.md`,
+   `analysis.md`, `glossary.md`, `domain/analysis.md`,
+   `migration/tech-debt.md`) — Step 3 is **skipped entirely for a no-BC host**
+   (and for a baseline 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.
+   Those sweeps reach
+   Domain-layer documents under `dflow/specs/domain/`, plus the **global**
+   documents `glossary.md`, `domain/analysis.md` and `migration/tech-debt.md`,
+   which belong to no bounded context and stay legitimate for a **no-BC** host.
+   The two that exist
+   today —
+   `modify-existing-flow.md` **Step 6.3** and `new-feature-flow.md`
+   **§ 8.3 Documentation updates** — are **illustrations, not the definition**:
+   a later flow with a sweep of its own is covered without editing this line.
+   ⚠ **Key it on the flow that produced the change, never on the flow that
+   opened the host.**
+   ⚠ **How to tell which flow produced a change: it is determined by the
+   artifact, and it is recorded nowhere.** The ledger has no producer column, so
+   read it off the shape.
+   A **Lightweight Changes row** was produced by `modify-existing-flow.md` **by
+   construction** — that is the only flow that writes such a row
+   (`/dflow:bug-fix` routes into the same file, and `new-feature-flow.md` creates
+   that table empty and never adds to it), so its sweep is **Step 6.3**.
+   A **phase-spec** has three possible producers — `/dflow:new-feature`,
+   `/dflow:new-phase`, or `modify-existing-flow.md` Step 1.6 / 6.4 routing into
+   the new-feature machinery — and **you do not have to tell them apart**:
+   § 8.3 and Step 6.3 enumerate the same external paths, and `/dflow:new-phase`
+   has no sweep at all, so every branch yields that same set or a part of it,
+   save one file the next paragraph names.
+   ⚠ **`/dflow:new-phase` has no sweep and is deliberately absent here.**
+   `new-phase-flow.md` Step 7 updates the phase-spec and this host's own tables,
+   and says so in as many words — "System-level domain docs, migration debt
+   sync, and the feature directory move to `completed/` remain
+   `/dflow:finish-feature` responsibilities; Step 2 records into
+   `analysis.md` directly, at whichever of its two paths the entry belongs
+   to. **Do not sync any other system-level current state**". The external
+   writes its own steps call for are those two paths and, on an
+   Aggregate-emergence escalation, the `models.md` row its Step 2 marks; the
+   set above already carries all three. The one file outside it is
+   `context-map.md`: `ddd-modeling-guide.md`, which its Step 2 sends it to,
+   records there a choice to model deeper — stage it too when a phase did.
+   On a **minimal host** that set is exactly what allow-list member (iii) of
+   `references/finish-feature-minimal-host.md`'s uncommitted-source check
+   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*;
+   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
    rejects it or the commit fails, flip the checkpoint row to `failed` (the
    row is not committed yet — edit it directly), surface the error, and
@@ -234,19 +583,159 @@ Then, in this order:
 declaring the Local-closeout gate satisfied, AI runs and reports `✓` / `✗` for
 every item:
 
-- [ ] `git show HEAD:dflow/specs/features/completed/{SPEC-ID}-{slug}/_index.md`
-      — one blob read verifying **two** things: frontmatter `status: completed`
-      **and** the Checkpoint Log contains the closeout row. This reads the
-      **committed** content, not the working tree — the former catches "rename
-      carried stale content", the latter catches "row never made it into the
-      commit".
+- [ ] `git ls-tree -r --name-only HEAD
+      dflow/specs/features/completed/{SPEC-ID}-{slug}/` — **every file this
+      commit carries from inside the archived host directory** — then
+      `git show HEAD:<path>` for each.
+      **The span, fixed once and used by both halves of this check:** exactly
+      that set — nothing wider, nothing narrower. What may differ, and what
+      blocks, are judged over exactly that span.
+      ⚠ **The span is derived from what was staged, not from what the tables
+      name.**
+      **The baseline is the `path → blob` list Step 1 anchored** — read it with
+      `git cat-file -p refs/dflow/closeout-baseline/{SPEC-ID}-{slug}`, recomputing
+      that name from this host's own `{SPEC-ID}-{slug}`. The tree Step 1 read is
+      captured rather than remembered, **and so is the way back into it** — this
+      resolves in a session that never saw Step 1. **Both sides are already
+      host-relative** — Step 1 stripped its prefix, this span is read under
+      `completed/{SPEC-ID}-{slug}/`, and the `git mv` preserved the relative
+      tree — so the two sets line up with no prefix left to reconcile.
+      **Compare the two path sets first, before any blob comparison.** A
+      **baseline path missing from the span** is a file removed after Step 1; a
+      **span path with no baseline entry** is a file added after Step 1. Each is
+      a difference and is judged like any other: it **blocks** unless a step of
+      this closeout ordered it.
+      Then, for each path the two sets share, take the committed blob with
+      `git rev-parse HEAD:{completed path}`. **Different from that path's
+      baseline blob → read the delta itself with `git diff {baseline blob}
+      HEAD:{completed path}`, and judge that delta against the derived
+      condition below. Equal → that path carries no difference at all, which
+      satisfies the condition only where no step of this closeout ordered an
+      edit to it; where one did, the ordered edit never landed and this
+      **blocks**.**
+      ⚠ **Blob ids alone answer only *same* / *different*, which cannot decide
+      the derived condition.**
+      ⚠ **If the ref does not resolve, or the content behind it does not read
+      back, report this check as degraded and say so — do not substitute
+      `HEAD^`.** The probe at the top of this step exists so that this is reached
+      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
+      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.)
+      **The condition is derived, not listed:** within that span, the committed
+      blob differs from that baseline in **exactly the edits Step 2, Step 4's
+      terminal Resume Pointer write and Step 4 instruction 1 ordered, carrying
+      the values those steps state, and in nothing else**. Read those three
+      steps and compute the set — do not keep a second copy of it here. Any
+      difference **no step of this closeout ordered** is edit fallout and
+      **blocks**.
+      ⚠ **This compares final net state, not the sequence of edits.** Step 2
+      writes an in-progress cursor and gate 3 → 4 updates it again; Step 4's
+      terminal write then overwrites every field either of them touched, so
+      neither appears in the committed blob. **Their absence is not a difference
+      and must not block**, and nothing here proves they happened. What this
+      comparison settles is that the *terminal* value is the one that landed.
+      **What this check cannot decide — stated, not asserted:** whether a
+      backfilled hosted `Commit` cell holds *that row's own* implementation hash
+      rather than some other commit's. Instruction 1 orders that value and is
+      the single place the constraint lives; closeout cannot verify it, because
+      the hash-evidence test is minimal-host-only and lives in
+      `references/finish-feature-minimal-host.md`, so on a phase-bearing host
+      **no check reads the value at all**.
+      **Identity is confirmed by `references/pr-review-checklist.md`'s
+      "Hosted `Commit` cell identity" item**, which sits in that file's
+      *Delegated to review by `finish-feature-flow.md`* block — the same
+      assignment this file already makes for the whole-history assertion.
+      ⚠ **Not** its "Every Lightweight Changes row now carries a `Commit` hash"
+      item: that one asserts **presence, not correctness**, and pointing a
+      boundary at a presence check would make it a hole rather than a division
+      of labour.
+      ⚠ **An empty hosted `Commit` cell does not fail this item — and this item
+      does not clear it either.** `references/pr-review-checklist.md` asserts that
+      cell and says so in its own words; **this check does not**. Judge the item on
+      the rest of its evidence and leave the cell to that checklist.
+      **Scope, stated so it is not read as more than it is:** this gate re-reads
+      the archived **host directory** only — what the archived record *says*.
+      What the closeout **commit** *contains* is the separate item below; neither
+      implies the other, and "closeout is clean" needs both.
+      What has actually gone missing this way: `branch:` rewritten away from the
+      value the host opened with (Step 2 flips `status` only, so a bugfix host
+      still reads `bugfix/BUG-{NUMBER}-{slug}`); `follow-up-of` dropped by the
+      Step 2 metadata edit — Step 5 skips Step 6 when it is absent, so losing it
+      strands the original feature's reverse link at `in-progress` while
+      closeout reports success; a Lightweight Changes row, or its `Commit` cell,
+      deleted — archiving an effectively empty host.
+      The closeout row's Result must also **not** be `failed`: you are reading a
+      commit that landed, so `failed` contradicts reality (`committed` on the Y
+      path, `skipped` when the developer declined and committed it themselves).
+      **Minimal host (zero-phase) additionally**: one further condition on the
+      first checkpoint row, stated in
+      `references/finish-feature-minimal-host.md` § Step 4.
+- [ ] **The closeout commit contains only what closeout is allowed to write.**
+      Read its changed paths (`git show --stat HEAD`) and admit **only** the
+      archived host directory — the `git mv` rename plus the finalization
+      Step 1 validated — **plus exactly the external paths Step 4 instruction 2
+      ordered staged**. That is the same derivation the item above uses, applied
+      to the other half of "closeout is clean": the permitted set comes from the
+      instruction that ordered the staging, never from a copy kept here.
+      **Anything else blocks**: implementation source, or a
+      `domain/{context}/…` document under a host that declared itself no-BC.
+      ⚠ **That no-BC half applies to every host shape, and on a phase-bearing
+      host this is the only place closeout tests it.** The
+      `Minimal host (zero-phase), no-BC only` check in
+      `references/finish-feature-minimal-host.md` reads checkpoint 1, and a
+      phase-bearing host has no checkpoint 1 to read — so do not treat "the
+      minimal-host branch file already covers no-BC" as true here. It is true
+      only for a minimal host.
+      **Scope: this is a path-level spill check and nothing more.** It proves no
+      unpermitted *file* entered the commit — not that the permitted ones carry
+      only this host's delta. Judging a hunk inside `rules.md` as "this host's
+      change rather than an unrelated BR edit" needs the intended delta, which
+      lives in the spec and the row, not in a path list. The item that reads one
+      against the other is `references/pr-review-checklist.md`'s
+      **"The closeout commit carries only this host's delta"**.
+      Say that plainly rather than implying the stronger claim.
+      ⚠ **And its span is this one commit.** Between them, the minimal-host
+      branch file's check (a minimal host's checkpoint 1) and this one (any
+      host's closeout commit)
+      still leave every *other* commit on the branch unread — where a no-BC host
+      is concerned, that gap is closed by
+      `references/pr-review-checklist.md`'s **"A no-BC host committed no
+      BC-scoped Domain material"** item, which takes the branch range for
+      **every** no-BC host.
 - [ ] `dflow/specs/features/active/{SPEC-ID}-{slug}/` no longer exists (the
       directory was moved, not copied)
 - [ ] `git status --short` shows no leftovers related to this feature
       (working tree clean; identify any unrelated dirty files explicitly)
 
-If any item fails, do **not** declare closeout complete — fix it (re-add and
-amend, or a follow-up commit; the developer chooses) and re-verify.
+**Once every item above reads `✓`, release the baseline anchor:**
+
+```bash
+git update-ref -d refs/dflow/closeout-baseline/{SPEC-ID}-{slug}
+```
+
+⚠ **Only after they all pass** — a failed item is fixed and re-verified against
+this same evidence, so the anchor has to survive it.
+⚠ **Deleting the ref is not a worktree edit**, so it is not a difference the
+item above could have seen.
+
+If any item fails, do **not** declare closeout complete — fix it and re-verify.
+**How you may fix it depends on the host.** A **phase-bearing** feature has no
+fixed commit count, so re-add and amend *or* a follow-up commit both work; the
+developer chooses. A **minimal (zero-phase) host** does not: its lifecycle is
+exactly checkpoint 1 plus closeout, and every check its branch file adds rests
+on that, so the
+repair must go **into the closeout commit itself** — re-add and amend. Nothing
+has been pushed yet (integration is Step 5), so amending is safe here. A
+follow-up commit would give the host a third host-mutating commit while its
+ledger still claims two; the Step 6 flip is the *only* sanctioned
+post-closeout commit, and it touches the original feature, not this host.
 
 The Local-closeout gate is satisfied **only when the closeout is committed and
 the verification above passes**. If you declined the commit (chose N) or it
@@ -262,7 +751,32 @@ offline; integration happens in Step 5 when you have network.
 
 ## Step 5: Emit Integration Summary (Git-strategy-neutral)
 
-Produce a plain-text summary of what this feature did. The summary is
+**First, print the closeout verification's derivation.** Before the summary
+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).
+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
+   lets a reader check the derivation rather than trust it. Say as well that the
+   comparison reads final net state, so the transitional cursor values Step 2
+   and gate 3 → 4 wrote are outside what it can show.
+3. **The external paths admitted, and which half of Step 4 instruction 2 each
+   came from** — what Step 3 wrote, or this change's own sweep.
+4. **What the check could not decide, and who holds it** — for a backfilled
+   hosted `Commit` cell, that closeout cannot decide whether the value is that
+   row's own implementation hash, and that
+   `references/pr-review-checklist.md`'s **"Hosted `Commit` cell identity"**
+   item is where it gets confirmed (not its presence check). Say this **even
+   when there was nothing to backfill**, so its absence is visible rather than
+   silent.
+5. **Any check that passed on a recorded exception** — e.g. a branch mismatch
+   honoured by a `branch-override` row, naming the row and the branch.
+
+Then produce a plain-text summary of what this feature did. The summary is
 **not** a commit message template — it is reference material the
 developer adapts to whichever merge strategy their project uses
 (merge commit, squash, rebase, fast-forward — Dflow stays neutral).
@@ -282,7 +796,7 @@ Feature Goal: {1-2 sentences from _index.md Goals & Scope}
 Change Scope:
 - BC: {context-name}
 - Phase Count: {N} (phase-spec-{date1}-{slug1} ... phase-spec-{dateN}-{slugN})
-- Lightweight Changes: {n_t2} T2 lightweight specs + {n_t3} T3 inline rows
+- Lightweight Changes: {n_t2} T2 lightweight specs + {n_t3} T3 inline rows + {n_baseline} baseline rows
 
 Related BR-IDs (post-closeout state):
 - ADDED: BR-NN, BR-NN, ...
@@ -301,17 +815,70 @@ Next Steps (developer) — Integration / PR gate (needs network):
   you, but only when you explicitly ask; it never pushes on its own
 ```
 
+**Zero-phase minimal host — exact fields.** A zero-phase host does not fill the
+format above the way a phase-bearing one does. Its whole field set, and the
+authority on that shape, is `references/finish-feature-minimal-host.md`
+§ Step 5.
+
 Print the summary to the conversation; do not write it to a file (it is
 ephemeral closeout output).
 
-**→ Step Gate: Step 5 → Step 6**
-
-If the feature has `follow-up-of: {原 SPEC-ID}` in its Metadata, prompt
-the developer:
-> "This feature is a follow-up of `{原 SPEC-ID}`. Ready to update the
-> original feature's `_index.md` Follow-up Tracking row to mark this
-> follow-up as `completed`? `/dflow:next` to proceed (or skip if you
-> prefer to do it manually)."
+**A mainline hotfix that overlapped this feature.** Step 4 has already archived
+and committed this host — **it is frozen**, so anything a merge with the
+mainline leaves over is routed elsewhere and never recorded back into it. What
+is left over, how to classify it, and where each class goes are decided in
+`references/finish-feature-post-hoc-hotfix.md` § After closeout — the same
+branch file Step 1's hotfix callout dispatches to.
+
+**→ Post-Local-closeout confirmation: Step 5 → Step 6**
+
+**This stops and waits, and it is not a step gate.** By now the host is in
+`completed/` and its cursor reads `none`. **Confirming here updates no cursor**,
+and nothing below re-opens the workflow.
+
+If the feature has `follow-up-of` in its Metadata, prompt the developer —
+naming **every** original it lists (the field may be a YAML array):
+> "This feature is a follow-up of `{原 SPEC-ID}` (and `{原 SPEC-ID-2}`, …).
+> Ready to update **each** original feature's `_index.md` Follow-up Tracking row
+> to mark this follow-up as `completed`? (Or tell me you'll do it manually —
+> either way this tracking commit is **required** before closeout is complete;
+> see Step 6.)"
+
+**What this confirmation accepts** — this governs the follow-up prompt above; a
+host with no `follow-up-of` never reaches it and takes the branch below instead:
+
+- **Any affirmative reply → enter Step 6.** The verbal signals the guide lists
+  (`AI-AGENT-GUIDE.md` § Confirmation Signals) are illustrations, **not the
+  list**: a reply that plainly means "go ahead" counts however it is worded.
+  **Implicit confirmation counts too** — a developer who supplies what Step 6
+  needs, by naming the originals or by saying they will make the commit
+  themselves, has confirmed, not declined.
+- **`/dflow:next` and `/dflow:cancel` do not apply here.** No workflow is
+  active, and the guide requires both to be refused in that state. Refuse as the
+  guide says, **then ask this question again in plain language**. ⚠ **Do not
+  read either as a decline** — every earlier gate in this flow asked for
+  `/dflow:next`, so typing it here is a trained reflex, not an answer.
+- **A request to change something first** — revise what was asked about, then
+  ask again. Nothing already committed is undone, and the Local-closeout gate
+  stays satisfied.
+- **A plain decline, or "not now" — stop, and do not ask again.** There is
+  nothing to revise, so re-asking is the same question and reads as pressure.
+  Report that closeout is **not complete**, name the Step 6 flip as what is
+  still owed, and leave restarting to the developer.
+
+⚠ **Declining does not waive the tracking commit** — Step 6's flip is required
+either way. `references/finish-feature-follow-up.md` holds that rule and states
+what it takes to satisfy it.
+
+**The reverse link must have been opened, not only closed — and that is not
+minimal-host-only.** This confirmation point puts no host shape on
+`follow-up-of`, so a phase-bearing host can carry it too, but it has no single
+commit required to carry the row. The requirement still holds for that host; nothing in closeout
+tests it. **The opening half is confirmed for a phase-bearing follow-up host by
+`references/pr-review-checklist.md`'s "A follow-up's reverse link was opened,
+not only closed" item**, in that file's *Delegated to review by
+`finish-feature-flow.md`* block — it reads the branch history, which is exactly
+what closeout cannot take.
 
 If no `follow-up-of` field, skip Step 6 and announce closeout complete:
 > "`/dflow:finish-feature` complete for `{SPEC-ID}-{slug}`. Feature
@@ -323,29 +890,9 @@ If no `follow-up-of` field, skip Step 6 and announce closeout complete:
 **In-flight reminder** — after the closeout announcement (with or without
 Step 6), run the in-flight overview scan (see `AI-AGENT-GUIDE.md` § Status /
 Control Commands) and list any other unfinished features in `active/` and any
-in-flight feature / bugfix branches. Surfacing them at closeout is deliberate:
-attention is about to move elsewhere, and this is exactly where half-done work
-sinks.
+in-flight feature / bugfix branches.
 
 ## Step 6: Reverse-Update Follow-up Tracking (only if follow-up)
 
-For features that were created as follow-ups of an earlier completed
-feature, update the original feature's
-Follow-up Tracking table.
-
-1. Locate `dflow/specs/features/completed/{原 SPEC-ID}-{原 slug}/_index.md`
-2. Find the Follow-up Tracking section's row for this feature's SPEC-ID
-3. Flip Status → `completed`
-
-```bash
-# The AI makes the edit and may offer to commit it (Y / N), per the AI commit policy
-```
-
-After the update:
-> "Follow-up Tracking row in `{原 SPEC-ID}-{原 slug}/_index.md` updated
-> to Status = `completed`. Closeout complete."
-
-The connection is bidirectional and weakly redundant: the new feature's
-`follow-up-of` field is the authoritative source; the old feature's
-Follow-up Tracking row is a derived index. If they ever disagree, trust
-`follow-up-of`.
+**Open `references/finish-feature-follow-up.md` and follow it there.** This
+step's rules live in that file and are not repeated here.