dflow-sdd-ddd 0.14.0 → 0.16.0

package/templates/brownfield/references/git-integration.md

@@ -13,8 +13,12 @@ feature-branch-per-feature convention that SDD traceability depends on.
 
 ## Branch-to-Workflow Mapping
 
-Dflow only requires that every SDD feature / bug-fix lives on its own branch
-that links back to a spec. The *base branch* that feature branches are cut
+Dflow only requires that SDD work is traceable from the branch it lands on. A
+feature, and a defect that owns its own branch, each get a branch that links
+back to what was recorded. Work picked up by a feature that is still in
+progress stays on that host's branch — the host `_index.md` `branch:` field is
+authoritative — and a T3 change is traced by its `_index.md` row, not by a spec
+file of its own. The *base branch* that feature branches are cut
 from (e.g. `main`, `develop`, `trunk`) is a project-level decision that Dflow
 does not mandate.
 
@@ -24,8 +28,12 @@ main (or your project's base branch)
   ├─ feature/{SPEC-ID}-{slug}       ← Full SDD workflow
   │   Gate: spec must exist BEFORE first commit
   │
-  └─ bugfix/{BUG-ID}-{slug}         ← Lightweight SDD workflow
-      Gate: at minimum a lightweight spec
+  └─ bugfix/{BUG-ID}-{slug}         ← a defect that owns its own branch
+      (a defect with no feature to host it opens a minimal zero-phase host
+       of its own — see references/modify-existing-flow.md Step 1.7)
+      Gate: whatever the cascade's tier calls for (T2: at minimum a
+      lightweight spec; T3: the host _index.md row only; T1: escalate —
+      it belongs on a feature/ branch)
 ```
 
 > If your project adopts Git Flow / GitHub Flow / trunk-based, the choice of
@@ -60,7 +68,9 @@ The branch slug follows the language the developer / AI discuss the
 feature in. **Both Chinese and English slugs are valid**; Dflow does not
 force translation in either direction. The same slug is reused for the
 feature directory name and the first phase-spec filename, so consistency
-across branch / dir / phase-spec is automatic.
+across branch / dir / phase-spec is automatic. A **minimal (zero-phase)
+host** has no phase-spec, so its slug is shared by the branch and the
+directory only — the absent third name is the host's shape, not drift.
 
 Examples:
 
@@ -94,8 +104,13 @@ This is the one non-negotiable Git coupling Dflow enforces:
 - **Every SDD feature must have its own feature branch.** Branch name must
   match its SPEC-ID so that `git log`, PR titles, and spec documents can be
   traced back to one another.
-- **Every bug-fix (SDD-tracked) must have its own bugfix branch** following
-  the same pattern.
+- **A defect that owns its own branch uses a `bugfix/` branch** following the
+  same pattern — including a standalone defect whose own minimal host is what
+  owns it, and whose branch therefore carries a BUG-NUMBER rather than that
+  host's SPEC-ID. A defect picked up by a feature that is still in progress is
+  hosted work instead: it stays on that host's branch. Either way the host
+  `_index.md` `branch:` field is authoritative — every spec inside that host,
+  and every branch gate applied to it, takes its value.
 - Commits that span multiple specs (accidentally or deliberately) are
   discouraged; if you notice work on a new spec emerging mid-branch, stop
   and create a new branch off the correct base.
@@ -124,9 +139,34 @@ Both Git policies (`gitflow` / `trunk`, per `dflow/specs/shared/_conventions.md`
   project cuts features from — `main` / `develop` / `trunk`, or whatever your
   policy uses — or on an unrelated branch) — the AI offers to create and switch
   to the correct branch, switch to an existing matching one, or override and
-  stay (recorded in the feature `_index.md` Checkpoint Log; three consecutive
-  overrides → the AI suggests re-running `dflow init`, never changing the
-  setting on its own).
+  stay (three consecutive overrides → the AI suggests re-running `dflow init`,
+  never changing the setting on its own).
+
+  **How "override and stay" is recorded, so closeout can honour it.** Write one
+  row in the feature `_index.md` Checkpoint Log:
+
+  | Timestamp | Checkpoint | Result |
+  |---|---|---|
+  | {YYYY-MM-DD HH:MM} | `branch-override` | `override ({branch-you-stayed-on})` |
+
+  The Result **names the branch you stayed on** — not the value of `branch:`,
+  which stays exactly as the host opened it. That name is what makes the record
+  usable, and it is exactly what closeout reads: **its branch check passes when
+  *any* `branch-override` row on this host names the branch `HEAD` is on** — not
+  only the most recent one, because a host may override onto different branches
+  in different phases and closeout fires no branch gate of its own, so it never
+  writes a newer row. A record that does not say *where* you stayed excuses
+  nothing.
+  ⚠ **This row is a record, not a lifecycle checkpoint.** It is not a commit and
+  it does not count toward the tier's checkpoint count.
+  ⚠ **Where it can appear at all: only on a phase-bearing host.**
+  `references/modify-existing-flow.md` withholds this override from every
+  **minimal host** (Step 1.6's follow-up variant, Step 1.7 standalone, Step 1.8
+  post-hoc), because those hosts assert branch equality against a `branch:` they
+  cut by change class. So `references/finish-feature-flow.md`'s closeout branch
+  check reads this row and honours it, while its minimal-host checkpoint count
+  is never looking at one — that count says so at the site rather than carrying
+  an exclusion for a row that cannot reach it.
 
 Dflow does not need to identify your base branch to evaluate the gate — it only
 checks whether you are on the right feature branch. The base branch matters only
@@ -136,7 +176,8 @@ project's decision (GitFlow → `develop`, Trunk / GitHub Flow → `main`).
 ### Commit checkpoints
 
 At lifecycle milestones the AI offers a commit checkpoint, folded into the
-existing Step Gate prompt (it does not add a separate question):
+prompt the flow already shows there — a Step Gate, or the flow's closing
+announcement (it does not add a separate question):
 
 ```
 ✓ {milestone} complete
