dflow-sdd-ddd 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -6,7 +6,67 @@
 
 ---
 
-## 0.13.0 — 2026-07-10 — dflow render（specs 人讀化）+ init 預設安裝 skill（day-one 自動觸發）
+## 0.14.0 — 2026-07-12 — 升級健檢與 guide canonical 區可升級化
+
+**Proposals**：PROPOSAL-058（升級期 user-owned 層 drift 偵測 + guide marker-guard）、PROPOSAL-076（configure-agents context inference 死源修正）、PROPOSAL-075（workflow 內容源單一化，內部）
+
+本版主線：讓「升級既有專案」從黑箱變成可診斷、可局部自動化——
+
+1. **`dflow doctor` 成為升級健檢**（058）：偵測專案各層相對當前 CLI 版本的
+   drift，只報不改。
+2. **guide 的 Dflow 段落隨升級刷新**（058）：`AI-AGENT-GUIDE.md` canonical 區包
+   marker、`configure-agents` 原地刷新；你的 `## Project Context` 與 marker 外
+   內容一律保留。
+3. **context inference 讀真正的資料源**（076）：修正 re-projection 時 tech
+   stack / migration context 恆退 `unknown` / `none` 的死源缺口。
+
+### 新功能（PROPOSAL-058）
+
+- **guide-canonical marker-guard**：兩軌 `AI-AGENT-GUIDE.md` 模板的 canonical
+  段包 `<!-- dflow-generated: guide-canonical START/END -->`；`configure-agents`
+  對 marker 完好的 guide **原地刷新** canonical 區（canonical 區
+  substitution-free、刷新 byte-idempotent；保留檔案 EOL 與 marker 外全部內容）。
+- **Consent-gated adoption offers**（互動式、預設 No；非互動一律 skip+warn、
+  不佔 stdin slot）：
+  - 無 marker 但可辨識的舊 guide → 詢問是否包 marker 並刷新（`## Project
+    Context` 保留、其餘替換）；
+  - 引用 guide 但非 Dflow 管理的 root agent 檔（case 2d）→ 詢問是否附掛
+    marker 管理區塊（此後隨升級刷新；提示手動清舊 Dflow 措辭）。
+- **`> Dflow Version:` 進位為 last-reconciled 語意**：`configure-agents` 成功
+  套用後把 `_conventions.md` 的版本行推進到當前 CLI 版；任何 guarded skip 即
+  放棄推進（不高估 reconciliation）；行缺失不自動補（doctor 報告）。
+- **doctor 升級 drift 偵測集**（全部 warn/info、exit 0、嚴格唯讀）：版本行
+  stale／不可解析、政策段存在與機器格式、guide marker 態 + canonical byte 比
+  對、workflow bundle 與 `_conventions` 的 `AI-AGENT-GUIDE.md §` dangling 參
+  照、Git-principles 檔缺失／漂移、active feature `_index.md` 舊模板形狀（附
+  AI 協助遷移指引；completed/ 不掃）、root agent shim 態、bundle manifest 版
+  本落後。
+- docs：README（兩語）升級 caveat 段改寫——新升級行為 + doctor 健檢 +
+  「fresh init 對比」保留為徹底驗證 SOP；六個 using-with 檔與 doctor help 同步。
+
+### 修正（PROPOSAL-076）
+
+- **configure-agents 的 context inference 死源修正**：
+  `techStackSummary` / `migrationContext` 推斷原本讀 `_overview.md` 的
+  `| Tech stack |` / `| Migration / legacy context |` 表列——但任何版本的
+  packaged `_overview` 模板都從未有這兩列，推斷恆 fallback `unknown` / `none`。
+  現改讀真正的機器可讀落點：guide `AI-AGENT-GUIDE.md` 的 `## Project Context`
+  表（init 自始把 Q2/Q3 答案寫在這裡；只解析 Project Context 段內、段外同名列
+  不遮蔽）。`dflow doctor` 新增 info 級檢查：可辨識／marker 管理的 guide 若缺
+  `## Project Context` 段、缺這兩列或列不可解析，會提示 inference 後果；fresh
+  init 專案不受影響（列本來就在）。同步校正兩軌 `init-project-flow.md` 把 Q3
+  落點誤述為 `_overview.md` 的殘句。
+- **解析與寫入加固**（076 實作 review 鏈產物，惠及既有 doctor 掃描）：fence
+  掃描補齊 CommonMark 閉合規則（fence 長度、info-string 行不算閉合、≤3 空白縮
+  排）；guide 可辨識性判準 fence-aware 且與 Project Context 定位一致（接受
+  adoption offer 不可能再因 fenced 假標題中止）；BOM 容忍；init 把 Q2/Q3 答案
+  寫入表格 cell 時跳脫 `|`，值經 inference 完整 round-trip。
+
+### 內部（PROPOSAL-075）
+
+- workflow 內容源單一化：退役兩個歷史 skill-source 鏡像目錄，`templates/` 成
+  唯一內容源（npm 包內容不變；README／docs 對應措辭同步、一致性 guard 防止
+  retired 路徑回流）。
 
 **Proposals**：PROPOSAL-072（表格 `<br>` 分行慣例）、PROPOSAL-073（`dflow render` 子指令）、PROPOSAL-074（init 預設安裝 project-level skill）
 
