dflow-sdd-ddd 0.10.0 → 0.12.0

package/docs/why-dflow.md

@@ -0,0 +1,72 @@
+# 為什麼用 Dflow（即使 AI 已經會 DDD）
+
+> **繁體中文** | [English](why-dflow.en.md)
+
+如果你的直覺是「現在的 AI 已經會 DDD，叫它『用 DDD 建一個 feature』，aggregate、value object、event 都出得來，再加一層 spec-first 工具是不是過度工程？」——這份文件是寫給你的。它不打算說服你，而是把 Dflow 的價值、證據與限制攤平，讓你自己判斷。
+
+## Dflow 是什麼
+
+Dflow 不是教 AI 什麼是 DDD——它是一層 scaffold（鷹架）：強迫 AI 把每個設計決策的取捨完整留檔，並補上「AI 自己補細節時容易漏、而 review 又難一眼看出」的盲區。
+
+把「AI 會 DDD」拆成兩件事，就懂為什麼還需要它：
+
+1. **AI 能不能說出對的 DDD 答案？** 能。模型讀過教科書，aggregate 邊界、不變式、ubiquitous language 都答得出來。
+2. **AI 在你 review 時會不會留下夠完整的紀錄（它考慮過哪些、為何這樣選、哪裡還沒確定）讓你 audit、會不會主動 catch 它自己容易漏的陷阱？** 不一定，要看你怎麼問。
+
+所以真正該比的不是「AI 工具 vs process」，而是：
+
+- **AI alone** 的產出 = AI 知識 × 隱含的 prompt 結構 × 你 review 它的能力
+- **AI + Dflow** 的產出 = AI 知識 × **明確的 elicitation scaffold** × **可審查的決策紀錄（取捨、否決的方案、open questions）** × 你 review 它的能力
+
+差異不是「更聰明的 AI」，是「**更可審查的 AI**」。
+
+## Dflow 的 DDD 引導是「長出來的」，不是抄教科書
+
+Dflow 的價值有一部分在於：它的引導是從真實盲區回灌的，而且補上之後，模型真的會在後續主動沿用。一個具體、可檢查的例子——
+
+**盲區**：模型自己建模時，把「一個充電槍同時只能有一筆進行中 session」這條唯一性規則，只用 aggregate 內 `if Status == InUse throw` 的 in-memory check 保護。DDD 教科書角度這是對的，但並發下兩個請求各自讀到 `Available`、各自通過檢查、各自 save → 不變式被破壞（modeling-correct、production-broken）。
+
+**回灌**：把這個盲區寫成一段引導，補進 Dflow 的 `ddd-modeling-guide.md`——「Set-Based / Uniqueness Invariants」：這類「同 X 只能有一筆 active」的規則，無論怎麼切 aggregate，in-memory check 在並發下永遠不夠，要加 DB unique / partial index 或 concurrency token，並把衝突 translate 成 HTTP 409。
+
+**沿用**：換一個 domain（冷鏈感測器「一個 sensor 同時最多掛在一個 carton」，結構平行）、且讓模型不知道自己在被測，它就**主動引用那段**、補上完整三層保護（in-memory guard + concurrency token + DB partial unique index + 409）。
+
+這證明的是一件具體的事：**Dflow 把「AI 自己會漏的盲區」固化成可重用、會被遵循的引導。** 這不是「跑幾次就證明 AI+process 全面勝出」那種大結論（樣本很小）；它是 Dflow 引導迴路有效的證據——**盲區 → 補引導 → 模型沿用**。你也能自己複現（見文末）。
+
+> 補充誠實度：兩次 run 之間 domain 與 framing 也不同，但都不利於「不是引導的功勞」這個反方——兩個 domain 在模型的 pre-training 裡都不是高頻並發設計題材；framing 在第二次更純（不知被測），若它是主因，結果該更差而非更好。把這兩條的可能性壓低後，最能解釋這個翻轉的就剩那段引導在不在。
+
+## 其他幾個「Dflow 強制留檔、AI 自己容易漏」
+
+同一輪觀察裡還看到（每點都是「Dflow 做了什麼 → 沒它會怎樣」）：
+
+- **強迫寫否決理由**：aggregate 設計模板一句 prompt，誘出「選這個邊界 + 理由 + 考慮過哪些替代 + 為何否決」的完整決策段；AI 自己通常只給你一個方案，review 時你無法 audit「它想過 X 嗎」。
+- **Step gate 把決策變成 reviewable moment**：模型在命名、模型 spike 等節點自然停下等確認；AI 自己一路寫到 code、tests 都好了你才有機會 review，這時 aggregate 邊界已經沒有商量空間。
+- **Open Question 留檔給 domain expert**：模型把不確定的點列成 OQ 等人答，而不是「不確定就猜一個合理的」把假設藏進 code。
+- **Ubiquitous language 不漂移**：術語表 + code mapping 讓 spec / model / code 用同一組名詞；AI 自己一段話內就能混用 Sensor / Device / Tracker。
+- **規則可被查詢**：每條 business rule 有 ID、status、所屬 aggregate、behavior 連結；AI 自己把規則散在 prose 裡，「BR-003 影響哪些測試」只能用 grep 推敲。
+
+## 誠實的取捨
+
+不掩蓋限制，反而是這套論點的可信來源：
+
+- **scope**：目前觀察只跑在單一模型 × 幾個中等複雜度 domain × lightweight modeling scope（到領域建模、不含 implementation phase）。implementation 階段的引導是否同樣有效、換不同模型會不會一樣，**未驗**。
+- **先驗**：被測模型本來就對 DDD 有 pre-training 先驗。Dflow 證明的是「能讓『會、但不一定每次仔細想』變成『仔細想』」，**不是**「能讓完全不懂 DDD 的 AI 變會」。
+- **採用即承諾遵循**：Dflow 是 spec-first 工具，只在被遵循時有效；AI 或人故意走偏的情境不在宣稱範圍內。這是工具屬性，不是 bug。
+
+對需要 audit 的場景——醫療、金融、合規、安全敏感、或任何「上線出包代價高 / 個人責任重」的領域——這個 reviewability 差異是 deal-breaker。成本要分兩塊看：**產出** DDD 文件已經不是徒手做 DDD 的高人力年代——AI 幫你生規格、決策紀錄與領域模型，邊際成本主要是多花一些 token 與走一遍流程；而且光是「生成時被領域模型約束」就已讓產出更穩（如上面那個並發盲區），這層就算你沒深讀紀錄也拿得到。Dflow 的 DDD 也刻意務實裁剪（不是學院派全套）、適合一般公司的中型系統，採用門檻不高（不需要團隊先是 DDD 專家）。但要再兌現「可審查」這份價值，得有人實際去 review 那份紀錄——那才是人力與紀律的關鍵成本。所以取捨仍在、值得討論：高風險、需 audit、要長期維護時，這筆投資明顯划算；你不會去 review、失敗成本低、迭代又快時，AI alone 仍可能是更實際的選擇，不是 Dflow 一定贏。
+
+## 自己驗證
+
+不用相信任何說法，自己跑一次（約 10–30 分鐘）：
+
+```bash
+npm install -g dflow-sdd-ddd
+mkdir dflow-test && cd dflow-test
+git init && git commit --allow-empty -m "init"
+dflow init           # 選 greenfield + 你的 AI 工具 + 你的 stack
+```
+
+接著在你的 AI coding agent 裡跑 `/dflow:new-feature`，指派一個含「跨實例唯一」型不變式的 feature，例如「同帳號同時最多一個 active session」。看模型走到領域建模時，會不會寫到「Set-Based / Uniqueness Invariants」段（Dflow 的 `ddd-modeling-guide.md`）、cite 它、並補上 DB unique / partial index + concurrency token + 409。注意：裝最新版能驗證的是「引導在場時模型確實會用它」這一半；「引導不在場時模型會漏」那一半是上面那段在加入引導之前建立的，不是你在最新版上能切換的——最新版一律含這段。
+
+---
+
+Dflow 不宣稱讓 AI 更聰明，它讓 AI 更可審查：規格優先、領域語義顯式化、把決策與否決理由留檔、在實作前約束、完成前驗證漂移（drift）。為什麼領域語義本身在 AI 時代更關鍵，見 [為什麼 AI 時代 DDD 更重要](why-ddd-for-ai.md)。