@@ -147,12 +188,47 @@ existing Step Gate prompt (it does not add a separate question):
 
 Tier sets how many checkpoints a change has: T1 three (spec / implementation /
 closeout), T2 two (spec+implementation merged / closeout), T3 a single commit.
+**What a checkpoint carries follows from where its flow offers it.**
+`references/modify-existing-flow.md` offers its checkpoint at the end of its
+artifact step (Step 6), so a T2's merged commit — and a T3's single commit —
+carries the change together with the documentation that step writes.
+`/dflow:new-feature` and `/dflow:new-phase` offer the implementation checkpoint
+at the gate into their completion step, so what that step writes rides the
+host's next commit, whichever that is — for example the next phase's first
+checkpoint, a hosted lightweight change's commit, or closeout.
+"T3 = a single commit" means a single **implementation** commit. On a hosted T3
+the entries that carry its hash ride the host's **next** commit (more work, or
+closeout), as every checkpoint's do (below). If the host has no next commit
+scheduled, one ledger-only tracking commit that references the T3 hash is
+allowed. It is bookkeeping, not a lifecycle milestone: it adds no Checkpoint Log
+row of its own (unlike closeout, which is a checkpoint and does get a row).
+**Minimal host (zero-phase) exception — there, tier does not set the count.**
+On a minimal host (`references/modify-existing-flow.md` Step 1.7 standalone, or
+its Step 1.6 follow-up minimal variant) there is no later host commit for a row
+to ride, so the count is **two for every tier** — implementation, or
+`spec-baseline` for a baseline capture, then closeout — and every row, a T3's
+included, is written into checkpoint 1 itself; only the entries that carry
+checkpoint 1's hash ride the closeout commit.
+Everything above about "T3 = a single commit" describes a **hosted** T3, the
+case where a later host commit exists.
 Whether you choose Y or N, the AI records one row in the feature `_index.md`
 Checkpoint Log — every checkpoint is accounted for (`committed` / `skipped` /
-`failed`), even when no commit happens. A commit hash is written only after the
-commit succeeds; a hook rejection or failed commit is recorded as `failed`
-(never a fake hash). **Exception — the closeout row**: the closeout commit
-cannot contain its own hash, so the closeout row is written before the commit
+`failed`), even when no commit happens.
+**No checkpoint commit can contain its own hash.** The entries that carry a
+checkpoint's hash — its Checkpoint Log Result `committed ({hash})`, and any
+Lightweight Changes `Commit` cell holding that hash — are written after the
+commit succeeds and ride the host's **next** commit. A hook rejection or failed
+commit is recorded as `failed` (never a fake hash).
+**One further Result value — `reconciled ({merged-hotfix-hash})`.** It records
+that this checkpoint documents a change that was **already merged** before any
+ceremony ran, and it is written only on a post-hoc hotfix host's implementation
+row (`references/modify-existing-flow.md` Step 1.8). The hash in the parentheses
+belongs to the **merged hotfix**, not to this host's own documentation commit —
+that one goes in the Lightweight Changes row's `Commit` cell, and the two have
+different provenance and must never be swapped. On every other host the three
+values above are the whole vocabulary.
+**Exception — the closeout row**: no later commit of this host's lifecycle
+carries it, so the closeout row is written before the commit
 as `closeout | committed` with **no hash** (see
 `references/finish-feature-flow.md` Step 4); trace that commit via
 `git log -1 -- dflow/specs/features/completed/{SPEC-ID}-{slug}` or the optional
