dflow-sdd-ddd 0.9.0 → 0.11.0

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

@@ -28,7 +28,7 @@ are not available in the current AI tool:
 | `/dflow:bug-fix` | A defect can be described with expected vs actual behavior. |
 | `/dflow:new-phase` | An active feature needs another implementation slice. |
 | `/dflow:finish-feature` | Implementation is complete and needs drift closure. |
-| `/dflow:verify` | Specs, domain docs, implementation, and tests need consistency checks. |
+| `/dflow:verify` | A bounded context's domain docs (`rules.md` ↔ `behavior.md`) need a consistency / drift check. |
 | `/dflow:pr-review` | A change is ready for SDD/DDD review. |
 | `/dflow:report-dflow-feedback` | You found a Dflow issue or improvement and want a sanitized upstream feedback draft. |
 | `/dflow:status` | You need the current workflow state, current step, completed work, in-progress work, remaining work, pending decision, and next valid action. |
@@ -45,7 +45,7 @@ Machine-readable source for rendering tool-specific thin wrappers:
 | bug-fix | /dflow:bug-fix | Investigate a defect described by expected vs actual behavior. | expected vs actual | workflow |
 | new-phase | /dflow:new-phase | Add another implementation slice to an active feature. | feature id or phase goal | workflow |
 | finish-feature | /dflow:finish-feature | Close implementation with drift checks and archived feature state. | feature id | workflow |
-| verify | /dflow:verify | Check specs, domain docs, implementation, and tests for consistency. | area or feature id | workflow |
+| verify | /dflow:verify | Check a bounded context's domain docs (`rules.md` ↔ `behavior.md`) for consistency. | bounded context or all | workflow |
 | pr-review | /dflow:pr-review | Review a ready change for SDD/DDD alignment. | change or branch | workflow |
 | report-dflow-feedback | /dflow:report-dflow-feedback | Draft sanitized upstream feedback about Dflow. | issue or improvement | workflow |
 | status | /dflow:status | Report current workflow state and next valid action. | - | control |
@@ -53,6 +53,25 @@ Machine-readable source for rendering tool-specific thin wrappers:
 | cancel | /dflow:cancel | Abort the active workflow and return to free conversation. | - | control |
 <!-- dflow-command-registry:end -->
 
+## Routing Non-Command Input
+
+Not every developer message maps to a `/dflow:*` workflow. Route non-command
+input like this (supporting files live in the workflow bundle at
+`dflow/specs/shared/dflow-workflows/`):
+
+- **"I'm designing a domain model" / "How should I model X?"** → read
+  `references/ddd-modeling-guide.md`.
+- **"Quick question about..." / "How does X work?"** → check
+  `dflow/specs/domain/` first and answer from the documented domain knowledge.
+- **"I'm creating a branch"** → read `references/git-integration.md`.
+- **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
+  guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
+  anything upstream automatically.
+- **Anything else code-related** → assess whether it touches business logic. If
+  it does, use the auto-trigger safety net (suggest the matching `/dflow:*`
+  command and wait for confirmation — see § Workflow Transparency); if not, help
+  directly with no ceremony.
+
 ## Status / Control Commands
 
 `/dflow:status` reports active workflow state. Include these fields: workflow,
@@ -71,6 +90,67 @@ workflow was cancelled.
 When no workflow is active, `/dflow:next` and `/dflow:cancel` must report that
 there is no active workflow to advance or cancel.
 
