dflow-sdd-ddd 0.13.0 → 0.15.0

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

@@ -2,10 +2,13 @@
 id: BUG-{NUMBER}    # bug-type T2 only; a non-bug T2 (lightweight-{date}-{slug}.md) carries no id — the filename identifies it
 title: {簡述問題}
 status: in-progress    # in-progress | completed
-bounded-context: {ContextName}
+bounded-context: {ContextName}    # or `none` when the host has no meaningful bounded context
 created: {YYYY-MM-DD}
-branch: bugfix/BUG-{NUMBER}-{slug}
+branch: bugfix/BUG-{NUMBER}-{slug}    # must equal the host _index.md `branch:` value (that field is authoritative) — a non-bug T2 therefore carries the host's feature/{SPEC-ID}-{slug} branch
+# hotfix-branch: hotfix/{name}    # ADD (uncomment) only for a post-hoc T2 — references/modify-existing-flow.md Step 1.8. The already-merged emergency fix's own branch, kept even after that branch was deleted.
+# hotfix-identity: {PR / incident / tracker reference}    # ADD only for a post-hoc T2 — the source the asserted `reconciled ({merged-hotfix-hash})` identity rests on; an uncited hash blocks closeout. Keep it adjacent to hotfix-branch.
 ---
+<!-- dflow-shape: brownfield/lightweight-spec.md 1 — keep this line: dflow doctor reads it -->
 
 <!--
 Template note (for AI):
@@ -16,7 +19,7 @@ Template note (for AI):
   - T1 Heavy → use templates/phase-spec.md instead
   - T2 Light → THIS template; produces an independent file
   - T3 Trivial → no independent file; just one inline row in _index.md
-                 Lightweight Changes with a tag like [cosmetic] / [text] / [format]
+                 Lightweight Changes with a tag like [cosmetic] / [text] / [appearance]
 
   Instance file location and naming:
     Place the instantiated file inside the corresponding feature directory:
@@ -24,17 +27,136 @@ Template note (for AI):
     or, when the lightweight change is a tracked bug:
       dflow/specs/features/active/{SPEC-ID}-{slug}/BUG-{NUMBER}-{slug}.md
 
-    If the change is a standalone bug not yet attached to any existing
-    feature, /dflow:bug-fix must first create a feature directory (with a
-    minimal _index.md) before placing the lightweight-spec instance inside.
-    This keeps the structure invariant: every spec file lives under some
-    feature directory.
-
-  After finalizing this lightweight-spec, AI must:
+    A standalone change not yet attached to any existing feature needs a
+    minimal host feature directory (with a minimal _index.md) to hold this
+    instance — the structure invariant is that every spec file lives under
+    some feature directory. That minimal host has a defined create / record /
+    close-out lifecycle: references/modify-existing-flow.md Step 1.7 for a
+    standalone change, or its Step 1.6 minimal variant when the change is a
+    follow-up on a completed feature; a post-hoc hotfix reaches the same
+    lifecycle through Step 1.8, which resolves its linkage to one of those two.
+    Follow that lifecycle rather than
+    improvising one, and do not leave an empty host behind.
+
+  No-BR variants (a T2 that carries no BR delta at all):
+    The default shape below is the classic BR-delta form (Behavior Delta with
+    BR-NN entries + Root Cause). It stays valid and is the right shape whenever
+    the change does have a BR delta.
+    A change can reach T2 carrying no BR delta at all. These families describe
+    how to write a spec the cascade has ALREADY placed at T2; none of them
+    makes a change T2, and none of them overrides an earlier cascade step. Do
+    NOT invent a BR-NN and do NOT write a fake root cause. Pick the matching
+    family, put its BR line under `## Behavior Delta` in place of the
+    ADDED / MODIFIED / REMOVED / RENAMED subsections, and replace `## Root Cause`
+    with that family's evidence section:
+
+    (a) presentation — any copy / appearance change T3 would not take: a sweep
+        beyond the local unit, a whole-screen rewrite, a local edit to
+        high-consequence content (a security warning, a password hint,
+        consent text, a payment or legal notice), or one that changes what the output *means* (an
+        instruction reversed from "company email only" to "any email", a
+        danger / status colour flipped)
+        BR line: `BR: none — presentation`
+        Evidence: `## Output Footprint` — which screens / outputs the change
+        actually reaches, and **what it now says or signals** whenever the
+        meaning moved or the content is high-consequence
+    (b) contract change — non-breaking structured-log / export / API / event
+        field or semantics change
+        BR line: `BR: none — contract change`
+        Evidence: `## Contract Delta`, including a `**Downstream consumers**:`
+        line naming who reads it
+    (c) operational — CVE / security dependency bump, or a behavior-preserving
+        refactor on an auth / payment / resilience / compliance path
+        BR line: `BR: none — operational`
+        Evidence: `## Operational Rationale`, including a `**Trace**:` line
+        (advisory / ticket / audit reference; a self-initiated case with nothing
+        to cite records `**Trace**: none — self-initiated` — the line is never
+        omitted)
+    (d) performance — a runtime performance / resource / SLA change, including
+        one no audience perceives
+        BR line: `BR: none — performance`
+        Evidence: `## Performance Delta`, including an
+        `**SLA / resource context**:` line
+    (e) implementation defect — the rule is unchanged; the implementation was
+        wrong
+        BR lines: `BR Delta: none — implementation defect` AND
+        `Governing BR-IDs: {BR-NN, BR-NN | none}`
+        Evidence: keep `## Problem` / `## Root Cause` / `## Fix Approach`, plus a
+        regression task
+    (f) intentional change — a planned, non-normative functional or interaction
+        change with no rule in the catalogue (default tab, redirect target,
+        ordering, a presentation / interaction control)
+        BR line: `BR: none — intentional change`
+        Evidence: `## Change Rationale`, including `**Before**` / `**After**`
+        behavior lines and a `**Regression**:` line
+
+    More than one family can fit — a behaviour-preserving payment-retry refactor
+    that also shifts runtime SLA is both (c) and (d). Do not pick one and drop
+    the other's evidence: write the BR line of the family with the higher
+    consequence (order: (e) → (c) → (b) → (d) → (f) → (a)) and include **every**
+    matching family's evidence section. A reviewer needs the operational trace
+    and the SLA context, not whichever one the author chose first.
+
+    Family (e) keeps two fields on purpose: "no BR delta" is not "no governing
+    rule". `Governing BR-IDs:` lists the rules the defect sits under, so the rule
+    the fix answers to stays traceable; a genuinely uncatalogued defect records
+    `none`. Never collapse the pair into a single `BR: none`.
+    Family (f) is non-normative only. A new normative constraint (permission /
+    eligibility / threshold / approval / required outcome) is a new BR — take it
+    back to the cascade rather than filing it here, even when the catalogue has
+    no BR-ID for it yet.
+
+    Legacy shapes are accepted, never migrated. Readers and gates take both the
+    classic BR-delta form and the older single `BR:` line bug form (written
+    before the `BR Delta:` / `Governing BR-IDs:` split) as they are; leave
+    existing specs alone and use the shapes above for new ones.
+
+  After drafting this lightweight-spec, AI must:
     1. Add an outbound-link row to the feature's _index.md Lightweight Changes table
