dflow-sdd-ddd 0.11.0 → 0.13.0

package/templates/brownfield/templates/lightweight-spec.md

@@ -1,10 +1,10 @@
 ---
-id: BUG-{NUMBER}
+id: BUG-{NUMBER}    # bug-type T2 only; a non-bug T2 (lightweight-{date}-{slug}.md) carries no id — the filename identifies it
 title: {簡述問題}
-status: in-progress
+status: in-progress    # in-progress | completed
 bounded-context: {ContextName}
 created: {YYYY-MM-DD}
-branch: bugfix/BUG-{NUMBER}-{short-description}
+branch: bugfix/BUG-{NUMBER}-{slug}
 ---
 
 <!--

package/templates/brownfield/templates/models.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Domain Models
 

package/templates/brownfield/templates/phase-spec.md

@@ -1,13 +1,15 @@
 ---
-id: {CONTEXT}-{NUMBER}
+spec-id: SPEC-{YYYYMMDD}-{NNN}    # the owning feature's SPEC-ID (matches the feature directory name)
 title: Feature title
-status: draft | in-progress | completed
+status: in-progress    # in-progress | completed
 bounded-context: {ContextName}
 created: {YYYY-MM-DD}
 author: {developer-name}
-branch: feature/{CONTEXT}-{NUMBER}-{short-description}
+branch: feature/{SPEC-ID}-{slug}
 ---
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {Feature Title}
 
 <!--

package/templates/brownfield/templates/rules.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Business Rules
 

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

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Migration Tech Debt
 

package/templates/common/references/ddd-modeling-guide.md

