dflow-sdd-ddd 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,977 @@
 
 ---
 
+## 0.4.0 — 2026-05-19 — Language-agnostic templates and skill source
+
+**Proposals**：PROPOSAL-030（language-agnostic templates and skill source；
+post-v0.3.0 follow-up; cross-model reviewed with Codex CLI）
+
+**變更**：
+
+- **`lib/init.js` canonical placeholders + backward-compat aliases**（PROPOSAL-030 Group 1）：
+  - 新增 canonical placeholders：`{Language}` / `{Framework}` /
+    `{Framework version}` / `{ORM / persistence}` / `{ORM version}` /
+    `{Mediator}`（與既有 `{Test framework}` 對齊）
+  - 既有 .NET-specific placeholder（`{ASP.NET Core version}` /
+    `{EF Core version}` / `{MediatR version}` / `{ASP.NET WebForms version}` /
+    `{.NET Framework version}` / `{ORM / Data Access}`）保留為 backward-compat
+    alias，substitute 同 canonical 值
+  - `extractTechStackPlaceholders` regex 擴充：Spring Boot / NestJS /
+    Fastify / Express / Django / FastAPI / Flask / Gin / Echo / Laravel
+    framework；EF Core / Hibernate / Spring Data JPA / SQLAlchemy /
+    Prisma / TypeORM / MikroORM / GORM / Eloquent / Doctrine ORM；JUnit /
+    Vitest / Jest / Mocha / pytest / unittest / go test / PHPUnit / Pest
+    test framework；C# / TypeScript / JavaScript / Kotlin / Java /
+    Python / Go / PHP / Ruby language
+  - `detectProjectSignals` 加 `stackHints`（從 `pom.xml` / `package.json` /
+    `pyproject.toml` / `go.mod` / `Cargo.toml` / `composer.json` / `Gemfile`
+    fingerprint）— **不**自動推 `trackHint`，user 選擇仍主導
+  - `printNextSteps` 加 `docs/examples-by-stack.md` pointer
+- **Brownfield skill source + templates language-agnostic**（Group 2 + Group 2 follow-up）：
+  - `Code-Behind` → umbrella `business logic embedded in delivery/entrypoint
+    code`，context 簡寫 `presentation-layer logic` (web/UI/API) 或
+    `entrypoint-layer logic` (CLI/batch/pipeline)
+  - `ASP.NET Core migration` / `future ASP.NET Core migration` →
+    `target architecture`
+  - `No System.Web references` → `No delivery-framework references`，明列
+    HTTP req/resp、session/cookie、job-runner context、CLI flag parser、
+    ViewState equivalents 等多 stack 示例
+  - `純 C# class` → `framework-pure class`
+  - Layer tag `PAGE` → `DELIVERY`（含 lightweight-spec 的 layer tags
+    說明擴及 web/CLI/job/pipeline）
+  - SKILL.md 新增 `## Scope: When Dflow Brownfield Applies` 段，明標適用
+    business-rule-bearing legacy systems / 不適用純 infra script 或無
+    domain model pipeline
+  - 目錄樹 `src/Pages/` → `src/Delivery/`（與 umbrella term 對齊）
+  - SKILL.md / templates/CLAUDE.md / scaffolding/CLAUDE-md-snippet.md /
+    scaffolding/_overview.md 在 directory tree 前加 stack-adapt callout
+- **Greenfield skill source + templates language-agnostic**（Group 3 + Group 3 follow-up）：
+  - 檔案標題 `# Project — ASP.NET Core + DDD` →
+    `# Project — Clean Architecture + DDD`
+  - `# X Workflow — ASP.NET Core` → `# X Workflow — Greenfield Clean Architecture`
+  - Cross-edition `Same as WebForms version` → `Same as Brownfield edition`
+  - `_overview.md` stack table 全用 canonical placeholders
+  - `init-project-flow.md` Q2 prompt + substitution table 改 canonical
+  - Project Layout `{Project}.Domain` `.NET` 慣例保留 + 加詳細 callout
+    列 Java/Spring、Node/TS、Python、Go、PHP/Laravel 對應
+  - `PRACTICE_PLAN_tw.md` 開頭加 disclaimer：練習以 .NET 為示例、
+    Dflow 本身 language-agnostic
+  - Git-principles-{gitflow,trunk} 的 `NuGet dependencies` →
+    `external package dependencies`
+- **`docs/examples-by-stack.md` 新增**（Group 4）：520 行 public
+  appendix，列 7 stack 段（.NET ASP.NET Core greenfield / .NET WebForms
+  brownfield / Java Spring Boot / Node TypeScript NestJS / Python FastAPI /
+  Go Gin / PHP Laravel），每段：substituted stack table + project
+  layout + per-stack domain purity check + test framework + run
+  command。`README.md` / `README.en.md` 在 Project Tracks 段加 link。
+- **`planning/init-contract-spec.md` 同步**（Group 1）：placeholder
+  inventory + alias table + detectProjectSignals stackHints 文件對齊
+
+**Breaking / migration notes**：
+
+- **無 runtime API 破壞**：v0.3.0 寫入 user project 的 `CLAUDE.md` /
+  `_overview.md` 等檔案 Dflow 不會自動覆蓋；backward-compat alias 只保護
+  future init 動作的 placeholder 替換不破壞，不主動 migrate 既有檔案
+- 若要對齊新風格，請參考 `docs/examples-by-stack.md` 對既有 init 產出的
+  檔案手動修改
+- AI agent 對話中讀 skill source 會自動切到新術語（Code-Behind →
+  delivery/entrypoint code、ASP.NET Core migration → target architecture）；
+  若 user 有自製 prompt / shortcut 用到舊術語，建議同步更新但**不強制**
+
+**驗證**：
+
+- `npm test`（含新增 Java/Spring Boot greenfield init e2e，assert 不殘留 .NET literals）
+- `scripts/check-repo-consistency.sh`（source ↔ packaged mirror diff clean）
+- 全 repo grep `Code-Behind` / `ASP.NET` / `WebForms` / `NuGet` 在 active skill / template surface 範圍內無殘留（archive/ 與 test fixture 刻意保留）
+
+**邊界**：
+
+- Tutorial 目錄 `tutorial/**` scenario prose 為教學劇情 artifact，明確
+  out of scope（PROPOSAL-030 §影響範圍 已宣告）
+- `test/smoke.mjs` 既有 .NET fixture 保留作為 brownfield init 測試輸入
+- Dist projection 在所有 Group merge 完後一次性 export（Director-only）
+
+---
+
+## 0.3.0 — 2026-05-18 — Workflow flow completion, terminology disambiguation, bilingual public docs
+
+**Proposals**：PROPOSAL-022（CLI install 推薦路徑）、PROPOSAL-023（line-ending normalization）、PROPOSAL-024（README zh-TW + migration reframing）、PROPOSAL-025（Phase 術語拆解：Step Gate / Activity）、PROPOSAL-026（`/dflow:new-phase` 補 implementation / verification）、PROPOSAL-027（handoff lifecycle，dev-only）、PROPOSAL-028（`docs/*.md` 雙語化）、PROPOSAL-029（tutorial 檔名 align）。
+
+**變更**：
+
+- **CLI install 推薦路徑改為 `npm install -g dflow-sdd-ddd` + `dflow init`**（PROPOSAL-022）；`npx dflow-sdd-ddd init` 降為 labeled alternative。README、`docs/*.md`、scaffolding 模板與 bug template 全部對齊。
+- **`/dflow:new-phase` 從 5-step planning-only flow 擴為 7-step full phase workflow**（PROPOSAL-026），新增 Step 6 implementation / verification 與 Step 7 phase-level completion；phase-spec frontmatter lifecycle `status: in-progress` → `status: completed`。Greenfield / Brownfield `new-phase-flow.md`、兩份 `SKILL.md`、tutorial walkthrough-03 全部同步。
+- **Phase 術語拆解**（PROPOSAL-025）：
+  - `phase-spec` / `/dflow:new-phase` 保留（user-facing API）
+  - **Phase Gate → Step Gate**（Workflow 內 Step ↔ Step 之間的 checkpoint）
+  - **Phase 1-5 → Activity N: Name**（SDD 概念活動：Understanding / Domain Modeling / Spec Writing / Implementation Planning / Testing Strategy）
+- **bilingual public docs**（PROPOSAL-024 / 028）：
+  - `README.md` 改 zh-TW primary，新增 `README.en.md` 英文 alt，兩份頂部都有 language switcher
+  - `docs/` 6 份 user-facing docs（`why-ddd-for-ai`、`evaluating-dflow`、`using-with-{claude-code,codex,gemini-cli,github-copilot}`）全部雙語化：`<file>.md` zh-TW + `<file>.en.md` en，含 language switcher 與 outgoing-ref 分流
+- **Tutorial 檔名 align**（PROPOSAL-029）：14 份 `walkthrough-*.zh-TW.md` + 3 份 helper 全部去掉語言後綴，落到 `<file>.md`，與 README / docs pattern 統一
+- **line-ending policy**（PROPOSAL-023）：新增 `.gitattributes` 以 `* text=auto eol=lf` + `.bat`/`.cmd` CRLF 例外 + 二進位防護
+- **公開 docs 整體 register polish**：README round 2（reframe features around engineer problems + rewrite Documentation Model）、tier 標籤對齊、`using-with-github-copilot.md` register polish
+
+**Breaking / migration notes**：
+
+- **Phase Gate / Phase 1-5 在 AI agent 對話中已淘汰**。已採用 Dflow 的專案會在下次 AI 助理重新讀 skill 時自動換到新術語（skill source 已更新）。若 user 有自製 prompt / shortcut 用到 "Phase Gate" 或 "Phase 1-5"，請改成 "Step Gate" 與 "Activity N: <Name>"。
+- **`/dflow:new-phase` 行為擴展**：原本只寫 phase-spec / refresh `_index.md`，現在會走完 implementation / verification / phase-level completion。既有的 phase-spec 不需 retrofit；新跑的 `/dflow:new-phase` 走新流程。
+- **Tutorial 檔名變動**：若有外部連結指向 `tutorial/0X-*/walkthrough-NN-*.zh-TW.md`，需改為去掉 `.zh-TW` 後綴的版本。tutorial 是教學素材、無 runtime 影響。
+- **CLI install 推薦變更**：舊文件用 `npx dflow-sdd-ddd init` 仍可用，只是 README 與 docs 預設改成全域安裝。
+
+**邊界**：
+
+- 無 runtime API 破壞：`bin/dflow.js`、`lib/init.js`、`test/smoke.mjs`、scaffolding mirrors 行為向後相容
+- 無 `package.json#files` 變動（`.en.md` 自然透過既有 include 規則進 tarball）
+- PROPOSAL-027（handoff lifecycle）為 dev-only governance，不影響 public 行為
+- `docs/migrating-to-dflow-v1.md` 維持英文且未動內容（PROPOSAL-028 明確 defer 至有 real adopter 或需實質改寫時再翻譯）
+
+**驗證**：
+
+- `npm test`
+- `npm pack --dry-run`
+- `scripts/check-repo-consistency.sh`
+- `scripts/export-dist.sh --check`
+- `git diff --check`
+
+詳見以下 dated entries（按時間倒序）。
+
+---
+
+## 2026-05-17 ～ 2026-05-18 — `docs/*.md` 雙語化 (PROPOSAL-028)
+
+**變更**：
+
+延續 PROPOSAL-024 的 `<file>.md` (zh-TW primary) + `<file>.en.md` (en alternative) pattern，把 `docs/` 下 6 份 user-facing 文件雙語化。每份 doc 一個 commit、Sonnet worker 草譯、Director review。
+
+| Commit | Doc | en 行 / zh-TW 行 |
+|---|---|---|
+| `07c1cb9` | `docs/why-ddd-for-ai.md` | 36 / 37 |
+| `0a3ddd5` | `docs/evaluating-dflow.md` | 238 / 169 |
+| `8264ab4` | `docs/using-with-claude-code.md` | 208 / 199 |
+| `4720280` | `docs/using-with-codex.md` | 246 / 226 |
+| `3dfa428` | `docs/using-with-gemini-cli.md` | 198 / 184 |
+| `d065b3f` | `docs/using-with-github-copilot.md` | 136 / 178 |
+
+每份 doc 都掛 language switcher（在 H1 後第一行），outgoing refs 依規分流：zh-TW doc 連 `.md` + zh-TW anchor、en doc 連 `.en.md` + en anchor。Anchor 對齊例如 `#init-產生的檔案`、`#workflow-模型`、`#30-分鐘評估-playbook`。README.md 與 README.en.md、`docs/evaluating-dflow.md`(zh+en)、`docs/migrating-to-dflow-v1.md`、`docs/using-with-*.md` 互引、`planning/public-onboarding-tasklist.md` 的 incoming refs 全 sweep 並依語言分流。
+
+**Side findings & pre-translation sweeps**（cross-model review 階段 + 翻譯過程中發現並一併處理）：
+
+- `4023a99`：修 `docs/evaluating-dflow.md:178` tier 標籤倒置（T1 Lightweight / T2 Standard / T3 Full → T1 Heavy / T2 Light / T3 Trivial），對齊 README canonical 排序
+- `3dfa428` 順手：移除 `using-with-gemini-cli.en.md` 殘留章節編號（`## 1. / ## 2. / ...`），對齊其他 3 份 per-tool en docs
+- `82b3da4`：bilingualize 前先 polish `using-with-github-copilot.md` register（headings → Title Case、backtick path mentions → markdown links、合併「(verify with maintainer)」hedges 為單一 footer note）
+- `d065b3f` 順手：補上 `using-with-github-copilot.en.md` 缺的「Tool / Generated shim / Loads canonical guide via」對照表，4 份 per-tool docs 兩語版本完全對稱
+
+**Cross-model review**：
+
+PROPOSAL-028 起草後（`9da50f6`）走 cross-model review（reviewer 另一個 session）回 `approve with modifications`。所有 modifications 整合進 Proposal 內文（`fffabcb`）：scope 收斂為 Option B 分批 commit + Worker 草譯 + Director review、新增 Acceptance criteria 段（強制 pre-translation stale sweep）、新增 Validation 段（dev commit vs dist projection 兩級）、補 outgoing refs 分流規則、補 npm tarball 驗證。
+
+**Scope 不含**：
+
+- `docs/migrating-to-dflow-v1.md`：deferred（runtime contingency endpoint、Dflow 目前無 user 也無非 OBTS adopter；等真有 adopter 或該檔需實質改寫時再翻譯）。本次只更新它對其他 6 份新雙語 docs 的 outgoing refs 指向 `.en.md` 版本。
+- `docs/npm-publish-checklist.md`、`docs/release-versioning-policy.md`：maintainer-facing、user 是唯一 maintainer，英文 ops 文件對外更直覺，明確不譯。
+
+**邊界**：
+
+- dev-only；dist projection 留待 user-approved checkpoint
+- 純 public-facing docs；無 lib/、bin/、test/、scaffolding 變動。`package.json` `files`、`scripts/export-dist.sh` `include_paths`、`test/smoke.mjs`、`bin/dflow.js`、`lib/init.js`、scaffolding mirrors **全部未動**（runtime 零衝擊）
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release
+
+**驗證**：
+
+- 每份 commit 都驗證 `git diff --check` clean、incoming refs sweep 完整、stale anchor grep 通過
+- npm pack --dry-run（cross-model review 階段）：tarball 自然帶入 `.en.md`，`package.json` `files` 不需動
+
+---
+
+## 2026-05-17 — Tutorial 檔名與 README/docs 雙語規約對齊 (PROPOSAL-029)
+
+**變更**：
+
+純機械 cleanup：把 tutorial/ 內三種不一致後綴（`.zh-TW.md`、`_tw.md`、`.md`）統一到 PROPOSAL-024 規約（zh-TW primary 落在 `.md`，`.en.md` 保留給未來英文版）。
+
+17 個 `git mv` 去掉語言後綴（commit `edd97fa`）：
+
+- 14 個 walkthrough：`tutorial/0{1,2}-{greenfield,brownfield}/walkthrough-{00..06}-*.zh-TW.md` → `walkthrough-{00..06}-*.md`
+- 2 個 tutorial-level helpers：`tutorial/dflow-command-surface.zh-TW.md` 與 `tutorial/how-to-read-dflow-specs.zh-TW.md` → 同名 `.md`
+- 1 個離群檔案：`tutorial/DDD_MINDSET_SHIFT_tw.md` → `tutorial/DDD_MINDSET_SHIFT.md`
+
+Incoming refs sweep 同 commit：`tutorial/README.md`、所有 rename 後 walkthrough 互連、`docs/evaluating-dflow.md`、`docs/using-with-{claude-code,codex,gemini-cli}.md`、`MAINTAINERS.md`、6 份 `planning/*.md`。
+
+**保留不動**：
+
+- `tutorial/0X-*/outputs/` 內所有 demo 專案輸出（非雙語化目標）
+- `CHANGELOG.md` 歷史條目（凍結）
+- `archive/**`（archived 內容凍結）
+
+**邊界**：
+
+- 零 runtime 影響：scaffolding mirrors、`bin/`、`lib/`、`test/`、`scripts/export-dist.sh` 完全不引用 walkthrough 檔名
+- 無翻譯工作（內容語言不變）
+- dev-only；dist projection 留待 user-approved checkpoint
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release
+
+**驗證**：
+
+- `git diff --check` clean
+- 殘留 grep（`\.zh-TW\.md\|_tw\.md` 在 `tutorial`、`docs`、`MAINTAINERS.md`）：0 命中
+- Git rename detection: 90–100% similarity，17 個全部偵測為 rename
+- 不需 `npm test`（純檔名 cleanup、無 runtime 變動）
+
+---
+
+## 2026-05-17 — `/dflow:new-phase` implementation / verification flow (PROPOSAL-026)
+
+**變更**：
+
+- Greenfield / Brownfield `new-phase-flow.md` 從 5-step planning-only flow 改為 7-step full phase workflow：新增 Step 6 implementation / verification 與 Step 7 phase-level completion。
+- `/dflow:new-phase` 現在明確處理 phase-spec frontmatter lifecycle：Step 4 建檔時 `status: in-progress`，Step 7 完成時 `status: completed`。
+- 兩份 `SKILL.md` 的 command summary、Step Gate positions、Reference Files 與 `Completion Checklist Execution` 已同步，並明確區分 new-phase Step 6 -> 7 是 phase-level completion，不做 BC-level docs sync、不 archive feature directory。
+- README zh-TW / English、round-2 planning note、tutorial command surface 與 walkthrough-03 已同步 7-step 語意；`/dflow:new-phase` 不再被描述成只寫文件。
+- Tutorial supervisor-approval fixture 更新為 completed phase state，phase-spec status 與 tests / Implementation Tasks checkbox 對齊 completed `_index.md`。
+
+**邊界**：
+
+- Slash command 名稱、`phase-spec-{date}-{slug}.md` 命名、CLI runtime 不變。
+- `/dflow:finish-feature` 仍負責 BC-level `rules.md` / `behavior.md` / `events.md` sync、feature directory archival 與 Integration Summary。
+- Dev-only；dist projection 留待 user-approved checkpoint。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- `scripts/check-repo-consistency.sh`
+- Targeted stale-grep for `new-phase` 5-step wording and missing `## Step 7`
+
+---
+
+## 2026-05-15 — Phase terminology disambiguation (PROPOSAL-025)
+
+**變更**：
+
+Dflow 內部「Phase」一詞之前同時用於三個互不相關的概念，造成 SKILL.md / templates / tutorial 內歧義。本次重命名清理：
+
+- **(A) `phase-spec` / `/dflow:new-phase`**（feature 內一次「提案 → 實作 → 歸檔」循環）— **保留**。這是已發佈 v0.2.0 的 user-facing API
+- **(B) Phase Gate → Step Gate**（Workflow 內 Step 與 Step 之間需停下等確認的 checkpoint）— 改名。標準書寫格式：`Step Gate: Step X → Step Y`。與既有 `Step-internal transition` 形成詞根對偶
+- **(C) Phase 1-5 → Activity 1-5**（SDD 概念活動：Understanding / Domain Modeling / Spec Writing / Implementation Planning / Testing Strategy）— 改名。HTML comment 標準格式 `<!-- Fill timing: Activity N: Name -->`（編號 + 名稱，提升 AI 排序與人類可讀性）
+
+**檔案範圍**：~30 個檔案、3 個 commit（atomic terminology rename）：
+
+- `c12f909` Add PROPOSAL-025 proposal (approved, cross-model reviewed by Codex)
+- `f091ffb` (B) Phase Gate → Step Gate in 12 skill source files；連帶 `/dflow:next` 與 Confirmation Signals 的 "next phase" / "next-phase" idiom 改成 "next step" 避免與 (A) 撞詞
+- `f0e7bcf` (C) Phase 1-5 → Activity N: Name in 13 source + packaged mirror files；含 SKILL.md `Guiding Questions by Phase` 段、phase-spec template HTML comments、scaffolding `_conventions.md` 的 CQRS-split convention、references flow 的 `Phase 3 draft sections` checklist item
+- `e287791` Tutorial walkthrough + outputs sync（9 檔）— 逐句判斷 (A)/(B)/(C) 後分別處理。Tutorial outputs 視為 live teaching artifacts（per user 決策 Q1 = A）
+
+**保留不動的部分**：
+
+- `/dflow:new-phase` 指令名稱、`phase-spec-{date}-{slug}.md` 檔名模式、`templates/phase-spec.md` template 檔名 — 都是 user-facing API
+- `_index.md` 內 `Phase Specs` table 標題、所有 `Phase 1 phase-spec` / `Phase 2+ specs` 衍生用法 — 都屬 (A)
+- `CHANGELOG.md` 內既有條目、`archive/proposals/` — 凍結歷史紀錄
+- `superseded-drafts/` 內檔案 — 已標 superseded，不維護
+- `PRACTICE_PLAN_tw.md` 內 `Phase 1-7`（tutorial 練習章節，第 4 種 Phase 用法）— 加入 disambiguation note；完整重命名（候選名 Module / Practice Session）留作 follow-up
+
+**Codex cross-model review**：
+
+提案經 Codex 獨立評審，accept with revisions。5 處具體修正全部納入（衍生用法澄清、標準書寫格式、HTML comment 格式、影響範圍補列 9 檔、atomic commit / release notes / 外部相容性配套）。User 拍板 2 個 Open Questions：tutorial outputs 視為 live artifact（Q1=A）、(B) 採 Step Gate（Q2=A）。
+
+**邊界**：
+
+- 無 CLI / 檔名 / 對外 API 表面變更 — 純文件術語清理
+- dev-only；dist projection 留待下次 user-approved checkpoint
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release
+- 解鎖 PROPOSAL-024 後續 README polish 第二輪（README workflow 模型段落可用新詞彙改寫）
+
+**驗證**：
+
+- `scripts/check-repo-consistency.sh` pass（source ↔ packaged mirror diff clean）
+- 全 repo grep 無 `Phase Gate` / `phase gate` 殘留（CHANGELOG 與 PROPOSAL-025 文檔內提及為刻意）
+
+---
+
+## 2026-05-15 — Public README zh-TW strategy + migrating-to-v1 reframing (PROPOSAL-024)
+
+**變更**：
+
+- `README.md` 改為**繁體中文版**（GitHub / npm 預設顯示），新增 `README.en.md` 作為英文版備案
+- 兩份 README 頂部都有 language switcher（粗體 = 當前語言、連結 = 另一語言）
+- 兩份 README 都**移除**舊有的 migration-guide 廣告段（原 `README.md:254-256` 那段「If you maintain a project that adopted an early Dflow form...」）。Dflow 經驗上只有 OBTS 這個唯一 pre-V1 adopter 且已完成遷移；首頁廣告 migration guide 對新 evaluator 是干擾文字
+- `scripts/export-dist.sh` `include_paths` 加 `README.en.md`，確保未來 dist projection 把雙語版都帶過去
+- `docs/migrating-to-dflow-v1.md` 頂部加「Audience reality (2026-05-15)」blockquote，校正讀者期待 — 這篇 doc 仍存在是因為 `dflow doctor` / `dflow init` warning 接過來時需要它，**不是**廣告型 evangelism 文件
+- `MAINTAINERS.md` 新增「README Language Strategy」段，記錄雙語政策
+
+**邊界**：
+
+- dev-only；dist projection 留待 user-approved checkpoint，與 PROPOSAL-022 / 023 一起 bundle
+- 純 public-facing docs；無 lib/、bin/、test/、scaffolding 變動。`docs/migrating-to-dflow-v1.md` 的 runtime references（doctor、init.js warning、smoke test、scaffolding mirrors）全部保留
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release
+
+**驗證**：
+
+- `git diff --check` clean
+- `scripts/check-repo-consistency.sh` pass
+- `npm pack --dry-run`：file list 含 `README.en.md`
+- `test/smoke.mjs` 不受影響（migrating-to-v1 path reference 未動）
+
+---
+
+## 2026-05-15 — Line-ending policy, dev-side (PROPOSAL-023)
+
+**變更**：
+
+- 新增 `.gitattributes` line-ending 政策（commit `f7b3cbe`）：
+  - `* text=auto eol=lf` 規定全 repo 文字檔 LF（含 repo storage 與所有 OS 的 working tree）
+  - `*.bat` / `*.cmd` 例外 CRLF（Windows `cmd.exe` 必需）
+  - `*.png` / `*.jpg` / `*.pdf` 標記 binary（defensive future-proofing；repo 內目前無此類檔案）
+- `scripts/export-dist.sh` `include_paths` 加 `.gitattributes`（commit `c887b05`，Phase 1.5；resolves Director cross-check Finding 12），確保未來 dist projection 把政策帶過去
+- 一次性 brute-force WT refresh（`git ls-files -z | xargs -0 rm -f && git checkout -- .`）讓 dev 內 336 個 CRLF working-tree 檔對齊 LF。**無 commit 產生** — repo storage 早已是 LF（`autocrlf=true` 歷史），`git add --renormalize .` 是 no-op；只有 WT 不一致
+- `MAINTAINERS.md` 加「Line Endings」段，說明政策、`.bat`/`.cmd` 例外、Windows 個人 `core.autocrlf=input` 建議、`.git-blame-ignore-revs` 未使用的理由與未來啟用步驟
+- `planning/line-ending-finding.md` 加 closeout 註
+
+**邊界**：
+
+- dev-only；Phase 2（dist projection）留待 user-approved checkpoint，與 PROPOSAL-022 implementation + bug template 等 pending 變更一起 bundle
+- 純 line-ending policy + WT refresh；無 semantic / API / runtime 變化
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release
+
+**驗證**：
+
+- `git ls-files --eol | awk '{print $1, $2}' | sort | uniq -c` → 347 `i/lf w/lf` + 3 `i/none w/none`（無 `i/lf w/crlf` 殘留）
+- `scripts/check-repo-consistency.sh` pass
+- `git diff --check` clean
+- `git status` clean after WT refresh
+
+---
+
+## 2026-05-15 — Archive legacy tutorial drafts
+
+**變更**：
+
+- 將 14 個 legacy 非 zh-TW tutorial 草稿從 `tutorial/0X-{greenfield,brownfield}/`
+  搬到 `archive/tutorial-drafts/0X-{greenfield,brownfield}/`，使用 `git mv` 保留
+  rename history（檔案內容不變）：
+  - greenfield 7 檔（00-setup、01-init-project、02-new-feature、03-new-phase、
+    04-modify-existing、05-bug-fix、06-finish-feature）
+  - brownfield 7 檔（00-setup、01-init-project、02-modify-existing、
+    03-baseline-capture、04-new-feature、05-bug-fix、06-finish-feature）
+- 更新 `archive/README.md`，加入 `archive/tutorial-drafts/` 子目錄說明。
+
+**動機**：
+
+- zh-TW canonical walkthrough（`tutorial/0X-*/walkthrough-*.zh-TW.md`）已是
+  reader-facing 入口；legacy 草稿在公開閱讀流程中已無入口（PROPOSAL-022 Phase 2
+  已將 `docs/*.md` 連結重新指向 zh-TW canonical）。
+- `scripts/export-dist.sh` 將 `tutorial/` 整個投影到 dist；legacy 檔留在
+  `tutorial/` 內會在 dist projection 時被帶上 dist。搬到已被排除的 `archive/`
+  目錄即可保留 dev 歷史、不污染 dist。
+
+**邊界**：
+
+- 純檔案搬移；無內容變更。
+- `archive/` 已在 `scripts/export-dist.sh` `excluded_stale_paths` 內。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- `scripts/check-repo-consistency.sh`
+- `ls tutorial/` 與 `ls archive/tutorial-drafts/` 確認 14 檔搬移完整。
+
+---
+
+## 2026-05-14 — CLI install recommendation docs update (PROPOSAL-022)
+
+**變更**：
+
+- 更新 `README.md`：將 `npm install -g dflow-sdd-ddd` + `dflow init` 提升為
+  主要安裝路徑；`npx dflow-sdd-ddd` 改為明確標示的「Alternative: try without
+  installing」替代路徑，並列出 init / doctor / configure-agents 的 npx 形式。
+- 更新 `tutorial/README.md`、`tutorial/dflow-command-surface.zh-TW.md`、
+  `tutorial/01-greenfield/walkthrough-0{0,1,2}-*.zh-TW.md`、
+  `tutorial/02-brownfield/walkthrough-0{0,1,6}-*.zh-TW.md`：
+  CLI 命令參照從 `npx dflow-sdd-ddd init` 更新為 `dflow init`；
+  walkthrough-01 保留一段 npx 替代路徑說明。
+- 更新 `templates/` 與 `sdd-ddd-*-skill/scaffolding/` 四個 mirror pair
+  (AI-AGENT-GUIDE.md、CLAUDE-md-snippet.md)：install 參照改為 neutral 措辭
+  (`dflow init`, or `npx dflow-sdd-ddd init` when using the no-install path)。
+- 更新 `templates/{greenfield,brownfield}/templates/CLAUDE.md` 與
+  `sdd-ddd-{green,brown}field-skill/templates/CLAUDE.md` 兩對 mirror pair：
+  目錄樹 comment 從「由 npx dflow-sdd-ddd init 寫入」改為「由 dflow init 寫入」。
+- 更新 `docs/evaluating-dflow.md`、`docs/using-with-claude-code.md`、
+  `docs/using-with-codex.md`、`docs/using-with-gemini-cli.md`、
+  `docs/using-with-github-copilot.md`、`docs/migrating-to-dflow-v1.md`：
+  install ordering 對齊新主路徑；重新連結四個 docs 的舊 tutorial 連結至
+  zh-TW canonical walkthrough 檔案。
+- 更新 `MAINTAINERS.md`：新增 contributor CLI 使用 `npm link` 的一行說明。
+- `docs/npm-publish-checklist.md`：確認未動，versioned smoke checks 保持不變。
+- `npx dflow-sdd-ddd` 形式繼續有效；本次只是不再作為主要文件路徑推薦。
+
+**邊界**：
+
+- doc-only；無 `lib/` / `bin/` / `package.json` / skill source 行為變更。
+- dev-only checkpoint；dist projection 待後續 user-approved checkpoint。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- `scripts/check-repo-consistency.sh`
+- 手動 grep 分類：`rg -n "npx dflow-sdd-ddd|dflow doctor|dflow configure-agents"`
+
+---
+
+## 2026-05-14 — Maintainer operational guardrails
+
+**變更**：
+
+- 更新 `MAINTAINERS.md`，將近期 handoff 中反覆出現的跨任務運作規則制度化：
+  commit / push 判斷、依 changed surface 選擇驗證、dist projection cadence、
+  tutorial fixture 邊界與 release boundary。
+- 明確規定 docs / tutorial / planning-only 變更不需跑 `npm test`；
+  `npm test` 保留給 runtime、CLI、templates、tests、package metadata 或
+  release automation 等會影響 package behavior 的變更。
+- 明確規定 tutorial draft 不逐次投影 dist；dist projection 需在
+  user-approved checkpoint 或 full tutorial rewrite ready 時進行。
+- 明確規定 `tutorial/**/outputs/` fixture 不因 wording cleanup 或翻譯工作修改；
+  若要 rename，必須作為獨立 path-migration checkpoint 處理。
+
+**邊界**：
+
+- dev-only maintainer guidance；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+
+---
+
+## 2026-05-14 — Tutorial wording and link-label cleanup
+
+**變更**：
+
+- 更新 `tutorial/README.md` 開頭說明，移除「API reference」這類不直覺的對比，
+  改成直接說明 tutorial 讓讀者透過 Greenfield / Brownfield 劇情理解 Dflow。
+- 將 tutorial walkthrough 內指向其他教學篇章與導讀頁的連結文字，從檔名改為
+  reader-facing 篇名，並在段落連結中使用 `〈...〉` 呈現篇名。
+- 將 `how-to-read-dflow-specs.zh-TW.md` 的標題與說明從 `outputs snapshots`
+  收斂為「Dflow 規格與完整文件範例」，降低讀者必須理解 repo 內
+  `outputs/` 目錄命名的負擔。
+- 更新 walkthrough 開頭的閱讀提示，將 `outputs/` 描述為完整文件範例目前的存放位置。
+- 更新主 `README.md` 的 `Files Created by Init` 目錄樹，加入 tree connector 符號。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- 本次不 rename `tutorial/**/outputs/`；該目錄命名需要另行決策。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 grep tutorial walkthrough 中舊式 walkthrough filename labels
+
+---
+
+## 2026-05-13 — Tutorial README reader-facing labels
+
+**變更**：
+
+- 更新 `tutorial/README.md`，將「先讀」與 walkthrough 入口的連結文字
+  從檔名改成 reader-facing 文件題名。
+- 保留 Greenfield / Brownfield walkthrough 表格形式，並補上「建議順讀、
+  但每篇可單篇閱讀」的導覽說明。
+- 將 README 中「正在改寫中的 immersive walkthrough 系列」改為
+  `zh-TW immersive walkthrough 系列`，避免過期語氣。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 grep `tutorial/README.md` 中舊式 walkthrough filename labels
+
+---
+
+## 2026-05-13 — Walkthrough reading-flow cleanup
+
+**變更**：
+
+- 清理 Greenfield / Brownfield 02-06 user / evaluator-facing walkthrough 的
+  reading flow wording，範圍包含：
+  `tutorial/01-greenfield/walkthrough-02-new-feature.zh-TW.md` through
+  `tutorial/01-greenfield/walkthrough-06-finish-feature.zh-TW.md`，
+  以及 `tutorial/02-brownfield/walkthrough-02-modify-existing.zh-TW.md`
+  through `tutorial/02-brownfield/walkthrough-06-finish-feature.zh-TW.md`。
+- 將重複的 `final snapshot` 說明收斂成「完整文件範例」與少量情境補充，
+  避免每個文件片段都重複解釋 snapshot / excerpt 分工。
+- 將「README feature claims」區塊改成 reader-facing「本篇展示的 Dflow 能力」，
+  並把 `Three-layer documentation model` 改成較自然的「三層文件分工」。
+- 保留每篇開頭的自足閱讀提示，讓讀者不必先跳到
+  `how-to-read-dflow-specs.zh-TW.md` 才能讀懂單篇 walkthrough。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 grep 02-06 walkthroughs 中的舊式 `final snapshot` /
+  `README feature claims` / `Three-layer` wording
+
+---
+
+## 2026-05-13 — Reader-facing walkthrough wording cleanup
+
+**變更**：
+
+- 清理 Greenfield / Brownfield `walkthrough-*.zh-TW.md` 的開頭與閱讀提示，
+  移除 `00-setup.md`、`02-new-feature.md` 等素材檔引用，避免 user /
+  evaluator-facing 文件暴露 maintainer source-material 語境。
+- 將 walkthrough 的 bracketed notes 改為 reader-facing「閱讀提示」，說明
+  `outputs/` 連結代表完整 snapshot、正文 excerpt 代表當下重點，並連到
+  `how-to-read-dflow-specs.zh-TW.md`。
+- 更新 `tutorial/dflow-command-surface.zh-TW.md`，把舊 step trace links
+  改指向公開 walkthrough 入口。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check walkthrough source-material references
+
+---
+
+## 2026-05-13 — Dflow specs reading guide
+
+**變更**：
+
+- 新增 `tutorial/how-to-read-dflow-specs.zh-TW.md`，作為 cross-cutting
+  reading guide，說明 walkthrough excerpt 與 `outputs/` final snapshot
+  的差別、phase / lightweight / BUG specs、feature `_index.md`、BC layer
+  cumulative docs、Brownfield baseline capture 與 `migration/tech-debt.md`
+  的讀法。
+- 更新 `tutorial/README.md` 的「先讀」入口，加入 spec / snapshot 讀法導覽。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把
+  `how-to-read-dflow-specs.zh-TW.md` 從候選轉為 accepted cross-cutting
+  tutorial。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；本篇只說明如何閱讀 snapshots。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-13 — Setup and init immersive walkthroughs
+
+**變更**：
+
+- 新增 Greenfield walkthrough 00 / 01：
+  `tutorial/01-greenfield/walkthrough-00-setup.zh-TW.md` 與
+  `tutorial/01-greenfield/walkthrough-01-init-project.zh-TW.md`，補齊
+  Alice / ExpenseTracker 的專案起點、Clean Architecture repo state、
+  `npx dflow-sdd-ddd init`、file-list preview、Greenfield baseline
+  outputs、AI tool shims，以及 Day-0 不預建 `behavior.md` / ADR 的理由。
+- 新增 Brownfield walkthrough 00 / 01：
+  `tutorial/02-brownfield/walkthrough-00-setup.zh-TW.md` 與
+  `tutorial/02-brownfield/walkthrough-01-init-project.zh-TW.md`，補齊
+  Bob / OrderManager 的 legacy context、WebForms / EF 6 / Stored Procedure
+  風險、Brownfield init baseline、`migration/tech-debt.md`、Git Flow 選擇，
+  以及 init 不建立 `src/Domain/` 或預設 Order BC 的邊界。
+- 更新 `tutorial/README.md`，讓 Greenfield 與 Brownfield walkthrough path
+  都從 00-06 完整列出。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 00 / 01 四篇 zh-TW
+  walkthrough 加入 accepted pattern。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-12 — Greenfield finish-feature immersive walkthrough
+
+**變更**：
+
+- 新增 `tutorial/01-greenfield/walkthrough-06-finish-feature.zh-TW.md`，
+  以中文 canonical walkthrough 展示 Greenfield `/dflow:finish-feature`
+  如何收尾 `SPEC-20260428-001-employee-submit-expense`：closeout
+  validation、deferred item disposition、status flip、BR-001~007 sync
+  到 Expense BC `rules.md`、completed archive、Integration Summary、
+  tech-debt preserve，以及 completed feature frozen history 邊界。
+- 更新 `tutorial/README.md` 的 Greenfield walkthrough 表格，連到新的
+  finish-feature walkthrough，並將目前狀態更新為 Greenfield 02-06
+  與 Brownfield 02-06 zh-TW immersive walkthroughs 已列入索引。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 Greenfield
+  `walkthrough-06-finish-feature.zh-TW.md` 加入 accepted pattern。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-12 — Greenfield bug-fix immersive walkthrough
+
+**變更**：
+
+- 新增 `tutorial/01-greenfield/walkthrough-05-bug-fix.zh-TW.md`，
+  以中文 canonical walkthrough 展示 Greenfield `/dflow:bug-fix`
+  如何處理 reject reason emoji surrogate truncation：T2 Light 判定、
+  BUG-001 命名、active host feature linkage、Presentation primary /
+  Domain secondary layer split、BR-007 wording unchanged、Current BR
+  Snapshot intentionally unchanged note，以及 Unicode character counting
+  tech debt 分流。
+- 更新 `tutorial/README.md` 的 Greenfield walkthrough 表格，連到新的
+  bug-fix walkthrough，並將目前狀態更新為只剩 Greenfield 06 尚未
+  改寫。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 Greenfield
+  `walkthrough-05-bug-fix.zh-TW.md` 加入 accepted pattern。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-12 — Greenfield modify-existing immersive walkthrough
+
+**變更**：
+
+- 新增 `tutorial/01-greenfield/walkthrough-04-modify-existing.zh-TW.md`，
+  以中文 canonical walkthrough 展示 Greenfield `/dflow:modify-existing`
+  如何把 BR-007 reject reason 從單一 10 字元調整為 bilingual length
+  rule：T2 Light 判定、active host feature linkage、completed-feature
+  reopen skip、lightweight spec Delta、Current BR Snapshot regenerate、
+  `ApprovalReason` Value Object impact，以及 `models.md` / `context.md`
+  故意不擴張同步的邊界。
+- 更新 `tutorial/README.md` 的 Greenfield reading path 與 immersive
+  walkthrough 區塊，連到新的 modify-existing walkthrough。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 Greenfield
+  `walkthrough-04-modify-existing.zh-TW.md` 加入 accepted pattern。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-11 — Greenfield new-phase immersive walkthrough
+
+**變更**：
+
+- 新增 `tutorial/01-greenfield/walkthrough-03-new-phase.zh-TW.md`，
+  以中文 canonical walkthrough 展示 Greenfield `/dflow:new-phase`
+  如何在既有 `SPEC-20260428-001-employee-submit-expense` 內新增
+  supervisor approval phase：active feature context loading、phase scope
+  confirmation、ApprovalDecision Aggregate 邊界、ADDED / MODIFIED Delta、
+  Current BR Snapshot regenerate，以及 living domain docs sync。
+- 更新 `tutorial/README.md` 的 Greenfield reading path 與 immersive
+  walkthrough 區塊，連到新的 new-phase walkthrough。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 Greenfield
+  `walkthrough-03-new-phase.zh-TW.md` 加入 accepted pattern。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-11 — Brownfield finish-feature immersive walkthrough
+
+**變更**：
+
+- 新增 `tutorial/02-brownfield/walkthrough-06-finish-feature.zh-TW.md`，
+  以中文 canonical walkthrough 展示 Brownfield `/dflow:finish-feature`
+  如何收尾 `SPEC-20260430-001-order-discount-calculation`：closeout
+  validation、BR-001~004 sync、BR-005~008 preserve、completed archive、
+  Integration Summary、tech-debt sweep，以及 completed feature frozen
+  history 邊界。
+- 更新 `tutorial/README.md` 的 Brownfield reading path 與 immersive
+  walkthrough 區塊，連到新的 finish-feature walkthrough。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 Brownfield
+  `walkthrough-06-finish-feature.zh-TW.md` 加入 accepted pattern。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-11 — Brownfield bug-fix immersive walkthrough
+
+**變更**：
+
+- 新增 `tutorial/02-brownfield/walkthrough-05-bug-fix.zh-TW.md`，
+  以中文 canonical walkthrough 展示 Brownfield `/dflow:bug-fix`
+  如何處理跨頁 rounding inconsistency：T2 Light 判定、BUG-001 命名、
+  host feature 歸屬 SPEC-001、`Money.ToDisplay()` implementation contract
+  收斂、BR Snapshot intentionally unchanged note，以及 `tech-debt.md`
+  resolved disposition。
+- 更新 `tutorial/README.md` 的 Brownfield reading path 與 immersive
+  walkthrough 區塊，連到新的 bug-fix walkthrough。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 Brownfield
+  `walkthrough-05-bug-fix.zh-TW.md` 加入 accepted pattern。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-11 — Brownfield new-feature immersive walkthrough
+
+**變更**：
+
+- 新增 `tutorial/02-brownfield/walkthrough-04-new-feature.zh-TW.md`，
+  以中文 canonical walkthrough 展示 Brownfield 已有 Order BC 後如何用
+  `/dflow:new-feature` 新增 VIP discount policy，並說明 `isVip * 0.93`
+  dead code disposition、Customer reference data 邊界、BR-005~008 與
+  既有 BR-001~004 的互動。
+- 更新 `tutorial/README.md` 的 Brownfield reading path 與 immersive
+  walkthrough 區塊，連到新的 new-feature walkthrough。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 Brownfield
+  `walkthrough-04-new-feature.zh-TW.md` 加入 accepted pattern。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-10 — Brownfield baseline-capture immersive walkthrough
+
+**變更**：
+
+- 新增 `tutorial/02-brownfield/walkthrough-03-baseline-capture.zh-TW.md`，
+  以中文 canonical walkthrough 展示 baseline-only path：不硬塞 T1 / T2 /
+  T3、不改 code、不建 spec、不改 rules，而是把跨頁面 `OrderList` /
+  `OrderDetail` 現況分成 confirmed / buggy / unknown 並分流到
+  `behavior.md` 與 `tech-debt.md`。
+- 更新 `tutorial/README.md` 的 Brownfield reading path，連到新的
+  baseline-capture walkthrough。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 Brownfield
+  `walkthrough-03-baseline-capture.zh-TW.md` 加入 accepted pattern。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-10 — Brownfield modify-existing immersive walkthrough
+
+**變更**：
+
+- 新增 `tutorial/02-brownfield/walkthrough-02-modify-existing.zh-TW.md`，
+  以中文 canonical walkthrough 展示 Brownfield `/dflow:modify-existing`
+  如何從 WebForms 客訴進入 T1 判定、無 host feature 時升級為
+  `/dflow:new-feature`、捕捉 baseline contrast、建立第一個 Order BC，
+  並把折扣計算抽成可測試 Domain logic。
+- 更新 `tutorial/README.md` 的 Brownfield reading path 與 immersive
+  walkthrough 區塊，連到新 walkthrough。
+- 更新 `planning/immersive-tutorial-suite-plan.md`，把 Brownfield
+  `walkthrough-02-modify-existing.zh-TW.md` 加入 accepted pattern。
+- 更新 `MAINTAINERS.md` 與 active tutorial plan，記錄 tutorial-only
+  變更不需要 `npm test`，且 active tutorial rewrite 期間 dev commits
+  不必每次投影 dist；等 user-approved tutorial checkpoint 或 full rewrite
+  ready 時再 export。
+
+**邊界**：
+
+- dev-only checkpoint；本次不投影 dist。
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- 手動 spot-check 新增 tutorial link targets
+
+---
+
+## 2026-05-10 — Bilingual immersive tutorial suite
+
+**變更**：
+
+- 新增 `tutorial/dflow-command-surface.zh-TW.md`，整理現行 Dflow 命令表面：
+  `npx dflow-sdd-ddd init` / `dflow doctor` / `dflow configure-agents`
+  與 `/dflow:*` AI workflow commands 的分工，並明確列出 workflow /
+  phase / closeout / control / verify / review / feedback commands。
+- 新增 `tutorial/01-greenfield/walkthrough-02-new-feature.zh-TW.md`，
+  作為第一份中文 canonical immersive walkthrough，展示
+  `/dflow:new-feature` 如何從 AI 對話、DDD discovery、phase gate、
+  generated document excerpts 走到 implementation task list。
+- 更新 `tutorial/README.md`，移除不存在的 `outputs-tour.md` forward-links，
+  改連到已存在的中文 command surface 與 Greenfield walkthrough；Brownfield
+  walkthrough 標為後續 incremental work。
+- 新增 `planning/immersive-tutorial-suite-plan.md` 作為目前 tutorial rewrite
+  的 active source of truth，記錄 zh-TW first、English adaptation later、
+  「讀者」用詞、cross-cutting tutorials、Worker 分工策略。
+- 將 `planning/full-tutorial-rewrite-plan.md` 收斂為 superseded stub，避免
+  舊 English-first / `outputs-tour.md` 設計干擾後續 session；歷史細節由 git
+  history 保留。
+- 更新 `planning/public-onboarding-tasklist.md` 的 tutorial rewrite 狀態，
+  指向新的 immersive tutorial suite plan。
+
+**邊界**：
+
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更。
+- `outputs/` tree 完全未動；walkthrough 只以連結與內嵌 excerpt 引用。
+- 不 bump `package.json`、不 `npm publish`、不 `git tag`、不建 GitHub Release。
+
+**驗證**：
+
+- `git diff --check`
+- `scripts/check-repo-consistency.sh`
+- `scripts/export-dist.sh --dry-run`
+- dist `npm test`
+- dist `npm pack --dry-run`
+- dist `git diff --check`
+
+---
+
+## 2026-05-09 — Tutorial English-first promotion (full tutorial rewrite Batch 1)
+
+**變更**：
+
+- `tutorial/README.md` 推升為 English-first canonical entry：
+  - 開頭兩段英文 orientation；既有 zh-TW 表格與 `使用方式` 段落移至
+    `## 中文導讀` companion section，保留現有內容
+  - 新增 `## Two Scenarios` 概述 Greenfield (Alice / ExpenseTracker)
+    與 Brownfield (Bob / OrderManager) 適配對象
+  - 每條 scenario 新增 `### Reading Order` 段落，每個 step file 一段
+    1-2 句英文 plot summary
+  - 新增 `### Curated Outputs Tour` 區塊，前向連到尚未存在的
+    `01-greenfield/outputs-tour.md` 與 `02-brownfield/outputs-tour.md`
+    （由本 rewrite 計畫的 Batch 2 / Batch 3 建立）
+  - mermaid workflow chart 保留為 language-neutral，置於英文段內
+- 對 `docs/evaluating-dflow.md`、`docs/using-with-{claude-code,codex}.md`
+  與 root `README.md` 採 cross-link，不重述 evaluator playbook /
+  per-tool surface / Get Started 內容（per
+  `planning/full-tutorial-rewrite-plan.md` Non-duplication guardrails）
+- 14 個 step file 內容未動（English summary header 屬本 rewrite 計畫
+  的 Batch 4 / Batch 5 範疇）
+
+**邊界**：
+
+- doc-only；無 `lib/` / `templates/` / `bin/` / skill source 變更
+- 依 `planning/full-tutorial-rewrite-plan.md` §3.4，本次走 independent
+  public docs update：不 bump `package.json`、不 `npm publish`、不
+  `git tag`、不建 GitHub Release
+- `outputs/` tree 完全未動（無 file move / delete / rename / 內容修改）
+
+**驗證**：
+
+- `npm test`
+- `scripts/check-repo-consistency.sh`
+- `scripts/export-dist.sh --check`
+- dist `npm pack --dry-run`
+- `git diff --check`
+- 手動 link spot-check：`../docs/evaluating-dflow.md`、
+  `../docs/using-with-claude-code.md`、`../docs/using-with-codex.md`、
+  step file paths、`outputs/` tree 連結均可達；`outputs-tour.md` 兩條
+  forward-link 為設計性故意，將於 Batch 2 / Batch 3 落地
+
+---
+
 ## 0.2.0 — 2026-05-09 — Public migration tooling, governance baseline, and evaluator onboarding
 
 **Proposals**：PROPOSAL-016（governance baseline）、PROPOSAL-017（AI-assisted feedback flow）、PROPOSAL-018（repository consistency）、PROPOSAL-021（verification-only CI）。其餘為 backlog 推進的公開 docs 與 migration tooling 累積項。