dflow-sdd-ddd 0.7.0 → 0.9.0

package/templates/brownfield/references/pr-review-checklist.md

@@ -0,0 +1,179 @@
+# PR Review Checklist
+
+When reviewing code changes or discussing PRs, use this checklist to ensure
+the SDD/DDD workflow was followed.
+
+`/dflow:pr-review` enters this checklist starting from **Step 0**. Do not skip Step 0 — reviewing code without first understanding spec intent breaks the SDD feedback loop (all the upstream spec work loses its verification mechanism).
+
+## Step 0: Understand the Change Intent (before code review)
+
+Ground yourself in the spec *before* looking at the diff. A feature
+directory may contain multiple spec files; identify which ones this PR
+touches and read them all.
+
+- [ ] Locate the feature directory at
+      `dflow/specs/features/active/{SPEC-ID}-{slug}/` (or
+      `dflow/specs/features/completed/{SPEC-ID}-{slug}/` if the PR is the
+      closeout commit and the dir was already `git mv`d)
+- [ ] Read `_index.md` first — it gives you the feature-level overview,
+      Current BR Snapshot, list of phase-specs, and Resume Pointer (where the
+      author left off)
+- [ ] Identify which **phase-spec(s)** and / or **lightweight-spec(s)**
+      this PR diff touches. There may be:
+      - A new phase-spec being introduced (T1) — read in full
+      - An existing phase-spec being marked `completed` — verify its
+        Delta-from-prior-phases section reads correctly relative to the
+        prior phase
+      - A new lightweight-spec (T2) — read in full
+      - Just T3 inline rows added to `_index.md` Lightweight Changes (no
+        spec file changed) — confirm the row description is precise
+- [ ] If a `Behavior Delta` / Delta-from-prior-phases section exists,
+      read **ADDED / MODIFIED / REMOVED / RENAMED**; note any
+      **UNCHANGED** scope declaration
+- [ ] State in one sentence: "This PR intends to {change} because
+      {reason}." (If you can't, pause and ask the author.)
+- [ ] Only then proceed to the code-review sections below
+
+If the PR has no spec or no `_index.md`:
+```
+"I don't see a feature directory or _index.md for this PR. Before I
+review the code, can you point me to it, or run /dflow:new-feature
+(or /dflow:bug-fix for a small fix) to create the feature directory
+and at least a lightweight spec? SDD relies on the spec being the
+review anchor."
+```
+
+## Spec Compliance
+
+Per-feature checks:
+- [ ] **Feature directory exists** with `_index.md` + at least one
+      phase-spec (or one lightweight-spec for a T2-only feature)
+- [ ] **`_index.md` Current BR Snapshot is up to date** — reflects
+      the cumulative effect of all phase-specs / lightweight-specs in
+      the directory
+- [ ] **`_index.md` Phase Specs table** — every row's referenced
+      phase-spec file exists and its `status` matches the row's claim
+- [ ] **For follow-up features**: `_index.md` Metadata has `follow-up-of:
+      {原 SPEC-ID}` AND the original feature's `_index.md`
+      Follow-up Tracking row references this feature
+
+Per-phase-spec / lightweight-spec checks (run for **each** spec file the
+PR touches, not just one):
+- [ ] **Spec matches code** — implementation matches Given/When/Then
+- [ ] **Business rules covered** — all BR-* rules in this spec
+      implemented
+- [ ] **Edge cases handled** — EC-* in this spec addressed
+- [ ] **Delta integrity** (phase 2+ only) — the Delta-from-prior-phases
+      section's ADDED / MODIFIED / REMOVED / RENAMED entries actually
+      match the diff against the prior phase-spec's BR set
+
+If the closeout commit is in this PR (`/dflow:finish-feature` was run):
+- [ ] **BC layer sync landed** — `dflow/specs/domain/{context}/rules.md` and
+      `behavior.md` reflect the feature's net effect (compare against
+      `_index.md` Current BR Snapshot)
+- [ ] **Whole feature directory `git mv`'d** to `completed/` — git
+      shows `renamed:` (not `deleted:` + `new file:`)
+- [ ] **Integration Summary** was emitted to the conversation (not
+      written to a file — it's ephemeral)
+
+If the spec is missing or incomplete:
+```
+"I notice this PR doesn't have a matching feature directory / _index.md.
+Let's create one retroactively — it'll help with documentation and
+the target architecture. Can you describe what this change does?"
+```
+
+## Domain Layer Quality
+
+- [ ] **No delivery-framework references in Domain** — `src/Domain/` must have zero dependencies on HTTP request/response objects, session/cookie context, job-runner context, CLI flag parsers, or ViewState equivalents
+- [ ] **No direct DB access in Domain** — All data access through interfaces
+- [ ] **No delivery-framework runtime context in Domain** — Pure business logic only
+- [ ] **Testable without delivery infrastructure** — Could you unit test this without the web server, job runner, message broker, or CLI runtime?
+
+Common violations to flag:
+```text
+// BAD: Domain code depending on delivery framework runtime
+deliveryFramework.request.currentUser
+deliveryFramework.session["key"]
+jobRunnerContext.retryState
+cliFlags["mode"]
+
+// BAD: Direct DB in Domain
+databaseClient.openConnection(connectionString)
+
+// GOOD: Interface-based
+public class ExpenseService
+{
+    private readonly IExpenseRepository _repo;
+    public ExpenseService(IExpenseRepository repo) => _repo = repo;
+}
+```
+
+## Delivery/Entrypoint Thickness
+
+Evaluate whether business logic embedded in delivery/entrypoint code
+(presentation/UI layer, controllers, handlers, jobs, message consumers, data
+pipelines, or stored procedures) has been kept appropriately thin:
+
+**Acceptable delivery/entrypoint responsibilities:**
+- Parse inputs (UI controls, HTTP payloads, message payloads, job parameters, CLI args)
+- Call Domain layer services
+- Bind or return results
+- Handle delivery-specific events (page load, route handler, message received, job started)
+- Delivery-level validation (required fields, request shape, command syntax)
+
+**Should be in Domain layer instead:**
+- Calculations (math, conversions, aggregations)
+- Business validation (rules, constraints, limits)
+- State transitions (status changes, workflow steps)
+- Data transformations (business meaning, not UI formatting)
+
+If delivery/entrypoint code is too thick:
+```
+"This delivery/entrypoint code has [calculation/validation/transformation] logic
+that could be extracted to src/Domain/{Context}/. Since we're already
+reviewing this, should we extract it now or record it in tech-debt.md
+for later?"
+```
+
+## Glossary Consistency
+
+- [ ] **New terms documented** — Any new business concept added to glossary.md?
+- [ ] **Consistent naming** — Do class/method/variable names match glossary terms?
+- [ ] **No ambiguous terms** — Are domain-specific terms used precisely?
+
+Example check:
+```
+"I see you're using 'reimbursement' in the code but the glossary
+uses '報銷 (Expense Claim)'. Should we align the naming?"
+```
+
+## Domain Documentation Updates
+
+- [ ] **models.md updated** — New entities/VOs/services documented?
+- [ ] **rules.md updated** — New or changed business rules recorded?
+- [ ] **context.md boundaries respected** — Does this change stay within its context?
+
+## Tech Debt Awareness
+
+- [ ] **New debt recorded** — Any shortcuts or compromises documented in tech-debt.md?
+- [ ] **Existing debt not worsened** — Did this change make existing tech debt worse?
+- [ ] **Debt reduced** — Did this change fix any existing tech-debt.md items? If so, check them off.
+
+## Migration Readiness Score
+
+Rate the PR on a quick migration readiness scale:
+
+- **A**: New business logic entirely in Domain layer, fully testable, spec complete
+- **B**: Mostly in Domain layer, some minor coupling, spec exists
+- **C**: Mixed — some extraction done, some logic still in delivery/entrypoint code
+- **D**: All logic in delivery/entrypoint code, but at least documented in spec/tech-debt
+- **F**: No spec, no extraction, no documentation — push back
+
+Share the score with the developer constructively:
+```
+"This PR is a solid B — the exchange rate logic is cleanly extracted
+to Domain, and the spec covers the key scenarios. One thing that would
+make it an A: the date parsing logic in the delivery/entrypoint layer could
+move to a DateRange value object. Want to do that now or add it to tech-debt?"
+```

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

@@ -121,12 +121,39 @@ Recommend `docs/migrating-to-dflow-v1.md` for the manual migration
 checklist. Migration affects every spec the team has written; manual
 review is required.
 
+## Workflow Steps
+
+This guide is the **command registry, routing rules, and project context**.
+Executable workflow steps (Step 1→N, step gates, completion checklists) are
+**not** defined here. They live in the vendored workflow bundle projected into
+this project at:
+
+- `dflow/specs/shared/dflow-workflows/`
+
+When executing a `/dflow:*` command, read the matching flow file from that
+directory first. For example:
+
+| Command | Flow file |
+|---|---|
+| `/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: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` |
+| `/dflow:pr-review` | `dflow/specs/shared/dflow-workflows/references/pr-review-checklist.md` |
+| `/dflow:report-dflow-feedback` | `dflow/specs/shared/dflow-workflows/references/dflow-feedback-flow.md` |
+
+Supporting files (templates, drift checklist) are also in
+`dflow/specs/shared/dflow-workflows/` under the same relative paths used
+by the flow files.
+
 ## Tool-Specific Notes
 
-This file is the canonical Dflow guide. Root-level files such as
-`AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`
+This file is the canonical Dflow guide (registry + rules + router). Root-level
+files such as `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`
 should stay thin and point back here.
 
 If a tool does not support Dflow slash commands, treat the command names as
-plain workflow names. This guide contains the installed runtime behavior
-contract; execute the workflow semantics defined here directly.
+plain workflow names and follow the matching flow file from the workflow bundle
+at `dflow/specs/shared/dflow-workflows/`.

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

@@ -1,4 +1,4 @@
-<!-- Scaffolding template maintained alongside Dflow skill. See archive/proposals/PROPOSAL-010 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # CLAUDE.md Snippet — Dflow Adoption
 
@@ -11,10 +11,10 @@
 > - Use this legacy snippet only if you intentionally want the older
 >   Claude-specific two-H2 layout in your project's root `CLAUDE.md`.
 
-The snippet follows the Dflow `templates/CLAUDE.md` H2 segmentation
-(established in PROPOSAL-007c): **System Context** (what the system is)
-and **Development Workflow** (how we work). Keep those two H2 sections as the backbone
-when merging into an existing `CLAUDE.md`.
+The snippet follows the Dflow `templates/CLAUDE.md` H2 segmentation:
+**System Context** (what the system is) and **Development Workflow**
+(how we work). Keep those two H2 sections as the backbone when merging
+into an existing `CLAUDE.md`.
 
 ---
 
@@ -97,11 +97,15 @@ src/
 3. **Ubiquitous Language** — 使用 `dflow/specs/domain/glossary.md` 中定義的術語
 4. **Migration Awareness** — 每個決策都要考慮 target architecture
 
-### Dflow Skill — Canonical Decision Logic Lives in the Skill
+### Dflow Skill — Canonical Decision Logic Lives in the Project
 
 AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
-（T1/T2/T3）、各 `/dflow:` 命令的具體流程，**全部定義於 Dflow skill
-本體**（`sdd-ddd-brownfield-skill/SKILL.md` 與 `references/*.md`）。
+（T1/T2/T3）、各 `/dflow:` 命令的具體流程，**全部定義於本專案內
+的 Dflow 工件**（init 時投影）：
+
+- `dflow/specs/shared/AI-AGENT-GUIDE.md` — 決策樹 + Slash Commands 總表 + 路由規則
+- `dflow/specs/shared/dflow-workflows/references/*.md` — 各 flow 執行步驟定義
+
 本 `CLAUDE.md` 不重述這些內容，避免雙份維護。
 
 當你作為 AI assistant 被呼叫時，若偵測到使用者需要 SDD/DDD 工作流

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

@@ -1,4 +1,4 @@
-<!-- Scaffolding template maintained alongside Dflow skill. See archive/proposals/PROPOSAL-010 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # Git Principles — Git Flow edition
 
@@ -124,8 +124,6 @@ Commits must tie back to a SPEC-ID:
 [{SPEC-ID}] {short description}
 
 {optional detailed body}
-
-Co-Authored-By: Claude <noreply@anthropic.com>   ← suggested, not mandatory
 ```
 
 ### Type prefix (recommended)
@@ -299,19 +297,22 @@ Three categories:
 | `git stash` (local-only) |
 | `git branch` (listing only) |
 
-### AI commit authorship (suggested, not enforced)
+### AI commit authorship
 
-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:
+How AI-made commits are marked is chosen once at `dflow init` and recorded in
+`dflow/specs/shared/_conventions.md` § AI Commit Policy:
 
-```
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
+- `none` — AI commits carry no extra marker.
+- `co-authored-by` — a `Co-Authored-By: dflow-ai <noreply@dflow.local>` trailer
+  (teams may customize the name / email).
+- `prefix` — an `[ai-assisted]` commit-subject prefix.
 
-For other AI assistants, use the vendor-documented author line (or omit
-it). This is a project-level transparency convention, not a Dflow
-requirement.
+This recorded setting is authoritative and the runtime does not re-ask. The AI
+offers commits at lifecycle checkpoints (see `references/git-integration.md`
+§ Commit Checkpoints, Branch Gate & AI Commits) using your Git identity, and you
+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.
 
 ---
 

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

@@ -1,4 +1,4 @@
-<!-- Scaffolding template maintained alongside Dflow skill. See archive/proposals/PROPOSAL-010 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # Git Principles — Trunk-based / GitHub Flow edition
 
@@ -72,8 +72,6 @@ Commits must tie back to a SPEC-ID:
 [{SPEC-ID}] {short description}
 
 {optional detailed body}
-
-Co-Authored-By: Claude <noreply@anthropic.com>   ← suggested, not mandatory
 ```
 
 ### Conventional Commits style (recommended, optional)
@@ -170,8 +168,6 @@ Related BR-IDs:
 - REMOVED: (none)
 
 Related SPEC-IDs: {SPEC-ID}{, follow-up SPEC-IDs if any}
-
-Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
 Example:
@@ -191,8 +187,6 @@ Related BR-IDs:
 - MODIFIED: BR-03
 
 Related SPEC-IDs: SPEC-20260421-001
-
-Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
 ### 4.2 Rebase + merge (preserve feature commits on `main`)
@@ -281,19 +275,22 @@ Three categories:
 | `git branch` (listing only) |
 | `git rebase` on a private (not-yet-pushed) branch |
 
-### AI commit authorship (suggested, not enforced)
+### AI commit authorship
 
-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:
+How AI-made commits are marked is chosen once at `dflow init` and recorded in
+`dflow/specs/shared/_conventions.md` § AI Commit Policy:
 
-```
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
+- `none` — AI commits carry no extra marker.
+- `co-authored-by` — a `Co-Authored-By: dflow-ai <noreply@dflow.local>` trailer
+  (teams may customize the name / email).
+- `prefix` — an `[ai-assisted]` commit-subject prefix.
 
-For other AI assistants, use the vendor-documented author line (or omit
-it). This is a project-level transparency convention, not a Dflow
-requirement.
+This recorded setting is authoritative and the runtime does not re-ask. The AI
+offers commits at lifecycle checkpoints (see `references/git-integration.md`
+§ Commit Checkpoints, Branch Gate & AI Commits) using your Git identity, and you
+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.
 
 ---
 

package/templates/brownfield/scaffolding/_conventions.md

@@ -1,4 +1,4 @@
-<!-- Scaffolding template maintained alongside Dflow skill. See archive/proposals/PROPOSAL-010 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # Spec Writing Conventions — {System Name}
 

package/templates/brownfield/scaffolding/_overview.md

@@ -1,4 +1,4 @@
-<!-- Scaffolding template maintained alongside Dflow skill. See archive/proposals/PROPOSAL-010 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # System Overview — {System Name}
 
@@ -116,5 +116,5 @@ Link to any ADR or migration plan doc if one exists.}
   branching-strategy-specific file that matches this project
 - [Glossary](../domain/glossary.md)
 - [Tech debt backlog](../migration/tech-debt.md)
