dflow-sdd-ddd 0.8.0 → 0.9.0

package/templates/brownfield/references/dflow-feedback-flow.md

@@ -2,7 +2,8 @@
 
 `/dflow:report-dflow-feedback` helps the developer turn a Dflow problem or
 improvement observed during real project work into a high-quality upstream
-feedback draft.
+feedback draft. The draft is rendered **field by field to match the upstream
+GitHub issue form**, so the developer pastes each field with no reformatting.
 
 This flow is **not** a project feature workflow and does not change the
 application being built. It is a standalone governance/support flow for Dflow
@@ -48,13 +49,16 @@ turn it into a PR, or discard it.
 
 ## Step 1: Classify the Feedback
 
-Classify the feedback as one of:
+Classify the feedback as one of the following. Each maps to one upstream issue
+form (see "Upstream Issue Forms" below):
 
-- Bug report
-- Workflow change request
-- Documentation feedback
-- Question / unclear usage
-- Maintainer release/process feedback
+| Classification | Upstream issue form | Title prefix |
+|---|---|---|
+| Bug report | Bug report | `[Bug]: ` |
+| Workflow change request | Workflow change request | `[Workflow]: ` |
+| Documentation feedback | Documentation feedback | `[Docs]: ` |
+| Question / unclear usage | Question | `[Question]: ` |
+| Maintainer release/process feedback | Workflow change request (closest form; the upstream repo disables blank issues) | `[Workflow]: ` |
 
 Capture:
 
@@ -88,92 +92,160 @@ Avoid:
 
 ## Step 3: Redaction Pass
 
-Before writing the issue body section, perform a redaction check and include it
-in the draft:
+Before writing any field content, run a redaction check and use it as your own
+gate. Confirm there are:
 
-```markdown
-## Redaction Checklist
+- No secrets, tokens, credentials, or auth headers
+- No customer, tenant, or private organization names
+- No proprietary business rules beyond a sanitized paraphrase
+- No private repository URLs or internal hostnames
+- No long proprietary source snippets
 
-- [ ] No secrets, tokens, credentials, or auth headers
-- [ ] No customer, tenant, or private organization names
-- [ ] No proprietary business rules beyond sanitized paraphrase
-- [ ] No private repository URLs or internal hostnames
-- [ ] No long proprietary source snippets
-- [ ] Developer reviewed before submission
-```
+The draft ends with a short submitter self-check (Step 5); leave its items
+unchecked unless the developer explicitly confirms them.
+
+## Step 4: Resolve the Target Issue Form
 
-Leave the final "Developer reviewed before submission" unchecked unless the
-developer explicitly confirms it.
+Submit upstream at: **https://github.com/weilung/dflow-sdd-ddd/issues/new/choose**
 
-## Step 4: Write the Feedback Draft
+Resolve the field schema for the chosen form using this priority chain (it
+avoids any network dependency at draft time):
 
-Use this structure:
+1. **Live upstream schema** — if you can read the target repo's
+   `.github/ISSUE_TEMPLATE/*.yml` (for example you are working inside a
+   `dflow-sdd-ddd` checkout), use that file; it is authoritative.
+2. **Bundled field map** — otherwise use the field map in "Upstream Issue
+   Forms" below. It is a snapshot of the upstream forms shipped with Dflow.
+3. **Generic fallback** — only if the feedback matches none of the forms, use
+   Step 6.
 
