dflow-sdd-ddd 0.1.0

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

@@ -0,0 +1,375 @@
+<!-- Scaffolding template maintained alongside Dflow skill. See proposals/PROPOSAL-010 for origin. -->
+
+# Git Principles — Trunk-based / GitHub Flow edition
+
+> Created: {YYYY-MM-DD}
+> Scope: project Git conventions. This project adopts a **single-`main`
+> trunk-based / GitHub Flow** branching strategy.
+> Audience: engineers + AI assistants performing Git operations.
+
+Dflow itself is branching-strategy-neutral — it only requires the
+feature-branch-per-feature convention (see the Dflow skill's
+`references/git-integration.md`). This file records the trunk-based
+conventions chosen by this project.
+
+If your project adopts Git Flow (develop / release / hotfix branches),
+use `Git-principles-gitflow.md` instead.
+
+---
+
+## 1. Branch Structure
+
+Single-trunk model:
+
+| Branch | Naming | Cut from | Merges to |
+|--------|--------|----------|-----------|
+| `main` | `main` | — | — (protected; feature branches merge in) |
+| feature | `feature/{SPEC-ID}-{slug}` | `main` | `main` |
+
+No `develop`, no `release/*`, no `hotfix/*` branches. Hotfixes are just
+small, fast feature branches cut from `main`.
+
+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.
+
+### Feature Branch Workflow
+
+```bash
+# 1. Start from latest main
+git checkout main
+git pull origin main
+git checkout -b feature/{SPEC-ID}-{slug}
+
+# 2. Stay in sync with main during development (rebase preferred)
+git fetch origin
+git rebase origin/main
+
+# 3. Commit as you go (see § 2 below)
+git add .
+git commit -m "[{SPEC-ID}] {short description}"
+
+# 4. Push + open PR
+git push -u origin feature/{SPEC-ID}-{slug}
+gh pr create --base main --fill
+```
+
+### Key trunk-based practices
+
+- **Short-lived feature branches**: typically hours to a few days, not
+  weeks. Encourage splitting large features into multiple phase-specs
+  and merging each phase to `main` (see Dflow's Ceremony Scaling +
+  `/dflow:new-phase`)
+- **Main is always releasable**: feature flags or dark launches for
+  incomplete functionality; CI must be green on `main` at all times
+- **Rebase, don't merge, during development**: keep history linear on
+  the feature branch by rebasing against `main`; use squash / rebase
+  merge (not `--no-ff`) when merging into `main`
+
+---
+
+## 2. Commit Message Format
+
+Commits must tie back to a SPEC-ID. Conventional Commits style is
+recommended but not strictly required:
+
+```
+{type}({scope}): {short description}
+
+[{SPEC-ID}] {longer description, optional}
+
+Co-Authored-By: Claude <noreply@anthropic.com>   ← suggested, not mandatory
+```
+
+### Type prefix (Conventional Commits)
+
+| Type | Meaning |
+|------|---------|
+| feat | new feature |
+| fix | bug fix |
+| refactor | internal refactor (no behavior change) |
+| docs | documentation only |
+| style | formatting only |
+| test | tests only |
+| chore | build / tooling |
+
+### Scope (optional)
+
+Scope is typically a bounded context or module name, e.g.
+`feat(expense): introduce ExpenseReport submission invariants`.
+
+### Example
+
+```
+feat(expense): add ExpenseReport submission invariants
+
+[SPEC-20260421-001] Introduce ExpenseReport Aggregate with submission
+state machine; enforces non-negative Amounts and requires at least one
+ExpenseItem before submission.
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+---
+
+## 3. Merge Strategy Options
+
+Trunk-based projects typically pick **one** of the three below as the
+default. Document which one your team uses:
+
+### Option A — Squash merge (most common)
+
+All commits on the feature branch are squashed into a single commit on
+`main`. Clean history; each feature is one commit.
+
+- Pro: Linear, easy-to-read history
+- Pro: Cherry-picks and reverts are trivial
+- 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
+history, but more commits than squash.
+
+- Pro: Preserves commit-by-commit history
+- Pro: Each phase-spec can map to its own commit (trace SPEC-ID by
+  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`.
+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
+
+`/dflow:finish-feature` emits a **Git-strategy-neutral Integration
+Summary** (see `references/finish-feature-flow.md` in the Dflow skill).
+This section specifies how to turn that Summary into the actual
+commit message under each trunk-based merge style.
+
+### 4.1 Squash merge commit format
+
+When squash-merging, the single resulting commit should look like this:
+
+```
+feat({scope}): {title from Integration Summary}
+
+{Feature Goal block, copied from Integration Summary}
+
+Change Scope:
+- BC: {context-name}
+- Aggregate(s) touched: {Aggregate names}
+- Phase Count: {N}
+- Lightweight Changes: {n_t2} T2 + {n_t3} T3
+
+Related BR-IDs:
+- ADDED: BR-NN, BR-NN
+- MODIFIED: BR-NN
+- REMOVED: (none)
+
+Domain Events introduced / modified: {Event names, or "(none)"}
+
+Related SPEC-IDs: {SPEC-ID}{, follow-up SPEC-IDs if any}
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+GitHub PR editor can be pre-filled with this body; the merge button
+then produces the squash commit.
+
+### 4.2 Rebase merge (per-commit, multi-phase feature)
+
+If the feature has N phase-specs, you can produce N commits (one per
+phase) on `main`:
+
+- Each commit retains its original `[{SPEC-ID}][Phase-N]` prefix from
+  development
+- **The last commit** of the rebased chain should carry the Integration
+  Summary as its extended body, so a reader scanning the last commit
+  sees the feature-level summary:
+
+```
+feat({scope}): {Phase N title} — closes {SPEC-ID}
+
+[{SPEC-ID}][Phase-N] {phase-level description}
+
+--- Feature integration summary ---
+{Feature Goal block}
+Change Scope: ... (as in §4.1)
+Related BR-IDs: ...
+Domain Events: ...
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### 4.3 Fast-forward (feature has 1 commit total)
+
+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.
+
+---
+
+## 5. Gate Checks
+
+Before making key Git operations:
+
+### Before `git commit`
+
+- [ ] If the change corresponds to a phase-spec, that phase-spec's
+      `Implementation Tasks` section items are checked (or remaining items have
+      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)
+- [ ] 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)
+- [ ] `_index.md` status = `completed`, feature directory moved to
+      `dflow/specs/features/completed/` via `git mv`
+- [ ] BC layer synced: `dflow/specs/domain/{context}/rules.md`,
+      `behavior.md`, `events.md`, and (if cross-context)
+      `context-map.md` reflect the feature's net changes
+- [ ] `dflow/specs/domain/glossary.md` updated with any new terms
+- [ ] `dflow/specs/architecture/tech-debt.md` updated with any debt discovered
+- [ ] Domain project has zero external NuGet dependencies
+- [ ] No ORM / serialization attributes on Domain entities
+- [ ] Domain unit tests pass (invariants + value object equality)
+- [ ] CI is green (all required checks passing)
+
+---
+
+## 6. AI Collaboration Rules (Project Policy)
+
+Three categories:
+
+### Must-confirm operations (AI asks before running)
+
+| Operation | Why |
+|-----------|-----|
+| `git commit` | Stage needs human review |
+| `git push` | Publishing to shared remote |
+| `gh pr merge` (squash / rebase) | Shared-branch impact |
+| Any `git rebase` that rewrites shared history | Force-push risk |
+
+### Forbidden operations
+
+| Operation | Reason |
+|-----------|--------|
+| `git push -f` to `main` | Overwrites other people's work |
+| `git reset --hard` to a remote branch | Irreversible |
+| `git commit --amend` on a pushed commit | Rewrites public history |
+| Deleting `main` | Protected branch |
+
+### Allowed without asking
+
+| Operation |
+|-----------|
+| `git status` / `git diff` / `git log` / `git show` |
+| `git fetch` (no merge) |
+| `git stash` (local-only) |
+| `git branch` (listing only) |
+| `gh pr status` / `gh pr view` |
+
+### AI commit authorship (suggested, not enforced)
+
+When an AI assists in producing a commit, appending a `Co-Authored-By`
+line is **suggested** but not mandatory. The canonical form for
+Claude is:
+
+```
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+For other AI assistants, use the vendor-documented author line (or omit
+it). This is a project-level transparency convention, not a Dflow
+requirement.
+
+---
+
+## 7. Hotfixes under Trunk-based
+
+There is no separate `hotfix/*` branch. A hotfix is:
+
+1. A (small) feature branch cut from `main`
+2. Named `feature/{SPEC-ID}-{slug}` where SPEC-ID is a lightweight spec
+   or a full-ceremony spec depending on severity
+3. Merged back to `main` via the team's chosen merge strategy
+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.
+This is a **human-to-human commitment** — Dflow / AI cannot track the
+24-hour clock; the team enforces it in retros.
+
+---
+
+## 8. Release & Versioning
+
+Trunk-based does not impose a release branch. Two common patterns:
+
+### Pattern A — Tag-based release (recommended)
+
+Each deploy-worthy state of `main` is tagged:
+
+```bash
+git tag -a v{major}.{minor}.{patch} -m "{release summary}"
+git push origin --tags
+```
+
+### Pattern B — Release branches (only if regulatory / LTS needs)
+
+Cut `release/{version}` from `main` only when you must maintain an
+older version. Use sparingly; avoid if possible.
+
+### `CHANGELOG.md`
+
+Detailed version history lives in `CHANGELOG.md` at the repo root. One
+section per release tag; link back to the SPEC-IDs included in that
+release.
+
+---
+
+## 9. CI / CD
+
+{Fill in this project's CI/CD pipeline shape: trigger (push to main,
+tag), stages (build → test → deploy), environments
+(dev / staging / prod). Reference the pipeline config file if one
+exists, e.g. `.github/workflows/ci.yml` or `azure-pipelines.yml`.}
+
+### Suggested CI gates for Clean Architecture
+
+- Verify Domain project has zero (or allow-listed) NuGet deps
+- Run Domain unit tests + Application tests on every PR
+- Run Integration tests on `main` and pre-deploy
+- Verify EF migrations build cleanly
+
+---
+
+## Related Documents
+
+- `references/git-integration.md` in the Dflow skill — canonical
+  source for feature-branch-per-feature, `git mv` mandate, Gate Checks
+- [System overview](_overview.md)
+- [Spec conventions](_conventions.md)
+- `CHANGELOG.md` at repo root

package/templates/core/scaffolding/_conventions.md

@@ -0,0 +1,175 @@
+<!-- Scaffolding template maintained alongside Dflow skill. See proposals/PROPOSAL-010 for origin. -->
+
+# Spec Writing Conventions — {System Name}
+
+> Created: {YYYY-MM-DD}
+> Scope: how spec documents are authored and named in this project.
+> Audience: engineers writing specs; AI assistants producing spec drafts.
+
+This file captures **project-level** conventions only. Template shapes
+and Ceremony criteria are defined by the Dflow skill; here we just
+record how *this* project fills them in.
+
+---
+
+## Where Specs Live
+
+All spec documents live under `dflow/specs/`. The feature directory pattern
+and file names follow Dflow (see the Dflow skill § "Project Structure"
+for the full tree):
+
+```
+dflow/specs/features/active/{SPEC-ID}-{slug}/
+├── _index.md                              # Feature dashboard
+├── phase-spec-{YYYY-MM-DD}-{slug}.md      # T1 Heavy (one per phase)
+└── lightweight-{YYYY-MM-DD}-{slug}.md     # T2 Light (or BUG-{NUMBER}-{slug}.md)
+```
+
+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`)
+- Per-day counter `NNN` resets daily, starts at `001`
+- 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`)
+
+### Slug Conventions (Project-Specific Fill-In)
+
+- **Language**: follow the language the feature is discussed in (Dflow
+  skill policy); no translation is forced. Both Chinese and English
+  slugs are valid.
+- **Project-specific term list**: {fill in project-specific abbreviation
+  conventions here, e.g. "bounded context name shortenings",
+  "Aggregate name → slug rules"; otherwise leave empty}
+- **Length target**: 2–4 English words or 2–6 Chinese characters
+  (Dflow skill guidance)
+
+---
+
+## Filling the Templates
+
+Dflow ships these templates (do **not** re-inline their content here
+— always read the canonical template from the skill):
+
+| 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/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 |
+
+Project-specific guidance when filling these templates:
+
+### DDD-specific spec conventions
+
+- **Aggregate identification**: every phase-spec that introduces new
+  behavior should explicitly name the Aggregate involved. If the
+  change spans Aggregates, call that out in the spec's "Domain
+  Modeling" section and explain the integration strategy (Domain
+  Event? Query? ACL?).
+- **Domain Events documentation**: events belong in
+  `dflow/specs/domain/{context}/events.md`. When a phase-spec introduces or
+  modifies an event, update `events.md` during Step 8.3 sync — do not
+  only update it in the feature-level spec.
+- **Aggregate state transitions**: for phase-specs that change
+  Aggregate state, include explicit "state-before → state-after"
+  descriptions (Mermaid state diagram or Given / When / Then + "And
+  the Aggregate is in state X").
+- **CQRS split**: commands (write) vs queries (read) should be
+  identified during Phase 4 (Implementation Planning). Commands
+  generally map 1:1 to an Aggregate method; queries bypass the
+  Domain layer and read projections.
+
+### Project-specific fill-ins
+
+- {e.g. "All Money amounts use the `Money` value object with explicit
+  currency; do not use `decimal` for money in the Domain layer."}
+- {e.g. "Every Aggregate has a `CreatedAt` / `LastModifiedAt`
+  shadow property; this is implemented in the Infrastructure layer
+  EF configuration, not in the Domain."}
+- {e.g. "Pagination for queries uses `PagedResult<T>` defined in
+  SharedKernel."}
+
+---
+
+## Ceremony Scaling (Project Application)
+
+The Dflow skill defines three tiers — **T1 Heavy / T2 Light / T3
+Trivial**. See the Dflow skill § "Ceremony Scaling" for the full
+criteria table. We do not re-define the tier criteria here; this
+section records how *this* project applies them in borderline
+situations.
+
+| 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 |
+
+### DDD Modeling Depth (Dflow skill § Ceremony Scaling)
+
+The Dflow skill further distinguishes:
+
+- **Full** (new Aggregate / new BC): use `templates/aggregate-design.md`
+  + update `context-map.md` + define events in `events.md`
+- **Standard** (feature within existing BC, existing Aggregate):
+  confirm Aggregate ownership + update `models.md` / `rules.md`
+- **T2 / T3**: confirm the fix lands in the correct layer; no
+  design-level updates required
+
+Use this table to record project-specific interpretation if needed.
+
+---
+
+## Glossary Consistency
+
+All business terms in spec documents must use names defined in
+`dflow/specs/domain/glossary.md`. When a new term appears:
+
+1. Check glossary first
+2. If missing, add it **before** using the term in a spec
+3. Cross-reference the BC the term belongs to
+4. If the term maps to a code construct (Aggregate / VO / Event), add
+   the `Code Mapping` column value
+
+This rule is enforced by the Dflow skill during `/dflow:new-feature`
+and `/dflow:new-phase` flows; the project-level convention is simply
+"don't bypass the glossary update."
+
+---
+
+## Related Documents
+
+- [System overview](_overview.md)
+- [Git principles](Git-principles-{gitflow|trunk}.md)
+- [Context map](../domain/context-map.md)
+- [Glossary](../domain/glossary.md)
+- Dflow skill `SKILL.md` — canonical source for Ceremony Scaling, flow
+  selection, and template shapes.
+- Dflow skill `references/ddd-modeling-guide.md` — DDD tactical
+  pattern reference.