-- Dflow skill: see `CLAUDE.md` and the `sdd-ddd-brownfield-skill/` bundle
-  for the full AI workflow guidance.
+- Dflow skill: see `CLAUDE.md` and the in-project bundle at
+  `dflow/specs/shared/dflow-workflows/` for the full AI workflow guidance.

package/templates/brownfield/templates/_index.md

@@ -12,13 +12,14 @@ Template note (for AI):
   This is the **feature-level dashboard** (`_index.md`) for a feature
   directory. Place at `dflow/specs/features/active/{SPEC-ID}-{slug}/_index.md`.
 
-  Six required sections (see below):
+  Seven required sections (see below):
     1. Metadata (YAML front matter above)
     2. Goals & Scope (prose)
     3. Phase Specs (T1 list)
     4. Current BR Snapshot (feature-level cumulative state)
     5. Lightweight Changes (T2 outbound link + T3 inline)
-    6. Resume Pointer
+    6. Checkpoint Log (commit / skip timeline)
+    7. Resume Pointer
 
   Optional section (append at end if applicable):
     - Follow-up Tracking (when this feature has follow-up features derived)
@@ -87,6 +88,23 @@ Template note (for AI):
 | {YYYY-MM-DD} | T2 | bug fix XYZ — 見 [`lightweight-{date}-{slug}.md`](./lightweight-{date}-{slug}.md) | {hash} |
 | {YYYY-MM-DD} | T3 | 按鈕顏色從藍改綠 `[cosmetic]` | {hash} |
 