@@ -275,17 +351,35 @@ heavily enough that git's similarity index dropped below the rename
 threshold; consider using `git mv` for the move, then making content
 edits in a follow-up commit).
 
-### CI / hook automation (future)
+### CI / hook automation
 
-A pre-commit hook can refuse commits where `dflow/specs/features/active/` or
-`dflow/specs/features/completed/` show paired `D` + `A` instead of `R` for
-the same feature directory. Not part of Dflow today, but compatible
-with the rule.
+Dflow ships `dflow check-closeout`, a gate for the closeout commit. For each
+feature directory newly archived to `dflow/specs/features/completed/` it checks
+that `_index.md` and every spec say `status: completed`, that nothing is left
+under `active/`, that the Checkpoint Log has a real `closeout` row reading
+`committed` or `skipped`, and — with `--staged` — that nothing under the
+archived directory is left unstaged; it exits 1 when one fails. A project wires
+it into a pre-commit hook (`--staged`) or a CI job (`--range <base>..<head>`)
+itself — Dflow installs neither. `dflow check-closeout --help` names the page
+with the hook and CI templates. When the hook refuses a closeout commit, handle
+it as `references/finish-feature-flow.md` Step 4 instruction 3 says.
+
+Passing it is not a clean closeout: the post-commit verification in
+`references/finish-feature-flow.md` Step 4 still applies in full.
+
+A hook that refuses paired `D` + `A` instead of `R` for the same feature
+directory is compatible with the `git mv` rule, but it is not part of
+`check-closeout`.
 
 ## Gate Checks by Branch Type
 
 ### feature/ branch — Before Creating
 
+This is the **phase-bearing** (T1) list. A **minimal (zero-phase) host** cuts a
+`feature/{SPEC-ID}-{slug}` branch too and takes the short list under it: it has
+no phase-spec *by definition*, so every item that reads one is not merely unmet
+but unmeetable, and demanding them would block the change the branch exists for.
+
 AI should verify:
 - [ ] Feature directory exists at `dflow/specs/features/active/{SPEC-ID}-{slug}/`
       with `_index.md` and at least one phase-spec inside
@@ -294,7 +388,33 @@ AI should verify:
 - [ ] At least one Given/When/Then scenario is defined in the first phase-spec
 - [ ] Domain concepts are identified (even if not yet in models.md)
 
+**Minimal (zero-phase) host — this list instead**
+(any route in `references/modify-existing-flow.md` that opens a zero-phase host
+— Step 1.7 standalone, Step 1.6's follow-up variant, Step 1.8's post-hoc
+hotfix, or one added later; a baseline capture uses the same shape):
+- [ ] Feature directory exists at `dflow/specs/features/active/{SPEC-ID}-{slug}/`
+      with a minimal `_index.md` — all seven sections, Phase Specs table
+      **empty**, and no `phase-spec-*` file
+- [ ] `_index.md` has status: `in-progress`, and its `branch:` equals the branch
+      being cut — that field is authoritative for everything in this host
+- [ ] The tier's artifact is ready to be written into the first commit: a
+      lightweight-spec for a **T2**, a Lightweight Changes row for a **T3**, a
+      `Tier = baseline` row for a baseline capture — in every case with the
+      paths it declares named. For a **T2 / T3** those are the implementation
+      paths; a **baseline capture** is observation-only and declares the
+      **documents it wrote** instead — that is its counterpart
+      (`references/modify-existing-flow.md` Step 1.7). Do not ask a capture for
+      implementation paths: `references/finish-feature-flow.md` Step 1 blocks a
+      baseline commit that carries implementation source at all
+- [ ] Bounded Context is identified **only if this change has one**; a no-BC
+      host records `none` and must not acquire a context to pass this gate.
+      **A baseline capture is never no-BC** — it sets `BC:` to the context it
+      captured, because capturing that context is the whole point of the host
+
 If any are missing, guide the developer through creating them BEFORE the branch.
