dflow-sdd-ddd 0.8.0 → 0.9.0

package/templates/greenfield/references/git-integration.md

@@ -7,9 +7,10 @@ project's Git *branching strategy* (Git Flow, GitHub Flow, trunk-based,
 etc.) — it only prescribes the feature-branch-per-feature convention
 that SDD traceability depends on.
 
-> If your project adopts Git Flow specifically, see the optional
-> optional `scaffolding/Git-principles-gitflow.md` template
-> for Git-Flow-specific conventions.
+> Dflow does not pick `gitflow` vs `trunk` for you, but it now requires you to
+> record one at `dflow init` so the runtime branch gate and finish-stage merge
+> guidance can adapt. The selected policy's `Git-principles-{gitflow|trunk}.md`
+> is seeded under `dflow/specs/shared/`.
 
 ## Branch-to-Workflow Mapping
 
@@ -104,6 +105,64 @@ This requirement is independent of the branching strategy — whether you
 branch off `develop`, `main`, or something else, the feature-per-branch
 convention stays.
 
+## Commit Checkpoints, Branch Gate & AI Commits
+
+Dflow actively helps keep the Git trace aligned with the workflow — the AI
+reminds, can do the work, and leaves policy to the team.
+
+### Branch gate
+
+Before implementation starts (and before the first commit), the AI checks
+whether the current branch is the feature / bugfix branch this work belongs to.
+Both Git policies (`gitflow` / `trunk`, per `dflow/specs/shared/_conventions.md`
+§ Git Policy) use a feature branch, so:
+
+- **Already on the matching `feature/{SPEC-ID}-{slug}` (or
+  `bugfix/{BUG-ID}-{slug}`) branch** — e.g. continuing an active feature with
+  `new-phase`, `modify-existing`, or `bug-fix` — the gate is satisfied; nothing
+  is created or switched.
+- **Not on this work's feature / bugfix branch** (you are on the base branch the
+  project cuts features from — `main` / `develop` / `trunk`, or whatever your
+  policy uses — or on an unrelated branch) — the AI offers to create and switch
+  to the correct branch, switch to an existing matching one, or override and
+  stay (recorded in the feature `_index.md` Checkpoint Log; three consecutive
+  overrides → the AI suggests re-running `dflow init`, never changing the
+  setting on its own).
+
+Dflow does not need to identify your base branch to evaluate the gate — it only
+checks whether you are on the right feature branch. The base branch matters only
+when a new branch is actually created, and which base to cut from is your
+project's decision (GitFlow → `develop`, Trunk / GitHub Flow → `main`).
+
+### Commit checkpoints
+
+At lifecycle milestones the AI offers a commit checkpoint, folded into the
+existing Step Gate prompt (it does not add a separate question):
+
+```
+✓ {milestone} complete
+   Commit here?
+   [Y] Yes — the AI commits with your Git identity (marker per _conventions.md § AI Commit Policy)
+   [N] No — skip this checkpoint
+```
+
+Tier sets how many checkpoints a change has: T1 three (spec / implementation /
+closeout), T2 two (spec+implementation merged / closeout), T3 a single commit.
+Whether you choose Y or N, the AI records one row in the feature `_index.md`
+Checkpoint Log. A commit hash is written only after the commit succeeds; a hook
+rejection or failed commit is recorded as `failed` (never a fake hash). After
+several consecutive skips in a project the AI mentions you can turn checkpoints
+off in config — it does not turn them off for you.
+
+### AI commits
+
+The AI may commit at these checkpoints using your Git identity; you can always
+decline. How AI commits are marked is the `## AI Commit Policy` setting in
+`_conventions.md` (`none` / `co-authored-by` / `prefix`), chosen once at init.
+This is a deliberate reversal of Dflow's earlier "the AI never commits" stance:
+the AI helps at natural break points, while merge / push / PR still follow the
+team's policy and your explicit go-ahead.
+
 ## Directory Moves Must Use `git mv`
 
 When you rename or move a directory or file that is tracked in Dflow