@@ -101,6 +101,9 @@ Is it identified by an ID that persists over time?
             └─ No  → Re-examine — it's probably one of the above
 ```
 
+A stateful multi-step flow is not a Domain Service — see "Long-Running
+Processes".
+
 ## Aggregate Design
 
 Aggregates are the most important and most commonly misunderstood DDD concept.
@@ -186,6 +189,9 @@ When designing a new Aggregate:
 6. **Will any child collection grow without bound over time?** (history,
    comments, audit entries) Unbounded growth is a split signal — move it to
    its own Aggregate or a read model and reference by ID.
+7. **What would make this boundary wrong?** Record the answer in the
+   worksheet's Design Decisions as a re-evaluation condition ("revisit
+   when …") — it is what "Revising an Established Model" re-reads later.
 
 ### Invariant Classification
 
@@ -255,6 +261,79 @@ serialization tactics — distributed locks, per-key actors, aggregate-per-key
 sharding — exist but are advanced; reach for a store-level constraint or version
 check first.)
 
+## Revising an Established Model
+
+The sections above are about getting a boundary right the first time. This
+one is about the other half of a model's life: an established model whose
+original decision was right — until the conditions changed. **A recorded
+design decision is not settled law.** It is a decision *plus the conditions
+under which it was right*; when those conditions expire, the decision is
+due for review, not deference.
+
+### The re-read rule
+
+**When extending an existing Aggregate, re-read its recorded Design
+Decisions before adding to it** (the `aggregate-design.md` worksheet;
+Brownfield — see the Edition note). You are not reading for format — you
+are checking two things:
+
+1. Does any recorded **re-evaluation condition** ("revisit when …") match
+   the change in front of you?
+2. Did the original rationale assume something that is no longer true?
+
+### Signals that the model is resisting
+
+Any of these appearing in your change is a signal — go to the ladder below:
+
+- **Bending a field to fit** — a field that was previously required by the
+  entity's lifecycle is made nullable to fit a new case.
+- **Discriminator creep** — adding a `Purpose` / `Type` discriminator so
+  one entity carries materially different lifecycles, required fields, or
+  rules.
+- **Stacking another branch** — a third or later *distinct business branch*
+  on the same decision axis (validation / error variants don't count; the
+  count is an anchor, not an automatic refactor rule).
+- **Qualifying a term to use it** — you keep saying "the Order here means
+  the cart-order"; one glossary term now covers two lifecycles.
+- **A recorded re-evaluation condition matches** the current change.
+- **Cross-instance transaction pressure** — a new invariant or operation
+  needs same-transaction writes across Aggregate instances because the
+  current boundary cannot own the rule (see Aggregate Design Rules #2; a
+  flow over *time* is a different topic — see "Long-Running Processes").
+- **A child collection grows without bound** — the split signal from
+  Aggregate Design Rules #4 and Common Mistakes #7 applies to established
+  models too.
+
+### What to do when a signal fires — take the lowest rung that fits
+
+1. **Name it in the spec** (mandatory when a signal fires; zero design
+   cost). One short passage in the spec's design decisions / open
+   questions: which signal fired, the options, and the decision —
+   **proceed as-is, split, or rename — with the reason**. Deciding *not*
+   to split, recorded, is a perfectly good outcome when the rationale
+   still holds. What is not acceptable is extending the model as if the
+   question did not exist.
+2. **Treat the revision as its own change** when the answer is "split" or
+   "rename": record it as tech debt or a follow-up feature — or, if the
+   feature cannot proceed sanely on the old boundary, make the split /
+   rename the feature's first phase (T1 ceremony; the glossary moves
+   first, RENAMED deltas, code follows).
+
+Two guards, so this section cannot become its own kind of
+over-engineering:
+
+> Signals are the trigger, not a schedule. Do not re-litigate the model on
+> every touch: no signal → no ceremony; one signal → name it; several
+> signals, or a matched re-evaluation condition → evaluate seriously.
+
+> A signal triggers **review, not redesign**. Do not split or rename just
+> because a signal fired. A short recorded decision to keep the current
+> model is a valid outcome when the rationale still holds.
+
+This applies where a model exists to revise — core / supporting contexts.
+A generic context's thin wrapper (see "Subdomain-Aware Modeling Depth")
+has no worksheet and needs none of this ceremony.
+
 ## Value Objects
 
 ### When to Use Value Objects
@@ -286,11 +365,16 @@ public record Money(decimal Amount, Currency Currency)
 }
 
 // DateRange
-public record DateRange(DateOnly Start, DateOnly End)
+public record DateRange
 {
-    public DateRange
+    public DateOnly Start { get; }
+    public DateOnly End { get; }
+
+    public DateRange(DateOnly start, DateOnly end)
     {
-        if (Start > End) throw new DomainException("Start must be before End.");
+        if (start > end) throw new DomainException("Start must be before End.");
+        Start = start;
+        End = end;
     }
 
     public bool Contains(DateOnly date) => date >= Start && date <= End;
@@ -433,6 +517,95 @@ the values that changed — not a snapshot of the whole Aggregate.
   delivery. If no dispatcher is wired yet, record it as deferred tech debt — but
   still clear on a successful save so events cannot accumulate unbounded.
 
+## Long-Running Processes
+
+The Aggregate design rules above already cover the simple case: one Aggregate
+per transaction, with cross-Aggregate work flowing through Domain Events and
+eventual consistency. This section is for the flows where that is not the
+whole story — where the multi-step flow is itself a business thing with
+state, and that state needs a home.
+
+### Process or event chain?
+
+Use an event chain when each reaction can succeed or fail independently — a
+later failure does not change the earlier domain commitment. Treat the flow
+as a **process** when the business must track and decide the multi-step
+**outcome**: compensate or reverse an earlier commitment, answer current
+progress, enforce a deadline, or enforce an ordered cross-Aggregate workflow
+whose intermediate state matters.
+
+The quickest entry test: **if a later step fails, must an earlier step be
+undone?** "Payment failed → release the reserved stock" is a process, not an
+event chain.
+
+Further signals that the flow is a process:
+
+- The business asks "where is order #123 in the flow?" and no single
+  Aggregate can answer.
+- A deadline is part of the rules ("if payment is not confirmed within 30
+  minutes, release the seats").
+- Steps across Aggregates must run in a prescribed order **and** the
+  intermediate state matters to the business — being ordered by itself is
+  not enough.
+
+**Not a process:** fire-and-forget notifications, read-model updates,
+logging, and other best-effort side effects — even when ordered, even when
+they cross Aggregates. Those remain plain event chains; their failure
+handling is already covered by the failure-path guideline under Event
+Handling Guidelines.
+
+### Where does the process state live? Take the lowest rung that fits
+
+1. **A status field on the Aggregate that owns the flow** — the first choice
+   when the process is naturally part of one Aggregate's lifecycle:
+   `Order.Status = PendingPayment → Paid → Shipped`. Event handlers advance
+   the status; each compensation is an explicit state-transition method
+   (`order.Cancel(reason)`) with its own BR. Most mid-size flows stop here.
+   The boundary: a status field is enough only when the process is naturally
+   part of that Aggregate's lifecycle — do not store every downstream
+   system's bookkeeping on the owner just to avoid a process Aggregate.
+
+2. **A dedicated process Aggregate** (the DDD shape of a *process manager*) —
+   when the coordination belongs to no existing Aggregate, or the flow needs
+   its own bookkeeping (steps completed, retries, deadline): a small
+   Aggregate (e.g. `OrderFulfillment`) whose state *is* the flow's progress.
+   It reacts to events, issues commands, and its invariants are process
+   rules ("cannot ship before payment is confirmed"). It is an ordinary
+   Aggregate — same aggregate-design worksheet, same Invariants table,
+   events cataloged in `events.md` like any other (Brownfield — see the
+   Edition note). Two boundaries: a process Aggregate **coordinates
+   progress** — it does not pull the participating Aggregates into one
+   transaction or take over their invariants. And do not create one for a
+   two-step event reaction with no compensation, no deadline, and no
+   business-visible progress to answer — keep that as an event chain, or as
+   the owner Aggregate's normal state if it already has one.
+
+3. **An orchestration framework / workflow engine** — the Phase 2+ upgrade,
+   worth it only at operational scale (versioning long-lived in-flight
+   flows, visibility dashboards). Like event sourcing, this is a separate,
+   heavyweight architecture decision: record it as an ADR if genuinely
+   needed; never introduce it as a side effect of modeling.
+
+### Compensation is business behavior, not plumbing
+
+A compensating action is not a rollback — the mail was sent, the money
+moved; they cannot un-happen. Compensation is a **new domain fact**
+(`RefundIssued`, `ReservationReleased`) with its own BR and Given/When/Then
+in `behavior.md`. The failure-path guideline under Event Handling Guidelines
+says *which* final failures must become BRs; this section says *where the
+logic that answers them lives*.
+
+### Deadlines
+
+A deadline is part of the process state. Detecting expiry is infrastructure
+(a scheduled check), but the decision — "expired → release the seats" — is a
+domain rule, expressed as a domain event (`BookingExpired`) and handled like
+any other.
+
+Two search terms, so you can find the literature: *choreography* is a plain
+event chain; *orchestration* means an explicit process owner. These are
+search terms, not a framework choice.
+
 ## Specifications
 
 For complex query logic that belongs to the domain:
@@ -504,6 +677,10 @@ Use Domain Services for operations that:
 - Require external information (through interfaces) to make domain decisions
 - Don't naturally belong to any single Entity
 
+A Domain Service can make a **stateless** cross-Aggregate decision. It is
+not a home for process progress, retries, deadlines, or compensation state.
+When the flow has state, use the "Long-Running Processes" ladder.
+
 ```csharp
 // Domain Service — in Domain layer
 public class ExpenseApprovalService
