dflow-sdd-ddd 0.11.0 → 0.12.0

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/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:

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

@@ -10,6 +10,8 @@ Triggered by `/dflow:new-feature` (or natural language implying a new-feature ta
 - Step 6 → Step 7 (branch ready → start implementation)
 - Step 7 → Step 8 (implementation done → completion)
 
+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 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.
 
 **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).
@@ -31,6 +33,27 @@ Check existing assets:
 - Search `dflow/specs/features/` for related features
 - Check `dflow/specs/domain/glossary.md` and `context-map.md`
 
+**In-flight overlap scan (cross-branch + other unfinished features)** — this
+branch's `dflow/specs/` does not show everything in flight. Run the in-flight
+scan (classification and dedup rules in `AI-AGENT-GUIDE.md` § Status / Control
+Commands):
+
+```bash
+git fetch   # when the network allows; skip gracefully offline
+git branch --all --list '*feature/*' --list '*bugfix/*'
+```
+
+- List other unfinished features already in this branch's `active/` (one
+  cursor line each, from their `_index.md` Resume Pointer).
+- Classify every listed branch by the guide's rules — in flight elsewhere /
+  closed out awaiting integration / stale (completed here) / unknown — do
+  not shortcut the classification. If a branch classified as **in flight
+  elsewhere, closed out awaiting integration, or unknown** has an ID / slug
+  that semantically overlaps this request, surface it and wait for the
+  developer to decide — continue there / integrate it first / treat as
+  related / unrelated — **before creating any new directory, spec, or
+  branch**. Only stale (completed here) branches are non-blocking.
+
 **→ Transition (step-internal)**: Step 1 complete. Announce "Step 1 complete (intake). Entering Step 2: Identify the Bounded Context." and continue.
 
 ## Step 2: Identify the Bounded Context
@@ -96,6 +119,17 @@ Those things form an Aggregate. Everything else is eventually consistent."
 - What entities belong inside this Aggregate?
 - What Value Objects can we extract?
 
+**Established-model re-read (when the feature reuses 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/`) — before extending it. 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
+phase-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.
+
 ### Domain Events
 ```
 "After this happens, what else in the system needs to know?"
@@ -192,7 +226,7 @@ dflow/specs/features/active/{SPEC-ID}-{slug}/
    - Current BR Snapshot: initialise from the first phase's planned BRs
      (will be refreshed when the phase-spec finalises)
    - Lightweight Changes: empty table at start
-   - Resume Pointer: "phase-1 in progress: drafting phase-spec." / "Next Action: finish phase-spec, then implement Domain layer."
+   - Resume Pointer: "phase-1 in progress: drafting phase-spec." / "Next Action: finish phase-spec, then implement Domain layer." / cursor fields: Active Workflow `new-feature`, Current Step `Step 4 — write the spec`, Gates Passed `3→3.5`, Awaiting `none (mid-step)`
 3. **Create the first phase-spec** at `phase-spec-{YYYY-MM-DD}-{slug}.md`
    using `templates/phase-spec.md`. The "Delta from prior phases" section
    is filled with "首 phase，無前置 Delta" (first phase has nothing to

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

@@ -19,6 +19,8 @@ adds a new phase to an in-progress feature only.
 - Step 5 → Step 6 (`_index.md` refreshed → start implementation)
 - Step 6 → Step 7 (implementation done → complete the phase)
 
+Crossing any step gate above also updates the feature's `_index.md` Resume Pointer cursor (Active Workflow / Current Step / Gates Passed / Awaiting) — 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.
@@ -66,6 +68,11 @@ AI must locate the target feature and load its current state:
    - Cross-reference the bounded context's `dflow/specs/domain/{context}/rules.md`
      and `behavior.md` if the new phase is likely to touch system-level
      state (BC-level current state lives there, not in `_index.md`)
+   - Run the in-flight overlap scan (classification and dedup rules in
+     `AI-AGENT-GUIDE.md` § Status / Control Commands): list other unfinished
+     features in `active/` and any feature / bugfix branches whose work is
+     not visible on this branch — if the incoming phase scope overlaps one
+     of them, surface it before writing the phase-spec.
 
 4. **Branch gate — ensure you are on this feature's branch (before any commit)**
 
@@ -99,6 +106,10 @@ Walk the developer through what the new phase covers:
    at the depth set by the BC's Subdomain Type (see
    `references/ddd-modeling-guide.md` § Subdomain-Aware Modeling Depth) — don't
    bypass the classification just because this is a phase, not a new feature.
+   If the phase **extends an existing Aggregate**, apply the established-model
+   re-read from `references/ddd-modeling-guide.md` § "Revising an Established
+   Model" (match recorded re-evaluation conditions; record proceed / split /
+   rename in the phase-spec).
 4. **Cross-context impact?** Does this phase introduce / change Domain
    Events that other contexts consume? (If yes, plan for `context-map.md`
    updates at finish-feature time.)