dflow-sdd-ddd 0.10.0 → 0.12.0

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

@@ -74,10 +74,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 +118,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.
@@ -313,34 +348,6 @@ are verified against the phase-spec before Step 7 completion.
 - Application tests: command / query handler behavior
 - Integration tests: repository, external services
 
-## Pre-V1 Artifacts Detection
-
-When working in a project that adopted Dflow before `dflow-sdd-ddd@0.1.0`,
-you may encounter layout or naming patterns that predate the V1 baseline.
-If any of the following appear, surface the observation to the developer
-and recommend manual migration; do not rewrite anything silently.
-
-Signals:
-
-- Top-level `specs/` directory containing Dflow-shaped content (V1 layout
-  uses `dflow/specs/`).
-- `_共用/` directory under `specs/` or `dflow/specs/` (V1 uses `shared/`).
-- Section headings in Traditional Chinese where V1 templates render
-  canonical English; compare against `TEMPLATE-LANGUAGE-GLOSSARY.md` if
-  available.
-- References to a runtime `/dflow:init-project` slash command (V1
-  replaced it with the Dflow CLI init command (`dflow init`, or
-  `npx dflow-sdd-ddd init` when using the no-install path)).
-- A root `CLAUDE.md`, `AGENTS.md`, or equivalent that holds the full
-  Dflow workflow text instead of being a thin shim pointing to this
-  file.
-- `dflow/specs/shared/_conventions.md` is missing the `> Dflow Version:`
-  front-matter line (V1 init writes it automatically).
-
-Recommend `docs/migrating-to-dflow-v1.md` for the manual migration
-checklist. Migration affects every spec the team has written; manual
-review is required.
-
 ## Workflow Steps
 
 This guide is the **command registry, routing rules, and project context**.

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

@@ -105,23 +105,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

@@ -13,6 +13,12 @@ created: {YYYY-MM-DD}
 ## Invariants
 
 > 必須永遠為真的規則。這是 Aggregate 存在的理由。
+> 主體列 **boundary invariants**(需同時看到 Aggregate 內多個物件的狀態才能判的規則)。
+> 單一物件可判的 local constraint 不列這裡 — 純格式/必填走 Validator、有 domain
+> 語意走 VO / Entity constructor。跨 instance 的規則(唯一性、僅一筆 active)可列,
+> 但標 `set-based` 並在 Behavior on Violation 寫明 store-level guard(unique /
+> partial index、concurrency token;見 ddd-modeling-guide 的 Invariant
+> Classification 與 Set-Based 段)。
 
 | ID | Invariant | Behavior on Violation |
 |---|---|---|
@@ -55,4 +61,5 @@ created: {YYYY-MM-DD}
 
 ## Design Decisions
 
-> 為什麼 Aggregate 的邊界劃在這裡？有沒有考慮過其他方案？
+> 為什麼 Aggregate 的邊界劃在這裡？有沒有考慮過其他方案？每個決策附
+> **再評估條件**：什麼情況出現時，這個決策應該被重看？（「revisit when …」）

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

@@ -6,15 +6,24 @@
 
 ## Contexts
 
-| Bounded Context | Responsibility | Owner / Team | Primary Module | Notes |
-|---|---|---|---|---|
-| {Context name} | {業務責任} | {owner} | `{module/project}` | {optional notes} |
+| Bounded Context | Responsibility | Subdomain Type | Owner / Team | Primary Module | Notes |
+|---|---|---|---|---|---|
+| {Context name} | {業務責任} | core / supporting / generic | {owner} | `{module/project}` | {optional notes} |
+
+> **Subdomain Type** — 判別問句:「這塊功能換成現成 SaaS / 套件,系統的差異化會消失嗎?」
+> (差異化不限商業競爭優勢;內部系統指獨特的營運優勢 / 任務成果。)會 → `core`;
+> 不會、但需要為自家流程客製 → `supporting`(必要、常需客製、非差異化);
+> 不會、且現成方案存在 → `generic`。多數 BC 是 supporting,`core` 通常只有 1–2 個;
+> 全標 core = 沒分類。分類是可修訂的初判,改判時更新本欄並在 Notes 留一行理由。
+> 它決定建模深度(見 `references/ddd-modeling-guide.md`
+> § Subdomain-Aware Modeling Depth),但**不**降低 BR 紀錄、Tier ceremony、
+> 或安全 / 測試 / 可靠性要求。
 
 ## Relationships
 
 | Upstream | Downstream | Relationship Type | Published Language | ACL | Events |
 |---|---|---|---|---|---|