@@ -245,9 +304,9 @@ with the rule.
       Domain
 
 > The exact merge strategy (merge commit, squash, rebase, fast-forward)
-> is a project-level decision and sits outside Dflow's scope. See your
-> project's Git-principles document (e.g. the optional
-> Git-principles scaffolding) for integration commit conventions.
+> follows the team's selected Git policy. See the seeded
+> `Git-principles-{gitflow|trunk}.md` under `dflow/specs/shared/` for that
+> policy's integration commit conventions.
 
 ## Commit Message Convention
 

package/templates/greenfield/references/init-project-flow.md

@@ -128,25 +128,42 @@ blank input, or prose descriptions such as "Traditional Chinese". Dflow
 templates keep canonical English structural language; this setting controls
 free prose inside generated spec sections.
 
-### Q5. Optional starter files (multi-select)
+### Q5. Git policy (mandatory — pick one)
 
-> "Besides the mandatory baseline, which optional starter files do
-> you want me to seed? You can check as many as apply:
+> "Which Git policy does the team follow? This drives the runtime branch gate
+> and the finish-stage merge guidance, so it is required:
 >
->   - [ ] `dflow/specs/shared/_overview.md` — system overview template
->   - [ ] Git principles — **pick one** if your project has opinions
->         about Git conventions (decision hint: **if you're not sure,
->         pick trunk-based** — that's the default for GitHub / GitLab.
->         Pick Git Flow only if you have a formal release cycle with
->         dedicated release / hotfix branches):
->     - [ ] `dflow/specs/shared/Git-principles-gitflow.md`
->     - [ ] `dflow/specs/shared/Git-principles-trunk.md`"
+>   1. GitFlow — long-lived develop / release branches
+>   2. Trunk / GitHub Flow — short-lived feature branches (lightest; the
+>      default for most GitHub / GitLab teams)"
 
-Wait for answers. If the developer picks both Git-principles flavours,
-confirm once more that they really want both (usually a project picks
-one).
+Required — do not accept a skip. Both policies use feature branches; the choice
+only changes finish-stage merge guidance. The selected policy seeds exactly one
+`dflow/specs/shared/Git-principles-{gitflow|trunk}.md` (**mandatory, not
+optional**) and is recorded in `_conventions.md` under `## Git Policy`.
 
-### Q6. AI coding agents (multi-select)
+### Q6. AI commit marker (mandatory — default None)
+
+> "How should AI-made commits be marked? The AI offers to commit at lifecycle
+> checkpoints (you can always decline); this sets how those commits are tagged:
+>
+>   1. None (default) — AI commits look like any other commit
+>   2. Co-Authored-By trailer (`dflow-ai <noreply@dflow.local>`) — filterable
+>   3. `[ai-assisted]` commit-subject prefix — visible at a glance"
+
+Recorded in `_conventions.md` under `## AI Commit Policy`; the runtime does not
+re-ask.
+
+### Q7. Optional starter files (multi-select)
+
+> "Besides the mandatory baseline, which optional starter files do you want me
+> to seed?
+>
+>   - [ ] `dflow/specs/shared/_overview.md` — system overview template"
+
+Wait for answers.
+
+### Q8. AI coding agents (multi-select)
 
 > "Which AI coding agents should Dflow configure?
 >
@@ -215,7 +232,7 @@ Key Greenfield-track notes:
   moment the first bounded context is established. Creating empty
   `behavior.md` files here would create stale placeholders.
 
