dflow-sdd-ddd 0.8.0 → 0.10.0

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

@@ -49,8 +49,8 @@ Report findings plainly:
 >  - `dflow/specs/`: not yet present → greenfield Dflow setup
 >  - `specs/`: present → legacy / other-tool directory; Dflow V1 will not
 >    migrate or modify it
->  - `CLAUDE.md`: present → will not overwrite; I'll offer a snippet
->    to merge into it"
+>  - `CLAUDE.md`: present → I'll append a marked Dflow block (shown in
+>    the preview); a merge snippet only if there's a marker conflict"
 
 Or:
 
@@ -117,25 +117,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?
 >
@@ -145,9 +162,10 @@ one).
 >
 > If you select any agent, Dflow will create
 > `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical guide. Root-level
-> tool files stay thin and point back to that guide. Existing tool files are
-> never overwritten; Dflow writes merge snippets under `dflow/specs/shared/`
-> instead."
+> tool files stay thin and point back to that guide. Existing user content is
+> never overwritten; Dflow appends a marked Dflow block (shown in the preview)
+> and refreshes it in place on re-run. Merge snippets under
+> `dflow/specs/shared/` are used only if Dflow markers conflict."
 
 **→ Transition (step-internal)**: Step 2 complete. Announce
 > "Step 2 complete (project information captured). Entering Step 3:
@@ -197,7 +215,7 @@ Key Brownfield-track notes:
   track makes this file mandatory because BCs are usually planned
   up-front).
 
-### 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
@@ -211,16 +229,17 @@ vendored workflow bundle). Compute the destination path:
 | `scaffolding/Git-principles-trunk.md` | `dflow/specs/shared/Git-principles-trunk.md` |
 | `scaffolding/AI-AGENT-GUIDE.md` | `dflow/specs/shared/AI-AGENT-GUIDE.md` when at least one AI agent is selected |
 | generated tool shim | `AGENTS.md`, `CLAUDE.md`, or `.github/copilot-instructions.md` when selected and missing |
-| generated merge snippet | `dflow/specs/shared/*-snippet.md` when the selected tool file already exists |
+| marked Dflow block | appended to a selected existing tool file unless it already points to `AI-AGENT-GUIDE.md`; refreshed in place on re-run |
+| fallback merge snippet | `dflow/specs/shared/*-snippet.md` only when the selected tool file has conflicting or malformed Dflow markers |
 
 ### 3.3 Present the preview
 
-Present the complete file list as two tables, separating create vs
+Present the complete file list as two tables, separating create / update vs
 skip, and wait for developer confirmation:
 
 > "Based on Step 1 inventory + Step 2 answers, here is what I'll do:
 >
-> **Will create ({N} files):**
+> **Will create / update ({N} files):**
 >
 > | Path | Source |
 > |---|---|
@@ -231,9 +250,9 @@ skip, and wait for developer confirmation:
 > | `dflow/specs/shared/_conventions.md` | `scaffolding/_conventions.md` (mandatory baseline) |
 > | `dflow/specs/migration/tech-debt.md` | `templates/tech-debt.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 |
+> | `CLAUDE.md` | marked Dflow block appended to existing CLAUDE.md (shown in preview) |
 >
 > **Will skip ({M} files — already present):**
 >
@@ -255,7 +274,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.
 
 ---
 
@@ -301,18 +320,31 @@ 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.
 
 For each selected tool-specific file (`AGENTS.md`, `CLAUDE.md`,
 `.github/copilot-instructions.md`):
 
+(checked in this order — the first matching rule wins):
+
 - if the target file does not exist, create a small shim at the target
   path that points to `dflow/specs/shared/AI-AGENT-GUIDE.md`
-- if the target file already exists, do not overwrite it; write a merge
-  snippet under `dflow/specs/shared/` and report that the developer
-  should merge it manually
+- if the target file contains conflicting or malformed Dflow markers, do not
+  edit it; write a fallback merge snippet under `dflow/specs/shared/` and
+  report that the developer should merge it manually
+- if the target file already contains a single well-formed Dflow marked block,
+  replace that block in place (idempotent refresh) and keep the rest of the
+  file unchanged
+- if the target file is an existing whole-file Dflow-generated shim, refresh it
+  in place
+- if the target file already points to the guide through the developer's own
+  pointer (and has no Dflow marked block), leave it untouched
+- otherwise preserve the existing content and append a marked Dflow block at
+  the end of the file, keeping the file's dominant line ending; show that block
+  in the preview, and refresh that same block on re-run. If the developer later
+  deletes the block, a later `init` / `configure-agents` run appends it again
 
 ### 4.4 Directory-only entries
 
@@ -337,7 +369,7 @@ Summarise what actually happened and point at the next command.
 ```
 Init complete. Summary:
 
-  Created ({N} files):
+  Created / Updated ({N} files):
     ✓ dflow/specs/features/active/.gitkeep
     ✓ dflow/specs/features/completed/.gitkeep
     ✓ dflow/specs/features/backlog/.gitkeep
@@ -346,7 +378,7 @@ Init complete. Summary:
     ✓ dflow/specs/migration/tech-debt.md
     ✓ dflow/specs/shared/_overview.md
     ✓ dflow/specs/shared/Git-principles-trunk.md
-    ✓ CLAUDE.md (seeded from scaffolding snippet)
+    ✓ CLAUDE.md (marked Dflow block appended)
 
   Skipped ({M} files already present):
     - (none this run)
@@ -395,9 +427,8 @@ Remind the developer to review files that have `{placeholder}` tokens
 still in them:
 
 > "A few files still have `{placeholder}` tokens that need your input:
->  - `dflow/specs/shared/_overview.md`: `{業務領域}`, `{團隊}`,
->    `{使用者規模}`
->  - `CLAUDE.md`: `{業務領域}`
+>  - `dflow/specs/shared/_overview.md`: the Business Domain and Technical
+>    Architecture fields (e.g. primary domain, stakeholders, user scale, stack)
 >
 >  These are fine to leave for now; fill them in during your next
 >  review pass."

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

@@ -1,15 +1,15 @@
 # Modify Existing Feature Workflow
 
-Step-by-step guide for when a developer triggers `/dflow:modify-existing` or `/dflow:bug-fix` (or natural language implying a modification task — see SKILL.md § Workflow Transparency for the auto-trigger safety net).
+Step-by-step guide for when a developer triggers `/dflow:modify-existing` or `/dflow:bug-fix` (or natural language implying a modification task — see AI-AGENT-GUIDE.md § Workflow Transparency for the auto-trigger safety net).
 
 **Step Gates** in this flow (stop-and-confirm before proceeding):
 - Step 2 → Step 3 (baseline captured → analyze business logic embedded in delivery/entrypoint code: presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures)
 - Step 4 → Step 5 (extraction decision → start implementation)
 - Step 5 → Step 6 (implementation done → update artifacts)
 
-All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See SKILL.md § Workflow Transparency for the full transparency protocol and confirmation signals.
+All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow Transparency for the full transparency protocol and confirmation signals.
 
-**Ceremony adjustment when triggered by `/dflow:bug-fix`**: treat as lightweight — use the Lightweight Spec Template at the end of this file instead of the full spec, and Step 4 (extraction) may default to "defer and record in tech-debt.md" unless the bug itself is in extractable logic. T2 still generates a concise `Implementation Tasks` checklist (see Step 4).
+**Ceremony adjustment when triggered by `/dflow:bug-fix`**: treat as lightweight — use the Lightweight Spec Template (see `templates/lightweight-spec.md`) instead of the full spec, and Step 4 (extraction) may default to "defer and record in tech-debt.md" unless the bug itself is in extractable logic. T2 still generates a concise `Implementation Tasks` checklist (see Step 4).
 
 ## Mindset
 
@@ -31,7 +31,7 @@ This step has two parallel concerns:
 
 **Part A — Determine the Ceremony Tier (T1 / T2 / T3)**
 
-Dflow runs three ceremony tiers (full table in SKILL.md § Ceremony Scaling).
+Dflow runs three ceremony tiers (full table in AI-AGENT-GUIDE.md § Ceremony Scaling).
 For a modification, AI judges which tier fits before deciding what to
 produce:
 
@@ -141,7 +141,7 @@ add a row:
 | {新 SPEC-ID} | {新 slug} | {today} | in-progress |
 ```
 
-This update is **part of the same change set** (the developer commits
+This update is **part of the same change set** (offer to commit
 both at once; commit message should mention "Add follow-up reference to
 `{新 SPEC-ID}`"). The reverse link is a derived index — the new
 feature's `follow-up-of` field is the authoritative source.
@@ -152,8 +152,6 @@ phase's content).
 
 ## Step 2: Document Current Behavior (if no spec exists)
 
-## Step 2: Document Current Behavior (if no spec exists)
-
 This is critical. Before changing anything, capture what currently exists:
 
 ```
@@ -299,6 +297,8 @@ If the lightweight checklist looks larger than a short-fix checklist, AI must pa
 Announce to developer:
 > "Extraction decision made — {extract now / defer and record}. Ready to start implementation? `/dflow:next` to proceed, or adjust the extraction scope 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 5.
 
 ## Step 5: Implement the Change
@@ -341,6 +341,8 @@ protected void Calculate()
 Announce to developer:
 > "Implementation appears complete. Ready to update artifacts (spec, rules.md, models.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 6. This step gate is where the completion checklist is triggered — do not skip.
 
 ## Step 6: Update Artifacts
@@ -356,7 +358,7 @@ Items marked *(post-6.3)* are re-verified after the documentation merge in 6.3 l
 - [ ] Extracted logic (if Step 4 decided "extract now") lives under `src/Domain/` as framework-pure code
 - [ ] `Implementation Tasks` section (`phase-spec.md` or `lightweight-spec.md`): all tasks checked, or unchecked items explicitly labelled as follow-up
 - [ ] *(post-6.3)* `dflow/specs/domain/{context}/behavior.md` has a section anchor for every `BR-*` in ADDED / MODIFIED entries; REMOVED entries' anchors have been deleted (mechanical input for `/dflow:verify`)
-- [ ] *(post-6.3)* `dflow/specs/domain/{context}/behavior.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
+- [ ] *(post-6.3)* every ADDED / MODIFIED / RENAMED BR's `Last updated` in `dflow/specs/domain/{context}/rules.md` is later than this spec's `created` date (mechanical drift guard)
 
 If any item fails, report the gap and pause — don't proceed to 6.2.
 
@@ -412,33 +414,3 @@ new follow-up directory; that happens at `/dflow:finish-feature` time.
 
 Only announce "change complete" after the appropriate archival step
 above (or the Step 6.3 docs sweep) is done.
-
-## Lightweight Spec Template (for bug fixes)
-
-For small bug fixes, a lightweight spec is enough:
-
-```markdown
----
-id: BUG-042
-title: Fix rounding inconsistency in expense calculation
-status: in-progress
-bounded-context: Expense
-created: 2025-02-12
----
-
-## Problem
-Entrypoint A uses Math.Round(amount, 0, MidpointRounding.AwayFromZero) (四捨五入)
-Entrypoint B uses Math.Floor(amount) (無條件捨去)
-They should both use the same rounding rule.
-
-## Expected Behavior
-Given an expense amount of 123.5 TWD
-When displayed or returned by any entrypoint
-Then it should show 124 (四捨五入 per accounting standard)
-
-## Root Cause
-Duplicated calculation logic — recorded in tech-debt.md
-
-## Fix
-Extract rounding to Money.Round() in Domain layer, both pages call it.
-```

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

@@ -1,6 +1,6 @@
 # New Feature Workflow
 
-Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natural language implying a new-feature task — see SKILL.md § Workflow Transparency for the auto-trigger safety net behavior).
+Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natural language implying a new-feature task — see AI-AGENT-GUIDE.md § Workflow Transparency for the auto-trigger safety net behavior).
 
 **Step Gates** in this flow (stop-and-confirm before proceeding):
 - Step 3 → Step 3.5 (domain concepts captured → confirm slug + directory + branch names)
@@ -8,9 +8,9 @@ Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natura
 - Step 6 → Step 7 (branch ready → start implementation)
 - Step 7 → Step 8 (implementation done → completion)
 
-All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See SKILL.md § Workflow Transparency for the full transparency protocol and confirmation signals.
+All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow Transparency for the full transparency protocol and confirmation signals.
 
-**Ceremony**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (T1 / T2 / T3) only applies to `/dflow:modify-existing` (see `references/modify-existing-flow.md` and SKILL.md § Ceremony Scaling).
+**Ceremony**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (T1 / T2 / T3) only applies to `/dflow:modify-existing` (see `references/modify-existing-flow.md` and AI-AGENT-GUIDE.md § Ceremony Scaling).
 
 ## Step 1: Intake — Understand the Request
 
@@ -188,7 +188,7 @@ Specifically ask about:
 Announce to developer:
 > "Spec is drafted — behavior scenarios, business rules, and edge cases are captured. Ready to plan the implementation (Domain layer design, interfaces, thin delivery/entrypoint code — presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures)? `/dflow:next` or reply 'OK' to continue, or tell me if the spec needs another iteration first."
 
-Wait for confirmation (`/dflow:next`, verbal OK, or implicit — see SKILL.md § Confirmation Signals) before entering Step 5.
+Wait for confirmation (`/dflow:next`, verbal OK, or implicit — see AI-AGENT-GUIDE.md § Confirmation Signals) before entering Step 5.
 
 ## Step 5: Plan the Implementation
 
@@ -273,11 +273,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 implementation? `/dflow:next` to proceed, or discuss implementation 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
@@ -294,6 +307,8 @@ During implementation, continuously check:
 Announce to developer:
 > "Implementation appears complete. Ready to run the completion checklist (verify against spec, update domain docs, 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
@@ -310,7 +325,7 @@ AI reports `✓` / `✗` for every item before touching docs. Items marked *(pos
 - [ ] Every `EC-*` edge case is handled
 - [ ] Domain layer has **no** delivery-framework references (grep `src/Domain/`)
 - [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` contains a section anchor for every `BR-*` introduced by this spec (mechanical input for `/dflow:verify`)
-- [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
+- [ ] *(post-8.3)* `dflow/specs/domain/{context}/rules.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
 
 If any item fails, report the gap and pause — don't proceed to 8.2.
 
@@ -339,12 +354,14 @@ Ask these one-by-one; do not dump all five at once.
 
 ### 8.4 Archival
 
-For a single-phase feature, this is the closeout point. For a multi-phase
-feature, the developer typically reaches this point at the end of the
-final phase — at which time `/dflow:finish-feature` is the recommended
-trigger (it bundles steps 8.1 / 8.2 verification, BC sync, and archival
-into one explicit ceremony). Either path is acceptable; pick the one
-that matches the developer's habit.
+For a single-phase feature, this is the closeout point. If the feature has
+later phases still ahead, this phase is complete but the feature is not —
+don't archive yet; run `/dflow:new-phase` to start the next phase, not
+`/dflow:finish-feature` yet. For a multi-phase feature, the developer
+typically reaches this point at the end of the final phase — at which time
+`/dflow:finish-feature` is the recommended trigger (it bundles steps 8.1 /
+8.2 verification, BC sync, and archival into one explicit ceremony). Either
+path is acceptable; pick the one that matches the developer's habit.
 
 - [ ] `_index.md` `status` field changed to `completed`
 - [ ] All `phase-spec-*.md` files in the feature directory have `status:

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

@@ -20,7 +20,7 @@ adds a new phase to an in-progress feature only.
 - Step 6 → Step 7 (implementation done → complete the phase)
 
 All other step transitions are **step-internal**: announce "Step N complete,
-entering Step N+1" and proceed without waiting. See SKILL.md § Workflow
+entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow
 Transparency for the full transparency protocol and confirmation signals.
 
 ## Step 1: Read Active Feature Context
@@ -64,6 +64,17 @@ AI must locate the target feature and load its current state:
      left off (its Business Rules and Delta-from-prior-phases sections in
      particular)
 
+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. The most recent
@@ -158,6 +169,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`
@@ -227,6 +240,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