dflow-sdd-ddd 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -6,6 +6,42 @@
 
 ---
 
+## 0.12.0 — 2026-07-09 — 模型生命週期閉環（長時流程 + 模型重審）+ 收尾守門與跨 session 連續性
+
+**Proposals**：PROPOSAL-067（skill source 舊制 ID 與範例正確性清理）、PROPOSAL-068（finish-feature 收尾完整性守門）、PROPOSAL-069（跨分支 / 跨 session 連續性 Phase 1）、PROPOSAL-070（Long-Running Processes 判準與最簡階梯）、PROPOSAL-071（模型修正判準）
+
+本版兩條主線：
+
+1. **DDD 指引優化線收官**（070 / 071）——modeling guide 補上模型生命週期的最後兩塊：跨 Aggregate 多步驟流程的協調與補償邏輯住哪（Long-Running Processes），以及既有模型何時該被重審（Revising an Established Model）。至此生命週期閉環：形成（061 萌芽）→ 使用 → 漂移偵測（verify）→ 重審（071）。
+2. **Workflow 收尾與連續性**（068 / 069）——finish-feature 收尾產物守門 + 跨分支 / 跨 session 的在途工作可見性。
+
+### 新功能 / 行為改善（DDD 建模指引）
+
+- **Long-Running Processes（長時流程）**（PROPOSAL-070）：guide 新段——判準先行（「後面失敗需要撤銷前面 → 你要的是 process，不是 event chain」+ 訊號清單與 fire-and-forget 負向守句）、三階梯（owning aggregate status 欄位 → 專責 process aggregate → workflow framework = ADR 決策，比照 outbox / Event Sourcing 防呆先例）、補償 BR 化（補償是新的 domain fact，非 rollback）、deadline 分層（偵測是排程、決策是 domain 規則）。同檔補 Pattern Selection flowchart 與 Domain Services 的 stateful-process 守句、Common Mistakes #11（補償邏輯散落 handler）；greenfield `events.md` 模板加指路一句。
+- **Revising an Established Model（重審既有模型）**（PROPOSAL-071）：guide 新段——重讀規則（擴充既有 Aggregate 前重讀其 Design Decisions 與再評估條件）、六個「模型在抵抗」訊號（生命週期必填欄位 nullable 化、判別欄增生、同軸第 3+ 業務分支、術語加限定詞、再評估條件命中、跨 instance 交易壓力）+ 無界集合 cross-ref、兩階梯（spec 內具名記錄「照舊 / 拆分 / 改名 + 理由」→ 修正當獨立變更走 T1）、雙反空轉守句（訊號是觸發器不是排程；觸發的是重審不是重設計）。Design Questions 加第 7 問（把再評估條件寫進 worksheet）、Common Mistakes #12；兩軌 new-feature / modify-existing flow 在 Aggregate 歸屬時刻加完整重讀掛鉤（brownfield 與 061 萌芽判準成對）、兩軌 new-phase 加一句指路；`aggregate-design.md` 模板提示再評估條件。
+
+### Workflow 強化
+
+- **finish-feature 收尾完整性守門**（PROPOSAL-068）：closeout 產物順序重排與雙驗證——closeout 列先寫（明文無 hash 例外）→ 整目錄 `git add` → commit → `git show HEAD:` 單 blob 同時驗 status 與 closeout 列，gate 以驗證通過為準；lightweight / BUG spec 驗證補進 Step 1；選配 `Dflow-Checkpoint` trailer 與 checkpoint 帳原則明文化（dist issue #5 的 skill 面收斂）。
+- **跨分支 / 跨 session 連續性 Phase 1**（PROPOSAL-069）：`_index.md` Resume Pointer 加持久化 workflow cursor（Active Workflow / Current Step / Gates Passed / Awaiting；宣告與推導證據交叉、證據優先）；`/dflow:status` 改兩段式——在途總覽（本分支 active features + 跨分支 git 掃描分類）+ 當前 feature 細節；intake 重疊掃描（dist issue #4 部分收）。
+
+### 清理 / 修正
+
+- **skill source 舊制 ID 與範例正確性**（PROPOSAL-067）：flow / 模板殘留的 pre-SPEC-ID 舊制全面換為 SPEC-format（frontmatter、branch 命名、範例 ID）、greenfield trunk Hotfixes 依 severity 雙軌命名、guide 內 `DateRange` 範例改合法 C#。
+- `scripts/check-cross-refs.mjs` Windows 路徑 bug 修正（dev-only，不影響套件使用者）。
+
+### 升級提醒
+
+- 既有專案重跑 `dflow configure-agents` 後，bundle 內 `ddd-modeling-guide.md` 取得兩個新段落（Long-Running Processes、Revising an Established Model），六個 flow 檔取得既有模型重讀掛鉤，`aggregate-design.md` / `events.md` 模板取得新提示句。
+
+### 驗證
+
+- P-067〜071 全程 proposal-stage + implementation-stage cross-model review 收斂（各案 1〜3 輪迭代至 zero findings）；cold-eye gate 依風險分級 skip（純散文、不動 runtime，user 逐案核可）。
+- **P-071 為證據驅動成案**：sim-test R4（seeded 既有專案 + 事前登錄 per-signal rubric）判定「AI 不回頭質疑既有模型決策」盲區成立（H1）後才寫指引；P-070 於同一 R4 中獲落地當日後驗（dev session 主動引用並正確應用其負向守句）。
+- `npm test` + `scripts/check-repo-consistency.sh`（含 cross-refs + source↔mirror diff + `npm pack --dry-run`）全綠。
+
+---
+
 ## 0.11.0 — 2026-06-27 — DDD 指引深化 + pre-V1 退役 + docs 刷新
 
 **Proposals**：PROPOSAL-059（modeling-guide 盲區補強）、PROPOSAL-060（Subdomain 分類）、PROPOSAL-061（Brownfield aggregate 萌芽判準）、PROPOSAL-062（戰術補遺）、PROPOSAL-064（Brownfield modeling-guide reachability）、PROPOSAL-065（檢查機械化）、PROPOSAL-066（context-map 語彙補完）、PROPOSAL-063（退役 pre-V1 migration story）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {

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

@@ -55,6 +55,10 @@ proceeding (do not flip status, do not archive, do not emit summary).
 - [ ] Every phase-spec file referenced in the Phase Specs table exists at
       the path the table claims
 - [ ] 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
+- [ ] Every such lightweight / BUG spec file's frontmatter has
+      `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
@@ -65,6 +69,7 @@ If any check fails:
 > found:
 >   ✗ phase-spec-2026-04-15-foo.md status is still `in-progress`
 >   ✗ Phase Specs table row 3 references missing file phase-spec-...
+>   ✗ lightweight-2026-06-20-rounding.md frontmatter status is still `in-progress`
 >
 > Address these (run `/dflow:new-phase` to add missing work, or fix the
 > stale status manually), then re-run `/dflow:finish-feature`."
@@ -92,11 +97,17 @@ branch: feature/{SPEC-ID}-{slug}
 ---
 ```
 
-Also update the **Resume Pointer** to reflect closeout:
+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):
 
 ```
 **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
 ```
 
 **→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (status flipped). Entering Step 3: Sync BR Snapshot to BC layer." and continue.