-| {Upstream context} | {Downstream context} | {Customer/Supplier, Conformist, ACL, Shared Kernel, etc.} | {shared terms / contract} | {Yes/No + location} | {event names or n/a} |
+| {Upstream context} | {Downstream context} | {Customer/Supplier, Conformist, ACL, Shared Kernel, Separate Ways, Big Ball of Mud (BBoM), OHS, etc.} | {shared terms / contract} | {Yes/No + location} | {event names or n/a} |
 
 ## Integration Notes
 

package/templates/greenfield/templates/events.md

@@ -12,7 +12,11 @@
 
 ## Event Flow Notes
 
-- {事件發生時序、交易邊界、重試或一致性注意事項}
+- {事件發生時序、交易邊界、重試或一致性注意事項;跨 aggregate 的 async(eventual
+  consistency)event chain,handler 重試耗盡的最終失敗若造成 business-visible 後果
+  (補償/權益/金流/庫存/合規/人工對帳)→ 升級為 BR/EC 寫進 behavior.md 與 spec,
+  best-effort 副作用(通知/logging)記這裡或 tech-debt 即可;多步驟且失敗需補償
+  → 見 ddd-modeling-guide 的 Long-Running Processes 段(process 判準與階梯)}
 
 ## Open Questions
 

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/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: 功能標題
-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}
 ---
 
 # {功能標題}

package/docs/migrating-to-dflow-v1.md