-       (Tier = T2; description includes the link to this file)
+       (Tier = T2; description includes the link to this file).
+       TIMING — do this BEFORE the implementation commit, not after. On a
+       minimal (zero-phase) host the row must already be inside checkpoint 1,
+       and closeout's allow-list admits only the row's `Commit` cell
+       afterwards, so a row added later blocks. "Drafting", not the Step 1.7
+       "Finalize + close" sub-step, which runs after that commit and only fills
+       the cell in.
     2. Refresh the feature's _index.md Current BR Snapshot table to reflect
        any BR ADDED / MODIFIED / REMOVED / RENAMED in this lightweight-spec
+       (a no-BR family has nothing to refresh — leave the snapshot as it is)
+
+  Implementation Paths:
+    The `## Implementation Paths` section below names the source paths this
+    change touches. Paths, not a diff — enough to compare a commit against.
+    REQUIRED on a minimal (zero-phase) host — standalone or follow-up:
+    `/dflow:finish-feature` asserts that checkpoint 1's diff touches them, so a
+    spec declaring none leaves that check nothing to compare and a missing
+    declaration BLOCKS closeout rather than passing vacuously
+    (references/finish-feature-flow.md Step 1; written at
+    references/modify-existing-flow.md Step 1.7, before the first commit).
+    On a HOSTED T2 — one recorded under a phase-bearing feature — closeout runs
+    no such check and nothing blocks on it, so the section is good practice
+    there, not a gate. Do not read the "blocks" above as applying to a hosted
+    spec; it does not.
+    Keep the paths OUT of `## Implementation Tasks`: the completion checklist
+    may collapse or remove that section once the tasks are done, and the paths
+    must still be readable at closeout.
+
+  Post-hoc hotfix fields — T2 only, references/modify-existing-flow.md Step 1.8:
+    `hotfix-branch:` records the already-merged emergency fix's own branch
+    (keep the value even when that branch has been deleted); `hotfix-identity:`
+    cites what the identity claim rests on — the PR, incident, or tracker
+    reference. Both live in the frontmatter, adjacent, so the trace and the
+    thing it rests on stay together. They ship COMMENTED OUT: an ordinary
+    (non-post-hoc) T2 leaves them commented and they are inert. Uncomment them
+    only in post-hoc mode — never fill them with `none`, and never leave them
+    live on an ordinary T2, which would claim a hotfix branch that never
+    existed on a record nothing else re-checks.
+    In post-hoc mode `## Implementation Paths` names the paths the MERGED
+    HOTFIX touched: closeout compares them against the `reconciled ({hash})`
+    commit, and blocks if this host's own documentation commit touches any of
+    them (that would be re-implementation, not reconciliation). Closeout tests
+    plausibility only and blocks on an uncited hash; the identity itself is
+    confirmed by references/pr-review-checklist.md.
 -->
 
 # {問題簡述}
@@ -46,6 +168,8 @@ Template note (for AI):
 ## Behavior Delta
 
 > 精簡 delta 格式：bug fix 多數只需 MODIFIED；若確實是新增規則可改用 ADDED、移除用 REMOVED、改名用 RENAMED。多項變更時照類別列。
+>
+> 完全沒有 BR delta 時改用 no-BR 家族形（見檔首 Template note 的 No-BR variants）：本段只留該家族的 BR 行（例如 `BR: none — presentation`；家族 (e) 是 `BR Delta:` + `Governing BR-IDs:` 兩行），不要為了填滿 delta 子段捏造 BR-NN。
 
 ### MODIFIED - behavior modified in this fix
 #### Rule: BR-NN {規則名稱}
@@ -58,12 +182,31 @@ Template note (for AI):
 
 ## Root Cause
 
+> classic BR-delta 形與 no-BR 家族 (e) 保留本段；家族 (a)–(d)、(f) 以該家族的 evidence 段取代本段（見檔首 Template note 的 No-BR variants）。
+
 {為什麼會這樣？是邏輯錯誤？資料問題？還是需求理解有誤？}
 
 ## Fix Approach
 
 {怎麼修？有沒有抽到 Domain 層的機會？}
 
+## Implementation Paths
+
+> The source paths this change touches — paths, not a diff, at a granularity a
+> commit can be compared against. **Required on a minimal (zero-phase) host**:
+> `/dflow:finish-feature` asserts checkpoint 1's diff touches them, and
+> declaring none **blocks** closeout instead of passing. On a **hosted** T2 —
+> recorded under a phase-bearing feature — closeout runs no such check, so this
+> is good practice there rather than a gate. Do not move the list into
+> `## Implementation Tasks`: that section may be collapsed once the tasks are
+> done, and these paths must still be readable at closeout.
+>
+> **Post-hoc hotfix (Step 1.8)**: list what the **already-merged hotfix**
+> touched. This host's own documentation commit must **not** touch any of them.
+
+- `{src/path/touched}`
+- `{src/another/path/touched}`
+
 <!-- dflow:section implementation-tasks -->
 ## Implementation Tasks
 

package/templates/brownfield/templates/models.md

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

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

@@ -7,6 +7,7 @@ created: {YYYY-MM-DD}
 author: {developer-name}
 branch: feature/{SPEC-ID}-{slug}
 ---
+<!-- dflow-shape: brownfield/phase-spec.md 1 — keep this line: dflow doctor reads it -->
 
 <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
@@ -17,7 +18,14 @@ Template note (for AI):
   This is the **phase-spec** template - one phase-spec captures one full
   "Kickoff -> Domain -> Design -> Build -> Verify" cycle inside a feature directory.
   A feature can have 1..N phase-specs; the feature-level dashboard lives in
-  the sibling `_index.md` (see templates/_index.md). The instance file name is
+  the sibling `_index.md` (see templates/_index.md).
+  Exception — a **minimal (zero-phase) host** has **0**: it records a small
+  standalone or follow-up change and is defined by carrying no phase-spec at
+  all (references/modify-existing-flow.md Step 1.7, or its Step 1.6 minimal
+  variant). Such a host never uses this template. If you are about to create a
+  phase-spec for one, stop: adding a phase makes it a phase-bearing feature,
+  and closeout will then check it as one.
+  The instance file name is
   `phase-spec-YYYY-MM-DD-{slug}.md` placed at
   `dflow/specs/features/active/{SPEC-ID}-{slug}/`.
 

package/templates/brownfield/templates/rules.md

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

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

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

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

@@ -76,10 +76,10 @@ never cross:
    BR-ID in `rules.md` and a scenario in `behavior.md`; `/dflow:verify` works
    the same. What shrinks is the *domain model's thickness*, not the spec's
    existence.
-2. **The Tier system is unchanged.** A bug fix in a generic context is still a
-   T2; a new feature still runs the flow. Subdomain governs *how deep to model
-   a context*; Tier governs *how much ceremony a single change needs* — they
-   are orthogonal.
+2. **The Tier system is unchanged.** A bug fix's tier is whatever the cascade
+   decides by the change itself (T3 / T2 / T1), not by the subdomain; a new
+   feature still runs the flow. Subdomain governs *how deep to model a context*;
+   Tier governs *how much ceremony a single change needs* — they are orthogonal.
 3. **Criticality is not downgraded.** Security, tests, SLA, audit,
    permissions, and data integrity do **not** drop with the subdomain type —
    auth or notifications can be generic *and* mission-critical. Generic lowers
@@ -119,9 +119,14 @@ or value objects directly.
 1. **Protect invariants** — The Aggregate exists to enforce business rules that span
    multiple objects within it.
 
-2. **One Aggregate per transaction** — A single operation should modify only ONE
-   Aggregate. If you need to modify two Aggregates, use Domain Events for eventual
-   consistency.
+2. **One Aggregate per transaction — by default** — A single operation should
+   normally modify one Aggregate. If it appears to need multiple roots, first
+   challenge whether the boundary is wrong and whether Domain Events with eventual
+   consistency can separate the work. If a multi-root local transaction remains
+   justified, record the domain rationale, the shared atomic boundary / operational
+   coupling, and when to re-evaluate the choice. A local database transaction cannot
+   make an external provider or service fact atomic with local state; that workflow
+   still needs idempotency plus reliable delivery / retry or compensation.
 
 3. **Reference other Aggregates by ID only** — Never hold a direct object reference
    to another Aggregate. Store its ID instead.
@@ -479,9 +484,10 @@ the values that changed — not a snapshot of the whole Aggregate.
   event** decision (record the Delivery expectation in `events.md`; Brownfield —
   see the Edition note) and treat
   the payload as a published contract: add fields if you must, never change
-  their meaning. Ceremony-wise, extending an event payload that crosses
-  contexts is a T1 contract change (see the ceremony examples in
-  `_conventions.md`).
+  their meaning. Ceremony-wise it follows the contract axis of the ordered
+  cascade — classify the change in AI-AGENT-GUIDE.md § Ceremony Scaling, which
+  is where breaking versus non-breaking and the resulting tier are decided; a
+  project's own `_conventions.md` may escalate from there.
 
 ### Event Flow
 
@@ -673,13 +679,19 @@ build. (Read model ≠ event sourcing.)
 ## Domain Services
 
 Use Domain Services for operations that:
-- Involve multiple Aggregates (read-only access to the second Aggregate)
+- Require a domain decision spanning information from multiple Aggregates
+  (read-only access by default)
 - Require external information (through interfaces) to make domain decisions
 - Don't naturally belong to any single Entity
 
-A Domain Service can make a **stateless** cross-Aggregate decision. It is
-not a home for process progress, retries, deadlines, or compensation state.
-When the flow has state, use the "Long-Running Processes" ladder.
+A Domain Service expresses a **stateless domain operation or decision** and may
+read multiple Aggregate roots. A justified multi-root mutation is rare rather
+than automatically invalid: it must trigger a boundary / transaction review and
+the service itself must carry a real domain rule or decision. A service that only
+orders calls to multiple roots is Application-layer orchestration in the wrong
+place. A Domain Service is not a home for process progress, retries, deadlines,
+or compensation state. Application code owns ordinary workflow sequencing; when
+the flow has business-visible state, use the "Long-Running Processes" ladder.
 
 ```csharp
 // Domain Service — in Domain layer
@@ -791,8 +803,13 @@ The less-obvious three — when to reach for them:
 4. **Business logic in Infrastructure** — Rules in SQL queries or EF configurations
    → Domain defines WHAT, Infrastructure defines HOW
 
-5. **Direct cross-Aggregate modification** — One command modifying two Aggregates
-   → Use Domain Events for the second Aggregate
+5. **Unreviewed direct cross-Aggregate modification** — One command modifies
+   multiple Aggregate roots without challenging the boundaries or recording why
+   one local transaction is justified
+   → Prefer Domain Events and eventual consistency; if the local-transaction
+   exception is justified, record the rationale and re-evaluation condition from
+   Aggregate Design Rule 2. External provider / service facts are never atomic
+   with the local database transaction.
 
 6. **Set-based invariant guarded only in memory** — A "unique" / "only one active"
    rule enforced solely by an in-app check, with no DB unique constraint or

package/templates/{greenfield → common}/references/dflow-feedback-flow.md

@@ -77,7 +77,8 @@ Allowed evidence:
 - Dflow command name
 - Dflow version if known
 - Template or reference file name
-- Generic project type, such as "existing legacy presentation-framework app"
+- Generic project type, such as "existing legacy presentation-framework app" or
+  "new internal service"
 - Minimal paraphrased symptom
 - Short sanitized snippets from Dflow-owned files
 

package/templates/common/references/flow-rationale-registry.md

@@ -0,0 +1,130 @@
+# Flow Rationale Registry
+
+Why the rules in the workflow flow files and templates are shaped the way they
+are. One entry per physical line, so one lookup returns the whole answer:
+
+```bash
+grep -E '^R-FF-BRANCH-02:' references/flow-rationale-registry.md
+```
+
+**Do not read this file whole.** It is a lookup table, not a document. Nothing
+here is needed to execute a flow. Look up an entry when a developer asks why a
+rule exists, or says a rule looks wrong.
+
+Every line reads `<id>: [<edition ·>? <file> · <step or section> · <the rule it
+belongs to>]` followed by the reason, so a keyword search finds the line when
+you do not have an id. **Search a short fragment — four to eight words — not a whole sentence.**
+The flow files are hard-wrapped, so most sentences there span a line break and
+carry an indent that this file's single long lines do not have; a long phrase
+copied out of a flow file will therefore match nothing here.
+
+**Do not add `-m 1`.** A bracket that opens with `gf ·` or `bf ·` applies to
+that edition only — usually one line per edition of the same rule, sometimes a
+rule only one edition has. A bracket with no edition marker applies to both. So
+a lookup can legitimately return two lines: read the one matching this project's
+edition, which the workflow bundle's own `.dflow-bundle-manifest.json` records
+in its `edition` field. Taking only the first would hand a Brownfield project
+the Greenfield answer — the `gf ·` line is always first.
+
+**Reviewers and future maintainers: read this before concluding that a check is
+under-specified.** Several of these rules look loose on their own and are
+bounded deliberately, with the boundary recorded here.
+
+## finish-feature-flow.md
+
+R-FF-MINSEL-01: [finish-feature-flow.md · Step 1 · What "Minimal host (zero-phase) only" selects, and what that does not prove] The routing rules are what keep the two apart in practice: a T1 never records into a minimal host, and a sealed minimal host cannot take anything further.
+
+R-FF-ORPHAN-01: [finish-feature-flow.md · Step 1 · "And the other direction, for every host shape"] The checks around this one walk rows → files, so a file no row names is otherwise never examined. Deliberately **not** scoped to a host shape: an unreferenced `phase-spec-*` is precisely what makes a host read as *phase-bearing* to the minimal-host selector below, so a shape-scoped version of this check could never be the one that sees it.
+
+R-FF-BRANCH-01: [finish-feature-flow.md · Step 1 · "The row must name *this* branch"] "An override happened once" would excuse closing out on any branch at all, which is not what the option sanctions; requiring the row to name where you actually are defeats that without over-blocking.
+
+R-FF-BRANCH-02: [finish-feature-flow.md · Step 1 · "You are on this host's branch — or on a branch this host recorded a sanctioned override for"] ⚠ **Deliberately not "the most recent override".** A host can override onto `develop` for one phase and onto `spike/x` for the next, then close out on `develop` — and closeout fires no branch gate of its own, so no newer row is ever written. Keying on the most recent row would block a branch this host recorded a sanctioned override for, which is the same false block this clause exists to remove.
+
+R-FF-BRANCH-03: [finish-feature-flow.md · Step 1 · "When it passes this way, say so in the conversation"] A gate that silently accepts an exception teaches the developer nothing about why it passed.
+
+R-FF-BRSNAP-01: [finish-feature-flow.md · Step 1 · "Current BR Snapshot table is non-empty", on a phase-bearing T1 whose phase-specs establish no BR delta] (genuinely new work is `/dflow:new-feature` "even with no new BR / Domain / schema", `AI-AGENT-GUIDE.md` § Ceremony Scaling step 0, and `new-feature-flow.md` Step 4 initialises the Snapshot from planned BRs that may legitimately be none)
+
+R-FF-BASELINE-01: [finish-feature-flow.md · Step 1 · "The `-w` is mandatory"] Without `-w`, `git hash-object` computes the id and never stores the blob, so the baseline's **content** is unrecoverable afterwards — `git cat-file -p` on that id fails with `Not a valid object name`, leaving Step 4 holding fingerprints for a comparison that needs the text. It is also what makes Step 1's "captured rather than remembered" true of the **content** and not only of the id. ⚠ **These blobs are unreferenced, and the ref does not change that.** A ref pointing at the list keeps *the list* reachable; the ids written inside it are text, not object pointers, so reachability does not follow them — measured: `git rev-list --objects --no-walk {list blob}` returns one object, and a `git gc --prune=now` after anchoring the ref removes the per-file blobs while the list survives. What bounds their lifetime is git's own prune grace (`gc.pruneExpire`, two weeks by default), which a closeout does not outlast even when it spans sessions. ⚠ The blobs most needed are the least covered: a path whose content is **unchanged** between Step 1 and the commit is reachable from the commit anyway, while `_index.md` — the one every ordered edit touches — is reachable from neither the commit nor the ref.
+
+R-FF-BASELINE-04: [finish-feature-flow.md · Step 1 · "Both halves of that command are load-bearing"] The capture has to name the same set `git add` will stage, and it can miss in **both** directions. An **ignored** file captured here enters the baseline as a path the span can never carry — `git add` skips it too — so it reads as a file deleted after Step 1. An **untracked but not ignored** file *omitted* here is the mirror image: `git add {dir}` does stage it, so it arrives in the span with no baseline entry and reads as a file added after Step 1. Both block, and neither is clearable — by the time either surfaces the host is archived and the closeout committed. `--cached --others --exclude-standard` is the set `git add` itself works from, so the two are the same predicate evaluated at two times rather than two sets that happen to agree. ⚠ The second direction is not hypothetical: greenfield's `aggregate-design.md` worksheet is ordered into the host by `AI-AGENT-GUIDE.md` § Ceremony Scaling and may never have been committed.
+
+R-FF-BASELINE-05: [finish-feature-flow.md · Step 1 · "That ref is the baseline"] The `-w` made the blobs durable but left the `path → blob` list — the only way to address them — stated in the conversation, two sentences after the same paragraph called that store unreliable. Closeout is expected to cross sessions: `templates/_index.md`'s Resume Pointer says to read it when continuing in a new conversation, and Step 2 writes a cursor for "the next session". A ref fixes the addressing rather than shrinking it: the name is **recomputed** from `{SPEC-ID}-{slug}`, which the next session already knows from the host it is closing, so nothing about the baseline has to survive the conversation. It also makes the list itself an object in the database rather than a conversational artefact. ⚠ **It does not extend reachability to the blobs it names** — see `R-FF-BASELINE-01` for what actually bounds those. `refs/dflow/**` is outside the default push, fetch and clone refspecs; an explicit refspec or `clone --mirror` does carry it, which is why the step says not to add one.
+
+R-FF-BASELINE-06: [finish-feature-flow.md · Step 4 · "First, confirm the baseline is still readable"] The post-commit item below reads the same ref, so this looks redundant — the difference is entirely **where the failure leaves you**. Below, the `git mv` has happened and the closeout is committed: the host is in `completed/`, the tree Step 1 read cannot be rebuilt, and the section's own "fix it and re-verify" has nothing to act on. Detected here the host is still in `active/` with nothing committed, so the remedy is one step. A check whose failure has no repair procedure is a report, not a gate; this moves the detection to where it is a gate.
+
+
+R-FF-BASELINE-08: [finish-feature-flow.md · Step 4 post-commit verification · "release the baseline anchor"] The ref is deleted rather than left behind because it is scaffolding, and an adopter repo should not accumulate one per closed feature. It is deleted **after** the items pass, not before: while it exists a failed item can be fixed and re-verified against the same evidence, and releasing it first would discard the only copy of what the comparison needs. Deleting a ref changes no file, so it is not a difference the comparison above could see and nothing there needs to admit it.
+
+R-FF-COMMITCELL-03: [finish-feature-flow.md · Step 4 post-commit verification · "An empty hosted `Commit` cell does not fail this item"] The obvious repair — have closeout check the cell it is reading anyway — is the wrong one. `references/pr-review-checklist.md`'s "Every Lightweight Changes row now carries a `Commit` hash" item states its own reason for existing as *"That is why closeout does not assert this for a phase-bearing host, and why it is checkable here"*, so making closeout assert it falsifies the other half of a documented division of labour and leaves the same rule written in two places. What was wrong was never the division; it was that the clause read as a **ruling** that an empty cell is acceptable, stated at the moment closeout is *entered*, while the item reading it runs against the **committed** blob after instruction 1 has already ordered the backfill.
+
+R-FF-CURSOR-01: [finish-feature-flow.md · Step 2 · "Also update the **Resume Pointer** — to the state closeout is actually in"] The terminal value used to be written here, four steps before closeout ends. While the host is still in `active/` the global scans do read this cursor, so a `none` written at Step 2 made the flow's own gate 3 → 4 ask the developer for `/dflow:next` — a command `AI-AGENT-GUIDE.md` requires to be refused when no workflow is active — and it disabled `/dflow:cancel` for a closeout that was genuinely still running. An honest in-progress value removes both and costs nothing: the field is a claim, and a claim that closeout has finished is false until it has.
+
+R-FF-CURSOR-02: [finish-feature-flow.md · Step 4 · "The `git mv` and this write are one uninterruptible pair"] Two decisions, and the second is a deliberate narrowing. **Why it is bound to the `git mv` rather than to the commit:** the archive is what moves the host out of `active/`, so from that instant the cursor is read by one reader (the PR reviewer `references/pr-review-checklist.md` sends to it) instead of by the global scans; writing before the Y / N prompt closes the only window where the host sits in `completed/` while the cursor still declares the workflow active, which is the window `/dflow:cancel` would act on. **Why closeout does not restore it when the commit is declined, fails, or post-commit verification reports `✗`:** a restore cannot buy back findability, because `git mv` is Step 4's first action and `/dflow:status` reads only `active/` — the host is already gone from the only place a restored cursor would be seen. The rule was written and then removed: it bought nothing and cost an index / working-tree synchronisation contract on three failure branches. The accepted residual risk is that a closeout failing after this point is visible only in `git status`.
+
+R-FF-GITMV-01: [finish-feature-flow.md · Step 4 · "`git mv` is mandatory — never use plain `mv` + `git add`"] This preserves git's directory rename detection so `git log --follow` / `git blame` / PR diff quality stays intact across the move.
+
+R-FF-SWEEPKEY-01: [gf · finish-feature-flow.md · Step 4 instruction 2 · "Key it on the flow that produced the change, never on the flow that opened the host"] Those differ, and keying on the host is how the deadlock came back: `modify-existing-flow.md` Step 1.6 opens a **phase-bearing** host for a T1 follow-up, and Step 5.4 puts a T1 new-phase or a T2 lightweight *inside* a host opened by `/dflow:new-feature` — each of those runs Step 5.3 as its own sweep. Ask "which flow opened this host" and a hosted **T2** on a phase-bearing **no-BC** host has no arm at all: half (a) is empty because Step 3 is skipped, and the `glossary.md` rename its Step 5.3 made belongs to a sweep the question refused to look at. Unstaged it fails the clean-tree item; staged it is attributable to nothing. Deriving from *this change's* flow is the fix — not widening the set to "anything dirty".
+
+R-FF-SWEEPKEY-01: [bf · finish-feature-flow.md · Step 4 instruction 2 · "Key it on the flow that produced the change, never on the flow that opened the host"] Those differ, and keying on the host is how the deadlock came back: `modify-existing-flow.md` Step 1.6 opens a **phase-bearing** host for a T1 follow-up, and Step 6.4 puts a T1 new-phase or a T2 lightweight *inside* a host opened by `/dflow:new-feature` — each of those runs Step 6.3 as its own sweep. Ask "which flow opened this host" and a hosted **T2** on a phase-bearing **no-BC** host has no arm at all: half (a) is empty because Step 3 is skipped, and the `glossary.md` rename its Step 6.3 made belongs to a sweep the question refused to look at. Unstaged it fails the clean-tree item; staged it is attributable to nothing. Deriving from *this change's* flow is the fix — not widening the set to "anything dirty".
+
+R-FF-SWEEPKEY-02: [finish-feature-flow.md · Step 4 instruction 2 · "do not go looking for a list that host never produced"] ⚠ Keying this on the minimal-host allow-list (`finish-feature-minimal-host.md`) is what deadlocked the one shape where both halves are empty: a **phase-bearing, no-BC** host that swept a global document has nothing from Step 3 *and* no Step 1 allow-list, while this instruction still requires the delta staged and the post-commit path check would then reject it as unpermitted — two mandatory requirements that could not both be met.
+
+R-FF-SPAN-01: [gf · finish-feature-flow.md · Step 4 post-commit verification · "The span is derived from what was staged, not from what the tables name"] Instruction 2 stages the archived directory **whole**, so a span built from the Phase Specs and Lightweight Changes rows is narrower than the commit — and Step 1 permits exactly one file no table names, the `aggregate-design.md` worksheet. Under the narrower span that file entered the commit and was compared against nothing. Keying on `git ls-tree` closes that for any such file, present or future, with no list to maintain.
+
+R-FF-SPAN-01: [bf · finish-feature-flow.md · Step 4 post-commit verification · "The span is derived from what was staged, not from what the tables name"] Instruction 2 stages the archived directory **whole**, so a span built from the Phase Specs and Lightweight Changes rows is narrower than the commit. Greenfield's Step 1 permits one such file by name (an `aggregate-design.md` worksheet); brownfield has no counterpart today, and keying on `git ls-tree` means it needs no edit if one ever appears.
+
+R-FF-BASELINE-02: [finish-feature-flow.md · Step 4 post-commit verification · "Blob ids alone answer only *same* / *different*"] The derived condition asks whether the committed blob differs from the baseline in **exactly** the ordered edits and nothing else, and id equality cannot express it: on the normal path the ids differ, because Step 2, Step 4's terminal Resume Pointer write and Step 4 instruction 1 all edit `_index.md` by design — so *different* is the expected reading and says nothing about **which** differences are present. Reading the delta is the only form that separates an ordered edit from edit fallout. Equality is still read, and it is not a pass on its own: identical ids mean that file was not touched at all — the ordinary case for the spec files in the host, and a failure for any path a step of this closeout ordered an edit to, because it says the ordered edit never landed.
+
+R-FF-BASELINE-03: [finish-feature-flow.md · Step 4 post-commit verification · "Compare the two path sets first, before any blob comparison"] The `git mv` makes the two sets line up only while no file was added or removed between Step 1 and the commit, so the alignment is the thing to establish rather than the thing to assume — and neither kind of mismatch is reachable by the per-path comparison that follows: a removed file is never visited, because the span comes from `git ls-tree` on the commit, and an added one has no baseline blob to diff against. The other half of this check does not catch them either: the spill item admits the archived host directory **whole**, so a file added inside it is a permitted path. Left unstated, a host file deleted during closeout passes both halves in silence — the coarsest form of the edit fallout this check exists to block.
+
+R-FF-POSTCOMMIT-01: [finish-feature-flow.md · Step 4 post-commit verification · "do not substitute `HEAD^`"] The parent commit is not the tree Step 1 read: the edits legitimately uncommitted at Step 1 would each surface as a difference no step ordered, and the check would block a correct closeout.
+
+R-FF-POSTCOMMIT-02: [finish-feature-flow.md · Step 4 post-commit verification · "`git show HEAD:<path>` for each"] Reading the **committed** blob is what catches "the rename carried stale content" and "the row never made it into the commit".
+
+R-FF-SPILL-01: [gf · finish-feature-flow.md · Step 4 post-commit verification · "The closeout commit contains only what closeout is allowed to write"] ⚠ **Keyed on instruction 2, and deliberately not on the minimal-host allow-list.** That allow-list exists only for a `Minimal host (zero-phase)` and lives in `finish-feature-minimal-host.md`; a phase-bearing host has none. Keying this item on it — with "plus whatever Step 3 wrote" as the other half — left a **phase-bearing, no-BC** host with **both** sources empty while instruction 2 still required its global sweep delta staged: stage it and this item rejected the path, skip it and the clean-tree item failed. Instruction 2 is the one statement that covers every host shape, which is why it is the source.
+
+R-FF-SPILL-01: [bf · finish-feature-flow.md · Step 4 post-commit verification · "The closeout commit contains only what closeout is allowed to write"] ⚠ **Keyed on instruction 2, and deliberately not on the minimal-host allow-list.** That allow-list exists only for a `Minimal host (zero-phase)` and lives in `finish-feature-minimal-host.md`; a phase-bearing host has none. Keying this item on it — with "plus whatever Step 3 wrote" as the other half — left a **phase-bearing, no-BC** host with **both** sources empty (Step 3 is skipped for a no-BC host and for a baseline host) while instruction 2 still required its global sweep delta staged: stage it and this item rejected the path, skip it and the clean-tree item failed. Instruction 2 is the one statement that covers every host shape, which is why it is the source.
+
+R-FF-SPILL-02: [finish-feature-flow.md · Step 4 post-commit verification · "Scope: this is a path-level spill check and nothing more"] A clean tree does not even cover the path level — it proves the changes were committed, not that only permitted ones were — and Step 4's staging instructions prove nothing on the developer-commit path.
+
+R-FF-DERIV-01: [finish-feature-flow.md · Step 5 · "First, print the closeout verification's derivation"] **Why this is here.** The verification derives its admitted set instead of reading a list — that is what keeps the list and its sources from drifting apart — but it also means a reader cannot see the set by looking at the checklist. Printing the derivation keeps the flow inspectable instead of a box that answers `✓` without showing its working.
+
+R-FF-INFLIGHT-01: [finish-feature-flow.md · Step 5 · "In-flight reminder"] Surfacing them at closeout is deliberate: attention is about to move elsewhere, and this is exactly where half-done work sinks.
+
+## finish-feature-minimal-host.md
+
+R-FF-COMMITCELL-01: [finish-feature-minimal-host.md · Step 1 · "Do not collapse the middle case into the first"] it is the one that reads as *filled* to every rule written against empty / non-empty, which is exactly why it survives elsewhere.
+
+R-FF-COMMITCELL-02: [finish-feature-minimal-host.md · Step 1 · "Deliberately not run on a phase-bearing host"] a hosted T3's row rides the host's *next* commit (`references/git-integration.md` § Commit checkpoints), and nothing requires a hosted row to declare implementation paths — so (c) has no defined input there, and demanding it would reject every hosted T3.
+
+R-FF-BASELINECAP-01: [bf · finish-feature-minimal-host.md · Step 1 · "a `spec-baseline` checkpoint and a `Tier = baseline` row imply each other"] `modify-existing-flow.md` Step 1.7 states the contract: a baseline capture is observation-only, *there is no implementation work*, which is why its checkpoint is not named `implementation`. (1) and (2) alone are the ledger talking about itself; (3) is what makes the claim true of the commit.
+
+R-FF-CKPTCOUNT-01: [finish-feature-minimal-host.md · Step 1 · "the Checkpoint Log carries exactly one row at this point"] ⚠ **Why this counts every row, with no exclusion for the `branch-override` record:** a minimal host cannot carry one. `references/modify-existing-flow.md` withholds the branch-gate override from exactly these hosts (Step 1.6's follow-up variant, Step 1.7, Step 1.8), because they assert branch equality against a `branch:` cut by change class.
+
+R-FF-CKPTCOUNT-02: [finish-feature-minimal-host.md · Step 1 · "the Checkpoint Log carries exactly one row at this point"] "Exactly two after closeout" follows from `finish-feature-flow.md` Step 4's post-commit read, which derives its admitted differences from Step 2, Step 4's terminal Resume Pointer write and Step 4 instruction 1, and admits nothing else.
+
+R-FF-FOLLOWUP-01: [finish-feature-minimal-host.md · Step 1 · "the reverse link was opened, not only closed"] Decidable from one commit and one blob per original, so it stays inside closeout's remit.
+
+R-FF-SUMMARY-01: [finish-feature-minimal-host.md · Step 5 · "Zero-phase minimal host — exact fields", on a no-BC host's `Related BR-IDs`] Forcing `none` here would erase a marker the approved zero-phase shape requires.
+
+## init-project-flow.md
+
+R-INIT-DEFERRED-01: [init-project-flow.md · Step 3.1 · "is NOT generated here", both bullets] Init creates neither a per-context `behavior.md` nor either `analysis.md`: an empty file created ahead of its content becomes a stale placeholder.
+
+## modify-existing-flow.md
+
+R-ME-BASELINE-01: [bf · modify-existing-flow.md · Step 2 · "Systematic Baseline Capture"] Baseline capture looks for system-level knowledge and records it in `analysis.md`, even though it runs only when the feature being modified has no prior spec: it is how a project that adopts Dflow midway gets its existing system into `analysis.md` in bulk, rather than one entry at a time. Every other entry point only records what the change in hand happens to touch; the observation-only route in Part A records without changing anything, but only what that observation reached.
+
+## new-phase-flow.md
+
+R-NP-ANALYSIS-01: [new-phase-flow.md · Step 2 · "System-level knowledge?"] Step 2 records into `analysis.md` on the spot rather than leaving it to closeout, because deferring needs two things this flow does not have: somewhere to hold the answer until closeout (the phase-spec template has no section for it), and a closeout step that always runs (a host with no bounded context skips `/dflow:finish-feature` Step 3 entirely). Each track's Step 7 carves these two paths out of its "remain `/dflow:finish-feature` responsibilities" sentence for the same reason. Step 6 re-checks what Step 2 recorded - what the phase was to add or change against what it built, what Step 2 uncovered in the existing system against the system as it now stands, since knowledge Step 2 uncovered was true before the phase began and does not stop being true because the phase built nothing for it - instead of leaving that to closeout as well: no closeout step is sure to reach the entry (`/dflow:new-feature` § 8.4 archives without `/dflow:finish-feature`), and by then a checkpoint has usually committed it, so no diff would show it.
+
+## templates/analysis.md
+
+R-ANALYSIS-PLACEMENT-01: [templates/analysis.md · Placement · "who owns what the entry describes"] This template fills two paths rather than one because the knowledge it holds splits that way in practice: a lifecycle, a derived figure and a mechanism usually have an owning context, while ordered flows across contexts and the function/role map are kept in the domain-root copy by policy, whoever owns what a given flow or row describes - a flow is read end to end across the contexts its steps belong to, and the index answers who reaches what across the whole system, which no one context's copy could show. Keeping all of it in one domain-root file would both deny the first three their owning context and make that single file grow with the whole system; asking who owns the thing an entry describes lets each copy grow with what it describes, and leaves a home for the cases that turn out to have no owner. A hotspot row goes with the knowledge it is stuck on - in whichever copy holds that knowledge, the ownership question deciding only when it is stuck on a business rule or on knowledge not recorded yet - so that whoever reads that knowledge also sees what the project is still working around in it. The per-context path costs little to enforce, because it is an ordinary BC-layer document to every closeout, no-BC and path check in the workflow - though the checks that enumerate those documents by name still name it.
+
+R-ANALYSIS-EVIDENCE-01: [templates/analysis.md · Lifecycles · "Evidence sits on the transitions"] The state list carries no Evidence column because it is the entry's vocabulary - what each value means and what it allows or blocks next - while each transition is a claim about how the system behaves now, which goes stale and must stay re-checkable. The cost is that the claim "these are all the values this field holds" cannot itself be re-checked from the table.
+
+R-ANALYSIS-QUESTIONS-01: [templates/analysis.md · Open Questions and Hotspots · "comes up while writing an entry here"] Questions are not routed into this file by subject: where a question belongs depends on the form its answer will take, and the two can disagree — "which role may approve a refund?" is about role reach, yet its answer is a business rule for the owning context's `rules.md`. An unanswered question therefore stays in the feature spec or in the Open Questions section of the document its answer belongs to; when that document is this template, the question goes in the copy that will hold the answer, whichever copy raised it, so that whoever comes to record the answer finds the question beside it - even where that means creating that copy for the question.
+
+R-ANALYSIS-IDCOL-01: [templates/analysis.md · the two tables with an ID column · "carries it there"] The ID column is placed after the name column, not first, because `dflow render` takes a table's first column as each card's title: with the id first, every card in these two tables would be titled `FN-01` or `HS-01` and the name or the hotspot itself would be demoted to a field. The flow table keeps `#` first because a step number is a reasonable card title.

package/templates/common/skill/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: dflow
 description: >
-  Dflow SDD/DDD workflow guardian for this project. PRIMARY: the canonical
-  /dflow:* commands (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
+  Dflow SDD/DDD workflow guardian. PRIMARY: the canonical /dflow:* commands
+  (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
   /dflow:new-phase, /dflow:finish-feature, /dflow:pr-review, /dflow:verify,
   /dflow:report-dflow-feedback, /dflow:status, /dflow:next, /dflow:cancel).
-  SECONDARY — engage ONLY for adding or changing product/user-facing/domain
-  behavior, a new requirement, a feature or bug-fix workflow, or spec-impacting
-  architecture/domain-model decisions. Includes indirect phrasings, e.g. "I want
-  to build/add ...", "let's add the ability to ...", "we need to support ...",
-  "can you implement ...", "users should be able to ...", "the app should also
-  ...". Do NOT engage for pure refactors, renames, infra/build chores,
-  formatting, dep bumps, or general code questions ("how does X work", "explain
-  this"). When engaged by natural language, DO NOT auto-enter a workflow: judge
-  the intent, suggest the matching /dflow: command, and wait for confirmation.
+  SECONDARY — engage for anything Dflow tracks: a product-visible change, or
+  one touching a machine-consumed contract (log/export/API/event, env
+  var/CLI flag/exit code), data structure, operational semantics
+  (security/CVE, safety, resilience, compliance, payment),
+  performance/resource/SLA, BR-ID, or architecture/domain model. Indirect
+  phrasings: "I want to build/add ...", "we need to support ...", "users
+  should be able to ...". Do NOT engage for behavior-preserving routine work
+  touching none of those — refactors, renames, chores, formatting, routine
+  dependency bumps — or code questions. When engaged by natural language, DO
+  NOT auto-enter a workflow: judge the intent, suggest the matching /dflow:
+  command, and wait for confirmation.
 ---
 
 <!-- dflow-generated: skill-adapter -->

package/templates/greenfield/references/drift-verification.md

@@ -165,6 +165,10 @@ Issues:
      remove the stale scenario reference from behavior.md
 ```
 
+When a remediation action adds or updates `rules.md` rows, follow the spec formatting convention:
+
+> **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).
+
 The optional domain-doc hygiene checks (below) append their non-blocking signals
 to this same report — the `events.md` cross-check as `⚠`, the `models.md`
 Code-Mapping check as `ℹ` — and never change the core pass / fail count.