@@ -83,6 +143,10 @@
   mixed-state sentinel 回歸：flagless 不重生成既有 skill）、三家路徑全驗。
   `npm test` + `scripts/check-repo-consistency.sh` + `npm pack --dry-run` 全綠
   （dev 與 dist 兩側）。
+- **Post-publish smoke（對公開 registry 套件，2026-07-10）**：
+  `npx dflow-sdd-ddd@0.13.0` 之 `--version` / `--help` 正確；init（非互動
+  舊答案序列）exit 0、預設產出三家 skill 檔；configure-agents exit 0；
+  doctor 全過；render 30 md → HTML 成功。registry `latest = 0.13.0`。
 
 ### 升級提醒
 

package/CONTRIBUTING.md

@@ -13,8 +13,8 @@ Please read:
   document structure.
 - `TEMPLATE-LANGUAGE-GLOSSARY.md` before changing template headings or field
   labels.
-- The relevant Greenfield or Brownfield skill source when changing workflow
-  behavior.
+- The relevant Greenfield or Brownfield workflow content under `templates/`
+  when changing workflow behavior.
 
 The public source is kept intentionally smaller than the development workspace.
 Internal planning notes, proposal handoffs, and review artifacts are maintainer
@@ -71,13 +71,10 @@ GitHub Actions runs the same verification commands on every pull request to
 `main` and on every push to `main`. The CI is verification-only — it does not
 publish releases, change versions, or create tags.
 
-When changing templates or scaffolding, keep both source surfaces aligned:
-
-- skill source under `sdd-ddd-greenfield-skill/` or
-  `sdd-ddd-brownfield-skill/`
-- packaged templates under `templates/greenfield/` or `templates/brownfield/`
-
-If you are unsure which surface to edit, describe that uncertainty in the PR.
+Templates and scaffolding live under `templates/greenfield/`,
+`templates/brownfield/`, and `templates/common/` — the single content source
+read by the CLI. Edit them directly; there is no separate mirror to keep in
+sync.
 
 ## Greenfield and Brownfield Synchronization
 

package/README.en.md

@@ -283,8 +283,11 @@ files whose only job is to redirect the tool to the canonical guide):
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
 If one of those files already exists, Dflow preserves custom content. A
-Dflow-generated shim is refreshed in place; another file that already points to
-`dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped. If the file does not yet
+Dflow-generated shim is refreshed in place. A file you wrote yourself that
+already points to `dflow/specs/shared/AI-AGENT-GUIDE.md` is never rewritten:
+an interactive run asks whether to append the marked managed block at the end
+of the file (default No), and a non-interactive run skips it with a warning.
+If the file does not yet
 point to the guide, Dflow shows the change in the confirmation preview and
 appends a marked `<!-- dflow-generated: agent-shim START/END -->` block at the
 end of the file; re-running refreshes that same block in place without
@@ -324,27 +327,35 @@ across all tools in a project**, rather than ignoring adapters for one tool and
 tracking them for another.
 
 After upgrading Dflow, re-running `dflow configure-agents --command-adapters`
-re-projects adapters from the **new command registry**, but it does **not**
-overwrite an existing `dflow/specs/shared/AI-AGENT-GUIDE.md` (an existing
-canonical guide is kept). "Re-projecting adapters" and "migrating the canonical
-guide" are two different things; re-project with the **same dflow CLI version**
-to avoid a registry / guide version mismatch. Per-tool `.gitignore` snippets,
+re-projects adapters from the **new command registry**, and it also refreshes
+the **marker-guarded canonical region** of
+`dflow/specs/shared/AI-AGENT-GUIDE.md` in place (everything outside the markers
+— including `## Project Context` — is kept), so the two no longer skew apart.
+Re-project with the **same dflow CLI version**. Per-tool `.gitignore` snippets,
 glob side effects, the `git rm --cached` switch-over step, and upgrade details
 are covered in the per-tool guides.
 
