dflow-sdd-ddd 0.14.0 → 0.16.0

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

@@ -28,8 +28,8 @@ are not available in the current AI tool:
 
 | Workflow | Use when |
 |---|---|
-| `/dflow:new-feature` | A new user-visible capability or business behavior is requested. |
-| `/dflow:modify-existing` | Existing behavior needs to change. |
+| `/dflow:new-feature` | A genuinely new feature, page, or capability — a **newly created** navigable surface (its own route and its own content tree), a new user-executable domain operation, or a new independently-consumable output. Adding a control to an existing surface — or a menu entry pointing at a route that already exists — is modify-existing. |
+| `/dflow:modify-existing` | Existing behavior or an existing surface changes — including adding a presentation / interaction control (copy button, filter, sort, quick-view) to an existing screen. |
 | `/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. |
@@ -45,8 +45,8 @@ Machine-readable source for rendering tool-specific thin wrappers:
 <!-- dflow-command-registry:start -->
 | id | label | description | arg-hint | scope |
 |---|---|---|---|---|
-| new-feature | /dflow:new-feature | Start a new user-visible feature or business behavior. | feature request | workflow |
-| modify-existing | /dflow:modify-existing | Change existing behavior. | change request | workflow |
+| new-feature | /dflow:new-feature | Start a genuinely new feature, page, or capability (new navigable surface, domain operation, or consumable output). | feature request | workflow |
+| modify-existing | /dflow:modify-existing | Change existing behavior, or add a control to an existing surface. | change request | workflow |
 | 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 |
@@ -68,7 +68,26 @@ input like this (supporting files live in the workflow bundle at
   `references/ddd-modeling-guide.md`.
 - **"Quick question about..." / "How does X work?"** → check
   `dflow/specs/domain/` first and answer from the documented domain knowledge.
+- **Knowledge that no single context document holds** — an ordered flow that
+  crosses contexts (always the domain-root copy), the lifecycle a status field
+  moves through, a figure computed rather than stored, the mechanism behind a
+  behavior no single rule explains, which roles reach which function (always
+  the domain-root copy), or a spot in one of these that this project keeps
+  working around until a domain decision settles it (in the copy that holds
+  the knowledge it is stuck on) → **record it in
+  `analysis.md`**: `dflow/specs/domain/{context}/analysis.md` when one context
+  owns what it describes, otherwise `dflow/specs/domain/analysis.md`. Create
+  the file from `templates/analysis.md` the first time there is something to
+  record. With no workflow running, offer to commit that record on its own.
 - **"I'm creating a branch"** → read `references/git-integration.md`.
+- **"Why does this rule exist?" / "This rule seems wrong"** → look the rule up in
+  `references/flow-rationale-registry.md`. Grep the rule id when you have one
+  (`grep -E '^R-FF-BRANCH-02:'`), otherwise a **short** fragment of the rule —
+  four to eight words, because the flow files are hard-wrapped and a longer
+  phrase spans a line break. A lookup may return two lines tagged `gf ·` / `bf ·`;
+  take this project's edition, which the workflow bundle's
+  `.dflow-bundle-manifest.json` records in its `edition` field. **Do not read
+  that file whole** — it is a lookup table, not a document.
 - **"Turn the specs into HTML" / "make the specs easier to read"** → run the
   CLI command `dflow render` (a human-readability tool, not a `/dflow:*`
   workflow). It mirrors `dflow/specs/` into a browsable static HTML tree
@@ -77,10 +96,18 @@ input like this (supporting files live in the workflow bundle at
 - **"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.
+- **Anything else code-related** → run it through § Ceremony Scaling's ordered
+  cascade rather than a business-logic yes/no. Only the cascade's step 2 sends
+  work outside Dflow, and it is narrower than "not business logic": a display
+  typo, an appearance change, a machine-consumed contract edit, security / CVE
+  work and a deliberate runtime performance change are all tracked. If the
+  cascade lands the request anywhere at or above T3, suggest the matching
+  `/dflow:*` command and wait for confirmation (see § Workflow Transparency);
+  only if it lands below workflow, help directly with no ceremony. If step 0
+  takes it out of the cascade instead — observation-only work — it is neither:
+  say so and record it, do not treat "no tier" as "no ceremony". This applies
+  once you are already reading this guide — what makes a tool load it in the
+  first place is that tool's own trigger configuration, which is narrower.
 
 ## Status / Control Commands
 
@@ -206,6 +233,8 @@ Dflow-owned project documents live under `dflow/specs/`.
 | System overview | `dflow/specs/shared/_overview.md` |
 | Domain glossary | `dflow/specs/domain/glossary.md` |
 | Context map | `dflow/specs/domain/context-map.md` |
+| Domain analysis (cross-context) | `dflow/specs/domain/analysis.md` |
+| Domain analysis (per context) | `dflow/specs/domain/{context}/analysis.md` |
 | Active feature specs | `dflow/specs/features/active/` |
 | Completed feature snapshots | `dflow/specs/features/completed/` |
 | Technical debt | `dflow/specs/architecture/tech-debt.md` or `dflow/specs/migration/tech-debt.md` |
@@ -222,10 +251,12 @@ dflow/specs/
 ├── domain/
 │   ├── glossary.md
 │   ├── context-map.md              # Bounded Context relationships
+│   ├── analysis.md                 # Cross-context flows and role reach
 │   └── {bounded-context}/
 │       ├── context.md
 │       ├── models.md               # Aggregates, Entities, VOs
 │       ├── rules.md                # Business rules index (BR-ID + one-line)
+│       ├── analysis.md             # Lifecycles, derived figures, mechanisms
 │       ├── behavior.md             # Consolidated behavior (Given/When/Then)
 │       └── events.md               # Domain Events catalog
 ├── features/
@@ -255,29 +286,112 @@ dflow/specs/
 
 ## 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.
+Dflow uses three tiers — **T1 Heavy / T2 Light / T3 Trivial** — plus a
+**below-workflow** level Dflow doesn't track at all. `/dflow:new-feature` and
+`/dflow:new-phase` are always T1 (no judgement). For `/dflow:modify-existing`
+and `/dflow:bug-fix`, classify the change with the **ordered cascade — the first
+step that matches wins** (order matters: a later catch-all would otherwise
+swallow the trivial and below-workflow cases):
+
+0. **Scope.** The cascade classifies a *modification*. Genuinely new work — a
+   new feature, page, or capability — is `/dflow:new-feature` (T1), even with no
+   new BR / Domain / schema. Adding a presentation or interaction control to an
+   **existing** surface (copy button, date-range filter, sort control, quick-view
+   drawer / tab, or filling a missing `aria-label`) is a *modification* (stays in
+   the cascade). A new user-executable domain operation (e.g. one-click return), a
+   new independently-consumable output or delivery channel (Download-PDF / export /
+   emailed report), or a **newly created** navigable surface (its own route and its
+   own content tree) **is** new-feature. Adding a menu entry or link that points at
+   a route that already exists is an access control on an existing surface —
+   a modification, not a new surface. **Unit of classification**: classify one
+   coherent requested change. Split a compound request into its atomic changes,
+   run each through the cascade, and let the highest tier govern the whole — each
+   lower-tier part still records its own artifact under the same host. Mechanical
+   fallout you did not ask for (formatter noise, lint churn) neither raises nor
+   lowers the result.
+   **Observation-only work is also outside the
+   cascade**: capturing existing behaviour as a baseline (Brownfield) changes no
+   output, so it carries no tier at all — record it and do not read step 2's
+   "below workflow" as permission to skip the record.
+1. **T1 — Heavy.** A **new** business rule or normative constraint (permission /
+   eligibility / threshold / approval / required outcome — regardless of whether a
+   BR-ID already exists). *New* means a rule that can be stated and broken on its
+   own: take the change away and the original rule still works exactly as before.
+   Changing an existing rule's parameters is **T2** — a different threshold value,
+   or adding to a set the rule already checks (one more allowed country, one more
+   approver role). Adding an independent condition the rule never had (an approver
+   predicate for a specific payment channel) is a new rule, and T1. A Domain concept (Aggregate / Entity / VO / Event)
+   **added or structurally changed** (identity, VO equality components, aggregate
+   boundary, or removing / renaming / redefining a spec-tracked member — a Domain
+   concept **rename** is T1); a persistent **data-structure** change (table /
+   column / relation / index added, removed, renamed, or its type / nullability /
+   constraint / logical definition changed); an **architectural** change
+   (inter-layer dependency direction, deployment / module boundary, runtime /
+   platform ownership, or overturning an architecture decision — behavior-
+   preserving still counts); or a **breaking** cross-consumer contract (API /
+   event). Contracts run **inbound** too — a required env var / deployment config
+   key, a CLI flag, an exit code, a scheduled-automation calling convention. What
+   breaks a caller is T1: removing or renaming one, changing what one means, or
+   adding a **required** key with no backward-compatible default (deployments must
+   act) — making an existing operation's parameter **required** breaks callers the
+   same way. Adding an *optional* key or parameter with a backward-compatible
+   default is non-breaking — T2 via step 4.
+2. **Below workflow — not tracked.** No audience-perceivable output delta **and**
+   no machine-consumed-contract or operational-semantics touch: auto-formatter
+   runs, whitespace, internal comments, internal-doc typos, commit messages, and
+   behavior-preserving **routine** refactors / dependency bumps. **Routine** =
+   touches no operational-semantics axis (security / safety / resilience /
+   compliance / payment) and is not architectural — **breadth is not the test** (a
+   behavior-preserving refactor across hundreds of call sites is still below
+   workflow; a single-file change that touches an operational axis is not). Never
+   below workflow, even when invisible: any BR-ID delta, any machine-consumed
+   structured-log / export / contract change, any deliberate runtime performance /
+   resource / SLA change, or any security / CVE / compliance work — those reach
+   step 1 or 4 by audience. `git commit` directly.
+3. **T3 — Trivial.** A **local, low-risk, meaning-preserving pure copy or
+   appearance change a product audience perceives** — display-text typo / wording
+   polish, colour, spacing, layout polish, or polishing existing alt / ARIA
+   wording — on a **single screen / component or single independently-consumed
+   page / file**, at the **element level**. **Excluded from T3**: high-consequence
+   content (security warnings, password hints, consent, payment / legal notices);
+   meaning-changing appearance (danger / status-colour semantics); anything
+   affecting operability, default state, interaction order, or task completion
+   ("just CSS" is no exemption); adding a **missing** accessible name (compliance
+   remediation); and text a machine consumes — an API error string or code a client
+   parses is contract, not display copy, so it is never T3: route it by the contract
+   axis instead (breaks the consumer → step 1, T1; otherwise → step 4, T2). **Locality is
+   the rendered audience footprint, not the number of source files**: one shared
+   component or localization key whose output appears on several screens is beyond
+   the local unit (T2), while edits to several files that surface in one place stay
+   T3. Anything beyond that unit is T2 — a typo swept across many screens, a
+   whole-screen visual rewrite, a cross-page sweep. The limit follows the whole
+   intent, so splitting one cross-screen typo sweep into per-screen requests does
+   not turn it into several T3s.
+4. **T2 — Light (catch-all — everything else).** Functional / semantic behavior
+   delta (logic, validation, interaction flow, display calculation, an
+   **existing** BR's delta, non-breaking contract semantics); performance-only
+   changes (perceivable or not); and copy / appearance sweeps escalated from step
+   3. Functional bug fixes are T2 (root-cause + regression notes).
+
+| Tier | Output | Command / Trigger |
+|---|---|---|
+| **T1 Heavy** | Independent `phase-spec-YYYY-MM-DD-{slug}.md` 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; durable summary stays in `models.md`) + update `context-map.md` + `events.md`. | `/dflow:new-feature` / `/dflow:new-phase` — also where a `/dflow:modify-existing` or `/dflow:bug-fix` request goes when the cascade lands it at T1 |
+| **T2 Light** | 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:modify-existing` or `/dflow:bug-fix` — the usual landing for a functional defect |
+| **T3 Trivial** | **Inline row in the host `_index.md` Lightweight Changes only** (no independent spec file) | `/dflow:modify-existing` or `/dflow:bug-fix` (`_index`-only branch — e.g. a defect that is only a display-text typo) |
+
+**Audience** = any human audience of the product perceives the output: UI
+(including alt / ARIA read by assistive tech), email, exports. Public / adopter-
+facing docs (product README, public API reference) and operator surfaces
+(dashboard labels, alerts) are product-audience: pure wording = T3 (single page;
+a cross-page sweep escalates to T2 at step 3), meaning change = T2. Raw internal
+diagnostic logs / traces are internal (copy-only fixes are below workflow).
+Structured logs / machine-readable exports a downstream consumer depends on are
+contract: breaking cross-consumer = step 1 T1, non-breaking = step 4 T2.
+
+**Project conventions can only escalate.** `_conventions.md` Ceremony (Project
+Application) rows are a floor-raising overlay applied *after* the cascade: a
+project may push a T2 up to T1, but may not lower a cascade T1, nor drop a
+tracked class below workflow.
 
 **DDD Modeling Depth (still informs T1 scope)**:
 
@@ -374,7 +488,7 @@ directory first. For example:
 |---|---|
 | `/dflow:new-feature` | `dflow/specs/shared/dflow-workflows/references/new-feature-flow.md` |
 | `/dflow:modify-existing` | `dflow/specs/shared/dflow-workflows/references/modify-existing-flow.md` |
-| `/dflow:bug-fix` | `dflow/specs/shared/dflow-workflows/references/modify-existing-flow.md` (lightweight-ceremony branch) |
+| `/dflow:bug-fix` | `dflow/specs/shared/dflow-workflows/references/modify-existing-flow.md` (same flow; tier comes from the cascade, not from the command) |
 | `/dflow:new-phase` | `dflow/specs/shared/dflow-workflows/references/new-phase-flow.md` |
 | `/dflow:finish-feature` | `dflow/specs/shared/dflow-workflows/references/finish-feature-flow.md` |
 | `/dflow:verify` | `dflow/specs/shared/dflow-workflows/references/drift-verification.md` |

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

@@ -115,7 +115,10 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 1. **Spec Before Code** — 沒有規格就不寫實作
 2. **Domain at the Center** — 業務邏輯只存在於 Domain 層
 3. **Ubiquitous Language** — 使用 `dflow/specs/domain/glossary.md` 中定義的術語
-4. **One Aggregate per Transaction** — 單一操作只修改一個 Aggregate
+4. **One Aggregate per Transaction（default）** — 單一操作預設只修改一個
+   Aggregate；有充分理由的 multi-root local transaction 例外，依
+   `dflow/specs/shared/dflow-workflows/references/ddd-modeling-guide.md`
+   「Aggregate Design Rules」記錄 domain rationale 與 re-evaluation condition
 5. **Dependency Inversion** — Domain 定義介面，Infrastructure 實作
 
 ### Domain Layer Rules (Hard Invariants)
@@ -147,7 +150,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 
 ### AI Collaboration Notes
 
-- 開發者提出任何需求時，先引導建立 spec 和 Aggregate 設計
+- 開發者提出需求時，先用 guide 的 § Ceremony Scaling ordered cascade 判 tier，再依 tier 決定產出：T1 才引導建立 spec 和 Aggregate 設計，T2 用 lightweight spec，T3 在所屬 feature 的 `_index.md` 記一行（沒有 active host 時，`/dflow:modify-existing` 會先開一個 minimal zero-phase host），below workflow 直接做
 - 確認實作順序：Domain → Application → Infrastructure → Presentation
 - 發現業務邏輯在錯誤的層時，指出並建議搬移
 - 每次開發循環結束時，提醒更新術語表、models.md、events.md

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,22 @@ 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. The hash it records is the hotfix's own
+commit, **not** the tagged merge commit on `main` (step 3): the record is
+never a merge commit, and step 4 merges the hotfix **branch**, so the tagged
+commit does not come into `develop` with it.
+`references/modify-existing-post-hoc-hotfix.md` item 3 has the rule.
+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,15 +182,22 @@ 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)
 
 ### Before merging a feature branch to `develop`
 
-- [ ] `/dflow:finish-feature` has run (or the equivalent Step 8.4
-      manual archival is complete)
+- [ ] **Closeout complete**: `/dflow:finish-feature` has announced closeout
+      complete for this host — its Local-closeout gate is satisfied (the
+      closeout commit landed and passed post-commit verification) and, if
+      the host carries `follow-up-of`, the Step 6 tracking commit has also
+      landed and been verified. `status: completed` or a directory already
+      under `completed/` does not show this on its own.
 - [ ] `_index.md` status = `completed`, feature directory moved to
       `dflow/specs/features/completed/` via `git mv`
 - [ ] BC layer synced: `dflow/specs/domain/{context}/rules.md`,
@@ -176,6 +209,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 —
+> **Closeout complete**, `_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 +257,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 +336,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 +350,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,15 +267,22 @@ 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)
 
 ### Before merging a feature branch to `main` (opening / merging the PR)
 
-- [ ] `/dflow:finish-feature` has run (or the equivalent Step 8.4
-      manual archival is complete)
+- [ ] **Closeout complete**: `/dflow:finish-feature` has announced closeout
+      complete for this host — its Local-closeout gate is satisfied (the
+      closeout commit landed and passed post-commit verification) and, if
+      the host carries `follow-up-of`, the Step 6 tracking commit has also
+      landed and been verified. `status: completed` or a directory already
+      under `completed/` does not show this on its own.
 - [ ] `_index.md` status = `completed`, feature directory moved to
       `dflow/specs/features/completed/` via `git mv`
 - [ ] BC layer synced: `dflow/specs/domain/{context}/rules.md`,
@@ -247,8 +295,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 —
+> **Closeout complete**, `_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 +363,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 +385,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.