dflow-sdd-ddd 0.13.0 → 0.15.0

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

@@ -17,6 +17,8 @@ trunk-based, GitHub Flow), use `Git-principles-trunk.md` instead.
 
 ---
 
+<!-- dflow-generated: git-principles-canonical START -->
+
 ## 1. Branch Structure
 
 | Branch | Naming | Cut from | Merges to |
@@ -24,6 +26,7 @@ trunk-based, GitHub Flow), use `Git-principles-trunk.md` instead.
 | `main` / `master` | `main` | — | release / hotfix only |
 | `develop` | `develop` | — | integration branch for features |
 | feature | `feature/{SPEC-ID}-{slug}` | `develop` | `develop` |
+| bugfix | `bugfix/{BUG-ID}-{slug}` | `develop` | `develop` |
 | release | `release/{version}` | `develop` | `main` + `develop` |
 | hotfix | `hotfix/{version}-hotfix{n}` | `main` | `main` + `develop` |
 
@@ -31,6 +34,17 @@ The `feature/{SPEC-ID}-{slug}` pattern is a **Dflow requirement** (not
 a Git Flow requirement). It ties each feature branch to its
 corresponding `dflow/specs/features/active/{SPEC-ID}-{slug}/` directory.
 
+A **`bugfix/{BUG-ID}-{slug}`** branch is the same shape as a feature branch and
+follows the same topology — cut from the same base, pushed the same way,
+integrated the same way, and **closed out the same way**. It is used when a
+defect owns its own host rather than being picked up by a feature already in
+flight. Its host is a **minimal (zero-phase) host**, so it carries no
+phase-spec: the SPEC-ID lives in the directory name while the branch name
+carries the BUG-NUMBER, and the host `_index.md` `branch:` field is
+authoritative for both. Closeout is not optional because the branch prefix
+differs — `/dflow:finish-feature` runs and the directory is archived to
+`completed/` before the branch merges, exactly as for `feature/`.
+
 ### Feature Branch Workflow
 
 ```bash
@@ -108,10 +122,18 @@ git branch -d hotfix/{version}-hotfix{n}
 ```
 
 **Hotfix spec requirement (team convention)**: Hotfixes often skip the
-upfront SDD cycle for speed. This project commits to writing a
-lightweight spec within **24 hours** after the hotfix lands, documenting
-root cause + fix + (if applicable) a tech-debt entry in
-`dflow/specs/architecture/tech-debt.md` if the bug reveals a systemic issue.
+upfront SDD cycle for speed. This project commits to documenting the fix
+within **24 hours** after it lands. Run `/dflow:modify-existing` in
+**post-hoc mode** (`references/modify-existing-flow.md` Step 1.8): it opens a
+minimal host of its own for the fix, records the implementation checkpoint as
+`reconciled ({merged-hotfix-hash})`, and reconciles rather than re-running work
+that is already on the mainline.
+What gets written is whatever the cascade's tier calls for — a **T2** lands a
+lightweight spec (root cause + fix + a `dflow/specs/architecture/tech-debt.md` entry
+if the bug reveals a systemic issue); a **T3** lands one `_index.md` Lightweight
+Changes row and no spec file. Step 1.8 admits **T2 / T3 only**: a **T1**
+post-hoc keeps the normal phase-bearing route and documents the merged work
+there.
 This is a **human-to-human commitment** — Dflow / AI cannot track the
 24-hour clock; the team enforces it in retros.
 
@@ -156,7 +178,10 @@ Before making key Git operations:
       justification in the spec's notes section)
 - [ ] `_index.md` status reflects the current work (Phase Specs row
       updated, `Resume Pointer` refreshed if the commit reaches a meaningful
-      checkpoint)
+      checkpoint). A **minimal (zero-phase) host** has no Phase Specs row to
+      update — its record is the Lightweight Changes row, and that row must
+      already be written **before** this commit, not after it. Refresh the
+      Resume Pointer as usual.
 - [ ] Clean Architecture layer rules hold (Domain has no external
       package deps, no business logic leaked into handlers /
       controllers)
@@ -176,6 +201,21 @@ Before making key Git operations:
 - [ ] No ORM / serialization attributes on Domain entities
 - [ ] Domain unit tests pass (invariants + value object equality)
 
+> **Minimal (zero-phase) host.** The items about this host's own record —
+> `/dflow:finish-feature` having run, `_index.md` status `completed`, and the
+> archival move — apply **unchanged**: they are what stops a host merging with
+> its record still open. Every item naming a **Domain or bounded-context
+> artifact** applies only to what this change **actually touched**: a **no-BC**
+> host has no context to sync or document, and a **T3** does no Domain work at
+> all, so for those they read N/A. **Bounded-context-scoped only** —
+> `glossary.md` and the tech-debt file belong to no bounded context, stay in a
+> no-BC host's sweep, and are **not** N/A for it. **Code invariants are not
+> artifacts** — the items here that state a rule about the **source** rather
+> than name a document to update are **never N/A**: they hold for any change
+> that touches code at all, and a host wrongly claiming to be no-BC is exactly
+> what they catch. Record the N/A; do not create a context, a Domain document,
+> or a BR row to tick a box.
+
 ---
 
 ## 4. Integration Commit Message Conventions
@@ -209,6 +249,32 @@ Domain Events introduced / modified: {Event names, or "(none)"}
 Related SPEC-IDs: {SPEC-ID}{, follow-up SPEC-IDs if any}
 ```
 
+**Zero-phase (minimal host) form.** A minimal host has no phases and may have
+no bounded context, so its Change Scope block carries the values that are
+actually true rather than padded ones:
+
+```
+Change Scope:
+- BC: none                          # or the real context, when the change has one
+- Aggregate(s) touched: none
+- Phase Count: 0
+- Lightweight Changes: 1 T2 + 0 T3  # at least one row, always
+
+Related BR-IDs: {empty, or the per-family no-BR marker this change carries}
+
+Domain Events introduced / modified: (none)
+```
+
+`none` and `0` are the honest values here, not placeholders waiting to be
+filled. **`Related BR-IDs` is the exception — never force it to `none`.**
+It reports what this change's own record carries, not what was synced, so it
+takes the same values a BC-bearing host would: empty, or the per-family no-BR
+marker when the T2 carries one. Writing `none` there erases the marker the
+zero-phase shape requires (`references/finish-feature-flow.md` Step 5 states
+the rule). A minimal host that genuinely touches a bounded context
+reports that context and its real BR delta exactly as a phase-bearing feature
+would — the zero is the **phase count**, not the significance.
+
 ### Concrete example
 
 ```bash
@@ -262,7 +328,7 @@ release.
 Example entry:
 
 ```markdown
-## [1.2.3] — {YYYY-MM-DD}
+## [1.2.3] — {2026-04-21}
 
 ### Added
 - {SPEC-20260421-001}: ExpenseReport submission flow with Domain Events
@@ -276,6 +342,8 @@ Example entry:
 
 ---
 
+<!-- dflow-generated: git-principles-canonical END -->
+
 ## 6. AI Collaboration Rules (Project Policy)
 
 Three categories:

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

@@ -17,6 +17,8 @@ use `Git-principles-gitflow.md` instead.
 
 ---
 
+<!-- dflow-generated: git-principles-canonical START -->
+
 ## 1. Branch Structure
 
 Single-trunk model:
@@ -25,6 +27,7 @@ Single-trunk model:
 |--------|--------|----------|-----------|
 | `main` | `main` | — | — (protected; feature branches merge in) |
 | feature | `feature/{SPEC-ID}-{slug}` | `main` | `main` |
+| bugfix | `bugfix/{BUG-ID}-{slug}` | `main` | `main` |
 
 No `develop`, no `release/*`, no `hotfix/*` branches. Hotfixes are just
 small, fast feature branches cut from `main`.
@@ -33,6 +36,17 @@ The `feature/{SPEC-ID}-{slug}` pattern is a **Dflow requirement** (not
 a trunk-based requirement). It ties each feature branch to its
 corresponding `dflow/specs/features/active/{SPEC-ID}-{slug}/` directory.
 
+A **`bugfix/{BUG-ID}-{slug}`** branch is the same shape as a feature branch and
+follows the same topology — cut from the same base, pushed the same way,
+integrated the same way, and **closed out the same way**. It is used when a
+defect owns its own host rather than being picked up by a feature already in
+flight. Its host is a **minimal (zero-phase) host**, so it carries no
+phase-spec: the SPEC-ID lives in the directory name while the branch name
+carries the BUG-NUMBER, and the host `_index.md` `branch:` field is
+authoritative for both. Closeout is not optional because the branch prefix
+differs — `/dflow:finish-feature` runs and the directory is archived to
+`completed/` before the branch merges, exactly as for `feature/`.
+
 ### Feature Branch Workflow
 
 ```bash
@@ -111,7 +125,8 @@ ExpenseItem before submission.
 ## 3. Merge Strategy Options
 
 Trunk-based projects typically pick **one** of the three below as the
-default. Document which one your team uses:
+default. The trade-offs are here; **record which one your team uses in
+§ 6, under "Merge strategy"** — that section is yours, this one is not.
 
 ### Option A — Squash merge (most common)
 
@@ -123,8 +138,6 @@ All commits on the feature branch are squashed into a single commit on
 - Con: Loses intermediate commit context (though it's still available
   via the PR)
 
-**This project uses**: {Yes / No / Default — fill in}
-
 ### Option B — Rebase merge
 
 Each commit on the feature branch is rebased onto `main` as-is. Linear
@@ -135,8 +148,6 @@ history, but more commits than squash.
   phase)
 - Con: Noisier history
 
-**This project uses**: {Yes / No / Default — fill in}
-
 ### Option C — Fast-forward only
 
 Only merges when the feature branch is a direct descendant of `main`.
@@ -145,8 +156,6 @@ Equivalent to rebase merge when used consistently.
 - Pro: Perfectly linear
 - Con: Requires strict rebase discipline; can be inconvenient
 
-**This project uses**: {Yes / No / Default — fill in}
-
 ---
 
 ## 4. Integration Commit Message Conventions
@@ -181,6 +190,32 @@ Domain Events introduced / modified: {Event names, or "(none)"}
 Related SPEC-IDs: {SPEC-ID}{, follow-up SPEC-IDs if any}
 ```
 
+**Zero-phase (minimal host) form.** A minimal host has no phases and may have
+no bounded context, so its Change Scope block carries the values that are
+actually true rather than padded ones:
+
+```
+Change Scope:
+- BC: none                          # or the real context, when the change has one
+- Aggregate(s) touched: none
+- Phase Count: 0
+- Lightweight Changes: 1 T2 + 0 T3  # at least one row, always
+
+Related BR-IDs: {empty, or the per-family no-BR marker this change carries}
+
+Domain Events introduced / modified: (none)
+```
+
+`none` and `0` are the honest values here, not placeholders waiting to be
+filled. **`Related BR-IDs` is the exception — never force it to `none`.**
+It reports what this change's own record carries, not what was synced, so it
+takes the same values a BC-bearing host would: empty, or the per-family no-BR
+marker when the T2 carries one. Writing `none` there erases the marker the
+zero-phase shape requires (`references/finish-feature-flow.md` Step 5 states
+the rule). A minimal host that genuinely touches a bounded context
+reports that context and its real BR delta exactly as a phase-bearing feature
+would — the zero is the **phase count**, not the significance.
+
 GitHub PR editor can be pre-filled with this body; the merge button
 then produces the squash commit.
 
@@ -213,6 +248,12 @@ For trivial features consisting of a single commit (often a T3
 triaged later to one small refactor / fix), the commit body itself
 IS the integration message — use the §4.1 format.
 
+**A minimal (zero-phase) host is never this case.** It records **exactly two**
+commits — the implementation checkpoint, then the closeout commit that carries
+the archival `git mv` — so it does not arrive here with one. A minimal host
+showing a single commit has not closed out: run `/dflow:finish-feature` first
+rather than fast-forwarding it as it stands.
+
 ---
 
 ## 5. Gate Checks
@@ -226,7 +267,10 @@ Before making key Git operations:
       justification in the spec's notes section)
 - [ ] `_index.md` status reflects the current work (Phase Specs row
       updated, `Resume Pointer` refreshed if the commit reaches a meaningful
-      checkpoint)
+      checkpoint). A **minimal (zero-phase) host** has no Phase Specs row to
+      update — its record is the Lightweight Changes row, and that row must
+      already be written **before** this commit, not after it. Refresh the
+      Resume Pointer as usual.
 - [ ] Clean Architecture layer rules hold (Domain has no external
       package deps, no business logic leaked into handlers /
       controllers)
@@ -247,8 +291,25 @@ Before making key Git operations:
 - [ ] Domain unit tests pass (invariants + value object equality)
 - [ ] CI is green (all required checks passing)
 
+> **Minimal (zero-phase) host.** The items about this host's own record —
+> `/dflow:finish-feature` having run, `_index.md` status `completed`, and the
+> archival move — apply **unchanged**: they are what stops a host merging with
+> its record still open. Every item naming a **Domain or bounded-context
+> artifact** applies only to what this change **actually touched**: a **no-BC**
+> host has no context to sync or document, and a **T3** does no Domain work at
+> all, so for those they read N/A. **Bounded-context-scoped only** —
+> `glossary.md` and the tech-debt file belong to no bounded context, stay in a
+> no-BC host's sweep, and are **not** N/A for it. **Code invariants are not
+> artifacts** — the items here that state a rule about the **source** rather
+> than name a document to update are **never N/A**: they hold for any change
+> that touches code at all, and a host wrongly claiming to be no-BC is exactly
+> what they catch. Record the N/A; do not create a context, a Domain document,
+> or a BR row to tick a box.
+
 ---
 
+<!-- dflow-generated: git-principles-canonical END -->
+
 ## 6. AI Collaboration Rules (Project Policy)
 
 Three categories:
@@ -298,6 +359,13 @@ can always decline. If your team also wants vendor attribution, appending the
 assistant's documented line (e.g. `Co-Authored-By: Claude
 <noreply@anthropic.com>`) is an independent, optional convention on top.
 
+### Merge strategy
+
+Dflow does not choose this for you; § 3 lists the trade-offs. Record what this
+project settled on:
+
+**This project uses**: {Squash / Rebase / Fast-forward only — fill in}
+
 ---
 
 ## 7. Hotfixes under Trunk-based
@@ -313,10 +381,18 @@ There is no separate `hotfix/*` branch. A hotfix is:
 4. Deployed via the same pipeline as any other change
 
 **Hotfix spec requirement (team convention)**: Hotfixes often skip the
-upfront SDD cycle for speed. This project commits to writing a
-lightweight spec within **24 hours** after the hotfix lands, documenting
-root cause + fix + (if applicable) a tech-debt entry in
-`dflow/specs/architecture/tech-debt.md` if the bug reveals a systemic issue.
+upfront SDD cycle for speed. This project commits to documenting the fix
+within **24 hours** after it lands. Run `/dflow:modify-existing` in
+**post-hoc mode** (`references/modify-existing-flow.md` Step 1.8): it opens a
+minimal host of its own for the fix, records the implementation checkpoint as
+`reconciled ({merged-hotfix-hash})`, and reconciles rather than re-running work
+that is already on the mainline.
+What gets written is whatever the cascade's tier calls for — a **T2** lands a
+lightweight spec (root cause + fix + a `dflow/specs/architecture/tech-debt.md` entry
+if the bug reveals a systemic issue); a **T3** lands one `_index.md` Lightweight
+Changes row and no spec file. Step 1.8 admits **T2 / T3 only**: a **T1**
+post-hoc keeps the normal phase-bearing route and documents the merged work
+there.
 This is a **human-to-human commitment** — Dflow / AI cannot track the
 24-hour clock; the team enforces it in retros.
 

package/templates/greenfield/scaffolding/_conventions.md

@@ -30,25 +30,6 @@ dflow/specs/features/active/{SPEC-ID}-{slug}/
 T3 Trivial changes do **not** produce a separate file — they are
 recorded as one row in `_index.md` Lightweight Changes.
 
-## Prose Language
-
-Project prose language: `{prose-language}`
-
-Dflow templates keep canonical English structural language: headings,
-table headers, fixed labels, placeholders, IDs, anchors, and code-facing
-terms remain English.
-
-Free prose written inside those sections should follow the project prose
-language:
-
-- `en`: write free prose in English.
-- `zh-TW`: write free prose in Traditional Chinese.
-- `{xx-XX}`: write free prose in that explicit BCP-47 language.
-
-Do not translate code identifiers, DDD pattern names, BR IDs, SPEC IDs,
-file paths, branch names, anchors, or inline code only to satisfy the
-prose-language setting.
-
 ### SPEC-ID Format
 
 - Pattern: `SPEC-YYYYMMDD-NNN` (e.g. `SPEC-20260421-001`)
@@ -56,6 +37,14 @@ prose-language setting.
 - Once assigned, the SPEC-ID is immutable — it appears in the feature
   directory name, the first phase-spec filename, and the git branch
   name (see `Git-principles-*.md`)
+- **Minimal (zero-phase) host exception.** A host that records a small
+  standalone or follow-up change carries **no phase-spec**, so there is no
+  phase-spec filename for the SPEC-ID to appear in — the directory name and
+  the branch carry it. A **functional bug** host goes one step further: its
+  branch is `bugfix/BUG-{NUMBER}-{slug}`, so it carries the BUG-NUMBER and
+  not the SPEC-ID at all. In every case the host `_index.md` `branch:` field
+  is authoritative, and the SPEC-ID itself stays immutable. Do not create a
+  phase-spec, or rename a branch, to make the three-name rule above hold.
 
 ### Slug Conventions (Project-Specific Fill-In)
 
@@ -68,6 +57,25 @@ prose-language setting.
 - **Length target**: 2–4 English words or 2–6 Chinese characters
   (Dflow skill guidance)
 
+## Prose Language
+
+Project prose language: `{prose-language}`
+
+Dflow templates keep canonical English structural language: headings,
+table headers, fixed labels, placeholders, IDs, anchors, and code-facing
+terms remain English.
+
+Free prose written inside those sections should follow the project prose
+language:
+
+- `en`: write free prose in English.
+- `zh-TW`: write free prose in Traditional Chinese.
+- `{xx-XX}`: write free prose in that explicit BCP-47 language.
+
+Do not translate code identifiers, DDD pattern names, BR IDs, SPEC IDs,
+file paths, branch names, anchors, or inline code only to satisfy the
+prose-language setting.
+
 ---
 
 ## Filling the Templates
@@ -78,12 +86,15 @@ Dflow ships these templates (do **not** re-inline their content here
 | Template | Used when |
 |----------|-----------|
 | `templates/_index.md`           | Creating a feature directory (every feature) |
-| `templates/phase-spec.md`       | T1 Heavy — new feature / new phase / architectural change |
-| `templates/lightweight-spec.md` | T2 Light — bug fix / small tweak with BR Delta |
+| `templates/phase-spec.md`       | T1 Heavy |
+| `templates/lightweight-spec.md` | T2 Light — classic BR-delta form, or one of the no-BR family variants (presentation, non-breaking contract, operational / security, performance, implementation defect, intentional change) |
 | `templates/context-definition.md` | When a new Bounded Context is introduced |
 | `templates/aggregate-design.md` | When a new Aggregate is introduced |
 | `templates/behavior.md`         | BC-level consolidated behavior spec |
 
+Which tier applies is decided by the cascade in `AI-AGENT-GUIDE.md` § Ceremony
+Scaling, never by this table — these rows only say which template a tier uses.
+
 Project-specific guidance when filling these templates:
 
 ### DDD-specific spec conventions
@@ -120,18 +131,29 @@ Project-specific guidance when filling these templates:
 
 ## Ceremony Scaling (Project Application)
 
-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
+Dflow defines three tiers — **T1 Heavy / T2 Light / T3 Trivial** — plus a
+below-workflow level. See `AI-AGENT-GUIDE.md` § Ceremony Scaling for the
+full ordered cascade. We do not re-define the tier criteria here; this
 section records how *this* project applies them in borderline
 situations.
 
+**The cascade result is a floor: rows in this section may only escalate a
+tier, never lower it.** A row may take a change Dflow would call T2 and
+make it T1 for this project; no row may lower a T1, and no row may move a
+tracked change below workflow.
+
+Write `T<n> (project convention)` in the Tier column when this project raises the
+tier, and `cascade result` when it adds an obligation but no tier change. Do not
+write a bare tier — that restates the cascade instead of recording a decision,
+and it is how the two drift apart.
+
 | Situation (project-specific) | Tier we default to | Why |
 |------------------------------|--------------------|-----|
-| {e.g. New Aggregate} | T1 + `aggregate-design.md` | Crosses Aggregate boundary and needs invariant documentation |
-| {e.g. Adding a Query only (no write)} | T2 | No Aggregate state change, but goes through Application layer; trace via lightweight-spec |
-| {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 |
+| {e.g. New Aggregate} | cascade result + `aggregate-design.md` | No tier change — we add the design worksheet on top of whatever the cascade returns, because our invariants need somewhere to live |
+| {e.g. A supporting query added for an existing screen or behaviour change} | T2 (project convention) | We want a lightweight-spec trace even when the cascade would not require a spec file |
+| {e.g. A newly exposed read capability — new endpoint, new data source, or an independently callable read} | T1 (project convention) | We escalate any newly exposed read above whatever the cascade returns — our consumers treat it as a contract the moment it exists |
+| {e.g. EF configuration tweak in Infrastructure} | T1 (project convention) | We escalate Infrastructure mapping tweaks above whatever the cascade returns — this layer has silently changed persisted behaviour before |
+| {e.g. Domain Event payload extension} | T1 (project convention) | We escalate above whatever the cascade returns for an additive optional field, because our cross-context consumers deserialize strictly |
 
 ### DDD Modeling Depth (`AI-AGENT-GUIDE.md` § Ceremony Scaling)
 

package/templates/greenfield/scaffolding/_overview.md

@@ -1,3 +1,4 @@
+<!-- dflow-shape: greenfield/_overview.md 1 — keep this line: dflow doctor reads it -->
 <!-- Seeded by Dflow. -->
 
 # System Overview — {System Name}
@@ -140,8 +141,11 @@ to the following design habits. Expand / adapt each to this project:
 - **Domain at the Center** — Business rules live in `*.Domain`. If you
   find business logic in `*.Application` handlers or (worse) in
   controllers, raise a tech-debt entry.
-- **Aggregate Boundaries** — Each transaction modifies exactly one
-  Aggregate. Cross-aggregate workflows go through Domain Events.
+- **Aggregate Boundaries** — By default, each transaction modifies one
+  Aggregate and cross-Aggregate workflows use Domain Events. Any justified
+  local multi-Aggregate exception must follow and record the contract in
+  `dflow/specs/shared/dflow-workflows/references/ddd-modeling-guide.md`
+  "Aggregate Design Rules"; external facts cannot join the local transaction.
 - **Dependency Inversion** — The Domain declares interfaces; the
   Infrastructure layer implements them. No Domain code imports
   `Microsoft.EntityFrameworkCore`.