dflow-sdd-ddd 0.14.0 → 0.16.0

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

@@ -0,0 +1,104 @@
+# Step 1.6: Create Follow-up Feature — Greenfield Clean Architecture
+
+Branch file of `references/modify-existing-flow.md`. It **adds** the
+follow-up-specific rules; it does not restate or override anything in that flow.
+
+**You are here because** that flow's Step 1.6 dispatched you — it owns whether
+this route applies, and what has already been decided by the time you arrive.
+
+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. **Use the tier Part A already decided.**
+This is the same change Part A classified, and re-running the cascade on it can
+return a second answer to one question. Re-enter Part A **only** when the
+Step 1.5 A/B/C discussion materially changed the scope (work added or dropped);
+say so explicitly when you do, and let that re-run **replace** the earlier tier
+rather than stand beside it. On that tier: a **T1** follow-up takes the full
+new-feature machinery below; a **T2 / T3** follow-up takes
+the **minimal (zero-phase) variant** described after the reverse-link step —
+it does **not** delegate new-feature Step 4's unconditional first phase-spec.
+A **post-hoc hotfix** whose host linkage Step 1.8 resolved to *follow-up*
+also arrives here (never through the Step 1.5 prompt, and always T2 / T3, so
+always the minimal variant); its first checkpoint keeps the `implementation`
+name but carries Result `reconciled (...)` per Step 1.8.
+
+- **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** (**BC-bearing follow-up only**):
+  if the follow-up touches a bounded context, 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 — or, for a minimal follow-up, its
+  lightweight-spec's delta — touches it). For a **no-BC follow-up** (the
+  minimal variant on a completed no-BC host), leave the Current BR Snapshot
+  **empty** — do not read or fabricate a BC's `rules.md`.
+
+**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. When `follow-up-of` names **more than one** original (it may be a
+YAML array), do this in **every** one of them; a parent left without its row
+never gets the `absent → in-progress → completed` transition the contract
+requires, and on a **minimal** follow-up host finish-feature Step 1 blocks
+closeout on it (that check is scoped "Minimal host (zero-phase), follow-up
+only" and proves the *opening* half; on a phase-bearing follow-up Step 6 still
+flips and verifies the closing half, but nothing checks that the row was ever
+opened as `in-progress`):
+
+```
+| {新 SPEC-ID} | {新 slug} | {today} | in-progress |
+```
+
+This update is **part of the same change set** as opening the host. For a
+**T1** follow-up the AI may offer to commit the new host and this initial
+`absent → in-progress` reverse-link together (commit message should mention
+"Add follow-up reference to `{新 SPEC-ID}`"). For the **minimal (T2 / T3)
+variant** the AI does **not** offer a separate host-open commit — the
+initial reverse-link edit rides along in the implementation checkpoint (see
+the variant paragraph below), keeping the follow-up at exactly two host
+checkpoints. The reverse link is a derived index — the new feature's
+`follow-up-of` field is the authoritative source.
+
+After a **T1** 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).
+
+**Minimal (zero-phase) follow-up variant (T2 / T3).** When the follow-up
+change is itself lightweight, do **not** delegate new-feature Step 4 (which
+would create an unconditional first phase-spec). Instead treat the follow-up
+host exactly like a standalone minimal host — open it via **Step 1.7's
+mechanics, steps 2–4 only** (assign identifiers + collision check, create the
+minimal `_index.md` with an empty Phase Specs table, branch gate **by change
+class**: `bugfix/BUG-{NUMBER}-{slug}` for a functional bug,
+`feature/{SPEC-ID}-{slug}` otherwise — this **overrides** new-feature's
+hardcoded `feature/` branch). Step 1.7's **step 1 does not apply**: it is the
+standalone-classification gate, and this caller has already been classified as
+a follow-up. Everything Step 1.7 states **after** step 4 *does* apply
+unchanged — every artifact's row written before checkpoint 1, the
+implementation-path declaration, the finalization before checkpoint 1 and
+"Finalize + close" after it, and the two
+commit-evidence surfaces — because finish-feature reads for all of it on a
+follow-up host exactly as on a standalone one. Then record the change's
+artifacts — a T2 lightweight-spec, one
+or more T3 inline rows, or both for a compound follow-up (Step 1.7's
+"minimal means zero-phase, not one-artifact") — and close with
+`/dflow:finish-feature`. The lifecycle is **two host checkpoints**
+(implementation, then closeout) **plus one post-closeout reverse-link flip
+tracking commit** — the flip (the original feature's Follow-up Tracking row
+`in-progress → completed`, done by `/dflow:finish-feature` Step 6) is a
+**sanctioned post-completion mutation, not a host checkpoint**, and is
+recorded in **neither** the follow-up host's Checkpoint Log **nor** the
+original feature's. Option C of Step 1.5 ("a follow-up containing only one
+T3 row") lands here.

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

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

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

