dflow-sdd-ddd 0.11.0 → 0.13.0

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

@@ -10,6 +10,8 @@ Triggered by `/dflow:new-feature` (or natural language implying a new-feature ta
 - 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).
@@ -31,6 +33,27 @@ Check existing assets:
 - Search `dflow/specs/features/` for related features
 - Check `dflow/specs/domain/glossary.md` and `context-map.md`
 
+**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.
+
 **→ Transition (step-internal)**: Step 1 complete. Announce "Step 1 complete (intake). Entering Step 2: Identify the Bounded Context." and continue.
 
 ## Step 2: Identify the Bounded Context
@@ -96,6 +119,17 @@ Those things form an Aggregate. Everything else is eventually consistent."
 - What entities belong inside this Aggregate?
 - What Value Objects can we extract?
 
+**Established-model re-read (when the feature reuses an existing
+Aggregate).** Re-read that Aggregate's recorded Design Decisions — its
+`aggregate-design.md` worksheet in the feature directory that introduced it
+(usually under `features/completed/`) — 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
+phase-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.
+
 ### Domain Events
 ```
 "After this happens, what else in the system needs to know?"
@@ -192,7 +226,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 Domain layer."
+   - Resume Pointer: "phase-1 in progress: drafting phase-spec." / "Next Action: finish phase-spec, then implement Domain layer." / 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/greenfield/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.
@@ -66,6 +68,11 @@ AI must locate the target feature and load its current state:
    - Cross-reference the bounded context's `dflow/specs/domain/{context}/rules.md`
      and `behavior.md` if the new phase is likely to touch system-level
      state (BC-level current state lives there, not in `_index.md`)
+   - 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,6 +106,10 @@ Walk the developer through what the new phase covers:
    at the depth set by the BC's Subdomain Type (see
    `references/ddd-modeling-guide.md` § Subdomain-Aware Modeling Depth) — don't
    bypass the classification just because this is a phase, not a new feature.
+   If the phase **extends an existing Aggregate**, 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. **Cross-context impact?** Does this phase introduce / change Domain
    Events that other contexts consume? (If yes, plan for `context-map.md`
    updates at finish-feature time.)

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

@@ -64,6 +64,11 @@ input like this (supporting files live in the workflow bundle at
 - **"Quick question about..." / "How does X work?"** → check
   `dflow/specs/domain/` first and answer from the documented domain knowledge.
 - **"I'm creating a branch"** → read `references/git-integration.md`.
+- **"Turn the specs into HTML" / "make the specs easier to read"** → run the
+  CLI command `dflow render` (a human-readability tool, not a `/dflow:*`
+  workflow). It mirrors `dflow/specs/` into a browsable static HTML tree
+  (default output: `dflow-specs-html/`); re-run it after specs change —
+  Markdown stays the AI-facing source of truth.
 - **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
   guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
   anything upstream automatically.
@@ -74,10 +79,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
@@ -85,7 +123,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/greenfield/scaffolding/Git-principles-gitflow.md

@@ -141,7 +141,7 @@ When applicable, prefix with a type (conventional commits-style):
 | test | tests only |
 | chore | build / tooling |
 
-Example: `[EXP-001] feat: introduce ExpenseReport Aggregate with submission invariants`
+Example: `[SPEC-20260424-002] feat: introduce ExpenseReport Aggregate with submission invariants`
 
 ---
 

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

@@ -305,8 +305,10 @@ assistant's documented line (e.g. `Co-Authored-By: Claude
 There is no separate `hotfix/*` branch. A hotfix is:
 
 1. A (small) feature branch cut from `main`
-2. Named `feature/{SPEC-ID}-{slug}` where SPEC-ID is a lightweight spec
-   or a full-ceremony spec depending on severity
+2. Named by the normal Dflow branch scheme, chosen by severity: a
+   bug-type hotfix (T2 lightweight) uses `bugfix/{BUG-ID}-{slug}`; a
+   hotfix that warrants full ceremony uses `feature/{SPEC-ID}-{slug}`
+   (see `references/git-integration.md` § Branch Naming Convention)
 3. Merged back to `main` via the team's chosen merge strategy
 4. Deployed via the same pipeline as any other change
 

package/templates/greenfield/templates/_index.md

@@ -46,6 +46,8 @@ Template note (for AI):
     initial BR Snapshot + Resume Pointer. The other sections can stay empty.
 -->
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {Feature Title}
 
 ## Goals & Scope
@@ -105,23 +107,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/greenfield/templates/aggregate-design.md

@@ -4,6 +4,8 @@ bounded-context: {ContextName}
 created: {YYYY-MM-DD}
 ---
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {AggregateName} Aggregate
 
 ## Purpose
@@ -61,4 +63,5 @@ created: {YYYY-MM-DD}
 
 ## Design Decisions
 
-> 為什麼 Aggregate 的邊界劃在這裡？有沒有考慮過其他方案？
+> 為什麼 Aggregate 的邊界劃在這裡？有沒有考慮過其他方案？每個決策附
+> **再評估條件**：什麼情況出現時，這個決策應該被重看？（「revisit when …」）

package/templates/greenfield/templates/context-definition.md

@@ -5,6 +5,8 @@ owner: {負責的開發者或團隊}
 created: {YYYY-MM-DD}
 ---
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {ContextName} Bounded Context
 
 ## Responsibilities

package/templates/greenfield/templates/context-map.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Context Map
 

package/templates/greenfield/templates/events.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Domain Events
 
@@ -15,7 +16,8 @@
 - {事件發生時序、交易邊界、重試或一致性注意事項;跨 aggregate 的 async(eventual
   consistency)event chain,handler 重試耗盡的最終失敗若造成 business-visible 後果
   (補償/權益/金流/庫存/合規/人工對帳)→ 升級為 BR/EC 寫進 behavior.md 與 spec,
-  best-effort 副作用(通知/logging)記這裡或 tech-debt 即可}
+  best-effort 副作用(通知/logging)記這裡或 tech-debt 即可;多步驟且失敗需補償
+  → 見 ddd-modeling-guide 的 Long-Running Processes 段(process 判準與階梯)}
 
 ## Open Questions
 

package/templates/greenfield/templates/glossary.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Glossary
 

package/templates/greenfield/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/greenfield/templates/models.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Domain Models
 

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

@@ -1,13 +1,15 @@
 ---
-id: {CONTEXT}-{NUMBER}
+spec-id: SPEC-{YYYYMMDD}-{NNN}    # the owning feature's SPEC-ID (matches the feature directory name)
 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}
 ---
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {功能標題}
 
 <!--

package/templates/greenfield/templates/rules.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Business Rules
 

package/templates/greenfield/templates/tech-debt.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Architecture Tech Debt