+## Workflow Transparency
+
+Dflow uses a hybrid interaction design: `/dflow:*` commands are the primary
+entry, natural-language auto-trigger is a safety net, and tiered transparency
+keeps the developer aware of where they are in a workflow.
+
+### Auto-Trigger Safety Net
+
+When natural language implies a development task, detect the intent — but do
+**not** auto-enter a workflow. Instead:
+
+1. State your judgment clearly:
+   > "I think this is a new-feature task."
+2. Offer the developer three options:
+   - Type `/dflow:new-feature` to start explicitly
+   - Reply "OK" / "繼續" to confirm this workflow
+   - Or correct the workflow (e.g., "no, this is a bug fix")
+3. Wait for confirmation before entering any workflow.
+
+This addresses three failure modes of pure auto-trigger: missed triggers, wrong
+workflow selection, and invisible state.
+
+### Three-Tier Transparency
+
+During an active workflow, communicate at three levels — no more, no less:
+
+| Level | Trigger point | AI behavior |
+|---|---|---|
+| **Flow entry (must confirm)** | After judging the workflow from NL | Stop and wait for confirmation (command, "OK", or implicit) |
+| **Step gate (notify + optional confirm)** | Before major milestones | Announce the transition; if the developer provides next-step input, treat it as implicit confirmation |
+| **Step-internal (notify only)** | Step N → Step N+1 | Announce "Step N complete, entering Step N+1" — do not wait |
+
+The specific step-gate positions for each workflow live in that flow's own file
+(`dflow/specs/shared/dflow-workflows/references/<flow>.md`), which is the source
+of truth for its gate sequence.
+
+### Confirmation Signals (NL ↔ Command Equivalence)
+
+Any of these count as "proceed to next step" — accept whichever the developer
+uses:
+
+- **Command**: `/dflow:next`
+- **Verbal (English)**: OK / yes / continue / go ahead / sounds good / proceed
+- **Verbal (Chinese)**: 好 / 對 / 繼續 / 可以 / 沒問題
+- **Implicit**: the developer provides the information needed for the next step
+  (e.g., the AI asks "Which Aggregate?" and the developer answers with the
+  Aggregate name → implicit confirmation)
+
+The implicit-confirmation rule matters — do not turn every transition into a
+ceremony where the developer must say "OK" before every sentence.
+
+### Completion Checklist Skip Guard
+
+Completion checklists and their step ordering live in the flow files and run at
+the gate each flow specifies (the feature-level completion gate in
+`new-feature-flow` / `modify-existing-flow`, the phase-level gate in
+`new-phase-flow`). Do not run a checklist opportunistically. But if the
+developer skips the gate and commits directly, use the auto-trigger safety net
+to prompt — "It looks like you're wrapping up — should I run the Step N
+completion checklist?" — before giving commit guidance.
+
 ## Source of Truth
 
 Dflow-owned project documents live under `dflow/specs/`.
@@ -85,6 +165,41 @@ Dflow-owned project documents live under `dflow/specs/`.
 | Completed feature snapshots | `dflow/specs/features/completed/` |
 | Technical debt | `dflow/specs/architecture/tech-debt.md` or `dflow/specs/migration/tech-debt.md` |
 
+### Project Structure
+
+The full `dflow/specs/` layout Dflow seeds and maintains:
+
+```
+dflow/specs/
+├── shared/                         # Project-level governance docs (seeded by npx dflow-sdd-ddd init)
+│   ├── _overview.md
+│   └── _conventions.md
+├── domain/
+│   ├── glossary.md
+│   ├── context-map.md              # Bounded Context relationships
+│   └── {bounded-context}/
+│       ├── context.md
+│       ├── models.md               # Aggregates, Entities, VOs
+│       ├── rules.md                # Business rules index (BR-ID + one-line)
+│       ├── behavior.md             # Consolidated behavior (Given/When/Then)
+│       └── events.md               # Domain Events catalog
+├── features/
+│   ├── active/
+│   │   └── {SPEC-ID}-{slug}/       # One feature = one directory
+│   │       ├── _index.md           # Feature dashboard + BR Snapshot + Resume Pointer
+│   │       ├── phase-spec-YYYY-MM-DD-{slug}.md   # T1: 0..N phase specs
+│   │       └── lightweight-YYYY-MM-DD-{slug}.md  # T2: 0..N lightweight specs
+│   │                                             #     (or BUG-{NUMBER}-{slug}.md)
+│   ├── completed/                  # Done (whole feature directory archived here)
+│   └── backlog/
+│   #
+│   # SPEC-ID format: SPEC-YYYYMMDD-NNN; slug follows discussion language (中文 / 英文 both OK).
+│   # T3 trivial changes have NO independent file — just a row in _index.md Lightweight Changes.
+└── architecture/
+    ├── decisions/                  # Architecture Decision Records
+    └── tech-debt.md
+```
+
 ## Core Rules
 
 1. Spec before code: meaningful behavior changes need a spec or lightweight bug spec before implementation.
@@ -93,33 +208,110 @@ Dflow-owned project documents live under `dflow/specs/`.
 4. Check drift before calling work complete.
 5. Follow `dflow/specs/shared/_conventions.md`, especially `## Prose Language`.
 
