dflow-sdd-ddd 0.14.0 → 0.15.0

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

@@ -34,20 +34,45 @@ touches and read them all.
       {reason}." (If you can't, pause and ask the author.)
 - [ ] 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 or a `Tier = baseline` 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 some observation-only records legitimately
+have 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.
+      A **baseline-only** host has none either — a baseline capture writes
+      Domain documents directly and records a `Tier = baseline` row. For both,
+      the requirement is at least one `_index.md` Lightweight Changes row,
+      not a spec file. 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
@@ -55,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):
@@ -63,6 +90,23 @@ PR touches, not just one):
 - [ ] **Business rules covered** — all BR-* rules in this spec
       implemented
 - [ ] **Edge cases handled** — EC-* in this spec addressed
+- [ ] **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: a contract change that touches documented
+      behavior still belongs in `behavior.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
@@ -70,19 +114,267 @@ PR touches, not just one):
 If the closeout commit is in this PR (`/dflow:finish-feature` was run):
 - [ ] **BC layer sync landed** — `dflow/specs/domain/{context}/rules.md` and
       `behavior.md` reflect the feature's net effect (compare against
-      `_index.md` Current BR Snapshot)
+      `_index.md` Current BR 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 baseline capture** — a baseline
+      writes Domain documents directly, so there is no separate sync to land.
+      **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
+      `migration/tech-debt.md` belong to no bounded context, stay in a no-BC
+      host's sweep, and are a baseline capture's own capture destinations, 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, a **`Tier = baseline`** row's capture documents — a capture
+      is **observation-only**, so what it declares is documents, never
+      implementation paths. (A phase-bearing host may legitimately hold a
+      baseline row alongside phase work; `finish-feature-minimal-host.md` says so
+      where it explains why such a host never reaches the zero-phase checks.)
+      **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**, and for a **baseline** row, the absence is the
+      sanctioned state — and for the baseline it is the same hosted exemption
+      that covers a hosted T3, which `templates/_index.md` extends to baseline
+      rows in the same breath. It is not a property of captures.
+      ⚠ 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.**
+      `migration/tech-debt.md` is outside the filter entirely and never appears.
+      ⚠ **A baseline capture is not a no-BC host** and this item does not apply
+      to it: writing Domain documents is exactly what a baseline is for. Closeout's
+      own no-BC check states the same exemption.
 
 If the spec is missing or incomplete:
 ```
 "I notice this PR doesn't have a matching feature directory / _index.md.
-Let's create one retroactively — it'll help with documentation and
-the target architecture. Can you describe what this change does?"
+Can you describe what this change does? If it only records existing
+behaviour or a decision without changing output, it is observation-only
+and tier-exempt — it is captured in whichever Domain documents it
+actually wrote (there is no fixed list) and stops there. It needs no host
+when it is an analysis.md record made with no workflow running and
+committed on its own, or a capture about no bounded context at all; any
+other capture with no active feature to attach it to gets a baseline
+minimal host, whose Tier = baseline row declares the documents it wrote —
+not a spec. 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 appropriate Aggregate / Domain Service
+  row and Notes in `models.md`; when it protects an invariant, update the
+  related `rules.md` entry too. 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,
+  domain `models.md` / `rules.md` / `context.md` / `context-map.md` /
+  `behavior.md`, or `migration/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 `migration/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
 
 - [ ] **No delivery-framework references in Domain** — `src/Domain/` must have zero dependencies on HTTP request/response objects, session/cookie context, job-runner context, CLI flag parsers, or ViewState equivalents
@@ -158,6 +450,7 @@ uses '報銷 (Expense Claim)'. Should we align the naming?"
 
 - [ ] **models.md updated** — New entities/VOs/services documented?
 - [ ] **rules.md updated** — New or changed business rules recorded?
+- [ ] **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.
 - [ ] **context.md boundaries respected** — Does this change stay within its context?
 
 ## Tech Debt Awareness

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

@@ -64,8 +64,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. |
@@ -81,8 +81,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 |
@@ -103,16 +103,36 @@ input like this (supporting files live in the workflow bundle at
 - **"Quick question about..." / "How does X work?"** → check
   `dflow/specs/domain/` first and answer from the documented domain knowledge.
   If no spec exists yet, suggest documenting the answer as 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.
 - **"What should I work on next?" / sprint planning** → review
   `dflow/specs/features/backlog/` and suggest work based on migration value.
 - **"I'm creating a branch"** → read `references/git-integration.md`; verify
-  branch naming and ensure a spec exists before coding starts.
+  branch naming, and make sure the tier's own record exists before coding starts
+  (T1 / T2: a spec; T3: the host `_index.md` row — a T3 branch has no spec file).
 - **"I'm designing a domain model" / "How should I model X?" / building or
   reshaping an Aggregate** → read `references/ddd-modeling-guide.md` (DDD
   tactical patterns: aggregates, invariants, value objects, domain events). It
   is written with Greenfield artifact names; see its **Edition note** for where
   Brownfield records the same decisions (`models.md` / `rules.md` /
   `behavior.md` / `migration/tech-debt.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
@@ -121,10 +141,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
 
@@ -250,6 +278,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` |
@@ -265,10 +295,13 @@ dflow/specs/
 │   └── _conventions.md           # Spec writing conventions
 ├── domain/                       # Domain knowledge (DDD preparation)
 │   ├── glossary.md               # Ubiquitous Language
+│   ├── context-map.md            # Bounded Context relationships (created when needed)
+│   ├── analysis.md               # Cross-context flows and role reach
 │   └── {bounded-context}/        # e.g., expense/, hr/, leave/
 │       ├── context.md            # Context boundary & responsibilities
 │       ├── models.md             # Entity, VO, Aggregate definitions
 │       ├── rules.md              # Business rules index (BR-ID + one-line)
+│       ├── analysis.md           # Lifecycles, derived figures, mechanisms
 │       └── behavior.md           # Consolidated behavior (Given/When/Then)
 ├── features/
 │   ├── active/                   # Currently in development
@@ -297,29 +330,112 @@ dflow/specs/
 ## Ceremony Scaling
 
 Not everything needs full ceremony — match effort to impact. 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, 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 | `/dflow:new-feature` / `/dflow:new-phase` |
-| **T2 Light** | Bug fix, 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 | `/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.
+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` placed in the feature directory + `_index.md` Phase Specs row + refresh BR Snapshot | `/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 | `/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.
 
 **Lightweight spec** = Problem + Expected behavior + 1–2 Given/When/Then. The
 instantiated file is placed inside the feature directory (see
@@ -393,7 +509,8 @@ during the completion checklist, not via template section markers.
 - Did we discover scattered business logic? → Record in tech-debt.md
 - Are there duplicated calculations? → Record
 - Direct SQL in delivery/entrypoint code? → Record
-- Magic numbers or undocumented statuses? → Record and add to glossary
+- Magic numbers? → Record and add to glossary
+- Undocumented status values? → List them in their field's lifecycle in `analysis.md`
 
 ## Workflow Steps
 
@@ -411,7 +528,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` |