dflow-sdd-ddd 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -6,6 +6,161 @@
 
 ---
 
+## 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）
+
+本版兩條主線：
+
+1. **Specs 給 AI 讀、也給人讀**（073）——新增 `dflow render`，把 `dflow/specs/`
+   Markdown 樹鏡像成可瀏覽的靜態 HTML，`file://` 直開免 server；Markdown 仍是
+   AI-facing source of truth。
+2. **自然語言自動觸發成為 day-one 體驗**（074）——`dflow init` 預設安裝
+   project-level skill（先前要 `configure-agents --skills` 事後加裝）；
+   configure-agents 對「之後加新工具」路徑同步補問，兩條 onboarding 路徑一致。
+
+### 新功能
+
+- **`dflow render [--src <dir>] [--out <dir>] [--title <text>]`**（PROPOSAL-073）：
+  specs Markdown → 靜態 HTML 鏡像 + 根目錄 `index.html` 檔案樹（記錄型表格轉
+  卡片、AI 標記轉 badge、gherkin 關鍵字高亮、樹內 `.md` 連結改連對應 HTML 頁）；
+  每次執行全量重建。人讀性工具、不是 AI workflow 指令：不進命令登錄表、無
+  command adapters，11 個 `/dflow:*` 清單不變。輸出目錄由 render 專屬持有：
+  `.dflow-render-manifest.json` ledger + 每檔內嵌 generated-by marker——來源
+  刪除/改名的殘檔下次執行清掉（ledger 列名 + marker 雙證才刪）、marker 驗證
+  才覆寫、非空且無 ledger 的目錄拒絕、symlink / junction / hardlink / 特殊檔
+  拒絕、來源投影碰撞先拒絕；`--src` 永不被寫。第一個 npm runtime 依賴：
+  `marked`（exact-pinned `18.0.5`）。
+
+### 行為變更（breaking-class，升級請讀）
+
+- **init 預設安裝 project-level skill**（PROPOSAL-074）：`dflow init` 在 AI agents
+  題後新增 skill 安裝題——只在互動終端機（TTY）問、專用預設 Y 契約（空白輸入 =
+  裝）；答 `n` 必印 `dflow configure-agents --skills` 補裝提示；未選任何 agent 則
+  不問也不裝。**非互動（piped）init 不新增 stdin 槽位**：既有腳本答案序列結構不變
+  照跑，但產出集合改變——會為選定 agents 預設多產出 skill 檔
+  （`.claude/skills/dflow/` / `.agents/skills/dflow/` / `.github/skills/dflow/`）。
+- **configure-agents 對稱補問**（PROPOSAL-074 開放問題 2 選 (b)）：無 `--skills`
+  時，對「新選且尚無 skill」的 agent 問同款預設 Y 題（非 TTY 直接預設裝）；已有
+  skill 檔（Dflow 產或使用者自有）的 agent 不重問、不重生成。`--skills` 語意不變
+  ＝強制重生成所有選定工具的 skill。既有 scripted configure-agents 若選了尚無
+  skill 的 agent，非互動下會多產出 skill 檔。
+- init / configure-agents 完成訊息在裝了 skill 時加衍生物版控提示（建議
+  gitignore + clone 後重投影，沿用 PROPOSAL-037 建議預設）。
+
+### 模板 / 慣例
+
+- **表格一格多項的 `<br>` 分行慣例**（PROPOSAL-072）：spec 模板與 skill source
+  加格式守則註記（36 檔）——記錄型表格一格多項時用 `<br>` 分行，避免整格糊成
+  一行；不改任何欄位語意。
+
+### 文件
+
+- README（zh/en）主要特點表加「Specs 給 AI 讀、也給人讀（md → HTML）」列；
+  render 段落加左右對照截圖（`media/render-side-by-side.png`，以正式 renderer
+  跑 tutorial outputs 產生；`media/` 隨 GitHub 散佈、不進 npm tarball）；
+  npm-latest 版本參照刷新。
+- README（zh/en）「開始使用」改寫：`--skills` 從「建議標準安裝」改為「init 預設
+  已裝；`--skills` = 補裝 / 強制重生成」，並補非互動契約與版控建議；per-tool
+  docs（Claude / Codex / Copilot × zh/en）、evaluating-dflow（zh/en）、兩軌
+  init-project-flow（加 Q9 + manual fallback 不手寫 SKILL.md 守句；templates
+  鏡像同步）、TEMPLATE-COVERAGE（加 skill 列）、bin help、tutorial 兩軌
+  walkthrough-01 + `outputs/` fixtures（補真 CLI 產生的 SKILL.md 快照）同步。
+
+### 驗證
+
+- **P-073**：proposal-stage review 收斂 → impl-stage cross-model loop R1–R3 →
+  fresh cold-eye gates G1–G8（每輪全新 session、不餵先前 findings、gate 前後
+  worktree hash 比對）至 **G8 approve 零 findings**。
+- **P-074**：proposal-stage R1–R4 收斂（R3 reviewer 檔案存取故障判有條件
+  approve、不採計，R3b 全文內嵌重驗）→ impl-stage G6 2 findings（flagless
+  configure-agents「只裝缺的」邊界、Claude docs 舊契約殘留）修正 → G6 R2
+  approve 零 findings → fresh cold-eye gate G7 runtime 面零 findings。
+- `test/skill-default.mjs`（新增，in-process 假 TTY）：TTY Y / n / 空白（預設
+  Y）/ 未選 agent 不問、configure-agents missing 問 / 已有不重問 / n-path 提示 /
+  `--skills` 不問。smoke：非 TTY 序列不變性（舊 9 行序列原樣照跑 + 多出 skill
+  檔）、no-agent 不裝、configure-agents 非 TTY 預設補裝（含「加新工具」路徑 +
+  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`。
+
+### 升級提醒
+
+- **scripted 自動化不用改答案序列**：非互動 `dflow init` / `configure-agents`
+  的既有 stdin 序列照跑；差別是產出會多 skill 檔。不想要 → TTY 下答 `n`、
+  非互動則事後刪檔並 gitignore（skill 檔是衍生物，`dflow configure-agents
+  --skills` 隨時可重生成）。
+- 既有專案重跑 `configure-agents` 新增工具時會被補問 skill（預設 Y）；已有
+  skill 的工具不受影響。
+- `dflow render` 為新增指令，不影響任何既有 workflow；11 個 `/dflow:*` 指令
+  清單不變。
+
+---
+
 ## 0.12.0 — 2026-07-09 — 模型生命週期閉環（長時流程 + 模型重審）+ 收尾守門與跨 session 連續性
 
 **Proposals**：PROPOSAL-067（skill source 舊制 ID 與範例正確性清理）、PROPOSAL-068（finish-feature 收尾完整性守門）、PROPOSAL-069（跨分支 / 跨 session 連續性 Phase 1）、PROPOSAL-070（Long-Running Processes 判準與最簡階梯）、PROPOSAL-071（模型修正判準）

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

@@ -24,6 +24,7 @@ The goal is not the process itself, but repeatable software change with clearer
 | **Three-layer documentation model** | Matches how feature branches actually evolve: phase (one propose-implement-archive cycle) / feature (the whole branch's running state and resume pointer) / system (cross-feature long-term knowledge). Many spec tools only ship phase + system, which breaks down when a feature branch spans multiple phases. Detailed below. |
 | **Change-depth-based tiers (T1/T2/T3)** | AI scales specification and verification by change depth: color/typo gets one inline row in `_index.md`; bug fixes get a lightweight spec plus focused verification; new features or bounded-context-level changes go through a full phase-spec plus layer-by-layer implementation planning / verification. Small changes don't get dragged down by the process. |
 | **Drift verification** | `/dflow:verify` cross-checks specs, domain documents, implementation, tests, and tech-debt records to surface the "documentation still describes the old behavior" drift that PR review by eye usually misses. |
+| **Specs humans can read, not just AI (md → HTML)** | Most spec-first tools produce specs only the AI reads comfortably — dense Markdown tables and markers humans skim past, so spec review quietly stops happening. `dflow render` mirrors the whole specs tree into browsable static HTML: tables become cards, AI-facing markers become badges, cross-file links stay clickable. Markdown stays the AI-facing source of truth; humans get a readable projection. Side-by-side screenshot below. |
 | **Multi-AI-tool rule sharing** | A canonical project guide plus thin tool-specific shims (`CLAUDE.md` / `AGENTS.md` / Copilot instructions) — teams switching between Claude, Codex, and Copilot don't have to maintain multiple copies of workflow rules. All three also share one project-level skill built on the agentskills.io open standard, so natural language auto-triggers the matching workflow (Copilot CLI summons it via `/dflow`). |
 
 ## Get Started
@@ -40,11 +41,22 @@ dflow init
 ```
 
 The init flow asks whether the project is greenfield or brownfield, which Git
-policy the team follows (GitFlow / Trunk), and how AI-made commits should be
-marked, then previews the files it will create. Existing files are not overwritten. Init
+policy the team follows (GitFlow / Trunk), how AI-made commits should be
+marked, and which AI tools to configure, then previews the files it will create. Existing files are not overwritten. Init
 creates workflow documentation and AI instruction files; it does not inspect,
 refactor, or migrate your application code.
 
+When AI tools were selected, init also installs the project-level skill for
+them (Claude, Codex, and GitHub Copilot) **by default** — the source of
+natural-language auto-trigger (you say "I want to add a feature" and the AI
+suggests the matching workflow; Copilot CLI summons it via `/dflow`). On an
+interactive terminal it asks one `(Y/n)` question — just press Enter to
+install; a scripted (non-interactive) run never reads an extra answer and
+installs by default, so existing automation answer sequences run unchanged.
+Skill files are Dflow-generated derivatives: the recommended default is to
+gitignore them and re-project after cloning (see the version-control table
+below).
+
 If the project is already initialized and you later add another AI coding
 tool, run:
 
@@ -52,16 +64,24 @@ tool, run:
 dflow configure-agents
 ```
 
-Adding `--skills` projects a project-level skill for all three tools (Claude,
-Codex, and GitHub Copilot), restoring natural-language auto-trigger (you say "I
-want to add a feature" and the AI suggests the matching workflow; Copilot CLI
-still summons it via `/dflow`). All three support it now, so treat it as the
-recommended standard install:
+It asks the same default-yes skill question for newly selected tools that have
+no skill yet (non-interactive runs install by default), so tools added later
+don't miss auto-trigger either. To force-regenerate the skills for all selected
+tools (for example to refresh them after upgrading Dflow), use `--skills`:
 
 ```bash
 dflow configure-agents --skills
 ```
 
+Answering `n` to the skill does not leave the AI trigger-blind — the project
+instructions init writes (the shims + the canonical guide) already tell it to
+suggest the matching `/dflow:*` command for spec-impacting requests. The
+difference is reliability: that path depends on the model remembering the
+instructions in the moment and degrades in long sessions, while the skill hands
+triggering to the tool's native matching mechanism (the skill's trigger
+description sits in front of the model every turn), making it dependable. You
+can add it any time later with `dflow configure-agents --skills`.
+
 If you also want tool-native `/` command / prompt menus, add `--command-adapters`
 (it composes with `--skills`):
 
@@ -113,6 +133,49 @@ Dflow](docs/evaluating-dflow.en.md). For end-to-end scenario walk-throughs of
 Greenfield and Brownfield workflows with worked spec outputs, see the
 [`tutorial/`](tutorial/README.md) index.
 
+### Render the specs as human-readable HTML
+
+Dflow specs are AI-facing Markdown (dense tables, heavy markers). For human
+reading, run:
+
+```bash
+dflow render
+```
+
+It mirrors `dflow/specs/` into a static HTML tree (default output
+`dflow-specs-html/`; adjust with `--src` / `--out` / `--title`): record-style
+tables become one card per row, AI-facing comment markers become badges /
+chips, gherkin blocks get keyword highlighting, and in-tree `.md` links and
+filename mentions are rewritten to the matching HTML pages. Open the output
+directory's `index.html` in a browser (`file://` works; no server needed).
+
+The same spec, read two ways — left: the AI-facing Markdown source (dense
+tables plus AI-only markers like `<!-- phase-2 ADDED -->`); right: the HTML
+`dflow render` produces (one card per row, markers become badges):
+
+![The same models.md: AI-facing Markdown source on the left, dflow render HTML output on the right](media/render-side-by-side.png)
+
+The example comes from this repo's Expense tutorial specs
+([`tutorial/01-greenfield/outputs`](tutorial/01-greenfield/outputs/)); after
+cloning and running `npm install`, reproduce it with
+`node bin/dflow.js render --src tutorial/01-greenfield/outputs/dflow/specs`.
+
+The division of labor: **Markdown is the AI-facing source of truth; HTML is
+the human-reading projection.** Re-run `dflow render` whenever the specs
+change (every run is a full rebuild). The output directory is managed by
+render — tracked in `.dflow-render-manifest.json`, so deleting or renaming a
+source cleans up its stale HTML on the next run, and files render did not
+generate are never touched — it is a regenerable derived artifact, so add it
+to `.gitignore`:
+
+```gitignore
+dflow-specs-html/
+```
+
+Note: render passes inline HTML in your specs (`<br>` and the like) through
+as-is, without sanitizing — it is designed to render your own project's specs
+(a trusted source); do not point it at untrusted Markdown.
+
 ## Project Tracks
 
 | Track | Use it when | Main outcome |
@@ -220,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
@@ -231,10 +297,12 @@ guide stays the single source of truth, so teams can use multiple AI tools
 without maintaining multiple copies of the workflow rules.
 
 You can run `dflow configure-agents` later to add more tool shims as the team
-adopts additional AI coding agents. If you need Claude / Copilot tool-native
-command entries, use `dflow configure-agents --command-adapters`. For
-natural-language auto-trigger (a project-level skill for Claude Code, Codex, and
-GitHub Copilot), use `dflow configure-agents --skills`.
+adopts additional AI coding agents — it asks the default-yes skill question for
+newly selected tools that have no skill yet (non-interactive runs install by
+default), so auto-trigger is not missed. If you need Claude / Copilot
+tool-native command entries, use `dflow configure-agents --command-adapters`.
+To force-regenerate the skills for all selected tools (for example after
+upgrading Dflow), use `dflow configure-agents --skills`.
 
 ### Version-Control Policy for Generated Artifacts (recommended default)
 
@@ -259,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
@@ -380,11 +456,10 @@ For the full loop (how a blind spot becomes guidance, and why the flip points to
 | Path | Purpose |
 |---|---|
 | `bin/` | CLI entrypoint. |
-| `lib/` | Init runtime implementation. |
-| `templates/` | Files copied by the init command. |
+| `lib/` | CLI runtime implementation (init / configure-agents / doctor / render). |
+| `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
 
@@ -397,19 +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.10.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)
-- Native project-level skills for all three tools (Claude / Codex / GitHub Copilot), sharing the agentskills.io open standard with natural-language auto-trigger (Copilot CLI still summons via `/dflow`)
-- Optional tool-native command entries (`--command-adapters`) and an auto-trigger skill (`--skills`)
-- AI-agent-readable SDD/DDD guidance
-- `dflow doctor` read-only project health check
+- 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, 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.10.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

@@ -24,6 +24,7 @@
 | **三層文件模型** | 對應 feature branch 的實際節奏：phase（單次提案-實作循環）/ feature（整條 branch 的累積狀態與接續指引）/ system（跨 feature 的長期知識）。許多 spec 工具只有 phase + system 兩層，多次迭代的 feature branch 跨多個 phase 時就會失真。下方有完整說明。 |
 | **依改動深淺的 Tier 制（T1/T2/T3）** | AI 依改動深淺自動決定規格與驗證量級：改顏色 / typo 只需 `_index.md` 一行；bug fix 用 lightweight spec + 聚焦驗證；新 feature 或動到 bounded context 才走完整 phase-spec + 分層實作計畫 / 驗證。小修改不會被流程拖累。 |
 | **漂移驗證** | `/dflow:verify` 把規格、領域文件、實作、測試、技術債紀錄做交叉比對，找出 PR review 人眼看不出來的「文件還在描述舊行為」漂移。 |
+| **Specs 給 AI 讀、也給人讀（md → HTML）** | 多數 spec-first 工具的規格只有 AI 好讀——密集表格加標記的 Markdown，人翻起來吃力，時間一久規格就沒人 review。`dflow render` 把整棵 specs 樹轉成可瀏覽的靜態 HTML：表格變卡片、AI 專用標記變 badge、跨檔連結可點。Markdown 仍是 AI 讀的 source of truth，人另有一份好讀的投影。下方有對照截圖。 |
 | **多 AI 工具共用一份規則** | Canonical 專案指南 + 各工具薄 shim（`CLAUDE.md` / `AGENTS.md` / Copilot instructions），團隊在 Claude / Codex / Copilot 之間切換時不必維護多份 workflow 規則。三家還共用一份依 agentskills.io 開放標準的 project-level skill，可用自然語言自動觸發對應 workflow（Copilot CLI 需先打 `/dflow` 喚起）。 |
 
 ## 開始使用
@@ -37,7 +38,9 @@ npm install -g dflow-sdd-ddd
 dflow init
 ```
 
-init 流程會詢問是 greenfield 或 brownfield、團隊採用的 Git policy（GitFlow / Trunk）、以及 AI commit 的標記方式，接著預覽即將建立的檔案。既有檔案不會被覆寫。Init 只建立 workflow 文件與 AI 指示檔，**不會**檢查、重構、或遷移你的應用程式碼。
+init 流程會詢問是 greenfield 或 brownfield、團隊採用的 Git policy（GitFlow / Trunk）、AI commit 的標記方式、以及要設定哪些 AI 工具，接著預覽即將建立的檔案。既有檔案不會被覆寫。Init 只建立 workflow 文件與 AI 指示檔，**不會**檢查、重構、或遷移你的應用程式碼。
+
+有選 AI 工具時，init **預設**同時為選定的工具（Claude / Codex / GitHub Copilot）安裝 project-level skill——自然語言自動觸發的來源（你描述「我要加一個功能」，AI 就主動建議對應 workflow；Copilot CLI 需先打 `/dflow` 喚起）。互動模式會問一題 `(Y/n)`，直接按 Enter 就裝；腳本（非互動）模式不多讀任何答案、直接預設安裝，既有的自動化答案序列照跑不用改。skill 檔是 Dflow 衍生物，建議 gitignore、clone 後重新投影（見下方版控建議表）。
 
 若專案已初始化、之後又要加入另一個 AI 程式設計工具，執行：
 
@@ -45,12 +48,14 @@ init 流程會詢問是 greenfield 或 brownfield、團隊採用的 Git policy
 dflow configure-agents
 ```
 
-加上 `--skills` 會為 Claude / Codex / GitHub Copilot 三家投影 project-level skill，找回自然語言自動觸發（你描述「我要加一個功能」，AI 就主動建議對應 workflow；Copilot CLI 仍需先打 `/dflow` 喚起）。三家現在都支援，建議當成標準安裝：
+它對「新選、而且還沒有 skill」的工具問同一題預設 Y 的 skill 安裝問句（非互動同樣直接預設裝），之後加工具也不會漏掉自動觸發。要強制重生成所有選定工具的 skill（例如升級 Dflow 後刷新內容），用 `--skills`：
 
 ```bash
 dflow configure-agents --skills
 ```
 
+答 `n` 略過 skill 不代表 AI 完全不會建議 workflow——init 產生的專案指示（shim + canonical 指南）本身就要求 AI 對 spec-impacting 的請求建議對應的 `/dflow:*` 指令。差別在可靠度：那條路靠模型當下記得指示，對話一長就可能漏；skill 把觸發交給工具原生的匹配機制（skill 的觸發描述每回合都在模型面前），觸發才穩定。略過之後隨時可用 `dflow configure-agents --skills` 補裝。
+
 若還想要工具原生的 `/` 命令 / prompt 選單，再加 `--command-adapters`（可與 `--skills` 並用）：
 
 ```bash
@@ -88,6 +93,30 @@ dflow configure-agents --command-adapters --skills
 
 完整評估流程（init 產生哪些檔案、AI 工具支援、模式選擇、30 分鐘試用 playbook）見 [評估 Dflow](docs/evaluating-dflow.md)。Greenfield 與 Brownfield 端到端劇情走完與規格範例見 [`tutorial/`](tutorial/README.md) 索引。
 
+### 把 specs 轉成人類可讀的 HTML
+
+Dflow 的 specs 是給 AI 讀的 Markdown（表格緊湊、標記密集）。要給人閱讀時，執行：
+
+```bash
+dflow render
+```
+
+它把 `dflow/specs/` 鏡像成一棵靜態 HTML 樹（預設輸出 `dflow-specs-html/`，可用 `--src` / `--out` / `--title` 調整）：記錄型表格逐列轉成卡片、AI 專用註解標記變成 badge / chip、gherkin 區塊關鍵字高亮、樹內 `.md` 連結與檔名提及自動改連對應 HTML 頁。開啟輸出目錄的 `index.html` 即可瀏覽（`file://` 直開、免 server）。
+
+同一份 spec 的兩種讀法——左：AI 讀的 Markdown 源（密集表格 + `<!-- phase-2 ADDED -->` 這類 AI 專用標記）；右：`dflow render` 產出的 HTML（逐列變卡片、標記變 badge）：
+
+![同一份 models.md：左為 AI 讀的 Markdown 源，右為 dflow render 產生的 HTML 頁面](media/render-side-by-side.png)
+
+範例取自本 repo 的 Expense 教學規格（[`tutorial/01-greenfield/outputs`](tutorial/01-greenfield/outputs/)），clone、`npm install` 後可用 `node bin/dflow.js render --src tutorial/01-greenfield/outputs/dflow/specs` 自行重現。
+
+分工模型：**Markdown 是 AI 閱讀的 source of truth；HTML 是人類閱讀投影**。specs 一變就重跑一次 `dflow render` 即刷新（每次執行都是全量重建）。輸出目錄由 render 管理——以 `.dflow-render-manifest.json` 記帳，來源刪除 / 改名後重跑會清掉對應的舊 HTML，非 render 產生的檔案永不會被動到——屬可重生成的衍生物，建議加進 `.gitignore`：
+
+```gitignore
+dflow-specs-html/
+```
+
+註：render 將 specs 內的行內 HTML（`<br>` 等）原樣輸出、不做 sanitize——它設計上只渲染你自己專案的 specs（trusted source），不要拿它渲染來路不明的 Markdown。
+
 ## 專案模式
 
 | 模式 | 何時用 | 主要產出 |
@@ -190,14 +219,16 @@ 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 時，
 才會改寫 fallback merge snippet 到 `dflow/specs/shared/`。專案指南保持單一
 source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。
 
-之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim；若需要 Claude / Copilot 的工具原生命令入口，改用 `dflow configure-agents --command-adapters`；若要自然語言自動觸發（為 Claude Code、Codex 與 GitHub Copilot 投影專案層 skill），改用 `dflow configure-agents --skills`。
+之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim——它會對新選且尚無 skill 的工具問預設 Y 的安裝問句（非互動直接預設裝），自動觸發不會漏；若需要 Claude / Copilot 的工具原生命令入口，改用 `dflow configure-agents --command-adapters`；要強制重生成所有選定工具的 skill（例如升級 Dflow 後刷新），用 `dflow configure-agents --skills`。
 
 ### 產生物的版控政策（建議預設）
 
@@ -212,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 指南：
 
@@ -310,11 +341,10 @@ Dflow 把 DDD 當成規格背後的語意結構：ubiquitous language 讓命名
 | 路徑 | 用途 |
 |---|---|
 | `bin/` | CLI 進入點 |
-| `lib/` | Init runtime 實作 |
-| `templates/` | init 指令複製的檔案 |
+| `lib/` | CLI runtime 實作（init / configure-agents / doctor / render） |
+| `templates/` | workflow 內容唯一來源；`dflow init` / `dflow configure-agents` 由此投影到你的專案 |
 | `test/` | 產出物的 smoke test |
 | `tutorial/` | 引導式學習劇情與預期產出 |
-| `sdd-ddd-*-skill/` | AI 程式設計助理消化的 workflow 來源材料 |
 
 ## 貢獻與發布
 
@@ -322,19 +352,21 @@ issue 與 pull request 指引見 [CONTRIBUTING.md](CONTRIBUTING.md)。Pull reque
 
 ## 狀態
 
-Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.10.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 的區塊自動注入、零手動合併
-- 三家原生 project-level skill（Claude / Codex / GitHub Copilot），共用 agentskills.io 開放標準、支援自然語言自動觸發（Copilot CLI 仍需先打 `/dflow` 喚起）
-- 選配工具原生命令入口（`--command-adapters`）與自動觸發 skill（`--skills`）
-- AI agent 可讀的 SDD/DDD 指引
-- `dflow doctor` 唯讀專案健康檢查
+- 升級時 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` 唯讀專案健康檢查，含升級 drift 偵測（版本行、政策格式、guide 凍結與 dangling 參照、starter 漂移、模板形狀；0.14）
 - 公開 onboarding：evaluator 指南，Claude Code / Codex CLI / GitHub Copilot 的 per-tool walkthrough
 - 僅驗證的 CI workflow（不執行 publish）
 
-GitHub 上的 source 可能包含 `0.10.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
+GitHub 上的 source 可能包含 `0.14.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 授權
 

package/TEMPLATE-COVERAGE.md

@@ -25,11 +25,12 @@ The matrix lists Brownfield / Greenfield logical template parity so reviewers ca
 | ADR guide | `dflow/specs/architecture/decisions/README.md` | n/a | `scaffolding/architecture-decisions-README.md` | Greenfield only | Brownfield not applicable | - |
 | Project AI guide | `dflow/specs/shared/AI-AGENT-GUIDE.md` when at least one AI agent is selected during init | `scaffolding/AI-AGENT-GUIDE.md` | `scaffolding/AI-AGENT-GUIDE.md` | Same canonical tool-neutral workflow guide and source-of-truth pointers | Track-specific seeded values and available source-of-truth paths may differ | - |
 | AI tool shims | `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, or merge snippets under `dflow/specs/shared/` | generated by CLI | generated by CLI | Thin files must point back to `dflow/specs/shared/AI-AGENT-GUIDE.md`; existing files are not overwritten | Tool-specific import hints differ | - |
+| Project-level skill | `.claude/skills/dflow/SKILL.md`, `.agents/skills/dflow/SKILL.md`, `.github/skills/dflow/SKILL.md` — installed by default: init asks an agent-gated default-yes question on TTY (non-TTY installs without prompting); `configure-agents` asks the same question for newly selected agents without a skill; `--skills` force-regenerates | generated by CLI from `templates/common/skill/SKILL.md` | generated by CLI from `templates/common/skill/SKILL.md` | Single edition-neutral canonical source; all tool copies byte-identical; non-Dflow files at those paths are never overwritten | Tool path differs only | - |
 
 ## 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.