@@ -1,234 +0,0 @@
-# Migrating to Dflow V1
-
-> **Audience**: maintainers of an existing project that adopted an early
-> Dflow form (pre-`dflow-sdd-ddd@0.1.0`) and want to align it with the
-> V1 baseline that ships from npm.
->
-> **Stance**: V1 took a clean cut. Dflow does not perform automatic
-> migration. This guide is a manual checklist. The CLI only warns when
-> it detects legacy paths; it does not modify existing files.
-
-> **Audience reality (2026-05-15)**: To date, the only known user of
-> this guide has been the **OBTS** migration (a single, completed
-> one-off). Dflow has not had broad pre-V1 adoption; this guide is
-> maintained as a contingency endpoint for `dflow doctor` and
-> `dflow init` warning messages, not as documentation of an active
-> migration program. If you reach this page via those tool outputs
-> and your case isn't covered below, please open a docs feedback issue
-> so the guide can be extended.
-
-## When You Need This Guide
-
-Skip this guide if you started using Dflow at `dflow-sdd-ddd@0.1.0`
-or later. Your project is already on the V1 baseline.
-
-Read this guide if any of the following are true:
-
-- Your project has a top-level `specs/` directory that holds Dflow
-  spec material (not the V1 `dflow/specs/`).
-- Your project has `specs/_共用/` instead of `dflow/specs/shared/`.
-- Your spec headings are in Traditional Chinese rather than the
-  canonical English vocabulary documented in
-  `TEMPLATE-LANGUAGE-GLOSSARY.md`.
-- Your AI instructions point teammates to `/dflow:init-project`
-  instead of the Dflow CLI init command (`dflow init`, or
-  `npx dflow-sdd-ddd init` on the no-install path).
-- Your `CLAUDE.md` (or equivalent root instruction file) was generated
-  by an early Dflow variant that wrote a full Claude-only file rather
-  than the V1 multi-AI thin shim that points to
-  `dflow/specs/shared/AI-AGENT-GUIDE.md`.
-
-You may need only some of these steps; the five sections below are
-independent.
-
-## Before You Start
-
-- Work on a dedicated branch or a disposable copy. None of the steps
-  are destructive, but move-and-rename mistakes are easier to recover
-  from a clean branch.
-- Make sure the working tree is clean (`git status`).
-- Note your current Dflow version if you can identify it. Older
-  internal Dflow forms may not have been versioned at all.
-- Open these V1 reference files for cross-checking:
-  - `TEMPLATE-LANGUAGE-GLOSSARY.md` — canonical English headings.
-  - `TEMPLATE-COVERAGE.md` — V1 file layout and parity matrix.
-  - `docs/evaluating-dflow.en.md` — what a fresh V1 `init` produces, if
-    you want to spin up a sample project to compare against.
-- For an on-demand read-only summary of legacy artifacts in your
-  project, run `dflow doctor` (or `npx dflow-sdd-ddd doctor` on the
-  no-install path). The command lists detected legacy paths and missing
-  V1 fields; it never modifies files.
-
-## Migration Steps
-
-### 1. Move root `specs/` to `dflow/specs/`
-
-V1 puts every Dflow-managed spec under `dflow/specs/`, so the `dflow/`
-directory becomes a single Dflow namespace separate from any
-unrelated `specs/` directory another tool may own (PROPOSAL-014).
-
-If your project has top-level `specs/` containing Dflow content:
-
-```bash
-mkdir -p dflow
-git mv specs dflow/specs
-git status
-```
-
-Commit the rename in a single commit. Avoid mixing the rename with
-content edits in the same commit so reviewers can read the diff
-cleanly.
-
-If you also have an unrelated `specs/` directory used by another
-tool, move only the Dflow material into `dflow/specs/`. The CLI will
-warn when it sees a non-Dflow `specs/` directory but will not modify
-it.
-
-### 2. Rename `_共用/` to `shared/`
-
-V1 uses canonical English directory names (PROPOSAL-012). If your
-project has `dflow/specs/_共用/`:
-
-```bash
-git mv dflow/specs/_共用 dflow/specs/shared
-git status
-```
-
-Update any cross-references in spec files or AI instructions. A
-project-wide grep after the rename catches leftover references:
-
-```bash
-grep -rn "_共用" .
-```
-
-### 3. Translate Chinese headings to canonical English
-
-V1 templates use canonical English structure for section headings,
-field labels, anchors, and placeholders (PROPOSAL-013). Free prose
-inside those sections may stay in your team language.
-
-This is the most labor-intensive step. Recommended approach:
-
-1. Open `TEMPLATE-LANGUAGE-GLOSSARY.md` for the heading-by-heading
-   mapping.
-2. For each generated spec file, replace Chinese H2 / H3 headings,
-   table column labels, and bold inline labels with their canonical
-   English form.
-3. Leave free prose (descriptions, decision rationale, task text) in
-   the team language. The Prose Language convention recorded in
-   `dflow/specs/shared/_conventions.md` applies here — see also
-   step 6 below.
-
-An AI assistant can walk through each spec file heading-by-heading
-faster than a global search-and-replace, because earlier Dflow
-adoption may have used slightly different wording per team. After
-translation, run a project-wide search for the most common Chinese
-headings to catch missed files. Adjust the search list to match the
-templates your team actually used:
-
-```bash
-grep -rn "## 業務規則\|## 行為情境\|## 領域模型" dflow/specs/
-```
-
-### 4. Switch the init entry point
-
-Pre-V1 documentation may have instructed teammates to start a Dflow
-project by running `/dflow:init-project` from inside an AI agent. V1
-removed that runtime slash command (PROPOSAL-014). The init flow now
-runs as a shell command. Install Dflow globally and run:
-
-```bash
-npm install -g dflow-sdd-ddd
-dflow init
-```
-
-If you cannot or do not want to install globally, use the no-install path:
-
-```bash
-npx dflow-sdd-ddd init
-```
-
-If you already have an initialized project, you do not need to re-run
-`init`. The other `/dflow:*` workflow commands (`/dflow:new-feature`,
-`/dflow:modify-existing`, `/dflow:bug-fix`, `/dflow:new-phase`,
-`/dflow:finish-feature`, `/dflow:verify`, `/dflow:pr-review`) are
-unchanged and continue to work.
-
-Update any team documentation, runbooks, or onboarding notes that
-still reference `/dflow:init-project` so new project setups use the
-shell command instead.
-
-### 5. Adopt multi-AI thin shims
-
-V1 separates the canonical project guide from each per-tool
-instruction file (PROPOSAL-020). The canonical guide lives at
-`dflow/specs/shared/AI-AGENT-GUIDE.md`. Per-tool files (`AGENTS.md`,
-`CLAUDE.md`, `.github/copilot-instructions.md`) are thin
-shims pointing at the canonical guide.
-
-If your project's `CLAUDE.md` (or equivalent) was generated by an
-early Dflow form that wrote a full file rather than a thin shim:
-
-```bash
-dflow configure-agents
-```
-
-This command adds shims for any AI tools you select. `dflow configure-agents`
-does not overwrite custom content in an existing root instruction file. If it
-recognizes an older Dflow-generated shim, it refreshes that file to the current
-thin shim in place; a file that already points to the guide is left as-is;
-otherwise it shows the change in the preview and appends a marked Dflow block to
-the existing file. It writes a manual-merge snippet under
-`dflow/specs/shared/<tool>-md-snippet.md` only when the file contains
-conflicting or malformed Dflow markers.
-
-If you prefer a fully clean V1 layout, archive the existing root
-instruction file under another name first, then run
-`dflow configure-agents` so it can write the new shim from scratch.
-
-## After Migration
-
-Verify the migrated project:
-
-- Ask the AI agent to run `/dflow:status` and confirm it can locate
-  Dflow flow material and report the project's current state.
-- Open `dflow/specs/shared/_conventions.md` and confirm a `## Prose
-  Language` section exists. If your project predates the
-  prose-language convention (PROPOSAL-015), add the section manually
-  with the correct BCP-47 language tag, for example `zh-TW` or `en`.
-- Run a final grep to confirm no legacy paths or terms remain inside
-  `dflow/specs/`. Adjust the term list to match your earlier Dflow
-  adoption:
-
-```bash
-grep -rn "_共用\|/dflow:init-project" dflow/specs/
-```
-
-## Out of Scope
-
-This guide stays manual on purpose. The items below are not part of
-V1 and may or may not arrive in a later release; do not rely on them
-when planning a migration today.
-
-- Automatic migration of legacy paths or headings.
-- A `dflow doctor` health check command.
-- A `dflow migrate` subcommand that edits files.
-- Automated translation of free prose between languages.
-
-If any of these would help your team, open a docs feedback issue so
-the request is recorded. The maintainer position is not to refuse
-them, only to keep V1 a clean cut.
-
-## Where To Go Next
-
-- `docs/evaluating-dflow.en.md` for what a fresh V1 `init` produces, in
-  case you want to compare against your migrated project.
-- Per-tool walkthroughs under `docs/` for the AI tool you use:
-  - `docs/using-with-claude-code.en.md`
-  - `docs/using-with-codex.en.md`
-- `TEMPLATE-COVERAGE.md` for the V1 logical / generated file parity
-  between Greenfield and Brownfield tracks.
-
-If something in this guide does not match your project's actual
-pre-V1 state, open a docs feedback issue. The guide can be extended
-as new edge cases come in.