-## 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.
+## Ceremony Scaling
+
+Dflow uses three tiers — **T1 Heavy / T2 Light / T3 Trivial** — chosen by the AI
+per change. `/dflow:new-feature` and `/dflow:new-phase` always default to T1 (no
+judgement needed). The criteria below apply when `/dflow:modify-existing` or
+`/dflow:bug-fix` decides which tier fits a modification.
+
+| Tier | Scenario | Output | Command / Trigger |
+|---|---|---|---|
+| **T1 Heavy** | New feature, new phase, new Aggregate / BC, architectural change, new BR | Independent `phase-spec-YYYY-MM-DD-{slug}.md` placed in the feature directory + `_index.md` Phase Specs row + refresh BR Snapshot. For a new Aggregate / BC also create an `aggregate-design.md` from `templates/aggregate-design.md` **in the feature directory** (working worksheet; the durable summary stays in `models.md`) + update `context-map.md` + `events.md`. | `/dflow:new-feature` / `/dflow:new-phase` |
+| **T2 Light** | Bug fix (logic error), UI input validation tweak, flow branch change — has BR Delta | Independent `lightweight-{YYYY-MM-DD}-{slug}.md` (or `BUG-{NUMBER}-{slug}.md`) inside the feature directory + `_index.md` Lightweight Changes row (outbound link) + refresh BR Snapshot. Confirm the fix lands in the correct architectural layer. | `/dflow:bug-fix` or `/dflow:modify-existing` (lightweight branch) |
+| **T3 Trivial** | Button colour, copy/text fix, typo, formatting, pure comments — **no BR change, no Domain concept change, no data structure change** | **Inline row in `_index.md` Lightweight Changes only** (no independent spec file) | `/dflow:modify-existing` (`_index-only` branch) |
+
+**T3 criteria** (the AI must satisfy **all four** before classifying T3):
+
+1. No BR-ID change (no ADDED / MODIFIED / REMOVED / RENAMED business rule)
+2. No Domain concept added or changed (Aggregate / Entity / VO / Event)
+3. No data structure change (table, column, relation, index)
+4. Only changes UI surface (colour, text, layout), pure comments, or pure formatting
+
+If any criterion fails → drop to T2; if Domain / BR / data structure is touched → escalate to T1.
+
+**Below T3 — Dflow doesn't track at all**: pure typo fixes, commit-message
+typos, pure formatting commits (e.g. `prettier` / `dotnet format` auto-runs).
+You can `git commit` directly without writing even a T3 inline row.
+
+**DDD Modeling Depth (still informs T1 scope)**:
+
+- New Aggregate / BC → **Full**: create an `aggregate-design.md` from `templates/aggregate-design.md` in the feature directory (durable summary stays in `models.md`), update `context-map.md`, define Domain Events in `events.md`
+- Feature within an existing BC → **Standard**: confirm Aggregate ownership, update `models.md` and `rules.md`
+- T2 / T3 → confirm the fix lands in the correct architectural layer; no design-level updates required
+
+## Behavior Source of Truth (rules.md + behavior.md)
+
+Each Bounded Context has two complementary files that together describe the
+system's current behavior:
+
+- **`rules.md`** — declarative index: lists each BR-ID with a one-line summary.
+  Quick lookup, easy to scan.
+- **`behavior.md`** — scenario-level detail: the full Given/When/Then scenarios
+  for each BR-ID, including Aggregate state transitions and Domain Events. This
+  is the consolidated source of truth for "what does the system actually do
+  right now?"
+
+`dflow/specs/features/completed/` is a historical archive (individual change
+records). `behavior.md` is the **merged current state** — when a feature is
+completed, the AI merges its scenarios into `behavior.md`; when behavior is
+modified, the AI updates the corresponding section to reflect the new behavior
+(git preserves history). See the `behavior.md` template in the workflow bundle
+at `dflow/specs/shared/dflow-workflows/templates/behavior.md`.
+
+## Guiding Questions by Activity
+
+SDD has five conceptual activities (Understanding / Domain Modeling / Spec
+Writing / Implementation Planning / Testing Strategy) that the AI walks the
+developer through inside a workflow. They cut across workflow steps — Activity 2
+(Domain Modeling) might span Step 2 and Step 3 of new-feature-flow, for example.
+
+**Activity markers in the phase-spec template**: each section in
+`templates/phase-spec.md` carries an HTML comment (e.g.,
+`<!-- Fill timing: Activity 2: Domain Modeling -->`) indicating the activity in
+which that section should be filled. These markers align with the activities
+below and are used by `/dflow:status` and the completion checklist to track
+progress. When guiding a developer, fill sections in activity order; do not jump
+ahead to Activity 4 (Implementation Planning) before Activity 3 (Spec Writing)
+is agreed. The `Implementation Tasks` section at the end of the template is
+produced by the AI at the end of Activity 4 — see new-feature-flow.md Step 5 /
+new-phase-flow.md Step 4 / modify-existing-flow.md Step 3.
+
+Note: the phase-spec template HTML comments cover Activity 1–4; Activity 5
+(Testing Strategy) is a conceptual category folded into the Test Strategy
+section that the template marks with Activity 4 timing. In `new-phase-flow`,
+Activity 5 is exercised operationally in Step 6 when implementation and tests
+are verified against the phase-spec before Step 7 completion.
+
+### Activity 1: Understanding (What & Why)
+- What problem does this solve? Who asked for it?
+- What's the expected behavior from the user's perspective?
+- Are there existing specs or domain docs related to this?
+
+### Activity 2: Domain Modeling (DDD)
+- Which Bounded Context? (Check context-map.md)
+- What Aggregate does this belong to? Or is it a new Aggregate?
+- What are the invariants this Aggregate must protect?
+- Are there Value Objects to extract? (Money, DateRange, Address...)
+- Will this produce Domain Events? Who consumes them?
+- Does this cross Aggregate / Context boundaries? → Need an integration strategy
+
+### Activity 3: Spec Writing
+- Write the spec using the template (see `templates/phase-spec.md`)
+- Define Given/When/Then with Aggregate state transitions
+- Document Domain Events produced and consumed
+- Identify edge cases around Aggregate invariants
+
+### Activity 4: Implementation Planning
+- Domain layer: Aggregate design, Value Objects, Domain Events
+- Application layer: Command / Query, handlers, validation
+- Infrastructure: Repository implementation, persistence / ORM configuration
+- Presentation: API endpoint design
+
+### Activity 5: Testing Strategy
+- Domain unit tests: invariants, business rules, value object equality
+- Application tests: command / query handler behavior
+- Integration tests: repository, external services
 
 ## Workflow Steps
 