package/lib/init.js

@@ -26,6 +26,13 @@ const AGENT_SHIM_SECTION_END = '<!-- dflow-generated: agent-shim END -->';
 const WORKFLOW_BUNDLE_DEST = 'dflow/specs/shared/dflow-workflows';
 const WORKFLOW_BUNDLE_MANIFEST_PATH = `${WORKFLOW_BUNDLE_DEST}/.dflow-bundle-manifest.json`;
 const COMMON_SKILL_SOURCE_REL = 'common/skill/SKILL.md';
+// Files the common bundle tree (templates/common/) MUST provide. A missing
+// common file is a broken package, NOT a retired bundle file: without this guard
+// listBundleSourceFiles would return a smaller-but-"valid" set lacking the file,
+// and configure-agents stale-removal would then DELETE the already-installed
+// copy from the user's project (it diffs as "retired"). PROPOSAL-064 fresh-gate
+// finding. Guarded before any stale cleanup / manifest write.
+const REQUIRED_COMMON_BUNDLE_FILES = ['references/ddd-modeling-guide.md'];
 const EXPECTED_COMMAND_IDS = [
   'new-feature',
   'modify-existing',
@@ -399,13 +406,6 @@ async function runPreflight(cwd) {
     warnings.push('Found empty dflow/specs/. Continuing because no initialized files were found.');
   }
 
-  const legacySpecsPath = path.join(cwd, 'specs');
-  if ((await pathExists(legacySpecsPath)) && (await containsInitializedContent(legacySpecsPath))) {
-    warnings.push(
-      'Detected legacy specs/. Dflow V1 will not migrate or modify it; new files will be created under dflow/specs/. See docs/migrating-to-dflow-v1.md for the manual migration checklist.'
-    );
-  }
-
   await assertWritableProjectRoot(cwd);
 
   if (compareVersions(process.versions.node, MIN_NODE_VERSION) < 0) {
@@ -1214,31 +1214,97 @@ async function finalizePlanItems(cwd, items) {
   }
 }
 
+// A workflow bundle file name must be unique across the common and edition
+// source trees, so the merged dest path / manifest entry never collide or
+// shadow each other. Pure (no I/O) so it is unit-testable on a synthetic list.
+function assertNoBundleCollision(files) {
+  const seenBy = new Map();
+  for (const f of files) {
+    const prior = seenBy.get(f.sourceRel);
+    if (prior && prior !== f.sourceRoot) {
+      throw new InitError(
+        `Internal error: workflow bundle file "${f.sourceRel}" exists in both templates/${prior}/ and templates/${f.sourceRoot}/. A bundle file name must be unique across the common and edition source trees.`
+      );
+    }
+    seenBy.set(f.sourceRel, f.sourceRoot);
+  }
+}
+
+// R3-02 (sharpened for the PROPOSAL-064 common merge): the EDITION tree itself
+// must contribute both the flow docs (references/) and the blank templates
+// (templates/) — the common tree must NOT mask a broken edition (a vanished
+// templates/{edition}/references/ would otherwise be hidden by common's
+// non-empty references/). Enforced in the scanner (not only the projector) so
+// BOTH callers are covered: the projector hard-fails, and doctor's existing
+// try/catch around listBundleSourceFiles degrades to skipping the orphan scan
+// rather than mis-reporting every projected flow file as orphaned. Pure (no
+// I/O) so it is unit-testable on a synthetic list.
+function assertEditionBundleComplete(files, edition) {
+  const hasEditionRefs = files.some((f) => f.sourceRoot === edition && f.dir === 'references');
+  const hasEditionTemplates = files.some((f) => f.sourceRoot === edition && f.dir === 'templates');
+  if (!hasEditionRefs || !hasEditionTemplates) {
+    throw new InitError(
+      `Internal error: incomplete workflow bundle source for edition "${edition}" (expected files under both templates/${edition}/references/ and templates/${edition}/templates/). The installed dflow package looks incomplete.`
+    );
+  }
+}
+
+// Companion to assertEditionBundleComplete for the common tree: every file the
+// common bundle MUST provide has to be present. A common file silently missing
+// (broken package / tarball) would otherwise slip through as a smaller-but-valid
+// set and, on re-projection, be DELETED from the user's project by stale-removal
+// (the manifest diff would classify the still-installed copy as "retired").
+// Hard-fail here, before stale cleanup / manifest write. Pure (no I/O) so it is
+// unit-testable on a synthetic list.
+function assertCommonBundleComplete(files) {
+  const present = new Set(files.filter((f) => f.sourceRoot === 'common').map((f) => f.sourceRel));
+  for (const required of REQUIRED_COMMON_BUNDLE_FILES) {
+    if (!present.has(required)) {
+      throw new InitError(
+        `Internal error: missing required common workflow bundle file templates/common/${required}. The installed dflow package looks incomplete.`
+      );
+    }
+  }
+}
+
+// Bundle source files come from two trees, merged: the edition-neutral common
+// tree (templates/common/, PROPOSAL-064) and the per-edition tree
+// (templates/{edition}/). Each descriptor carries its sourceRoot so the reader
+// (readPackagedBundleFile) loads content from the right tree; the projected dest
+// path and the manifest stay keyed on sourceRel, so a common-sourced file lands
+// at the same dflow/.../references/<name> path in every edition. The scanner
+// validates the merged set (collision + complete-edition guards) before
+// returning, so both callers (projector, doctor) get a trustworthy list.
 async function listBundleSourceFiles(edition) {
   const bundleDirs = ['references', 'templates'];
+  const sourceRoots = ['common', edition];
   const files = [];
 
-  for (const dir of bundleDirs) {
-    const sourceDir = path.join(TEMPLATE_ROOT, edition, dir);
-    let entries;
-    try {
-      entries = await fs.readdir(sourceDir);
-    } catch (error) {
-      if (error.code === 'ENOENT') {
-        continue;
+  for (const sourceRoot of sourceRoots) {
+    for (const dir of bundleDirs) {
+      const sourceDir = path.join(TEMPLATE_ROOT, sourceRoot, dir);
+      let entries;
+      try {
+        entries = await fs.readdir(sourceDir);
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          continue;
+        }
+        throw error;
       }
-      throw error;
-    }
-    for (const entry of entries) {
-      const sourceRel = `${dir}/${entry}`;
-      const sourcePath = path.join(sourceDir, entry);
-      const stat = await fs.stat(sourcePath);
-      if (stat.isFile()) {
-        files.push({ sourceRel, dir, name: entry });
+      for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry);
+        const stat = await fs.stat(sourcePath);
+        if (stat.isFile()) {
+          files.push({ sourceRel: `${dir}/${entry}`, dir, name: entry, sourceRoot });
+        }
       }
     }
   }
 
+  assertNoBundleCollision(files);
+  assertEditionBundleComplete(files, edition);
+  assertCommonBundleComplete(files);
   return files;
 }
 
@@ -1306,18 +1372,12 @@ function injectBundleMarker(content) {
 }
 
 async function addWorkflowBundleItems(cwd, items, warnings, edition) {
+  // listBundleSourceFiles merges templates/common/ + templates/{edition}/ and
+  // validates the merged set (collision + complete-edition guards) before
+  // returning, so the projector can trust a complete set here. A broken package
+  // throws (InitError) before any stale removal or manifest write.
   const bundleFiles = await listBundleSourceFiles(edition);
 
-  // R3-02: a healthy edition's bundle source is never empty. An empty scan means
-  // a broken installed package — hard-fail BEFORE scheduling any removal or
-  // writing the manifest, so we never overwrite the manifest with files:[]
-  // (which would orphan every projected file and ship a workflow-less project).
-  if (bundleFiles.length === 0) {
-    throw new InitError(
-      `Internal error: no workflow bundle source files found for edition "${edition}" (expected files under templates/${edition}/references/ and templates/${edition}/templates/). The installed dflow package looks incomplete.`
-    );
-  }
-
   const newRelPaths = new Set(bundleFiles.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`));
 
   // Read the previous manifest to drive stale cleanup. Distinguish absent
@@ -1396,10 +1456,10 @@ async function addWorkflowBundleItems(cwd, items, warnings, edition) {
   }
 
   // Build items for current edition bundle files.
-  for (const { sourceRel } of bundleFiles) {
+  for (const { sourceRel, sourceRoot } of bundleFiles) {
     const relativePath = `${WORKFLOW_BUNDLE_DEST}/${sourceRel}`;
     const absolutePath = path.join(cwd, relativePath);
-    const sourceContent = await readPackagedBundleFile(edition, sourceRel);
+    const sourceContent = await readPackagedBundleFile(sourceRoot, sourceRel);
     const content = injectBundleMarker(sourceContent);
 
     let action;
@@ -1423,7 +1483,7 @@ async function addWorkflowBundleItems(cwd, items, warnings, edition) {
 
     items.push({
       relativePath,
-      source: `packaged-bundle:${edition}/${sourceRel}`,
+      source: `packaged-bundle:${sourceRoot}/${sourceRel}`,
       notes,
       content,
       action,
@@ -1455,13 +1515,17 @@ async function addWorkflowBundleItems(cwd, items, warnings, edition) {
   }
 }
 
-async function readPackagedBundleFile(edition, sourceRel) {
-  const filePath = path.join(TEMPLATE_ROOT, edition, sourceRel);
-  const normalizedRoot = path.resolve(TEMPLATE_ROOT, edition);
+// Reads one bundle file's content from its source tree. sourceRoot is the
+// descriptor's tree ('common' or an edition) so a common-sourced file is read
+// from templates/common/, not templates/{edition}/ (PROPOSAL-064). The traversal
+// guard is re-rooted at templates/${sourceRoot}/ accordingly.
+async function readPackagedBundleFile(sourceRoot, sourceRel) {
+  const filePath = path.join(TEMPLATE_ROOT, sourceRoot, sourceRel);
+  const normalizedRoot = path.resolve(TEMPLATE_ROOT, sourceRoot);
   const normalizedFilePath = path.resolve(filePath);
 
   if (!normalizedFilePath.startsWith(`${normalizedRoot}${path.sep}`)) {
-    throw new InitError(`Internal error: packaged bundle file not found: templates/${edition}/${sourceRel}`);
+    throw new InitError(`Internal error: packaged bundle file not found: templates/${sourceRoot}/${sourceRel}`);
   }
 
   let buffer;
@@ -1469,15 +1533,15 @@ async function readPackagedBundleFile(edition, sourceRel) {
     buffer = await fs.readFile(normalizedFilePath);
   } catch (error) {
     if (error.code === 'ENOENT') {
-      throw new InitError(`Internal error: packaged bundle file not found: templates/${edition}/${sourceRel}`);
+      throw new InitError(`Internal error: packaged bundle file not found: templates/${sourceRoot}/${sourceRel}`);
     }
-    throw new InitError(`Internal error: cannot read packaged bundle file: templates/${edition}/${sourceRel}`);
+    throw new InitError(`Internal error: cannot read packaged bundle file: templates/${sourceRoot}/${sourceRel}`);
   }
 
   try {
     return new TextDecoder('utf-8', { fatal: true }).decode(buffer);
   } catch {
-    throw new InitError(`Internal error: invalid UTF-8 packaged bundle file: templates/${edition}/${sourceRel}`);
+    throw new InitError(`Internal error: invalid UTF-8 packaged bundle file: templates/${sourceRoot}/${sourceRel}`);
   }
 }
 
@@ -3056,8 +3120,6 @@ async function runDoctor(options = {}) {
     }
 
     const findings = [];
-    await checkLegacyRootSpecsDir(cwd, findings);
-    await checkLegacySharedDir(cwd, findings);
     await checkConventionsDflowVersion(cwd, findings);
     await checkOrphanedWorkflowBundleFiles(cwd, findings);
 
@@ -3073,36 +3135,6 @@ async function runDoctor(options = {}) {
   }
 }
 
-async function checkLegacyRootSpecsDir(cwd, findings) {
-  const legacyPath = path.join(cwd, 'specs');
-  if ((await pathExists(legacyPath)) && (await containsInitializedContent(legacyPath))) {
-    findings.push({
-      level: 'warn',
-      title: 'Legacy specs/ directory at project root',
-      detail: 'V1 layout uses dflow/specs/ instead. The CLI does not modify root specs/.',
-      action: 'See docs/migrating-to-dflow-v1.md (Step 1) for the manual migration steps.'
-    });
-  }
-}
-
-async function checkLegacySharedDir(cwd, findings) {
-  const candidates = [
-    path.join(cwd, 'dflow', 'specs', '_共用'),
-    path.join(cwd, 'specs', '_共用')
-  ];
-  for (const candidate of candidates) {
-    if (await pathExists(candidate)) {
-      const rel = normalizePath(path.relative(cwd, candidate));
-      findings.push({
-        level: 'warn',
-        title: `Legacy ${rel}/ directory`,
-        detail: 'V1 layout uses shared/ (canonical English directory name).',
-        action: 'See docs/migrating-to-dflow-v1.md (Step 2) for the rename steps.'
-      });
-    }
-  }
-}
-
 async function checkConventionsDflowVersion(cwd, findings) {
   const conventionsPath = path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md');
   if (!(await pathExists(conventionsPath))) return;
@@ -3185,7 +3217,7 @@ function printDoctorReport(stdout, cwd, findings) {
   stdout.write(`Project: ${cwd}\n\n`);
 
   if (findings.length === 0) {
-    stdout.write('All checks passed. No legacy artifacts detected.\n');
+    stdout.write('All checks passed. No Dflow health findings detected.\n');
     return;
   }
 
@@ -3211,5 +3243,10 @@ module.exports = {
   // Exported for tests: the write phase enforces the PROPOSAL-054 raw-equality guard
   // for user-owned root agent files (changed-after-preview -> skip), which cannot be
   // exercised through the CLI because preview and write happen in one process.
-  writeFilePlan
+  writeFilePlan,
+  // Exported for tests (PROPOSAL-064): pure bundle-source guards, unit-tested on
+  // synthetic descriptor lists without touching the packaged templates/ tree.
+  assertNoBundleCollision,
+  assertEditionBundleComplete,
+  assertCommonBundleComplete
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {
@@ -39,7 +39,7 @@
   },
   "homepage": "https://github.com/weilung/dflow-sdd-ddd#readme",
   "scripts": {
-    "test": "node test/smoke.mjs && node test/registry-parity.mjs && node test/agent-inject.mjs"
+    "test": "node test/smoke.mjs && node test/registry-parity.mjs && node test/agent-inject.mjs && node test/bundle-guards.mjs"
   },
   "license": "AGPL-3.0-or-later",
   "publishConfig": {

package/templates/brownfield/references/drift-verification.md

@@ -4,18 +4,23 @@ Triggered by `/dflow:verify` or `/dflow:verify <bounded-context>`.
 
 ## Purpose
 
-The A+C structure (`rules.md` as index + `behavior.md` as scenario content) introduces a drift risk — the two files can fall out of sync. This command provides a mechanical verification safety net that developers can run at key moments: before a PR, after a refactor, or when onboarding to an unfamiliar Bounded Context.
+The A+C structure (`rules.md` as index + `behavior.md` as scenario content) introduces a drift risk — the two files can fall out of sync. This command's **core** is a mechanical safety net for that `rules.md` ↔ `behavior.md` correspondence, run at key moments: before a PR, after a refactor, or when onboarding to an unfamiliar Bounded Context. On top of the core it also runs an **optional, non-blocking domain-doc hygiene check** on the model catalog (`models.md`) — see Scope.
 
 ## Scope
 
-### This command does (mechanical layer)
+### This command does (core + optional hygiene)
 
-Three string-matching checks that AI can perform deterministically:
+A small **core** of three deterministic string-matching checks on the
+`rules.md` ↔ `behavior.md` correspondence:
 
 1. **BR-ID forward check**: Every `BR-*` declared in `rules.md` has a corresponding section in `behavior.md`
 2. **Anchor validity**: If `rules.md` links to `behavior.md#section`, that anchor exists
 3. **BR-ID reverse check**: Every `BR-*` referenced in `behavior.md` is declared in `rules.md`
 
+Plus an **optional domain-doc hygiene** warning (non-blocking — it never fails the
+command, only surfaces a "confirm this is intentional" signal): the `models.md`
+Code-Mapping hygiene check (see Model Catalog Notes).
+
 ### This command does NOT do (semantic layer — explicitly excluded)
 
 Semantic verification (LLM reads the one-line summary in `rules.md` vs the Given/When/Then in `behavior.md` and judges whether they contradict) is **out of scope**. Reasons:
@@ -39,8 +44,8 @@ Reasons:
   Step 3
 - BC-level current state is already maintained by `rules.md` /
   `behavior.md`, written by the same `/dflow:finish-feature` Step 3
-- `/dflow:verify` keeps a small, mechanical scope: just the
-  `rules.md` ↔ `behavior.md` correspondence inside one BC
+- `/dflow:verify` keeps a small core: the `rules.md` ↔ `behavior.md`
+  correspondence inside one BC, plus the optional models.md hygiene check below
 - Cross-feature / cross-phase aggregation would mix `/dflow:verify`'s
   job with `/dflow:finish-feature`'s job and produce false positives
   during in-progress features
@@ -84,6 +89,9 @@ For each Bounded Context:
       - behavior.md → templates/behavior.md
       Or run the completion flow to populate it from existing completed specs
   ```
+- Also locate the **optional** hygiene input for this BC — `models.md`. It feeds
+  the non-blocking Model Catalog Notes hygiene check. If it is absent, **skip the
+  check silently** — do not report or stop; it is bonus, not part of the core.
 
 ### Step 2: Extract BR-IDs from rules.md
 
@@ -153,6 +161,31 @@ Issues:
      remove the stale scenario reference from behavior.md
 ```
 
+The optional `models.md` Code-Mapping hygiene check (below) appends its
+non-blocking `ℹ` signals to this same report and never changes the core
+pass / fail count.
+
+## Model Catalog Notes
+
+A non-blocking **informational** hygiene check on `models.md`:
+
+- For each row whose **primary name cell** holds a real value, if the
+  `Code Mapping` column is empty or still a `{Namespace.Class}` placeholder,
+  surface it:
+  ```
+  ℹ models.md: Entity "ExpenseReport" has no Code Mapping yet — link it if the
+    code is extracted; if extraction is deferred, this is expected
+  ```
+- **Skip untouched seed rows by the name cell only**: a row whose name is still a
+  `{...}` placeholder is seed scaffolding. But a row with a **real name** and a
+  placeholder / empty Code Mapping is exactly the one to surface — do not skip it
+  just because that one cell still holds `{...}`.
+- This is **informational, not drift** — Brownfield records a concept in `models.md`
+  during discovery, often *before* the code is extracted, so an empty Code Mapping
+  is a normal state, not drift. An explicit "planned / deferred" note on the row, or
+  a matching `## Code Mapping Notes` entry, counts as accounted for; do not surface
+  it.
+
 ## When to Run
 
 Recommended trigger points (not enforced — developer's judgment):
@@ -166,7 +199,8 @@ Recommended trigger points (not enforced — developer's judgment):
 ## Path Assumptions
 
 This command operates entirely within `dflow/specs/domain/{context}/` files
-(`rules.md` and `behavior.md`). It does **not** read from
+(`rules.md` and `behavior.md` for the core check; `models.md` for the optional
+hygiene warning). It does **not** read from
 `dflow/specs/features/active/{SPEC-ID}-{slug}/` directories — the feature
 directory layout is not part of verify's input.
 

package/templates/brownfield/references/finish-feature-flow.md

@@ -55,6 +55,10 @@ proceeding (do not flip status, do not archive, do not emit summary).
 - [ ] Every phase-spec file referenced in the Phase Specs table exists at
       the path the table claims
 - [ ] Every phase-spec file's frontmatter has `status: completed`
+- [ ] Every Tier = T2 row in `_index.md` Lightweight Changes references an
+      existing `lightweight-*.md` / `BUG-*.md` file in the feature directory
+- [ ] Every such lightweight / BUG spec file's frontmatter has
+      `status: completed`
 - [ ] `_index.md` has no obvious open items in Resume Pointer (e.g. "phase-N
       drafting" / "implementation pending" / "TODO" markers)
 - [ ] Current BR Snapshot table is non-empty (or feature is intentionally
@@ -65,6 +69,7 @@ If any check fails:
 > found:
 >   ✗ phase-spec-2026-04-15-foo.md status is still `in-progress`
 >   ✗ Phase Specs table row 3 references missing file phase-spec-...
+>   ✗ lightweight-2026-06-20-rounding.md frontmatter status is still `in-progress`
 >
 > Address these (run `/dflow:new-phase` to add missing work, or fix the
 > stale status manually), then re-run `/dflow:finish-feature`."
@@ -92,11 +97,17 @@ branch: feature/{SPEC-ID}-{slug}
 ---
 ```
 
-Also update the **Resume Pointer** to reflect closeout:
+Also update the **Resume Pointer** to reflect closeout — this writes the
+cursor's terminal state (after closeout no workflow is active on this
+feature; do not edit the cursor again after the Step 4 closeout commit):
 
 ```
 **Current Progress**: feature completed ({date}); all phase-specs status = completed.
 **Next Action**: integration — push / merge / PR per the selected Git policy.
+**Active Workflow**: none
+**Current Step**: n/a
+**Gates Passed**: n/a
+**Awaiting**: none
 ```
 
 **→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (status flipped). Entering Step 3: Sync BR Snapshot to BC layer." and continue.
@@ -170,7 +181,8 @@ AI runs:
 ```bash
 git mv dflow/specs/features/active/{SPEC-ID}-{slug} \
        dflow/specs/features/completed/{SPEC-ID}-{slug}
-git status   # confirm rename detection
+git status   # confirm rename detection AND check for `RM` — an `M` next to
+             # a rename means unstaged edits you must re-add before committing
 ```
 
 `git mv` is mandatory — never use plain `mv` + `git add`. This preserves
@@ -179,37 +191,74 @@ PR diff quality stays intact across the move. See
 `references/git-integration.md` § "Directory Moves Must Use git mv" for
 the full rule set.
 
-After the move, also `git add` any modified files from Step 3 (the
-updated `rules.md`, `behavior.md`, `glossary.md`, `tech-debt.md`, etc.)
-into the same stage.
-
 **Closeout commit checkpoint** (completes the offline Local-closeout gate):
 
 ```
-✓ Feature archived to completed/ and closeout files staged
+✓ Feature archived to completed/ and closeout ready to stage
    Commit this closeout now?
    [Y] Yes — the AI commits with your Git identity (marker per _conventions.md § AI Commit Policy)
    [N] No — skip; you commit yourself
 ```
 
-Whether you choose Y or N, record one row in the feature `_index.md`
-Checkpoint Log (`closeout | committed ({hash})` or `closeout | skipped`). Only
-write a hash after the commit actually succeeds; if a pre-commit hook rejects it
-or the commit fails, record `failed` and surface the error — never write a fake
-hash.
-
-The Local-closeout gate is satisfied **only when the closeout is committed**:
-closeout complete, Checkpoint Log updated, and the working tree clean (no
-uncommitted changes). If you declined the commit (chose N) or it failed,
-Local-closeout is **not** satisfied yet — commit the staged closeout yourself
-before continuing; do not enter the Integration / PR gate with uncommitted
-changes. Once committed, the gate stands on its own offline; integration happens
-in Step 5 when you have network.
-
-**→ Transition (step-internal)**: Step 4 complete. Branch on whether the closeout commit landed:
-
-- **Closeout commit landed (working tree clean)** → announce "Step 4 complete (feature archived; Local-closeout gate satisfied). Entering Step 5: Integration / PR gate." and continue.
-- **Closeout commit was declined (N) or failed** → **stop here.** Announce "Step 4 complete (feature archived), but the Local-closeout gate is not satisfied yet — the closeout is staged but uncommitted. Commit those changes (or address the failure), then resume to Step 5." Do **not** enter Step 5 with uncommitted closeout changes.
+Then, in this order:
+
+1. **Record the checkpoint row first.** Write one row in the moved
+   `_index.md` Checkpoint Log — `closeout | committed` for Y, `closeout |
+   skipped` for N. The closeout row carries **no commit hash**: the closeout
+   commit cannot contain its own hash. Trace it later via
+   `git log -1 -- dflow/specs/features/completed/{SPEC-ID}-{slug}` (or the
+   optional `Dflow-Checkpoint` trailer). The "hash only after success" rule
+   still applies to spec / implementation rows — closeout is the documented
+   exception (see `references/git-integration.md` § Commit Checkpoints,
+   Branch Gate & AI Commits).
+2. **Stage the whole archived feature directory:**
+
+   ```bash
+   git add dflow/specs/features/completed/{SPEC-ID}-{slug}
+   ```
+
+   This is required, not optional: `git mv` stages the rename with the
+   **last-committed** content, so working-tree edits made earlier in this
+   flow to the moved files — the Step 2 status flip and Resume Pointer
+   update, plus the checkpoint row you just wrote — stay **unstaged** until
+   this `git add`. In `git status`, the moved `_index.md` showing `RM`
+   instead of plain `R` is exactly this signal. Then also `git add` the
+   files updated in Step 3 (the updated `rules.md`, `behavior.md`,
+   `glossary.md`, `tech-debt.md`, etc.) into the same stage.
+3. **Commit (Y) or stop (N).** For Y the AI commits. If a pre-commit hook
+   rejects it or the commit fails, flip the checkpoint row to `failed` (the
+   row is not committed yet — edit it directly), surface the error, and
+   treat the gate as unsatisfied.
+
+**Post-commit closeout verification** — after a successful commit, and before
+declaring the Local-closeout gate satisfied, AI runs and reports `✓` / `✗` for
+every item:
+
+- [ ] `git show HEAD:dflow/specs/features/completed/{SPEC-ID}-{slug}/_index.md`
+      — one blob read verifying **two** things: frontmatter `status: completed`
+      **and** the Checkpoint Log contains the closeout row. This reads the
+      **committed** content, not the working tree — the former catches "rename
+      carried stale content", the latter catches "row never made it into the
+      commit".
+- [ ] `dflow/specs/features/active/{SPEC-ID}-{slug}/` no longer exists (the
+      directory was moved, not copied)
+- [ ] `git status --short` shows no leftovers related to this feature
+      (working tree clean; identify any unrelated dirty files explicitly)
+
+If any item fails, do **not** declare closeout complete — fix it (re-add and
+amend, or a follow-up commit; the developer chooses) and re-verify.
+
+The Local-closeout gate is satisfied **only when the closeout is committed and
+the verification above passes**. If you declined the commit (chose N) or it
+failed, Local-closeout is **not** satisfied yet — commit the staged closeout
+yourself before continuing; do not enter the Integration / PR gate with
+uncommitted changes. Once committed and verified, the gate stands on its own
+offline; integration happens in Step 5 when you have network.
+
+**→ Transition (step-internal)**: Step 4 complete. Branch on the verification result:
+
+- **Closeout commit landed and post-commit verification passed** → announce "Step 4 complete (feature archived; Local-closeout gate satisfied). Entering Step 5: Integration / PR gate." and continue.
+- **Closeout commit was declined (N), failed, or verification reported `✗`** → **stop here.** Announce "Step 4 complete (feature archived), but the Local-closeout gate is not satisfied yet — the closeout is staged but uncommitted, or the committed content failed verification. Commit the staged changes (or fix the failure), then resume to Step 5." Do **not** enter Step 5 with uncommitted or unverified closeout changes.
 
 ## Step 5: Emit Integration Summary (Git-strategy-neutral)
 
@@ -266,10 +315,17 @@ the developer:
 
 If no `follow-up-of` field, skip Step 6 and announce closeout complete:
 > "`/dflow:finish-feature` complete for `{SPEC-ID}-{slug}`. Feature
-> directory is now at `dflow/specs/features/completed/{SPEC-ID}-{slug}/`.
-> If you skipped the closeout commit, commit the staged changes first to
-> finish the Local-closeout gate. Then integration — merge / push / PR —
-> follows the selected Git policy, at your discretion."
+> directory is now at `dflow/specs/features/completed/{SPEC-ID}-{slug}/`,
+> with the Local-closeout gate satisfied (closeout committed and verified).
+> Integration — merge / push / PR — follows the selected Git policy, at
+> your discretion."
+
+**In-flight reminder** — after the closeout announcement (with or without
+Step 6), run the in-flight overview scan (see `AI-AGENT-GUIDE.md` § Status /
+Control Commands) and list any other unfinished features in `active/` and any
+in-flight feature / bugfix branches. Surfacing them at closeout is deliberate:
+attention is about to move elsewhere, and this is exactly where half-done work
+sinks.
 
 ## Step 6: Reverse-Update Follow-up Tracking (only if follow-up)