dflow-sdd-ddd 0.13.0 → 0.15.0

package/templates/greenfield/references/pr-review-checklist.md

@@ -37,20 +37,42 @@ touches and read them all.
       `/dflow:finish-feature` time)
 - [ ] Only then proceed to the code-review sections below
 
-If the PR has no spec or no `_index.md`:
+If the PR records its change in neither a spec nor an `_index.md` row (a T3
+inline row is such a record, and a host that carries one needs no spec), first
+check whether it only records existing behaviour or a decision in Domain
+documents, without changing output. That PR is observation-only and wants no
+host: answer it with the reply under "If the spec is missing or incomplete" at
+the end of Spec Compliance, not with the one below. For any other PR with no
+such record:
 ```
 "I don't see a feature directory or _index.md for this PR. Before I
-review the code, can you point me to it, or run /dflow:new-feature
-(or /dflow:bug-fix for a small fix) to create the feature directory
-and at least a lightweight spec? SDD relies on the spec being the
-review anchor."
+review the code, can you point me to the host feature? SDD relies on
+the recorded change being the review anchor.
+
+If this change belongs to a feature that already exists, run
+/dflow:modify-existing or /dflow:bug-fix against it — the cascade
+decides what gets recorded (a T2 lands a lightweight spec; a T3 lands
+one inline row in that feature's _index.md and no spec file). If it is
+genuinely new work, run /dflow:new-feature.
+
+If no feature exists to host it at all, that is the standalone case and
+it has a defined route: /dflow:modify-existing opens a minimal
+(zero-phase) host for it — Step 1.7, or Step 1.6's minimal variant when
+the change is a follow-up on a completed feature. Send it there rather
+than inventing a home by hand."
 ```
 
 ## Spec Compliance
 
 Per-feature checks:
 - [ ] **Feature directory exists** with `_index.md` + at least one
-      phase-spec (or one lightweight-spec for a T2-only feature)
+      phase-spec (or one lightweight-spec for a T2-only feature).
+      **Exception — a host whose whole record is inline.** A **T3-only**
+      minimal host has no spec file by design: a T3 never produces one.
+      What it must have instead is at least one `_index.md` Lightweight
+      Changes row. Check for that, and do **not** ask the author to add a
+      spec to satisfy this line — that manufactures the artifact the tier
+      forbids and the flow refuses to write.
 - [ ] **`_index.md` Current BR Snapshot is up to date** — reflects
       the cumulative effect of all phase-specs / lightweight-specs in
       the directory
@@ -58,7 +80,9 @@ Per-feature checks:
       phase-spec file exists and its `status` matches the row's claim
 - [ ] **For follow-up features**: `_index.md` Metadata has `follow-up-of:
       {原 SPEC-ID}` AND the original feature's `_index.md`
-      Follow-up Tracking row references this feature
+      Follow-up Tracking row references this feature. **`follow-up-of` may
+      be a YAML array** — when it names several originals, *each* of them
+      must carry the row; checking the first one is not checking the field.
 
 Per-phase-spec / lightweight-spec checks (run for **each** spec file the
 PR touches, not just one):
@@ -67,6 +91,23 @@ PR touches, not just one):
       Aggregate state transitions and Domain Events)
 - [ ] All business rules (BR-*) in this spec implemented
 - [ ] Edge cases (EC-*) in this spec handled
+- [ ] **No-BR family evidence** — for a lightweight-spec whose Behavior
+      Delta is a `BR:` / `BR Delta:` none line, check that family's
+      evidence instead: (a) `Output Footprint`; (b) `Contract Delta` +
+      `**Downstream consumers**`; (c) `Operational Rationale` +
+      `**Trace**`; (d) `Performance Delta` + `**SLA / resource
+      context**`; (e) `Governing BR-IDs` + root cause + a regression
+      check; (f) `Change Rationale` with `**Before**` / `**After**` +
+      `**Regression**`. The BR / scenario / Domain items above are
+      **N/A** for these specs — record them as N/A rather than passing
+      them on an empty rule set, and never fabricate a BR or a
+      `behavior.md` anchor to make one pass. Domain documents are not
+      automatically N/A: an added event field still belongs in
+      `events.md`. A spec in the
+      classic BR-delta form, or a bug spec with the older single `BR:`
+      line, is accepted as-is. A change matching more than one family
+      must carry **every** matching family's evidence, not just the one
+      its BR line names
 - [ ] **Delta integrity** (phase 2+ only) — the Delta-from-prior-phases
       section's ADDED / MODIFIED / REMOVED / RENAMED entries actually
       match the diff against the prior phase-spec's BR set
@@ -75,11 +116,248 @@ If the closeout commit is in this PR (`/dflow:finish-feature` was run):
 - [ ] **BC layer sync landed** — `dflow/specs/domain/{context}/rules.md` /
       `behavior.md` / `events.md` / `context-map.md` reflect the
       feature's net effect (compare against `_index.md` Current BR