-### 3.2 Optional files (from Step 2 Q5)
+### 3.2 Optional files (from Step 2 Q7)
 
 Use the packaged scaffolding templates listed below; their project-local
 outputs are under `dflow/specs/shared/` (the scaffolding root, not the
@@ -251,7 +268,7 @@ skip, and wait for developer confirmation:
 > | `dflow/specs/architecture/tech-debt.md` | `templates/tech-debt.md` (mandatory baseline) |
 > | `dflow/specs/architecture/decisions/README.md` | `scaffolding/architecture-decisions-README.md` (mandatory baseline) |
 > | `dflow/specs/shared/_overview.md` | optional (you picked it) |
-> | `dflow/specs/shared/Git-principles-trunk.md` | optional (you picked it) |
+> | `dflow/specs/shared/Git-principles-trunk.md` | mandatory (selected Git policy) |
 > | `dflow/specs/shared/AI-AGENT-GUIDE.md` | selected AI agent guide |
 > | `CLAUDE.md` | selected tool shim because repo has no CLAUDE.md |
 >
@@ -274,7 +291,7 @@ skip, and wait for developer confirmation:
 **→ Step Gate: Step 3 → Step 4**
 
 Wait for explicit confirmation. If the developer asks to change the
-selection, go back to Step 2 Q5 or Q6 and re-run Step 3.
+selection, go back to the relevant Step 2 question (Q5–Q8) and re-run Step 3.
 
 ---
 
@@ -322,7 +339,7 @@ notice:
 
 ### 4.3 Special case — AI agent instruction files
 
-If the developer selected any AI coding agent in Q6, create
+If the developer selected any AI coding agent in Q8, create
 `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical Dflow project
 guide.
 

package/templates/greenfield/references/modify-existing-flow.md

@@ -265,6 +265,8 @@ If the lightweight checklist looks larger than a short-fix checklist, AI must pa
 Announce to developer:
 > "DDD impact analysis done — {Aggregate boundary OK / needs redesign}, {no new events / new events needed}. Ready to implement? `/dflow:next` to proceed, or adjust the design first."
 
+> Branch gate (policy-aware): a feature branch is mandatory for every tier (T1 / T2 / T3) under both Git policies (`_conventions.md` § Git Policy). If you are already on this work's `feature/{SPEC-ID}-{slug}` (or `bugfix/{BUG-ID}-{slug}`) branch — e.g. the change belongs to the active feature you are already in — the gate is satisfied and nothing new is created. Otherwise (on the base branch the project cuts from, or an unrelated branch) the AI offers to create/switch to the correct branch, switch to an existing matching one, or override and record it in the `_index.md` Checkpoint Log. Dflow does not need to know which branch is your base. See `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI Commits.
+
 Wait for confirmation before entering Step 4.
 
 ## Step 4: Implement
@@ -283,6 +285,8 @@ Even for bug fixes, verify:
 Announce to developer:
 > "Implementation appears complete. Ready to update documentation (spec, models.md, rules.md, events.md, glossary, tech-debt)? `/dflow:next` to proceed."
 
+> Commit checkpoint (per `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI Commits): offer to commit, then record the result in the `_index.md` Checkpoint Log. Tier sets the count — T2 commits the merged spec+implementation here (closeout is the second checkpoint); T3 is a single commit.
+
 Wait for confirmation before entering Step 5. This step gate is where the completion checklist is triggered — do not skip.
 
 ## Step 5: Update Documentation

package/templates/greenfield/references/new-feature-flow.md

@@ -278,11 +278,24 @@ The slug **must match the slug agreed in Step 3.5** (which is also the
 feature directory name). The SPEC-ID + slug links the branch to its
 feature directory and `_index.md`.
 
+**Branch gate (policy-aware).** A feature branch is mandatory under both Git
+policies (`gitflow` / `trunk`, per `_conventions.md` § Git Policy). The gate
+checks whether you are already on this feature's `feature/{SPEC-ID}-{slug}`
+branch: if so, it is satisfied. If you are not yet on it (still on the base
+branch the project cuts from, or an unrelated branch), the AI offers to create
+and switch to `feature/{SPEC-ID}-{slug}`, switch to an existing matching branch,
+or override and stay (recorded in the `_index.md` Checkpoint Log; three
+consecutive overrides → the AI suggests re-running `dflow init`). Dflow does not
+need to know which branch is your base. See `references/git-integration.md`
+§ Commit Checkpoints, Branch Gate & AI Commits.
+
 **→ Step Gate: Step 6 → Step 7**
 
 Announce to developer:
 > "Branch `feature/{SPEC-ID}-{description}` is created. Ready to start layer-by-layer implementation (Domain first)? `/dflow:next` to proceed, or discuss layer order / scope first."
 
+> Commit checkpoint (T1 milestone 1 of 3 — see `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI Commits): now that the feature branch exists (the branch gate above ran first, so this commit lands on the feature branch — never on a base branch), offer to commit the spec baseline, then record the result (committed / skipped) in the `_index.md` Checkpoint Log. Milestone 2 = implementation (Step 7→8); milestone 3 = closeout (`/dflow:finish-feature`).
+
 Wait for confirmation before entering Step 7.
 
 ## Step 7: Implementation Checklist
@@ -318,6 +331,8 @@ During implementation, continuously verify:
 Announce to developer:
 > "Implementation appears complete across all four layers. Ready to run the completion checklist (verify against spec, update domain docs + context-map, ensure test coverage, archive the spec)? `/dflow:next` to proceed."
 
+> Commit checkpoint (T1 milestone 2 of 3): offer to commit the implementation, then record the result in the `_index.md` Checkpoint Log. Milestone 3 (closeout) is the `/dflow:finish-feature` checkpoint.
+
 Wait for confirmation before entering Step 8. This step gate is where the completion checklist is triggered — do not skip.
 
 ## Step 8: Completion

package/templates/greenfield/references/new-phase-flow.md

@@ -67,6 +67,17 @@ AI must locate the target feature and load its current state:
      and `behavior.md` if the new phase is likely to touch system-level
      state (BC-level current state lives there, not in `_index.md`)
 
+4. **Branch gate — ensure you are on this feature's branch (before any commit)**
+
+   This phase's commits must land on the active feature's
+   `feature/{SPEC-ID}-{slug}` branch. If you are not already on it (you
+   identified the feature by name, or are on a base / unrelated branch),
+   switch to the existing branch — or override and record it in the
+   `_index.md` Checkpoint Log. **Never create a new feature branch here:**
+   `new-phase` extends an existing active feature, it does not start one. See
+   `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI
+   Commits.
+
 Share what you found:
 
 > "OK — `{SPEC-ID}-{slug}` has {N} prior phases in BC `{context}`. The
@@ -167,6 +178,8 @@ Announce to developer:
 > Ready to refresh `_index.md` (add Phase Specs row, regenerate Current BR
 > Snapshot from the Delta)? `/dflow:next` to proceed."
 
+> Commit checkpoint (per `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI Commits): with the Step 1 branch gate satisfied (you are on the feature's branch), offer to commit the phase-spec baseline and record the result in the `_index.md` Checkpoint Log.
+
 Wait for confirmation before entering Step 5.
 
 ## Step 5: Refresh `_index.md`
@@ -240,6 +253,8 @@ Announce to developer:
 > Ready to mark this phase completed and update `_index.md`? `/dflow:next`
 > to proceed."
 
+> Commit checkpoint (per `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI Commits): offer to commit the phase implementation, then record the result in the `_index.md` Checkpoint Log.
+
 Wait for confirmation before entering Step 7.
 
 ## Step 7: Complete the Phase

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

@@ -125,8 +125,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)
@@ -309,19 +307,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/greenfield/scaffolding/Git-principles-trunk.md

@@ -77,8 +77,6 @@ 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)
@@ -106,8 +104,6 @@ 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>
 ```
 
 ---
@@ -183,7 +179,6 @@ Related BR-IDs:
 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
@@ -210,8 +205,6 @@ feat({scope}): {Phase N title} — closes {SPEC-ID}
 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)
@@ -288,19 +281,22 @@ Three categories:
 | `git branch` (listing only) |
 | `gh pr status` / `gh pr view` |
 
-### 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/greenfield/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)
@@ -95,6 +96,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
 
 > 一句話：目前進展到哪？下一個動作是什麼？