-**Caveat when upgrading an existing project**: `configure-agents` only
-re-projects the layers Dflow itself owns (the workflow bundle, command / skill
-adapters, and the marked block inside existing agent files). It does **not**
-refresh the canonical guide (`AI-AGENT-GUIDE.md`) or the other user-owned layers
-(such as `_conventions.md` or the prose outside a shim's markers) — those become
-project-owned right after init and are deliberately left untouched. The trade-off:
-when a new release adds content into the canonical guide, an existing project does
-not pick it up automatically and can silently drift from that release's canonical
-shape. After upgrading an existing project, reconcile manually and use a fresh
-comparison baseline — run a **brand-new `dflow init` with the same edition and the
-same answers** elsewhere, then diff it file-by-file against your project: every
-difference should classify as either "your user content" or "known
-outside-the-markers", otherwise it is a missed update.
+**Caveat when upgrading an existing project**: `configure-agents` re-projects
+the layers Dflow itself owns — the workflow bundle, command / skill adapters,
+the marked block inside existing agent files, and the marker-guarded canonical
+region of `AI-AGENT-GUIDE.md` — and advances the `> Dflow Version:` line in
+`_conventions.md` to the CLI version it reconciled with. It does **not**
+rewrite user-owned content: the guide's `## Project Context`, the rest of
+`_conventions.md`, the init-only starters (`_overview.md`,
+`Git-principles-*.md`), and any prose outside a shim's markers. A pre-marker guide, or an
+agent file carrying your own edits, is not rewritten silently either — an
+interactive run **asks** before adopting the markers (default No; guide
+adoption keeps `## Project Context`), and a non-interactive run skips with a
+warning; only a pristine, unedited Dflow shim is still regenerated in place as
+before. After upgrading, run `dflow doctor`
+first: it reports drift read-only (a stale last-reconciled version, a frozen
+guide or dangling `§` references from the bundle, policy sections that are no
+longer machine-readable, feature `_index.md` files with an older template
+shape, unmanaged agent files). For a thorough verification, the baseline is
+still a **brand-new `dflow init` with the same edition and the same answers**
+elsewhere, diffed file-by-file against your project: every difference should
+classify as either "your user content" or "known outside-the-markers",
+otherwise it is a missed update.
 
 For tool-specific walk-throughs of what `init` writes and how Dflow's
 workflow commands appear in a given AI tool, see the per-tool guides under
@@ -446,10 +457,9 @@ For the full loop (how a blind spot becomes guidance, and why the flip points to
 |---|---|
 | `bin/` | CLI entrypoint. |
 | `lib/` | CLI runtime implementation (init / configure-agents / doctor / render). |
-| `templates/` | Files copied by the init command. |
+| `templates/` | The single source of workflow content; `dflow init` / `dflow configure-agents` project from here into your project. |
 | `test/` | Smoke tests for generated output. |
 | `tutorial/` | Guided learning scenarios and expected outputs. |
-| `sdd-ddd-*-skill/` | Source workflow material consumed by AI coding agents. |
 
 ## Contributing and Releases
 
@@ -462,20 +472,21 @@ Publish Checklist](docs/npm-publish-checklist.md).
 ## Status
 
 Dflow is currently published as `dflow-sdd-ddd` on npm. The latest published
-npm package is `0.13.0`, covering:
+npm package is `0.14.0`, covering:
 
 - Project initialization (`dflow init`) and idempotent upgrade re-projection (`dflow configure-agents`)
 - Workflow documentation (the `/dflow:*` flows) plus a workflow bundle vendored into each project
 - Multi-AI agent setup: a canonical guide plus thin per-tool shims (CLAUDE.md / AGENTS.md / Copilot instructions), with existing agent files auto-injected as a marked block (no manual merge)
+- Marker-guarded in-place refresh of the guide's Dflow canonical sections on upgrade, plus consent-gated marker adoption for pre-marker guides / agent files (0.14)
 - Native project-level skills for all three tools (Claude / Codex / GitHub Copilot), **installed by init by default** (0.13), sharing the agentskills.io open standard with natural-language auto-trigger (Copilot CLI still summons via `/dflow`)
 - Optional tool-native command entries (`--command-adapters`); `--skills` backfills / force-regenerates the skill
 - `dflow render`: specs Markdown → a browsable static HTML mirror (for human reading; opens via `file://`, no server; 0.13)
 - AI-agent-readable SDD/DDD guidance, including deepened DDD tactical-modeling guidance and a closed model-lifecycle loop (long-running flows and model re-review; 0.11–0.12)
-- `dflow doctor` read-only project health check
+- `dflow doctor` read-only project health check, including upgrade-drift detection (version line, policy format, guide freeze and dangling references, starter drift, template shape; 0.14)
 - Public onboarding: evaluator guide and per-tool walkthroughs for Claude Code, Codex CLI, and GitHub Copilot
 - A verification-only CI workflow (it does not execute publish)
 
-The GitHub source may include post-`0.13.0` repository changes before the
+The GitHub source may include post-`0.14.0` repository changes before the
 next npm release is published. See [CHANGELOG.md](CHANGELOG.md) for full
 release history.
 

package/README.md

@@ -219,7 +219,9 @@ Dflow 也會為你的 AI 程式設計助理建立或更新專案指示檔；確
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
 若這些檔案已存在，Dflow 不會覆蓋自訂內容；已是 Dflow-generated shim 的檔案
-會原地刷新，其他已指向 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過。
+會原地刷新。其他已指向 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的自寫檔不會被
+改寫：互動執行會詢問是否在檔尾附加帶 marker 的管理區塊（預設 N），非互動
+執行則略過並警告。
 若檔案尚未指向 guide，預設會在確認 preview 顯示並於檔案末尾附加帶有
 `<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block，重跑會
 原地更新同一段且不重複。只有檔案內有衝突或 malformed Dflow markers 時，
@@ -241,9 +243,9 @@ source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow
 
 這是**建議**，不是唯一正解。若團隊希望 clone 後立即有原生 `/` 選單、或 CI / 開發環境不裝 npm，**版控 adapter** 也是合理選擇——代價是升級若改了命名，要重投影並 commit 刪除舊檔。關鍵原則：**同一專案對所有工具採一致策略**，別像常見的踩雷一樣一邊 ignore、一邊版控。
 
-升級 dflow 後重跑 `dflow configure-agents --command-adapters`，adapter 會用**新版的 command registry** 重投影；但**不會**覆寫已存在的 `dflow/specs/shared/AI-AGENT-GUIDE.md`（canonical guide 已存在則保留）。「重投影 adapter」與「升級 canonical guide」是兩件事；升級時請用**相同的 dflow CLI 版本**重投影，避免 registry 與 guide 版本錯位。各工具的 `.gitignore` 片段、glob 副作用、`git rm --cached` 切換步驟與升級細節見 per-tool 指南。
+升級 dflow 後重跑 `dflow configure-agents --command-adapters`，adapter 會用**新版的 command registry** 重投影；`dflow/specs/shared/AI-AGENT-GUIDE.md` 內**帶 marker 的 canonical 區**也會原地刷新（marker 以外——含 `## Project Context`——保留不動），兩者不再錯位。升級時請用**相同的 dflow CLI 版本**重投影。各工具的 `.gitignore` 片段、glob 副作用、`git rm --cached` 切換步驟與升級細節見 per-tool 指南。
 
-**升級既有專案的 caveat**：`configure-agents` 只重投影 Dflow 自己擁有的自動層（workflow bundle、command / skill adapters，以及既有 agent 檔內帶 marker 的區塊）。它**不會**刷新 canonical 指南（`AI-AGENT-GUIDE.md`）與其他 user-owned 層（如 `_conventions.md`、shim marker 以外的文字）——這些檔在 init 後即歸專案所有、刻意不被覆寫。代價是：當新版把內容加進 canonical 指南時，既有專案不會自動拿到，可能與該版的 canonical 形狀 silent drift。升級既有專案後，建議手動 reconcile，並以「在別處跑一個**同 edition、同答案的全新 `dflow init`**、再與你的專案逐檔 diff」當驗證基準：每個差異都應能歸類為「你的 user content」或「已知 marker 以外」，否則就是漏修。
+**升級既有專案的 caveat**：`configure-agents` 重投影 Dflow 自己擁有的自動層——workflow bundle、command / skill adapters、既有 agent 檔內帶 marker 的區塊、以及 `AI-AGENT-GUIDE.md` 帶 marker 的 canonical 區——並把 `_conventions.md` 的 `> Dflow Version:` 行更新為本次對齊的 CLI 版本（last-reconciled）。它**不會**改寫 user-owned 內容：guide 的 `## Project Context`、`_conventions.md` 其餘內文、init-only starter（`_overview.md`、`Git-principles-*.md`）、以及 shim marker 以外的文字。還沒有 marker 的 guide、或帶有你自己編輯的 agent 檔，Dflow 不靜默改寫——互動執行會**詢問**是否採用 marker（預設 N；guide 採用時 `## Project Context` 保留），非互動則跳過並警告；只有**未經編輯的 pristine Dflow shim** 照舊直接原地重生成。升級後先跑 `dflow doctor`：它以 read-only 回報漂移（對齊版本落後、guide 凍結或 bundle 的 `§` 參照斷裂、政策段非機器格式、舊模板形狀的 feature `_index.md`、未受管的 agent 檔）。要更徹底的驗證，仍以「在別處跑一個**同 edition、同答案的全新 `dflow init`**、再與你的專案逐檔 diff」當基準：每個差異都應能歸類為「你的 user content」或「已知 marker 以外」，否則就是漏修。
 
 特定工具的 init 寫入內容與 Dflow workflow 命令呈現方式，見 `docs/` 內的 per-tool 指南：
 
@@ -340,10 +342,9 @@ Dflow 把 DDD 當成規格背後的語意結構：ubiquitous language 讓命名
 |---|---|
 | `bin/` | CLI 進入點 |
 | `lib/` | CLI runtime 實作（init / configure-agents / doctor / render） |
-| `templates/` | init 指令複製的檔案 |
+| `templates/` | workflow 內容唯一來源；`dflow init` / `dflow configure-agents` 由此投影到你的專案 |
 | `test/` | 產出物的 smoke test |
 | `tutorial/` | 引導式學習劇情與預期產出 |
-| `sdd-ddd-*-skill/` | AI 程式設計助理消化的 workflow 來源材料 |
 
 ## 貢獻與發布
 
@@ -351,20 +352,21 @@ issue 與 pull request 指引見 [CONTRIBUTING.md](CONTRIBUTING.md)。Pull reque
 
 ## 狀態
 
-Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.13.0`，涵蓋：
+Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.14.0`，涵蓋：
 
 - 專案初始化（`dflow init`）與 idempotent 升級重投影（`dflow configure-agents`）
 - Workflow 文件（`/dflow:*` 流程）＋隨專案 vendored 的 workflow bundle
 - 多 AI agent 設定：canonical 指南 + 各工具薄 shim（CLAUDE.md / AGENTS.md / Copilot instructions）；既有 agent 檔以帶 marker 的區塊自動注入、零手動合併
+- 升級時 guide 的 Dflow canonical 段落 marker-guard 原地刷新；舊 guide / 舊 agent 檔的 consent-gated marker adoption（0.14）
 - 三家原生 project-level skill（Claude / Codex / GitHub Copilot），**init 預設安裝**（0.13）、共用 agentskills.io 開放標準、支援自然語言自動觸發（Copilot CLI 仍需先打 `/dflow` 喚起）
 - 選配工具原生命令入口（`--command-adapters`）；`--skills` 補裝 / 強制重生成 skill
 - `dflow render`：specs Markdown → 可瀏覽的靜態 HTML 鏡像（給人讀；`file://` 直開、免 server；0.13）
 - AI agent 可讀的 SDD/DDD 指引，含深化的 DDD 戰術建模指引與模型生命週期閉環（長時流程與模型重審；0.11–0.12）
-- `dflow doctor` 唯讀專案健康檢查
+- `dflow doctor` 唯讀專案健康檢查，含升級 drift 偵測（版本行、政策格式、guide 凍結與 dangling 參照、starter 漂移、模板形狀；0.14）
 - 公開 onboarding：evaluator 指南，Claude Code / Codex CLI / GitHub Copilot 的 per-tool walkthrough
 - 僅驗證的 CI workflow（不執行 publish）
 
-GitHub 上的 source 可能包含 `0.13.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
+GitHub 上的 source 可能包含 `0.14.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 授權
 

package/TEMPLATE-COVERAGE.md

@@ -29,8 +29,8 @@ The matrix lists Brownfield / Greenfield logical template parity so reviewers ca
 
 ## Reference Flow Parity
 
-Common reference flows under `sdd-ddd-brownfield-skill/references/` and
-`sdd-ddd-greenfield-skill/references/` must stay synchronized unless a
+Common reference flows under `templates/brownfield/references/` and
+`templates/greenfield/references/` must stay synchronized unless a
 track-specific difference is explicit. This includes
 `dflow-feedback-flow.md`; it is a governance/support flow and should not grow
 GitHub CLI submission behavior without a separate proposal.

package/bin/dflow.js

@@ -51,6 +51,14 @@ Without --skills, selecting an agent that has no project-level skill yet
 prompts to install it (default yes) on an interactive terminal; non-interactive
 runs install it by default without reading an extra stdin answer. Agents whose
 skill file already exists are not re-asked and not regenerated.
+
+On upgrade re-runs the command also refreshes the marker-guarded canonical
+region of dflow/specs/shared/AI-AGENT-GUIDE.md (content outside the markers,
+including "## Project Context", is kept) and advances the "> Dflow Version:"
+last-reconciled line in _conventions.md. A pre-marker guide, or an agent file
+you edited yourself, is never rewritten silently: interactive runs offer
+marker adoption (default No); non-interactive runs skip and warn. (A pristine,
+unedited Dflow shim is still regenerated in place, as before.)
 `);
 }
 
@@ -92,7 +100,20 @@ function printDoctorHelp() {
 Read-only health check for the current project. Reports findings such as:
 
   - dflow/specs/shared/_conventions.md missing the Dflow Version
-    front-matter line
+    front-matter line, or recording an older last-reconciled version
+  - policy sections (Git Policy / AI Commit Policy / Prose Language)
+    missing or no longer machine-readable
+  - AI-AGENT-GUIDE.md frozen at an older Dflow version (missing or
+    malformed guide-canonical markers, stale canonical content) and
+    dangling "AI-AGENT-GUIDE.md § ..." references from the workflow bundle
+  - AI-AGENT-GUIDE.md "## Project Context" missing the machine-readable
+    Tech stack / Migration rows that context inference reads
+  - init-only starters drifted (missing or edited Git-principles file
+    for the selected policy)
+  - active feature _index.md files created from an older template shape
+  - root agent files (AGENTS.md / CLAUDE.md / copilot-instructions.md)
+    with malformed Dflow markers or unmanaged Dflow wording
+  - workflow bundle orphans and a bundle projected by an older Dflow
 
 Doctor never modifies files.
 `);

