dflow-sdd-ddd 0.14.0 → 0.15.0

package/templates/brownfield/templates/analysis.md

@@ -0,0 +1,79 @@
+<!-- dflow-shape: brownfield/analysis.md 1 — keep this line: dflow doctor reads it -->
+<!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+<!-- Placement: this template fills two paths. Cross-Context Flows and Function / Role Index are always written in the domain-root copy, `dflow/specs/domain/analysis.md`, whoever owns what they describe, and left as they are in a per-context copy - including in a project that has only one context. A hotspot row goes in the copy that holds the knowledge it is stuck on, and a question row in the copy that will hold its answer, as Open Questions and Hotspots says. For every other entry, ask who owns what the entry describes. A status field is owned by the context whose entity stores it - the entity that context's models.md defines, or will define. A derived figure is owned by the context that computes it, not the ones it reads from. A mechanism is owned by the context whose behavior it explains. One context owns it: the entry goes in that context's `dflow/specs/domain/{context}/analysis.md`, and it stays there even when another context reads the field, triggers a transition or supplies data it reads. No one context owns it - two contexts own it equally, or a mechanism explains behavior in several contexts equally: it goes in the domain-root copy. -->
+<!-- Entry ids: every entry carries one. The prefix is the section's - `FL` flows, `LC` lifecycles, `RM` read models, `MX` mechanisms, `FN` function rows, `HS` hotspot rows - and the number is sequential within this copy and never reused; an entry keeps its id for as long as it stays in this copy. A subsection carries its id in its heading (`### LC-01: {name}`); in the two tables that have an ID column, each row carries it there. Cite an entry in this file by its id alone. Cite one in the other copy, or from any other document, as path then id: `domain/{context}/analysis.md LC-01`. Until what a citation points at has an entry of its own, write its name instead of an id; whenever you update this file, replace any such name whose entry now exists. An entry that moves to the other copy takes a new id there: update whatever cited the old one - search for its path and id together, and for the bare id in the file it left. -->
+<!-- Referring to a rule: a cell that names what a business rule decides refers to that rule and holds nothing else; a cell decided by no rule holds the value itself. Refer to a rule by its BR-ID alone only from the copy of the context whose rules.md holds it; anywhere else - always in the domain-root copy - write its path then its id: `domain/{context}/rules.md BR-001`. A cell holding a BR-ID, alone or after its path, is a reference; anything else is a recorded value. Until a rule has a BR-ID, write the rule's name; whenever you update this file, replace any rule name whose BR-ID now exists. -->
+<!-- Evidence convention: every entry carries its evidence in the form `{code | data | confirmed by {role} | document | inferred | assumed} - {what to open to re-check} ({date})`. A subsection ends with one line that reads `Evidence: ` followed by it; a table row puts it in its Evidence column. For `data`, the middle slot also carries the counting rule the number used. `document` is a written source outside the code - a regulation, an internal policy, a ticket, an existing spec. When you take a claim from one of these rather than re-checking it yourself, the date is the one that source gives, not the day you copied it. `inferred` is a conclusion drawn from code or data rather than read off either one: name what it was drawn from. A question nobody has answered yet is not an entry: record it where the Open Questions and Hotspots section says. A value that rests on nothing a reader can open is `assumed`: a guess, or a fact whose only home is a private note, a chat log, or one person's AI memory. Say what it rests on, and record the question of confirming it where the Open Questions and Hotspots section says. -->
+
+# Domain Analysis
+
+> System-level knowledge that no single bounded-context document holds: flows
+> that cross contexts, the lifecycle a status field moves through, how derived
+> figures are computed, the mechanisms behind observed behavior, who reaches
+> which function, and the spots in them this project keeps working around.
+> Where an entry relies on a rule, a model, or a context relationship, link it
+> by BR-ID, model name, or section instead of restating it. Where this project
+> has already written one of these somewhere else, leave that text where it is
+> and give it a row or a subsection here that says where to read it.
+
+## Cross-Context Flows
+
+<!-- Global file only. One subsection per ordered flow whose steps are owned by more than one context; the table is the record, one row per step in order. A flow that stays inside one context is not recorded here: its scenarios belong in behavior.md. A statement about two contexts that holds without an order - which one is upstream, how they integrate, what data passes between them - belongs in context-map.md: link it instead of repeating it. A derived figure is not a flow, however many contexts it reads from - it goes in Read Models and Derived Figures. Keep one row per step and no branches: where the flow genuinely forks, either write the fork as its own flow or record the condition as a rule in rules.md and link it. -->
+
+### FL-01: {流程名稱}
+
+| # | From | To | Handed over | State change | Evidence |
+|---|---|---|---|---|---|
+| 1 | {Context A} | {Context B} | {交出去的是什麼：欄位、識別鍵或事件} | {造成什麼狀態變化} | {code｜data｜confirmed by {role}｜document｜inferred｜assumed} - {複查入口} ({date}) |
+
+## Lifecycles
+
+<!-- One subsection per status field: name the field and where it is stored, list every value it can hold, then one row per transition. List the values even when the code admits more than the workflow uses: a value seen only in stored data is still a state. A transition triggered from another context stays here - name that flow in Cross-Context Flows and cite it rather than restating the handover (from a per-context copy: `domain/analysis.md FL-01`). Whether a single transition is allowed to happen is a business rule: it belongs in rules.md and the Guard cell carries its BR-ID. One scenario played out end to end belongs in behavior.md. The entity that stores the field is defined in models.md. The Means cell says what the state allows or blocks next; when the value's name is also a term the business uses elsewhere, its definition belongs in glossary.md and this cell stays short. Evidence sits on the transitions, not on the state list. -->
+
+### LC-01: {狀態欄位名稱}（`{存放位置：資料表.欄位，或 Aggregate 屬性}`）
+
+| State | Means |
+|---|---|
+| `{狀態值}` | {這個狀態允許或擋住接下來的什麼} |
+
+| From | Trigger | To | Guard | Evidence |
+|---|---|---|---|---|
+| `{原狀態}` | {誰做了什麼} | `{新狀態}` | {決定它的 BR-ID；沒有規則決定就寫必須成立的條件，都沒有就留空} | {code｜data｜confirmed by {role}｜document｜inferred｜assumed} - {複查入口} ({date}) |
+
+## Read Models and Derived Figures
+
+<!-- One subsection per figure or read model: its definition, which records or states it counts, and the point at which an amount moves from one figure to another. A stored entity or value object is defined in models.md; this section holds what is computed from them. Say what a missing, duplicated or stale record does to the figure. -->
+
+### RM-01: {數字或 read model 名稱}
+
+{定義、計入條件、切換點}
+
+Evidence: {code | data | confirmed by {role} | document | inferred | assumed} - {要開哪一支才能複查} ({date})
+
+## Mechanisms
+
+<!-- One subsection per mechanism: how the system produces a behavior that no single rule explains - versioned records, deferred updates, recalculation on read. A behavior that one rule or one Given/When/Then scenario can state belongs in rules.md / behavior.md instead. The Affects line lists what this mechanism changes the meaning of - BR-IDs and entry ids, each cited as Entry ids and Referring to a rule say. -->
+
+### MX-01: {機制名稱}
+
+{運作方式與影響}
+
+Affects: {BR-ID 與 FL-／LC-／RM- 編號（照檔頭的引用規則帶路徑；還沒有編號的寫名稱），逗號分隔；沒有就寫 none}
+Evidence: {code | data | confirmed by {role} | document | inferred | assumed} - {要開哪一支才能複查} ({date})
+
+## Function / Role Index
+
+<!-- Global file only. One row per function: which roles reach it and the data scope each one sees. When a business rule decides who may use the function or what a role sees, that rule is the source of truth: write its BR-ID in that cell instead of restating the rule. Write roles or a data scope directly only where no rule decides them - a menu entry every role sees, a report anyone can run. -->
+
+| Function | ID | Entry point | Bounded Context | Roles | Data scope | Evidence |
+|---|---|---|---|---|---|---|
+| {功能名稱} | FN-01 | `{route / page / job}` | {Context name} | {角色，或決定它的 BR-ID（帶路徑）} | {看得到的資料範圍，或決定它的 BR-ID（帶路徑）} | {code｜data｜confirmed by {role}｜document｜inferred｜assumed} - {複查入口} ({date}) |
+
+## Open Questions and Hotspots
+
+<!-- One row per hotspot: a spot in the knowledge above this project keeps working around until a domain decision settles it. It goes in whichever copy of this file holds the knowledge it is stuck on - or, when that is a business rule or knowledge not recorded yet, the copy the Placement question gives it - and the Affects column names that knowledge by id, cited as Entry ids and Referring to a rule say. Also one row per question that comes up while writing an entry here and whose own answer will be a cross-context flow, a lifecycle, a derived figure, a mechanism or role reach. A question the current feature must answer before it can finish stays in that feature's spec, and a question whose answer belongs to another document's subject stays in that document's own Open Questions section - a term in glossary.md, a business rule in the owning context's rules.md, and a context boundary, an integration responsibility or the question of which context owns a rule in context-map.md. A question that stays in this file goes in the copy that will hold its answer - the copy Placement gives that answer - whichever copy the entry that raised it is in. When a code change would settle an item - a missing check, a known shortcut - it is tech debt: record it in tech-debt.md instead. A hotspot whose pending decision is recorded elsewhere links to it. A settled item stays as a resolved row that says what settled it, with the settling decision in its Evidence cell. -->
+
+| Item | ID | Affects | Why it matters | Status | Evidence |
+|---|---|---|---|---|---|
+| {待確認事項或熱點} | HS-01 | {FL-／LC-／RM-／MX-／FN- 編號或 BR-ID（照檔頭的引用規則帶路徑；還沒有編號的寫名稱）} | {影響} | open / resolved | {code｜data｜confirmed by {role}｜document｜inferred｜assumed} - {複查入口} ({date}) |