-      Snapshot)
+      Snapshot). **N/A for a no-BC host** — one whose Goals & Scope
+      declares no bounded context has nothing to sync, and a `{context}`
+      document invented to satisfy this line is a fiction, never a pass.
+      ⚠ **Do not read that as "closeout already blocks it" without qualifying
+      where.** Closeout blocks it in the commits it actually reads — checkpoint
+      1, and only on a **minimal** host, plus the closeout commit on any host.
+      A fiction committed by a **phase-bearing** no-BC host anywhere in between
+      passes every closeout check. That range is the *"A no-BC host committed no
+      BC-scoped Domain material"* item in the delegated block below, and it is
+      yours to run. **N/A for a T3**, which does no Domain work at all.
+      Record the N/A rather than ticking it against an empty comparison — but
+      note `glossary.md` and the tech-debt file belong to no bounded context
+      and stay in a no-BC host's sweep, so this N/A does not reach them.
 - [ ] **Whole feature directory `git mv`'d** to `completed/` — git
       shows `renamed:` (not `deleted:` + `new file:`)
 - [ ] **Integration Summary** was emitted to the conversation (not
       written to a file — it's ephemeral)
+- [ ] **Every Lightweight Changes row now carries a `Commit` hash.**
+      Before closeout an empty cell can be legitimate: on a **hosted** row
+      the cell is filled by the host's *next* commit, and closeout is
+      allowed to be that commit. (A **minimal** host is stricter — its rows
+      are written before checkpoint 1, and closeout already refuses an empty
+      cell there.) After closeout there is no next commit, so an empty cell
+      will never be filled. That is why closeout does not assert this for a
+      phase-bearing host, and why it is checkable here.
+      ⚠ **A placeholder is not a hash.** `{hash}`, `{pending}`, `（待 commit）` —
+      anything that is not a resolvable commit — counts as **unfilled**, not as
+      carrying one. It is the harder case to catch precisely because the cell is
+      **non-empty**: every rule downstream is written against empty / non-empty,
+      so a placeholder reads as filled to all of them. Resolve each value
+      (`git cat-file -t {value}`) rather than checking the cell is populated.
+
+**Delegated to review by `finish-feature-flow.md`.** Closeout states at each
+of these sites that it does *not* prove them. They are not optional extras:
+skip one and the boundary is a hole rather than a division of labour.
+
+- [ ] **Whole history — no stray host-open commit.** Closeout validates the
+      hashes the record names and cannot see the rest of the branch. List
+      this branch's commits that touch the host directory:
+      `git log --oneline {base}..HEAD -- 'dflow/specs/features/active/{SPEC-ID}-{slug}/' 'dflow/specs/features/completed/{SPEC-ID}-{slug}/'`
+      For a **minimal (zero-phase) host** there must be exactly two —
+      checkpoint 1 and closeout. A third, typically a host opened in its own
+      commit before the work landed, breaks the two-commit lifecycle while
+      every closeout check still passes, because those read only the hashes
+      the record points at. **This count applies to a minimal host only**: a
+      phase-bearing feature has no fixed number of host commits, so there is
+      nothing to count there and this item is N/A.
+      This is also where closeout's minimal-host **selector** boundary is
+      settled: that selector reads the host's persisted shape today and
+      cannot know it was opened minimal and *stayed* minimal. The commit walk
+      is what shows that.
+- [ ] **Hotfix identity — confirm it against the cited source** (post-hoc
+      host only). Closeout tests **plausibility only**, and says so: which
+      commit was *the* merged hotfix is not derivable from inside the flow,
+      so the developer asserts it and cites what the claim rests on —
+      `hotfix-identity:` beside `hotfix-branch:` in a **T2**'s
+      lightweight-spec frontmatter, or in the row Description for a **T3**.
+      **Open that source** — PR, incident, or tracker — and confirm it names
+      this fix and this commit. Closeout already checked that a citation is
+      *present*; only review can check that it *matches*.
+- [ ] **Hosted `Commit` cell identity — confirm each hash is *that row's own*
+      implementation commit** (phase-bearing host only). `finish-feature-flow.md`
+      Step 4 instruction 1 orders the value ("each row's own implementation
+      hash, never the closeout hash") and its post-commit verification **states
+      that it cannot decide it**: the hash-evidence test is minimal-host-only
+      and lives in `finish-feature-minimal-host.md`, so on a phase-bearing host
+      no closeout check reads the value at all. The presence item above asserts the cell is **non-empty**;
+      this one asserts it is **right**, and the two are not interchangeable.
+      For each Lightweight Changes row, take its `Commit` hash and run
+      `git show --stat {hash}`. **Take the row's declaration if it has one and
+      require the commit to touch it** — a **T2**'s own spec file
+      (`lightweight-*.md` / `BUG-*.md`), a **T3**'s Description implementation
+      paths.
+      **If the row declares nothing, that is by design on a hosted row — with
+      one exception.** A **T2** links to its own spec file on *every* host shape:
+      `finish-feature-flow.md` Step 1 carries two `Tier = T2` checks that no
+      host shape escapes — one of them says so in as many words — and
+      `finish-feature-minimal-host.md`'s phase-bearing exemption note confirms
+      those hosts keep them. A T2 row with
+      no such link is **malformed, not exempt** — find the spec file or flag the
+      row. For a **T3** the absence is the sanctioned state.
+      ⚠ The record then gives you nothing to compare against, and that is
+      deliberate: `finish-feature-minimal-host.md` exempts phase-bearing hosts
+      from its `Commit` cell path check for exactly this reason
+      (`references/flow-rationale-registry.md`, `R-FF-COMMITCELL-02`:
+      "demanding it would reject every hosted T3"), and `templates/_index.md`
+      calls declaring them good
+      practice with no gate behind it. **Do not read "touches nothing declared"
+      as a pass.** What remains checkable is weaker and is worth stating as
+      such: the hash is **not** the closeout commit, is **not** any other row's
+      hash, and is a commit on this host's branch — or on a branch this host
+      recorded a `branch-override` for. Past that, ask the developer which
+      commit carried the row. If identity matters for this change, say so and
+      have the row declare its paths — that is what makes the comparison above
+      available.
+      ⚠ **Do not let tier decide that a declaration must exist.** Tier says what
+      the declaration would have been; the one hosted row required to carry one
+      is a T2, and that requirement lives in Step 1, not here. Keying this check
+      on tier produced three successive versions that each named an input some
+      row was not required to carry.
+      A cell holding the **closeout** hash, or another row's hash, is what this
+      exists to catch: both are non-empty, both pass every closeout check, and
+      neither is what instruction 1 ordered.
+      **N/A for a minimal host** — there `finish-feature-minimal-host.md`'s
+      hash-evidence test already runs (a)–(c) against every row before closeout
+      may proceed.
+- [ ] **A recorded branch override still matches where the closeout landed**
+      (only when the host carries a `branch-override` row). Closeout passes its
+      branch check on any such row naming the branch it ran on, and **states
+      that it cannot decide** whether that override was still the current
+      intent — nothing expires a row once the developer returns to the host's
+      own branch. You can see what closeout cannot: which branch the closeout
+      commit sits on, and whether the work had already been integrated by then.
+      Two cases to reject, both instances of one rule — **the branch this
+      closeout landed on is not where this host's work was finished**: a closeout
+      committed onto the **base** branch *after* the feature branch was merged
+      (that puts the closeout commit outside the review this checklist is part
+      of), and a closeout committed onto a branch an override named earlier but
+      which the work has since **left** — a superseded spike, say. Closeout
+      distinguishes neither, because it accepts any branch this host ever
+      recorded an override for.
+- [ ] **The closeout commit carries only this host's delta.** Closeout's spill
+      check derives its permitted set from Step 4 instruction 2, which defines
+      one for **every** host shape — so there is a permitted-file list to read
+      against on a phase-bearing feature too. What that does not change is what
+      the check proves: it is a **path-level spill check**, so it proves no
+      unpermitted *file* entered the commit, never that the permitted ones carry
+      only this change. An unrelated BR edit inside `rules.md`, or another
+      feature's term in `glossary.md`, passes it untouched. Read each
+      permitted file's diff against the intended delta in the spec / row.
+- [ ] **A follow-up's reverse link was opened, not only closed.** The
+      original's Follow-up Tracking row must have existed as `in-progress`
+      before the flip to `completed` — `absent → in-progress → completed`,
+      never created straight as `completed`. Closeout verifies this for a
+      **minimal** host only, from checkpoint 1's committed blob; a
+      **phase-bearing** follow-up has no single commit required to carry the
+      row, so closeout has nothing equivalent to read and the opening half
+      arrives here unchecked. Confirm it from the branch history
+      (`git log -p {base}..HEAD -- <original feature>/_index.md`), for
+      **each** SPEC-ID in `follow-up-of`.
+- [ ] **A no-BC host committed no BC-scoped Domain material** — **every no-BC
+      host, not only phase-bearing ones.** Closeout inspects only **checkpoint
+      1's** diff on a minimal host, and a phase-bearing host has no single
+      checkpoint to inspect at all. **Neither is a branch-range proof**, and
+      closeout cannot take a range — it needs a base branch and Dflow
+      deliberately does not know yours. **You have it.** Run
+      `git diff --name-status {base}..HEAD -- 'dflow/specs/domain/'` and confirm
+      no BC-scoped Domain document — **the set this track's own no-BC closeout
+      check names**, `context-map.md` included — was **added, modified, deleted
+      or renamed**. A no-BC host is one whose Goals & Scope declares no bounded
+      context, the same identification the BC-layer-sync item above uses.
+      ⚠ **The path filter is deliberately wider than the prohibited set, so read
+      the output before flagging.** `context-map.md` sits at `domain/` top level
+      rather than under `{context}/`, and the filter has to reach up there to
+      catch it — which means it also lists `domain/glossary.md` and
+      `domain/analysis.md`. Both belong to no bounded context and stay
+      legitimate for a no-BC host: **seeing either here is not a finding.** The
+      tech-debt file is outside the filter entirely and never appears.
+
+If the spec is missing or incomplete:
+```
+"I notice this PR doesn't have a matching feature directory / _index.md.
+Can you describe what this change does? If it only records existing
+behaviour or a decision without changing output, it is observation-only
+and wants no host at all — it is captured in the relevant Domain
+document (models.md / rules.md / behavior.md / events.md / analysis.md)
+and stops
+there. Otherwise: if it belongs to a feature we already have, we can
+record it there retroactively — the tier decides what gets written
+(T2: a lightweight spec; T3: one inline _index.md row). If it's
+genuinely new work, it wants /dflow:new-feature. If
+there's no feature it could belong to, that's the standalone case and
+it has a defined route: /dflow:modify-existing opens a minimal
+(zero-phase) host for it — Step 1.7, or Step 1.6's minimal variant when
+it's a follow-up on a completed feature. Let's send it there rather
+than inventing a home by hand."
+```
+
+## Risk-Triggered Modeling Review
+
+Use the spec and diff to identify these risks; do not use a keyword-only scan.
+Only when a signal matches, read the named section in
+`dflow/specs/shared/dflow-workflows/references/ddd-modeling-guide.md`. If no
+signal matches, skip this section's guide lookup, create no artifact, and
+continue with the existing checklist below.
+
+| Risk signal | Read in the modeling guide |
+|---|---|
+| One use case mutates / saves multiple Aggregate roots, or adds a multi-root Unit of Work | Aggregate Design Rules; Domain Services |
+| The diff crosses Bounded Contexts or changes an event payload, handler, or delivery expectation | Domain Events; Event Handling Guidelines |
+| Deadline, retry, out-of-order callback, compensation, business-visible progress, or a claim that local persistence and an external provider / service fact form one atomic outcome | Aggregate Design Rules; Long-Running Processes; failure-path guidance under Event Handling Guidelines |
+| `unique`, `only one active`, or another set-based invariant | Set-Based / Uniqueness Invariants |
+| A Domain Service is added or changed | Domain Services; Long-Running Processes when the flow has state |
+
+For every matched risk, record one disposition in the review:
+
+- **Finding** — identify the violated guarantee at the boundary named by the
+  matched risk, its severity, and merge disposition. For a match involving an
+  external provider / service fact, state that a local transaction cannot make
+  that fact atomic with local state; implementing or repairing a local
+  transaction / Unit of Work alone is not sufficient closure.
+- **Accepted with rationale** — state why the boundary / transaction / service
+  role is sound and when to revisit it. For such an exception, the rationale
+  must already exist or be added to the feature's `aggregate-design.md` Design
+  Decisions; the PR conversation points to that decision and is not its only
+  home. This disposition evaluates the rationale's adequacy, not only its
+  existence: it must explain how it answers every matched risk. For a
+  match involving an external provider / service fact, acknowledge that a local
+  transaction cannot make that fact atomic with local state and explain how the
+  outcome progresses across the boundary, including idempotency and retry /
+  compensation (or a justified equivalent). For a Domain Service match, name
+  the actual domain rule or decision the accepted operation carries; an
+  operation that only orders root calls is Application-layer orchestration and
+  remains a Finding, even when another operation of the same service holds a
+  real rule. If the rationale does not cover the matched risk, use Finding
+  rather than this disposition.
+- **Not applicable** — explain from the spec and diff why the match is only
+  superficial.
+
+Multiple signals for the same design decision may share one disposition, but
+every matched risk must have an auditable disposition. This is not a per-signal
+form.
+
+### Closing a blocking modeling finding
+
+A DDD / domain-correctness blocker must state:
+
+- the code boundary or enforcement needed to restore the guarantee;
+- the existing durable surfaces that must change, as applicable — the spec,
+  `aggregate-design.md`, domain `context-map.md` / `events.md` / `behavior.md`,
+  or `architecture/tech-debt.md`;
+- the automated tests or observable evidence that re-verify the guarantee; and
+- that the unimplemented guarantee must not remain marked `completed` before
+  re-review.
+
+If the review offers defer as an option, it must list the owner, known risk,
+exit criteria, and `architecture/tech-debt.md` landing surface as closure
+conditions. If the team defers the finding, record those items on that surface;
+rationale, a re-evaluation condition, or "future refactor" alone is not
+closure. The reviewer defines the evidence needed to unblock, not the author's
+implementation. Use the existing PR comment / conversation surface; do not
+create a separate review report.
 
 ## Domain Layer Quality
 
@@ -127,6 +405,7 @@ If the closeout commit is in this PR (`/dflow:finish-feature` was run):
       glossary)? Align it. (Judgment call, not a string match.)
 - [ ] **Context boundaries respected** — no reaching into another context's internals
 - [ ] **Domain Events documented** — events.md updated?
+- [ ] **analysis.md updated** — did this change touch a status transition, an ordered cross-context flow, which roles reach a function, or the way a figure is computed? If so, is the matching entry in `analysis.md` updated? Open one Evidence source it cites and confirm it still says what the entry claims. An entry whose Evidence is `inferred` names what its conclusion was drawn from: confirm instead that the conclusion still follows from it. An entry whose Evidence is `assumed` has no source to open: confirm instead that it says what it rests on and that the question of confirming it is recorded where the Evidence convention at the top of `analysis.md` says, and report it as unverified rather than blocking on it.
 - [ ] **Tests cover invariants** — not just happy path
 
 ## Architecture Score

package/templates/greenfield/scaffolding/AI-AGENT-GUIDE.md

@@ -13,6 +13,11 @@ This project uses Dflow for spec-first AI-assisted development.
 | Migration / legacy context | {migration-context} |
 | Prose language | {prose-language} |
 
+<!-- dflow-generated: guide-canonical START -->
+<!-- Everything between these markers is Dflow-managed canonical guide content.
+     `dflow configure-agents` refreshes it in place on upgrade. Put project-specific
+     notes in "## Project Context" above (or outside the markers), not in here. -->
+
 ## Before Editing Code
 
 Do not jump from a request directly to code. First identify the matching
@@ -23,8 +28,8 @@ are not available in the current AI tool:
 
 | Workflow | Use when |
 |---|---|
-| `/dflow:new-feature` | A new user-visible capability or business behavior is requested. |
-| `/dflow:modify-existing` | Existing behavior needs to change. |
+| `/dflow:new-feature` | A genuinely new feature, page, or capability — a **newly created** navigable surface (its own route and its own content tree), a new user-executable domain operation, or a new independently-consumable output. Adding a control to an existing surface — or a menu entry pointing at a route that already exists — is modify-existing. |
+| `/dflow:modify-existing` | Existing behavior or an existing surface changes — including adding a presentation / interaction control (copy button, filter, sort, quick-view) to an existing screen. |
 | `/dflow:bug-fix` | A defect can be described with expected vs actual behavior. |
 | `/dflow:new-phase` | An active feature needs another implementation slice. |
 | `/dflow:finish-feature` | Implementation is complete and needs drift closure. |
@@ -40,8 +45,8 @@ Machine-readable source for rendering tool-specific thin wrappers:
 <!-- dflow-command-registry:start -->
 | id | label | description | arg-hint | scope |
 |---|---|---|---|---|
-| new-feature | /dflow:new-feature | Start a new user-visible feature or business behavior. | feature request | workflow |
-| modify-existing | /dflow:modify-existing | Change existing behavior. | change request | workflow |
+| new-feature | /dflow:new-feature | Start a genuinely new feature, page, or capability (new navigable surface, domain operation, or consumable output). | feature request | workflow |
+| modify-existing | /dflow:modify-existing | Change existing behavior, or add a control to an existing surface. | change request | workflow |
 | bug-fix | /dflow:bug-fix | Investigate a defect described by expected vs actual behavior. | expected vs actual | workflow |
 | new-phase | /dflow:new-phase | Add another implementation slice to an active feature. | feature id or phase goal | workflow |
 | finish-feature | /dflow:finish-feature | Close implementation with drift checks and archived feature state. | feature id | workflow |
@@ -63,7 +68,26 @@ input like this (supporting files live in the workflow bundle at
   `references/ddd-modeling-guide.md`.
 - **"Quick question about..." / "How does X work?"** → check
   `dflow/specs/domain/` first and answer from the documented domain knowledge.
+- **Knowledge that no single context document holds** — an ordered flow that
+  crosses contexts (always the domain-root copy), the lifecycle a status field
+  moves through, a figure computed rather than stored, the mechanism behind a
+  behavior no single rule explains, which roles reach which function (always
+  the domain-root copy), or a spot in one of these that this project keeps
+  working around until a domain decision settles it (in the copy that holds
+  the knowledge it is stuck on) → **record it in
+  `analysis.md`**: `dflow/specs/domain/{context}/analysis.md` when one context
+  owns what it describes, otherwise `dflow/specs/domain/analysis.md`. Create
+  the file from `templates/analysis.md` the first time there is something to
+  record. With no workflow running, offer to commit that record on its own.
 - **"I'm creating a branch"** → read `references/git-integration.md`.
+- **"Why does this rule exist?" / "This rule seems wrong"** → look the rule up in
+  `references/flow-rationale-registry.md`. Grep the rule id when you have one
+  (`grep -E '^R-FF-BRANCH-02:'`), otherwise a **short** fragment of the rule —
+  four to eight words, because the flow files are hard-wrapped and a longer
+  phrase spans a line break. A lookup may return two lines tagged `gf ·` / `bf ·`;
+  take this project's edition, which the workflow bundle's
+  `.dflow-bundle-manifest.json` records in its `edition` field. **Do not read
+  that file whole** — it is a lookup table, not a document.
 - **"Turn the specs into HTML" / "make the specs easier to read"** → run the
   CLI command `dflow render` (a human-readability tool, not a `/dflow:*`
   workflow). It mirrors `dflow/specs/` into a browsable static HTML tree
@@ -72,10 +96,18 @@ input like this (supporting files live in the workflow bundle at
 - **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
   guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
   anything upstream automatically.
-- **Anything else code-related** → assess whether it touches business logic. If
-  it does, use the auto-trigger safety net (suggest the matching `/dflow:*`
-  command and wait for confirmation — see § Workflow Transparency); if not, help
-  directly with no ceremony.
+- **Anything else code-related** → run it through § Ceremony Scaling's ordered
+  cascade rather than a business-logic yes/no. Only the cascade's step 2 sends
+  work outside Dflow, and it is narrower than "not business logic": a display
+  typo, an appearance change, a machine-consumed contract edit, security / CVE
+  work and a deliberate runtime performance change are all tracked. If the
+  cascade lands the request anywhere at or above T3, suggest the matching
+  `/dflow:*` command and wait for confirmation (see § Workflow Transparency);
+  only if it lands below workflow, help directly with no ceremony. If step 0
+  takes it out of the cascade instead — observation-only work — it is neither:
+  say so and record it, do not treat "no tier" as "no ceremony". This applies
+  once you are already reading this guide — what makes a tool load it in the
+  first place is that tool's own trigger configuration, which is narrower.
 
 ## Status / Control Commands
 
@@ -201,6 +233,8 @@ Dflow-owned project documents live under `dflow/specs/`.
 | System overview | `dflow/specs/shared/_overview.md` |
 | Domain glossary | `dflow/specs/domain/glossary.md` |
 | Context map | `dflow/specs/domain/context-map.md` |
+| Domain analysis (cross-context) | `dflow/specs/domain/analysis.md` |
+| Domain analysis (per context) | `dflow/specs/domain/{context}/analysis.md` |
 | Active feature specs | `dflow/specs/features/active/` |
 | Completed feature snapshots | `dflow/specs/features/completed/` |
 | Technical debt | `dflow/specs/architecture/tech-debt.md` or `dflow/specs/migration/tech-debt.md` |
@@ -217,10 +251,12 @@ dflow/specs/
 ├── domain/
 │   ├── glossary.md
 │   ├── context-map.md              # Bounded Context relationships
+│   ├── analysis.md                 # Cross-context flows and role reach
 │   └── {bounded-context}/
 │       ├── context.md
 │       ├── models.md               # Aggregates, Entities, VOs
 │       ├── rules.md                # Business rules index (BR-ID + one-line)
+│       ├── analysis.md             # Lifecycles, derived figures, mechanisms
 │       ├── behavior.md             # Consolidated behavior (Given/When/Then)
 │       └── events.md               # Domain Events catalog
 ├── features/
@@ -250,29 +286,112 @@ dflow/specs/
 
 ## Ceremony Scaling
 
-Dflow uses three tiers — **T1 Heavy / T2 Light / T3 Trivial** — chosen by the AI
-per change. `/dflow:new-feature` and `/dflow:new-phase` always default to T1 (no
-judgement needed). The criteria below apply when `/dflow:modify-existing` or
-`/dflow:bug-fix` decides which tier fits a modification.
-
-| Tier | Scenario | Output | Command / Trigger |
-|---|---|---|---|
-| **T1 Heavy** | New feature, new phase, new Aggregate / BC, architectural change, new BR | Independent `phase-spec-YYYY-MM-DD-{slug}.md` placed in the feature directory + `_index.md` Phase Specs row + refresh BR Snapshot. For a new Aggregate / BC also create an `aggregate-design.md` from `templates/aggregate-design.md` **in the feature directory** (working worksheet; the durable summary stays in `models.md`) + update `context-map.md` + `events.md`. | `/dflow:new-feature` / `/dflow:new-phase` |
-| **T2 Light** | Bug fix (logic error), UI input validation tweak, flow branch change — has BR Delta | Independent `lightweight-{YYYY-MM-DD}-{slug}.md` (or `BUG-{NUMBER}-{slug}.md`) inside the feature directory + `_index.md` Lightweight Changes row (outbound link) + refresh BR Snapshot. Confirm the fix lands in the correct architectural layer. | `/dflow:bug-fix` or `/dflow:modify-existing` (lightweight branch) |
-| **T3 Trivial** | Button colour, copy/text fix, typo, formatting, pure comments — **no BR change, no Domain concept change, no data structure change** | **Inline row in `_index.md` Lightweight Changes only** (no independent spec file) | `/dflow:modify-existing` (`_index-only` branch) |
-
-**T3 criteria** (the AI must satisfy **all four** before classifying T3):
-
-1. No BR-ID change (no ADDED / MODIFIED / REMOVED / RENAMED business rule)
-2. No Domain concept added or changed (Aggregate / Entity / VO / Event)
-3. No data structure change (table, column, relation, index)
-4. Only changes UI surface (colour, text, layout), pure comments, or pure formatting
-
-If any criterion fails → drop to T2; if Domain / BR / data structure is touched → escalate to T1.
-
-**Below T3 — Dflow doesn't track at all**: pure typo fixes, commit-message
-typos, pure formatting commits (e.g. `prettier` / `dotnet format` auto-runs).
-You can `git commit` directly without writing even a T3 inline row.
+Dflow uses three tiers — **T1 Heavy / T2 Light / T3 Trivial** — plus a
+**below-workflow** level Dflow doesn't track at all. `/dflow:new-feature` and
+`/dflow:new-phase` are always T1 (no judgement). For `/dflow:modify-existing`
+and `/dflow:bug-fix`, classify the change with the **ordered cascade — the first
+step that matches wins** (order matters: a later catch-all would otherwise
+swallow the trivial and below-workflow cases):
+
+0. **Scope.** The cascade classifies a *modification*. Genuinely new work — a
+   new feature, page, or capability — is `/dflow:new-feature` (T1), even with no
+   new BR / Domain / schema. Adding a presentation or interaction control to an
+   **existing** surface (copy button, date-range filter, sort control, quick-view
+   drawer / tab, or filling a missing `aria-label`) is a *modification* (stays in
+   the cascade). A new user-executable domain operation (e.g. one-click return), a
+   new independently-consumable output or delivery channel (Download-PDF / export /
+   emailed report), or a **newly created** navigable surface (its own route and its
+   own content tree) **is** new-feature. Adding a menu entry or link that points at
+   a route that already exists is an access control on an existing surface —
+   a modification, not a new surface. **Unit of classification**: classify one
+   coherent requested change. Split a compound request into its atomic changes,
+   run each through the cascade, and let the highest tier govern the whole — each
+   lower-tier part still records its own artifact under the same host. Mechanical
+   fallout you did not ask for (formatter noise, lint churn) neither raises nor
+   lowers the result.
+   **Observation-only work is also outside the
+   cascade**: capturing existing behaviour as a baseline (Brownfield) changes no
+   output, so it carries no tier at all — record it and do not read step 2's
+   "below workflow" as permission to skip the record.
+1. **T1 — Heavy.** A **new** business rule or normative constraint (permission /
+   eligibility / threshold / approval / required outcome — regardless of whether a
+   BR-ID already exists). *New* means a rule that can be stated and broken on its
+   own: take the change away and the original rule still works exactly as before.
+   Changing an existing rule's parameters is **T2** — a different threshold value,
+   or adding to a set the rule already checks (one more allowed country, one more
+   approver role). Adding an independent condition the rule never had (an approver
+   predicate for a specific payment channel) is a new rule, and T1. A Domain concept (Aggregate / Entity / VO / Event)
+   **added or structurally changed** (identity, VO equality components, aggregate
+   boundary, or removing / renaming / redefining a spec-tracked member — a Domain
+   concept **rename** is T1); a persistent **data-structure** change (table /
+   column / relation / index added, removed, renamed, or its type / nullability /
+   constraint / logical definition changed); an **architectural** change
+   (inter-layer dependency direction, deployment / module boundary, runtime /
+   platform ownership, or overturning an architecture decision — behavior-
+   preserving still counts); or a **breaking** cross-consumer contract (API /
+   event). Contracts run **inbound** too — a required env var / deployment config
+   key, a CLI flag, an exit code, a scheduled-automation calling convention. What
+   breaks a caller is T1: removing or renaming one, changing what one means, or
+   adding a **required** key with no backward-compatible default (deployments must
+   act) — making an existing operation's parameter **required** breaks callers the
+   same way. Adding an *optional* key or parameter with a backward-compatible
+   default is non-breaking — T2 via step 4.
+2. **Below workflow — not tracked.** No audience-perceivable output delta **and**
+   no machine-consumed-contract or operational-semantics touch: auto-formatter
+   runs, whitespace, internal comments, internal-doc typos, commit messages, and
+   behavior-preserving **routine** refactors / dependency bumps. **Routine** =
+   touches no operational-semantics axis (security / safety / resilience /
+   compliance / payment) and is not architectural — **breadth is not the test** (a
+   behavior-preserving refactor across hundreds of call sites is still below
+   workflow; a single-file change that touches an operational axis is not). Never
+   below workflow, even when invisible: any BR-ID delta, any machine-consumed
+   structured-log / export / contract change, any deliberate runtime performance /
+   resource / SLA change, or any security / CVE / compliance work — those reach
+   step 1 or 4 by audience. `git commit` directly.
+3. **T3 — Trivial.** A **local, low-risk, meaning-preserving pure copy or
+   appearance change a product audience perceives** — display-text typo / wording
+   polish, colour, spacing, layout polish, or polishing existing alt / ARIA
+   wording — on a **single screen / component or single independently-consumed
+   page / file**, at the **element level**. **Excluded from T3**: high-consequence
+   content (security warnings, password hints, consent, payment / legal notices);
+   meaning-changing appearance (danger / status-colour semantics); anything
+   affecting operability, default state, interaction order, or task completion
+   ("just CSS" is no exemption); adding a **missing** accessible name (compliance
+   remediation); and text a machine consumes — an API error string or code a client
+   parses is contract, not display copy, so it is never T3: route it by the contract
+   axis instead (breaks the consumer → step 1, T1; otherwise → step 4, T2). **Locality is
+   the rendered audience footprint, not the number of source files**: one shared
+   component or localization key whose output appears on several screens is beyond
+   the local unit (T2), while edits to several files that surface in one place stay
+   T3. Anything beyond that unit is T2 — a typo swept across many screens, a
+   whole-screen visual rewrite, a cross-page sweep. The limit follows the whole
+   intent, so splitting one cross-screen typo sweep into per-screen requests does
+   not turn it into several T3s.
+4. **T2 — Light (catch-all — everything else).** Functional / semantic behavior
+   delta (logic, validation, interaction flow, display calculation, an
+   **existing** BR's delta, non-breaking contract semantics); performance-only
+   changes (perceivable or not); and copy / appearance sweeps escalated from step
+   3. Functional bug fixes are T2 (root-cause + regression notes).
+
+| Tier | Output | Command / Trigger |
+|---|---|---|
+| **T1 Heavy** | Independent `phase-spec-YYYY-MM-DD-{slug}.md` in the feature directory + `_index.md` Phase Specs row + refresh BR Snapshot. For a new Aggregate / BC also create an `aggregate-design.md` from `templates/aggregate-design.md` **in the feature directory** (working worksheet; durable summary stays in `models.md`) + update `context-map.md` + `events.md`. | `/dflow:new-feature` / `/dflow:new-phase` — also where a `/dflow:modify-existing` or `/dflow:bug-fix` request goes when the cascade lands it at T1 |
+| **T2 Light** | Independent `lightweight-YYYY-MM-DD-{slug}.md` (or `BUG-{NUMBER}-{slug}.md`) inside the feature directory + `_index.md` Lightweight Changes row (outbound link) + refresh BR Snapshot. Confirm the fix lands in the correct architectural layer. | `/dflow:modify-existing` or `/dflow:bug-fix` — the usual landing for a functional defect |
+| **T3 Trivial** | **Inline row in the host `_index.md` Lightweight Changes only** (no independent spec file) | `/dflow:modify-existing` or `/dflow:bug-fix` (`_index`-only branch — e.g. a defect that is only a display-text typo) |
+
+**Audience** = any human audience of the product perceives the output: UI
+(including alt / ARIA read by assistive tech), email, exports. Public / adopter-
+facing docs (product README, public API reference) and operator surfaces
+(dashboard labels, alerts) are product-audience: pure wording = T3 (single page;
+a cross-page sweep escalates to T2 at step 3), meaning change = T2. Raw internal
+diagnostic logs / traces are internal (copy-only fixes are below workflow).
+Structured logs / machine-readable exports a downstream consumer depends on are
+contract: breaking cross-consumer = step 1 T1, non-breaking = step 4 T2.
+
+**Project conventions can only escalate.** `_conventions.md` Ceremony (Project
+Application) rows are a floor-raising overlay applied *after* the cascade: a
+project may push a T2 up to T1, but may not lower a cascade T1, nor drop a
+tracked class below workflow.
 
 **DDD Modeling Depth (still informs T1 scope)**:
 
@@ -369,7 +488,7 @@ directory first. For example:
 |---|---|
 | `/dflow:new-feature` | `dflow/specs/shared/dflow-workflows/references/new-feature-flow.md` |
 | `/dflow:modify-existing` | `dflow/specs/shared/dflow-workflows/references/modify-existing-flow.md` |
-| `/dflow:bug-fix` | `dflow/specs/shared/dflow-workflows/references/modify-existing-flow.md` (lightweight-ceremony branch) |
+| `/dflow:bug-fix` | `dflow/specs/shared/dflow-workflows/references/modify-existing-flow.md` (same flow; tier comes from the cascade, not from the command) |
 | `/dflow:new-phase` | `dflow/specs/shared/dflow-workflows/references/new-phase-flow.md` |
 | `/dflow:finish-feature` | `dflow/specs/shared/dflow-workflows/references/finish-feature-flow.md` |
 | `/dflow:verify` | `dflow/specs/shared/dflow-workflows/references/drift-verification.md` |
@@ -389,3 +508,5 @@ should stay thin and point back here.
 If a tool does not support Dflow slash commands, treat the command names as
 plain workflow names and follow the matching flow file from the workflow bundle
 at `dflow/specs/shared/dflow-workflows/`.
+
+<!-- dflow-generated: guide-canonical END -->

package/templates/greenfield/scaffolding/CLAUDE-md-snippet.md

@@ -115,7 +115,10 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 1. **Spec Before Code** — 沒有規格就不寫實作
 2. **Domain at the Center** — 業務邏輯只存在於 Domain 層
 3. **Ubiquitous Language** — 使用 `dflow/specs/domain/glossary.md` 中定義的術語
-4. **One Aggregate per Transaction** — 單一操作只修改一個 Aggregate
+4. **One Aggregate per Transaction（default）** — 單一操作預設只修改一個
+   Aggregate；有充分理由的 multi-root local transaction 例外，依
+   `dflow/specs/shared/dflow-workflows/references/ddd-modeling-guide.md`
+   「Aggregate Design Rules」記錄 domain rationale 與 re-evaluation condition
 5. **Dependency Inversion** — Domain 定義介面，Infrastructure 實作
 
 ### Domain Layer Rules (Hard Invariants)
@@ -147,7 +150,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 
 ### AI Collaboration Notes
 
-- 開發者提出任何需求時，先引導建立 spec 和 Aggregate 設計
+- 開發者提出需求時，先用 guide 的 § Ceremony Scaling ordered cascade 判 tier，再依 tier 決定產出：T1 才引導建立 spec 和 Aggregate 設計，T2 用 lightweight spec，T3 在所屬 feature 的 `_index.md` 記一行（沒有 active host 時，`/dflow:modify-existing` 會先開一個 minimal zero-phase host），below workflow 直接做
 - 確認實作順序：Domain → Application → Infrastructure → Presentation
 - 發現業務邏輯在錯誤的層時，指出並建議搬移
 - 每次開發循環結束時，提醒更新術語表、models.md、events.md