package/docs/npm-publish-checklist.md

@@ -12,7 +12,9 @@ Replace `<version>` with the version being published, for example `0.1.2`.
 - [ ] Update `CHANGELOG.md`.
 - [ ] Confirm `README.md` installation instructions match the release.
 - [ ] Confirm Greenfield and Brownfield common flow changes are synchronized.
-- [ ] Confirm generated templates match skill source where applicable.
+- [ ] Confirm workflow content changes are complete under `templates/` — the
+      single content source; there is no separate skill-source copy to
+      synchronize.
 - [ ] Run the lifecycle check in the development repo and confirm it is green,
       so every proposal this release covers is terminal (`implemented` /
       `rejected` / `superseded`) and already archived:

package/docs/release-versioning-policy.md

@@ -95,8 +95,9 @@ the only place where release history is recorded.
 
 ## Greenfield and Brownfield Changes
 
-If a change touches a common SDD flow, update both Greenfield and Brownfield
-skill sources unless the release intentionally changes only one track.
+If a change touches a common SDD flow, update the flow under both
+`templates/greenfield/references/` and `templates/brownfield/references/`
+unless the release intentionally changes only one track.
 
 Common synchronized flow files include:
 

package/docs/using-with-claude-code.en.md

@@ -82,8 +82,11 @@ without Claude-Code-specific edits.
 
 If a `CLAUDE.md` already existed in the project, `init` does not overwrite
 custom content. A Dflow-generated shim is refreshed in place; another file
