dflow-sdd-ddd 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -6,6 +6,133 @@
 
 ---
 
+## 0.13.0 — 2026-07-10 — dflow render（specs 人讀化）+ init 預設安裝 skill（day-one 自動觸發）
+
+**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 兩側）。
+
+### 升級提醒
+
+- **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（模型修正判準）
+
+本版兩條主線：
+
+1. **DDD 指引優化線收官**（070 / 071）——modeling guide 補上模型生命週期的最後兩塊：跨 Aggregate 多步驟流程的協調與補償邏輯住哪（Long-Running Processes），以及既有模型何時該被重審（Revising an Established Model）。至此生命週期閉環：形成（061 萌芽）→ 使用 → 漂移偵測（verify）→ 重審（071）。
+2. **Workflow 收尾與連續性**（068 / 069）——finish-feature 收尾產物守門 + 跨分支 / 跨 session 的在途工作可見性。
+
+### 新功能 / 行為改善（DDD 建模指引）
+
+- **Long-Running Processes（長時流程）**（PROPOSAL-070）：guide 新段——判準先行（「後面失敗需要撤銷前面 → 你要的是 process，不是 event chain」+ 訊號清單與 fire-and-forget 負向守句）、三階梯（owning aggregate status 欄位 → 專責 process aggregate → workflow framework = ADR 決策，比照 outbox / Event Sourcing 防呆先例）、補償 BR 化（補償是新的 domain fact，非 rollback）、deadline 分層（偵測是排程、決策是 domain 規則）。同檔補 Pattern Selection flowchart 與 Domain Services 的 stateful-process 守句、Common Mistakes #11（補償邏輯散落 handler）；greenfield `events.md` 模板加指路一句。
+- **Revising an Established Model（重審既有模型）**（PROPOSAL-071）：guide 新段——重讀規則（擴充既有 Aggregate 前重讀其 Design Decisions 與再評估條件）、六個「模型在抵抗」訊號（生命週期必填欄位 nullable 化、判別欄增生、同軸第 3+ 業務分支、術語加限定詞、再評估條件命中、跨 instance 交易壓力）+ 無界集合 cross-ref、兩階梯（spec 內具名記錄「照舊 / 拆分 / 改名 + 理由」→ 修正當獨立變更走 T1）、雙反空轉守句（訊號是觸發器不是排程；觸發的是重審不是重設計）。Design Questions 加第 7 問（把再評估條件寫進 worksheet）、Common Mistakes #12；兩軌 new-feature / modify-existing flow 在 Aggregate 歸屬時刻加完整重讀掛鉤（brownfield 與 061 萌芽判準成對）、兩軌 new-phase 加一句指路；`aggregate-design.md` 模板提示再評估條件。
+
+### Workflow 強化
+
+- **finish-feature 收尾完整性守門**（PROPOSAL-068）：closeout 產物順序重排與雙驗證——closeout 列先寫（明文無 hash 例外）→ 整目錄 `git add` → commit → `git show HEAD:` 單 blob 同時驗 status 與 closeout 列，gate 以驗證通過為準；lightweight / BUG spec 驗證補進 Step 1；選配 `Dflow-Checkpoint` trailer 與 checkpoint 帳原則明文化（dist issue #5 的 skill 面收斂）。
+- **跨分支 / 跨 session 連續性 Phase 1**（PROPOSAL-069）：`_index.md` Resume Pointer 加持久化 workflow cursor（Active Workflow / Current Step / Gates Passed / Awaiting；宣告與推導證據交叉、證據優先）；`/dflow:status` 改兩段式——在途總覽（本分支 active features + 跨分支 git 掃描分類）+ 當前 feature 細節；intake 重疊掃描（dist issue #4 部分收）。
+
+### 清理 / 修正
+
+- **skill source 舊制 ID 與範例正確性**（PROPOSAL-067）：flow / 模板殘留的 pre-SPEC-ID 舊制全面換為 SPEC-format（frontmatter、branch 命名、範例 ID）、greenfield trunk Hotfixes 依 severity 雙軌命名、guide 內 `DateRange` 範例改合法 C#。
+- `scripts/check-cross-refs.mjs` Windows 路徑 bug 修正（dev-only，不影響套件使用者）。
+
+### 升級提醒
+
+- 既有專案重跑 `dflow configure-agents` 後，bundle 內 `ddd-modeling-guide.md` 取得兩個新段落（Long-Running Processes、Revising an Established Model），六個 flow 檔取得既有模型重讀掛鉤，`aggregate-design.md` / `events.md` 模板取得新提示句。
+
+### 驗證
+
+- P-067〜071 全程 proposal-stage + implementation-stage cross-model review 收斂（各案 1〜3 輪迭代至 zero findings）；cold-eye gate 依風險分級 skip（純散文、不動 runtime，user 逐案核可）。
+- **P-071 為證據驅動成案**：sim-test R4（seeded 既有專案 + 事前登錄 per-signal rubric）判定「AI 不回頭質疑既有模型決策」盲區成立（H1）後才寫指引；P-070 於同一 R4 中獲落地當日後驗（dev session 主動引用並正確應用其負向守句）。
+- `npm test` + `scripts/check-repo-consistency.sh`（含 cross-refs + source↔mirror diff + `npm pack --dry-run`）全綠。
+
+---
+
 ## 0.11.0 — 2026-06-27 — DDD 指引深化 + pre-V1 退役 + docs 刷新
 
 **Proposals**：PROPOSAL-059（modeling-guide 盲區補強）、PROPOSAL-060（Subdomain 分類）、PROPOSAL-061（Brownfield aggregate 萌芽判準）、PROPOSAL-062（戰術補遺）、PROPOSAL-064（Brownfield modeling-guide reachability）、PROPOSAL-065（檢查機械化）、PROPOSAL-066（context-map 語彙補完）、PROPOSAL-063（退役 pre-V1 migration story）

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 |
@@ -231,10 +294,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)
 