package/templates/brownfield/templates/behavior.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/behavior.md 1 — keep this line: dflow doctor reads it -->
 # {Bounded Context} — Behavior Specification
 
 > **Purpose**: Consolidated source of truth for this context's current behavior.

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

@@ -4,6 +4,7 @@ chinese-name: {中文名稱}
 owner: {負責的開發者或團隊}
 created: {YYYY-MM-DD}
 ---
+<!-- dflow-shape: brownfield/context-definition.md 1 — keep this line: dflow doctor reads it -->
 
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 

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

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/context-map.md 1 — keep this line: dflow doctor reads it -->
 <!-- Seeded by Dflow. -->
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
@@ -27,7 +28,7 @@
 
 ## Integration Notes
 
-- {跨 context 的資料流、權責邊界或 legacy coupling}
+- {沒有先後順序也成立的跨 context 資料交換、權責邊界或 legacy coupling；有先後順序的跨 context 交手流程記在 analysis.md}
 
 ## Open Questions
 

package/templates/brownfield/templates/glossary.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/glossary.md 1 — keep this line: dflow doctor reads it -->
 <!-- Seeded by Dflow. -->
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 

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

@@ -2,10 +2,13 @@
 id: BUG-{NUMBER}    # bug-type T2 only; a non-bug T2 (lightweight-{date}-{slug}.md) carries no id — the filename identifies it
 title: {簡述問題}
 status: in-progress    # in-progress | completed
