dflow-sdd-ddd 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,98 @@
 
 ---
 
+## 0.4.0 — 2026-05-19 — Language-agnostic templates and skill source
+
+**Proposals**：PROPOSAL-030（language-agnostic templates and skill source；
+post-v0.3.0 follow-up; cross-model reviewed with Codex CLI）
+
+**變更**：
+
+- **`lib/init.js` canonical placeholders + backward-compat aliases**（PROPOSAL-030 Group 1）：
+  - 新增 canonical placeholders：`{Language}` / `{Framework}` /
+    `{Framework version}` / `{ORM / persistence}` / `{ORM version}` /
+    `{Mediator}`（與既有 `{Test framework}` 對齊）
+  - 既有 .NET-specific placeholder（`{ASP.NET Core version}` /
+    `{EF Core version}` / `{MediatR version}` / `{ASP.NET WebForms version}` /
+    `{.NET Framework version}` / `{ORM / Data Access}`）保留為 backward-compat
+    alias，substitute 同 canonical 值
+  - `extractTechStackPlaceholders` regex 擴充：Spring Boot / NestJS /
+    Fastify / Express / Django / FastAPI / Flask / Gin / Echo / Laravel
+    framework；EF Core / Hibernate / Spring Data JPA / SQLAlchemy /
+    Prisma / TypeORM / MikroORM / GORM / Eloquent / Doctrine ORM；JUnit /
+    Vitest / Jest / Mocha / pytest / unittest / go test / PHPUnit / Pest
+    test framework；C# / TypeScript / JavaScript / Kotlin / Java /
+    Python / Go / PHP / Ruby language
+  - `detectProjectSignals` 加 `stackHints`（從 `pom.xml` / `package.json` /
+    `pyproject.toml` / `go.mod` / `Cargo.toml` / `composer.json` / `Gemfile`
+    fingerprint）— **不**自動推 `trackHint`，user 選擇仍主導
+  - `printNextSteps` 加 `docs/examples-by-stack.md` pointer
+- **Brownfield skill source + templates language-agnostic**（Group 2 + Group 2 follow-up）：
+  - `Code-Behind` → umbrella `business logic embedded in delivery/entrypoint
+    code`，context 簡寫 `presentation-layer logic` (web/UI/API) 或
+    `entrypoint-layer logic` (CLI/batch/pipeline)
+  - `ASP.NET Core migration` / `future ASP.NET Core migration` →
+    `target architecture`
+  - `No System.Web references` → `No delivery-framework references`，明列
+    HTTP req/resp、session/cookie、job-runner context、CLI flag parser、
+    ViewState equivalents 等多 stack 示例
+  - `純 C# class` → `framework-pure class`
+  - Layer tag `PAGE` → `DELIVERY`（含 lightweight-spec 的 layer tags
+    說明擴及 web/CLI/job/pipeline）
+  - SKILL.md 新增 `## Scope: When Dflow Brownfield Applies` 段，明標適用
+    business-rule-bearing legacy systems / 不適用純 infra script 或無
+    domain model pipeline
+  - 目錄樹 `src/Pages/` → `src/Delivery/`（與 umbrella term 對齊）
+  - SKILL.md / templates/CLAUDE.md / scaffolding/CLAUDE-md-snippet.md /
+    scaffolding/_overview.md 在 directory tree 前加 stack-adapt callout
+- **Greenfield skill source + templates language-agnostic**（Group 3 + Group 3 follow-up）：
+  - 檔案標題 `# Project — ASP.NET Core + DDD` →
+    `# Project — Clean Architecture + DDD`
+  - `# X Workflow — ASP.NET Core` → `# X Workflow — Greenfield Clean Architecture`
+  - Cross-edition `Same as WebForms version` → `Same as Brownfield edition`
+  - `_overview.md` stack table 全用 canonical placeholders
+  - `init-project-flow.md` Q2 prompt + substitution table 改 canonical
+  - Project Layout `{Project}.Domain` `.NET` 慣例保留 + 加詳細 callout
+    列 Java/Spring、Node/TS、Python、Go、PHP/Laravel 對應
+  - `PRACTICE_PLAN_tw.md` 開頭加 disclaimer：練習以 .NET 為示例、
+    Dflow 本身 language-agnostic
+  - Git-principles-{gitflow,trunk} 的 `NuGet dependencies` →
+    `external package dependencies`
+- **`docs/examples-by-stack.md` 新增**（Group 4）：520 行 public
+  appendix，列 7 stack 段（.NET ASP.NET Core greenfield / .NET WebForms
+  brownfield / Java Spring Boot / Node TypeScript NestJS / Python FastAPI /
+  Go Gin / PHP Laravel），每段：substituted stack table + project
+  layout + per-stack domain purity check + test framework + run
+  command。`README.md` / `README.en.md` 在 Project Tracks 段加 link。
+- **`planning/init-contract-spec.md` 同步**（Group 1）：placeholder
+  inventory + alias table + detectProjectSignals stackHints 文件對齊
+
+**Breaking / migration notes**：
+
+- **無 runtime API 破壞**：v0.3.0 寫入 user project 的 `CLAUDE.md` /
+  `_overview.md` 等檔案 Dflow 不會自動覆蓋；backward-compat alias 只保護
+  future init 動作的 placeholder 替換不破壞，不主動 migrate 既有檔案
+- 若要對齊新風格，請參考 `docs/examples-by-stack.md` 對既有 init 產出的
+  檔案手動修改
+- AI agent 對話中讀 skill source 會自動切到新術語（Code-Behind →
+  delivery/entrypoint code、ASP.NET Core migration → target architecture）；
+  若 user 有自製 prompt / shortcut 用到舊術語，建議同步更新但**不強制**
+
+**驗證**：
+
+- `npm test`（含新增 Java/Spring Boot greenfield init e2e，assert 不殘留 .NET literals）
+- `scripts/check-repo-consistency.sh`（source ↔ packaged mirror diff clean）
+- 全 repo grep `Code-Behind` / `ASP.NET` / `WebForms` / `NuGet` 在 active skill / template surface 範圍內無殘留（archive/ 與 test fixture 刻意保留）
+
+**邊界**：
+
+- Tutorial 目錄 `tutorial/**` scenario prose 為教學劇情 artifact，明確
+  out of scope（PROPOSAL-030 §影響範圍 已宣告）
+- `test/smoke.mjs` 既有 .NET fixture 保留作為 brownfield init 測試輸入
+- Dist projection 在所有 Group merge 完後一次性 export（Director-only）
+
+---
+
 ## 0.3.0 — 2026-05-18 — Workflow flow completion, terminology disambiguation, bilingual public docs
 
 **Proposals**：PROPOSAL-022（CLI install 推薦路徑）、PROPOSAL-023（line-ending normalization）、PROPOSAL-024（README zh-TW + migration reframing）、PROPOSAL-025（Phase 術語拆解：Step Gate / Activity）、PROPOSAL-026（`/dflow:new-phase` 補 implementation / verification）、PROPOSAL-027（handoff lifecycle，dev-only）、PROPOSAL-028（`docs/*.md` 雙語化）、PROPOSAL-029（tutorial 檔名 align）。

package/README.en.md

@@ -113,15 +113,15 @@ Greenfield and Brownfield workflows with worked spec outputs, see the
 | **Greenfield** | You are starting a new system or a new bounded area with room to shape architecture and domain model early. | Clean spec baseline, domain model ownership, feature-by-feature implementation through SDD. |
 | **Brownfield** | You are adding or changing behavior in an existing codebase where business rules may already be scattered. | Progressive domain extraction, safer change planning, and migration-ready domain knowledge. |
 
-These tracks describe adoption style, not framework branding. Dflow should be read as a workflow system for software teams that want AI assistance without giving up domain clarity.
+These tracks distinguish the project's starting state (new vs existing codebase), not a framework choice; the design makes no assumption about language or stack. Dflow should be read as a workflow system for software teams that want AI assistance without giving up domain clarity.
 
-### Track Choice and Migration
+Filled-in examples for common stacks (.NET, Java/Spring, Node/TypeScript, Python, Go, PHP/Laravel) are in [`docs/examples-by-stack.md`](./docs/examples-by-stack.md).
 
-> The "rewrite to ASP.NET Core" path below is the default migration story baked into the current Dflow templates (reflecting Dflow's initial C# / ASP.NET use case), but the design itself is language- and framework-agnostic — the workflow, tier system, and documentation model work for any stack.
+### Track Choice and Migration
 
-Track is fixed at `dflow init` time and **cannot be switched in-place** (there is no `/dflow:switch-to-greenfield` command). Brownfield is by design a preparation path toward Greenfield: pure C# code extracted into `src/Domain/` and the domain documents under `dflow/specs/domain/` (glossary, rules, models, events) are all migration-ready assets — at the eventual rewrite (new ASP.NET Core project + fresh `dflow init` with Greenfield track), they can be lifted directly. `dflow/specs/migration/tech-debt.md` is the brownfield-specific migration debt log.
+Track is fixed at `dflow init` time and **cannot be switched in-place** (there is no `/dflow:switch-to-greenfield` command). Brownfield is by design a preparation path toward Greenfield: domain code extracted into the project's domain layer (e.g., `src/Domain/`) and the domain documents under `dflow/specs/domain/` (glossary, rules, models, events) are all migration-ready assets — at the eventual rewrite (a new project + fresh `dflow init` with Greenfield track), they can be lifted directly. `dflow/specs/migration/tech-debt.md` is the brownfield-specific migration debt log.
 
-Per-BC migration is also supported — once a Bounded Context's logic is fully extracted into `src/Domain/` and the Code-Behind is reduced to UI binding, that BC is already in a Clean Architecture state; the whole system doesn't have to switch in one go. The brownfield `/dflow:modify-existing`'s "assess Code-Behind" step becomes a no-op for that BC naturally.
+Per-BC migration is also supported — once a Bounded Context's business logic is fully extracted into the domain layer and the presentation layer is reduced to UI binding, that BC is already in a Clean Architecture state; the whole system doesn't have to switch in one go. The brownfield `/dflow:modify-existing`'s "assess presentation-layer business logic" step becomes a no-op for that BC naturally.
 
 ## Workflow Model
 

package/README.md

@@ -83,24 +83,24 @@ dflow doctor
 
 第一次採用建議用 branch 或一次性試用專案，讓團隊先檢視產生的 `dflow/specs/` 工作區，再把流程引入正式程式碼。
 
-完整評估流程（init 產生哪些檔案、AI 工具支援、track 選擇、30 分鐘試用 playbook）見 [評估 Dflow](docs/evaluating-dflow.md)。Greenfield 與 Brownfield 端到端劇情走完與規格範例見 [`tutorial/`](tutorial/README.md) 索引。
+完整評估流程（init 產生哪些檔案、AI 工具支援、模式選擇、30 分鐘試用 playbook）見 [評估 Dflow](docs/evaluating-dflow.md)。Greenfield 與 Brownfield 端到端劇情走完與規格範例見 [`tutorial/`](tutorial/README.md) 索引。
 
-## 專案 Track
+## 專案模式
 
-| Track | 何時用 | 主要產出 |
+| 模式 | 何時用 | 主要產出 |
 |---|---|---|
 | **Greenfield** | 新系統或新 bounded area，有空間早期塑形架構與領域模型 | 乾淨的規格 baseline、領域模型歸屬、feature-by-feature SDD 實作 |
 | **Brownfield** | 在既有 codebase 增加或修改行為，業務規則可能已散落各處 | 漸進的領域抽出、更安全的變更規劃、可遷移的領域知識 |
 
-兩條 track 描述的是採用風格，不是 framework 品牌。Dflow 本質是給「希望 AI 協助、又不願放棄領域清晰度」的軟體團隊使用的 workflow 系統。
+兩種模式區分的是專案起始狀態（新建 vs 既有 codebase），不是 framework 品牌；Dflow 對語言與 stack 不做假設，workflow、tier 制與文件模型可套用任何技術組合。本質是給「希望 AI 協助、又不願放棄領域清晰度」的軟體團隊使用的 workflow 系統。
 
-### Track 選擇與遷移
+各 stack（.NET / Java-Spring / Node-TS / Python / Go / PHP-Laravel）的填好範例見 [`docs/examples-by-stack.md`](./docs/examples-by-stack.md)。
 
-> 以下「rewrite 到 ASP.NET Core」是目前 Dflow 模板的預設遷移路徑（出於主要使用者背景），但設計本身與語言 / framework 無關 — workflow、ceremony tier、文件模型都可套用其他 stack。
+### 模式選擇與遷移
 
-Track 在 `dflow init` 時選定、之後**不能 in-place 切換**（沒有 `/dflow:switch-to-greenfield` 之類的指令）。Brownfield 設計上是 Greenfield 的前置準備：抽出到 `src/Domain/` 的純 C# 程式碼與 `dflow/specs/domain/` 內的領域文件（術語、規則、模型、事件）都是 migration-ready 資產，未來 rewrite 時（建新 ASP.NET Core 專案 + 新 `dflow init` 選 Greenfield）可以直接搬過去。`dflow/specs/migration/tech-debt.md` 是 brownfield 專用的遷移債紀錄。
+模式在 `dflow init` 時選定、之後**不能 in-place 切換**（沒有 `/dflow:switch-to-greenfield` 之類的指令）。Brownfield 設計上是 Greenfield 的前置準備：抽出到專案 domain 層（例如 `src/Domain/`）的領域程式碼，與 `dflow/specs/domain/` 內的領域文件（術語、規則、模型、事件），都是 migration-ready 資產 — 未來要 rewrite 時（建新專案 + 新 `dflow init` 選 Greenfield），可以直接搬過去。`dflow/specs/migration/tech-debt.md` 是 brownfield 專用的遷移債紀錄。
 
-也支援「逐 BC（Bounded Context）遷移」— 某個 BC 已純化到 `src/Domain/`、Code-Behind 已純為 UI 綁定後，這個 BC 就已是 Clean Architecture 狀態，不必整個 system 一次性切。brownfield 的 `/dflow:modify-existing` 內「assess Code-Behind」步驟對該 BC 自然會變 no-op。
+也支援「逐 BC（Bounded Context）遷移」— 某個 BC 的業務邏輯已純化到 domain 層、表現層只剩 UI 綁定後，這個 BC 就已是 Clean Architecture 狀態，不必整個 system 一次性切。Brownfield 的 `/dflow:modify-existing` 內「評估表現層業務邏輯」步驟對該 BC 自然會變 no-op。
 
 ## Workflow 模型
 

package/docs/examples-by-stack.md

@@ -0,0 +1,516 @@
+# Examples by Stack
+
+> A per-stack appendix to Dflow templates. Dflow itself is language- and
+> framework-agnostic; this document shows what canonical placeholders
+> (`{Language}` / `{Framework}` / `{Framework version}` / `{ORM / persistence}`
+> / `{ORM version}` / `{Mediator}` / `{Test framework}`) and stack-neutral
+> prose look like once filled in for common stacks.
+>
+> **How to use this**: after running `dflow init`, open
+> `dflow/specs/shared/_overview.md` and your root `CLAUDE.md`. Replace
+> placeholder rows / directory trees / dependency lists with the snippets
+> from your stack's section below. Adapt as needed — these are starting
+> points, not prescriptions.
+
+## Index
+
+- [.NET / ASP.NET Core (Greenfield)](#net--aspnet-core-greenfield)
+- [.NET / ASP.NET WebForms (Brownfield)](#net--aspnet-webforms-brownfield)
+- [Java / Spring Boot (Greenfield)](#java--spring-boot-greenfield) — Kotlin/Spring same pattern
+- [Node.js / TypeScript / NestJS (Greenfield)](#nodejs--typescript--nestjs-greenfield)
+- [Python / FastAPI (Greenfield)](#python--fastapi-greenfield) — Django/Flask similar
+- [Go / Gin (Greenfield)](#go--gin-greenfield)
+- [PHP / Laravel (Brownfield migration)](#php--laravel-brownfield-migration)
+
+Each section provides:
+
+1. **`_overview.md` stack table** — substituted canonical placeholders
+2. **Project layout** — idiomatic directory / package convention
+3. **Domain purity check** — the stack's equivalent of "no delivery-framework references" (used in Git-principles checklist)
+4. **Test framework** — what `{Test framework}` resolves to
+
+---
+
+## .NET / ASP.NET Core (Greenfield)
+
+### `_overview.md` stack table
+
+```markdown
+| Item | Choice |
+|------|--------|
+| Language | C# 12 |
+| Framework | ASP.NET Core 9 |
+| ORM / persistence | Entity Framework Core 9 |
+| Mediator | MediatR 12 |
+| Test framework | xUnit |
+| Database | PostgreSQL 16 |
+| Auth | JWT bearer / OIDC via Azure AD |
+| Hosting | Azure App Service |
+```
+
+### Project layout
+
+```
+src/
+├── {Project}.Domain/                   # Aggregates, Value Objects, Domain Events
+│   ├── Common/                         # Entity, AggregateRoot, ValueObject base classes
+│   ├── {BoundedContext}/
+│   │   ├── Entities/
+│   │   ├── ValueObjects/
+│   │   ├── Events/
+│   │   ├── Services/
+│   │   └── Interfaces/                 # Repository / external service interfaces
+│   └── SharedKernel/
+├── {Project}.Application/              # CQRS handlers, validators, DTOs
+│   ├── Common/
+│   └── {BoundedContext}/
+│       ├── Commands/
+│       ├── Queries/
+│       ├── DTOs/
+│       └── EventHandlers/
+├── {Project}.Infrastructure/           # EF Core DbContext, repository impls
+│   ├── Persistence/
+│   ├── Repositories/
+│   └── ExternalServices/
+└── {Project}.WebAPI/                   # Presentation: HTTP endpoints
+
+tests/
+├── {Project}.Domain.UnitTests/
+├── {Project}.Application.UnitTests/
+└── {Project}.Integration.Tests/
+```
+
+### Domain purity check
+
+The Domain project's `.csproj` should have **zero** package references
+outside the allow-list (typically just the `SharedKernel`). Specifically
+forbid:
+
+- `Microsoft.AspNetCore.*`, `System.Web`
+- `Microsoft.EntityFrameworkCore.*` (Domain declares interfaces; Infrastructure references EF Core)
+- `HttpContext`, `HttpRequest`, `ISession`
+- `Newtonsoft.Json` / `System.Text.Json` attributes on Domain entities
+
+CI check example: `dotnet list package` on Domain.csproj — fail if any
+disallowed dependency appears.
+
+### Test framework
+
+`xUnit` + `FluentAssertions` + `NSubstitute`. Run with `dotnet test`.
+
+---
+
+## .NET / ASP.NET WebForms (Brownfield)
+
+### `_overview.md` stack table
+
+```markdown
+| Item | Current |
+|------|---------|
+| Language | C# 7 (.NET Framework 4.8) |
+| Framework | ASP.NET WebForms 4.8 |
+| ORM / persistence | Entity Framework 6 (or ADO.NET / Dapper) |
+| Test framework | xUnit / NUnit |
+| Database | SQL Server 2019 |
+| UI | WebForms .aspx + Code-Behind + Bootstrap |
+| Auth | Forms authentication / Windows auth |
+| Hosting | IIS on-prem |
+| Target architecture | ASP.NET Core 8 + Clean Architecture |
+```
+
+### Project layout
+
+```
+src/
+├── Domain/                             # Extracted domain logic (framework-pure)
+│   ├── {BoundedContext}/
+│   │   ├── Entities/
+│   │   ├── ValueObjects/
+│   │   └── Services/
+│   └── SharedKernel/
+└── WebForms/                           # Existing .aspx + .aspx.cs (Code-Behind)
+    └── Pages/
+```
+
+### Domain purity check
+
+The Domain assembly must not reference:
+
+- `System.Web.*`, `System.Web.UI.*`
+- `HttpContext.Current`, `Session[…]`, `ViewState[…]`
+- Page lifecycle types (`Page`, `Control`)
+- EF6 attributes on Domain entities (use Fluent API in a separate
+  configuration class outside Domain)
+
+CI check: project reference analyzer on `src/Domain/Domain.csproj`.
+
+### Test framework
+
+`xUnit` or `NUnit`. Run with `dotnet test` or `nunit3-console`.
+
+---
+
+## Java / Spring Boot (Greenfield)
+
+> Same pattern applies to Kotlin/Spring with minor syntax differences.
+
+### `_overview.md` stack table
+
+```markdown
+| Item | Choice |
+|------|--------|
+| Language | Java 21 |
+| Framework | Spring Boot 3.3 |
+| ORM / persistence | Spring Data JPA / Hibernate 6.5 |
+| Mediator | (none — direct service injection; optional: Spring Modulith) |
+| Test framework | JUnit 5 + AssertJ + Mockito |
+| Database | PostgreSQL 16 |
+| Auth | Spring Security + OAuth2 / OIDC |
+| Hosting | Kubernetes / managed app platform |
+```
+
+### Project layout
+
+```
+src/
+├── main/
+│   └── java/com/example/{system}/
+│       ├── domain/                     # Aggregates, Value Objects, Domain Events
+│       │   ├── common/                 # Base classes (Entity, AggregateRoot, ValueObject)
+│       │   ├── {boundedcontext}/
+│       │   │   ├── entity/
+│       │   │   ├── valueobject/
+│       │   │   ├── event/
+│       │   │   ├── service/
+│       │   │   └── repository/         # Repository interfaces (NOT implementations)
+│       │   └── sharedkernel/
+│       ├── application/                # Command/Query handlers, DTOs
+│       │   ├── command/
+│       │   ├── query/
+│       │   └── dto/
+│       ├── infrastructure/             # JPA repositories, external clients
+│       │   ├── persistence/
+│       │   └── client/
+│       └── web/                        # Controllers, REST endpoints
+└── test/
+    └── java/com/example/{system}/
+        ├── domain/                     # Unit tests
+        ├── application/
+        └── web/                        # @SpringBootTest integration
+```
+
+Multi-module Maven/Gradle layouts (one module per layer) are also common
+and recommended for stricter dependency enforcement.
+
+### Domain purity check
+
+The Domain package must not import:
+
+- `org.springframework.*` (no Spring annotations on Domain entities)
+- `jakarta.persistence.*` / `javax.persistence.*` (no JPA annotations on
+  Domain entities; use a separate JPA mapping class in Infrastructure)
+- `jakarta.servlet.*` (no HTTP types)
+- `com.fasterxml.jackson.*` (no serialization annotations on Domain)
+
+CI check: ArchUnit rule `noClasses().that().resideInAPackage("..domain..")
+.should().dependOnClassesThat().resideInAnyPackage("org.springframework..", "jakarta.persistence..")`.
+
+### Test framework
+
+`JUnit 5` (`org.junit.jupiter`). Run with `./mvnw test` or `./gradlew test`.
+
+---
+
+## Node.js / TypeScript / NestJS (Greenfield)
+
+### `_overview.md` stack table
+
+```markdown
+| Item | Choice |
+|------|--------|
+| Language | TypeScript 5.4 |
+| Framework | NestJS 10 |
+| ORM / persistence | Prisma 5 (or TypeORM / MikroORM) |
+| Mediator | (none — NestJS providers; optional: nestjs-cqrs module) |
+| Test framework | Vitest (or Jest) + supertest |
+| Database | PostgreSQL 16 |
+| Auth | Passport (JWT, OAuth2) |
+| Hosting | Containerized (Docker / Kubernetes / Fly.io) |
+```
+
+### Project layout
+
+```
+src/
+├── domain/                             # Aggregates, Value Objects, Domain Events
+│   ├── common/                         # Base classes
+│   ├── {bounded-context}/
+│   │   ├── entities/
+│   │   ├── value-objects/
+│   │   ├── events/
+│   │   ├── services/
+│   │   └── repositories/               # Interfaces only
+│   └── shared-kernel/
+├── application/                        # Use cases, command/query handlers
+│   ├── commands/
+│   ├── queries/
+│   └── dtos/
+├── infrastructure/                     # Prisma client, external API clients
+│   ├── persistence/
+│   └── external/
+└── presentation/                       # NestJS controllers, modules
+    └── http/
+
+test/
+├── domain/
+├── application/
+└── e2e/
+```
+
+### Domain purity check
+
+`src/domain/` files must not import:
+
+- `@nestjs/*` (no `@Injectable`, `@Module`, decorators on Domain)
+- `@prisma/client` (Prisma generated client lives in Infrastructure only)
+- `express` / `fastify` types
+- `class-transformer` / `class-validator` (use plain TS types; validation
+  in Application layer)
+
+CI check: ESLint rule `no-restricted-imports` scoped to `src/domain/**` or
+`dependency-cruiser` rule forbidding cross-layer imports.
+
+### Test framework
+
+`Vitest` (or `Jest`). Run with `npm test` or `pnpm test`.
+
+---
+
+## Python / FastAPI (Greenfield)
+
+> Django and Flask follow the same layered pattern with framework-specific
+> presentation conventions. Django: views/templates as presentation;
+> Flask: blueprints; FastAPI: routers.
+
+### `_overview.md` stack table
+
+```markdown
+| Item | Choice |
+|------|--------|
+| Language | Python 3.12 |
+| Framework | FastAPI 0.115 |
+| ORM / persistence | SQLAlchemy 2.0 + Alembic (or SQLModel) |
+| Mediator | (none — typed dependency injection via FastAPI Depends) |
+| Test framework | pytest + pytest-asyncio |
+| Database | PostgreSQL 16 |
+| Auth | OAuth2 via fastapi.security (PasswordBearer / JWT) |
+| Hosting | Containerized (Docker / Kubernetes / Fly.io) |
+```
+
+### Project layout
+
+```
+src/
+├── domain/                             # Aggregates, Value Objects, Domain Events
+│   ├── common/
+│   ├── {bounded_context}/
+│   │   ├── entities.py
+│   │   ├── value_objects.py
+│   │   ├── events.py
+│   │   ├── services.py
+│   │   └── repositories.py             # Protocol / abstract base classes
+│   └── shared_kernel/
+├── application/                        # Use cases, DTOs
+│   ├── commands/
+│   ├── queries/
+│   └── dtos/
+├── infrastructure/                     # SQLAlchemy models, external clients
+│   ├── persistence/
+│   └── external/
+└── presentation/                       # FastAPI routers
+    └── api/
+
+tests/
+├── domain/
+├── application/
+└── integration/
+```
+
+### Domain purity check
+
+`src/domain/` modules must not import:
+
+- `fastapi` / `starlette`
+- `sqlalchemy.*` (use Protocols / dataclasses in Domain; SQLAlchemy models
+  live in Infrastructure as separate mapping classes)
+- `pydantic.BaseModel` for Domain entities (use `dataclass` or plain
+  classes; Pydantic models belong in DTO / API layer)
+
+CI check: `import-linter` (`importlinter.org`) contract forbidding Domain
+imports of presentation/infrastructure packages.
+
+### Test framework
+
+`pytest`. Run with `pytest` or `python -m pytest`.
+
+---
+
+## Go / Gin (Greenfield)
+
+### `_overview.md` stack table
+
+```markdown
+| Item | Choice |
+|------|--------|
+| Language | Go 1.22 |
+| Framework | Gin 1.10 (or Echo / Chi) |
+| ORM / persistence | GORM v2 (or sqlx / pgx) |
+| Mediator | (none — interface-based dispatch) |
+| Test framework | go test + testify |
+| Database | PostgreSQL 16 |
+| Auth | JWT middleware / OAuth2 |
+| Hosting | Containerized (Docker / Kubernetes / Fly.io) |
+```
+
+### Project layout
+
+```
+{module-root}/
+├── cmd/
+│   └── api/main.go                     # Application entrypoint
+├── internal/
+│   ├── domain/                         # Aggregates, Value Objects, Domain Events
+│   │   ├── common/
+│   │   ├── {boundedcontext}/
+│   │   │   ├── entity.go
+│   │   │   ├── valueobject.go
+│   │   │   ├── event.go
+│   │   │   ├── service.go
+│   │   │   └── repository.go           # Interface only
+│   │   └── sharedkernel/
+│   ├── application/                    # Use cases
+│   │   ├── command/
+│   │   └── query/
+│   ├── infrastructure/                 # GORM repo impls, external clients
+│   │   ├── persistence/
+│   │   └── external/
+│   └── handler/                        # HTTP handlers (Gin routes)
+└── go.mod
+```
+
+`internal/` enforces Go's import boundary — packages outside the module
+cannot import from `internal/...`.
+
+### Domain purity check
+
+`internal/domain/` packages must not import:
+
+- `github.com/gin-gonic/gin` or any HTTP router package
+- `gorm.io/gorm` (Domain declares repository interfaces; GORM lives in
+  Infrastructure)
+- `net/http` types (`http.Request`, `http.ResponseWriter`)
+- Encoding tags (e.g. `gorm:"primaryKey"`, `json:"..."`) on Domain
+  entities — keep tag-free, do encoding via separate Infrastructure
+  models
+
+CI check: `go vet` plus a custom `go-arch-lint` or `golangci-lint` rule
+forbidding `internal/domain` from importing the above.
+
+### Test framework
+
+`go test` (standard library) + `stretchr/testify` for assertions.
+Run with `go test ./...`.
+
+---
+
+## PHP / Laravel (Brownfield migration)
+
+> Older PHP monoliths (Symfony 2/3, CodeIgniter, custom) follow similar
+> extraction patterns; the snippets below are for a modern Laravel app
+> already on Laravel 10+ that wants to introduce a Domain layer.
+
+### `_overview.md` stack table
+
+```markdown
+| Item | Current |
+|------|---------|
+| Language | PHP 8.3 |
+| Framework | Laravel 11 |
+| ORM / persistence | Eloquent ORM (Active Record pattern — see Domain note) |
+| Test framework | PHPUnit 11 (or Pest 2) |
+| Database | MySQL 8 / MariaDB 10 |
+| UI | Blade templates / Inertia + Vue / API-only |
+| Auth | Laravel Breeze / Sanctum / Passport |
+| Hosting | Laravel Forge / shared hosting / containerized |
+| Target architecture | Same Laravel + extracted Domain layer + repository abstractions |
+```
+
+### Project layout
+
+```
+app/
+├── Domain/                             # Extracted domain logic (framework-pure)
+│   ├── Common/
+│   ├── {BoundedContext}/
+│   │   ├── Entities/                   # Plain PHP classes (NOT Eloquent models)
+│   │   ├── ValueObjects/
+│   │   ├── Events/
+│   │   ├── Services/
+│   │   └── Repositories/               # Interfaces only
+│   └── SharedKernel/
+├── Application/                        # Use cases, command/query handlers
+│   ├── Commands/
+│   └── Queries/
+├── Infrastructure/                     # Eloquent repository implementations
+│   ├── Persistence/
+│   │   ├── Eloquent/                   # Eloquent models live HERE, not in Domain
+│   │   └── Repositories/
+│   └── External/
+├── Http/                               # Controllers, middleware (Laravel-managed)
+│   ├── Controllers/
+│   └── Middleware/
+└── Providers/
+
+tests/
+├── Unit/Domain/
+├── Feature/Application/
+└── Feature/Http/
+```
+
+### Domain purity check
+
+`app/Domain/` classes must not extend / use:
+
+- `Illuminate\Database\Eloquent\Model` (Eloquent models are Infrastructure)
+- `Illuminate\Http\Request` / `Response`
+- `Illuminate\Support\Facades\*` (DB, Auth, Cache, etc.)
+- Laravel attribute / trait magic on Domain entities
+
+CI check: a Laravel-aware static analysis rule (Larastan / PHPStan with a
+custom architecture rule) forbidding `app/Domain/` from referencing the
+above.
+
+### Test framework
+
+`PHPUnit` (`phpunit/phpunit`) or `Pest` (`pestphp/pest`). Run with
+`./vendor/bin/phpunit` or `./vendor/bin/pest`.
+
+---
+
+## Adding your stack
+
+If your stack isn't listed (Rust, Ruby/Rails, Kotlin native, Elixir, etc.),
+the pattern is always the same:
+
+1. Identify your stack's **domain layer convention** (folder / package /
+   namespace where pure business code lives)
+2. Identify the **delivery / entrypoint layer** (controllers, handlers,
+   routes, CLI commands, message consumers, job runners)
+3. Identify the **persistence layer** (ORM, query builder, raw driver)
+4. Domain purity check = "no imports / usings / extends from delivery,
+   persistence, or framework runtime packages"
+5. Express the layer separation in a CI-enforceable rule appropriate to
+   the stack (ArchUnit, ESLint, import-linter, go-arch-lint, Larastan,
+   etc.)
+
+Contributions of additional stacks via PR are welcome.