@@ -380,7 +445,7 @@ 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. |
+| `lib/` | CLI runtime implementation (init / configure-agents / doctor / render). |
 | `templates/` | Files copied by the init command. |
 | `test/` | Smoke tests for generated output. |
 | `tutorial/` | Guided learning scenarios and expected outputs. |
@@ -397,19 +462,20 @@ 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.13.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
+- 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
 - 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.13.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。
+
 ## 專案模式
 
 | 模式 | 何時用 | 主要產出 |
@@ -197,7 +226,7 @@ Dflow 也會為你的 AI 程式設計助理建立或更新專案指示檔；確
 才會改寫 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`。
 
 ### 產生物的版控政策（建議預設）
 
@@ -310,7 +339,7 @@ Dflow 把 DDD 當成規格背後的語意結構：ubiquitous language 讓命名
 | 路徑 | 用途 |
 |---|---|
 | `bin/` | CLI 進入點 |
-| `lib/` | Init runtime 實作 |
+| `lib/` | CLI runtime 實作（init / configure-agents / doctor / render） |
 | `templates/` | init 指令複製的檔案 |
 | `test/` | 產出物的 smoke test |
 | `tutorial/` | 引導式學習劇情與預期產出 |
@@ -322,19 +351,20 @@ issue 與 pull request 指引見 [CONTRIBUTING.md](CONTRIBUTING.md)。Pull reque
 
 ## 狀態
 
-Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.10.0`，涵蓋：
+Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.13.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 指引
+- 三家原生 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` 唯讀專案健康檢查
 - 公開 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.13.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 授權
 

package/TEMPLATE-COVERAGE.md

@@ -25,6 +25,7 @@ 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
 

package/bin/dflow.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const { runConfigureAgents, runDoctor, runInit } = require('../lib/init');
+const { runRender } = require('../lib/render');
 const pkg = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -12,6 +13,7 @@ Usage:
   dflow init              Initialize Dflow specs in the current project
   dflow configure-agents  Add or update AI agent instruction shims
   dflow doctor            Read-only project health check
+  dflow render            Render the specs Markdown tree to browsable HTML
   dflow --help            Show this help
   dflow --version         Show the CLI version
 `);