package/templates/greenfield/scaffolding/CLAUDE-md-snippet.md

@@ -5,12 +5,10 @@
 > Source: `scaffolding/CLAUDE-md-snippet.md`
 > Purpose: a minimal block you paste into (or replace with) your
 > project's root `CLAUDE.md` when adopting Dflow.
-> For the Greenfield track, the full reference template lives in the
-> in-project bundle at
-> `dflow/specs/shared/dflow-workflows/templates/CLAUDE.md` (projected by
-> `dflow init`) — if you want the complete legacy Claude-specific version,
-> use that instead. New CLI init output uses `AI-AGENT-GUIDE.md` plus a
-> generated `CLAUDE.md` shim.
+> New CLI init output uses `dflow/specs/shared/AI-AGENT-GUIDE.md` as the
+> canonical guide plus a thin generated `CLAUDE.md` shim. This snippet is
+> only the older Claude-specific two-H2 layout, for when you intentionally
+> want that shape in your project's root `CLAUDE.md`.
 
 ---
 
@@ -23,8 +21,7 @@
   Claude-specific two-H2 layout in your project's root `CLAUDE.md`.
 
 The two-H2 structure (`System Context` / `Development Workflow`) is intentional and must be
-preserved — it matches the Dflow skill's `templates/CLAUDE.md` and
-keeps every project's `CLAUDE.md` scannable for AI in the same shape.
+preserved — it keeps every project's `CLAUDE.md` scannable for AI in the same shape.
 
 ---
 
@@ -67,7 +64,7 @@ Presentation → Application → Domain ← Infrastructure
 
 ### Project Structure
 
