dflow-sdd-ddd 0.7.0 → 0.9.0

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

@@ -0,0 +1,195 @@
+# Drift Verification — rules.md ↔ behavior.md Consistency Check
+
+Triggered by `/dflow:verify` or `/dflow:verify <bounded-context>`.
+
+## Purpose
+
+The A+C structure (`rules.md` as index + `behavior.md` as scenario content) introduces a drift risk — the two files can fall out of sync. This command provides a mechanical verification safety net that developers can run at key moments: before a PR, after a refactor, or when onboarding to an unfamiliar Bounded Context.
+
+## Scope
+
+### This command does (mechanical layer)
+
+Three string-matching checks that AI can perform deterministically:
+
+1. **BR-ID forward check**: Every `BR-*` declared in `rules.md` has a corresponding section in `behavior.md`
+2. **Anchor validity**: If `rules.md` links to `behavior.md#section`, that anchor exists
+3. **BR-ID reverse check**: Every `BR-*` referenced in `behavior.md` is declared in `rules.md`
+
+### This command does NOT do (semantic layer — explicitly excluded)
+
+Semantic verification (LLM reads the one-line summary in `rules.md` vs the Given/When/Then in `behavior.md` and judges whether they contradict) is **out of scope**. Reasons:
+- Mechanical checks already catch most drift (missing IDs, broken links)
+- Semantic judgment costs tokens and requires human review of LLM conclusions
+- Deferred to Wave D — revisit after 10+ verify runs show the type distribution of actual drift
+
+### This command does NOT do (feature-directory aggregation — explicitly excluded)
+
+Given the feature directory layout
+(`dflow/specs/features/active/{SPEC-ID}-{slug}/` containing `_index.md` plus
+0..N `phase-spec-*.md` and 0..N `lightweight-*.md`), a tempting but
+**out-of-scope** extension would be: "make `/dflow:verify` aggregate BR
+state across all phase-spec files in a feature, then cross-check against
+`rules.md`." Don't do that here.
+
+Reasons:
+- Feature-level BR aggregation is already maintained by `_index.md`
+  Current BR Snapshot, refreshed by `/dflow:new-phase` Step 5, reconciled
+  by `/dflow:new-phase` Step 7, and promoted by `/dflow:finish-feature`
+  Step 3
+- BC-level current state is already maintained by `rules.md` /
+  `behavior.md` / `events.md`, written by the same
+  `/dflow:finish-feature` Step 3
+- `/dflow:verify` keeps a small, mechanical scope: just the
+  `rules.md` ↔ `behavior.md` correspondence inside one BC, plus the
+  events.md bonus check below
+- Cross-feature / cross-phase aggregation would mix `/dflow:verify`'s
+  job with `/dflow:finish-feature`'s job and produce false positives
+  during in-progress features
+
+If a future need arises to add an `_index.md` Current BR Snapshot ↔
+`rules.md` cross-check, that belongs in a future extension,
+not in this command's current scope.
+
+### Anchor coexistence with `dflow:section`
+
+`dflow:section` HTML comment anchors and markdown heading anchors serve different purposes:
+
+- Markdown heading anchors (e.g., `behavior.md#br-001-rule-name`) remain the primary link target for BR-ID verification.
+- `<!-- dflow:section ... -->` anchors are helper markers for AI/tool section positioning only.
+- `dflow:section` does **not** replace BR-ID markdown anchors, and does **not** change the drift-verification algorithm.
+
+So this command still uses BR-ID + markdown auto-id anchors as its primary index; `dflow:section` is auxiliary metadata.
+
+## Usage
+
+```
+/dflow:verify            # Verify all Bounded Contexts
+/dflow:verify Expense    # Verify a single BC (recommended default)
+```
+
+When verifying all BCs, run each context independently and report per-context results.
+
+## Verification Steps
+
+For each Bounded Context:
+
+### Step 1: Locate files
+
+- Find `dflow/specs/domain/{context}/rules.md`
+- Find `dflow/specs/domain/{context}/behavior.md`
+- If either is missing, report and stop for that context:
+  ```
+  ✗ Expense: rules.md exists but behavior.md is missing
+    → Create the missing file using the matching template:
+      - rules.md → templates/rules.md
+      - behavior.md → templates/behavior.md
+      Or run the completion flow to populate it from existing completed specs
+  ```
+
+### Step 2: Extract BR-IDs from rules.md
+
+Scan `rules.md` for all `BR-*` identifiers. Record each ID and any anchor link to `behavior.md`.
+
+### Step 3: Extract BR-IDs from behavior.md
+
+Build two sets:
+
+- **Primary set (scenario-bound)**: BR-IDs that appear in section headings
+  (e.g. `## Amount Validation (BR-001)`) or in the formal `(BR-NNN)` marker
+  inside a Given/When/Then scenario block. These represent BR-IDs that have
+  a dedicated scenario section.
+- **Supplementary set (body-text mentions)**: BR-IDs that appear only in
+  prose / discussion text, outside any Given/When/Then block. These are
+  informational references, not equivalent to a scenario section.
+
+### Step 4: Cross-reference
+
+Run the three checks using the primary set from Step 3 as the main comparison basis:
+
+| Check | Pass condition | Fail message |
+|---|---|---|
+| Forward | Every BR-ID in rules.md has a corresponding scenario section in behavior.md (primary set) | `✗ BR-NNN declared in rules.md but has no scenario section in behavior.md` |
+| Anchor | Every `behavior.md#anchor` in rules.md resolves to an existing heading | `✗ BR-NNN links to behavior.md#section but anchor not found` |
+| Reverse | Every BR-ID formally referenced in behavior.md (primary set) is declared in rules.md | `✗ BR-NNN referenced in behavior.md scenario but not declared in rules.md` |
+
+Body-text mentions (supplementary set) do **not** satisfy forward / reverse
+pass conditions on their own. They are reported separately as informational
+signals (see Step 5).
+
+### Step 5: Report
+
+Output format:
+
+```
+Verifying {Context} — rules.md ↔ behavior.md consistency
+
+✓ BR-001 → scenario section exists and references BR-001
+✓ BR-002 → scenario section exists and references BR-002
+✗ BR-003 → behavior.md has no scenario section for BR-003
+          (note: BR-003 appears in body text of another section,
+           but that does not satisfy the forward check)
+ℹ BR-005 → body text reference only — no dedicated scenario section;
+           confirm this is intentional (e.g. cross-reference to another BR)
+
+✗ BR-010 → formally referenced in a behavior.md scenario but not
+          declared in rules.md
+
+Summary: 3 passed, 2 issues, 1 informational
+
+Issues:
+1. rules.md declares BR-003, but behavior.md has no corresponding
+   scenario section
+   → Possible cause: rule was implemented but behavior.md wasn't
+     updated in the completion flow; or a body-text mention was
+     mistaken for a scenario
+   → Action: check the implementation, then either add the scenario
+     to behavior.md (preferred) or remove BR-003 from rules.md if
+     deprecated
+
+2. behavior.md's {scenario section name} formally references BR-010,
+   but rules.md doesn't declare it
+   → Possible cause: scenario was added directly to behavior.md
+     without updating rules.md
+   → Action: add BR-010 to rules.md with a one-line summary, or
+     remove the stale scenario reference from behavior.md
+```
+
+## Core-Specific Notes
+
+When verifying a Core context, also check:
+- `events.md` references in `behavior.md`: if a scenario says "And {DomainEvent} is raised", confirm the event is listed in `events.md`
+- This is a **bonus check**, not a blocking failure — report as a warning:
+  ```
+  ⚠ BR-001 scenario references ExpenseReportSubmitted event,
+    but events.md does not list it
+  ```
+
+## When to Run
+
+Recommended trigger points (not enforced — developer's judgment):
+- Before creating a PR (`/dflow:verify` as a pre-PR sanity check)
+- After a refactor that touched multiple specs or domain docs
+- When onboarding to an unfamiliar Bounded Context (verify before trusting the docs)
+- After running `/dflow:finish-feature` — that command writes BC layer
+  updates from the feature's `_index.md` Current BR Snapshot; verify
+  catches any anchor / link drift introduced by the merge
+
+## Path Assumptions
+
+This command operates entirely within `dflow/specs/domain/{context}/` files
+(`rules.md`, `behavior.md`, and the `events.md` bonus check). It does
+**not** read from `dflow/specs/features/active/{SPEC-ID}-{slug}/` directories
+— the feature directory layout is not part of verify's input. The only effect of feature directory layout on this
+command is ensuring `last-updated` dates in `behavior.md` are bumped at
+`/dflow:finish-feature` time (so verify's mechanical drift guard stays
+useful).
+
+## Interaction with Other Commands
+
+- `/dflow:verify` is a **standalone command** — it does not require an active workflow
+- It can be run mid-workflow (e.g., during Step 7 implementation to check you haven't drifted)
+- It can be run after `/dflow:finish-feature` lands — that's the moment
+  BC-layer files get rewritten; verify catches mechanical issues from
+  the merge
+- If issues are found, the developer decides whether to fix now or defer — the command does not block other workflows

package/templates/greenfield/references/finish-feature-flow.md

@@ -0,0 +1,314 @@
+# Finish Feature Workflow — Greenfield Clean Architecture
+
+Step-by-step guide for when a developer triggers `/dflow:finish-feature` —
+the feature closeout ceremony.
+
+This command makes the previously-implicit closeout step (originally a
+sub-step of `new-feature-flow` / `modify-existing-flow`) explicit and
+directly callable. It validates that all phase-specs are completed,
+syncs the feature-level BR Snapshot to the bounded context's system-level
+state, archives the feature directory, and emits a Git-strategy-neutral
+**Integration Summary** for the developer's PR / merge / push step.
+
+**Important boundaries**:
+- This command **does not auto-merge** and never pushes or opens a PR on its
+  own. Merge strategy follows the team's selected Git policy (`gitflow` /
+  `trunk`, recorded in `dflow/specs/shared/_conventions.md` § Git Policy).
+- Closeout is split into two gates so it works offline: a **Local-closeout
+  gate** (Steps 1–4: validation, status flip, BC sync, archive + an optional
+  commit checkpoint — all doable with no network) and an **Integration / PR
+  gate** (Step 5: push / merge / PR — needs network; the AI only runs
+  `git push` / `gh pr create` when you explicitly ask).
+- At the archive checkpoint the AI may offer to commit using your Git identity;
+  you can always decline. The commit marker mode is read from `_conventions.md`
+  § AI Commit Policy. This replaces Dflow's earlier "the AI never commits"
+  stance — the AI helps at natural checkpoints, you keep the final say.
+- The BC-layer sync in Step 3 **reuses the existing Step 5.3 mechanism**
+  from `new-feature-flow` (Step 8.3) and `modify-existing-flow` (Step
+  5.3) — it does not introduce a new sync flow. Treat it as "lift Step
+  5.3 / 8.3 out of the per-phase checklist and run it once at feature
+  closeout, with the `_index.md` Current BR Snapshot as input."
+
+**Step Gates** in this flow (stop-and-confirm before proceeding):
+- Step 1 → Step 2 (validation passed → flip status)
+- Step 3 → Step 4 (BC sync done → archive)
+- Step 5 → Step 6 (Integration Summary emitted → optional follow-up reverse-link)
+
+All other step transitions are **step-internal**: announce "Step N complete,
+entering Step N+1" and proceed without waiting. See SKILL.md § Workflow
+Transparency for the full transparency protocol and confirmation signals.
+
+## Step 1: Validate Phase Specs and `_index.md`
+
+Before producing any closeout prose or Integration Summary text, read
+`dflow/specs/shared/_conventions.md` and apply the `## Prose Language`
+setting. If the setting is missing or not an explicit language tag, ask the
+developer to update `_conventions.md` before continuing.
+
+AI runs mechanical checks first. Report `✓` / `✗` for every item; if any
+`✗` appears, **stop here** and ask the developer to address them before
+proceeding (do not flip status, do not archive, do not emit summary).
+
+- [ ] Locate the feature directory at `dflow/specs/features/active/{SPEC-ID}-{slug}/`
+- [ ] `_index.md` exists and parses (YAML front matter intact, seven required
+      sections present, including the Checkpoint Log)
+- [ ] Every row in `_index.md` Phase Specs table has Status = `completed`
+- [ ] Every phase-spec file referenced in the Phase Specs table exists at
+      the path the table claims
+- [ ] Every phase-spec file's frontmatter has `status: completed`
+- [ ] `_index.md` has no obvious open items in Resume Pointer (e.g. "phase-N
+      drafting" / "implementation pending" / "TODO" markers)
+- [ ] Current BR Snapshot table is non-empty (or feature is intentionally
+      a no-BR feature — confirm with developer if uncertain)
+
+If any check fails:
+> "Cannot finish feature `{SPEC-ID}-{slug}` yet — {N} validation issues
+> found:
+>   ✗ phase-spec-2026-04-15-foo.md status is still `in-progress`
+>   ✗ Phase Specs table row 3 references missing file phase-spec-...
+>
+> Address these (run `/dflow:new-phase` to add missing work, or fix the
+> stale status manually), then re-run `/dflow:finish-feature`."
+
+**→ Step Gate: Step 1 → Step 2**
+
+If all checks pass:
+> "All {N} phase-specs are completed and `_index.md` is internally
+> consistent. Ready to flip the feature status to `completed`?
+> `/dflow:next` to proceed."
+
+Wait for confirmation before entering Step 2.
+
+## Step 2: Flip `_index.md` Status to `completed`
+
+Update the feature's `_index.md` Metadata block:
+
+```yaml
+---
+spec-id: SPEC-{YYYYMMDD}-{NNN}
+slug: {slug}
+status: completed         # ← flipped from in-progress
+created: {YYYY-MM-DD}
+branch: feature/{SPEC-ID}-{slug}
+---
+```
+
+Also update the **Resume Pointer** to reflect closeout:
+
+```
+**Current Progress**: feature completed ({date}); all phase-specs status = completed.
+**Next Action**: integration — push / merge / PR per the selected Git policy.
+```
+
+**→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (status flipped). Entering Step 3: Sync BR Snapshot to BC layer." and continue.
+
+## Step 3: Sync `_index.md` Current BR Snapshot to BC Layer
+
+This step **reuses the existing sync mechanism** from `new-feature-flow`
+Step 8.3 / `modify-existing-flow` Step 5.3 (`dflow/specs/domain/{context}/rules.md`
++ `behavior.md` + `events.md` + `context-map.md` updates). The input is
+the feature's `_index.md` Current BR Snapshot table; the output is the
+BC's `rules.md` / `behavior.md` updated to reflect the feature's net
+effect.
+
+Before syncing, ensure required BC files exist. If missing, create from templates:
+- `dflow/specs/domain/{context}/rules.md` → `templates/rules.md`
+- `dflow/specs/domain/{context}/behavior.md` → `templates/behavior.md`
+- `dflow/specs/domain/{context}/events.md` → `templates/events.md`
+
+For each row in Current BR Snapshot where Status = `active`:
+
+- If the BR-ID is **not yet in `rules.md`** → add it (new ADDED rule
+  introduced by this feature)
+- If the BR-ID is **already in `rules.md`** but the rule text differs →
+  update it (MODIFIED rule, reflect the new text)
+- If the BR-ID was previously in `rules.md` and is now in Current BR
+  Snapshot with Status = `removed` → remove the corresponding section in
+  `rules.md` (REMOVED rule)
+- For any RENAMED BR-ID → rename the BR-ID in `rules.md` and update
+  `glossary.md` if the term itself changed
+
+For `behavior.md`:
+
+- For every BR-ID still active after this feature, ensure
+  `dflow/specs/domain/{context}/behavior.md` has a scenario section (anchor)
+  matching the BR-ID; the scenario should include Aggregate state
+  transitions and Domain Events as appropriate
+- For REMOVED BR-IDs, delete the corresponding scenario section from
+  `behavior.md`
+- Update the BR-ID anchor's `last-updated` date in `behavior.md` to today
+
+For `events.md`:
+- Add any new Domain Events introduced by phase-specs in this feature
+- Remove events that were REMOVED across the feature's net delta
+- Update producers / consumers if Aggregate ownership shifted
+
+For `context-map.md`:
+- Update if any cross-context interaction was added, changed, or removed
+  across the feature
+
+This is the **mechanical input that `/dflow:verify` later uses** for the
+rules.md ↔ behavior.md drift check (see `references/drift-verification.md`).
+
+Cross-reference each phase-spec's Delta-from-prior-phases section to
+double-check the net result; the Snapshot is the SSOT but the per-phase
+Deltas are the audit trail.
+
+> Note: this step does NOT read individual phase-specs to re-derive the BR
+> set — that work was already reconciled by `/dflow:new-phase` Step 7 each
+> time a phase completed. We trust `_index.md` Current BR Snapshot as the
+> feature-level truth here. If the developer finds drift between Snapshot
+> and the phase-specs, fix `_index.md` first, then re-run
+> `/dflow:finish-feature`.
+
+Also update `architecture/tech-debt.md` / `models.md` / `glossary.md` as
+discovered during the feature (the same items listed in
+`new-feature-flow.md` Step 8.3) — these may have been touched per phase
+already; this is the closeout sweep.
+
+**→ Step Gate: Step 3 → Step 4**
+
+> "BC `{context}` synced — `rules.md` updated ({n_added} added,
+> {n_modified} modified, {n_removed} removed), `behavior.md` anchors
+> updated, `events.md` reflects {n_events} new / changed events,
+> `context-map.md` {updated / unchanged}, `last-updated` set to {date}.
+> Ready to archive the feature directory? `/dflow:next` to proceed."
+
+Wait for confirmation before entering Step 4.
+
+## Step 4: Archive — `git mv` the Feature Directory
+
+AI runs:
+
+```bash
+git mv dflow/specs/features/active/{SPEC-ID}-{slug} \
+       dflow/specs/features/completed/{SPEC-ID}-{slug}
+git status   # confirm rename detection
+```
+
+`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. See
+`references/git-integration.md` § "Directory Moves Must Use git mv" for
+the full rule set.
+
+After the move, also `git add` any modified files from Step 3 (the
+updated `rules.md`, `behavior.md`, `events.md`, `context-map.md`,
+`glossary.md`, `architecture/tech-debt.md`, etc.) into the same stage.
+
+**Closeout commit checkpoint** (completes the offline Local-closeout gate):
+
+```
+✓ Feature archived to completed/ and closeout files staged
+   Commit this closeout now?
+   [Y] Yes — the AI commits with your Git identity (marker per _conventions.md § AI Commit Policy)
+   [N] No — skip; you commit yourself
+```
+
+Whether you choose Y or N, record one row in the feature `_index.md`
+Checkpoint Log (`closeout | committed ({hash})` or `closeout | skipped`). Only
+write a hash after the commit actually succeeds; if a pre-commit hook rejects it
+or the commit fails, record `failed` and surface the error — never write a fake
+hash.
+
+The Local-closeout gate is satisfied **only when the closeout is committed**:
+closeout complete, Checkpoint Log updated, and the working tree clean (no
+uncommitted changes). If you declined the commit (chose N) or it failed,
+Local-closeout is **not** satisfied yet — commit the staged closeout yourself
+before continuing; do not enter the Integration / PR gate with uncommitted
+changes. Once committed, the gate stands on its own offline; integration happens
+in Step 5 when you have network.
+
+**→ Transition (step-internal)**: Step 4 complete. Branch on whether the closeout commit landed:
+
+- **Closeout commit landed (working tree clean)** → announce "Step 4 complete (feature archived; Local-closeout gate satisfied). Entering Step 5: Integration / PR gate." and continue.
+- **Closeout commit was declined (N) or failed** → **stop here.** Announce "Step 4 complete (feature archived), but the Local-closeout gate is not satisfied yet — the closeout is staged but uncommitted. Commit those changes (or address the failure), then resume to Step 5." Do **not** enter Step 5 with uncommitted closeout changes.
+
+## Step 5: Emit Integration Summary (Git-strategy-neutral)
+
+Produce a plain-text summary of what this feature did. The summary is
+**not** a commit message template — it is reference material the
+developer adapts to whichever merge strategy their project uses
+(merge commit, squash, rebase, fast-forward — Dflow stays neutral).
+
+The selected Git policy's `Git-principles-{gitflow|trunk}.md` (seeded at init
+under `dflow/specs/shared/`) explains, in its "Integration Commit Message
+Conventions" section, how to format the actual commit / merge message from this
+summary.
+
+Format:
+
+```
+== Integration Summary: {SPEC-ID}-{slug} ==
+
+Feature Goal: {1-2 sentences from _index.md Goals & Scope}
+
+Change Scope:
+- BC: {context-name}
+- Aggregates affected: {Aggregate1}, {Aggregate2}
+- Phase Count: {N} (phase-spec-{date1}-{slug1} ... phase-spec-{dateN}-{slugN})
+- Lightweight Changes: {n_t2} T2 lightweight specs + {n_t3} T3 inline rows
+
+Related BR-IDs (post-closeout state):
+- ADDED: BR-NN, BR-NN, ...
+- MODIFIED: BR-NN, BR-NN, ...
+- REMOVED: BR-NN, BR-NN, ...
+
+Domain Events Changes:
+- ADDED: {Event1}, {Event2}
+- MODIFIED: {Event3}
+- REMOVED: {Event4}
+
+Phase List:
+- phase-1 ({date}): {phase-slug} — {1 line}
+- phase-2 ({date}): {phase-slug} — {1 line}
+- ...
+
+Next Steps (developer) — Integration / PR gate (needs network):
+- Per the selected Git policy (`gitflow` / `trunk` in `_conventions.md`), choose
+  a merge strategy (merge commit / squash / rebase / fast-forward) and execute
+- Push to remote / open a PR — the AI can run `git push` / `gh pr create` for
+  you, but only when you explicitly ask; it never pushes on its own
+```
+
+Print the summary to the conversation; do not write it to a file (it is
+ephemeral closeout output).
+
+**→ Step Gate: Step 5 → Step 6**
+
+If the feature has `follow-up-of: {原 SPEC-ID}` in its Metadata, prompt
+the developer:
+> "This feature is a follow-up of `{原 SPEC-ID}`. Ready to update the
+> original feature's `_index.md` Follow-up Tracking row to mark this
+> follow-up as `completed`? `/dflow:next` to proceed (or skip if you
+> prefer to do it manually)."
+
+If no `follow-up-of` field, skip Step 6 and announce closeout complete:
+> "`/dflow:finish-feature` complete for `{SPEC-ID}-{slug}`. Feature
+> directory is now at `dflow/specs/features/completed/{SPEC-ID}-{slug}/`.
+> If you skipped the closeout commit, commit the staged changes first to
+> finish the Local-closeout gate. Then integration — merge / push / PR —
+> follows the selected Git policy, at your discretion."
+
+## Step 6: Reverse-Update Follow-up Tracking (only if follow-up)
+
+For features that were created as follow-ups of an earlier completed
+feature, update the original feature's
+Follow-up Tracking table.
+
+1. Locate `dflow/specs/features/completed/{原 SPEC-ID}-{原 slug}/_index.md`
+2. Find the Follow-up Tracking section's row for this feature's SPEC-ID
+3. Flip Status → `completed`
+
+```bash
+# The AI makes the edit and may offer to commit it (Y / N), per the AI commit policy
+```
+
+After the update:
+> "Follow-up Tracking row in `{原 SPEC-ID}-{原 slug}/_index.md` updated
+> to Status = `completed`. Closeout complete."
+
+The connection is bidirectional and weakly redundant: the new feature's
+`follow-up-of` field is the authoritative source; the old feature's
+Follow-up Tracking row is a derived index. If they ever disagree, trust
+`follow-up-of`.