-that already points to `dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped
-without adding a second pointer. Otherwise Dflow shows the change in the
+that already points to `dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped with
+a warning, without adding a second pointer — a later interactive
+`dflow configure-agents` run offers to append the marked managed block
+(default No), while non-interactive runs keep skipping with the warning.
+Otherwise Dflow shows the change in the
 confirmation preview and appends a marked
 `<!-- dflow-generated: agent-shim START/END -->` block at the end of the file;
 re-running refreshes that same block in place without duplicating it. Dflow
@@ -208,10 +211,13 @@ git rm --cached -r .claude/commands/dflow/
 files.)
 
 After upgrading Dflow, re-running `dflow configure-agents --command-adapters`
-re-projects adapters from the **new registry**, but an existing
-`dflow/specs/shared/AI-AGENT-GUIDE.md` is **not** overwritten — "re-projecting
-adapters" is not the same as "migrating the canonical guide." Re-project with
-the **same dflow CLI version** to avoid a registry / guide version mismatch.
+re-projects adapters from the **new registry** and also refreshes the
+**marker-guarded canonical region** of `dflow/specs/shared/AI-AGENT-GUIDE.md`
+in place (everything outside the markers — including `## Project Context` — is
+kept). If an older project's guide has no markers yet, an interactive run asks
+before adopting them (default No); a non-interactive run skips with a warning.
+Re-project with the **same dflow CLI version**, and run `dflow doctor`
+afterwards to review any remaining drift (read-only).
 
 ### Skill Adapter (Natural-Language Auto-Trigger, Installed by Default)
 

package/docs/using-with-claude-code.md

@@ -184,8 +184,10 @@ git rm --cached -r .claude/commands/dflow/
 （`--cached` 只移出版控、保留工作目錄檔案。）
 
 升級 dflow 後重跑 `dflow configure-agents --command-adapters`，adapter 會用**新版 registry**
-重投影；但既有 `dflow/specs/shared/AI-AGENT-GUIDE.md` **不會**被覆寫——「重投影 adapter」不等於
-「升級 canonical guide」。請以**相同的 dflow CLI 版本**重投影，避免 registry 與 guide 版本錯位。
+重投影；`dflow/specs/shared/AI-AGENT-GUIDE.md` 內**帶 marker 的 canonical 區**也會原地刷新
+（marker 以外——含 `## Project Context`——保留不動）。較舊專案的 guide 還沒有 marker 時，
+互動執行會詢問是否採用（預設 N）、非互動則跳過並警告。請以**相同的 dflow CLI 版本**重投影，
+升級後先跑 `dflow doctor` 檢視殘餘漂移（read-only）。
 
 ### Skill Adapter（自然語言自動觸發，init 預設安裝）
 
@@ -295,7 +297,9 @@ Code 會在進入對應 workflow 時才讀取它們。這樣可以讓 context
 工作保持比例。
 
 **既有的 `CLAUDE.md` 會被保留。** `init` 不會覆蓋你現有的自訂專案指示；已是