@@ -24,7 +26,11 @@ function printInitHelp() {
 Initializes Dflow project specs under dflow/specs/.
 The command prompts for project type, tech stack, migration context, prose
 language, Git policy, AI commit marker, optional starter files, and AI coding
-agents before showing a full file preview.
+agents, then — when agents were selected on an interactive terminal — whether
+to install the project-level Dflow skill (default yes), before showing a full
+file preview. Non-interactive runs never read an extra stdin answer for the
+skill question: existing scripted answer sequences run unchanged, and the
+skill is installed by default for the selected agents.
 `);
 }
 
@@ -39,7 +45,43 @@ dflow/specs/shared/AI-AGENT-GUIDE.md file.
 
 Options:
   --command-adapters  Also generate tool-native thin wrappers for supported tools.
-  --skills            Also generate project-level skill adapters for supported tools (Claude Code, Codex, and GitHub Copilot), restoring natural-language auto-trigger.
+  --skills            Regenerate project-level skill adapters for all selected supported tools (Claude Code, Codex, and GitHub Copilot), restoring natural-language auto-trigger.
+
+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.
+`);
+}
+
+function printRenderHelp() {
+  process.stdout.write(`Usage:
+  dflow render [--src <dir>] [--out <dir>] [--title <text>]
+
+Renders the Markdown specs tree into a mirrored static HTML tree for human
+reading (record tables become cards, AI markers become badges), plus an
+index.html file tree at the output root. Open index.html directly in a
+browser; file:// works, no server needed.
+
+Markdown stays the AI-facing source of truth. Re-run this command whenever
+the sources change; every run is a full rebuild.
+
+Options:
+  --src <dir>     Specs root to render (default: dflow/specs)
+  --out <dir>     Output directory (default: dflow-specs-html)
+  --title <text>  index.html page title (default: "dflow specs")
+
+The output directory is owned by dflow render: every rendered file embeds a
+generated-by marker, and a .dflow-render-manifest.json ledger tracks the
+mirror. Files whose sources were deleted or renamed are cleaned up on the
+next run — a file is deleted only when it is both ledger-listed and
+marker-verified, and an existing file at a path being rendered is
+overwritten only when it is marker-verified (that is how the partial
+outputs of an interrupted run converge on the next run). render refuses a
+non-empty directory without a ledger, anything it never creates (symlinks,
+junctions, hardlinked files), unrecognized files at paths it must write,
+and source trees whose outputs would collide. render only writes --out; it
+never modifies --src.
 `);
 }
 
@@ -111,6 +153,20 @@ async function main() {
     });
   }
 
