dflow-sdd-ddd 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -6,6 +6,106 @@
 
 ---
 
+## 0.10.0 — 2026-06-06 — agentskills 標準三家觸發 parity、既有 agent 檔自動注入、投影內容保全與清理
+
+**Proposals**：PROPOSAL-049（feature-slice 使用面語意體檢）、PROPOSAL-050（還原 041 雙軌合一丟失的 skill 內容進 AI-AGENT-GUIDE）、PROPOSAL-051（退役 `templates/CLAUDE.md`）、PROPOSAL-052（bundle stale-removal 推廣到同-edition）、PROPOSAL-054（既有 agent 檔 Dflow 墊片 auto-inject）、PROPOSAL-056（Codex 專案層 skill `--skills` parity）、PROPOSAL-057（以 agentskills.io 標準為三家共同自動觸發層；Phase 2）
+
+本版兩條主線：
+
+1. **入口層標準化 + 降低採用摩擦**（054 / 056 / 057 + Copilot 指南）—— 三家（Claude / Codex / Copilot）以 agentskills.io 開放標準取得 project-level skill 投影 parity（自然語言觸發；Copilot CLI 仍需 `/dflow` 喚起）、既有 agent 檔零手動合併即接上、Claude shim 瘦身、Copilot 跨介面用法講清楚。
+2. **投影內容保全與清理**（049 / 050 / 051 / 052）—— 一輪 feature-by-feature 語意體檢補回 041 雙軌合一時孤兒化的 canonical 內容、退役 legacy 範本、把 bundle 退役檔清除推廣到最常見的同-edition 升級。
+
+### 新功能 / 行為改善
+
+- **`dflow configure-agents --skills` 三家專案層 skill parity（Codex 補自動觸發、Copilot 補原生 skill）**（PROPOSAL-056 + #4 un-defer）：`--skills` 從「只投 Claude、寫死單一路徑」一般化為「把同一份工具中立 thin skill（`templates/common/skill/SKILL.md`）投影到每個被選工具各自的 project-level skill 路徑」。Claude 維持 `.claude/skills/dflow/SKILL.md`；**Codex 新增 `.agents/skills/dflow/SKILL.md`**，找回 Codex 的自然語言自動觸發（先前只有手動命令 / 文字 trigger）；**GitHub Copilot 新增 `.github/skills/dflow/SKILL.md`**（#4 un-defer：spike 確認 Copilot 從自己原生 `.github/skills/` 探索成立、即使移除 `.claude`/`.agents` 跨讀路徑也成立——**VS Code Chat 自然語言自動觸發、Copilot CLI 仍需 `/dflow` 手動喚起**）。Copilot 也會跨讀 `.claude`/`.agents`；Dflow 產生的各份逐字相同，但若該路徑已有非 Dflow 的同名 skill，Dflow 會保留不覆寫、可能內容不同（移除或改名即可避免同名重複）。依據：Claude / Codex / Copilot 已收斂於 agentskills.io 開放標準（皆以 `SKILL.md` 為入口、`name`/`description` frontmatter、project-level 探索、description 驅動自動觸發）。
+
+- **既有 agent 檔的 Dflow 墊片 auto-inject（三工具統一）**（PROPOSAL-054）：當使用者已有自己的根 agent 檔（Claude `CLAUDE.md`、Codex `AGENTS.md`、Copilot `.github/copilot-instructions.md`）且尚未引用 guide，`init` / `configure-agents` 不再預設「丟一個 snippet 檔、Notes 一行請你手動合併」，改為**附加一塊帶 `<!-- dflow-generated: agent-shim START/END -->` 標記的 Dflow 區塊**（呈現為確認預覽裡的一般項目），重跑時**原地抽換**該區塊（idempotent）。snippet + 警告降為 fallback，只在標記殘缺 / 重複 / 顛倒等無法安全注入時才用；並補上先前缺的對稱警告（最常見路徑反而 signpost 最弱的洞）。指令只能以文字寫進 `AGENTS.md` 的 Codex 受惠最大。
+
+- **bundle 退役檔在同-edition 升級也自動清除**（PROPOSAL-052）：`configure-agents` 的 bundle stale-removal 原本只在 **edition 改變**時觸發；現在推廣為「依 manifest diff 清除『舊 manifest 有、當前 bundle 已無』的退役檔」，涵蓋最常見的**同-edition 重跑升級**。一併補三道 projection-cleanup 硬化：current-bundle 非空 guard（防 bundle 掃出空集合時誤刪整包、砍掉 `/dflow:*` 可達性）、壞 manifest 區分 ENOENT vs parse/IO error（後者至少 warn，不再靜默跳過）、待刪檔措辭從硬編「stale adapter / edition changed」修正為通用。**直接受惠**：051 退役 `templates/CLAUDE.md` 後既有同-edition 專案殘留的 vendored copy，重跑 `dflow configure-agents` 即被清掉。
+
+- **Claude shim 瘦身為薄指標**（PROPOSAL-057 Phase 2）：`init` 生成的根 `CLAUDE.md` 墊片不再用 `@import` 把整份 `AI-AGENT-GUIDE.md`（~5k tokens）每個 session 強制載入，改為路徑無關的薄 awareness，並把「讀 guide」scoping 到 spec-impacting work（對齊 progressive disclosure；workflow 步驟本就按需載入）。
+
+- **skill 自動觸發 recall 強化**（PROPOSAL-057 Phase 2）：`templates/common/skill/SKILL.md` 的 `description` 補上間接觸發語（不點命令名的自然語句也能觸發），修掉先前「最間接語句 recall 較弱」的弱點；同時收斂在 **Codex 的 1024 字元上限**內（986 chars），並加 `test/registry-parity.mjs` 護欄斷言 folded description ≤ 1024 防回歸。觸發契約維持 suggest-and-wait（建議命令、等確認，不自動跑完整個 workflow）。
+
+### 文件
+
+- **GitHub Copilot 指南分介面重寫**（copilot-cmd-surface，2026-06-05 實測）：`docs/using-with-github-copilot.md` + `.en.md` 把 Copilot 用法分為 **VS Code Copilot Chat** 與 **GitHub Copilot CLI** 兩節，各自講自動觸發有無、命令能不能用、正確語法 —— VS Code Chat 自然語言自動觸發 + `/dflow-<id>`（連字號，需 `--command-adapters`）；Copilot CLI 無自動觸發、先打 `/dflow` 手動喚起 skill、無 per-id 命令（`.github/prompts/` CLI 不讀取）。冒號形式 `/dflow:<id>` 釐清為 canonical / Claude·Codex 命令語法，在 Copilot 只能當文字稱呼。移除舊的「chat 文字可直接說 canonical `/dflow:<id>`」易誤導措辭。雙語 parity。
+
+### 投影內容保全（PROPOSAL-049 / 050）
+
+- **feature-slice 使用面語意體檢**（PROPOSAL-049）：對「使用 Dflow 時實際會碰到的範圍」（CLI runtime + init 投影的 bundle / adapter + 雙軌 skill source）做一輪 feature-by-feature 人讀語意體檢，補 047（首次 implementation-stage cross-model review）之前 ship、未過該層 review 的盲區。修掉的 drift 含：`modify-existing-flow` 等殘留「the developer commits」的 pre-047 行為者口吻、Greenfield context-definition 路徑兩軌 parity、`/dflow:verify` scope over-claim、`last-updated` 權威歸 `rules.md` 等。純語意 / 結構修正，grep 擋不住。
+
+- **還原 041 合一丟失的 canonical 內容**（PROPOSAL-050）：041 把兩份 per-edition `SKILL.md` 合一成 35 行薄殼時，數個被各 flow 以 `see SKILL.md § …` 指向的 workflow-protocol 段變成**懸空 ref**。本版把這些段（Workflow Transparency〔Auto-Trigger Safety Net / Three-Tier Transparency / Confirmation Signals NL↔Command / Completion Checklist〕、Ceremony Scaling 完整 T1/T2/T3 表、Guiding Questions by Activity、Project Structure）還原進**兩軌 `AI-AGENT-GUIDE.md`**（runtime 面），並 repoint ~15 處 ref；另還原 conservation audit 抓到的 silent-drop（Brownfield 不適用排除條款、三項可攜資產立論、非指令 decision routing、完成清單 skip-detection guard）。使用者專案的 canonical 指南因此恢復完整、ref 不再撲空。
+
+### Migration / 升級提醒
+
+- **`templates/CLAUDE.md` 退役（移除一個 vendored generated 檔）**（PROPOSAL-051）：刪除 Greenfield / Brownfield 各一份 source + mirror 共 4 檔（legacy full-layout 範例）。它**不是** `init` 來源（根 `CLAUDE.md` 由 `lib/init.js` 程式化生成薄殼），canonical 內容（decision routing / Ceremony 表 / per-flow steps）已於 050 全數移進 `AI-AGENT-GUIDE.md` + bundle。**對既有專案的影響**：先前以同-edition 跑過的專案，其 vendored copy `dflow/specs/shared/dflow-workflows/templates/CLAUDE.md` 會留為**無害殘檔**（帶 generated marker、不被任何 flow 消費）；**重跑 `dflow configure-agents` 即自動清除**（PROPOSAL-052 的同-edition stale-removal）。npm tarball 因此縮減一個 generated file。
+
+- **Claude shim 形狀改變**（PROPOSAL-057）：既有專案的根 `CLAUDE.md` 仍可用；若要拿到瘦身後的薄指標版，重跑 `dflow init` / `dflow configure-agents` 即原地刷新該 Dflow 區塊。
+
+### 維護者工具 / 測試（不影響套件使用者）
+
+- **cross-ref resolver guard**（PROPOSAL-055，dev-only）：新增 `scripts/check-cross-refs.mjs`（納入 `check-repo-consistency.sh`），把「文件 `§` / 檔名 / 路徑 ref 解不解得開」從一次性人工 grep 固化為常駐檢查；namespace-aware（限 public source + governance 範圍、跳過 history 與 `{token}` 佔位、§/anchor longest-prefix）。`scripts/` 不投影 dist、不進 tarball。
+- **registry-parity 測試**（PROPOSAL-053，dev-only）：新增 `test/registry-parity.mjs`，斷言 11 個 `/dflow:*` 指令表跨 surface / 雙軌一致（F-02 安全網）；後並加 057 的 folded description ≤ 1024 斷言。
+- **`test/agent-inject.mjs`**（PROPOSAL-054）：新增既有 agent 檔 auto-inject 的注入 / idempotent 抽換 / fallback 矩陣覆蓋。
+- `test/smoke.mjs`：擴充 054 auto-inject、056 `--skills` 各家路徑、052 同-edition stale-removal 等斷言。
+
+### 驗證
+
+- `npm test`（`smoke.mjs` + `registry-parity.mjs` + `agent-inject.mjs` 全綠）
+- `scripts/check-repo-consistency.sh`（含 `check-cross-refs.mjs` + registry parity + source↔mirror diff + `npm pack --dry-run` + `git diff --check`）pass、0 error
+- `scripts/export-dist.sh --dry-run`：dev / dist 已同步、無 drift
+- 049–057 各 proposal 實作均經 implementation-stage cross-model review 收斂 approve（見各 closeout 紀錄）
+
+---
+
+## 0.9.0 — 2026-05-28 — 執行當下對齊：feedback 逐欄產出、Codex trigger 注入、commit checkpoints + branch gate（含 breaking changes）
+
+**Proposals**：PROPOSAL-048（feedback 輸出對齊目標 issue 表單）、PROPOSAL-046（Codex command-trigger 注入既有 AGENTS.md shim）、PROPOSAL-047（commit checkpoints、branch lifecycle 強制、AI commit 政策翻轉、init Git policy 升必選）
+
+三者共享同一條 design line：**AI 在執行當下直接對齊目標狀態**（目標 issue schema / 目標檔案 / 團隊 Git policy 與良好開發習慣），取代「先產通用版 → 使用者事後手動翻譯 / 補做」的兩層結構。
+
+### ⚠️ Breaking changes（PROPOSAL-047）
+
+1. **AI commit 政策翻轉**：Dflow 既有原則「AI 不 commit、開發者自己 commit」改為「**AI 在生命週期 checkpoint 主動提議 commit，使用者隨時可拒絕（Y / N）**」。AI commit 使用開發者 git identity，標記方式由 init 選擇。翻轉後仍守「不讓 AI 越權」精神——使用者可拒絕、merge / push / PR 仍需明確同意、政策團隊擁有。牽動 `finish-feature-flow.md`、`git-integration.md`、各 flow 與 `Git-principles-*.md` 多檔。
+
+2. **init Git policy 升為必選題**：0.9.0 起 `dflow init` 把 Git policy（GitFlow / Trunk 二選一）改為**必選**，不再是 optional starter file。沒選政策的團隊用不上 047 的 branch gate / commit checkpoint；必選排除此失效情境，且兩個選項對最輕量採用者都不過重（Trunk = GitHub Flow 短命 branch、merge 最自由）。
+
+3. **init 新增 AI commit marker 必問**：None（預設）/ Co-Authored-By `dflow-ai <noreply@dflow.local>` / `[ai-assisted]` prefix 三選一，寫入 `dflow/specs/shared/_conventions.md` 的 `## AI Commit Policy` 段；runtime 不再重複問。
+
+### Migration（0.8.0 → 0.9.0）
+
+既有 0.8.0 專案需補（沒有既有 dflow 專案的新使用者不受影響，首次 `dflow init` 即為 0.9.0 行為）：
+
+- `dflow/specs/shared/Git-principles-{gitflow|trunk}.md`（擇一）——若 0.8.0 init 時未選 git-principles starter。
+- `dflow/specs/shared/_conventions.md` 補 `## Git Policy` 與 `## AI Commit Policy` 兩段（記錄所選 policy 與 marker 模式）。
+
+可手動補，或請 AI 依本 release note 協助補入。Dflow **不提供自動 migration 工具**（早期、採用者少）。
+
+### 📜 授權變更（License Change）
+
+從本 release 起 **`dflow-sdd-ddd` 改採 [AGPL-3.0-or-later](LICENSE)**（原 MIT）。npm 上已發布的 0.8.0 永遠保留 MIT（無法追溯）；AGPL 從 0.9.0 起對新發布生效。Copyright holder 明確化為「Will Chuang」。LICENSE 採 FSF gnu.org 官方 AGPL-3.0 全文。
+
+對一般使用者（學術圈、個人工程師、團隊內部以 dflow 引導開發）**無影響**——你寫的應用程式碼不受 AGPL 約束。AGPL 的 copyleft 約束的是**對 dflow skill / template 本身的修改與再散布**（含 SaaS 部署），目的是擋住「叫 AI 直接複製 skill 內容塞進私有專案規格」這類默默吸收的使用方式。
+
+### 新功能 / 行為改善
+
+- **feedback 輸出逐欄對齊目標 issue 表單**（PROPOSAL-048）：`/dflow:report-dflow-feedback` 從「通用 Markdown 草稿 + 後置 Suggested Issue Body」改為**直接產出 schema-aligned 逐欄填寫稿**，使用者零翻譯逐塊貼上。schema 來源 priority chain（本地 `.github/ISSUE_TEMPLATE/*.yml` → bundled field map → generic fallback）；涵蓋 GitHub Issue Forms 全欄位類型（input / textarea / dropdown / checkboxes / markdown / upload + attributes）、動態 fence escape、submitter 提交前自查 checklist。bundled field map 內嵌 4 份上游 issue form（Bug / Workflow change / Documentation / Question）。
+
+- **Codex command-trigger 注入既有 AGENTS.md shim**（PROPOSAL-046）：標準兩步 onboarding（`dflow init` → `configure-agents --command-adapters`）下，Codex 的 trigger 段原本必然淪為手動併（side snippet）。現在 `configure-agents` 對「未經改動的 dflow 生成 AGENTS.md」**直接注入帶 marker 的 trigger 段**（零手動合併）；偵測用 normalized exact-template match（容忍 CRLF / IDE reformat、非 raw hash），同機制支援 idempotent re-projection；使用者改過的 AGENTS.md 安全降級為 snippet + warning。對齊既有 `SKILL_ADAPTER_GENERATED_MARKER` precedent。
+
+- **commit checkpoints + branch gate + Checkpoint Log**（PROPOSAL-047）：
+  - 生命週期 milestone 折入既有 Step Gate 的 commit checkpoint（選 Y / N 都記一列到 feature `_index.md` 新增的 **Checkpoint Log** 段）；Tier 決定點數（T1 ×3 / T2 ×2 / T3 ×1）；commit hash 僅在成功後寫入、失敗記 `failed`、不寫假 hash。
+  - **branch gate**：實作前檢查當前是否就在這份工作的 feature branch；不在才提議 create / switch（兩個 policy 都用 feature branch）；override 記入 Checkpoint Log、連 3 次提示 reconfig。判斷只看「在不在對的 feature branch」，不需辨識 base branch。
+  - **finish-feature 拆兩段以支援離線**：Local-closeout gate（驗證 / 封存 / 可選 commit，離線可完成）+ Integration / PR gate（push / merge / PR，需 network；AI 只在使用者明確要求時才 `git push` / `gh pr create`）。
+
+### 維護者工具 / 測試
+
+- `test/smoke.mjs`：新增 046 注入矩陣（pristine 注入 / idempotent re-run / user-modified 降級 / CRLF reformat 仍注入 / 冷門路徑）、047 init 必選題（Git policy 兩分支 + AI commit marker）含 `_conventions.md` 政策段與 `_index.md` Checkpoint Log marker 斷言、048 feedback flow schema-aligned 守衛。
+- `MAINTAINERS.md`：新增「Upstream Issue-Form Snapshot」release-time resync 提醒（048 的內嵌 field map 與 dist issue templates 同步）。
+
+---
+
 ## 0.8.0 — 2026-05-24 — DDD set-based invariant 引導擴充、雙軌 skill 殼合一、user-projected bundle 內容 polish
 
 **Proposals**：PROPOSAL-040（CLI papercuts + 文件補洞）、PROPOSAL-041（C0+C1：configure-agents idempotent bundle re-projection + 雙軌 skill 殼合一）、PROPOSAL-042（ddd-modeling-guide 補 set-based invariants 與 Phase-1 event dispatch 段）、PROPOSAL-044（user-projected bundle 內 maintainer-source path 清除）、PROPOSAL-045（user-projected bundle 內 maintainer-only provenance refs 清除）