dflow-sdd-ddd 0.13.0 → 0.15.0

package/templates/brownfield/references/modify-existing-follow-up.md

@@ -0,0 +1,121 @@
+# Step 1.6: Create Follow-up Feature — Brownfield Progressive Extraction
+
+Branch file of `references/modify-existing-flow.md`. It **adds** the
+follow-up-specific rules; it does not restate or override anything in that flow.
+
+**You are here because** that flow's Step 1.6 dispatched you — it owns whether
+this route applies, and what has already been decided by the time you arrive.
+
+Build the follow-up feature using the same machinery as
+`/dflow:new-feature` (see `new-feature-flow.md` Steps 3.5 and 4), with
+these follow-up-specific differences. **Use the tier Part A already decided.**
+This is the same change Part A classified, and re-running the cascade on it can
+return a second answer to one question. Re-enter Part A **only** when the
+Step 1.5 A/B/C discussion materially changed the scope (work added or dropped);
+say so explicitly when you do, and let that re-run **replace** the earlier tier
+rather than stand beside it. On that tier: a **T1** follow-up
+takes the full new-feature machinery below; a **T2 / T3** follow-up — or a
+**baseline capture**, which is **tier-exempt** (observation-only, no cascade
+tier, and reaches here via Part A's observation-only routing rather than the
+Step 1.5 A/B/C prompt) — takes the **minimal (zero-phase) variant** described
+after the reverse-link step, which does **not** delegate new-feature Step 4's
+unconditional first phase-spec. A **post-hoc hotfix** whose host linkage
+Step 1.8 resolved to *follow-up* also arrives here (likewise without the
+Step 1.5 prompt, and always T2 / T3, so always the minimal variant); its
+first checkpoint keeps the `implementation` name but carries Result
+`reconciled (...)` per Step 1.8.
+
+- **New SPEC-ID** (today's date sequence — do NOT reuse the original
+  SPEC-ID): e.g. original `SPEC-20260201-003-訂單折扣` → follow-up
+  `SPEC-20260424-002-訂單折扣-匯率擴充` (or any new slug)
+- **New slug**: not required to equal the original slug; pick whatever
+  best describes the follow-up scope
+- **`_index.md` Metadata**: `follow-up-of: {原 SPEC-ID}` is REQUIRED
+  (uncomment the optional line in the template; can be a YAML array if
+  the follow-up spans multiple originals)
+- **`_index.md` Goals & Scope** auto-prepended note:
+  ```
+  > 本 feature 為 `{原 SPEC-ID}-{原 slug}` 的 follow-up，原 feature
+  > 完成於 `{date}`，詳見 `completed/{原 SPEC-ID}-{原 slug}/_index.md`。
+  ```
+- **`_index.md` Current BR Snapshot baseline** (**BC-bearing follow-up only**):
+  if the follow-up touches a bounded context, AI reads the BC's
+  `dflow/specs/domain/{context}/rules.md` and inherits the BRs that are
+  in-scope for this follow-up. Mark each inherited row with First Seen
+  = `inherited from rules.md` and Last Updated = (empty until the new
+  feature's first phase Delta — or, for a minimal follow-up, its
+  lightweight-spec's delta — touches it). For a **no-BC follow-up** (the
+  minimal variant on a completed no-BC host), leave the Current BR Snapshot
+  **empty** — do not read or fabricate a BC's `rules.md`.
+  **A baseline capture is the other exception**, and it names a real bounded
+  context, so state it rather than leaving it to the BC-bearing rule: a
+  completed-only baseline host is tier-exempt and observation-only — it carries
+  no BR delta, and the capture may be the very thing that creates that BC's
+  `rules.md`. Leave its Current BR Snapshot **empty**, exactly as the
+  no-feature baseline route does (Step 1.7 step 3, "fill it only if the change
+  carries a BR delta"). The capture writes the BC layer directly, so the host's
+  snapshot is not its record and closeout has nothing to sync. **Both baseline
+  routes behave identically here** — lineage decides the host shape, never the
+  snapshot policy.
+
+**Reverse-link into the old `_index.md`**: AI also updates
+`dflow/specs/features/completed/{原 SPEC-ID}-{原 slug}/_index.md` —
+uncomment the Follow-up Tracking section (if not already present) and
+add a row. When `follow-up-of` names **more than one** original (it may be a
+YAML array), do this in **every** one of them; a parent left without its row
+never gets the `absent → in-progress → completed` transition the contract
+requires, and on a **minimal** follow-up host finish-feature Step 1 blocks
+closeout on it (that check is scoped "Minimal host (zero-phase), follow-up
+only" and proves the *opening* half; on a phase-bearing follow-up Step 6 still
+flips and verifies the closing half, but nothing checks that the row was ever
+opened as `in-progress`):
+
+```
+| {新 SPEC-ID} | {新 slug} | {today} | in-progress |
+```
+
+This update is **part of the same change set** as opening the host. For a
+**T1** follow-up the AI may offer to commit the new host and this initial
+`absent → in-progress` reverse-link together (commit message should mention
+"Add follow-up reference to `{新 SPEC-ID}`"). For the **minimal (T2 / T3, or
+baseline) variant** the AI does **not** offer a separate host-open commit — the
+initial reverse-link edit rides along in the first host checkpoint
+(implementation, or `spec-baseline` for a baseline follow-up; see the variant
+paragraph below), keeping the follow-up at exactly two host checkpoints. The reverse link is a derived index — the new feature's
+`follow-up-of` field is the authoritative source.
+
+After a **T1** follow-up feature is set up, this flow hands off to the
+`/dflow:new-phase` flow (or stays in this flow at Step 2 for the first
+phase's content).
+
+**Minimal (zero-phase) follow-up variant (T2 / T3 / baseline).** When the
+follow-up change is itself lightweight — or is an observation-only **baseline
+capture**, which is tier-exempt rather than lightweight and reaches this
+variant from Step 1.6's opening paragraph — do **not** delegate new-feature
+Step 4 (which would create an unconditional first phase-spec). Instead treat
+the follow-up host exactly like a standalone minimal host — open it via
+**Step 1.7's
+mechanics, steps 2–4 only** (assign identifiers + collision check, create the
+minimal `_index.md` with an empty Phase Specs table, branch gate **by change
+class**: `bugfix/BUG-{NUMBER}-{slug}` for a functional bug,
+`feature/{SPEC-ID}-{slug}` otherwise — this **overrides** new-feature's
+hardcoded `feature/` branch). Step 1.7's **step 1 does not apply**: it is the
+standalone-classification gate, and this caller has already been classified as
+a follow-up. Everything Step 1.7 states **after** step 4 *does* apply
+unchanged — every artifact's row written before checkpoint 1, the
+implementation-path declaration, tier-aware "Finalize + close", and the two
+commit-evidence surfaces — because finish-feature reads for all of it on a
+follow-up host exactly as on a standalone one. Then record the change's
+artifacts — a T2 lightweight-spec, one
+or more T3 inline rows, or both for a compound follow-up (Step 1.7's "minimal
+means zero-phase, not one-artifact") — or, for a **completed-only baseline
+capture**, record it per Step 1.7's baseline mechanics (the `spec-baseline`
+checkpoint and a `Tier = baseline` row) — and close with
+`/dflow:finish-feature`. The lifecycle is **two host checkpoints**
+(implementation — or `spec-baseline` for a baseline follow-up — then closeout)
+**plus one post-closeout reverse-link flip tracking commit** — the flip (the original feature's Follow-up Tracking row
+`in-progress → completed`, done by `/dflow:finish-feature` Step 6) is a
+**sanctioned post-completion mutation, not a host checkpoint**, and is
+recorded in **neither** the follow-up host's Checkpoint Log **nor** the
+original feature's. Option C of Step 1.5 ("a follow-up containing only one
+T3 row") lands here.

package/templates/brownfield/references/modify-existing-post-hoc-hotfix.md

@@ -0,0 +1,82 @@
+# Step 1.8: Hotfix T2 / T3 Post-Hoc — Brownfield Progressive Extraction
+
+Branch file of `references/modify-existing-flow.md`. It **adds** the
+post-hoc-specific rules; it does not restate or override anything in that flow.
+
+**You are here because** that flow's Step 1.8 dispatched you — it owns whether
+this route applies, and what has already been decided by the time you arrive.
+
+Sometimes an urgent fix is merged, pushed, and its branch cleaned up
+**before** any Dflow ceremony runs. When you come back to record it,
+declare **post-hoc mode** and reconcile rather than re-implement.
+
+**Admission condition — T2 / T3 only.** This step builds a *minimal
+(zero-phase)* host, so it admits only a post-hoc change Part A classified
+**T2 or T3**. A **T1** post-hoc keeps the normal phase-bearing route
+(`/dflow:new-phase` / `/dflow:new-feature`) and documents the merged work
+there — it is not routed here, and giving it a zero-phase host would be wrong.
+If you arrived here with a T1, go back to Part A's routing.
+
+1. **Host-linkage choice first.** A post-hoc hotfix is **already merged on the
+   mainline**, so no in-flight feature branch can host it: documenting it into
+   an unmerged `feature/...` host would strand the production fix's record on a
+   branch the mainline cannot see — possibly for weeks — and would let that
+   feature's Integration Summary claim work it never did. The hotfix therefore
+   always gets a host of its own, and the only question is whether that host is
+   linked:
+   - **A related completed feature** → run it as a **follow-up** (Step 1.6
+     minimal variant — keep `follow-up-of` and its two reverse-link
+     transitions). A hotfix on a completed feature filed as an unlinked
+     standalone loses its lineage.
+   - **Otherwise** → open a **standalone** minimal host (Step 1.7). "Otherwise"
+     includes *a related feature that is still in flight* — see above for why
+     it cannot be the host.
+
+   Do not skip this choice. If a feature that was in flight turns out to have
+   touched the same code, that is a **merge** question, settled when the
+   branches actually meet — see `finish-feature-flow.md` Step 5.
+2. **Reconcile, do not re-run.** The implementation already happened on the
+   (now often deleted) hotfix branch. Do **not** reopen an implementation
+   branch for it or redo the work. The documentation is recorded on **this
+   host's own branch**, cut by change class at Step 1.7 step 4 (or at Step
+   1.6's delegation to it) like any other minimal host — that branch *is* the
+   **post-hoc branch** the rest of this step names, and the value `_index.md`
+   `branch:` records.
+3. **Implementation checkpoint Result = `reconciled ({merged-hotfix-hash})`.**
+   In the host's Checkpoint Log the implementation row's Result is
+   `reconciled (...)` — the value meaning "this checkpoint documents an
+   already-merged change" — carrying the merged hotfix commit's hash. It sits
+   alongside the usual `committed` / `skipped` / `failed` Results (see
+   `references/git-integration.md` § Commit Checkpoints, Branch Gate & AI
+   Commits). That hash belongs to the **hotfix**, so it is **not** evidence
+   that this host's own first commit landed — the documentation work still owes
+   checkpoint 1 a real commit of its own (item 4), made **before** closeout.
+   Committing the documentation together with closeout collapses the host to
+   one commit and fails finish-feature Step 1.
+
+   **You are asserting this hash, not deriving it.** Nothing in the repository
+   records which commit was the hotfix, so no check in this flow can confirm
+   it — finish-feature's reconciliation gate is explicit that it tests
+   plausibility only. So state the identity
+   and **cite what it rests on**: the PR, incident, or tracker reference that
+   identifies this fix. Record the citation alongside the per-tier trace
+   (item 4). An **uncited** hash blocks closeout —
+   `references/pr-review-checklist.md` is what confirms the identity, and it
+   needs something to confirm against.
+4. **Per-tier trace.** A **T2** records the merged-hotfix branch in its
+   lightweight-spec `hotfix-branch:` field; a **T3** marks its `_index.md`
+   Lightweight Changes row Description as a hotfix (no new field, no T3 spec
+   file). Item 3's identity citation goes in the same place — beside
+   `hotfix-branch:` for a T2, in the row Description for a T3 — so the trace
+   and the thing it rests on stay together. In **both** tiers the host's
+   Lightweight Changes row carries a `Commit` value, and that value is the
+   **post-hoc documentation commit**
+   hash (the row is produced by the documentation work) — **not** the
+   merged hotfix hash, which already lives in the `reconciled (...)` checkpoint
+   above; the two have different provenance and must not be conflated. This
+   row hash is what finish-feature Step 1 reads to prove the documentation
+   commit exists separately from closeout, so fill it in as soon as that
+   commit lands.
+5. **Branch equality** for the host is asserted against the **post-hoc
+   documentation branch** (the `_index.md` `branch:` value), never the deleted
+   hotfix branch.

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

@@ -12,7 +12,7 @@ Crossing any step gate above also updates the host feature's `_index.md` Resume
 
 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).
+**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 (the ordered cascade — T1 / T2 / T3 / below workflow) applies to `/dflow:modify-existing` and `/dflow:bug-fix`; the criteria live in AI-AGENT-GUIDE.md § Ceremony Scaling, and `references/modify-existing-flow.md` is where they are applied.
 
 ## Step 1: Intake — Understand the Request
 
@@ -25,7 +25,26 @@ Ask these questions (naturally, not as a checklist dump):
 
 1. **What's the feature?** Get a plain-language description.
 2. **Who needs it?** Identify the stakeholder or user role.
-3. **Why now?** Understand priority and urgency (affects ceremony level).
+3. **Why now?** Understand priority and urgency.
+
+> **`/dflow:new-feature` is always T1 — it does not re-run the cascade.**
+> Entering here declares "genuinely new work" (a new capability, page, or
+> navigable surface). If the request is really a **modification** of existing
+> behaviour — a tweak, a bug fix, an appearance change, or anything that would
+> land at T2 / T3 / below-workflow — it belongs in `/dflow:modify-existing`,
+> whose Step 1 cascade (step 0) is the only place a misroute is caught. So
+> sanity-check at intake: if this looks like a small change to something that
+> already exists, redirect to `/dflow:modify-existing` rather than minting a T1
+> feature. ⚠ **Do not redirect a request that already came from there.** A
+> `/dflow:modify-existing` or `/dflow:bug-fix` request the cascade landed at T1
+> — including one a project convention escalated to T1, which the overlay may
+> only ever raise — is routed here **by** step 0 and has already been caught;
+> sending it back is a loop, because step 0 provably returns the same answer.
+> `AI-AGENT-GUIDE.md` § Ceremony Scaling's T1 row says so directly. The guard
+> is for a request that arrived at `/dflow:new-feature` **without** passing the
+> cascade. (A follow-up to a *completed* feature is the one new-feature-shaped
+> case that may still be lightweight — it arrives through `modify-existing`
+> Step 1.6's minimal variant, not here.)
 
 Then check existing assets:
 - Search `dflow/specs/domain/` for related concepts
@@ -99,8 +118,11 @@ Walk through these questions:
 - **What are the key nouns?** → Potential Entities or Value Objects
 - **What are the key verbs?** → Potential Domain Services or Entity behaviors
 - **What are the rules/constraints?** → Business Rules to document
-- **What are the states/statuses?** → State machines to model
+- **What are the states/statuses?** → State machines to model, recorded in `analysis.md`
 - **What external data is needed?** → Interfaces to define
+- **What crosses a bounded context, and what does each step hand to the next?** → An ordered cross-context flow (always the domain-root copy)
+- **Which figures are derived rather than stored?** → A read model definition
+- **Who reaches this feature, and what data scope does each role see?** → A role × function entry (always the domain-root copy)
 
 If one concept gathers rules / invariants that must hold together — **a state
 machine over its lifecycle, or invariants spanning several of its fields /
@@ -128,6 +150,8 @@ For each new concept:
 2. Check if it already exists in models.md — extend if needed
 3. If entirely new, add to the appropriate context's models.md
 
+For each of the system-level answers above — the state machines included: record it in `dflow/specs/domain/{context}/analysis.md` when one context owns what it describes and in `dflow/specs/domain/analysis.md` when no one context does, creating the file from `templates/analysis.md` the first time there is something to record. That template's sections carry the notation.
+
 If foundational domain docs are missing, create them from templates before writing content:
 - `dflow/specs/domain/glossary.md` → `templates/glossary.md`
 - `dflow/specs/domain/{context}/models.md` → `templates/models.md`
@@ -137,7 +161,7 @@ If foundational domain docs are missing, create them from templates before writi
 **→ Step Gate: Step 3 → Step 3.5**
 
 Announce to developer:
-> "Domain concepts captured. Before I create any files, let me confirm the SPEC-ID, slug, directory name, and branch name with you (Step 3.5). `/dflow:next` to proceed."
+> "Domain concepts captured. Before I create the feature directory or branch, let me confirm the SPEC-ID, slug, directory name, and branch name with you (Step 3.5). `/dflow:next` to proceed."
 
 Wait for confirmation before entering Step 3.5.
 
@@ -186,7 +210,31 @@ If the developer asks to change the slug, re-propose and re-confirm.
 
 ## Step 4: Write the Spec
 
-Create the **feature directory** + **`_index.md`** + **first phase-spec**:
+> **Minimal hosts do not come here (defensive guard).** Step 4 creates a first
+> phase-spec, which only a genuinely **T1** new feature has. A **minimal host**
+> is zero-phase and is recorded through its own path in `modify-existing-flow.md`,
+> **not here**: Step 1.6 explicitly does **not** delegate to this step. If you
+> reached Step 4 while handling a minimal / zero-phase host, **stop and re-enter
+> `modify-existing-flow.md` at Step 1** — *not* at Step 1.6, 1.7 or 1.8.
+>
+> Those steps each assume work Step 1 has already done: Part A has decided the
+> tier (or routed an observation-only **baseline capture**, which is tier-exempt
+> and has its own two routes), and Part B has done the host linkage. An entry
+> that arrived *here* ran neither, so recovering into one of them skips the
+> authoritative cascade and the completed-feature scan — which is how a change
+> that should have been a follow-up gets archived as an unlinked standalone.
+> Step 1 routes it from there, and its Part B hotfix callout is what sends a
+> **T2 / T3 post-hoc** to Step 1.8 — the only route that attaches `reconciled
+> ({merged-hotfix-hash})`, the identity citation, and the per-tier hotfix
+> trace, all of which a host recovered straight into 1.6 / 1.7 would silently
+> lack. (A **T1** post-hoc is not a minimal host and is not this guard's
+> business.)
+>
+> Either way, do not create a phase-spec, and do not treat this step as a
+> zero-phase execution path.
+
+Create the **feature directory** + **`_index.md`** + **first phase-spec** (T1
+new feature):
 
 ```
 dflow/specs/features/active/{SPEC-ID}-{slug}/
@@ -194,6 +242,8 @@ dflow/specs/features/active/{SPEC-ID}-{slug}/
 └── phase-spec-{YYYY-MM-DD}-{slug}.md
 ```
 
+> **Table-cell formatting**: keep table cells concise — separate multiple short items with `<br>` (never chain them into one line with ；/; separators), and move long narrative detail out of the cell into a document section (full convention: the formatting comment at each spec doc's head).
+
 1. **Create the directory**: `dflow/specs/features/active/{SPEC-ID}-{slug}/`
 2. **Create `_index.md`** using `templates/_index.md`:
    - Metadata: fill `spec-id`, `slug`, `status: in-progress`, `created`, `branch`
@@ -386,7 +436,7 @@ AI reports `✓` / `✗` for every item before touching docs. Items marked *(pos
 - [ ] Every `EC-*` edge case is handled
 - [ ] Domain layer has **no** delivery-framework references (grep `src/Domain/`)
 - [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` contains a section anchor for every `BR-*` introduced by this spec (mechanical input for `/dflow:verify`)
-- [ ] *(post-8.3)* `dflow/specs/domain/{context}/rules.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
+- [ ] *(post-8.3)* for **every `BR-*` this spec introduced or changed**, that rule's row in `dflow/specs/domain/{context}/rules.md` carries a `Last updated` not earlier than this spec's `created` date (mechanical drift guard). ⚠ Quantified per-BR on purpose, like the item above: a T1 may legitimately introduce **no** BR (§ Ceremony Scaling step 0 admits it), and this then passes vacuously rather than blocking. `rules.md` has no document-level `last-updated` — it is a column in the Rule Index, which is what 8.3 sub-step B4 updates.
 
 If any item fails, report the gap and pause — don't proceed to 8.2.
 
@@ -404,13 +454,18 @@ Ask these one-by-one; do not dump all five at once.
 
 ### 8.3 Documentation updates
 
+> **Table-cell formatting**: keep table cells concise — separate multiple short items with `<br>` (never chain them into one line with ；/; separators), and move long narrative detail out of the cell into a document section (full convention: the formatting comment at each spec doc's head).
+
 - [ ] `dflow/specs/domain/glossary.md` — new terms added
+- [ ] `dflow/specs/domain/analysis.md` — ordered cross-context flows, role reach, or anything else no one context owns, that this feature introduced, found or altered; any spot this feature worked around pending a domain decision, in those or in unrecorded knowledge that belongs here; and any open row there this feature settled (created from `templates/analysis.md` the first time there is something to record)
 - [ ] `dflow/specs/domain/{context}/models.md` — model definitions updated
+- [ ] `dflow/specs/domain/{context}/analysis.md` — lifecycles, derived figures or mechanisms no single rule explains this feature introduced, found or altered, in the owning context's copy, which may not be this host's; any spot this feature worked around pending a domain decision, in those or in a rule or unrecorded knowledge that belongs there; and any open row there this feature settled (created from `templates/analysis.md` the first time there is something to record)
 - [ ] `dflow/specs/domain/{context}/rules.md` — business rules updated
 - [ ] `dflow/specs/domain/{context}/behavior.md` — merge completed spec's Given/When/Then scenarios into consolidated behavior. Sub-steps:
       - Promote any Activity 3 (Spec Writing) draft sections (from B3 mid-sync) to formal sections
       - Update the corresponding `rules.md` anchor's `last-updated` date (B4)
 - [ ] `behavior.md` draft cleanup — if the spec was abandoned mid-way, keep the `## 提案中變更` section's history or explicitly REMOVE it
+- [ ] `analysis.md`, at either of its two paths — re-check every entry this feature recorded before building: an entry for what the feature was to add or change against what was built (corrected where the build differs, removed where nothing was built for it), and an entry for something already in the system against the system as it now stands (corrected where this feature changed it, never removed because this feature built nothing for it). Read the entries in the file, not in a diff: a checkpoint may already have committed them.
 - [ ] `dflow/specs/migration/tech-debt.md` — tech debt discovered during implementation recorded
 
 ### 8.4 Archival

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

@@ -59,7 +59,32 @@ AI must locate the target feature and load its current state:
    completed = frozen-history semantic and produces confusing dir-rename
    history. The follow-up path is the only correct route.
 
-3. **Load context for the new phase**
+3. **Refuse if the target is a minimal (zero-phase) host**
+
+   Decide this from the **persisted shape** — the same selector closeout
+   uses: an **empty Phase Specs table and no `phase-spec-*` file** in the host
+   directory. Such a host records a small standalone or follow-up change and
+   is *defined* by carrying no phase. Adding one does not extend it; it turns
+   the host into a phase-bearing feature, and closeout will then check it as
+   one. Refuse with:
+
+   ```
+   "`{SPEC-ID}-{slug}` is a minimal (zero-phase) host — it records a
+   lightweight change and carries no phase-specs, so a phase cannot be
+   added to it.
+
+   If this is genuinely new T1 work, run /dflow:new-feature. If it is
+   another small change, run /dflow:modify-existing — its Step 1 decides
+   the tier and finds or opens the right host for it."
+   ```
+
+   Do NOT create a first phase-spec here to "make the host usable", and do
+   not jump into `modify-existing-flow.md` Step 1.6, 1.7 or 1.8 from here:
+   each of those assumes Step 1's tier decision and host-linkage scan have
+   already run, and entering one directly skips both. Send the developer to
+   Step 1, exactly as `new-feature-flow.md` Step 4's guard does.
+
+4. **Load context for the new phase**
    - Read the feature's `_index.md` — Metadata, Goals & Scope, Phase Specs,
      Current BR Snapshot, Resume Pointer
    - Read the most recent phase-spec to understand where the prior phase
@@ -71,7 +96,7 @@ AI must locate the target feature and load its current state:
      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)**
+5. **Branch gate — ensure you are on this feature's branch (before any commit)**
 
    This phase's commits must land on the active feature's
    `feature/{SPEC-ID}-{slug}` branch. If you are not already on it (you
@@ -111,8 +136,19 @@ Walk the developer through what the new phase covers:
    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. **Data structure impact?** New tables, columns, indices?
-5. **Why now?** Priority — informs sequencing relative to other phases.
+4. **System-level knowledge?** Does this phase add, change, or uncover an
+   ordered cross-context flow (always the domain-root copy), the lifecycle a
+   status field moves through, a figure computed rather than stored, a
+   mechanism no single rule explains, or which roles reach a function (always
+   the domain-root copy) — or work around a spot in one of them that only a
+   domain decision will settle (in the copy that holds the knowledge it is
+   stuck on)? If yes, record it in
+   `dflow/specs/domain/{context}/analysis.md` when one context owns what it
+   describes and in `dflow/specs/domain/analysis.md` when no one context does,
+   creating the file from `templates/analysis.md` the first time there is
+   something to record.
+5. **Data structure impact?** New tables, columns, indices?
+6. **Why now?** Priority — informs sequencing relative to other phases.
 
 This is also the moment to ask: "Should this be its own follow-up feature
 instead of a phase here?" — useful when the scope drift suggests a
@@ -123,7 +159,7 @@ separate concern.
 ## Step 3: Phase Slug Confirmation
 
 AI proposes the new phase-spec filename and asks the developer to confirm
-before any file is written.
+before the phase-spec is written.
 
 > "Proposed phase-spec for `{SPEC-ID}-{slug}`:
 >
@@ -165,6 +201,8 @@ frontmatter `status` to `in-progress`. Phase-2-onward specs **must** fill
 in the **Delta from prior phases** section (the first phase typically has
 just "首 phase，無前置 Delta"; this is phase 2+, so the section is required).
 
+> **Table-cell formatting**: keep table cells concise — separate multiple short items with `<br>` (never chain them into one line with ；/; separators), and move long narrative detail out of the cell into a document section (full convention: the formatting comment at each spec doc's head).
+
 Walk the developer through each section, in the same way `new-feature-flow`
 Step 4 does — Behavior / Business Rules / Delta / Edge Cases — but only
 list NEW or MODIFIED BRs in Business Rules; UNCHANGED BRs from prior phases stay
@@ -195,6 +233,8 @@ Wait for confirmation before entering Step 5.
 
 Update the feature's `_index.md`:
 
+> **Table-cell formatting**: keep table cells concise — separate multiple short items with `<br>` (never chain them into one line with ；/; separators), and move long narrative detail out of the cell into a document section (full convention: the formatting comment at each spec doc's head).
+
 1. **Phase Specs table** — add a new row for this phase:
    ```
    | {N+1} | {YYYY-MM-DD} | {phase-slug} | in-progress | [phase-spec-{date}-{phase-slug}.md](./phase-spec-{date}-{phase-slug}.md) |
@@ -247,6 +287,14 @@ During implementation, continuously verify:
 - [ ] Domain code has no delivery-framework dependency
 - [ ] Data access changes do not introduce business rules into infrastructure
 - [ ] Test failures have been resolved or explicitly recorded as follow-up
+- [ ] Every entry Step 2 recorded in `analysis.md`, at either of its two
+      paths, still holds. An entry for what this phase was to add or change
+      matches what it built — corrected where the build differs, removed
+      where nothing was built for it. An entry for something Step 2
+      uncovered in the existing system matches the system as it now stands —
+      corrected where this phase changed it, never removed because this
+      phase built nothing for it. Read the entries in the file, not in a
+      diff: a checkpoint may already have committed them.
 
 If implementation changes the agreed Delta, update the phase-spec before
 continuing. Do not let code and spec diverge silently.
@@ -283,8 +331,10 @@ Update the feature artifacts:
      feature is ready to wrap up"
 
 System-level domain docs, migration debt sync, and the feature directory move
-to `completed/` remain `/dflow:finish-feature` responsibilities. Do not sync
-system-level current state or archive the whole feature from `/dflow:new-phase`.
+to `completed/` remain `/dflow:finish-feature` responsibilities; Step 2 records
+into `analysis.md` directly, at whichever of its two paths the entry belongs
+to. Do not sync any other system-level current state or archive the whole
+feature from `/dflow:new-phase`.
 
 After completion, summarize for the developer:
 > "Phase {N+1} is implemented and marked completed. `_index.md` is refreshed.