-```markdown
-# Dflow Feedback Draft: {short-title}
+## Step 5: Render the Draft Field by Field
 
-## Summary
+Write the draft as one block per upstream field, in the form's field order, so
+the developer copies each block straight into the matching field.
 
-{One or two sentences.}
+Per field-type rules:
 
-## Type
+| Field type | How to render |
+|---|---|
+| `input` | One short line inside a fenced block. |
+| `textarea` | Multi-line content inside a fenced block. If the field sets a non-empty `render:` attribute, do **not** add an extra fence (the form already code-blocks it). |
+| `dropdown` | State the **recommended option** plus a one-line reason. If `multiple: true`, list the chosen options. |
+| `checkboxes` | List every option as `- [x]` / `- [ ]`; mark any option whose schema sets `required: true`. |
+| `markdown` | Display-only text in the form — produce **no** field block for it. |
+| upload / attachment | Emit a manual step ("drag the relevant screenshot / log into the issue editor"); do not try to handle the file. |
 
-{Bug report | Workflow change request | Documentation feedback | Question | Maintainer process feedback}
+Always start with a **Title** block: the form's title prefix plus a concise
+one-line summary. GitHub pre-fills the prefix in the title box; the developer
+can paste the full line over it.
 
-## Observed While Using
+Attribute handling: bring `value` / `default` in as starting content; surface
+`placeholder` as a hint; append "(required)" to the block heading when the
+field sets `required: true`.
 
-- Dflow version: {version-or-unknown}
-- Command / flow: {command-or-flow}
-- Track: {Greenfield | Brownfield | both | unknown}
-- Project context: {sanitized generic context}
+**Fence escaping (dynamic).** Wrap each field's content in a backtick fence
+whose length is *(longest backtick run in the content) + 1*, minimum 3. The
+fence is only a local wrapper so the content survives in the draft file — when
+pasting into the issue form, the developer copies the **inner** content, not
+the fence. State this in the draft.
 
-## Affected Dflow Area
+Draft skeleton:
 
-- {CLI | template | scaffolding | skill reference | tutorial | docs | governance}
-- Files or concepts: {sanitized list}
+````markdown
+# {Issue form name} — {short title}
 
-## Problem
+## Where to submit
 
-{What happened, why it is confusing or harmful, and who is affected.}
+https://github.com/weilung/dflow-sdd-ddd/issues/new/choose → choose
+**"{Issue form name}"**. (A GitHub account is all you need; the title is
+auto-prefixed with `{prefix}`.)
 
-## Expected Behavior or Improvement
+## Title
+
+```
+{prefix}{concise one-line summary}
+```
 
-{What Dflow should do or explain instead.}
+## {Field label} (required)
 
-## Evidence
+```
+{field content; copy the inner text only, not this fence}
+```
 
-{Minimal sanitized observations.}
+... one block per field, in form order ...
 
-## Compatibility / Breaking-Change Risk
+## Before you submit (submitter self-check)
 
-{None | low | medium | high}, with reasoning.
+- [ ] Any real file names / customer names / internal project code names to redact?
+- [ ] If you attach screenshots, do they show sensitive content (internal systems, tokens, passwords)?
+- [ ] Is opening a public issue within what your organization allows?
+````
 
-## Suggested GitHub Issue Body
+Keep the draft **submitter-facing only**: no maintainer tracking notes, no
+internal references, no "for your friend / for yourself" audience switches.
 
-{Copy-ready issue body matching the closest issue template.}
+## Upstream Issue Forms (bundled field map)
 
-## Optional PR Plan
+> Snapshot of the `weilung/dflow-sdd-ddd` issue forms. If the live `.yml` is
+> reachable (Step 4 priority 1), prefer it. Resync this map when the upstream
+> forms change.
 
-{Only include if the change is small and concrete. Otherwise write "Not recommended yet; start with an issue."}
+### Bug report — title `[Bug]: `
 
-## Redaction Checklist
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| Dflow version | input | yes | placeholder `0.2.0` |
+| Node.js version | input | yes | from `node --version` |
+| Project track | dropdown | yes | Greenfield / Brownfield / Not sure |
+| Command or workflow | textarea | yes | the command or `/dflow:*` workflow used |
+| Expected behavior | textarea | yes | |
+| Actual behavior | textarea | yes | include relevant output |
+| Reproduction steps | textarea | yes | smallest steps that reproduce |
+| Additional context | textarea | no | screenshots / snippets / environment |
 
-- [ ] No secrets, tokens, credentials, or auth headers
-- [ ] No customer, tenant, or private organization names
-- [ ] No proprietary business rules beyond sanitized paraphrase
-- [ ] No private repository URLs or internal hostnames
-- [ ] No long proprietary source snippets
-- [ ] Developer reviewed before submission
-```
+### Workflow change request — title `[Workflow]: `
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| Problem | textarea | yes | |
+| Proposed change | textarea | yes | |
+| Affected track | dropdown | yes | Greenfield / Brownfield / Both / Not sure |
+| Affected area | checkboxes | no | CLI command / Generated template / Generated scaffolding / Skill workflow guidance / Tutorial or examples / Documentation only |
+| Compatibility risk | textarea | yes | |
+| Alternatives considered | textarea | no | |
+
+### Documentation feedback — title `[Docs]: `
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| Affected page or file | input | yes | placeholder `README.md` |
+| Reader goal | textarea | yes | what you were trying to understand or do |
+| What was confusing? | textarea | yes | the missing, unclear, or misleading part |
+| Suggested improvement | textarea | no | optional wording or structure |
+
+### Question — title `[Question]: `
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| Project type | dropdown | yes | New project / Existing project / Not sure |
+| Dflow track you are considering | dropdown | yes | Greenfield / Brownfield / Not sure |
+| What are you trying to do? | textarea | yes | the workflow or decision you need help with |
+| Project context | textarea | no | framework, team workflow, AI agent, constraints |
+
+## Step 6: Generic Fallback
+
+Use this only when the feedback matches none of the forms above. The upstream
+repo disables blank issues, so direct the developer to pick the closest form at
+`https://github.com/weilung/dflow-sdd-ddd/issues/new/choose` and adapt. Emit
+two paste-ready blocks — a `Title` and a `Body` — plus the URL. Do **not** fall
+back to a generic `## Problem` / `## Evidence` Markdown draft.
 
-## Step 5: Present Submission Options
+## Step 7: Present Submission Options
 
-After writing the draft, summarize the options:
+After writing the draft, name the draft file path and whether any submitter
+self-check items remain unchecked, then summarize the options:
 
-- Copy the suggested issue body manually into GitHub.
-- Use the optional PR plan as implementation guidance in a Dflow source
-  checkout.
+- Open the chosen issue form and paste each field block.
 - Discard the draft if it was only a local observation.
 
-Do not submit anything automatically. End by naming the draft file path and
-whether any redaction checklist items remain unchecked.
+Do not submit anything automatically.

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

@@ -11,10 +11,18 @@ state, archives the feature directory, and emits a Git-strategy-neutral
 **Integration Summary** for the developer's PR / merge / push step.
 
 **Important boundaries**:
-- This command **does not auto-merge**. It does not push, does not open a
-  PR, does not run the project's merge strategy. Those decisions stay
-  with the developer / project's Git principles — Dflow keeps merge
-  strategy project-owned.
+- This command **does not auto-merge** and never pushes or opens a PR on its
+  own. Merge strategy follows the team's selected Git policy (`gitflow` /
+  `trunk`, recorded in `dflow/specs/shared/_conventions.md` § Git Policy).
+- Closeout is split into two gates so it works offline: a **Local-closeout
+  gate** (Steps 1–4: validation, status flip, BC sync, archive + an optional
+  commit checkpoint — all doable with no network) and an **Integration / PR
+  gate** (Step 5: push / merge / PR — needs network; the AI only runs
+  `git push` / `gh pr create` when you explicitly ask).
+- At the archive checkpoint the AI may offer to commit using your Git identity;
+  you can always decline. The commit marker mode is read from `_conventions.md`
+  § AI Commit Policy. This replaces Dflow's earlier "the AI never commits"
+  stance — the AI helps at natural checkpoints, you keep the final say.
 - The BC-layer sync in Step 3 **reuses the existing Step 8.3 mechanism**
   from `new-feature-flow` — it does not introduce a new sync flow. Treat
   it as "lift Step 8.3 out of the per-phase checklist and run it once at
@@ -41,8 +49,8 @@ AI runs mechanical checks first. Report `✓` / `✗` for every item; if any
 proceeding (do not flip status, do not archive, do not emit summary).
 
 - [ ] Locate the feature directory at `dflow/specs/features/active/{SPEC-ID}-{slug}/`
-- [ ] `_index.md` exists and parses (YAML front matter intact, six required
-      sections present)
+- [ ] `_index.md` exists and parses (YAML front matter intact, seven required
+      sections present, including the Checkpoint Log)
 - [ ] Every row in `_index.md` Phase Specs table has Status = `completed`
 - [ ] Every phase-spec file referenced in the Phase Specs table exists at
       the path the table claims
@@ -88,7 +96,7 @@ Also update the **Resume Pointer** to reflect closeout:
 
 ```
 **Current Progress**: feature completed ({date}); all phase-specs status = completed.
-**Next Action**: merge / push (per project Git-principles).
+**Next Action**: integration — push / merge / PR per the selected Git policy.
 ```
 
 **→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (status flipped). Entering Step 3: Sync BR Snapshot to BC layer." and continue.
@@ -172,11 +180,35 @@ the full rule set.
 
 After the move, also `git add` any modified files from Step 3 (the
 updated `rules.md`, `behavior.md`, `glossary.md`, `tech-debt.md`, etc.)
-into the same stage. AI **does not commit** — the developer commits in
-their own preferred manner (and the project's Git-principles decide
-whether one commit or several).
+into the same stage.
 
-**→ Transition (step-internal)**: Step 4 complete. Announce "Step 4 complete (feature archived to completed/). Entering Step 5: Emit Integration Summary." and continue.
+**Closeout commit checkpoint** (completes the offline Local-closeout gate):
+
+```
+✓ Feature archived to completed/ and closeout files staged
+   Commit this closeout now?
+   [Y] Yes — the AI commits with your Git identity (marker per _conventions.md § AI Commit Policy)
+   [N] No — skip; you commit yourself
+```
+
+Whether you choose Y or N, record one row in the feature `_index.md`
+Checkpoint Log (`closeout | committed ({hash})` or `closeout | skipped`). Only
+write a hash after the commit actually succeeds; if a pre-commit hook rejects it
+or the commit fails, record `failed` and surface the error — never write a fake
+hash.
+
+The Local-closeout gate is satisfied **only when the closeout is committed**:
+closeout complete, Checkpoint Log updated, and the working tree clean (no
+uncommitted changes). If you declined the commit (chose N) or it failed,
+Local-closeout is **not** satisfied yet — commit the staged closeout yourself
+before continuing; do not enter the Integration / PR gate with uncommitted
+changes. Once committed, the gate stands on its own offline; integration happens
+in Step 5 when you have network.
+
+**→ Transition (step-internal)**: Step 4 complete. Branch on whether the closeout commit landed:
+
+- **Closeout commit landed (working tree clean)** → announce "Step 4 complete (feature archived; Local-closeout gate satisfied). Entering Step 5: Integration / PR gate." and continue.
+- **Closeout commit was declined (N) or failed** → **stop here.** Announce "Step 4 complete (feature archived), but the Local-closeout gate is not satisfied yet — the closeout is staged but uncommitted. Commit those changes (or address the failure), then resume to Step 5." Do **not** enter Step 5 with uncommitted closeout changes.
 
 ## Step 5: Emit Integration Summary (Git-strategy-neutral)
 
@@ -185,10 +217,10 @@ Produce a plain-text summary of what this feature did. The summary is
 developer adapts to whichever merge strategy their project uses
 (merge commit, squash, rebase, fast-forward — Dflow stays neutral).
 
-For projects that adopted the optional Dflow Git-principles scaffolding, the
-applicable `scaffolding/Git-principles-{gitflow|trunk}.md` "Integration
-Commit Message Conventions" section explains how to format the actual commit
-message from this summary.
+The selected Git policy's `Git-principles-{gitflow|trunk}.md` (seeded at init
+under `dflow/specs/shared/`) explains, in its "Integration Commit Message
+Conventions" section, how to format the actual commit / merge message from this
+summary.
 
 Format:
 
@@ -212,10 +244,11 @@ Phase List:
 - phase-2 ({date}): {phase-slug} — {1 line}
 - ...
 
-Next Steps (developer):
-- Per the project's Git-principles, choose a merge strategy (merge commit /
-  squash / rebase / fast-forward) and execute
-- Push to remote / open a PR
+Next Steps (developer) — Integration / PR gate (needs network):
+- Per the selected Git policy (`gitflow` / `trunk` in `_conventions.md`), choose
+  a merge strategy (merge commit / squash / rebase / fast-forward) and execute
+- Push to remote / open a PR — the AI can run `git push` / `gh pr create` for
+  you, but only when you explicitly ask; it never pushes on its own
 ```
 
 Print the summary to the conversation; do not write it to a file (it is
@@ -233,7 +266,9 @@ the developer:
 If no `follow-up-of` field, skip Step 6 and announce closeout complete:
 > "`/dflow:finish-feature` complete for `{SPEC-ID}-{slug}`. Feature
 > directory is now at `dflow/specs/features/completed/{SPEC-ID}-{slug}/`.
-> Stage is set; commit / merge / push at your discretion."
+> If you skipped the closeout commit, commit the staged changes first to
+> finish the Local-closeout gate. Then integration — merge / push / PR —
+> follows the selected Git policy, at your discretion."
 
 ## Step 6: Reverse-Update Follow-up Tracking (only if follow-up)
 
@@ -246,7 +281,7 @@ Follow-up Tracking table.
 3. Flip Status → `completed`
 
 ```bash
-# AI does the edit; commits stay with the developer
+# The AI makes the edit and may offer to commit it (Y / N), per the AI commit policy
 ```
 
 After the update:

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

@@ -6,9 +6,10 @@ agnostic about which Git *branching strategy* your project adopts (Git Flow,
 GitHub Flow, trunk-based, single-`main`, 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
 
@@ -103,6 +104,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
@@ -255,9 +314,9 @@ AI should verify:
 - [ ] If business logic was touched, evaluate Domain extraction
 
 > 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/brownfield/references/init-project-flow.md

@@ -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?
 >
@@ -197,7 +214,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
@@ -231,7 +248,7 @@ 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 |
 >
@@ -255,7 +272,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,7 +318,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/brownfield/references/modify-existing-flow.md

@@ -299,6 +299,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 +343,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

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

@@ -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