@@ -14,7 +14,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**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (T1 / T2 / T3) only applies to `/dflow:modify-existing` (see `references/modify-existing-flow.md` and AI-AGENT-GUIDE.md § Ceremony Scaling).
+**Ceremony**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (the ordered cascade — T1 / T2 / T3 / below workflow) applies to `/dflow:modify-existing` and `/dflow:bug-fix`; the criteria live in AI-AGENT-GUIDE.md § Ceremony Scaling, and `references/modify-existing-flow.md` is where they are applied.
 
 ## Step 1: Intake — Understand the Request
 
@@ -28,6 +28,25 @@ Ask naturally:
 2. **Who needs it?** Stakeholder or user role.
 3. **Why now?** Priority and urgency.
 
+> **`/dflow:new-feature` is always T1 — it does not re-run the cascade.**
+> Entering here declares "genuinely new work" (a new capability, page, or
+> navigable surface). If the request is really a **modification** of existing
+> behaviour — a tweak, a bug fix, an appearance change, or anything that would
+> land at T2 / T3 / below-workflow — it belongs in `/dflow:modify-existing`,
+> whose Step 1 cascade (step 0) is the only place a misroute is caught. So
+> sanity-check at intake: if this looks like a small change to something that
+> already exists, redirect to `/dflow:modify-existing` rather than minting a T1
+> feature. ⚠ **Do not redirect a request that already came from there.** A
+> `/dflow:modify-existing` or `/dflow:bug-fix` request the cascade landed at T1
+> — including one a project convention escalated to T1, which the overlay may
+> only ever raise — is routed here **by** step 0 and has already been caught;
+> sending it back is a loop, because step 0 provably returns the same answer.
+> `AI-AGENT-GUIDE.md` § Ceremony Scaling's T1 row says so directly. The guard
+> is for a request that arrived at `/dflow:new-feature` **without** passing the
+> cascade. (A follow-up to a *completed* feature is the one new-feature-shaped
+> case that may still be lightweight — it arrives through `modify-existing`
+> Step 1.6's minimal variant, not here.)
+
 Check existing assets:
 - Search `dflow/specs/domain/` for related concepts
 - Search `dflow/specs/features/` for related features
@@ -148,6 +167,20 @@ valid outcome; extending silently is not.
 - Service interfaces for external systems
 - Define in Domain layer, implement in Infrastructure
 
+### System-Level Knowledge
+```
+"Which parts of this feature will no single context document hold?"
+```
+
+- What crosses a bounded context, and what does each step hand to the next? (always the domain-root copy)
+- Which status fields does this feature introduce, and what transitions do they move through?
+- Which figures are derived rather than stored?
+- Who reaches this feature, and what data scope does each role see? (always the domain-root copy)
+
+Record each answer 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.
+
+Domain events keep their definitions and payloads in `events.md`; name them in the flow here instead of restating them.
+
 If foundational domain docs are missing, create them from templates before writing content:
 - `dflow/specs/domain/glossary.md` → `templates/glossary.md`
 - `dflow/specs/domain/{context}/models.md` → `templates/models.md`
@@ -159,7 +192,7 @@ If foundational domain docs are missing, create them from templates before writi
 **→ Step Gate: Step 3 → Step 3.5**
 
 Announce to developer:
-> "Aggregate / VO / Events identified. Before I create any files, let me confirm the SPEC-ID, slug, directory name, and branch name with you (Step 3.5). `/dflow:next` to proceed."
+> "Aggregate / VO / Events identified. Before I create the feature directory or branch, let me confirm the SPEC-ID, slug, directory name, and branch name with you (Step 3.5). `/dflow:next` to proceed."
 
 Wait for confirmation before entering Step 3.5.
 
@@ -208,7 +241,30 @@ If the developer asks to change the slug, re-propose and re-confirm.
 
 ## Step 4: Write the Spec
 
-Create the **feature directory** + **`_index.md`** + **first phase-spec**:
+> **Minimal hosts do not come here (defensive guard).** Step 4 creates a first
+> phase-spec, which only a genuinely **T1** new feature has. A **minimal host**
+> is zero-phase and is recorded through its own path in `modify-existing-flow.md`,
+> **not here**: Step 1.6 explicitly does **not** delegate to this step. If you
+> reached Step 4 while handling a minimal / zero-phase host, **stop and re-enter
+> `modify-existing-flow.md` at Step 1** — *not* at Step 1.6, 1.7 or 1.8.
+>
+> Those steps each assume work Step 1 has already done: Part A has decided the
+> tier, and Part B has done the host linkage. An entry that arrived *here* ran
+> neither, so recovering into one of them skips the authoritative cascade and
+> the completed-feature scan — which is how a change that should have been a
+> follow-up gets archived as an unlinked standalone. Step 1 routes it from
+> there, and its Part B hotfix callout is what sends a **T2 / T3 post-hoc**
+> to Step 1.8 — the only route that attaches `reconciled
+> ({merged-hotfix-hash})`, the identity citation, and the per-tier hotfix
+> trace, all of which a host recovered straight into 1.6 / 1.7 would silently
+> lack. (A **T1** post-hoc is not a minimal host and is not this guard's
+> business.)
+>
+> Either way, do not create a phase-spec, and do not treat this step as a
+> zero-phase execution path.
+
+Create the **feature directory** + **`_index.md`** + **first phase-spec** (T1
+new feature):
 
 ```
 dflow/specs/features/active/{SPEC-ID}-{slug}/
@@ -216,6 +272,8 @@ dflow/specs/features/active/{SPEC-ID}-{slug}/
 └── phase-spec-{YYYY-MM-DD}-{slug}.md
 ```
 
+> **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).
+
 1. **Create the directory**: `dflow/specs/features/active/{SPEC-ID}-{slug}/`
 2. **Create `_index.md`** using `templates/_index.md`:
    - Metadata: fill `spec-id`, `slug`, `status: in-progress`, `created`, `branch`