@@ -641,3 +818,20 @@ The less-obvious three — when to reach for them:
     Aggregates just to display a list / report causes object-graph bloat and N+1
     → Use a read model (denormalized projection / DTO) for the display path; see
     "Read Models (Query Side)"
+
+11. **Compensation logic scattered across event handlers** — Each handler
+    patches state on its own; no one owns the process, and nobody can answer
+    "where is order #123 in the flow"
+    → Give the process a home (a status field on the owning Aggregate or a
+    dedicated process Aggregate); write each compensating action as a BR; see
+    "Long-Running Processes"
+
+12. **Treating recorded design decisions as settled law** — Extending an
+    Aggregate while bending it to fit (a lifecycle-required field turned
+    nullable for a new case, a `Purpose` / `Type` discriminator making one
+    entity carry materially different lifecycles or rules), never re-reading
+    the Design Decisions whose re-evaluation condition the change just
+    triggered
+    → Re-read recorded decisions when extending an existing Aggregate; when a
+    resistance signal fires, name the revision question in the spec (proceed /
+    split / rename, with reason); see "Revising an Established Model"

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

@@ -56,6 +56,10 @@ proceeding (do not flip status, do not archive, do not emit summary).
 - [ ] Every phase-spec file referenced in the Phase Specs table exists at
       the path the table claims
 - [ ] Every phase-spec file's frontmatter has `status: completed`