-bounded-context: {ContextName}
+bounded-context: {ContextName}    # or `none` when the host has no meaningful bounded context
 created: {YYYY-MM-DD}
-branch: bugfix/BUG-{NUMBER}-{slug}
+branch: bugfix/BUG-{NUMBER}-{slug}    # must equal the host _index.md `branch:` value (that field is authoritative) — a non-bug T2 therefore carries the host's feature/{SPEC-ID}-{slug} branch
+# hotfix-branch: hotfix/{name}    # ADD (uncomment) only for a post-hoc T2 — references/modify-existing-flow.md Step 1.8. The already-merged emergency fix's own branch, kept even after that branch was deleted.
+# hotfix-identity: {PR / incident / tracker reference}    # ADD only for a post-hoc T2 — the source the asserted `reconciled ({merged-hotfix-hash})` identity rests on; an uncited hash blocks closeout. Keep it adjacent to hotfix-branch.
 ---
+<!-- dflow-shape: brownfield/lightweight-spec.md 1 — keep this line: dflow doctor reads it -->
 
 <!--
 Template note (for AI):
@@ -16,7 +19,7 @@ Template note (for AI):
   - T1 Heavy → use templates/phase-spec.md instead
   - T2 Light → THIS template; produces an independent file
   - T3 Trivial → no independent file; just one inline row in _index.md
-                 Lightweight Changes with a tag like [cosmetic] / [text] / [format]
+                 Lightweight Changes with a tag like [cosmetic] / [text] / [appearance]
 
   Instance file location and naming:
     Place the instantiated file inside the corresponding feature directory:
@@ -24,17 +27,136 @@ Template note (for AI):
     or, when the lightweight change is a tracked bug:
       dflow/specs/features/active/{SPEC-ID}-{slug}/BUG-{NUMBER}-{slug}.md
 
-    If the change is a standalone bug not yet attached to any existing
-    feature, /dflow:bug-fix must first create a feature directory (with a
-    minimal _index.md) before placing the lightweight-spec instance inside.
-    This keeps the structure invariant: every spec file lives under some
-    feature directory.
-
-  After finalizing this lightweight-spec, AI must:
+    A standalone change not yet attached to any existing feature needs a
+    minimal host feature directory (with a minimal _index.md) to hold this
+    instance — the structure invariant is that every spec file lives under
+    some feature directory. That minimal host has a defined create / record /
+    close-out lifecycle: references/modify-existing-flow.md Step 1.7 for a
+    standalone change, or its Step 1.6 minimal variant when the change is a
+    follow-up on a completed feature; a post-hoc hotfix reaches the same
+    lifecycle through Step 1.8, which resolves its linkage to one of those two.
+    Follow that lifecycle rather than
+    improvising one, and do not leave an empty host behind.
+
+  No-BR variants (a T2 that carries no BR delta at all):
+    The default shape below is the classic BR-delta form (Behavior Delta with
+    BR-NN entries + Root Cause). It stays valid and is the right shape whenever
+    the change does have a BR delta.
+    A change can reach T2 carrying no BR delta at all. These families describe
+    how to write a spec the cascade has ALREADY placed at T2; none of them
+    makes a change T2, and none of them overrides an earlier cascade step. Do
+    NOT invent a BR-NN and do NOT write a fake root cause. Pick the matching
+    family, put its BR line under `## Behavior Delta` in place of the
+    ADDED / MODIFIED / REMOVED / RENAMED subsections, and replace `## Root Cause`
+    with that family's evidence section:
+
+    (a) presentation — any copy / appearance change T3 would not take: a sweep
+        beyond the local unit, a whole-screen rewrite, a local edit to
+        high-consequence content (a security warning, a password hint,
+        consent text, a payment or legal notice), or one that changes what the output *means* (an
+        instruction reversed from "company email only" to "any email", a
+        danger / status colour flipped)
+        BR line: `BR: none — presentation`
+        Evidence: `## Output Footprint` — which screens / outputs the change
+        actually reaches, and **what it now says or signals** whenever the
+        meaning moved or the content is high-consequence
+    (b) contract change — non-breaking structured-log / export / API / event
+        field or semantics change
+        BR line: `BR: none — contract change`
+        Evidence: `## Contract Delta`, including a `**Downstream consumers**:`
+        line naming who reads it
+    (c) operational — CVE / security dependency bump, or a behavior-preserving
+        refactor on an auth / payment / resilience / compliance path
+        BR line: `BR: none — operational`
+        Evidence: `## Operational Rationale`, including a `**Trace**:` line
+        (advisory / ticket / audit reference; a self-initiated case with nothing
+        to cite records `**Trace**: none — self-initiated` — the line is never
+        omitted)
+    (d) performance — a runtime performance / resource / SLA change, including
+        one no audience perceives
+        BR line: `BR: none — performance`
+        Evidence: `## Performance Delta`, including an
+        `**SLA / resource context**:` line
+    (e) implementation defect — the rule is unchanged; the implementation was
+        wrong
+        BR lines: `BR Delta: none — implementation defect` AND
+        `Governing BR-IDs: {BR-NN, BR-NN | none}`
+        Evidence: keep `## Problem` / `## Root Cause` / `## Fix Approach`, plus a
+        regression task
+    (f) intentional change — a planned, non-normative functional or interaction
+        change with no rule in the catalogue (default tab, redirect target,
+        ordering, a presentation / interaction control)
+        BR line: `BR: none — intentional change`
+        Evidence: `## Change Rationale`, including `**Before**` / `**After**`
+        behavior lines and a `**Regression**:` line
+
+    More than one family can fit — a behaviour-preserving payment-retry refactor
+    that also shifts runtime SLA is both (c) and (d). Do not pick one and drop
+    the other's evidence: write the BR line of the family with the higher
+    consequence (order: (e) → (c) → (b) → (d) → (f) → (a)) and include **every**
+    matching family's evidence section. A reviewer needs the operational trace
+    and the SLA context, not whichever one the author chose first.
+
+    Family (e) keeps two fields on purpose: "no BR delta" is not "no governing
+    rule". `Governing BR-IDs:` lists the rules the defect sits under, so the rule
+    the fix answers to stays traceable; a genuinely uncatalogued defect records
+    `none`. Never collapse the pair into a single `BR: none`.
+    Family (f) is non-normative only. A new normative constraint (permission /
+    eligibility / threshold / approval / required outcome) is a new BR — take it
+    back to the cascade rather than filing it here, even when the catalogue has
+    no BR-ID for it yet.
+
+    Legacy shapes are accepted, never migrated. Readers and gates take both the
+    classic BR-delta form and the older single `BR:` line bug form (written
+    before the `BR Delta:` / `Governing BR-IDs:` split) as they are; leave
+    existing specs alone and use the shapes above for new ones.
+
+  After drafting this lightweight-spec, AI must:
     1. Add an outbound-link row to the feature's _index.md Lightweight Changes table
-       (Tier = T2; description includes the link to this file)
+       (Tier = T2; description includes the link to this file).
+       TIMING — do this BEFORE the implementation commit, not after. On a
+       minimal (zero-phase) host the row must already be inside checkpoint 1,
+       and closeout's allow-list admits only the row's `Commit` cell
+       afterwards, so a row added later blocks. "Drafting", not the Step 1.7
+       "Finalize + close" sub-step, which runs after that commit and only fills
+       the cell in.
     2. Refresh the feature's _index.md Current BR Snapshot table to reflect
        any BR ADDED / MODIFIED / REMOVED / RENAMED in this lightweight-spec
+       (a no-BR family has nothing to refresh — leave the snapshot as it is)
+
+  Implementation Paths:
+    The `## Implementation Paths` section below names the source paths this
+    change touches. Paths, not a diff — enough to compare a commit against.
+    REQUIRED on a minimal (zero-phase) host — standalone or follow-up:
+    `/dflow:finish-feature` asserts that checkpoint 1's diff touches them, so a
+    spec declaring none leaves that check nothing to compare and a missing
+    declaration BLOCKS closeout rather than passing vacuously
+    (references/finish-feature-flow.md Step 1; written at
+    references/modify-existing-flow.md Step 1.7, before the first commit).
+    On a HOSTED T2 — one recorded under a phase-bearing feature — closeout runs
+    no such check and nothing blocks on it, so the section is good practice
+    there, not a gate. Do not read the "blocks" above as applying to a hosted
+    spec; it does not.
+    Keep the paths OUT of `## Implementation Tasks`: the completion checklist
+    may collapse or remove that section once the tasks are done, and the paths
+    must still be readable at closeout.
+
+  Post-hoc hotfix fields — T2 only, references/modify-existing-flow.md Step 1.8:
+    `hotfix-branch:` records the already-merged emergency fix's own branch
+    (keep the value even when that branch has been deleted); `hotfix-identity:`
+    cites what the identity claim rests on — the PR, incident, or tracker
+    reference. Both live in the frontmatter, adjacent, so the trace and the
+    thing it rests on stay together. They ship COMMENTED OUT: an ordinary
+    (non-post-hoc) T2 leaves them commented and they are inert. Uncomment them
+    only in post-hoc mode — never fill them with `none`, and never leave them
+    live on an ordinary T2, which would claim a hotfix branch that never
+    existed on a record nothing else re-checks.
+    In post-hoc mode `## Implementation Paths` names the paths the MERGED
+    HOTFIX touched: closeout compares them against the `reconciled ({hash})`
+    commit, and blocks if this host's own documentation commit touches any of
+    them (that would be re-implementation, not reconciliation). Closeout tests
+    plausibility only and blocks on an uncited hash; the identity itself is
+    confirmed by references/pr-review-checklist.md.
 -->
 
 # {問題簡述}
@@ -46,6 +168,8 @@ Template note (for AI):
 ## Behavior Delta
 
 > 精簡 delta 格式：bug fix 多數只需 MODIFIED；若確實是新增規則可改用 ADDED、移除用 REMOVED、改名用 RENAMED。多項變更時照類別列。
+>
+> 完全沒有 BR delta 時改用 no-BR 家族形（見檔首 Template note 的 No-BR variants）：本段只留該家族的 BR 行（例如 `BR: none — presentation`；家族 (e) 是 `BR Delta:` + `Governing BR-IDs:` 兩行），不要為了填滿 delta 子段捏造 BR-NN。
 
 ### MODIFIED - behavior modified in this fix
 #### Rule: BR-NN {規則名稱}
@@ -58,12 +182,31 @@ Template note (for AI):
 
 ## Root Cause
 
+> classic BR-delta 形與 no-BR 家族 (e) 保留本段；家族 (a)–(d)、(f) 以該家族的 evidence 段取代本段（見檔首 Template note 的 No-BR variants）。
+
 {為什麼會這樣？是邏輯錯誤？資料問題？還是需求理解有誤？}
 
 ## Fix Approach
 
 {怎麼修？有沒有抽到 Domain 層的機會？}
 
+## Implementation Paths
+
+> The source paths this change touches — paths, not a diff, at a granularity a
+> commit can be compared against. **Required on a minimal (zero-phase) host**:
+> `/dflow:finish-feature` asserts checkpoint 1's diff touches them, and
+> declaring none **blocks** closeout instead of passing. On a **hosted** T2 —
+> recorded under a phase-bearing feature — closeout runs no such check, so this
+> is good practice there rather than a gate. Do not move the list into
+> `## Implementation Tasks`: that section may be collapsed once the tasks are
+> done, and these paths must still be readable at closeout.
+>
+> **Post-hoc hotfix (Step 1.8)**: list what the **already-merged hotfix**
+> touched. This host's own documentation commit must **not** touch any of them.
+
+- `{src/path/touched}`
+- `{src/another/path/touched}`
+
 <!-- dflow:section implementation-tasks -->
 ## Implementation Tasks
 

package/templates/brownfield/templates/models.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/models.md 1 — keep this line: dflow doctor reads it -->
 <!-- Seeded by Dflow. -->
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 

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

@@ -7,6 +7,7 @@ created: {YYYY-MM-DD}
 author: {developer-name}
 branch: feature/{SPEC-ID}-{slug}
 ---
+<!-- dflow-shape: brownfield/phase-spec.md 1 — keep this line: dflow doctor reads it -->
 
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
@@ -17,7 +18,14 @@ Template note (for AI):
   This is the **phase-spec** template - one phase-spec captures one full
   "Kickoff -> Domain -> Design -> Build -> Verify" cycle inside a feature directory.
   A feature can have 1..N phase-specs; the feature-level dashboard lives in
-  the sibling `_index.md` (see templates/_index.md). The instance file name is
+  the sibling `_index.md` (see templates/_index.md).
+  Exception — a **minimal (zero-phase) host** has **0**: it records a small
+  standalone or follow-up change and is defined by carrying no phase-spec at
+  all (references/modify-existing-flow.md Step 1.7, or its Step 1.6 minimal
+  variant). Such a host never uses this template. If you are about to create a
+  phase-spec for one, stop: adding a phase makes it a phase-bearing feature,
+  and closeout will then check it as one.
+  The instance file name is
   `phase-spec-YYYY-MM-DD-{slug}.md` placed at
   `dflow/specs/features/active/{SPEC-ID}-{slug}/`.
 

package/templates/brownfield/templates/rules.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/rules.md 1 — keep this line: dflow doctor reads it -->
 <!-- Seeded by Dflow. -->
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 

package/templates/brownfield/templates/tech-debt.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: brownfield/tech-debt.md 1 — keep this line: dflow doctor reads it -->
 <!-- Seeded by Dflow. -->
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 

package/templates/common/references/ddd-modeling-guide.md

@@ -76,10 +76,10 @@ never cross:
    BR-ID in `rules.md` and a scenario in `behavior.md`; `/dflow:verify` works
    the same. What shrinks is the *domain model's thickness*, not the spec's
    existence.
-2. **The Tier system is unchanged.** A bug fix in a generic context is still a
-   T2; a new feature still runs the flow. Subdomain governs *how deep to model
-   a context*; Tier governs *how much ceremony a single change needs* — they
-   are orthogonal.
+2. **The Tier system is unchanged.** A bug fix's tier is whatever the cascade
+   decides by the change itself (T3 / T2 / T1), not by the subdomain; a new
+   feature still runs the flow. Subdomain governs *how deep to model a context*;
+   Tier governs *how much ceremony a single change needs* — they are orthogonal.
 3. **Criticality is not downgraded.** Security, tests, SLA, audit,
    permissions, and data integrity do **not** drop with the subdomain type —
    auth or notifications can be generic *and* mission-critical. Generic lowers
@@ -119,9 +119,14 @@ or value objects directly.
 1. **Protect invariants** — The Aggregate exists to enforce business rules that span
    multiple objects within it.
 
-2. **One Aggregate per transaction** — A single operation should modify only ONE
-   Aggregate. If you need to modify two Aggregates, use Domain Events for eventual
-   consistency.
+2. **One Aggregate per transaction — by default** — A single operation should
+   normally modify one Aggregate. If it appears to need multiple roots, first
+   challenge whether the boundary is wrong and whether Domain Events with eventual
+   consistency can separate the work. If a multi-root local transaction remains
+   justified, record the domain rationale, the shared atomic boundary / operational
+   coupling, and when to re-evaluate the choice. A local database transaction cannot
+   make an external provider or service fact atomic with local state; that workflow
+   still needs idempotency plus reliable delivery / retry or compensation.
 
 3. **Reference other Aggregates by ID only** — Never hold a direct object reference
    to another Aggregate. Store its ID instead.
@@ -479,9 +484,10 @@ the values that changed — not a snapshot of the whole Aggregate.
   event** decision (record the Delivery expectation in `events.md`; Brownfield —
   see the Edition note) and treat
   the payload as a published contract: add fields if you must, never change
-  their meaning. Ceremony-wise, extending an event payload that crosses
-  contexts is a T1 contract change (see the ceremony examples in
-  `_conventions.md`).
+  their meaning. Ceremony-wise it follows the contract axis of the ordered
+  cascade — classify the change in AI-AGENT-GUIDE.md § Ceremony Scaling, which
+  is where breaking versus non-breaking and the resulting tier are decided; a
+  project's own `_conventions.md` may escalate from there.
 
 ### Event Flow
 
@@ -673,13 +679,19 @@ build. (Read model ≠ event sourcing.)
 ## Domain Services
 
 Use Domain Services for operations that:
-- Involve multiple Aggregates (read-only access to the second Aggregate)
+- Require a domain decision spanning information from multiple Aggregates
+  (read-only access by default)
 - Require external information (through interfaces) to make domain decisions
 - Don't naturally belong to any single Entity
 
-A Domain Service can make a **stateless** cross-Aggregate decision. It is
-not a home for process progress, retries, deadlines, or compensation state.
-When the flow has state, use the "Long-Running Processes" ladder.
+A Domain Service expresses a **stateless domain operation or decision** and may
+read multiple Aggregate roots. A justified multi-root mutation is rare rather
+than automatically invalid: it must trigger a boundary / transaction review and
+the service itself must carry a real domain rule or decision. A service that only
+orders calls to multiple roots is Application-layer orchestration in the wrong
+place. A Domain Service is not a home for process progress, retries, deadlines,
+or compensation state. Application code owns ordinary workflow sequencing; when
+the flow has business-visible state, use the "Long-Running Processes" ladder.
 
 ```csharp
 // Domain Service — in Domain layer
@@ -791,8 +803,13 @@ The less-obvious three — when to reach for them:
 4. **Business logic in Infrastructure** — Rules in SQL queries or EF configurations
    → Domain defines WHAT, Infrastructure defines HOW
 
-5. **Direct cross-Aggregate modification** — One command modifying two Aggregates
-   → Use Domain Events for the second Aggregate
+5. **Unreviewed direct cross-Aggregate modification** — One command modifies
+   multiple Aggregate roots without challenging the boundaries or recording why
+   one local transaction is justified
+   → Prefer Domain Events and eventual consistency; if the local-transaction
+   exception is justified, record the rationale and re-evaluation condition from
+   Aggregate Design Rule 2. External provider / service facts are never atomic
+   with the local database transaction.
 
 6. **Set-based invariant guarded only in memory** — A "unique" / "only one active"
    rule enforced solely by an in-app check, with no DB unique constraint or

package/templates/{greenfield → common}/references/dflow-feedback-flow.md

@@ -77,7 +77,8 @@ Allowed evidence:
 - Dflow command name
 - Dflow version if known
 - Template or reference file name
-- Generic project type, such as "existing legacy presentation-framework app"
+- Generic project type, such as "existing legacy presentation-framework app" or
+  "new internal service"
 - Minimal paraphrased symptom
 - Short sanitized snippets from Dflow-owned files