-完整 specs 目錄結構見 Dflow skill `SKILL.md` § "Project Structure"。
+完整 specs 目錄結構見 `AI-AGENT-GUIDE.md` § Source of Truth。
 以下只列本專案當前狀態（Dflow CLI init 建立後可能還未全填）：
 
 ```
@@ -161,13 +158,11 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 
 ## Notes
 
-- This snippet is intentionally lighter than the in-project bundle
-  template at `dflow/specs/shared/dflow-workflows/templates/CLAUDE.md`. If
-  you want the full version (with detailed flow descriptions per slash
-  command), use that template instead
+- This snippet is intentionally minimal — the older Claude-specific two-H2
+  layout, not a full restatement of Dflow's logic
 - The snippet does NOT re-copy the Dflow decision tree, Ceremony
-  Scaling criteria, or per-flow step details — those live in the
-  skill and change when the skill evolves
+  Scaling criteria, or per-flow step details — those live in
+  `AI-AGENT-GUIDE.md` and the workflow bundle, and change as Dflow evolves
 - Re-running the Dflow CLI init command (`dflow init`, or `npx dflow-sdd-ddd init`
   when using the no-install path) will NOT overwrite an existing `CLAUDE.md`;
   if you want to re-sync, merge manually

package/templates/greenfield/scaffolding/Git-principles-trunk.md

@@ -58,7 +58,7 @@ gh pr create --base main --fill
 
 - **Short-lived feature branches**: typically hours to a few days, not
   weeks. Encourage splitting large features into multiple phase-specs
-  and merging each phase to `main` (see Dflow's Ceremony Scaling +
+  and merging each phase to `main` (see `AI-AGENT-GUIDE.md` § Ceremony Scaling +
   `/dflow:new-phase`)
 - **Main is always releasable**: feature flags or dark launches for
   incomplete functionality; CI must be green on `main` at all times

package/templates/greenfield/scaffolding/_conventions.md

@@ -8,15 +8,16 @@
 > Audience: engineers writing specs; AI assistants producing spec drafts.
 
 This file captures **project-level** conventions only. Template shapes
-and Ceremony criteria are defined by the Dflow skill; here we just
-record how *this* project fills them in.
+and Ceremony criteria are defined by Dflow itself (the Ceremony tier criteria
+live in `AI-AGENT-GUIDE.md` § Ceremony Scaling; template shapes live in the
+workflow bundle); here we just record how *this* project fills them in.
 
 ---
 
 ## Where Specs Live
 
 All spec documents live under `dflow/specs/`. The feature directory pattern
-and file names follow Dflow (see the Dflow skill § "Project Structure"
+and file names follow Dflow (see `AI-AGENT-GUIDE.md` § Source of Truth
 for the full tree):
 
 ```
@@ -119,8 +120,8 @@ Project-specific guidance when filling these templates:
 
 ## Ceremony Scaling (Project Application)
 
-The Dflow skill defines three tiers — **T1 Heavy / T2 Light / T3
-Trivial**. See the Dflow skill § "Ceremony Scaling" for the full
+Dflow defines three tiers — **T1 Heavy / T2 Light / T3
+Trivial**. See `AI-AGENT-GUIDE.md` § Ceremony Scaling for the full
 criteria table. We do not re-define the tier criteria here; this
 section records how *this* project applies them in borderline
 situations.
@@ -132,9 +133,9 @@ situations.
 | {e.g. EF configuration tweak in Infrastructure} | T3 if no Domain change | Infra-only; inline row in `_index.md` |
 | {e.g. Domain Event payload extension} | T1 | Event contract change affects cross-context consumers |
 
-### DDD Modeling Depth (Dflow skill § Ceremony Scaling)
+### DDD Modeling Depth (`AI-AGENT-GUIDE.md` § Ceremony Scaling)
 
-The Dflow skill further distinguishes:
+Dflow further distinguishes:
 
 - **Full** (new Aggregate / new BC): use `templates/aggregate-design.md`
   + update `context-map.md` + define events in `events.md`
@@ -170,7 +171,7 @@ and `/dflow:new-phase` flows; the project-level convention is simply
 - [Git principles](Git-principles-{gitflow|trunk}.md)
 - [Context map](../domain/context-map.md)
 - [Glossary](../domain/glossary.md)
-- Dflow skill `SKILL.md` — canonical source for Ceremony Scaling, flow
+- `AI-AGENT-GUIDE.md` — canonical source for Ceremony Scaling, flow
   selection, and template shapes.
 - Dflow skill `references/ddd-modeling-guide.md` — DDD tactical
   pattern reference.

package/templates/greenfield/templates/_index.md

@@ -89,7 +89,7 @@ Template note (for AI):
 > T3 行：inline 完整描述一句話 + 標籤（如 `[cosmetic]` / `[text]` /
 >        `[format]`）；T3 不產獨立 spec 檔
 >
-> Tier 判準見 SKILL.md § Ceremony Scaling 三層表。
+> Tier 判準見 AI-AGENT-GUIDE.md § Ceremony Scaling 三層表。
 
 | Date | Tier | Description | Commit |
 |---|---|---|---|

package/templates/greenfield/templates/aggregate-design.md

@@ -13,6 +13,12 @@ created: {YYYY-MM-DD}
 ## Invariants
 
 > 必須永遠為真的規則。這是 Aggregate 存在的理由。
+> 主體列 **boundary invariants**(需同時看到 Aggregate 內多個物件的狀態才能判的規則)。
+> 單一物件可判的 local constraint 不列這裡 — 純格式/必填走 Validator、有 domain
+> 語意走 VO / Entity constructor。跨 instance 的規則(唯一性、僅一筆 active)可列,
+> 但標 `set-based` 並在 Behavior on Violation 寫明 store-level guard(unique /
+> partial index、concurrency token;見 ddd-modeling-guide 的 Invariant
+> Classification 與 Set-Based 段)。
 
 | ID | Invariant | Behavior on Violation |
 |---|---|---|

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

@@ -6,15 +6,24 @@
 
 ## Contexts
 
-| Bounded Context | Responsibility | Owner / Team | Primary Module | Notes |
-|---|---|---|---|---|
-| {Context name} | {業務責任} | {owner} | `{module/project}` | {optional notes} |
+| Bounded Context | Responsibility | Subdomain Type | Owner / Team | Primary Module | Notes |
+|---|---|---|---|---|---|
+| {Context name} | {業務責任} | core / supporting / generic | {owner} | `{module/project}` | {optional notes} |
+
+> **Subdomain Type** — 判別問句:「這塊功能換成現成 SaaS / 套件,系統的差異化會消失嗎?」
+> (差異化不限商業競爭優勢;內部系統指獨特的營運優勢 / 任務成果。)會 → `core`;
+> 不會、但需要為自家流程客製 → `supporting`(必要、常需客製、非差異化);
+> 不會、且現成方案存在 → `generic`。多數 BC 是 supporting,`core` 通常只有 1–2 個;
+> 全標 core = 沒分類。分類是可修訂的初判,改判時更新本欄並在 Notes 留一行理由。
+> 它決定建模深度(見 `references/ddd-modeling-guide.md`
+> § Subdomain-Aware Modeling Depth),但**不**降低 BR 紀錄、Tier ceremony、
+> 或安全 / 測試 / 可靠性要求。
 
 ## Relationships
 
 | Upstream | Downstream | Relationship Type | Published Language | ACL | Events |
 |---|---|---|---|---|---|
-| {Upstream context} | {Downstream context} | {Customer/Supplier, Conformist, ACL, Shared Kernel, etc.} | {shared terms / contract} | {Yes/No + location} | {event names or n/a} |
+| {Upstream context} | {Downstream context} | {Customer/Supplier, Conformist, ACL, Shared Kernel, Separate Ways, Big Ball of Mud (BBoM), OHS, etc.} | {shared terms / contract} | {Yes/No + location} | {event names or n/a} |
 
 ## Integration Notes
 

package/templates/greenfield/templates/events.md

@@ -12,7 +12,10 @@
 
 ## Event Flow Notes
 
-- {事件發生時序、交易邊界、重試或一致性注意事項}
+- {事件發生時序、交易邊界、重試或一致性注意事項;跨 aggregate 的 async(eventual
+  consistency)event chain,handler 重試耗盡的最終失敗若造成 business-visible 後果
+  (補償/權益/金流/庫存/合規/人工對帳)→ 升級為 BR/EC 寫進 behavior.md 與 spec,
+  best-effort 副作用(通知/logging)記這裡或 tech-debt 即可}
 
 ## Open Questions
 

package/templates/greenfield/templates/lightweight-spec.md

@@ -11,7 +11,7 @@ branch: bugfix/BUG-{NUMBER}-{short-description}
 Template note (for AI):
   This is the **lightweight-spec** template — it corresponds to T2 Light
   ceremony in the three-tier Ceremony Scaling (T1 Heavy / T2 Light /
-  T3 Trivial; see SKILL.md § Ceremony Scaling for the tier criteria).
+  T3 Trivial; see AI-AGENT-GUIDE.md § Ceremony Scaling for the tier criteria).
 
   - T1 Heavy → use templates/phase-spec.md instead
   - T2 Light → THIS template; produces an independent file

package/templates/greenfield/templates/phase-spec.md

@@ -21,7 +21,7 @@ Template note (for AI):
 
   Each section below carries an HTML comment indicating its fill-in activity (Activity 1-4).
   These activity markers let /dflow:status and the completion checklist track progress.
-  Activities correspond to SKILL.md § Guiding Questions by Activity:
+  Activities correspond to AI-AGENT-GUIDE.md § Guiding Questions by Activity:
     Activity 1: Understanding (What & Why)
     Activity 2: Domain Modeling (BC, Aggregate, VO, Events)
     Activity 3: Spec Writing (Behavior + Rules + Edge Cases)