-Dflow-generated shim 會原地刷新，其他已指向 `AI-AGENT-GUIDE.md` 的檔案會略過，
+Dflow-generated shim 會原地刷新，其他已指向 `AI-AGENT-GUIDE.md` 的檔案會略過
+並警告、不新增第二個指標（之後在互動終端跑 `dflow configure-agents` 會詢問
+是否附加帶 marker 的管理區塊，預設 N；非互動執行維持略過並警告），
 否則會在確認 preview 顯示要附加的 marked Dflow block，寫入後重跑會原地更新同一段。
 若你刪除該 block，下一次 `init` / `configure-agents` 會再附加它；只有 marker
 conflict 時才需要到 `dflow/specs/shared/` 找 fallback merge snippet 手動處理。

package/docs/using-with-codex.en.md

@@ -86,8 +86,11 @@ GitHub Copilot, and other tools.
 
 If an `AGENTS.md` already existed in the project, `init` does not overwrite
 custom content. A Dflow-generated shim is refreshed in place; another file
-that already points to `dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped
-without adding a second pointer. Otherwise Dflow shows the change in the
+that already points to `dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped with
+a warning, without adding a second pointer — a later interactive
+`dflow configure-agents` run offers to append the marked managed block
+(default No), while non-interactive runs keep skipping with the warning.
+Otherwise Dflow shows the change in the
 confirmation preview and appends a marked
 `<!-- dflow-generated: agent-shim START/END -->` block at the end of the file;
 re-running refreshes that same block in place. Dflow writes the fallback merge

package/docs/using-with-codex.md

@@ -76,7 +76,9 @@ Claude Code、GitHub Copilot 與其他工具。
 
 如果專案中已有 `AGENTS.md`，`init` 不會覆蓋自訂內容。已是 Dflow-generated shim
 的檔案會原地刷新；其他已指向 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會
-略過，不會新增第二個指標。否則 Dflow 會在確認 preview 顯示並於檔案末尾附加帶有
+略過並警告，不會新增第二個指標——之後在互動終端跑 `dflow configure-agents`
+會詢問是否附加帶 marker 的管理區塊（預設 N），非互動執行維持略過並警告。
+否則 Dflow 會在確認 preview 顯示並於檔案末尾附加帶有
 `<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block，重跑會
 原地更新同一段。只有遇到衝突或 malformed Dflow markers 時，才會改寫
 `dflow/specs/shared/AGENTS-md-snippet.md` fallback merge snippet 讓你手動合併。

package/docs/using-with-github-copilot.en.md

@@ -196,10 +196,13 @@ git rm --cached .github/prompts/dflow-*.prompt.md
 files.)
 
 After upgrading Dflow, re-running `dflow configure-agents --command-adapters`
-re-projects prompt adapters from the **new registry**, but an existing
-`dflow/specs/shared/AI-AGENT-GUIDE.md` is **not** overwritten — "re-projecting
-adapters" is not the same as "migrating the canonical guide." Re-project with
-the **same dflow CLI version**.
+re-projects prompt adapters from the **new registry** and also refreshes the
+**marker-guarded canonical region** of `dflow/specs/shared/AI-AGENT-GUIDE.md`
+in place (everything outside the markers — including `## Project Context` — is
+kept). If an older project's guide has no markers yet, an interactive run asks
+before adopting them (default No); a non-interactive run skips with a warning.
+Re-project with the **same dflow CLI version**, and run `dflow doctor`
+afterwards to review any remaining drift (read-only).
 
 ### Sample Conversation Flow
 