+<!-- dflow:section checkpoint-log -->
+## Checkpoint Log
+
+> 生命週期 checkpoint 的 commit / skip 時間線（讓三週後回溯不必手動重建）。
+> 每個 checkpoint 無論 commit 或 skip 都記一列。Tier 決定 checkpoint 數：
+> T1 三點（spec 完 / impl 完 / closeout）、T2 兩點（spec+impl 合併 / closeout）、
+> T3 單一 commit。
+>
+> commit hash 只在 commit 實際成功後填入；pre-commit hook reject 或 commit
+> 失敗記 `failed`、不寫假 hash。
+
+| Timestamp | Checkpoint | Result |
+|---|---|---|
+| {YYYY-MM-DD HH:MM} | spec-baseline | committed ({hash}) / skipped / failed |
+| {YYYY-MM-DD HH:MM} | implementation | committed ({hash}) / skipped / failed |
+| {YYYY-MM-DD HH:MM} | closeout | committed ({hash}) / skipped / failed |
+
 ## Resume Pointer
 
 > 一句話：目前進展到哪？下一個動作是什麼？

package/templates/brownfield/templates/context-map.md

@@ -1,4 +1,4 @@
-<!-- Template maintained by Dflow. See archive/proposals/PROPOSAL-013 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # Context Map
 

package/templates/brownfield/templates/glossary.md

@@ -1,4 +1,4 @@
-<!-- Template maintained by Dflow. See archive/proposals/PROPOSAL-013 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # Glossary
 

package/templates/brownfield/templates/models.md

@@ -1,4 +1,4 @@
-<!-- Template maintained by Dflow. See archive/proposals/PROPOSAL-013 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # Domain Models
 

package/templates/brownfield/templates/rules.md

@@ -1,4 +1,4 @@
-<!-- Template maintained by Dflow. See archive/proposals/PROPOSAL-013 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # Business Rules
 

package/templates/brownfield/templates/tech-debt.md

@@ -1,4 +1,4 @@
-<!-- Template maintained by Dflow. See archive/proposals/PROPOSAL-013 for origin. -->
+<!-- Seeded by Dflow. -->
 
 # Migration Tech Debt
 

package/templates/common/skill/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: dflow
+description: >
+  Dflow SDD/DDD workflow guardian for this project. PRIMARY: the canonical
+  /dflow:* commands (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
+  /dflow:new-phase, /dflow:finish-feature, /dflow:pr-review, /dflow:verify,
+  /dflow:report-dflow-feedback, /dflow:status, /dflow:next, /dflow:cancel).
+  SECONDARY (auto-trigger safety net) — engage ONLY for: adding or changing
+  product/domain behavior, new requirements, a feature or bug-fix workflow, or
+  spec-impacting architecture/domain-model decisions. Do NOT engage for pure
+  refactors, infrastructure chores, formatting, or general code questions.
+  When engaged by natural language, DO NOT auto-enter a workflow: judge the
+  intent, suggest the matching /dflow: command, and wait for confirmation.
+---
+
+<!-- dflow-generated: skill-adapter -->
+
+# Dflow SDD/DDD Workflow Guardian
+
+This project uses Dflow for spec-first AI-assisted development.
+
+When this skill engages:
+
+1. Read `dflow/specs/shared/AI-AGENT-GUIDE.md` — command registry, routing
+   rules, and project context.
+2. Read the matching workflow flow file from the vendored bundle at
+   `dflow/specs/shared/dflow-workflows/references/<flow>.md` for the executable
+   step definitions (Step 1→N, step gates, completion checklists).
+
+Do not duplicate or invent workflow steps — the flow files are the authoritative
+source for executable steps; the guide is the registry and router.
+
+If engaged by natural language (not an explicit `/dflow:` command): identify
+which `/dflow:` command fits, suggest it, and wait for the developer to confirm
+before entering any workflow.