dflow-sdd-ddd 0.8.0 → 0.10.0

package/templates/greenfield/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/greenfield/references/drift-verification.md

@@ -180,10 +180,7 @@ Recommended trigger points (not enforced — developer's judgment):
 This command operates entirely within `dflow/specs/domain/{context}/` files
 (`rules.md`, `behavior.md`, and the `events.md` bonus check). It does
 **not** read from `dflow/specs/features/active/{SPEC-ID}-{slug}/` directories
-— the feature directory layout is not part of verify's input. The only effect of feature directory layout on this
-command is ensuring `last-updated` dates in `behavior.md` are bumped at
-`/dflow:finish-feature` time (so verify's mechanical drift guard stays
-useful).
+— the feature directory layout is not part of verify's input.
 
 ## Interaction with Other Commands
 

package/templates/greenfield/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 5.3 mechanism**
   from `new-feature-flow` (Step 8.3) and `modify-existing-flow` (Step
   5.3) — it does not introduce a new sync flow. Treat it as "lift Step
@@ -27,7 +35,7 @@ state, archives the feature directory, and emits a Git-strategy-neutral
 - Step 5 → Step 6 (Integration Summary emitted → optional follow-up reverse-link)
 
 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: Validate Phase Specs and `_index.md`
@@ -42,8 +50,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
@@ -89,7 +97,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.
@@ -119,6 +127,8 @@ For each row in Current BR Snapshot where Status = `active`:
   `rules.md` (REMOVED rule)
 - For any RENAMED BR-ID → rename the BR-ID in `rules.md` and update
   `glossary.md` if the term itself changed
+- For every BR-ID added, modified, or renamed above, set its `Last updated`
+  date in `rules.md`'s Rule Index to today
 
 For `behavior.md`:
 
@@ -128,7 +138,6 @@ For `behavior.md`:
   transitions and Domain Events as appropriate
 - For REMOVED BR-IDs, delete the corresponding scenario section from
   `behavior.md`
-- Update the BR-ID anchor's `last-updated` date in `behavior.md` to today
 
 For `events.md`:
 - Add any new Domain Events introduced by phase-specs in this feature
@@ -187,11 +196,34 @@ the full rule set.
 After the move, also `git add` any modified files from Step 3 (the
 updated `rules.md`, `behavior.md`, `events.md`, `context-map.md`,
 `glossary.md`, `architecture/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).
 
-**→ 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)
 
@@ -200,10 +232,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:
 
@@ -233,10 +265,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
@@ -254,7 +287,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)
 
@@ -267,7 +302,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/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
@@ -123,7 +182,6 @@ diff. That breaks:
 - `git blame` on lines that crossed the rename boundary
 - PR diff quality (reviewers see two unrelated big-blob changes
   instead of one rename + small content diff)
-- `/dflow:verify` and other tools that walk feature history
 
 This is a known weakness of OpenSpec's directory-rename pattern; Dflow
 deliberately avoids it by mandating `git mv`.
@@ -245,9 +303,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