+  if (args[0] === 'render') {
+    if (args.length > 1 && (args[1] === '--help' || args[1] === '-h')) {
+      printRenderHelp();
+      return 0;
+    }
+
+    return await runRender({
+      cwd: process.cwd(),
+      args: args.slice(1),
+      stdout: process.stdout,
+      stderr: process.stderr
+    });
+  }
+
   if (args[0] === 'doctor') {
     if (args.length > 1 && (args[1] === '--help' || args[1] === '-h')) {
       printDoctorHelp();

package/docs/evaluating-dflow.en.md

@@ -46,6 +46,12 @@ in your project's `dflow/specs/` directory and AI instruction files.
   the tools you select (e.g., `CLAUDE.md`, `AGENTS.md`,
   `.github/copilot-instructions.md`). Each points the tool to the canonical
   guide and workflow bundle.
+- The project-level skill for the selected tools (`.claude/skills/dflow/` /
+  `.agents/skills/dflow/` / `.github/skills/dflow/`), installed **by default**
+  — the source of natural-language auto-trigger. Interactive runs ask one
+  `(Y/n)` question (Enter = install); non-interactive runs never read an extra
+  answer and install by default. If you answer `n`, add it later with
+  `dflow configure-agents --skills`.
 
 `init` does **not**:
 
@@ -76,7 +82,8 @@ and router; executable workflow steps live in the vendored bundle at
 - Multiple tools can be active in the same project without diverging
   workflow rules.
 - Switching or adding tools later does not require re-running `init`; run
-  `dflow configure-agents` to add another shim, or
+  `dflow configure-agents` to add another shim (it asks the same default-yes
+  skill question for newly selected tools that have no skill yet), or
   `dflow configure-agents --command-adapters` to opt in to tool-native command
   entries.
 - The guide and workflow bundle together are the authoritative sources for
@@ -154,6 +161,13 @@ real codebase.
    `dflow/specs/shared/_conventions.md`, and
    `dflow/specs/shared/AI-AGENT-GUIDE.md` to see the shape.
 
+   You can also run `dflow render` to project the specs tree into
+   human-readable HTML (output in `dflow-specs-html/`; open `index.html` to
+   browse). A freshly initialized project is mostly starter templates; for a
+   closer-to-real rendering, clone this repo and render the tutorial's worked
+   specs: `dflow render --src tutorial/01-greenfield/outputs/dflow/specs
+   --out <any output dir>`.
+
 4. **Read one tutorial walk-through** to see what a real feature flow looks
    like end to end:
    - Greenfield: [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)
@@ -177,7 +191,12 @@ against.
 
 Dflow is designed for low cost to try and low cost to leave:
 
-- Nothing depends on the `dflow-sdd-ddd` CLI being installed after `init`.
+- After `init`, the specs and workflow documents themselves do not depend on
+  the `dflow-sdd-ddd` CLI being installed — they are plain Markdown committed
+  into your repo, readable from any clone. The CLI is only needed for three
+  things: upgrade re-projection (`configure-agents`), health checks
+  (`doctor`), and rendering the specs as human-readable HTML (`dflow render`,
+  see playbook step 3 above).
 - The generated files are plain Markdown; remove Dflow from a project with
   `rm -rf dflow/` plus deleting the AI agent shim files you no longer want.
 - If an existing project instruction file (e.g., a pre-existing `CLAUDE.md`)

package/docs/evaluating-dflow.md

@@ -33,6 +33,10 @@ Dflow 是 Markdown-based 的 workflow 材料加上一個 scaffolding CLI。它
   且可達的，任何 clone 都不需要 Dflow source 或 package 在本機安裝。
 - 你所選工具的 AI 指示檔或既有檔案中的 marked Dflow block（例如 `CLAUDE.md`、`AGENTS.md`、`.github/copilot-instructions.md`）。
   每個都把工具指向 canonical 指南與 workflow bundle。
+- 選定工具的 project-level skill（`.claude/skills/dflow/` / `.agents/skills/dflow/` /
+  `.github/skills/dflow/`），**預設安裝**——自然語言自動觸發的來源。互動模式會問
+  一題 `(Y/n)`（Enter = 裝）；非互動不多讀答案、直接預設裝。答 `n` 可之後用
+  `dflow configure-agents --skills` 補裝。
 
 `init` **不會**：
 
@@ -58,8 +62,9 @@ Dflow 支援多種 AI 程式設計助理。跑完 `init` 後，你選取一個
 與 `dflow/specs/shared/dflow-workflows/`（可執行步驟定義）。實際意義：
 
 - 同一個專案可以同時啟用多個工具，而不會有 workflow 規則分歧。
-- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim，
-  或用 `dflow configure-agents --command-adapters` opt in 工具原生命令入口。
+- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim
+  （對新選且尚無 skill 的工具會問同一題預設 Y 的 skill 安裝問句），或用
+  `dflow configure-agents --command-adapters` opt in 工具原生命令入口。
 - 指南與 workflow bundle 共同成為 Dflow workflow 行為的權威來源；兩者都是純 Markdown
   已 commit 進 repo，任何 clone 均可直接讀取。
 
@@ -123,6 +128,12 @@ repo 上下文的 AI 助理一起運作。
 
    開啟 `dflow/specs/shared/_overview.md`、`dflow/specs/shared/_conventions.md`、以及 `dflow/specs/shared/AI-AGENT-GUIDE.md` 看看整體架構。
 
+   也可以跑 `dflow render` 把 specs 樹轉成人類閱讀的 HTML（輸出
+   `dflow-specs-html/`，開 `index.html` 即可瀏覽）。剛 init 完的 specs 多是
+   起始模板；要看接近實戰的渲染效果，clone 本 repo 後對 tutorial 的規格範例
+   跑 `dflow render --src tutorial/01-greenfield/outputs/dflow/specs --out
+   <任意輸出目錄>`。
+
 4. **閱讀一份 tutorial walk-through** 以了解完整的 feature flow：
    - Greenfield：[`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)
    - Brownfield：[`tutorial/02-brownfield/`](../tutorial/02-brownfield/walkthrough-00-setup.md)
@@ -137,7 +148,10 @@ repo 上下文的 AI 助理一起運作。
 
 Dflow 的設計讓試用成本低、退出成本也低：
 
-- `init` 完成後，你的專案不依賴已安裝的 `dflow-sdd-ddd` CLI。
+- `init` 完成後，specs 與 workflow 文件本身不依賴已安裝的 `dflow-sdd-ddd`
+  CLI——它們是已 commit 進 repo 的純 Markdown，任何 clone 都讀得到。CLI 只在
+  三種時機用到：升級重投影（`configure-agents`）、健康檢查（`doctor`）、以及
+  把 specs 轉成人類閱讀的 HTML（`dflow render`，見上方 playbook 第 3 步）。
 - 產生的檔案都是純 Markdown；用 `rm -rf dflow/` 加上刪除你不再需要的 AI 指示 shim 檔案，即可從專案中移除 Dflow。
 - 既有的專案指示檔（例如原本就存在的 `CLAUDE.md`）若被加入 marked Dflow
   block，刪除該 block 即可復原；但之後再跑 `init` / `configure-agents`