+- [ ] Every Tier = T2 row in `_index.md` Lightweight Changes references an
+      existing `lightweight-*.md` / `BUG-*.md` file in the feature directory
+- [ ] Every such lightweight / BUG spec file's frontmatter has
+      `status: completed`
 - [ ] `_index.md` has no obvious open items in Resume Pointer (e.g. "phase-N
       drafting" / "implementation pending" / "TODO" markers)
 - [ ] Current BR Snapshot table is non-empty (or feature is intentionally
@@ -66,6 +70,7 @@ If any check fails:
 > found:
 >   ✗ phase-spec-2026-04-15-foo.md status is still `in-progress`
 >   ✗ Phase Specs table row 3 references missing file phase-spec-...
+>   ✗ lightweight-2026-06-20-rounding.md frontmatter status is still `in-progress`
 >
 > Address these (run `/dflow:new-phase` to add missing work, or fix the
 > stale status manually), then re-run `/dflow:finish-feature`."
@@ -93,11 +98,17 @@ branch: feature/{SPEC-ID}-{slug}
 ---
 ```
 
-Also update the **Resume Pointer** to reflect closeout:
+Also update the **Resume Pointer** to reflect closeout — this writes the
+cursor's terminal state (after closeout no workflow is active on this
+feature; do not edit the cursor again after the Step 4 closeout commit):
 
 ```
 **Current Progress**: feature completed ({date}); all phase-specs status = completed.
 **Next Action**: integration — push / merge / PR per the selected Git policy.
+**Active Workflow**: none
+**Current Step**: n/a
+**Gates Passed**: n/a
+**Awaiting**: none
 ```
 
 **→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (status flipped). Entering Step 3: Sync BR Snapshot to BC layer." and continue.
@@ -184,7 +195,8 @@ AI runs:
 ```bash
 git mv dflow/specs/features/active/{SPEC-ID}-{slug} \
        dflow/specs/features/completed/{SPEC-ID}-{slug}
-git status   # confirm rename detection
+git status   # confirm rename detection AND check for `RM` — an `M` next to
+             # a rename means unstaged edits you must re-add before committing
 ```
 
 `git mv` is mandatory — never use plain `mv` + `git add`. This preserves
@@ -193,37 +205,75 @@ PR diff quality stays intact across the move. See
 `references/git-integration.md` § "Directory Moves Must Use git mv" for
 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.
-
 **Closeout commit checkpoint** (completes the offline Local-closeout gate):
 
 ```
-✓ Feature archived to completed/ and closeout files staged
+✓ Feature archived to completed/ and closeout ready to stage
    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.
+Then, in this order:
+
+1. **Record the checkpoint row first.** Write one row in the moved
+   `_index.md` Checkpoint Log — `closeout | committed` for Y, `closeout |
+   skipped` for N. The closeout row carries **no commit hash**: the closeout
+   commit cannot contain its own hash. Trace it later via
+   `git log -1 -- dflow/specs/features/completed/{SPEC-ID}-{slug}` (or the
+   optional `Dflow-Checkpoint` trailer). The "hash only after success" rule
+   still applies to spec / implementation rows — closeout is the documented
+   exception (see `references/git-integration.md` § Commit Checkpoints,
+   Branch Gate & AI Commits).
+2. **Stage the whole archived feature directory:**
+
+   ```bash
+   git add dflow/specs/features/completed/{SPEC-ID}-{slug}
+   ```
+
+   This is required, not optional: `git mv` stages the rename with the
+   **last-committed** content, so working-tree edits made earlier in this
+   flow to the moved files — the Step 2 status flip and Resume Pointer
+   update, plus the checkpoint row you just wrote — stay **unstaged** until
+   this `git add`. In `git status`, the moved `_index.md` showing `RM`
+   instead of plain `R` is exactly this signal. Then also `git add` the
+   files updated in Step 3 (the updated `rules.md`, `behavior.md`,
+   `events.md`, `context-map.md`, `glossary.md`,
+   `architecture/tech-debt.md`, etc.) into the same stage.
+3. **Commit (Y) or stop (N).** For Y the AI commits. If a pre-commit hook
+   rejects it or the commit fails, flip the checkpoint row to `failed` (the
+   row is not committed yet — edit it directly), surface the error, and
+   treat the gate as unsatisfied.
+
+**Post-commit closeout verification** — after a successful commit, and before
+declaring the Local-closeout gate satisfied, AI runs and reports `✓` / `✗` for
+every item:
+
+- [ ] `git show HEAD:dflow/specs/features/completed/{SPEC-ID}-{slug}/_index.md`
+      — one blob read verifying **two** things: frontmatter `status: completed`
+      **and** the Checkpoint Log contains the closeout row. This reads the
+      **committed** content, not the working tree — the former catches "rename
+      carried stale content", the latter catches "row never made it into the
+      commit".
+- [ ] `dflow/specs/features/active/{SPEC-ID}-{slug}/` no longer exists (the
+      directory was moved, not copied)
+- [ ] `git status --short` shows no leftovers related to this feature
+      (working tree clean; identify any unrelated dirty files explicitly)
+
+If any item fails, do **not** declare closeout complete — fix it (re-add and
+amend, or a follow-up commit; the developer chooses) and re-verify.
+
+The Local-closeout gate is satisfied **only when the closeout is committed and
+the verification above passes**. 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 and verified, the gate stands on its own
+offline; integration happens in Step 5 when you have network.
+
+**→ Transition (step-internal)**: Step 4 complete. Branch on the verification result:
+
+- **Closeout commit landed and post-commit verification passed** → announce "Step 4 complete (feature archived; Local-closeout gate satisfied). Entering Step 5: Integration / PR gate." and continue.
+- **Closeout commit was declined (N), failed, or verification reported `✗`** → **stop here.** Announce "Step 4 complete (feature archived), but the Local-closeout gate is not satisfied yet — the closeout is staged but uncommitted, or the committed content failed verification. Commit the staged changes (or fix the failure), then resume to Step 5." Do **not** enter Step 5 with uncommitted or unverified closeout changes.
 
 ## Step 5: Emit Integration Summary (Git-strategy-neutral)
 
@@ -286,10 +336,17 @@ 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}/`.
-> 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."
+> directory is now at `dflow/specs/features/completed/{SPEC-ID}-{slug}/`,
+> with the Local-closeout gate satisfied (closeout committed and verified).
+> Integration — merge / push / PR — follows the selected Git policy, at
+> your discretion."
+
+**In-flight reminder** — after the closeout announcement (with or without
+Step 6), run the in-flight overview scan (see `AI-AGENT-GUIDE.md` § Status /
+Control Commands) and list any other unfinished features in `active/` and any
+in-flight feature / bugfix branches. Surfacing them at closeout is deliberate:
+attention is about to move elsewhere, and this is exactly where half-done work
+sinks.
 
 ## Step 6: Reverse-Update Follow-up Tracking (only if follow-up)
 

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

@@ -43,8 +43,8 @@ bugfix/{BUG-ID}-{slug}
 Examples:
 
 ```
-feature/EXP-001-expense-submission-aggregate
-feature/HR-003-leave-approval-workflow
+feature/SPEC-20260424-002-submit-expense-report
+feature/SPEC-20260430-001-leave-approval-workflow
 bugfix/BUG-042-money-rounding
 ```
 
@@ -149,10 +149,30 @@ existing Step Gate prompt (it does not add a separate question):
 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.
+Checkpoint Log — every checkpoint is accounted for (`committed` / `skipped` /
+`failed`), even when no commit happens. A commit hash is written only after the
+commit succeeds; a hook rejection or failed commit is recorded as `failed`
+(never a fake hash). **Exception — the closeout row**: the closeout commit
+cannot contain its own hash, so the closeout row is written before the commit
+as `closeout | committed` with **no hash** (see
+`references/finish-feature-flow.md` Step 4); trace that commit via
+`git log -1 -- dflow/specs/features/completed/{SPEC-ID}-{slug}` or the optional
+`Dflow-Checkpoint` trailer below. 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.
+
+**Optional machine-greppable trailer.** Teams that want cross-flow checkpoint
+accounting can append a commit trailer at checkpoint commits:
+
+```
+Dflow-Checkpoint: {SPEC-ID} {spec|impl|closeout}
+```
+
+The `_index.md` Checkpoint Log **remains the source of truth**; the trailer is
+a cheap derived mirror (`git log --grep 'Dflow-Checkpoint: {SPEC-ID}'`). Use
+role names, not (k/N) counts — the checkpoint total can change mid-feature
+(tier escalation, follow-ups), and a role gap ("impl exists but no closeout for
+this SPEC-ID") is detectable without predicting N, even across flows.
 
 ### AI commits
 
@@ -312,9 +332,9 @@ with the rule.
 ```
 [SPEC-ID] Short description
 
-[EXP-001] Define ExpenseReport Aggregate with submission invariants
-[EXP-001] Add CreateExpenseReport command and handler
-[EXP-001] Implement persistence configuration for ExpenseReport
+[SPEC-20260424-002] Define ExpenseReport Aggregate with submission invariants
+[SPEC-20260424-002] Add CreateExpenseReport command and handler
+[SPEC-20260424-002] Implement persistence configuration for ExpenseReport
 [BUG-042] Fix rounding in Money value object
 ```
 

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

@@ -178,6 +178,32 @@ Wait for answers.
 > and refreshes it in place on re-run. Merge snippets under
 > `dflow/specs/shared/` are used only if Dflow markers conflict."
 
+Wait for answers.
+
+### Q9. Project-level skill (agent-gated, default yes)
+
+Asked only when Q8 selected at least one agent — with no agents there is no
+projection target and this question is skipped entirely.
+
+> "Install the project-level Dflow skill for natural-language auto-trigger?
+> (Y/n)
+>
+> The skill is what makes requests like 'I want to add a feature' surface the
+> matching workflow automatically; without it, triggering relies on the
+> instruction files alone and degrades in long sessions. Skill files are
+> Dflow-generated derivatives — the recommended default is to gitignore them
+> and re-project after cloning."
+
+Wait for the answer. **Blank defaults to yes.** On `n`, tell the developer:
+
+> "Skipped the project-level skill; add it later with
+> `dflow configure-agents --skills`."
+
+CLI note: the CLI asks this question only on an interactive terminal. A
+non-interactive (piped) `dflow init` never reads an extra stdin answer for it
+— existing scripted answer sequences keep their structure and keep working —
+and installs the skill for the selected agents by default.
+
 **→ Transition (step-internal)**: Step 2 complete. Announce
 > "Step 2 complete (project information captured). Entering Step 3:
 > File-list preview."
@@ -293,7 +319,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 the relevant Step 2 question (Q5–Q8) and re-run Step 3.
+selection, go back to the relevant Step 2 question (Q5–Q9) and re-run Step 3.
 
 ---
 
@@ -367,6 +393,22 @@ For each selected tool-specific file (`AGENTS.md`, `CLAUDE.md`,
   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
 
+If the developer chose to install the project-level skill (Q9), the CLI also
+creates the skill file for each selected tool at its native project-level
+path:
+
+- `.claude/skills/dflow/SKILL.md` — Claude Code
+- `.agents/skills/dflow/SKILL.md` — Codex
+- `.github/skills/dflow/SKILL.md` — GitHub Copilot
+
+All three are the same edition-neutral thin skill projected from the single
+canonical source in the npm package. An existing file at one of those paths
+that is **not** Dflow-generated (missing the
+`<!-- dflow-generated: skill-adapter -->` marker) is left unchanged with a
+warning. Manual AI fallback (no npm available): do **not** hand-write SKILL.md
+content — report that the skill install is deferred and the developer should
+run `dflow configure-agents --skills` once npm is available.
+
 ### 4.4 Directory-only entries
 
 For directories that Git otherwise wouldn't track (empty `active/` /

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

@@ -9,6 +9,8 @@ Triggered by `/dflow:modify-existing` or `/dflow:bug-fix` (or natural language i
 - Step 3 → Step 4 (DDD impact decision → implement)
 - Step 4 → Step 5 (implementation done → update documentation)
 
+Crossing any step gate above also updates the host feature's `_index.md` Resume Pointer cursor (Active Workflow / Current Step / Gates Passed / Awaiting) once the host feature directory exists — fold it into that gate's existing `_index.md` / Resume Pointer edit, no separate ceremony (see the `_index.md` template's Resume Pointer notes).
+
 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.
 
 **Note on step count**: Greenfield edition has 5 steps (Brownfield has
@@ -61,6 +63,16 @@ Walk through these in order:
    this is a new concern. For T1, use `/dflow:new-feature`. For T2 / T3
    on a standalone bug, see Step 1.5 — `/dflow:bug-fix` will create a
    minimal feature directory to host the lightweight-spec.
+4. **In-flight overlap scan (cross-branch)**: this branch's `active/` is not
+   everything in flight. Run the in-flight scan (classification and dedup
+   rules in `AI-AGENT-GUIDE.md` § Status / Control Commands) — `git fetch`
+   when the network allows, then
+   `git branch --all --list '*feature/*' --list '*bugfix/*'` — and also list
+   other unfinished features in this branch's `active/` (one cursor line
+   each). If a scanned branch classified as in flight elsewhere, closed out
+   awaiting integration, or unknown — or an unfinished feature — semantically
+   overlaps this change, surface it and wait for the developer to decide
+   before creating anything new (stale branches are non-blocking).
 
 > **Why scan completed too?** Completed features are frozen history
 > and **cannot accept** any T2 / T3 directly
@@ -237,6 +249,17 @@ Changes that require Aggregate redesign:
 boundary still make sense, or do we need to split/merge?"
 ```
 
+**Established-model re-read.** When the change extends an existing
+Aggregate, re-read that Aggregate's recorded Design Decisions — its
+`aggregate-design.md` worksheet in the feature directory that introduced it
+(usually under `features/completed/`). If this change matches a recorded
+re-evaluation condition ("revisit when …") or trips a model-resistance
+signal, follow `references/ddd-modeling-guide.md` § "Revising an
+Established Model": record one short passage in the spec's Design
+Decisions / Open Questions — proceed as-is, split, or rename, with the
+reason. Deciding to keep the current model, recorded, is a valid outcome;
+extending silently is not.
+
 ### Do we need new Domain Events?
 
 If the behavior change means other parts of the system need to react differently: