dflow-sdd-ddd 0.13.0 → 0.15.0

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

@@ -11,7 +11,7 @@ Crossing any step gate above also updates the host feature's `_index.md` Resume
 
 All other step transitions are **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.
 
-**Ceremony adjustment when triggered by `/dflow:bug-fix`**: treat as lightweight — use the Lightweight Spec Template (see `templates/lightweight-spec.md`) instead of the full spec, and Step 4 (extraction) may default to "defer and record in tech-debt.md" unless the bug itself is in extractable logic. T2 still generates a concise `Implementation Tasks` checklist (see Step 4).
+**Ceremony when triggered by `/dflow:bug-fix`**: the command does **not** set a tier — run the same ordered cascade as any other modification (Part A below). Most functional defects land **T2**, so the Lightweight Spec Template (`templates/lightweight-spec.md`) is the usual outcome, and Step 4 (extraction) may default to "defer and record in tech-debt.md" unless the bug itself is in extractable logic; T2 still generates a concise `Implementation Tasks` checklist (see Step 4). That is the usual landing, not a fixed set: the cascade also puts defects below T2 and above it, through any of its steps — not only via a Domain structural redesign. Let the cascade decide.
 
 ## Mindset
 
@@ -31,40 +31,112 @@ through `/dflow:bug-fix`.
 
 This step has two parallel concerns:
 
-**Part A — Determine the Ceremony Tier (T1 / T2 / T3)**
-
-Dflow runs three ceremony tiers (full table in AI-AGENT-GUIDE.md § Ceremony Scaling).
-For a modification, AI judges which tier fits before deciding what to
-produce:
-
-| Tier | When to choose | Production |
-|---|---|---|
-| **T1 Heavy** | Architectural change / new BR / new Domain concept / new data structure → escalate to `/dflow:new-phase` (if extending an active feature) or `/dflow:new-feature` (if it's truly a new concern) | Full phase-spec via the appropriate flow |
-| **T2 Light** | Bug fix / UI input validation tweak / flow branch change — **has BR Delta** but no Domain or data-structure overhaul | Independent `lightweight-{date}-{slug}.md` placed in feature directory + outbound-link row in `_index.md` Lightweight Changes |
-| **T3 Trivial** | Button colour / copy fix / typo / formatting / pure comments — **all four T3 criteria** must hold (no BR change, no Domain concept change, no data structure change, only UI surface / comments / formatting) | **Inline row in `_index.md` Lightweight Changes only** (no independent spec file) |
-
-If any T3 criterion fails → drop to T2. If Domain / BR / data structure
-is touched → escalate to T1.
-
-**Below T3** (pure typo, formatting commit) → tell the developer Dflow
-doesn't track this and they can `git commit` directly.
+**Part A — Determine the Ceremony Tier (T1 / T2 / T3 / below workflow)**
+
+The tier has **one source**: `AI-AGENT-GUIDE.md` § Ceremony Scaling — the
+ordered cascade, steps 0–4, where **the first step that matches wins**. **Open
+that section and classify from it before going further.** Do not classify from
+memory, from this flow's step headings, or from a summary: the cases that
+actually decide a tier — new work versus a modification, what stays below
+workflow, how far a T3 may reach, inbound contracts, compound requests — are
+settled there, and a second copy of those criteria here would be a second answer
+to the same question.
+
+Two of the cascade's outcomes leave this flow entirely: genuinely new work
+(`/dflow:new-feature`) and a change Dflow does not track. Take those two exits as
+the guide states them rather than continuing through the steps below.
+
+**Tier-aware routing (don't run heavier ceremony than the tier needs):**
+
+- **T3** → locate the host, then **skip the Domain / extraction work**: go to the
+  branch gate, implement, and record the inline `_index.md` row. Do **not** create
+  or update any spec file, and do **not** run the Step 2 Document-Current-Behavior
+  baseline capture, the Step 3 delivery-layer analysis, or the Step 4
+  Evaluate-Extraction-Opportunity step (a T3 produces no baseline / extraction /
+  tech-debt entries unless the request is itself about them).
+- **T2** → a lightweight-spec at the depth the change needs; run the
+  behavior-capture / layer steps only where the change actually touches them.
+- **Observation-only (tier-exempt, step 0)** → record the capture where it belongs
+  (BC-layer `behavior.md` and `analysis.md`, `domain/analysis.md` for a
+  cross-context flow, for role reach and for whatever else no one context owns,
+  a hotspot in the copy that holds the knowledge it is stuck on,
+  `tech-debt.md`, the host's Resume Pointer) and stop there; create either
+  `analysis.md` from `templates/analysis.md` the first time there is something to
+  record.
+  When the baseline capture needs its own host (no active feature to attach
+  it to), open a **baseline minimal host**: a related **completed** feature makes it
+  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.
+  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
+  record on its own.
+- **T1** → escalate to `/dflow:new-phase` (extending an active feature) or
+  `/dflow:new-feature` (a truly new concern); full ceremony via that flow.
 
 **Part B — Locate the Feature this Change Belongs To**
 
-Walk through these in order:
+Walk through these in order to **classify** the change. Do **not** jump to
+Step 1.5 / 1.7 mid-list: the in-flight overlap scan (item 4) and the hotfix
+check below both run first, and the actual routing to Step 1.5 / 1.6 / 1.7 /
+1.8 / Step 2 happens at this step's closing transition.
 
 1. **Active features**: scan `dflow/specs/features/active/*/_index.md`. Does
    the change belong inside an existing active feature directory? If
    yes, use that as the host (T1 → `/dflow:new-phase`; T2 → place
    lightweight-spec inside; T3 → inline row in that `_index.md`).
+   **Exception — a minimal (zero-phase) host that has already taken its
+   implementation (or `spec-baseline`) checkpoint is not an eligible host.** A
+   minimal host is fixed at two commits and **every** Lightweight Changes row
+   must belong to the first one (Step 1.7), so once that checkpoint has landed
+   it can accept nothing further, however well it fits. It does **not** become
+   this change's host, and for the rest of this walk it does not count as one —
+   keep scanning, and let the routing at this step's closing transition proceed
+   as if it were not there. (Item 4 still surfaces it as an overlap; that is
+   information for the developer, not a host.) **Before** that checkpoint lands
+   the host is still open, and a compound request legitimately records more than
+   one **T2 / T3** artifact under it ("minimal means zero-phase, not
+   one-artifact", Step 1.7) — but **never a phase**: a minimal host is
+   *defined* by carrying no `phase-spec-*`, so it is not an eligible host for a
+   **T1** at any point, before or after that checkpoint. Keep scanning, exactly
+   as above.
+   **Exception — an already-merged T2 / T3 emergency fix** (the callout
+   below): it is already on the mainline, so an in-flight host cannot hold
+   it. It takes **Step 1.8** and gets a host of its own there, however well
+   a related active feature seems to fit — Step 1.8 says why. A **T1**
+   post-hoc is unaffected and uses this route normally.
 2. **Completed features**: scan `dflow/specs/features/completed/*/_index.md`
    Goals & Scope sections. If the change description is semantically
-   related to a completed feature, this becomes the **completed feature
-   reopen** scenario — go to Step 1.5 below.
-3. **Standalone**: if no related feature exists (active or completed),
-   this is a new concern. For T1, use `/dflow:new-feature`. For T2 / T3
-   on a standalone bug, see Step 1.5 — `/dflow:bug-fix` will create a
-   minimal feature directory to host the lightweight-spec.
+   related to a completed feature, this is the **completed-feature-reopen**
+   case (Step 1.5, routed to at the closing transition) — with **two
+   exceptions that never reach the Step 1.5 A/B/C prompt**: a **T2 / T3**
+   already-merged emergency fix documented after the fact takes **Step 1.8**
+   (the callout below), and an **observation-only baseline capture** takes
+   **Step 1.6** directly (Part A already routed it). This scan still runs for
+   both — each needs to know whether a related completed feature exists in
+   order to pick its own host (follow-up when one relates, standalone
+   otherwise). (A **T1** post-hoc is not a Step 1.8 case at all and does reach
+   Step 1.5 normally.)
+3. **Standalone**: if no related feature exists (active or completed) that can
+   host this change — a host item 1 ruled **ineligible** does not count as one —
+   this is a new concern. For T1, use `/dflow:new-feature`. A standalone
+   T2 / T3 needs a **minimal host feature directory** to hold the change —
+   its open → record → close lifecycle is the **standalone** case (Step 1.7,
+   routed to at the closing transition). Do not improvise a host and do not
+   leave an empty one behind. (If a related active feature genuinely fits
+   after all, use it as the host instead.)
+   **Exception — an already-merged T2 / T3 emergency fix** (the callout
+   below): finding nothing related does **not** make it an ordinary standalone.
+   It still routes through **Step 1.8**, which picks standalone itself and
+   supplies what this item cannot — the `reconciled (...)` checkpoint, the
+   per-tier hotfix trace, and reconcile-instead-of-re-implement. Coming to
+   Step 1.7 straight from here drops all of that. A **T1** post-hoc is
+   unaffected and uses this route normally. An observation-only **baseline
+   capture** with nothing related also reaches Step 1.7, but by **Part A's**
+   observation-only routing, not by this item — it is tier-exempt, so this
+   item's "standalone T2 / T3" wording does not describe it.
 4. **In-flight overlap scan (cross-branch)**: this branch's `active/` is not
    everything in flight. Run the in-flight scan (classification and dedup
    rules in `AI-AGENT-GUIDE.md` § Status / Control Commands) — `git fetch`
@@ -75,19 +147,51 @@ Walk through these in order:
    awaiting integration, or unknown — or an unfinished feature — semantically
    overlaps this change, surface it and wait for the developer to decide
    before creating anything new (stale branches are non-blocking).
+   **Exception — an already-merged T2 / T3 emergency fix** (the callout
+   below): run the scan, but a surfaced overlap is **information, not a
+   blocker**. The fix is already on the mainline, so no unmerged feature branch
+   can host it (Step 1.8 says why) — there is no routing choice left to wait
+   for. Report the overlap as notice that a merge reconciliation is coming
+   (`finish-feature-flow.md` Step 5), then let Step 1.8 proceed: do not offer
+   the in-flight feature as a host and do not hold host creation on it.
+   Step 1.7's overlap scan states the same rule at the point of use. A **T1**
+   post-hoc is unaffected and waits normally, and so does a **baseline
+   capture** — an overlapping in-flight feature may well be the right place to
+   attach the capture, which is precisely the decision this item asks for.
 
 > **Why scan completed too?** Completed features are frozen history
 > and **cannot accept** any T2 / T3 directly
 > (would break the "completed = frozen" semantic). Reopen routes through
-> a new follow-up feature instead — see Step 1.5.
-
-**→ Transition (step-internal)**: Step 1 complete. Announce "Step 1 complete (tier {T1/T2/T3} decided, host feature {SPEC-ID-slug / new / follow-up} identified). Entering Step 1.5 / Step 2 as appropriate." and continue.
-
-## Step 1.5: Completed-Feature Reopen Detection (only if Step 1 found a related completed feature)
+> a new follow-up feature instead — see Step 1.5, or Step 1.8 (**T2 / T3**
+> post-hoc hotfix) / Step 1.6 (baseline capture), which reach the same
+> follow-up host without the A/B/C prompt.
+
+> **Already-merged emergency fix?** If this change was hotfixed to production
+> **before** any Dflow ceremony ran and you are now documenting it after the
+> fact, **the tier Part A decided routes it**:
+> - **T2 / T3 post-hoc** → **Step 1.8** (post-hoc mode) rather than opening a
+>   fresh host here — it picks the host linkage and reconciles instead of
+>   re-implementing.
+> - **T1 post-hoc** → **not** a minimal-host case. It keeps the normal
+>   phase-bearing route (`/dflow:new-phase` or `/dflow:new-feature`, as Part A
+>   says), documenting the merged work there. Step 1.8 does not admit it, and
+>   a T1 must never be given a zero-phase host.
+>
+> Every pointer to Step 1.8 below carries this same T2 / T3 restriction.
+
+**→ Transition (step-internal)**: Step 1 complete. Announce "Step 1 complete (classification {T1/T2/T3 / baseline (tier-exempt)} decided, host feature {SPEC-ID-slug / new / follow-up} identified). Entering Step 1.5 / 1.6 / 1.7 / 1.8 / Step 2 as appropriate." and continue. An observation-only **baseline** capture carries **no tier** — announce it as `baseline (tier-exempt)`, never as T1 / T2 / T3.
+
+## Step 1.5: Completed-Feature Reopen Detection (only if Step 1 found a related completed feature — and this is a normal modification, not a T2 / T3 post-hoc hotfix or a baseline capture)
 
 If Step 1 Part B identified a semantically related completed feature, AI
 must explicitly disambiguate the user's intent **before** writing any
-files:
+files. **Skip this step entirely for a T2 / T3 post-hoc hotfix (Step 1.8) or an
+observation-only baseline capture (Part A routes it straight to Step 1.6)** —
+each picks its own host without this prompt (follow-up when a completed
+feature relates, standalone otherwise), and asking it anyway lets Option B
+file a related hotfix or capture as an independent standalone, losing the
+`follow-up-of` lineage and both reverse-link transitions. (A **T1** post-hoc
+is a normal reopen and belongs in this prompt.)
 
 ```
 "I notice this change overlaps with completed feature
@@ -98,10 +202,14 @@ Is this a follow-up to that feature, or an independent new concern?
 
 Option A — follow-up of `{SPEC-ID}-{slug}`
   → Build a new feature with a fresh SPEC-ID and `follow-up-of:
-    {SPEC-ID}` link back to the original. Inherits BR Snapshot baseline
-    from the BC's rules.md.
+    {SPEC-ID}` link back to the original. A BC-bearing follow-up inherits
+    its BR Snapshot baseline from the BC's rules.md; a no-BC follow-up
+    inherits nothing (see Step 1.6).
 Option B — independent new requirement
-  → Run /dflow:new-feature normally; no link to the completed feature.
+  → Route by the tier Part A already decided: T1 → run /dflow:new-feature
+    normally; T2 / T3 → this is an independent standalone change, go to
+    Step 1.7 (do NOT send a T2/T3 to new-feature — its intake would bounce
+    it right back here). No link to the completed feature either way.
 Option C — actually I think it's just a tiny lightweight tweak, no
             new feature needed
   → Refused. Completed features are frozen — even T3 inline rows must
@@ -113,54 +221,229 @@ Option C — actually I think it's just a tiny lightweight tweak, no
 **Wait for the developer's explicit choice (A / B / C).**
 
 If A (follow-up): proceed to **Step 1.6: Create Follow-up Feature**.
-If B (independent): tell the developer to `/dflow:new-feature`; this
-flow ends.
+If B (independent): route by tier — **T1** → `/dflow:new-feature` (this flow
+ends); **T2 / T3** → Step 1.7 (standalone minimal host).
 If C: gently re-explain (per decision 17) that completed features
 cannot accept direct T2 / T3 writes; offer Option A (follow-up with
 just a T3 inline row) as the lightweight equivalent.
 
-## Step 1.6: Create Follow-up Feature (only if user picked Option A)
-
-Build the follow-up feature using the same machinery as
-`/dflow:new-feature` (see `new-feature-flow.md` Steps 3.5 and 4), with
-these follow-up-specific differences:
-
-- **New SPEC-ID** (today's date sequence — do NOT reuse the original
-  SPEC-ID): e.g. original `SPEC-20260201-003-訂單折扣` → follow-up
-  `SPEC-20260424-002-訂單折扣-匯率擴充` (or any new slug)
-- **New slug**: not required to equal the original slug; pick whatever
-  best describes the follow-up scope
-- **`_index.md` Metadata**: `follow-up-of: {原 SPEC-ID}` is REQUIRED
-  (uncomment the optional line in the template; can be a YAML array if
-  the follow-up spans multiple originals)
-- **`_index.md` Goals & Scope** auto-prepended note:
-  ```
-  > 本 feature 為 `{原 SPEC-ID}-{原 slug}` 的 follow-up，原 feature
-  > 完成於 `{date}`，詳見 `completed/{原 SPEC-ID}-{原 slug}/_index.md`。
-  ```
-- **`_index.md` Current BR Snapshot baseline**: AI reads the BC's
-  `dflow/specs/domain/{context}/rules.md` and inherits the BRs that are
-  in-scope for this follow-up. Mark each inherited row with First Seen
-  = `inherited from rules.md` and Last Updated = (empty until the new
-  feature's first phase Delta touches it)
-
-**Reverse-link into the old `_index.md`**: AI also updates
-`dflow/specs/features/completed/{原 SPEC-ID}-{原 slug}/_index.md` —
-uncomment the Follow-up Tracking section (if not already present) and
-add a row:
-
-```
-| {新 SPEC-ID} | {新 slug} | {today} | in-progress |
-```
-
-This update is **part of the same change set** (offer to commit
-both at once; commit message should mention "Add follow-up reference to
-`{新 SPEC-ID}`"). The reverse link is a derived index — the new
-feature's `follow-up-of` field is the authoritative source.
-
-After the follow-up feature is set up, this flow hands off to the
-`/dflow:new-phase` flow (or stays in this flow at Step 2 for the first
-phase's content).
+## Step 1.6: Create Follow-up Feature (Step 1.5 Option A, a completed-only baseline capture, or the follow-up linkage chosen at Step 1.8)
+
+**Open `references/modify-existing-follow-up.md` and follow it there.** This
+step's rules live in that file and are not repeated here.
+
+
+## Step 1.7: Open a Standalone Minimal Host (no active feature hosts this change, and no completed feature is being taken as its follow-up)
+
+A standalone T2 / T3 — one with no active host and no completed feature
+taken as its follow-up — or a **baseline capture** with no related feature
+(brownfield) — has no feature that will host it, yet the host-ledger
+invariants (SPEC-ID, branch, Checkpoint Log, and the `_index.md` as the
+authoritative record) still apply. Open a **minimal host**: a feature
+directory that carries the change's lightweight artifacts — or one baseline
+capture — and **never a phase-spec**. The lifecycle is
+**open → record → close, two commits** (implementation — or baseline capture
+— then closeout).
+
+**"Minimal" means zero-phase, not one-artifact.** A compound standalone
+request is split into its atomic changes, each run through the cascade, with
+the **highest tier governing the host** and **each lower-tier part still
+recording its own artifact under that same host** (`AI-AGENT-GUIDE.md`
+§ Ceremony Scaling, Unit of classification). So one minimal host may carry a
+T2 lightweight-spec **and** one or more T3 inline rows — that is the correct
+shape, not a reason to open a second standalone host, and never a reason to
+drop the T3 evidence. A **baseline capture** is the exception: it is
+observation-only and carries its own capture alone.
+
+**Open — do this here, before writing the change:**
+
+1. **Confirm it is standalone.** The test is a **condition**, not a list of
+   routes: *no active feature hosts this change, and no completed feature is
+   being taken as its follow-up.* Whatever brought you here — Part B item 3
+   (nothing related found), Step 1.5 **Option B** (a related completed feature
+   the developer settled as an independent concern), Step 1.8's standalone
+   linkage, Part A's observation-only routing for a baseline with no related
+   feature, or a route added later — it belongs here exactly when that
+   condition holds. If an **active** feature genuinely hosts this change, stop
+   and record it there instead — do not open a redundant host. If a
+   **completed** feature is the right home, that is a follow-up (Step 1.6),
+   not a standalone. Do **not** re-run Step 1.5 to decide: an Option B arrival
+   already answered there, and Part A (baseline) / Step 1.8 (post-hoc hotfix)
+   each made the choice themselves.
+
+   **Overlap scan.** For every arrival except a T2 / T3 post-hoc hotfix, an
+   overlap the in-flight scan (Part B item 4) surfaced must be settled before
+   you create anything. For a **post-hoc hotfix** the condition above holds even when a
+   related feature is in flight — the fix is already merged on the mainline, so
+   no unmerged feature branch can host it (Step 1.8 says why) — and a surfaced
+   overlap is **information, not a blocker**: it tells the developer a merge
+   reconciliation is coming (`finish-feature-flow.md` Step 5).
+2. **Assign the identifiers** per `_conventions.md` § SPEC-ID Format
+   (`SPEC-YYYYMMDD-NNN`). For a **functional bug**, also assign its
+   **BUG-NUMBER** here (issue-tracker number, else `max+1` over the existing
+   `BUG-*` across `dflow/specs/**`, active + completed). Collision-check
+   **before creating anything** in step 3: no `active/` or `completed/`
+   directory and no local or remote branch already carries this SPEC-ID (or
+   BUG-NUMBER) or the branch name you will cut (stale branches are non-blocking
+   but are never reused).
+
+   **What a collision means depends on who owns the number.** A SPEC-ID, and a
+   **locally allocated** `max+1` BUG-NUMBER, are this flow's to hand out — a
+   collision is an allocation clash and nothing more, so re-assign the day
+   counter (or take the next BUG-NUMBER) and re-check. A **tracker-owned**
+   BUG-NUMBER is not: the issue tracker owns that identity, and renaming
+   tracker issue 42 to `BUG-43` to dodge a collision silently severs the record
+   from the issue it is about. **Never renumber a tracker-owned BUG-NUMBER.**
+   A collision there is reporting something real — this work is already
+   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.
+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
+   matter, Goals & Scope, Phase Specs, Current BR Snapshot, Lightweight
+   Changes, Checkpoint Log, Resume Pointer. (`Follow-up Tracking` is the
+   template's **optional** eighth section; a standalone host gets one only if
+   it later grows follow-ups of its own.) "Minimal" means the sections are
+   thin, not missing:
+   - Metadata `status: in-progress`; `branch:` = the branch you cut in
+     step 4. This field is **authoritative** — the branch gate and any
+     lightweight-spec frontmatter read their branch from it.
+   - Goals & Scope: one or two sentences. A standalone change need not touch
+     a bounded context; if it does not, say so plainly in Goals & Scope
+     rather than inventing one. (A baseline capture names the context it
+     captures — that is a real BC, not `none`.)
+   - Phase Specs: **leave the table empty** — a minimal host has no
+     phase-spec.
+   - Current BR Snapshot: fill it only if the change carries a BR delta; a
+     no-BR / T3 host leaves it empty (finish-feature Step 1 reads an
+     intentionally empty snapshot as a no-BR feature, not a validation
+     failure).
+   - Lightweight Changes, Checkpoint Log, Resume Pointer: start them; the
+     record and the two checkpoints land here as you go.
+4. **Branch gate — by change class.** A **functional bug** cuts
+   `bugfix/BUG-{NUMBER}-{slug}`, using the BUG-NUMBER assigned and
+   collision-checked in step 2. **Otherwise** — a standalone non-bug **T2 / T3**, or a **baseline
+   capture** — cut `feature/{SPEC-ID}-{slug}`. The `_index.md` `branch:` field must equal the
+   branch cut here. (See `references/git-integration.md` § Commit Checkpoints,
+   Branch Gate & AI Commits.)
+
+**Record + commit — rejoin the normal flow.** Follow this flow's tier-aware
+routing (Part A): a **T2** writes its lightweight-spec (classic BR form or
+the matching no-BR family variant — shapes are defined in
+`templates/lightweight-spec.md`) and runs the Step 2–6 record **to the depth
+Part A set** — that range names the route, not an instruction to run every item
+in it. In particular a **no-BC** T2 — one whose host Goals & Scope says it
+touches no bounded context — does not acquire one by walking Step 2: it does no
+Domain-file work there (Step 2 carries the same guard at its own site), so
+closeout's no-BC branch has nothing fictitious to skip past. A **T3** skips
+the Domain / extraction work and records an inline row in `_index.md`
+Lightweight Changes — **one row per atomic T3 change**, so a compound request
+records each of them here (see "minimal means zero-phase, not one-artifact"
+above). 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.)
+
+**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
+the outbound link to its lightweight-spec; a **baseline** capture's is its
+`Tier = baseline` row — all three are rows, and closeout requires one per
+artifact. Write them now, carrying the tier, the description and the
+implementation paths (for a baseline, the documents it captured into). The
+**only** part that may appear afterwards is the `Commit` cell, which cannot
+exist until its commit does: closeout's allow-list admits that cell and no other
+change **to the row**, so a row added after checkpoint 1 **blocks**. (The
+allow-list separately admits the Checkpoint Log rows, the Resume Pointer and the
+Current BR Snapshot — the finalization edits this step makes next.)
+
+**Name the implementation paths in the artifact.** Closeout's evidence checks
+assert that a commit *touches the implementation paths this change describes* —
+which is only mechanical if the artifact actually declares them. So a **T2**'s
+lightweight-spec names the source paths it changes, and a **T3**'s row
+Description names them alongside its one-line description and tag. Paths, not a
+diff — enough to compare a commit against. A **baseline capture** declares the
+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.
+
+**Commit evidence goes to two surfaces, always — every row, every tier.** They
+answer different questions, so filling one is never filling the other, and
+finish-feature Step 1 reads both:
+
+- **Checkpoint Log Result** — what happened at the *lifecycle checkpoint*.
+- **Lightweight Changes row `Commit`** — the commit carrying *that row's own
+  artifact*. Every row needs one; a blank cell fails closeout — **and so does a
+  placeholder**. `{hash}`, `{pending}`, `（待 commit）`, anything
+  `git cat-file -t` cannot resolve to a commit: it counts as **unfilled**, not
+  as filled. Leave the cell empty until the hash exists.
+
+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.
+- **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).
+- **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
+**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
+`reconciled ({merged-hotfix-hash})` — a declined documentation commit is
+completed by filling each Lightweight Changes row's `Commit` cell once the
+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
+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.
+
+In every case leave the host `status: in-progress` until closeout — do not flip
+the host to `completed` early and do not invent a spec file for a T3. Then
+`/dflow:finish-feature` performs the zero-phase closeout, and its **closeout
+commit is checkpoint 2** — it includes the `git mv` archival. The two
+checkpoints each record their own Checkpoint Log
+row (implementation or baseline capture, then closeout); they are asserted
+separately, never merged into one.
+
+## Step 1.8: Hotfix T2 / T3 Post-Hoc (documenting an already-merged emergency change that Part A classified T2 or T3)
+
+**Open `references/modify-existing-post-hoc-hotfix.md` and follow it there.**
+This step's rules live in that file and are not repeated here.
+
+⚠ Do not record a post-hoc hotfix from this heading alone. That file carries the
+host-linkage choice, the `reconciled ({merged-hotfix-hash})` checkpoint Result,
+the identity citation an **uncited** hash blocks closeout for, and the per-tier
+hotfix trace. Reconstructed from this heading, post-hoc mode collapses into
+re-implementing a fix that is already on the mainline — which Step 5's guard
+forbids and closeout inspects that checkpoint's changed paths for.
 
 ## Step 2: Document Current Behavior (if no spec exists)
 
@@ -176,7 +459,17 @@ Create a spec with status `in-progress` that includes:
 - Current business rules (extracted from delivery/entrypoint code)
 - The proposed change clearly marked — use the **Delta** format below
 
-If baseline domain docs are missing, create them from templates before filling content:
+> **No-BC guard — never manufacture a bounded context to satisfy this step.**
+> The creations below apply only when the change actually touches one. A
+> **no-BC** change — a standalone appearance sweep, say, whose host Goals &
+> Scope states it touches no bounded context — records **N/A** here and moves
+> on. Inventing a `{context}` it does not have plants fictitious Domain files
+> that finish-feature's no-BC closeout branch **skips past rather than
+> removes**, so they survive into the archive as permanent fiction. Same rule
+> as Step 6.3's tier-conditional note: state the verdict, do not manufacture
+> the artifact an item names.
+
+If baseline domain docs are missing **for a change that does touch a bounded context**, create them from templates before filling content:
 - `dflow/specs/domain/glossary.md` → `templates/glossary.md`
 - `dflow/specs/domain/{context}/models.md` → `templates/models.md`
 - `dflow/specs/domain/{context}/rules.md` → `templates/rules.md`
@@ -230,7 +523,8 @@ When the feature being modified has no existing spec, take the opportunity to do
 2. Extract all business rules found (if/else conditions, calculations, validations)
 3. Identify domain concepts (potential Entities, Value Objects, Services)
 4. Check for duplicated logic across pages
-5. Record findings in the appropriate domain docs (`models.md`, `rules.md`) and `tech-debt.md`
+5. Identify the system-level knowledge no single context document holds — an ordered flow that crosses contexts (always the domain-root copy), the lifecycle a status field moves through, a figure computed rather than stored, a mechanism no single rule explains, which roles reach the function (always the domain-root copy), and any spot in those this system keeps working around pending a domain decision (in the copy that holds the knowledge it is stuck on)
+6. Record findings in the appropriate domain docs (`models.md`, `rules.md`, and `analysis.md` — the owning context's copy, or `dflow/specs/domain/analysis.md` when no one context owns what you found, created from `templates/analysis.md` the first time there is something to record) and `tech-debt.md`
 
 This is an **opportunistic** strategy — "capture while we're already here." Do not force a full codebase scan; scope it to the modified feature and its immediate neighbors. Share what you find:
 
@@ -240,6 +534,7 @@ the related delivery/entrypoint code. I found:
 - 3 business rules in {entrypoint file} (documented in rules.md)
 - Duplicated validation logic shared with {other entrypoint} (recorded in tech-debt.md)
 - A potential Money value object hiding in the calculation at line {N}
+- The approval status moves through four states, two of them set by the batch job (recorded in analysis.md)
 This gives us a better baseline before we make our change."
 ```
 
@@ -275,6 +570,17 @@ Record each finding in `dflow/specs/migration/tech-debt.md` with:
 - [ ] {File}:{Line} — {Description} — Severity: {High|Medium|Low}
 ```
 
+### System-Level Knowledge to Record
+Look for what this change depends on and no single context document holds:
+- **Cross-context flows** — ordered steps owned by more than one context (always the domain-root copy)
+- **Lifecycles** — a status field and the transitions it moves through
+- **Read models and derived figures** — a number computed rather than stored
+- **Mechanisms** — behavior no single rule explains
+- **Function / role index** — which roles reach this function, and what data each one sees (always the domain-root copy)
+- **Hotspots** in any of the above — what this change worked around, pending a domain decision (in the copy that holds the knowledge it is stuck on)
+
+Record each finding in `dflow/specs/domain/{context}/analysis.md` when one context owns what it describes and in `dflow/specs/domain/analysis.md` when no one context does, creating the file from `templates/analysis.md` the first time there is something to record. That template's sections carry the notation.
+
 **→ Transition (step-internal)**: Step 3 complete. Announce "Step 3 complete (delivery/entrypoint layer analyzed, tech debt recorded). Entering Step 4: Evaluate Extraction Opportunity." and continue.
 
 ## Step 4: Evaluate Extraction Opportunity
@@ -358,12 +664,21 @@ If the lightweight checklist looks larger than a short-fix checklist, AI must pa
 Announce to developer:
 > "Extraction decision made — {extract now / defer and record}. Ready to start implementation? `/dflow:next` to proceed, or adjust the extraction scope first."
 
-> Branch gate (policy-aware): a feature branch is mandatory for every tier (T1 / T2 / T3) under both Git policies (`_conventions.md` § Git Policy). If you are already on this work's `feature/{SPEC-ID}-{slug}` (or `bugfix/{BUG-ID}-{slug}`) branch — e.g. the change belongs to the active feature you are already in — the gate is satisfied and nothing new is created. Otherwise (on the base branch the project cuts from, or an unrelated branch) the AI offers to create/switch to the correct branch, switch to an existing matching one, or override and record it in the `_index.md` Checkpoint Log. Dflow does not need to know which branch is your base. See `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI Commits.
+> Branch gate (policy-aware): a feature branch is mandatory for every tier (T1 / T2 / T3) under both Git policies (`_conventions.md` § Git Policy). If you are already on this work's `feature/{SPEC-ID}-{slug}` (or `bugfix/{BUG-ID}-{slug}`) branch — e.g. the change belongs to the active feature you are already in — the gate is satisfied and nothing new is created. Otherwise (on the base branch the project cuts from, or an unrelated branch) the AI offers to create/switch to the correct branch, switch to an existing matching one, or override and record it in the `_index.md` Checkpoint Log. Dflow does not need to know which branch is your base. **Minimal-host exception (Step 1.6 follow-up variant / Step 1.7 standalone / Step 1.8 post-hoc): the override is not available.** Those hosts assert branch equality against the `_index.md` `branch:` value they cut by change class, so working them on an unrelated branch would falsify the host's own authoritative field — switch to the host's branch instead. See `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI Commits.
 
 Wait for confirmation before entering Step 5.
 
 ## Step 5: Implement the Change
 
+> **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
+> of the checkpoint while breaking §8's reconciliation contract, which is why
+> closeout inspects that commit's changed paths.
+
 If extracting to Domain layer:
 
 ```csharp
@@ -402,7 +717,7 @@ 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 commit.
+> 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.
 
 Wait for confirmation before entering Step 6. This step gate is where the completion checklist is triggered — do not skip.
 
@@ -410,16 +725,19 @@ Wait for confirmation before entering Step 6. This step gate is where the comple
 
 Triggered by the Step 5 → Step 6 Step Gate. AI runs the completion checklist in the order below; do **not** skip a section. `Implementation Tasks` checks apply to both `phase-spec.md` and `lightweight-spec.md` (T3 inline-only has no task section).
 
+> **Tier-conditional (matches the Part A routing — the checklist must not undo it).** A **T3** produces no spec file and no Domain-document updates: for a T3, 6.1's spec and Domain items and all of 6.3 are **N/A** except the `_index.md` row — which is **already written** (Step 1.7 for a minimal host, at record time otherwise), so this checklist **re-verifies** it and never creates it — record them as N/A, and do not create a spec or a Domain file to make an item pass. A **baseline capture** is tier-exempt and likewise produces **no spec file**: 6.1's spec items and 6.3's spec item are **N/A** — do not create one to make an item pass. Its **Domain documents are not N/A**, but this checklist does not create them either: the capture wrote them before checkpoint 1, so here they are **re-verified**, exactly as a T3's row is. A **no-BR family T2** has a spec but no BR delta: its **BR-derived** items are N/A (6.1 says the same). "No BR delta" is **not** "no Domain delta" — decide each Domain document from the actual change, not from the BR line. A family (b) contract change that touches a documented behavior still updates `behavior.md`; a family (e) defect in an extracted model still updates `models.md` if the shape moved. "Do not skip a section" means work through every section and state each verdict — including N/A — not manufacture the artifact an item names.
+
 ### 6.1 Verification — AI runs independently
 
 Items marked *(post-6.3)* are re-verified after the documentation merge in 6.3 lands:
 
 - [ ] Every ADDED / MODIFIED / REMOVED / RENAMED entry in the Delta section is covered by implementation or tests
+- [ ] **No-BR family evidence** — when the spec's Behavior Delta is a `BR:` / `BR Delta:` none line instead of delta entries, verify *that family's* evidence is present and substantive: (a) `Output Footprint`; (b) `Contract Delta` + `**Downstream consumers**`; (c) `Operational Rationale` + `**Trace**`; (d) `Performance Delta` + `**SLA / resource context**`; (e) `Governing BR-IDs` + root cause + a regression check; (f) `Change Rationale` with `**Before**` / `**After**` + `**Regression**`. For such a spec the **BR-derived** items in this checklist are **N/A** — say so explicitly rather than passing them on an empty delta set, and never add a BR or a `behavior.md` anchor just to make an item pass. Domain documents are **not** automatically N/A: judge each from the actual change (a family (b) contract change that touches a documented behavior still updates `behavior.md`). When a change matches more than one family (an operational refactor that also shifts SLA), **every** matching family's evidence must be present — one BR line, all matching evidence sections. A spec written in the classic BR-delta form, or a bug spec written with the older single `BR:` line, is accepted as-is
 - [ ] Domain layer has **no** delivery-framework references (grep `src/Domain/`)
 - [ ] Extracted logic (if Step 4 decided "extract now") lives under `src/Domain/` as framework-pure code
 - [ ] `Implementation Tasks` section (`phase-spec.md` or `lightweight-spec.md`): all tasks checked, or unchecked items explicitly labelled as follow-up
 - [ ] *(post-6.3)* `dflow/specs/domain/{context}/behavior.md` has a section anchor for every `BR-*` in ADDED / MODIFIED entries; REMOVED entries' anchors have been deleted (mechanical input for `/dflow:verify`)
-- [ ] *(post-6.3)* every ADDED / MODIFIED / RENAMED BR's `Last updated` in `dflow/specs/domain/{context}/rules.md` is later than this spec's `created` date (mechanical drift guard)
+- [ ] *(post-6.3)* every ADDED / MODIFIED / RENAMED BR's `Last updated` in `dflow/specs/domain/{context}/rules.md` is **not earlier than** this spec's `created` date (mechanical drift guard). ⚠ **Not earlier**, not *later*: `Last updated` is set to **today**, so a spec created and swept on the same day — the modal case for this tier — gives `Last updated == created`. Requiring *later* blocks it with no legitimate escape (post-dating the row fabricates a record). Same operator as `new-feature-flow.md` § 8.1; the two must not diverge.
 
 If any item fails, report the gap and pause — don't proceed to 6.2.
 
@@ -435,10 +753,15 @@ Ask these one-by-one.
 
 ### 6.3 Documentation updates
 
-- [ ] Update or create the feature / bug spec; set `status: completed`
+> **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)
+- [ ] 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
+- [ ] `dflow/specs/domain/{context}/analysis.md` — lifecycles, derived figures or mechanisms no single rule explains this change found or altered, in the owning context's copy, which may not be this host's; any spot this change worked around pending a domain decision, in those or in a rule or unrecorded knowledge that belongs there; and any open row there this change settled (created from `templates/analysis.md` the first time there is something to record; N/A when there is none)
 - [ ] `dflow/specs/domain/glossary.md` — new / renamed terms (mirror any RENAMED delta entries here)
+- [ ] `dflow/specs/domain/analysis.md` — ordered cross-context flows, role reach, or anything else no one context owns, that this change found or altered; any spot this change worked around pending a domain decision, in those or in unrecorded knowledge that belongs here; and any open row there this change settled (created from `templates/analysis.md` the first time there is something to record; N/A when there is none)
 - [ ] `dflow/specs/domain/{context}/behavior.md` — update scenarios to reflect Delta result (merge final state, not Delta markup). Sub-steps:
       - Promote any Activity 3 (Spec Writing) draft sections (from B3 mid-sync) to formal sections
       - Update the corresponding `rules.md` anchor's `last-updated` date (B4)
@@ -469,9 +792,11 @@ file move at this point. The whole feature directory moves to
 If this modification was a **T3 inline-only** change, no spec file
 exists — archival is just leaving the row in `_index.md` Lightweight Changes.
 
-If the modification was a **standalone follow-up feature** (created
-via Step 1.6), the same rule applies: this flow does not archive the
-new follow-up directory; that happens at `/dflow:finish-feature` time.
+If the modification opened a **standalone minimal host** (Step 1.7) or a
+**follow-up feature** (created via Step 1.6, including its minimal
+variant), the same rule applies: this flow does not archive the host
+directory — the closeout `git mv` happens at `/dflow:finish-feature` time
+(checkpoint 2 of the two-checkpoint minimal-host lifecycle).
 
 Only announce "change complete" after the appropriate archival step
 above (or the Step 6.3 docs sweep) is done.