dflow-sdd-ddd 0.10.0 → 0.11.0

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.11.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/modify-existing-flow.md

@@ -282,8 +282,46 @@ Decision framework:
 - **Extract now** if: the logic is being significantly modified anyway
 - **Extract now** if: the logic is duplicated elsewhere and we need the single source of truth
 - **Defer extraction** if: the change is a one-line fix and the surrounding code is too tangled
+- **Consider not extracting at all** if: the context is `generic` (per the
+  context-map Subdomain Type) — a commodity capability's endgame is wholesale
+  replacement with an off-the-shelf package / service, so extracting its rules
+  one by one is wasted effort; record the replacement intent as the tech-debt
+  entry instead
 - **Always record** the extraction opportunity in tech-debt.md even if deferring
 
+If the target context has **no Subdomain Type** (not in `context-map.md`, or
+the column is absent), ask the developer once to classify it. If they'd rather
+not decide now, record it as an Open Question in the spec and run the
+extraction decision on the framework above — do **not** assume `generic`.
+
+**Aggregate emergence check.** Before extracting yet another rule onto an
+existing concept, look at what has already accumulated on it (in `models.md` /
+`rules.md`). The signal that it has stopped being a loose entity and is
+becoming an **Aggregate Root with a consistency boundary**: **2+ non-trivial
+state-transition rules on the same lifecycle identity, or any invariant that
+must check / update multiple fields or child records atomically.** (A
+*consistency boundary* means state that must hold or change **together,
+atomically** — not mere relatedness: same screen, related nouns, or local
+single-field input validation do **not** count.) When you see it, continuing
+to extract rules one by one as T2 will leave the boundary undrawn — surface it
+and **suggest escalating to T1** (`/dflow:new-phase` inside an active feature,
+else `/dflow:new-feature`) to model the Aggregate deliberately: its invariants,
+what must change atomically, what it protects. For *how* to model it —
+invariant classification, set-based / uniqueness rules, aggregate sizing — read
+`references/ddd-modeling-guide.md` (its **Edition note** maps each recording
+surface to brownfield's `models.md` / `rules.md`). In `models.md`, **mark the
+existing Entity row as the Aggregate Root and note the protected invariants /
+atomic-change scope in its Responsibility / Notes** — brownfield `models.md`
+has no separate Aggregates section, do not invent one; update the Repository
+row if one exists. If the developer defers, **record the emergence observation
+in `tech-debt.md`** so the boundary decision is not silently lost.
+
+If the context is **`generic`** (Subdomain Type), emergence is usually a
+*replacement / adapter-boundary* debt signal, not a cue for deep T1 modeling —
+record the replacement intent (consistent with the generic extraction fallback
+above) rather than escalating, unless the developer explicitly chooses to
+model it.
+
 ### Generate Implementation Tasks List
 
 For a phase-spec modification, AI generates a concrete task list and writes it into the spec's `Implementation Tasks` section using `[LAYER]-[NUMBER]：description` (DOMAIN / DELIVERY / DATA / TEST).

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

@@ -50,6 +50,23 @@ If no matching context exists:
 2. Create `dflow/specs/domain/{new-context}/context.md` using the context-definition template
 3. Get developer confirmation before proceeding
 
+Once the BC is confirmed, classify and record its **Subdomain Type** as part
+of the same confirmation (not a separate gate):
+
+```
+"Is this capability core (差異化來源), supporting (必要但非差異化),
+or generic (可買 / 可套件 / 簡單 CRUD)? I'll record it in context-map.md."
+```
+
+If the BC already has a Subdomain Type, reuse it — don't re-ask unless the
+developer wants to reclassify. Record it in
+`dflow/specs/domain/context-map.md`:
+
+- If the file **does not exist** (the Brownfield track does not mandate it —
+  contexts emerge organically), create it from `templates/context-map.md`.
+- If it exists but the **Subdomain Type column is missing**, add the column
+  **preserving every existing row** — do not rewrite their content.
+
 **→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (BC identified). Entering Step 3: Domain Concept Discovery." and continue.
 
 ## Step 3: Domain Concept Discovery
@@ -62,6 +79,17 @@ Walk through these questions:
 - **What are the states/statuses?** → State machines to model
 - **What external data is needed?** → Interfaces to define
 
+If one concept gathers rules / invariants that must hold together — **a state
+machine over its lifecycle, or invariants spanning several of its fields /
+child records** — treat it as a candidate **Aggregate Root** (a consistency
+boundary = atomic, not mere relatedness), not just an Entity. Note its
+invariants and what must change atomically against its `models.md` Entity row,
+and confirm the boundary with the developer. (A state machine is one common
+signal, not a prerequisite.) For the tactical patterns — invariant
+classification, set-based / uniqueness rules, value objects, aggregate sizing —
+read `references/ddd-modeling-guide.md` (its **Edition note** maps recording
+surfaces to brownfield's `models.md` / `rules.md`).
+
 For each new concept:
 1. Check glossary — add if missing
 2. Check if it already exists in models.md — extend if needed

package/templates/brownfield/references/new-phase-flow.md

@@ -92,7 +92,14 @@ Walk the developer through what the new phase covers:
    BRs (ADDED), changed BRs (MODIFIED), removed BRs (REMOVED), renamed
    (RENAMED). Items not mentioned stay UNCHANGED implicitly.
 3. **Any Domain concepts introduced or changed?** New Entities / Value
-   Objects / Services touching `src/Domain/{context}/`?
+   Objects / Services touching `src/Domain/{context}/`? If this phase is an
+   **Aggregate-emergence escalation** (handed off from `/dflow:modify-existing`),
+   record the candidate Aggregate Root, the invariants it protects, and what
+   must change atomically — marking the Aggregate Root on its `models.md`
+   Entity row (no separate Aggregates section). For how to model it (invariant
+   classification, set-based / uniqueness rules, aggregate sizing), read
+   `references/ddd-modeling-guide.md` (its **Edition note** maps recording
+   surfaces to brownfield's `models.md` / `rules.md`).
 4. **Data structure impact?** New tables, columns, indices?
 5. **Why now?** Priority — informs sequencing relative to other phases.
 

package/templates/brownfield/references/pr-review-checklist.md

@@ -139,7 +139,13 @@ for later?"
 ## Glossary Consistency
 
 - [ ] **New terms documented** — Any new business concept added to glossary.md?
-- [ ] **Consistent naming** — Do class/method/variable names match glossary terms?
+- [ ] **Naming matches the Ubiquitous Language** — for each **domain-facing**
+      class / method / variable the diff introduces (skip DTO / test / framework
+      names), is there a matching term in `glossary.md`? The `Code Mapping` column
+      maps each term to its `{Namespace/Class/Member}` — a domain name with no
+      glossary term, or a term whose Code Mapping is now stale, is the signal.
+- [ ] **No synonym drift** — is the code naming a concept with a different word
+      than the glossary? Align it. (Judgment call, not a string match.)
 - [ ] **No ambiguous terms** — Are domain-specific terms used precisely?
 
 Example check:

package/templates/brownfield/scaffolding/AI-AGENT-GUIDE.md

@@ -102,6 +102,12 @@ input like this (supporting files live in the workflow bundle at
   `dflow/specs/features/backlog/` and suggest work based on migration value.
 - **"I'm creating a branch"** → read `references/git-integration.md`; verify
   branch naming and ensure a spec exists before coding starts.
+- **"I'm designing a domain model" / "How should I model X?" / building or
+  reshaping an Aggregate** → read `references/ddd-modeling-guide.md` (DDD
+  tactical patterns: aggregates, invariants, value objects, domain events). It
+  is written with Greenfield artifact names; see its **Edition note** for where
+  Brownfield records the same decisions (`models.md` / `rules.md` /
+  `behavior.md` / `migration/tech-debt.md`).
 - **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
   guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
   anything upstream automatically.
@@ -344,34 +350,6 @@ during the completion checklist, not via template section markers.
 - Direct SQL in delivery/entrypoint code? → Record
 - Magic numbers or undocumented statuses? → Record and add to glossary
 
-## Pre-V1 Artifacts Detection
-
-When working in a project that adopted Dflow before `dflow-sdd-ddd@0.1.0`,
-you may encounter layout or naming patterns that predate the V1 baseline.
-If any of the following appear, surface the observation to the developer
-and recommend manual migration; do not rewrite anything silently.
-
-Signals:
-
-- Top-level `specs/` directory containing Dflow-shaped content (V1 layout
-  uses `dflow/specs/`).
-- `_共用/` directory under `specs/` or `dflow/specs/` (V1 uses `shared/`).
-- Section headings in Traditional Chinese where V1 templates render
-  canonical English; compare against `TEMPLATE-LANGUAGE-GLOSSARY.md` if
-  available.
-- References to a runtime `/dflow:init-project` slash command (V1
-  replaced it with the Dflow CLI init command (`dflow init`, or
-  `npx dflow-sdd-ddd init` when using the no-install path)).
-- A root `CLAUDE.md`, `AGENTS.md`, or equivalent that holds the full
-  Dflow workflow text instead of being a thin shim pointing to this
-  file.
-- `dflow/specs/shared/_conventions.md` is missing the `> Dflow Version:`
-  front-matter line (V1 init writes it automatically).
-
-Recommend `docs/migrating-to-dflow-v1.md` for the manual migration
-checklist. Migration affects every spec the team has written; manual
-review is required.
-
 ## Workflow Steps
 
 This guide is the **command registry, routing rules, and project context**.

package/templates/brownfield/templates/context-map.md

@@ -6,15 +6,23 @@
 
 ## Context List
 
-| Bounded Context | Responsibility | Owner / Team | Primary Code Area | Notes |
-|---|---|---|---|---|
-| {Context name} | {業務責任} | {owner} | `{project/path/or/namespace}` | {optional notes} |
+| Bounded Context | Responsibility | Subdomain Type | Owner / Team | Primary Code Area | Notes |
+|---|---|---|---|---|---|
+| {Context name} | {業務責任} | core / supporting / generic | {owner} | `{project/path/or/namespace}` | {optional notes} |
+
+> **Subdomain Type** — 判別問句:「這塊功能換成現成 SaaS / 套件,系統的差異化會消失嗎?」
+> (差異化不限商業競爭優勢;內部系統指獨特的營運優勢 / 任務成果。)會 → `core`;
+> 不會、但需要為自家流程客製 → `supporting`(必要、常需客製、非差異化);
+> 不會、且現成方案存在 → `generic`。多數 BC 是 supporting,`core` 通常只有 1–2 個;
+> 全標 core = 沒分類。分類是可修訂的初判,改判時更新本欄並在 Notes 留一行理由。
+> 它影響漸進抽離的取捨(`generic` 傾向整塊替換而非逐條抽離,見 modify-existing-flow
+> Step 4),但**不**降低 BR 紀錄、Tier ceremony、或安全 / 測試 / 可靠性要求。
 
 ## Relationships
 
 | Source Context | Target Context | Relationship Type | Integration Mechanism | Notes |
 |---|---|---|---|---|
-| {Source} | {Target} | {Customer/Supplier, Conformist, ACL, Shared Kernel, etc.} | {DB table, service call, file, manual process} | {optional notes} |
+| {Source} | {Target} | {Customer/Supplier, Conformist, ACL, Shared Kernel, Separate Ways, Big Ball of Mud (BBoM), OHS, etc.} | {DB table, service call, file, manual process} | {optional notes} |
 
 ## Integration Notes