dflow-sdd-ddd 0.1.1 → 0.3.0

package/lib/init.js

@@ -3,6 +3,8 @@ const path = require('node:path');
 const readline = require('node:readline');
 const { TextDecoder } = require('node:util');
 
+const pkg = require('../package.json');
+
 const MIN_NODE_VERSION = '22.0.0';
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, 'templates');
@@ -320,7 +322,7 @@ async function runPreflight(cwd) {
   const legacySpecsPath = path.join(cwd, 'specs');
   if ((await pathExists(legacySpecsPath)) && (await containsInitializedContent(legacySpecsPath))) {
     warnings.push(
-      'Detected legacy specs/. Dflow V1 will not migrate or modify it; new files will be created under dflow/specs/.'
+      'Detected legacy specs/. Dflow V1 will not migrate or modify it; new files will be created under dflow/specs/. See docs/migrating-to-dflow-v1.md for the manual migration checklist.'
     );
   }
 
@@ -1117,6 +1119,7 @@ function buildSubstitutionMap(cwd, answers) {
     ['{tech-stack-summary}', answers.techStackSummary],
     ['{migration-context}', answers.migrationContext],
     ['{prose-language}', answers.proseLanguage],
+    ['{dflow-version}', pkg.version],
     ['{ASP.NET Core version}', extracted.aspNetCoreVersion || '{ASP.NET Core version}'],
     ['{EF Core version}', extracted.efCoreVersion || '{EF Core version}'],
     ['{MediatR version}', extracted.mediatRVersion || '{MediatR version}'],
@@ -1479,8 +1482,101 @@ function dedupe(values) {
   return Array.from(new Set(values));
 }
 
+async function runDoctor(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+
+  try {
+    if (compareVersions(process.versions.node, MIN_NODE_VERSION) < 0) {
+      throw new InitError(`Dflow doctor requires Node.js ${MIN_NODE_VERSION}+.`, 1);
+    }
+
+    const findings = [];
+    await checkLegacyRootSpecsDir(cwd, findings);
+    await checkLegacySharedDir(cwd, findings);
+    await checkConventionsDflowVersion(cwd, findings);
+
+    printDoctorReport(stdout, cwd, findings);
+    return 0;
+  } catch (error) {
+    if (error instanceof InitError) {
+      stderr.write(`${error.message}\n`);
+      return error.exitCode;
+    }
+    stderr.write(`${error && error.message ? error.message : error}\n`);
+    return 1;
+  }
+}
+
+async function checkLegacyRootSpecsDir(cwd, findings) {
+  const legacyPath = path.join(cwd, 'specs');
+  if ((await pathExists(legacyPath)) && (await containsInitializedContent(legacyPath))) {
+    findings.push({
+      level: 'warn',
+      title: 'Legacy specs/ directory at project root',
+      detail: 'V1 layout uses dflow/specs/ instead. The CLI does not modify root specs/.',
+      action: 'See docs/migrating-to-dflow-v1.md (Step 1) for the manual migration steps.'
+    });
+  }
+}
+
+async function checkLegacySharedDir(cwd, findings) {
+  const candidates = [
+    path.join(cwd, 'dflow', 'specs', '_共用'),
+    path.join(cwd, 'specs', '_共用')
+  ];
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) {
+      const rel = normalizePath(path.relative(cwd, candidate));
+      findings.push({
+        level: 'warn',
+        title: `Legacy ${rel}/ directory`,
+        detail: 'V1 layout uses shared/ (canonical English directory name).',
+        action: 'See docs/migrating-to-dflow-v1.md (Step 2) for the rename steps.'
+      });
+    }
+  }
+}
+
+async function checkConventionsDflowVersion(cwd, findings) {
+  const conventionsPath = path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md');
+  if (!(await pathExists(conventionsPath))) return;
+  const content = await fs.readFile(conventionsPath, 'utf8').catch(() => '');
+  if (!/^> Dflow Version:/m.test(content)) {
+    findings.push({
+      level: 'info',
+      title: 'dflow/specs/shared/_conventions.md missing Dflow Version line',
+      detail: 'V1 init writes a `> Dflow Version: <x.y.z>` line in the front matter automatically. This project predates that convention.',
+      action: 'Optionally add the line manually so future migration / review can identify the spec convention version.'
+    });
+  }
+}
+
+function printDoctorReport(stdout, cwd, findings) {
+  stdout.write(`Dflow Doctor ${pkg.version}\n`);
+  stdout.write(`Project: ${cwd}\n\n`);
+
+  if (findings.length === 0) {
+    stdout.write('All checks passed. No legacy artifacts detected.\n');
+    return;
+  }
+
+  for (const finding of findings) {
+    stdout.write(`[${finding.level}] ${finding.title}\n`);
+    stdout.write(`        ${finding.detail}\n`);
+    stdout.write(`        ${finding.action}\n\n`);
+  }
+
+  const counts = { warn: 0, info: 0 };
+  for (const f of findings) counts[f.level] = (counts[f.level] || 0) + 1;
+  stdout.write(`${findings.length} finding(s): ${counts.warn} warn, ${counts.info} info.\n`);
+  stdout.write('Doctor is read-only and does not modify any files.\n');
+}
+
 module.exports = {
   runConfigureAgents,
+  runDoctor,
   runInit,
   validateProseLanguage,
   ensureProseLanguageSection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {
@@ -12,8 +12,12 @@
   },
   "files": [
     "bin/",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "docs/",
     "lib/",
+    "TEMPLATE-COVERAGE.md",
+    "TEMPLATE-LANGUAGE-GLOSSARY.md",
     "templates/",
     "README.md"
   ],

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

@@ -30,6 +30,7 @@ are not available in the current AI tool:
 | `/dflow:finish-feature` | Implementation is complete and needs drift closure. |
 | `/dflow:verify` | Specs, domain docs, implementation, and tests need consistency checks. |
 | `/dflow:pr-review` | A change is ready for SDD/DDD review. |
+| `/dflow:report-dflow-feedback` | You found a Dflow issue or improvement and want a sanitized upstream feedback draft. |
 
 ## Source of Truth
 
@@ -53,6 +54,34 @@ Dflow-owned project documents live under `dflow/specs/`.
 4. Check drift before calling work complete.
 5. Follow `dflow/specs/shared/_conventions.md`, especially `## Prose Language`.
 
+## 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.
+
 ## Tool-Specific Notes
 
 This file is the canonical Dflow guide. Root-level files such as

package/templates/brownfield/scaffolding/CLAUDE-md-snippet.md

@@ -5,9 +5,9 @@
 > This file is a **snippet**, not a standalone `CLAUDE.md`. Its purpose
 > is to be merged into your project's root `CLAUDE.md`:
 >
-> - New `npx dflow-sdd-ddd init` output uses
->   `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical guide and
->   creates a thin `CLAUDE.md` shim that points back to it.
+> - New Dflow CLI init output (`dflow init`, or `npx dflow-sdd-ddd init` when
+>   using the no-install path) uses `dflow/specs/shared/AI-AGENT-GUIDE.md` as
+>   the canonical guide and creates a thin `CLAUDE.md` shim that points back to it.
 > - Use this legacy snippet only if you intentionally want the older
 >   Claude-specific two-H2 layout in your project's root `CLAUDE.md`.
 
@@ -45,7 +45,7 @@ ASP.NET Core 做準備。
 
 ```
 dflow/specs/
-├── shared/                   # 專案級治理文件（由 npx dflow-sdd-ddd init 寫入）
+├── shared/                   # 專案級治理文件（由 Dflow CLI init 寫入）
 │   ├── _overview.md          # 系統現況與遷移策略
 │   ├── _conventions.md       # 規格撰寫慣例
 │   └── Git-principles-*.md   # Git 規範（gitflow 或 trunk 版）
@@ -97,7 +97,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 當你作為 AI assistant 被呼叫時，若偵測到使用者需要 SDD/DDD 工作流
 引導，請參考 Dflow entry points：
 
-- `npx dflow-sdd-ddd init` — 專案初始化（建立 `dflow/specs/` 結構）
+- Dflow CLI init command (`dflow init`, or `npx dflow-sdd-ddd init` when using the no-install path) — 專案初始化（建立 `dflow/specs/` 結構）
 - `/dflow:new-feature` — 新功能開發
 - `/dflow:new-phase` — 在 active feature 內新增階段
 - `/dflow:modify-existing` — 修改既有功能
@@ -105,6 +105,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - `/dflow:finish-feature` — feature 收尾
 - `/dflow:pr-review` — PR 審查
 - `/dflow:verify` — rules.md ↔ behavior.md 漂移檢查
+- `/dflow:report-dflow-feedback` — 草擬給 Dflow upstream 的已清理回饋，不自動送出
 - `/dflow:status` / `/dflow:next` / `/dflow:cancel` — 狀態管理
 
 ### Project-Level Supplemental Rules
@@ -161,5 +162,5 @@ When merging this snippet into an existing `CLAUDE.md`:
    duplicate it.
 
 If you are starting from scratch (no existing `CLAUDE.md`), the
-`npx dflow-sdd-ddd init` flow will install this snippet as-is and you
-can refine from there.
+the Dflow CLI init flow (`dflow init`, or `npx dflow-sdd-ddd init` when using
+the no-install path) will install this snippet as-is and you can refine from there.

package/templates/brownfield/scaffolding/_conventions.md

@@ -3,6 +3,7 @@
 # Spec Writing Conventions — {System Name}
 
 > Created: {YYYY-MM-DD}
+> Dflow Version: {dflow-version}
 > Scope: how spec documents are authored and named in this project.
 > Audience: engineers writing specs; AI assistants producing spec drafts.
 

package/templates/brownfield/templates/CLAUDE.md

@@ -17,7 +17,7 @@
 
 ```
 dflow/specs/
-├── shared/                   # 專案級治理文件（由 npx dflow-sdd-ddd init 寫入）
+├── shared/                   # 專案級治理文件（由 dflow init 寫入）
 │   ├── _overview.md          # 系統現況與遷移策略
 │   └── _conventions.md       # 規格撰寫慣例與模板
 ├── domain/                   # 領域知識

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

@@ -19,30 +19,33 @@ Template note (for AI):
   `phase-spec-YYYY-MM-DD-{slug}.md` placed at
   `dflow/specs/features/active/{SPEC-ID}-{slug}/`.
 
-  Each section below carries an HTML comment indicating its fill-in phase (Phase 1-4).
-  These phase markers let /dflow:status and the completion checklist track progress.
-  Phases correspond to SKILL.md § Guiding Questions by Phase:
-    Phase 1 - Understanding (What & Why)
-    Phase 2 - Domain Analysis (Where does it live?)
-    Phase 3 - Spec Writing (Behavior + Rules + Edge Cases)
-    Phase 4 - Implementation Planning
-  The "Implementation Tasks" section at the end is generated by AI after Phase 4 planning is done
+  Each section below carries an HTML comment indicating its fill-in activity (Activity 1-4).
+  These activity markers let /dflow:status and the completion checklist track progress.
+  Activities correspond to SKILL.md § Guiding Questions by Activity:
+    Activity 1: Understanding (What & Why)
+    Activity 2: Domain Analysis (Where does it live?)
+    Activity 3: Spec Writing (Behavior + Rules + Edge Cases)
+    Activity 4: Implementation Planning
+  The "Implementation Tasks" section at the end is generated by AI after Activity 4 (Implementation Planning) is done
   (see new-feature-flow.md Step 5 end / new-phase-flow.md Step 4 end /
    modify-existing-flow.md Step 4 end).
 
+  Note: "phase 2+ specs" / "Phase 2+" in the BR and Delta sections below refers to
+  the N-th phase-spec of this feature (i.e. iteration unit), NOT an activity number.
+
   For phase 2+ specs in the same feature: only list BRs that are NEW or
   MODIFIED in this phase under "Business Rules"; do not re-copy unchanged BRs from
   prior phases. The cumulative state lives in the feature's `_index.md`
   Current BR Snapshot table.
 -->
 
-## Problem Description <!-- Fill timing: Phase 1 -->
+## Problem Description <!-- Fill timing: Activity 1: Understanding -->
 
 這個功能要解決什麼問題？誰需要它？
 
 > 用使用者的角度描述，避免技術用語。
 
-## Domain Concepts <!-- Fill timing: Phase 2 -->
+## Domain Concepts <!-- Fill timing: Activity 2: Domain Analysis -->
 
 涉及的 Domain 概念（引用 `dflow/specs/domain/{context}/models.md`）：
 
@@ -55,7 +58,7 @@ Template note (for AI):
 - [ ] `dflow/specs/domain/{context}/models.md` — 新增模型定義
 
 <!-- dflow:section behavior-scenarios -->
-## Behavior Scenarios <!-- Fill timing: Phase 3 -->
+## Behavior Scenarios <!-- Fill timing: Activity 3: Spec Writing -->
 
 ### Main Success Scenario
 
@@ -75,7 +78,7 @@ Scenario: {替代情境}
   Then {不同的預期結果}
 ```
 
-## Business Rules <!-- Fill timing: Phase 3 -->
+## Business Rules <!-- Fill timing: Activity 3: Spec Writing -->
 
 > Phase 2+ 注意：本段僅列**本 phase 新增 / 修改到的 BR**；未變動的 BR 不重抄
 > （它們的當前狀態見 feature 的 `_index.md` Current BR Snapshot 表）。
@@ -85,7 +88,7 @@ Scenario: {替代情境}
 | BR-01 | {規則描述} | |
 | BR-02 | {規則描述} | |
 
-## Delta from prior phases <!-- Fill timing: Phase 3; skip for the first phase -->
+## Delta from prior phases <!-- Fill timing: Activity 3: Spec Writing; skip for the first phase -->
 
 > 本段僅記**本 phase 相對前一 phase 的變化**，不累積歷史。歷史由 feature 目錄下
 > 各 phase-spec 的本段串接閱讀；feature 層的當前累積狀態見 `_index.md` 的
@@ -119,14 +122,14 @@ Then {新的預期結果}
 - BR-003 金額上限
 - BR-005 提交後不可修改
 
-## Edge Cases <!-- Fill timing: Phase 3 -->
+## Edge Cases <!-- Fill timing: Activity 3: Spec Writing -->
 
 | ID | Case | Expected Handling |
 |---|---|---|
 | EC-01 | {邊界描述} | {處理方式} |
 | EC-02 | {邊界描述} | {處理方式} |
 
-## Implementation Notes <!-- Fill timing: Phase 4 -->
+## Implementation Notes <!-- Fill timing: Activity 4: Implementation Planning -->
 
 ### Current WebForms Implementation
 
@@ -148,7 +151,7 @@ Then {新的預期結果}
 
 > 遷移時需要注意的事項，或者現在的設計如何幫助未來遷移。
 
-## Data Structure Changes <!-- Fill timing: Phase 4 -->
+## Data Structure Changes <!-- Fill timing: Activity 4: Implementation Planning -->
 
 > 涉及的資料表與欄位變更（如有）
 
@@ -156,7 +159,7 @@ Then {新的預期結果}
 |---|---|---|---|
 | {Table} | {Column} | 新增/修改/刪除 | |
 
-## Test Strategy <!-- Fill timing: Phase 4 -->
+## Test Strategy <!-- Fill timing: Activity 4: Implementation Planning -->
 
 > Domain 層的單元測試應驗證哪些行為？
 
@@ -164,14 +167,14 @@ Then {新的預期結果}
 - [ ] {測試案例 2}
 
 <!-- dflow:section open-questions -->
-## Open Questions <!-- Fill timing: Phase 1-4 -->
+## Open Questions <!-- Fill timing: Activity 1-4; any time during planning -->
 
 - {尚未釐清的需求、規則、資料或實作問題}
 
 <!-- dflow:section implementation-tasks -->
-## Implementation Tasks <!-- Fill timing: generated by AI after Phase 4; all items should be checked at completion -->
+## Implementation Tasks <!-- Fill timing: generated by AI after Activity 4: Implementation Planning; all items should be checked at completion -->
 
-> AI 在 Phase 4 實作規劃完成後，根據「Implementation Notes」產生的具體任務清單。
+> AI 在 Activity 4 (Implementation Planning) 完成後，根據「Implementation Notes」產生的具體任務清單。
 > 格式：`[LAYER]-[NUMBER]: 任務描述`
 > 分類標籤（Brownfield track）：
 >   - `DOMAIN`  — Domain 層類別、VO、Service、Interface

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

@@ -30,6 +30,7 @@ are not available in the current AI tool:
 | `/dflow:finish-feature` | Implementation is complete and needs drift closure. |
 | `/dflow:verify` | Specs, domain docs, implementation, and tests need consistency checks. |
 | `/dflow:pr-review` | A change is ready for SDD/DDD review. |
+| `/dflow:report-dflow-feedback` | You found a Dflow issue or improvement and want a sanitized upstream feedback draft. |
 
 ## Source of Truth
 
@@ -53,6 +54,34 @@ Dflow-owned project documents live under `dflow/specs/`.
 4. Check drift before calling work complete.
 5. Follow `dflow/specs/shared/_conventions.md`, especially `## Prose Language`.
 
+## 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.
+
 ## Tool-Specific Notes
 
 This file is the canonical Dflow guide. Root-level files such as

package/templates/greenfield/scaffolding/CLAUDE-md-snippet.md

@@ -14,9 +14,9 @@
 
 ## How to use this snippet
 
-- New `npx dflow-sdd-ddd init` output uses
-  `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical guide and creates
-  a thin `CLAUDE.md` shim that points back to it.
+- New Dflow CLI init output (`dflow init`, or `npx dflow-sdd-ddd init` when
+  using the no-install path) uses `dflow/specs/shared/AI-AGENT-GUIDE.md` as
+  the canonical guide and creates a thin `CLAUDE.md` shim that points back to it.
 - Use this legacy snippet only if you intentionally want the older
   Claude-specific two-H2 layout in your project's root `CLAUDE.md`.
 
@@ -66,7 +66,7 @@ Presentation → Application → Domain ← Infrastructure
 ### Project Structure
 
 完整 specs 目錄結構見 Dflow skill `SKILL.md` § "Project Structure"。
-以下只列本專案當前狀態（`npx dflow-sdd-ddd init` 建立後可能還未全填）：
+以下只列本專案當前狀態（Dflow CLI init 建立後可能還未全填）：
 
 ```
 dflow/specs/
@@ -101,13 +101,14 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - `sdd-ddd-greenfield-skill/references/` 內各 flow 文件
 
 本專案採用的 Dflow entry points：
-- `npx dflow-sdd-ddd init` — 專案初始化（一次性，已執行過）
+- Dflow CLI init command (`dflow init`, or `npx dflow-sdd-ddd init` when using the no-install path) — 專案初始化（一次性，已執行過）
 - `/dflow:new-feature` — 新功能
 - `/dflow:new-phase` — 既有 active feature 加新 phase
 - `/dflow:modify-existing` — 修改既有行為
 - `/dflow:bug-fix` — Bug 修復
 - `/dflow:finish-feature` — Feature 收尾 + 整合摘要
 - `/dflow:pr-review` — PR 審查檢查點
+- `/dflow:report-dflow-feedback` — 草擬給 Dflow upstream 的已清理回饋，不自動送出
 
 ### Core Principles (Project Reaffirmed)
 
@@ -164,5 +165,6 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - The snippet does NOT re-copy the Dflow decision tree, Ceremony
   Scaling criteria, or per-flow step details — those live in the
   skill and change when the skill evolves
-- Re-run `npx dflow-sdd-ddd init` will NOT overwrite an existing
-  `CLAUDE.md`; if you want to re-sync, merge manually
+- Re-running the Dflow CLI init command (`dflow init`, or `npx dflow-sdd-ddd init`
+  when using the no-install path) will NOT overwrite an existing `CLAUDE.md`;
+  if you want to re-sync, merge manually

package/templates/greenfield/scaffolding/_conventions.md

@@ -3,6 +3,7 @@
 # Spec Writing Conventions — {System Name}
 
 > Created: {YYYY-MM-DD}
+> Dflow Version: {dflow-version}
 > Scope: how spec documents are authored and named in this project.
 > Audience: engineers writing specs; AI assistants producing spec drafts.
 
@@ -100,7 +101,7 @@ Project-specific guidance when filling these templates:
   descriptions (Mermaid state diagram or Given / When / Then + "And
   the Aggregate is in state X").
 - **CQRS split**: commands (write) vs queries (read) should be
-  identified during Phase 4 (Implementation Planning). Commands
+  identified during Activity 4 (Implementation Planning). Commands
   generally map 1:1 to an Aggregate method; queries bypass the
   Domain layer and read projections.
 

package/templates/greenfield/templates/CLAUDE.md

@@ -34,7 +34,7 @@ Presentation → Application → Domain ← Infrastructure
 
 ```
 dflow/specs/
-├── shared/                   # 專案級治理文件（由 npx dflow-sdd-ddd init 寫入）
+├── shared/                   # 專案級治理文件（由 dflow init 寫入）
 │   ├── _overview.md          # 系統現況與遷移策略
 │   └── _conventions.md       # 規格撰寫慣例
 ├── domain/

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

@@ -19,17 +19,20 @@ Template note (for AI):
   `phase-spec-YYYY-MM-DD-{slug}.md` placed at
   `dflow/specs/features/active/{SPEC-ID}-{slug}/`.
 
-  Each section below carries an HTML comment indicating its fill-in phase (Phase 1-4).
-  These phase markers let /dflow:status and the completion checklist track progress.
-  Phases correspond to SKILL.md § Guiding Questions by Phase:
-    Phase 1 - Understanding (What & Why)
-    Phase 2 - Domain Modeling (BC, Aggregate, VO, Events)
-    Phase 3 - Spec Writing (Behavior + Rules + Edge Cases)
-    Phase 4 - Implementation Planning (layer-by-layer)
-  The "Implementation Tasks" section at the end is generated by AI after Phase 4 planning is done
+  Each section below carries an HTML comment indicating its fill-in activity (Activity 1-4).
+  These activity markers let /dflow:status and the completion checklist track progress.
+  Activities correspond to SKILL.md § Guiding Questions by Activity:
+    Activity 1: Understanding (What & Why)
+    Activity 2: Domain Modeling (BC, Aggregate, VO, Events)
+    Activity 3: Spec Writing (Behavior + Rules + Edge Cases)
+    Activity 4: Implementation Planning (layer-by-layer)
+  The "Implementation Tasks" section at the end is generated by AI after Activity 4 (Implementation Planning) is done
   (see new-feature-flow.md Step 5 end / new-phase-flow.md Step 4 end /
    modify-existing-flow.md Step 3 end).
 
+  Note: "phase 2+ specs" / "Phase 2+" in the BR and Delta sections below refers to
+  the N-th phase-spec of this feature (i.e. iteration unit), NOT an activity number.
+
   For phase 2+ specs in the same feature: only list BRs that are NEW or
   MODIFIED in this phase under "Business Rules"; do not re-copy unchanged BRs from
   prior phases. The cumulative state lives in the feature's `_index.md`
@@ -37,11 +40,11 @@ Template note (for AI):
   bounded context's `rules.md` / `behavior.md` (synced at /dflow:finish-feature).
 -->
 
-## Problem Description <!-- Fill timing: Phase 1 -->
+## Problem Description <!-- Fill timing: Activity 1: Understanding -->
 
 > 用使用者的角度描述，避免技術用語。
 
-## Domain Concepts <!-- Fill timing: Phase 2 -->
+## Domain Concepts <!-- Fill timing: Activity 2: Domain Modeling -->
 
 涉及的 Domain 概念（引用 `dflow/specs/domain/{context}/models.md`）：
 
@@ -55,7 +58,7 @@ Template note (for AI):
 - [ ] `dflow/specs/domain/{context}/events.md` — Domain Events
 
 <!-- dflow:section behavior-scenarios -->
-## Behavior Scenarios <!-- Fill timing: Phase 3 -->
+## Behavior Scenarios <!-- Fill timing: Activity 3: Spec Writing -->
 
 ### Main Success Scenario
 
@@ -76,7 +79,7 @@ Scenario: {替代情境}
   Then {不同結果}
 ```
 
-## Business Rules <!-- Fill timing: Phase 3 -->
+## Business Rules <!-- Fill timing: Activity 3: Spec Writing -->
 
 > Phase 2+ 注意：本段僅列**本 phase 新增 / 修改到的 BR**；未變動的 BR 不重抄
 > （它們的當前狀態見 feature 的 `_index.md` Current BR Snapshot 表）。
@@ -86,7 +89,7 @@ Scenario: {替代情境}
 | BR-01 | {規則描述} | Domain: {Entity/VO/Service} |
 | BR-02 | {規則描述} | Domain: {Entity/VO/Service} |
 
-## Delta from prior phases <!-- Fill timing: Phase 3; skip for the first phase -->
+## Delta from prior phases <!-- Fill timing: Activity 3: Spec Writing; skip for the first phase -->
 
 > 本段僅記**本 phase 相對前一 phase 的變化**，不累積歷史。歷史由 feature 目錄下
 > 各 phase-spec 的本段串接閱讀；feature 層的當前累積狀態見 `_index.md` 的
@@ -122,19 +125,19 @@ And {產生的 Domain Event}
 - BR-003 金額上限
 - BR-005 提交後不可修改
 
-## Edge Cases <!-- Fill timing: Phase 3 -->
+## Edge Cases <!-- Fill timing: Activity 3: Spec Writing -->
 
 | ID | Case | Expected Handling |
 |---|---|---|
 | EC-01 | {邊界描述} | {處理方式} |
 
-## Domain Events <!-- Fill timing: Phase 2-3; draft during design, finalized during spec writing -->
+## Domain Events <!-- Fill timing: Activity 2-3; draft during Domain Modeling, finalized during Spec Writing -->
 
 | Event | Trigger | Handler | Sync / Async |
 |---|---|---|---|
 | {EventName} | {何時觸發} | {Handler} | 同步/異步 |
 
-## Implementation Plan (Layer by Layer) <!-- Fill timing: Phase 4 -->
+## Implementation Plan (Layer by Layer) <!-- Fill timing: Activity 4: Implementation Planning -->
 
 ### Domain Layer
 > Aggregate 設計、Value Objects、Events、Interfaces
@@ -148,13 +151,13 @@ And {產生的 Domain Event}
 ### Presentation Layer
 > API Endpoint 設計、Request/Response 模型
 
-## Data Structure Changes <!-- Fill timing: Phase 4 -->
+## Data Structure Changes <!-- Fill timing: Activity 4: Implementation Planning -->
 
 | Table | Column | Change Type | Description |
 |---|---|---|---|
 | {Table} | {Column} | 新增/修改/刪除 | |
 
-## Test Strategy <!-- Fill timing: Phase 4 -->
+## Test Strategy <!-- Fill timing: Activity 4: Implementation Planning -->
 
 ### Domain Unit Tests
 - [ ] {不變條件測試}
@@ -169,14 +172,14 @@ And {產生的 Domain Event}
 - [ ] {Repository 測試}
 
 <!-- dflow:section open-questions -->
-## Open Questions <!-- Fill timing: Phase 1-4 -->
+## Open Questions <!-- Fill timing: Activity 1-4; any time during planning -->
 
 - {尚未釐清的需求、規則、資料或實作問題}
 
 <!-- dflow:section implementation-tasks -->
-## Implementation Tasks <!-- Fill timing: generated by AI after Phase 4; all items should be checked at completion -->
+## Implementation Tasks <!-- Fill timing: generated by AI after Activity 4: Implementation Planning; all items should be checked at completion -->
 
-> AI 在 Phase 4 實作規劃完成後，根據「Implementation Plan (Layer by Layer)」產生的具體任務清單。
+> AI 在 Activity 4 (Implementation Planning) 完成後，根據「Implementation Plan (Layer by Layer)」產生的具體任務清單。
 > 格式：`[LAYER]-[NUMBER]: 任務描述`
 > 分類標籤（Greenfield track，對應 Clean Architecture 各層）：
 >   - `DOMAIN` — Aggregate、Entity、VO、Domain Event、Domain Service、Repository Interface