@@ -230,7 +233,10 @@ Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
 If a `.github/copilot-instructions.md` file already exists in your project,
 `init` does not overwrite custom content. A Dflow-generated shim is refreshed
 in place; another file that already points to
-`dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped. If the file does not yet
+`dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped with a warning — a later
+interactive `dflow configure-agents` run offers to append the marked managed
+block (default No), while non-interactive runs keep skipping with the warning.
+If the file does not yet
 point to the guide, Dflow shows the change in the confirmation preview and
 appends a marked `<!-- dflow-generated: agent-shim START/END -->` block at the
 end of the file; re-running refreshes that same block in place without
@@ -292,7 +298,7 @@ The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the same across
 ## Where to Go Next
 
 - If you have not run `init`: run `dflow init` (after `npm install -g dflow-sdd-ddd`) or `npx dflow-sdd-ddd init` and choose the Copilot target to create `.github/copilot-instructions.md`.
-- Read [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../sdd-ddd-greenfield-skill/scaffolding/AI-AGENT-GUIDE.md) (or the brownfield equivalent) before starting a workflow.
+- Read [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../templates/greenfield/scaffolding/AI-AGENT-GUIDE.md) (or the brownfield equivalent) before starting a workflow.
 - See [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md) for conversation examples that demonstrate Copilot chat flows.
 - Read [`docs/why-ddd-for-ai.en.md`](why-ddd-for-ai.en.md) for the design rationale behind spec-first plus DDD.
 

package/docs/using-with-github-copilot.md

@@ -178,8 +178,10 @@ git rm --cached .github/prompts/dflow-*.prompt.md
 （`--cached` 只移出版控、保留工作目錄檔案。）
 
 升級 dflow 後重跑 `dflow configure-agents --command-adapters`，prompt adapter 會用**新版 registry**
-重投影；但既有 `dflow/specs/shared/AI-AGENT-GUIDE.md` **不會**被覆寫——「重投影 adapter」不等於
-「升級 canonical guide」。請以**相同的 dflow CLI 版本**重投影。
+重投影；`dflow/specs/shared/AI-AGENT-GUIDE.md` 內**帶 marker 的 canonical 區**也會原地刷新
+（marker 以外——含 `## Project Context`——保留不動）。較舊專案的 guide 還沒有 marker 時，
+互動執行會詢問是否採用（預設 N）、非互動則跳過並警告。請以**相同的 dflow CLI 版本**重投影，
+升級後先跑 `dflow doctor` 檢視殘餘漂移（read-only）。
 
 ### 對話範例
 
@@ -209,7 +211,9 @@ Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
 
 如果你的專案中已有 `.github/copilot-instructions.md`，`init` 不會覆蓋自訂內容。
 已是 Dflow-generated shim 的檔案會原地刷新；其他已指向
-`dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過。若既有檔案尚未指向 guide，
+`dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過並警告——之後在互動終端跑
+`dflow configure-agents` 會詢問是否附加帶 marker 的管理區塊（預設 N），非互動
+執行維持略過並警告。若既有檔案尚未指向 guide，
 Dflow 會在確認 preview 顯示並於檔案末尾附加帶有
 `<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block；重跑會
 原地更新同一段，不會重複。這樣可以避免破壞你已有的自訂 Copilot 指示。若你刪除
@@ -290,7 +294,7 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 
 如果你已執行 `init` 且想查看端到端的 workflow 範例：
 
-- 閱讀 [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../sdd-ddd-greenfield-skill/scaffolding/AI-AGENT-GUIDE.md)
+- 閱讀 [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../templates/greenfield/scaffolding/AI-AGENT-GUIDE.md)
   （或 brownfield 等效版本）後再開始 workflow。
 - 閱讀 [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)，
   其中有展示 Copilot chat flow 的對話範例。