@@ -391,7 +449,7 @@ During implementation, continuously verify:
 **→ Step Gate: Step 7 → Step 8**
 
 Announce to developer:
-> "Implementation appears complete across all four layers. Ready to run the completion checklist (verify against spec, update domain docs + context-map, ensure test coverage, archive the spec)? `/dflow:next` to proceed."
+> "Implementation appears complete across all four layers. Ready to run the completion checklist (verify against spec, update domain docs + context-map, ensure test coverage, complete the phase)? `/dflow:next` to proceed."
 
 > Commit checkpoint (T1 milestone 2 of 3): offer to commit the implementation, then record the result in the `_index.md` Checkpoint Log. Milestone 3 (closeout) is the `/dflow:finish-feature` checkpoint.
 
@@ -414,7 +472,7 @@ AI reports `✓` / `✗` for every item before touching docs. Items marked *(pos
 - [ ] Aggregate invariants still hold after the change (all state changes go through methods, no public setters)
 - [ ] ORM / persistence mapping is kept outside Domain entities (no persistence attributes/annotations on Domain entities)
 - [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` contains a section anchor for every `BR-*` introduced by this spec (mechanical input for `/dflow:verify`)
-- [ ] *(post-8.3)* `dflow/specs/domain/{context}/rules.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
+- [ ] *(post-8.3)* for **every `BR-*` this spec introduced or changed**, that rule's row in `dflow/specs/domain/{context}/rules.md` carries a `Last updated` not earlier than this spec's `created` date (mechanical drift guard). ⚠ Quantified per-BR on purpose, like the item above: a T1 may legitimately introduce **no** BR (§ Ceremony Scaling step 0 admits it), and this then passes vacuously rather than blocking. `rules.md` has no document-level `last-updated` — it is a column in the Rule Index, which is what 8.3 sub-step B4 updates.
 
 If any item fails, report the gap and pause — don't proceed to 8.2.
 
@@ -433,44 +491,67 @@ Ask these one-by-one; do not dump all six at once.
 
 ### 8.3 Documentation updates
 
+> **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).
+
 - [ ] `dflow/specs/domain/glossary.md` — new terms added
+- [ ] `dflow/specs/domain/analysis.md` — ordered cross-context flows, role reach, or anything else no one context owns, that this feature introduced, found or altered; any spot this feature worked around pending a domain decision, in those or in unrecorded knowledge that belongs here; and any open row there this feature settled (created from `templates/analysis.md` the first time there is something to record)
 - [ ] `dflow/specs/domain/{context}/models.md` — model definitions updated
+- [ ] `dflow/specs/domain/{context}/analysis.md` — lifecycles, derived figures or mechanisms no single rule explains this feature introduced, found or altered, in the owning context's copy, which may not be this host's; any spot this feature worked around pending a domain decision, in those or in a rule or unrecorded knowledge that belongs there; and any open row there this feature settled (created from `templates/analysis.md` the first time there is something to record) — including the lifecycle any `aggregate-design.md` worksheet recorded as State Transition Methods: that worksheet freezes with the feature directory, this file does not
 - [ ] `dflow/specs/domain/{context}/rules.md` — business rules updated
 - [ ] `dflow/specs/domain/{context}/behavior.md` — merge completed spec's Given/When/Then scenarios (incl. Aggregate transitions + Events) into consolidated behavior. 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)
 - [ ] `behavior.md` draft cleanup — if the spec was abandoned mid-way, keep the `## 提案中變更` section's history or explicitly REMOVE it
+- [ ] `analysis.md`, at either of its two paths — re-check every entry this feature recorded before building: an entry for what the feature was to add or change against what was built (corrected where the build differs, removed where nothing was built for it), and an entry for something already in the system against the system as it now stands (corrected where this feature changed it, never removed because this feature built nothing for it). Read the entries in the file, not in a diff: a checkpoint may already have committed them.
 - [ ] `dflow/specs/domain/{context}/events.md` — Domain Events updated
 - [ ] `dflow/specs/domain/context-map.md` — updated if cross-context interaction was added or changed
 - [ ] `dflow/specs/architecture/tech-debt.md` — tech debt discovered during implementation recorded
 
-### 8.4 Archival
-
-For a single-phase feature, this is the closeout point. If the feature has
-later phases still ahead, this phase is complete but the feature is not —
-don't archive yet; run `/dflow:new-phase` to start the next phase, not
-`/dflow:finish-feature` yet. For a multi-phase feature, the developer
-typically reaches this point at the end of the final phase — at which time
-`/dflow:finish-feature` is the recommended trigger (it bundles steps 8.1 /
-8.2 verification, BC sync, and archival into one explicit ceremony). Either
-path is acceptable; pick the one that matches the developer's habit.
-
-- [ ] `_index.md` `status` field changed to `completed`
-- [ ] All `phase-spec-*.md` files in the feature directory have `status:
-      completed` in their frontmatter
-- [ ] **Whole feature directory** moved from `dflow/specs/features/active/`
-      to `dflow/specs/features/completed/` using `git mv` (preserves rename
-      tracking — see `references/git-integration.md` § "Directory Moves
-      Must Use git mv"):
-      ```
-      git mv dflow/specs/features/active/{SPEC-ID}-{slug} \
-             dflow/specs/features/completed/{SPEC-ID}-{slug}
-      ```
-
-> **Recommended path for multi-phase features**: instead of doing
-> 8.1–8.4 manually at the end of every phase, run `/dflow:finish-feature`
-> once the feature's last phase is complete. It executes the same checks
-> + BC sync + `git mv` + emits an Integration Summary. See
-> `references/finish-feature-flow.md`.
-
-Only announce "feature complete" after 8.4 is done.
+### 8.4 Phase completion and handoff
+
+This step completes the phase and hands the feature on. It does not close the
+feature out: `/dflow:finish-feature` is the only closeout path — it flips the
+`_index.md` `status`, moves the feature directory to `completed/`, and takes
+the closeout commit checkpoint.
+
+**Complete this phase** — all four items, whether or not another phase
+follows:
+
+- [ ] This phase-spec's frontmatter `status` changed from `in-progress` to
+      `completed`
+- [ ] This phase's row in the `_index.md` Phase Specs table changed from
+      `in-progress` to `completed`
+- [ ] `_index.md` Current BR Snapshot reconciled against this phase-spec's
+      **Business Rules** section — this is the feature's first phase, so it
+      has no Delta from prior phases. If implementation changed a rule, update
+      the phase-spec first, then reconcile. Touch only this phase's rows: a
+      row that another change in this host wrote — a lightweight change
+      hosted under this feature, for example — stays as it is. Where this
+      phase and such a change both changed the same rule, keep the later
+      change's text; if the host's record does not show which change came
+      later, ask the developer which text is current instead of choosing.
+- [ ] `_index.md` Resume Pointer: rewrite **both** narrative lines — Current
+      Progress says this phase is completed, and Next Action names the
+      command the handoff below picks. Step 4 wrote "phase-1 in progress:
+      drafting phase-spec." and "finish phase-spec, then implement …" into
+      these two lines; either one left standing reads as open work.
+
+`/dflow:finish-feature` relies on these four whenever the feature reaches it,
+next or after later phases. Its Step 1 checks the phase-spec `status`, the
+Phase Specs row and the Resume Pointer, and stops closeout on a stale one.
+Its Step 3 syncs the Current BR Snapshot into the bounded context as it
+stands, without re-deriving it from the phase-specs.
+
+`Implementation Tasks` is not on this list: 8.1 verified it, and 8.2 may have
+collapsed or removed it by team convention. BC document sync is not on it
+either: 8.3 did it.
+
+**Hand off:**
+
+- Another phase is still ahead → run `/dflow:new-phase` next.
+- No further phase — a single-phase feature, or this was the last phase →
+  run `/dflow:finish-feature` next. It is the only closeout path.
+
+Announce that this phase is completed and name the next command. Do not
+announce the feature as complete: `/dflow:finish-feature` announces that once
+its closeout is complete.