+On the minimal-host list that governs the `_index.md` items; the tier's artifact
+only has to be *decided and ready to write*, because Step 1.7 records it after
+the branch is cut, not before.
 
 ```
 "Before we create the branch, let's set up the spec.
@@ -310,24 +430,83 @@ AI should verify:
 - [ ] All `phase-spec-*.md` in the feature directory have `status: completed`
 - [ ] `_index.md` Current BR Snapshot has been synced to BC layer
       (`rules.md` / `behavior.md`) — typically by `/dflow:finish-feature`
-- [ ] Whole feature directory ready to `git mv` to `dflow/specs/features/completed/`
-      (or already moved if `/dflow:finish-feature` ran)
+- [ ] **Closeout complete**: `/dflow:finish-feature` has announced closeout
+      complete for this host — its Local-closeout gate is satisfied (the
+      closeout commit landed and passed post-commit verification) and, if
+      the host carries `follow-up-of`, the Step 6 tracking commit has also
+      landed and been verified. `status: completed` or a directory already
+      under `completed/` does not show this on its own.
 - [ ] All new business logic is in `src/Domain/` (not delivery/entrypoint code — presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures)
 - [ ] New terms added to `glossary.md`
 - [ ] `rules.md` and `models.md` updated if applicable
 - [ ] Tech debt recorded for any shortcuts taken
 - [ ] Domain layer code has no delivery-framework references
 
+> **On a minimal (zero-phase) host**, split this list by what each item reads.
+> Items about **this host's own record** — `_index.md` status, **Closeout
+> complete**, and the phase-spec check, which passes vacuously on an empty
+> table — apply **unchanged**: they are what stops a host merging with its
+> record still open. Every item that names a **Domain or bounded-context
+> artifact**, the BR-Snapshot sync included, applies only to what this change
+> **actually touched**: a **no-BC** host has no bounded context to sync or
+> document, a **T3** does no Domain work at all, and a **baseline capture** has
+> already written Domain documents directly rather than syncing to them — so for
+> those they read N/A. **Bounded-context-scoped only** — `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 they are
+> **not** N/A for either. **Code invariants are not artifacts** — the items
+> here that state a rule about the **source** rather than name a document to
+> update are **never N/A**: they hold for any change that touches code at all,
+> and a host wrongly claiming to be no-BC is exactly what they catch. Record
+> the N/A — do not invent a context, a Domain document, or a BR row to tick
+> one.
+
 ### bugfix/ branch — Before Creating
 
+> **A `bugfix/` branch is always a minimal (zero-phase) host**, so the
+> minimal-host list above applies here **in full** — the `_index.md` shape, the
+> authoritative `branch:` field, and the artifact's declaration of the paths it
+> touches, which is what closeout blocks on. Every route that cuts one opens the
+> host through `references/modify-existing-flow.md` **Step 1.7's mechanics** —
+> its own numbered **step 4**, "Branch gate — by change class". The known routes
+> are Step 1.7 directly, Step 1.6's minimal follow-up variant, and Step 1.8's
+> post-hoc hotfix; the latter two delegate to that same step (steps 2–4), and a
+> route added later reaches it the same way.
+> Not the top-level `## Step 4`, which cuts no branch. A **T1**
+> escalates to `feature/`, a defect hosted under a phase-bearing feature never
+> gets a branch of its own, and a baseline capture is not a functional bug so it
+> cuts `feature/`. This matters because a functional bug walks **this** gate and
+> never the `feature/` one. The items below are what `bugfix/` adds on top.
+
 AI should verify:
-- [ ] Lightweight spec exists or is created during this session
-- [ ] Root cause is documented
+- [ ] **The tier's artifact** exists or is created during this session — a
+      **lightweight spec** for a T2; for a **T3**, the host `_index.md`
+      Lightweight Changes row and *no* spec file, exactly as the branch map
+      above says. A T3 spec file does not exist in Dflow, so asking for one
+      blocks the change instead of documenting it. A **T1** does not belong on
+      a `bugfix/` branch — escalate it to `feature/`.
+- [ ] Root cause is documented — a T2's `## Root Cause`, or the evidence
+      section its no-BR family substitutes for it; for a **T3** the row
+      Description is the whole record and there is no separate root-cause
+      artifact
 - [ ] Fix approach is noted
 
 ### bugfix/ branch — Before Merging (Pre-PR / Pre-Integration)
 
