dflow-sdd-ddd 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.9.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"
+    "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,12 +199,10 @@ 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. The only effect of feature directory layout on this command is
-ensuring `last-updated` dates in `behavior.md` are bumped at
-`/dflow:finish-feature` time (so verify's mechanical drift guard stays
-useful).
+directory layout is not part of verify's input.
 
 ## Interaction with Other Commands
 

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

@@ -34,7 +34,7 @@ state, archives the feature directory, and emits a Git-strategy-neutral
 - Step 5 → Step 6 (Integration Summary emitted → optional follow-up reverse-link)
 
 All other step transitions are **step-internal**: announce "Step N complete,
-entering Step N+1" and proceed without waiting. See SKILL.md § Workflow
+entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow
 Transparency for the full transparency protocol and confirmation signals.
 
 ## Step 1: Validate Phase Specs and `_index.md`
@@ -124,6 +124,8 @@ For each row in Current BR Snapshot where Status = `active`:
   `rules.md` (REMOVED rule)
 - For any RENAMED BR-ID → rename the BR-ID in `rules.md` and update
   `glossary.md` if the term itself changed
+- For every BR-ID added, modified, or renamed above, set its `Last updated`
+  date in `rules.md`'s Rule Index to today
 
 For `behavior.md`:
 
@@ -132,7 +134,6 @@ For `behavior.md`:
   matching the BR-ID
 - For REMOVED BR-IDs, delete the corresponding scenario section from
   `behavior.md`
-- Update the BR-ID anchor's `last-updated` date in `behavior.md` to today
 
 This is the **mechanical input that `/dflow:verify` later uses** for the
 rules.md ↔ behavior.md drift check (see `references/drift-verification.md`).

package/templates/brownfield/references/git-integration.md

@@ -181,7 +181,6 @@ diff. That breaks:
 - `git blame` on lines that crossed the rename boundary
 - PR diff quality (reviewers see two unrelated big-blob changes
   instead of one rename + small content diff)
-- `/dflow:verify` and other tools that walk feature history
 
 This is a known weakness of OpenSpec's directory-rename pattern; Dflow
 deliberately avoids it by mandating `git mv`.

package/templates/brownfield/references/init-project-flow.md

@@ -49,8 +49,8 @@ Report findings plainly:
 >  - `dflow/specs/`: not yet present → greenfield Dflow setup
 >  - `specs/`: present → legacy / other-tool directory; Dflow V1 will not
 >    migrate or modify it
->  - `CLAUDE.md`: present → will not overwrite; I'll offer a snippet
->    to merge into it"
+>  - `CLAUDE.md`: present → I'll append a marked Dflow block (shown in
+>    the preview); a merge snippet only if there's a marker conflict"
 
 Or:
 
@@ -162,9 +162,10 @@ Wait for answers.
 >
 > If you select any agent, Dflow will create
 > `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical guide. Root-level
-> tool files stay thin and point back to that guide. Existing tool files are
-> never overwritten; Dflow writes merge snippets under `dflow/specs/shared/`
-> instead."
+> tool files stay thin and point back to that guide. Existing user content is
+> never overwritten; Dflow appends a marked Dflow block (shown in the preview)
+> and refreshes it in place on re-run. Merge snippets under
+> `dflow/specs/shared/` are used only if Dflow markers conflict."
 
 **→ Transition (step-internal)**: Step 2 complete. Announce
 > "Step 2 complete (project information captured). Entering Step 3:
@@ -228,16 +229,17 @@ vendored workflow bundle). Compute the destination path:
 | `scaffolding/Git-principles-trunk.md` | `dflow/specs/shared/Git-principles-trunk.md` |
 | `scaffolding/AI-AGENT-GUIDE.md` | `dflow/specs/shared/AI-AGENT-GUIDE.md` when at least one AI agent is selected |
 | generated tool shim | `AGENTS.md`, `CLAUDE.md`, or `.github/copilot-instructions.md` when selected and missing |
-| generated merge snippet | `dflow/specs/shared/*-snippet.md` when the selected tool file already exists |
+| marked Dflow block | appended to a selected existing tool file unless it already points to `AI-AGENT-GUIDE.md`; refreshed in place on re-run |
+| fallback merge snippet | `dflow/specs/shared/*-snippet.md` only when the selected tool file has conflicting or malformed Dflow markers |
 
 ### 3.3 Present the preview
 
-Present the complete file list as two tables, separating create vs
+Present the complete file list as two tables, separating create / update vs
 skip, and wait for developer confirmation:
 
 > "Based on Step 1 inventory + Step 2 answers, here is what I'll do:
 >
-> **Will create ({N} files):**
+> **Will create / update ({N} files):**
 >
 > | Path | Source |
 > |---|---|
@@ -250,7 +252,7 @@ skip, and wait for developer confirmation:
 > | `dflow/specs/shared/_overview.md` | optional (you picked it) |
 > | `dflow/specs/shared/Git-principles-trunk.md` | mandatory (selected Git policy) |
 > | `dflow/specs/shared/AI-AGENT-GUIDE.md` | selected AI agent guide |
-> | `CLAUDE.md` | selected tool shim because repo has no CLAUDE.md |
+> | `CLAUDE.md` | marked Dflow block appended to existing CLAUDE.md (shown in preview) |
 >
 > **Will skip ({M} files — already present):**
 >
@@ -325,11 +327,24 @@ guide.
 For each selected tool-specific file (`AGENTS.md`, `CLAUDE.md`,
 `.github/copilot-instructions.md`):
 
+(checked in this order — the first matching rule wins):
+
 - if the target file does not exist, create a small shim at the target
   path that points to `dflow/specs/shared/AI-AGENT-GUIDE.md`
-- if the target file already exists, do not overwrite it; write a merge
-  snippet under `dflow/specs/shared/` and report that the developer
-  should merge it manually
+- if the target file contains conflicting or malformed Dflow markers, do not
+  edit it; write a fallback merge snippet under `dflow/specs/shared/` and
+  report that the developer should merge it manually
+- if the target file already contains a single well-formed Dflow marked block,
+  replace that block in place (idempotent refresh) and keep the rest of the
+  file unchanged
+- if the target file is an existing whole-file Dflow-generated shim, refresh it
+  in place
+- if the target file already points to the guide through the developer's own
+  pointer (and has no Dflow marked block), leave it untouched
+- otherwise preserve the existing content and append a marked Dflow block at
+  the end of the file, keeping the file's dominant line ending; show that block
+  in the preview, and refresh that same block on re-run. If the developer later
+  deletes the block, a later `init` / `configure-agents` run appends it again
 
 ### 4.4 Directory-only entries
 
@@ -354,7 +369,7 @@ Summarise what actually happened and point at the next command.
 ```
 Init complete. Summary:
 
-  Created ({N} files):
+  Created / Updated ({N} files):
     ✓ dflow/specs/features/active/.gitkeep
     ✓ dflow/specs/features/completed/.gitkeep
     ✓ dflow/specs/features/backlog/.gitkeep
@@ -363,7 +378,7 @@ Init complete. Summary:
     ✓ dflow/specs/migration/tech-debt.md
     ✓ dflow/specs/shared/_overview.md
     ✓ dflow/specs/shared/Git-principles-trunk.md
-    ✓ CLAUDE.md (seeded from scaffolding snippet)
+    ✓ CLAUDE.md (marked Dflow block appended)
 
   Skipped ({M} files already present):
     - (none this run)
@@ -412,9 +427,8 @@ Remind the developer to review files that have `{placeholder}` tokens
 still in them:
 
 > "A few files still have `{placeholder}` tokens that need your input:
->  - `dflow/specs/shared/_overview.md`: `{業務領域}`, `{團隊}`,
->    `{使用者規模}`
->  - `CLAUDE.md`: `{業務領域}`
+>  - `dflow/specs/shared/_overview.md`: the Business Domain and Technical
+>    Architecture fields (e.g. primary domain, stakeholders, user scale, stack)
 >
 >  These are fine to leave for now; fill them in during your next
 >  review pass."

package/templates/brownfield/references/modify-existing-flow.md

@@ -1,15 +1,15 @@
 # Modify Existing Feature Workflow
 
-Step-by-step guide for when a developer triggers `/dflow:modify-existing` or `/dflow:bug-fix` (or natural language implying a modification task — see SKILL.md § Workflow Transparency for the auto-trigger safety net).
+Step-by-step guide for when a developer triggers `/dflow:modify-existing` or `/dflow:bug-fix` (or natural language implying a modification task — see AI-AGENT-GUIDE.md § Workflow Transparency for the auto-trigger safety net).
 
 **Step Gates** in this flow (stop-and-confirm before proceeding):
 - Step 2 → Step 3 (baseline captured → analyze business logic embedded in delivery/entrypoint code: presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures)
 - Step 4 → Step 5 (extraction decision → start implementation)
 - Step 5 → Step 6 (implementation done → update artifacts)
 
-All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See SKILL.md § Workflow Transparency for the full transparency protocol and confirmation signals.
+All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow Transparency for the full transparency protocol and confirmation signals.
 
-**Ceremony adjustment when triggered by `/dflow:bug-fix`**: treat as lightweight — use the Lightweight Spec Template at the end of this file instead of the full spec, and Step 4 (extraction) may default to "defer and record in tech-debt.md" unless the bug itself is in extractable logic. T2 still generates a concise `Implementation Tasks` checklist (see Step 4).
+**Ceremony adjustment when triggered by `/dflow:bug-fix`**: treat as lightweight — use the Lightweight Spec Template (see `templates/lightweight-spec.md`) instead of the full spec, and Step 4 (extraction) may default to "defer and record in tech-debt.md" unless the bug itself is in extractable logic. T2 still generates a concise `Implementation Tasks` checklist (see Step 4).
 
 ## Mindset
 
@@ -31,7 +31,7 @@ This step has two parallel concerns:
 
 **Part A — Determine the Ceremony Tier (T1 / T2 / T3)**
 
-Dflow runs three ceremony tiers (full table in SKILL.md § Ceremony Scaling).
+Dflow runs three ceremony tiers (full table in AI-AGENT-GUIDE.md § Ceremony Scaling).
 For a modification, AI judges which tier fits before deciding what to
 produce:
 
@@ -141,7 +141,7 @@ add a row:
 | {新 SPEC-ID} | {新 slug} | {today} | in-progress |
 ```
 
-This update is **part of the same change set** (the developer commits
+This update is **part of the same change set** (offer to commit
 both at once; commit message should mention "Add follow-up reference to
 `{新 SPEC-ID}`"). The reverse link is a derived index — the new
 feature's `follow-up-of` field is the authoritative source.
@@ -152,8 +152,6 @@ phase's content).
 
 ## Step 2: Document Current Behavior (if no spec exists)
 
-## Step 2: Document Current Behavior (if no spec exists)
-
 This is critical. Before changing anything, capture what currently exists:
 
 ```
@@ -284,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).
@@ -360,7 +396,7 @@ Items marked *(post-6.3)* are re-verified after the documentation merge in 6.3 l
 - [ ] Extracted logic (if Step 4 decided "extract now") lives under `src/Domain/` as framework-pure code
 - [ ] `Implementation Tasks` section (`phase-spec.md` or `lightweight-spec.md`): all tasks checked, or unchecked items explicitly labelled as follow-up
 - [ ] *(post-6.3)* `dflow/specs/domain/{context}/behavior.md` has a section anchor for every `BR-*` in ADDED / MODIFIED entries; REMOVED entries' anchors have been deleted (mechanical input for `/dflow:verify`)
-- [ ] *(post-6.3)* `dflow/specs/domain/{context}/behavior.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
+- [ ] *(post-6.3)* every ADDED / MODIFIED / RENAMED BR's `Last updated` in `dflow/specs/domain/{context}/rules.md` is later than this spec's `created` date (mechanical drift guard)
 
 If any item fails, report the gap and pause — don't proceed to 6.2.
 
@@ -416,33 +452,3 @@ new follow-up directory; that happens at `/dflow:finish-feature` time.
 
 Only announce "change complete" after the appropriate archival step
 above (or the Step 6.3 docs sweep) is done.
-
-## Lightweight Spec Template (for bug fixes)
-
-For small bug fixes, a lightweight spec is enough:
-
-```markdown
----
-id: BUG-042
-title: Fix rounding inconsistency in expense calculation
-status: in-progress
-bounded-context: Expense
-created: 2025-02-12
----
-
-## Problem
-Entrypoint A uses Math.Round(amount, 0, MidpointRounding.AwayFromZero) (四捨五入)
-Entrypoint B uses Math.Floor(amount) (無條件捨去)
-They should both use the same rounding rule.
-
-## Expected Behavior
-Given an expense amount of 123.5 TWD
-When displayed or returned by any entrypoint
-Then it should show 124 (四捨五入 per accounting standard)
-
-## Root Cause
-Duplicated calculation logic — recorded in tech-debt.md
-
-## Fix
-Extract rounding to Money.Round() in Domain layer, both pages call it.
-```

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

@@ -1,6 +1,6 @@
 # New Feature Workflow
 
-Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natural language implying a new-feature task — see SKILL.md § Workflow Transparency for the auto-trigger safety net behavior).
+Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natural language implying a new-feature task — see AI-AGENT-GUIDE.md § Workflow Transparency for the auto-trigger safety net behavior).
 
 **Step Gates** in this flow (stop-and-confirm before proceeding):
 - Step 3 → Step 3.5 (domain concepts captured → confirm slug + directory + branch names)
@@ -8,9 +8,9 @@ Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natura
 - Step 6 → Step 7 (branch ready → start implementation)
 - Step 7 → Step 8 (implementation done → completion)
 
-All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See SKILL.md § Workflow Transparency for the full transparency protocol and confirmation signals.
+All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow Transparency for the full transparency protocol and confirmation signals.
 
-**Ceremony**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (T1 / T2 / T3) only applies to `/dflow:modify-existing` (see `references/modify-existing-flow.md` and SKILL.md § Ceremony Scaling).
+**Ceremony**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (T1 / T2 / T3) only applies to `/dflow:modify-existing` (see `references/modify-existing-flow.md` and AI-AGENT-GUIDE.md § Ceremony Scaling).
 
 ## Step 1: Intake — Understand the Request
 
@@ -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
@@ -188,7 +216,7 @@ Specifically ask about:
 Announce to developer:
 > "Spec is drafted — behavior scenarios, business rules, and edge cases are captured. Ready to plan the implementation (Domain layer design, interfaces, thin delivery/entrypoint code — presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures)? `/dflow:next` or reply 'OK' to continue, or tell me if the spec needs another iteration first."
 
-Wait for confirmation (`/dflow:next`, verbal OK, or implicit — see SKILL.md § Confirmation Signals) before entering Step 5.
+Wait for confirmation (`/dflow:next`, verbal OK, or implicit — see AI-AGENT-GUIDE.md § Confirmation Signals) before entering Step 5.
 
 ## Step 5: Plan the Implementation
 
@@ -325,7 +353,7 @@ AI reports `✓` / `✗` for every item before touching docs. Items marked *(pos
 - [ ] Every `EC-*` edge case is handled
 - [ ] Domain layer has **no** delivery-framework references (grep `src/Domain/`)
 - [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` contains a section anchor for every `BR-*` introduced by this spec (mechanical input for `/dflow:verify`)
-- [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
+- [ ] *(post-8.3)* `dflow/specs/domain/{context}/rules.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
 
 If any item fails, report the gap and pause — don't proceed to 8.2.
 
@@ -354,12 +382,14 @@ Ask these one-by-one; do not dump all five at once.
 
 ### 8.4 Archival
 
-For a single-phase feature, this is the closeout point. For a multi-phase
-feature, the developer typically reaches this point at the end of the
-final phase — at which time `/dflow:finish-feature` is the recommended
-trigger (it bundles steps 8.1 / 8.2 verification, BC sync, and archival
-into one explicit ceremony). Either path is acceptable; pick the one
-that matches the developer's habit.
+For a single-phase feature, this is the closeout point. If the feature has
+later phases still ahead, this phase is complete but the feature is not —
+don't archive yet; run `/dflow:new-phase` to start the next phase, not
+`/dflow:finish-feature` yet. For a multi-phase feature, the developer
+typically reaches this point at the end of the final phase — at which time
+`/dflow:finish-feature` is the recommended trigger (it bundles steps 8.1 /
+8.2 verification, BC sync, and archival into one explicit ceremony). Either
+path is acceptable; pick the one that matches the developer's habit.
 
 - [ ] `_index.md` `status` field changed to `completed`
 - [ ] All `phase-spec-*.md` files in the feature directory have `status:

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

@@ -20,7 +20,7 @@ adds a new phase to an in-progress feature only.
 - Step 6 → Step 7 (implementation done → complete the phase)
 
 All other step transitions are **step-internal**: announce "Step N complete,
-entering Step N+1" and proceed without waiting. See SKILL.md § Workflow
+entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow
 Transparency for the full transparency protocol and confirmation signals.
 
 ## Step 1: Read Active Feature Context
@@ -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: