dflow-sdd-ddd 0.14.0 → 0.16.0

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

@@ -64,8 +64,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. |
@@ -81,8 +81,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 |
@@ -103,16 +103,36 @@ input like this (supporting files live in the workflow bundle at
 - **"Quick question about..." / "How does X work?"** → check
   `dflow/specs/domain/` first and answer from the documented domain knowledge.
   If no spec exists yet, suggest documenting the answer as 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.
 - **"What should I work on next?" / sprint planning** → review
   `dflow/specs/features/backlog/` and suggest work based on migration value.
 - **"I'm creating a branch"** → read `references/git-integration.md`; verify
-  branch naming and ensure a spec exists before coding starts.
+  branch naming, and make sure the tier's own record exists before coding starts
+  (T1 / T2: a spec; T3: the host `_index.md` row — a T3 branch has no spec file).
 - **"I'm designing a domain model" / "How should I model X?" / building or
   reshaping an Aggregate** → read `references/ddd-modeling-guide.md` (DDD
   tactical patterns: aggregates, invariants, value objects, domain events). It
   is written with Greenfield artifact names; see its **Edition note** for where
   Brownfield records the same decisions (`models.md` / `rules.md` /
   `behavior.md` / `migration/tech-debt.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
@@ -121,10 +141,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
 
@@ -250,6 +278,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` |
@@ -265,10 +295,13 @@ dflow/specs/
 │   └── _conventions.md           # Spec writing conventions
 ├── domain/                       # Domain knowledge (DDD preparation)
 │   ├── glossary.md               # Ubiquitous Language
+│   ├── context-map.md            # Bounded Context relationships (created when needed)
+│   ├── analysis.md               # Cross-context flows and role reach
 │   └── {bounded-context}/        # e.g., expense/, hr/, leave/
 │       ├── context.md            # Context boundary & responsibilities
 │       ├── models.md             # Entity, VO, Aggregate definitions
 │       ├── rules.md              # Business rules index (BR-ID + one-line)
+│       ├── analysis.md           # Lifecycles, derived figures, mechanisms
 │       └── behavior.md           # Consolidated behavior (Given/When/Then)
 ├── features/
 │   ├── active/                   # Currently in development
@@ -297,29 +330,112 @@ dflow/specs/
 ## Ceremony Scaling
 
 Not everything needs full ceremony — match effort to impact. 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, 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 | `/dflow:new-feature` / `/dflow:new-phase` |
-| **T2 Light** | Bug fix, 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 | `/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.
+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` placed in the feature directory + `_index.md` Phase Specs row + refresh BR Snapshot | `/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 | `/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.
 
 **Lightweight spec** = Problem + Expected behavior + 1–2 Given/When/Then. The
 instantiated file is placed inside the feature directory (see
@@ -393,7 +509,8 @@ during the completion checklist, not via template section markers.
 - Did we discover scattered business logic? → Record in tech-debt.md
 - Are there duplicated calculations? → Record
 - Direct SQL in delivery/entrypoint code? → Record
-- Magic numbers or undocumented statuses? → Record and add to glossary
+- Magic numbers? → Record and add to glossary
+- Undocumented status values? → List them in their field's lifecycle in `analysis.md`
 
 ## Workflow Steps
 
@@ -411,7 +528,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/brownfield/scaffolding/CLAUDE-md-snippet.md

@@ -114,7 +114,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - `/dflow:new-feature` — 新功能開發
 - `/dflow:new-phase` — 在 active feature 內新增階段
 - `/dflow:modify-existing` — 修改既有功能
-- `/dflow:bug-fix` — 輕量修復
+- `/dflow:bug-fix` — Bug 修復
 - `/dflow:finish-feature` — feature 收尾
 - `/dflow:pr-review` — PR 審查
 - `/dflow:verify` — rules.md ↔ behavior.md 漂移檢查

package/templates/brownfield/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
@@ -107,10 +121,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/migration/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/migration/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,12 +182,19 @@ 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.
 
 ### 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` and
@@ -170,6 +203,23 @@ before making key Git operations:
 - [ ] `dflow/specs/migration/tech-debt.md` updated with any debt discovered
 - [ ] Domain layer (`src/Domain/`) has no delivery-framework references
 
+> **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, a **T3** does no Domain work at all,
+> and a **baseline capture** wrote Domain documents directly rather than syncing
+> to them — so for those they read N/A. **Bounded-context-scoped only** —
+> `glossary.md` and `migration/tech-debt.md` belong to no bounded context, stay
+> in a no-BC host's sweep, and are a baseline capture's own capture
+> destinations, so they are **not** N/A for either. **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
@@ -200,6 +250,31 @@ Related BR-IDs:
 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
+- 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}
+```
+
+`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, and a baseline host leaves the field empty). 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. A **baseline capture** is
+the one variant that always reports a real `BC:` — capturing it is the whole
+point of the host.
+
 ### Concrete example
 
 ```bash
@@ -252,7 +327,7 @@ release.
 Example entry:
 
 ```markdown
-## [1.2.3] — {YYYY-MM-DD}
+## [1.2.3] — {2026-04-21}
 
 ### Added
 - {SPEC-20260421-001}: JPY currency support in Money value object
@@ -266,6 +341,8 @@ Example entry:
 
 ---
 
+<!-- dflow-generated: git-principles-canonical END -->
+
 ## 6. AI Collaboration Rules (Project Policy)
 
 Three categories:

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

@@ -22,6 +22,8 @@ and long-lived release branches.
 
 ---
 
+<!-- dflow-generated: git-principles-canonical START -->
+
 ## 1. Branch Structure
 
 | Branch | Naming | Cut from | Merges to |
@@ -35,6 +37,17 @@ happens on short-lived feature / bugfix branches cut from `main` and
 merged back into `main` quickly (ideally within a day, always
 within a week).
 
+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/`.
+
 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.
@@ -76,8 +89,8 @@ Commits must tie back to a SPEC-ID:
 
 ### Conventional Commits style (recommended, optional)
 
-This project {does / does not} require Conventional Commits. When
-adopted, the format is:
+Conventional Commits is optional. **Record whether this project requires it
+in § 6, under "Commit and merge choices".** When adopted, the format is:
 
 ```
 {type}({scope}): {short description}
@@ -103,9 +116,9 @@ Example: `feat(expense): add JPY currency support` with
 ## 3. Merge Strategy (Project Chooses)
 
 Trunk-based strategies typically pick **one** merge style and stick to
-it. This project uses: **{squash | rebase | fast-forward}**. Delete
-the two unused options once decided, or keep all three in the table
-and circle the chosen one.
+it. The table below gives the trade-offs; **record this project's choice
+in § 6, under "Commit and merge choices"** — that section is yours, this
+one is not.
 
 | Strategy | How the feature lands on `main` | When to prefer |
 |----------|--------------------------------|----------------|
@@ -120,12 +133,19 @@ and circle the chosen one.
       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.
 
 ### Gate Checks — Before merging a feature PR to `main`
 
-- [ ] `/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` and
@@ -136,6 +156,23 @@ and circle the chosen one.
 - [ ] CI green
 - [ ] PR has at least one review approval
 
+> **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, a **T3** does no Domain work at all,
+> and a **baseline capture** wrote Domain documents directly rather than syncing
+> to them — so for those they read N/A. **Bounded-context-scoped only** —
+> `glossary.md` and `migration/tech-debt.md` belong to no bounded context, stay
+> in a no-BC host's sweep, and are a baseline capture's own capture
+> destinations, so they are **not** N/A for either. **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
@@ -170,6 +207,31 @@ Related BR-IDs:
 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
+- 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}
+```
+
+`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, and a baseline host leaves the field empty). 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. A **baseline capture** is
+the one variant that always reports a real `BC:` — capturing it is the whole
+point of the host.
+
 Example:
 
 ```
@@ -208,11 +270,17 @@ losing the feature-level summary.
 
 ### 4.3 Fast-forward (feature has exactly 1 commit)
 
-If the entire feature was a single commit (common for T2 / T3-only
-features or minimal features), fast-forward is fine. Use the commit
+If the entire feature was a single commit (a hosted T2 / T3 whose work and
+record landed together), fast-forward is fine. Use the commit
 message format from § 4.1 (squash) for that single commit — it already
 reads as the feature's single narrative.
 
+**A minimal (zero-phase) host is never this case.** It records **exactly two**
+commits — the implementation (or `spec-baseline`) 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.
+
 ```bash
 git checkout main
 git pull --ff-only origin main
@@ -244,6 +312,8 @@ style.
 
 ---
 
+<!-- dflow-generated: git-principles-canonical END -->
+
 ## 6. AI Collaboration Rules (Project Policy)
 
 Three categories:
@@ -292,6 +362,14 @@ 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.
 
+### Commit and merge choices
+
+Dflow does not choose these for you; §§ 2-3 give the trade-offs. Record what
+this project settled on:
+
+- **Conventional Commits**: {required / not required — fill in}
+- **Merge strategy**: {squash / rebase / fast-forward — fill in}
+
 ---
 
 ## 7. CI / CD