-- [ ] Spec has the fix documented
+- [ ] `_index.md` status: `completed`
+- [ ] **Closeout complete**: `/dflow:finish-feature` has announced closeout
+      complete for this host — its Local-closeout gate is satisfied (the
+      closeout commit landed and passed post-commit verification) and, if
+      the host carries `follow-up-of`, the Step 6 tracking commit has also
+      landed and been verified. `status: completed` or a directory already
+      under `completed/` does not show this on its own.
+      A `bugfix/` host closes out exactly like a `feature/` one; an
+      un-closed-out host must not merge.
+- [ ] **The tier's artifact** has the fix documented — a **T2**'s lightweight
+      spec, or for a **T3** the host `_index.md` Lightweight Changes row, which
+      is its whole record. Do not ask a T3 for a spec file here either: the
+      Before-Creating item above says why, and this gate is the last place that
+      mistake can still block the merge.
 - [ ] Tech debt recorded if the underlying issue is broader (record in
       `dflow/specs/migration/tech-debt.md` if the bug reveals a systemic issue)
 - [ ] If business logic was touched, evaluate Domain extraction
@@ -381,7 +560,7 @@ Examples:
 
 These checks could eventually be automated in CI:
 - Verify no delivery-framework references in `src/Domain/` directory
-- Verify spec file exists for any branch with feature/ or bugfix/ prefix
+- Verify a spec file exists for any branch with feature/ or bugfix/ prefix — except a host whose entire record is inline in its `_index.md` and therefore has no spec file by design (a T3-only host or a baseline-only capture today, and any later shape with that same property); check for the row instead
 - Verify glossary.md and rules.md were updated when Domain/ files change
 - Lint commit messages for spec ID format
 

package/templates/brownfield/references/init-project-flow.md

@@ -236,8 +236,18 @@ Key Brownfield-track notes:
 - **`behavior.md` is NOT generated here.** Per F-05, per-context
   `behavior.md` files are created by `/dflow:new-feature` Step 8.3
   (completion flow) or by the P007a baseline-capture flow at the moment
-  the first bounded context is established. Creating empty
-  `behavior.md` files here would create stale placeholders.
+  the first bounded context is established.
+- **`analysis.md` is NOT generated here**, at either of its paths. It holds
+  the system-level knowledge no single context document owns — 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), and the spots in them this project keeps
+  working around until a domain decision settles them (each in the copy that
+  holds the knowledge it is stuck on). What one context owns is recorded in
+  `domain/{context}/analysis.md` and the rest in `domain/analysis.md`, each
+  created from `templates/analysis.md` the first time a session records
+  something that belongs there.
 - `domain/context-map.md` is **not** mandatory in the Brownfield track
   (contexts emerge organically during domain extraction; the Greenfield
   track makes this file mandatory because BCs are usually planned
@@ -288,13 +298,20 @@ skip, and wait for developer confirmation:
 > |---|---|
 > | `dflow/specs/domain/glossary.md` | already exists (47 lines) |
 >
-> **Not creating** (per F-05 decision):
+> **Not creating**:
 > - No `dflow/specs/domain/{context}/behavior.md` files. These are created
 >   later by `/dflow:new-feature` Step 8.3 or P007a when the first
 >   bounded context is established.
 > - No `dflow/specs/domain/context-map.md`. Brownfield track treats BCs as
 >   emergent from domain extraction; this file becomes relevant later,
 >   typically when 2+ contexts coexist.
+> - No `dflow/specs/domain/analysis.md` and no
+>   `dflow/specs/domain/{context}/analysis.md`. Each is created the first time
+>   one of these turns up and belongs there — an ordered cross-context flow
+>   (always the domain-root copy), the lifecycle of a status field, a derived
+>   figure, a mechanism no single rule explains, which roles reach which
+>   function (always the domain-root copy), or a spot in one of them this
+>   project keeps working around until a domain decision settles it.
 >
 > Looks good? Reply 'yes' to proceed with the writes, or tell me what to
 > adjust."
@@ -432,6 +449,9 @@ Init complete. Summary:
       Step 8.3 or P007a baseline capture
     - dflow/specs/domain/context-map.md — created organically when you have
       ≥2 bounded contexts
+    - dflow/specs/domain/{context}/analysis.md — needs a real bounded context
+    - dflow/specs/domain/analysis.md — created the first time a session records a
+      cross-context flow, role reach, or other knowledge no single context owns
 ```
 
 ### 5.2 Next-step recommendation