@@ -170,7 +181,8 @@ AI runs:
 ```bash
 git mv dflow/specs/features/active/{SPEC-ID}-{slug} \
        dflow/specs/features/completed/{SPEC-ID}-{slug}
-git status   # confirm rename detection
+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
@@ -179,37 +191,74 @@ PR diff quality stays intact across the move. See
 `references/git-integration.md` § "Directory Moves Must Use git mv" for
 the full rule set.
 
-After the move, also `git add` any modified files from Step 3 (the
-updated `rules.md`, `behavior.md`, `glossary.md`, `tech-debt.md`, etc.)
-into the same stage.
-
 **Closeout commit checkpoint** (completes the offline Local-closeout gate):
 
 ```
-✓ Feature archived to completed/ and closeout files staged
+✓ Feature archived to completed/ and closeout ready to stage
    Commit this closeout now?
    [Y] Yes — the AI commits with your Git identity (marker per _conventions.md § AI Commit Policy)
    [N] No — skip; you commit yourself
 ```
 
-Whether you choose Y or N, record one row in the feature `_index.md`
-Checkpoint Log (`closeout | committed ({hash})` or `closeout | skipped`). Only
-write a hash after the commit actually succeeds; if a pre-commit hook rejects it
-or the commit fails, record `failed` and surface the error — never write a fake
-hash.
-
-The Local-closeout gate is satisfied **only when the closeout is committed**:
-closeout complete, Checkpoint Log updated, and the working tree clean (no
-uncommitted changes). If you declined the commit (chose N) or it failed,
-Local-closeout is **not** satisfied yet — commit the staged closeout yourself
-before continuing; do not enter the Integration / PR gate with uncommitted
-changes. Once committed, the gate stands on its own offline; integration happens
-in Step 5 when you have network.
-
-**→ Transition (step-internal)**: Step 4 complete. Branch on whether the closeout commit landed:
-
-- **Closeout commit landed (working tree clean)** → announce "Step 4 complete (feature archived; Local-closeout gate satisfied). Entering Step 5: Integration / PR gate." and continue.
-- **Closeout commit was declined (N) or failed** → **stop here.** Announce "Step 4 complete (feature archived), but the Local-closeout gate is not satisfied yet — the closeout is staged but uncommitted. Commit those changes (or address the failure), then resume to Step 5." Do **not** enter Step 5 with uncommitted closeout changes.
+Then, in this order:
+
+1. **Record the checkpoint row first.** Write one row in the moved
+   `_index.md` Checkpoint Log — `closeout | committed` for Y, `closeout |
+   skipped` for N. The closeout row carries **no commit hash**: the closeout
+   commit cannot contain its own hash. Trace it later via
+   `git log -1 -- dflow/specs/features/completed/{SPEC-ID}-{slug}` (or the
+   optional `Dflow-Checkpoint` trailer). The "hash only after success" rule
+   still applies to spec / implementation rows — closeout is the documented
+   exception (see `references/git-integration.md` § Commit Checkpoints,
+   Branch Gate & AI Commits).
+2. **Stage the whole archived feature directory:**
+
+   ```bash
+   git add dflow/specs/features/completed/{SPEC-ID}-{slug}
+   ```
+
+   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.
+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
+   treat the gate as unsatisfied.
+
+**Post-commit closeout verification** — after a successful commit, and before
+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".
+- [ ] `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.
+
+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
+failed, Local-closeout is **not** satisfied yet — commit the staged closeout
+yourself before continuing; do not enter the Integration / PR gate with
+uncommitted changes. Once committed and verified, the gate stands on its own
+offline; integration happens in Step 5 when you have network.
+
+**→ Transition (step-internal)**: Step 4 complete. Branch on the verification result:
+
+- **Closeout commit landed and post-commit verification passed** → announce "Step 4 complete (feature archived; Local-closeout gate satisfied). Entering Step 5: Integration / PR gate." and continue.
+- **Closeout commit was declined (N), failed, or verification reported `✗`** → **stop here.** Announce "Step 4 complete (feature archived), but the Local-closeout gate is not satisfied yet — the closeout is staged but uncommitted, or the committed content failed verification. Commit the staged changes (or fix the failure), then resume to Step 5." Do **not** enter Step 5 with uncommitted or unverified closeout changes.
 
 ## Step 5: Emit Integration Summary (Git-strategy-neutral)
 
@@ -266,10 +315,17 @@ the developer:
 
 If no `follow-up-of` field, skip Step 6 and announce closeout complete:
 > "`/dflow:finish-feature` complete for `{SPEC-ID}-{slug}`. Feature
-> directory is now at `dflow/specs/features/completed/{SPEC-ID}-{slug}/`.
-> If you skipped the closeout commit, commit the staged changes first to
-> finish the Local-closeout gate. Then integration — merge / push / PR —
-> follows the selected Git policy, at your discretion."
+> directory is now at `dflow/specs/features/completed/{SPEC-ID}-{slug}/`,
+> with the Local-closeout gate satisfied (closeout committed and verified).
+> Integration — merge / push / PR — follows the selected Git policy, at
+> your discretion."
+
+**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.
 
 ## Step 6: Reverse-Update Follow-up Tracking (only if follow-up)
 

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

@@ -37,9 +37,9 @@ main (or your project's base branch)
 ```
 feature/{SPEC-ID}-{slug}
   Examples:
-    feature/EXP-001-jpy-currency-support
-    feature/HR-003-leave-approval-workflow
-    feature/SHARED-002-audit-logging
+    feature/SPEC-20260424-001-jpy-currency-support
+    feature/SPEC-20260430-001-leave-approval-workflow
+    feature/SPEC-20260502-002-audit-logging
 
 bugfix/{BUG-ID}-{slug}
   Examples:
@@ -148,10 +148,30 @@ existing Step Gate prompt (it does not add a separate question):
 Tier sets how many checkpoints a change has: T1 three (spec / implementation /
 closeout), T2 two (spec+implementation merged / closeout), T3 a single commit.
 Whether you choose Y or N, the AI records one row in the feature `_index.md`
-Checkpoint Log. A commit hash is written only after the commit succeeds; a hook
-rejection or failed commit is recorded as `failed` (never a fake hash). After
-several consecutive skips in a project the AI mentions you can turn checkpoints
-off in config — it does not turn them off for you.
+Checkpoint Log — every checkpoint is accounted for (`committed` / `skipped` /
+`failed`), even when no commit happens. A commit hash is written only after the
+commit succeeds; a hook rejection or failed commit is recorded as `failed`
+(never a fake hash). **Exception — the closeout row**: the closeout commit
+cannot contain its own hash, so the closeout row is written before the commit
+as `closeout | committed` with **no hash** (see
+`references/finish-feature-flow.md` Step 4); trace that commit via
+`git log -1 -- dflow/specs/features/completed/{SPEC-ID}-{slug}` or the optional
+`Dflow-Checkpoint` trailer below. After several consecutive skips in a project
+the AI mentions you can turn checkpoints off in config — it does not turn them
+off for you.
+
+**Optional machine-greppable trailer.** Teams that want cross-flow checkpoint
+accounting can append a commit trailer at checkpoint commits:
+
+```
+Dflow-Checkpoint: {SPEC-ID} {spec|impl|closeout}
+```
+
+The `_index.md` Checkpoint Log **remains the source of truth**; the trailer is
+a cheap derived mirror (`git log --grep 'Dflow-Checkpoint: {SPEC-ID}'`). Use
+role names, not (k/N) counts — the checkpoint total can change mid-feature
+(tier escalation, follow-ups), and a role gap ("impl exists but no closeout for
+this SPEC-ID") is detectable without predicting N, even across flows.
 
 ### AI commits
 
@@ -325,8 +345,8 @@ Tie commits to specs:
 [SPEC-ID] Short description
 
 Examples:
-[EXP-001] Add JPY currency support to Money value object
-[EXP-001] Extract exchange rate logic to Domain service
+[SPEC-20260424-001] Add JPY currency support to Money value object
+[SPEC-20260424-001] Extract exchange rate logic to Domain service
 [BUG-042] Fix rounding inconsistency, extract to Money.Round()
 ```
 

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

@@ -7,6 +7,8 @@ Step-by-step guide for when a developer triggers `/dflow:modify-existing` or `/d
 - Step 4 → Step 5 (extraction decision → start implementation)
 - Step 5 → Step 6 (implementation done → update artifacts)
 
+Crossing any step gate above also updates the host feature's `_index.md` Resume Pointer cursor (Active Workflow / Current Step / Gates Passed / Awaiting) once the host feature directory exists — fold it into that gate's existing `_index.md` / Resume Pointer edit, no separate ceremony (see the `_index.md` template's Resume Pointer notes).
+
 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).
@@ -63,6 +65,16 @@ Walk through these in order:
    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.
+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`
+   when the network allows, then
+   `git branch --all --list '*feature/*' --list '*bugfix/*'` — and also list
+   other unfinished features in this branch's `active/` (one cursor line
+   each). If a scanned branch classified as in flight elsewhere, closed out
+   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).
 
 > **Why scan completed too?** Completed features are frozen history
 > and **cannot accept** any T2 / T3 directly
@@ -316,6 +328,17 @@ has no separate Aggregates section, do not invent one; update the Repository
 row if one exists. If the developer defers, **record the emergence observation
 in `tech-debt.md`** so the boundary decision is not silently lost.
 
+**Established-model re-read (the emergence check's mirror).** When the rule
+you are extracting lands on an **already-modeled** Aggregate / concept,
+re-read what was recorded when it was shaped (its `models.md` row + Notes
+and the relevant `rules.md` entries) before extending it. If this change
+matches a recorded re-evaluation condition ("revisit when …") or trips a
+model-resistance signal, follow `references/ddd-modeling-guide.md`
+§ "Revising an Established Model": record one short passage in the spec's
+design decisions / open questions — proceed as-is, split, or rename, with
+the reason. Deciding to keep the current model, recorded, is a valid
+outcome; extending silently is not.
+
 If the context is **`generic`** (Subdomain Type), emergence is usually a
 *replacement / adapter-boundary* debt signal, not a cue for deep T1 modeling —
 record the replacement intent (consistent with the generic extraction fallback

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

@@ -8,6 +8,8 @@ Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natura
 - Step 6 → Step 7 (branch ready → start implementation)
 - Step 7 → Step 8 (implementation done → completion)
 
+Crossing any step gate above also updates the host feature's `_index.md` Resume Pointer cursor (Active Workflow / Current Step / Gates Passed / Awaiting) once the feature directory exists — fold it into that gate's existing `_index.md` / Resume Pointer edit, no separate ceremony (see the `_index.md` template's Resume Pointer notes).
+
 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).
@@ -30,6 +32,27 @@ Then check existing assets:
 - Search `dflow/specs/features/` for related or overlapping features
 - Check `dflow/specs/domain/glossary.md` for relevant terms
 
+**In-flight overlap scan (cross-branch + other unfinished features)** — this
+branch's `dflow/specs/` does not show everything in flight. Run the in-flight
+scan (classification and dedup rules in `AI-AGENT-GUIDE.md` § Status / Control
+Commands):
+
+```bash
+git fetch   # when the network allows; skip gracefully offline
+git branch --all --list '*feature/*' --list '*bugfix/*'
+```
+
+- List other unfinished features already in this branch's `active/` (one
+  cursor line each, from their `_index.md` Resume Pointer).
+- Classify every listed branch by the guide's rules — in flight elsewhere /
+  closed out awaiting integration / stale (completed here) / unknown — do
+  not shortcut the classification. If a branch classified as **in flight
+  elsewhere, closed out awaiting integration, or unknown** has an ID / slug
+  that semantically overlaps this request, surface it and wait for the
+  developer to decide — continue there / integrate it first / treat as
+  related / unrelated — **before creating any new directory, spec, or
+  branch**. Only stale (completed here) branches are non-blocking.
+
 Share what you found: "I see we already have [X] documented. This new feature seems to extend
 that — is that right?"
 
@@ -90,6 +113,16 @@ classification, set-based / uniqueness rules, value objects, aggregate sizing
 read `references/ddd-modeling-guide.md` (its **Edition note** maps recording
 surfaces to brownfield's `models.md` / `rules.md`).
 
+The mirror case — the concept is **already modeled**: when extending an
+existing Aggregate / modeled concept, re-read what was recorded when it was
+shaped (its `models.md` row + Notes and the relevant `rules.md` entries)
+before extending it. If this change matches a recorded re-evaluation
+condition ("revisit when …") or trips a model-resistance signal, follow
+`references/ddd-modeling-guide.md` § "Revising an Established Model":
+record one short passage in the spec's design decisions / open questions —
+proceed as-is, split, or rename, with the reason. Deciding to keep the
+current model, recorded, is a valid outcome; extending silently is not.
+
 For each new concept:
 1. Check glossary — add if missing
 2. Check if it already exists in models.md — extend if needed
@@ -170,7 +203,7 @@ dflow/specs/features/active/{SPEC-ID}-{slug}/
    - Current BR Snapshot: initialise from the first phase's planned BRs
      (will be refreshed when the phase-spec finalises)
    - Lightweight Changes: empty table at start
-   - Resume Pointer: "phase-1 in progress: drafting phase-spec." / "Next Action: finish phase-spec, then implement."
+   - Resume Pointer: "phase-1 in progress: drafting phase-spec." / "Next Action: finish phase-spec, then implement." / cursor fields: Active Workflow `new-feature`, Current Step `Step 4 — write the spec`, Gates Passed `3→3.5`, Awaiting `none (mid-step)`
 3. **Create the first phase-spec** at `phase-spec-{YYYY-MM-DD}-{slug}.md`
    using `templates/phase-spec.md`. The "Delta from prior phases" section
    is filled with "首 phase，無前置 Delta" (first phase has nothing to

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

@@ -19,6 +19,8 @@ adds a new phase to an in-progress feature only.
 - Step 5 → Step 6 (`_index.md` refreshed → start implementation)
 - Step 6 → Step 7 (implementation done → complete the phase)
 
+Crossing any step gate above also updates the feature's `_index.md` Resume Pointer cursor (Active Workflow / Current Step / Gates Passed / Awaiting) — fold it into that gate's existing `_index.md` / Resume Pointer edit, no separate ceremony (see the `_index.md` template's Resume Pointer notes).
+
 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.
@@ -63,6 +65,11 @@ AI must locate the target feature and load its current state:
    - Read the most recent phase-spec to understand where the prior phase
      left off (its Business Rules and Delta-from-prior-phases sections in
      particular)
+   - Run the in-flight overlap scan (classification and dedup rules in
+     `AI-AGENT-GUIDE.md` § Status / Control Commands): list other unfinished
+     features in `active/` and any feature / bugfix branches whose work is
+     not visible on this branch — if the incoming phase scope overlaps one
+     of them, surface it before writing the phase-spec.
 
 4. **Branch gate — ensure you are on this feature's branch (before any commit)**
 
@@ -99,7 +106,11 @@ Walk the developer through what the new phase covers:
    Entity row (no separate Aggregates section). For how to model it (invariant
    classification, set-based / uniqueness rules, aggregate sizing), read
    `references/ddd-modeling-guide.md` (its **Edition note** maps recording
-   surfaces to brownfield's `models.md` / `rules.md`).
+   surfaces to brownfield's `models.md` / `rules.md`). If the phase **extends
+   an already-modeled Aggregate / concept**, apply the established-model
+   re-read from `references/ddd-modeling-guide.md` § "Revising an Established
+   Model" (match recorded re-evaluation conditions; record proceed / split /
+   rename in the phase-spec).
 4. **Data structure impact?** New tables, columns, indices?
 5. **Why now?** Priority — informs sequencing relative to other phases.
 

package/templates/brownfield/scaffolding/AI-AGENT-GUIDE.md

@@ -118,10 +118,43 @@ input like this (supporting files live in the workflow bundle at
 
 ## Status / Control Commands
 
-`/dflow:status` reports active workflow state. Include these fields: workflow,
-step, completed, in-progress, remaining, pending decision, and next valid action.
-If no workflow is active, say that no workflow is active and list valid flow-entry
-or standalone commands.
+`/dflow:status` reports in two parts.
+
+**Part 1 — in-flight overview (always shown, workflow active or not).**
+Aggregate every in-flight feature so unfinished work surfaces without anyone
+remembering to look:
+
+- Scan this branch's `dflow/specs/features/active/*/_index.md` and print one
+  line per feature: SPEC-ID / Active Workflow / Current Step / Awaiting / last
+  Checkpoint Log row (read from each Resume Pointer cursor).
+- Cross-branch: run `git fetch` when the network allows (skip gracefully
+  offline), then `git branch --all --list '*feature/*' --list '*bugfix/*'`,
+  deduplicating local and remote refs of the same branch (prefer local). For
+  each branch, classify in order: (1) its feature directory exists in this
+  branch's `active/` → already covered above; (2) exists in this branch's
+  `completed/` → a stale undeleted branch — list as "completed; branch can be
+  deleted", **not** in-flight; (3)
+  `git show {branch}:dflow/specs/features/active/{dir}/_index.md` is readable
+  → in flight on that branch, print its cursor line (no branch switching);
+  (4) the `completed/` path is readable on that branch → closed out there,
+  awaiting integration; (5) nothing readable → list the branch as unknown
+  state.
+- If `features/backlog/` is non-empty, append one count line.
+- Inherent limit: work never committed anywhere is invisible to any git scan.
+
+**Part 2 — current feature detail (when a workflow is active).** Read the
+Resume Pointer cursor as the **declared** state, then cross-check it against
+derived evidence (Checkpoint Log, phase-spec statuses, recent git log). On
+mismatch, report both sides explicitly and ask the developer to correct the
+cursor — the cursor is a claim; evidence wins. If the cursor fields are absent
+(an older `_index.md`), fall back to pure derivation. For readability you may
+expand the cursor into a step checklist (done / in progress / not started)
+derived live from the flow file — display only, never stored.
+
+Include these fields: workflow, step, completed, in-progress, remaining,
+pending decision, and next valid action. If no workflow is active, say so and
+list valid flow-entry or standalone commands (Part 1 still shows the
+in-flight overview).
 
 `/dflow:next` is valid only at a step gate in an active workflow. Treat it as
 developer confirmation equivalent to "OK" or "continue", then move to the next
@@ -129,7 +162,9 @@ workflow step.
 
 `/dflow:cancel` aborts the current workflow and returns to free conversation.
 Do not rollback changes, delete artifacts, or rewrite specs merely because the
-workflow was cancelled.
+workflow was cancelled. If the feature directory exists, set the Resume
+Pointer cursor's Active Workflow to `none` (keep Current Progress as a trace
+of where the cancellation happened).
 
 When no workflow is active, `/dflow:next` and `/dflow:cancel` must report that
 there is no active workflow to advance or cancel.

package/templates/brownfield/scaffolding/Git-principles-gitflow.md

@@ -140,7 +140,7 @@ When applicable, prefix with a type (conventional commits-style):
 | test | tests only |
 | chore | build / tooling |
 
-Example: `[EXP-001] feat: add JPY currency support to Money VO`
+Example: `[SPEC-20260424-001] feat: add JPY currency support to Money VO`
 
 ---
 

package/templates/brownfield/scaffolding/Git-principles-trunk.md

@@ -95,8 +95,8 @@ adopted, the format is:
 | test | tests only |
 | chore | build / tooling |
 
-Example: `feat(expense): add JPY currency support` with `[EXP-001]` in
-the body.
+Example: `feat(expense): add JPY currency support` with
+`[SPEC-20260424-001]` in the body.
 
 ---
 

package/templates/brownfield/templates/_index.md

@@ -97,23 +97,42 @@ Template note (for AI):
 > T3 單一 commit。
 >
 > commit hash 只在 commit 實際成功後填入；pre-commit hook reject 或 commit
-> 失敗記 `failed`、不寫假 hash。
+> 失敗記 `failed`、不寫假 hash。**例外：closeout 列不填 hash**——closeout
+> commit 無法自含自身 hash，該列於 commit 前寫入、隨歸檔目錄一起進 commit；
+> 溯源用 `git log -1 -- completed/{SPEC-ID}-{slug}` 或選配的
+> `Dflow-Checkpoint` trailer（見 references/git-integration.md）。
 
 | Timestamp | Checkpoint | Result |
 |---|---|---|
 | {YYYY-MM-DD HH:MM} | spec-baseline | committed ({hash}) / skipped / failed |
 | {YYYY-MM-DD HH:MM} | implementation | committed ({hash}) / skipped / failed |
-| {YYYY-MM-DD HH:MM} | closeout | committed ({hash}) / skipped / failed |
+| {YYYY-MM-DD HH:MM} | closeout | committed / skipped / failed |
 
 ## Resume Pointer
 
-> 一句話：目前進展到哪？下一個動作是什麼？
-> 開新對話接續工作時，從這裡讀起。
+> 目前進展到哪？下一個動作是什麼？開新對話接續工作時，從這裡讀起。
+>
+> 下方四個 cursor 欄位是 workflow 進度的**存放層（宣告，claim）**：
+> 進入 flow 時設 Active Workflow；**每過一個 step gate** 更新 Current Step /
+> Gates Passed / Awaiting（與該 gate 既有的 `_index.md` 更新合併，不另加儀式）；
+> closeout / `/dflow:cancel` 時 Active Workflow 設回 `none`。
+> `/dflow:status` 讀 cursor 後會與推導證據（Checkpoint Log、phase-spec
+> status、git log）交叉，不一致會明確報 mismatch——cursor 是宣告、證據優先。
+> Phase 粒度進度由上方 Phase Specs 表承載；cursor 只補 workflow step / gate
+> 粒度，不展開成 per-step 全表（步驟線性，游標可推導每一步的完成/未做）。
 
 **Current Progress**: {one-line summary}
 
 **Next Action**: {suggested next action}
 
+**Active Workflow**: {new-feature | modify-existing | bug-fix | new-phase | finish-feature | none}
+
+**Current Step**: {Step N — short step name | n/a}
+
+**Gates Passed**: {e.g. "3→3.5, 4→5" | n/a}
+
+**Awaiting**: {step-gate description | none}
+
 <!--
 ## Follow-up Tracking
 >（選用段；只有當本 feature 衍生出 follow-up feature 時才填）

package/templates/brownfield/templates/lightweight-spec.md

@@ -1,10 +1,10 @@
 ---
-id: BUG-{NUMBER}
+id: BUG-{NUMBER}    # bug-type T2 only; a non-bug T2 (lightweight-{date}-{slug}.md) carries no id — the filename identifies it
 title: {簡述問題}
-status: in-progress
+status: in-progress    # in-progress | completed
 bounded-context: {ContextName}
 created: {YYYY-MM-DD}
-branch: bugfix/BUG-{NUMBER}-{short-description}
+branch: bugfix/BUG-{NUMBER}-{slug}
 ---
 
 <!--

package/templates/brownfield/templates/phase-spec.md

@@ -1,11 +1,11 @@
 ---
-id: {CONTEXT}-{NUMBER}
+spec-id: SPEC-{YYYYMMDD}-{NNN}    # the owning feature's SPEC-ID (matches the feature directory name)
 title: Feature title
-status: draft | in-progress | completed
+status: in-progress    # in-progress | completed
 bounded-context: {ContextName}
 created: {YYYY-MM-DD}
 author: {developer-name}
-branch: feature/{CONTEXT}-{NUMBER}-{short-description}
+branch: feature/{SPEC-ID}-{slug}
 ---
 
 # {Feature Title}