dflow-sdd-ddd 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {
@@ -39,7 +39,7 @@
   },
   "homepage": "https://github.com/weilung/dflow-sdd-ddd#readme",
   "scripts": {
-    "test": "node test/smoke.mjs"
+    "test": "node test/smoke.mjs && node test/registry-parity.mjs && node test/agent-inject.mjs"
   },
   "license": "AGPL-3.0-or-later",
   "publishConfig": {

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

@@ -168,10 +168,7 @@ Recommended trigger points (not enforced — developer's judgment):
 This command operates entirely within `dflow/specs/domain/{context}/` files
 (`rules.md` and `behavior.md`). 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).
+directory layout is not part of verify's input.
 
 ## Interaction with Other Commands
 

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

@@ -34,7 +34,7 @@ state, archives the feature directory, and emits a Git-strategy-neutral
 - 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
+entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow
 Transparency for the full transparency protocol and confirmation signals.
 
 ## Step 1: Validate Phase Specs and `_index.md`
@@ -124,6 +124,8 @@ For each row in Current BR Snapshot where Status = `active`:
   `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 every BR-ID added, modified, or renamed above, set its `Last updated`
+  date in `rules.md`'s Rule Index to today
 
 For `behavior.md`:
 
@@ -132,7 +134,6 @@ For `behavior.md`:
   matching the BR-ID
 - 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
 
 This is the **mechanical input that `/dflow:verify` later uses** for the
 rules.md ↔ behavior.md drift check (see `references/drift-verification.md`).

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

@@ -181,7 +181,6 @@ diff. That breaks:
 - `git blame` on lines that crossed the rename boundary
 - PR diff quality (reviewers see two unrelated big-blob changes
   instead of one rename + small content diff)
-- `/dflow:verify` and other tools that walk feature history
 
 This is a known weakness of OpenSpec's directory-rename pattern; Dflow
 deliberately avoids it by mandating `git mv`.

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

@@ -49,8 +49,8 @@ Report findings plainly:
 >  - `dflow/specs/`: not yet present → greenfield Dflow setup
 >  - `specs/`: present → legacy / other-tool directory; Dflow V1 will not
 >    migrate or modify it
->  - `CLAUDE.md`: present → will not overwrite; I'll offer a snippet
->    to merge into it"
+>  - `CLAUDE.md`: present → I'll append a marked Dflow block (shown in
+>    the preview); a merge snippet only if there's a marker conflict"
 
 Or:
 
@@ -162,9 +162,10 @@ Wait for answers.
 >
 > If you select any agent, Dflow will create
 > `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical guide. Root-level
-> tool files stay thin and point back to that guide. Existing tool files are
-> never overwritten; Dflow writes merge snippets under `dflow/specs/shared/`
-> instead."
+> tool files stay thin and point back to that guide. Existing user content is
+> never overwritten; Dflow appends a marked Dflow block (shown in the preview)
+> and refreshes it in place on re-run. Merge snippets under
+> `dflow/specs/shared/` are used only if Dflow markers conflict."
 
 **→ Transition (step-internal)**: Step 2 complete. Announce
 > "Step 2 complete (project information captured). Entering Step 3:
@@ -228,16 +229,17 @@ vendored workflow bundle). Compute the destination path:
 | `scaffolding/Git-principles-trunk.md` | `dflow/specs/shared/Git-principles-trunk.md` |
 | `scaffolding/AI-AGENT-GUIDE.md` | `dflow/specs/shared/AI-AGENT-GUIDE.md` when at least one AI agent is selected |
 | generated tool shim | `AGENTS.md`, `CLAUDE.md`, or `.github/copilot-instructions.md` when selected and missing |
-| generated merge snippet | `dflow/specs/shared/*-snippet.md` when the selected tool file already exists |
+| marked Dflow block | appended to a selected existing tool file unless it already points to `AI-AGENT-GUIDE.md`; refreshed in place on re-run |
+| fallback merge snippet | `dflow/specs/shared/*-snippet.md` only when the selected tool file has conflicting or malformed Dflow markers |
 
 ### 3.3 Present the preview
 
-Present the complete file list as two tables, separating create vs
+Present the complete file list as two tables, separating create / update vs
 skip, and wait for developer confirmation:
 
 > "Based on Step 1 inventory + Step 2 answers, here is what I'll do:
 >
-> **Will create ({N} files):**
+> **Will create / update ({N} files):**
 >
 > | Path | Source |
 > |---|---|
@@ -250,7 +252,7 @@ skip, and wait for developer confirmation:
 > | `dflow/specs/shared/_overview.md` | optional (you picked it) |
 > | `dflow/specs/shared/Git-principles-trunk.md` | mandatory (selected Git policy) |
 > | `dflow/specs/shared/AI-AGENT-GUIDE.md` | selected AI agent guide |
-> | `CLAUDE.md` | selected tool shim because repo has no CLAUDE.md |
+> | `CLAUDE.md` | marked Dflow block appended to existing CLAUDE.md (shown in preview) |
 >
 > **Will skip ({M} files — already present):**
 >
@@ -325,11 +327,24 @@ guide.
 For each selected tool-specific file (`AGENTS.md`, `CLAUDE.md`,
 `.github/copilot-instructions.md`):
 
+(checked in this order — the first matching rule wins):
+
 - if the target file does not exist, create a small shim at the target
   path that points to `dflow/specs/shared/AI-AGENT-GUIDE.md`
-- if the target file already exists, do not overwrite it; write a merge
-  snippet under `dflow/specs/shared/` and report that the developer
-  should merge it manually
+- if the target file contains conflicting or malformed Dflow markers, do not
+  edit it; write a fallback merge snippet under `dflow/specs/shared/` and
+  report that the developer should merge it manually
+- if the target file already contains a single well-formed Dflow marked block,
+  replace that block in place (idempotent refresh) and keep the rest of the
+  file unchanged
+- if the target file is an existing whole-file Dflow-generated shim, refresh it
+  in place
+- if the target file already points to the guide through the developer's own
+  pointer (and has no Dflow marked block), leave it untouched
+- otherwise preserve the existing content and append a marked Dflow block at
+  the end of the file, keeping the file's dominant line ending; show that block
+  in the preview, and refresh that same block on re-run. If the developer later
+  deletes the block, a later `init` / `configure-agents` run appends it again
 
 ### 4.4 Directory-only entries
 
@@ -354,7 +369,7 @@ Summarise what actually happened and point at the next command.
 ```
 Init complete. Summary:
 
-  Created ({N} files):
+  Created / Updated ({N} files):
     ✓ dflow/specs/features/active/.gitkeep
     ✓ dflow/specs/features/completed/.gitkeep
     ✓ dflow/specs/features/backlog/.gitkeep
@@ -363,7 +378,7 @@ Init complete. Summary:
     ✓ dflow/specs/migration/tech-debt.md
     ✓ dflow/specs/shared/_overview.md
     ✓ dflow/specs/shared/Git-principles-trunk.md
-    ✓ CLAUDE.md (seeded from scaffolding snippet)
+    ✓ CLAUDE.md (marked Dflow block appended)
 
   Skipped ({M} files already present):
     - (none this run)
@@ -412,9 +427,8 @@ Remind the developer to review files that have `{placeholder}` tokens
 still in them:
 
 > "A few files still have `{placeholder}` tokens that need your input:
->  - `dflow/specs/shared/_overview.md`: `{業務領域}`, `{團隊}`,
->    `{使用者規模}`
->  - `CLAUDE.md`: `{業務領域}`
+>  - `dflow/specs/shared/_overview.md`: the Business Domain and Technical
+>    Architecture fields (e.g. primary domain, stakeholders, user scale, stack)
 >
 >  These are fine to leave for now; fill them in during your next
 >  review pass."

package/templates/brownfield/references/modify-existing-flow.md

@@ -1,15 +1,15 @@
 # Modify Existing Feature Workflow
 
-Step-by-step guide for when a developer triggers `/dflow:modify-existing` or `/dflow:bug-fix` (or natural language implying a modification task — see SKILL.md § Workflow Transparency for the auto-trigger safety net).
+Step-by-step guide for when a developer triggers `/dflow:modify-existing` or `/dflow:bug-fix` (or natural language implying a modification task — see AI-AGENT-GUIDE.md § Workflow Transparency for the auto-trigger safety net).
 
 **Step Gates** in this flow (stop-and-confirm before proceeding):
 - Step 2 → Step 3 (baseline captured → analyze business logic embedded in delivery/entrypoint code: presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures)
 - Step 4 → Step 5 (extraction decision → start implementation)
 - Step 5 → Step 6 (implementation done → update artifacts)
 
-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.
+All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow Transparency for the full transparency protocol and confirmation signals.
 
-**Ceremony adjustment when triggered by `/dflow:bug-fix`**: treat as lightweight — use the Lightweight Spec Template at the end of this file instead of the full spec, and Step 4 (extraction) may default to "defer and record in tech-debt.md" unless the bug itself is in extractable logic. T2 still generates a concise `Implementation Tasks` checklist (see Step 4).
+**Ceremony adjustment when triggered by `/dflow:bug-fix`**: treat as lightweight — use the Lightweight Spec Template (see `templates/lightweight-spec.md`) instead of the full spec, and Step 4 (extraction) may default to "defer and record in tech-debt.md" unless the bug itself is in extractable logic. T2 still generates a concise `Implementation Tasks` checklist (see Step 4).
 
 ## Mindset
 
@@ -31,7 +31,7 @@ This step has two parallel concerns:
 
 **Part A — Determine the Ceremony Tier (T1 / T2 / T3)**
 
-Dflow runs three ceremony tiers (full table in SKILL.md § Ceremony Scaling).
+Dflow runs three ceremony tiers (full table in AI-AGENT-GUIDE.md § Ceremony Scaling).
 For a modification, AI judges which tier fits before deciding what to
 produce:
 
@@ -141,7 +141,7 @@ add a row:
 | {新 SPEC-ID} | {新 slug} | {today} | in-progress |
 ```
 
-This update is **part of the same change set** (the developer commits
+This update is **part of the same change set** (offer to commit
 both at once; commit message should mention "Add follow-up reference to
 `{新 SPEC-ID}`"). The reverse link is a derived index — the new
 feature's `follow-up-of` field is the authoritative source.
@@ -152,8 +152,6 @@ phase's content).
 
 ## Step 2: Document Current Behavior (if no spec exists)
 
-## Step 2: Document Current Behavior (if no spec exists)
-
 This is critical. Before changing anything, capture what currently exists:
 
 ```
@@ -360,7 +358,7 @@ Items marked *(post-6.3)* are re-verified after the documentation merge in 6.3 l
 - [ ] Extracted logic (if Step 4 decided "extract now") lives under `src/Domain/` as framework-pure code
 - [ ] `Implementation Tasks` section (`phase-spec.md` or `lightweight-spec.md`): all tasks checked, or unchecked items explicitly labelled as follow-up
 - [ ] *(post-6.3)* `dflow/specs/domain/{context}/behavior.md` has a section anchor for every `BR-*` in ADDED / MODIFIED entries; REMOVED entries' anchors have been deleted (mechanical input for `/dflow:verify`)
-- [ ] *(post-6.3)* `dflow/specs/domain/{context}/behavior.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
+- [ ] *(post-6.3)* every ADDED / MODIFIED / RENAMED BR's `Last updated` in `dflow/specs/domain/{context}/rules.md` is later than this spec's `created` date (mechanical drift guard)
 
 If any item fails, report the gap and pause — don't proceed to 6.2.
 
@@ -416,33 +414,3 @@ new follow-up directory; that happens at `/dflow:finish-feature` time.
 
 Only announce "change complete" after the appropriate archival step
 above (or the Step 6.3 docs sweep) is done.
-
-## Lightweight Spec Template (for bug fixes)
-
-For small bug fixes, a lightweight spec is enough:
-
-```markdown
----
-id: BUG-042
-title: Fix rounding inconsistency in expense calculation
-status: in-progress
-bounded-context: Expense
-created: 2025-02-12
----
-
-## Problem
-Entrypoint A uses Math.Round(amount, 0, MidpointRounding.AwayFromZero) (四捨五入)
-Entrypoint B uses Math.Floor(amount) (無條件捨去)
-They should both use the same rounding rule.
-
-## Expected Behavior
-Given an expense amount of 123.5 TWD
-When displayed or returned by any entrypoint
-Then it should show 124 (四捨五入 per accounting standard)
-
-## Root Cause
-Duplicated calculation logic — recorded in tech-debt.md
-
-## Fix
-Extract rounding to Money.Round() in Domain layer, both pages call it.
-```

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

@@ -1,6 +1,6 @@
 # New Feature Workflow
 
-Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natural language implying a new-feature task — see SKILL.md § Workflow Transparency for the auto-trigger safety net behavior).
+Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natural language implying a new-feature task — see AI-AGENT-GUIDE.md § Workflow Transparency for the auto-trigger safety net behavior).
 
 **Step Gates** in this flow (stop-and-confirm before proceeding):
 - Step 3 → Step 3.5 (domain concepts captured → confirm slug + directory + branch names)
@@ -8,9 +8,9 @@ Step-by-step guide for when a developer triggers `/dflow:new-feature` (or natura
 - Step 6 → Step 7 (branch ready → start implementation)
 - Step 7 → Step 8 (implementation done → completion)
 
-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.
+All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow Transparency for the full transparency protocol and confirmation signals.
 
-**Ceremony**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (T1 / T2 / T3) only applies to `/dflow:modify-existing` (see `references/modify-existing-flow.md` and SKILL.md § Ceremony Scaling).
+**Ceremony**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (T1 / T2 / T3) only applies to `/dflow:modify-existing` (see `references/modify-existing-flow.md` and AI-AGENT-GUIDE.md § Ceremony Scaling).
 
 ## Step 1: Intake — Understand the Request
 
@@ -188,7 +188,7 @@ Specifically ask about:
 Announce to developer:
 > "Spec is drafted — behavior scenarios, business rules, and edge cases are captured. Ready to plan the implementation (Domain layer design, interfaces, thin delivery/entrypoint code — presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures)? `/dflow:next` or reply 'OK' to continue, or tell me if the spec needs another iteration first."
 
-Wait for confirmation (`/dflow:next`, verbal OK, or implicit — see SKILL.md § Confirmation Signals) before entering Step 5.
+Wait for confirmation (`/dflow:next`, verbal OK, or implicit — see AI-AGENT-GUIDE.md § Confirmation Signals) before entering Step 5.
 
 ## Step 5: Plan the Implementation
 
@@ -325,7 +325,7 @@ AI reports `✓` / `✗` for every item before touching docs. Items marked *(pos
 - [ ] Every `EC-*` edge case is handled
 - [ ] Domain layer has **no** delivery-framework references (grep `src/Domain/`)
 - [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` contains a section anchor for every `BR-*` introduced by this spec (mechanical input for `/dflow:verify`)
-- [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
+- [ ] *(post-8.3)* `dflow/specs/domain/{context}/rules.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
 
 If any item fails, report the gap and pause — don't proceed to 8.2.
 
@@ -354,12 +354,14 @@ Ask these one-by-one; do not dump all five at once.
 
 ### 8.4 Archival
 
-For a single-phase feature, this is the closeout point. For a multi-phase
-feature, the developer typically reaches this point at the end of the
-final phase — at which time `/dflow:finish-feature` is the recommended
-trigger (it bundles steps 8.1 / 8.2 verification, BC sync, and archival
-into one explicit ceremony). Either path is acceptable; pick the one
-that matches the developer's habit.
+For a single-phase feature, this is the closeout point. If the feature has
+later phases still ahead, this phase is complete but the feature is not —
+don't archive yet; run `/dflow:new-phase` to start the next phase, not
+`/dflow:finish-feature` yet. For a multi-phase feature, the developer
+typically reaches this point at the end of the final phase — at which time
+`/dflow:finish-feature` is the recommended trigger (it bundles steps 8.1 /
+8.2 verification, BC sync, and archival into one explicit ceremony). Either
+path is acceptable; pick the one that matches the developer's habit.
 
 - [ ] `_index.md` `status` field changed to `completed`
 - [ ] All `phase-spec-*.md` files in the feature directory have `status:

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

@@ -20,7 +20,7 @@ adds a new phase to an in-progress feature only.
 - Step 6 → Step 7 (implementation done → complete the phase)
 
 All other step transitions are **step-internal**: announce "Step N complete,
-entering Step N+1" and proceed without waiting. See SKILL.md § Workflow
+entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow
 Transparency for the full transparency protocol and confirmation signals.
 
 ## Step 1: Read Active Feature Context

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

@@ -13,6 +13,42 @@ This project uses Dflow for spec-first AI-assisted development.
 | Migration / legacy context | {migration-context} |
 | Prose language | {prose-language} |
 
+## Why This Matters
+
+This project has business logic embedded in delivery/entrypoint code
+(presentation/UI layer, controllers, handlers, jobs, message consumers, data
+pipelines, or stored procedures), direct SQL in entrypoints, and duplicated
+calculations across multiple flows. Every feature developed without specs makes
+the target architecture harder to reach; every spec written and every domain
+concept extracted makes it easier to reach.
+
+Your role is not to lecture — it's to ask the right questions at the right time
+so developers naturally produce three assets with every change:
+
+1. **Spec documents** — future requirements documentation
+2. **Domain layer code** — portable to a cleaner future architecture
+3. **Tech debt records** — migration guide entries
+
+## Scope: When Brownfield Applies
+
+Dflow Brownfield is designed for existing systems where:
+
+- **Business rules and domain concepts** can be extracted and re-expressed as
+  portable code (entities, value objects, services, repository interfaces)
+- **Business logic is currently embedded in delivery/entrypoint code** —
+  presentation/UI layer, controllers, handlers, jobs, message consumers, data
+  pipelines, or stored procedures — making changes risky and slow
+- The team wants to **gradually move toward a cleaner architecture** without a
+  full rewrite
+
+It is **not** a fit for:
+
+- Pure infrastructure scripts (deployment, monitoring) without a stable domain
+  model
+- Data pipelines or batch jobs that are purely transformational with no
+  business-rule complexity
+- Greenfield projects (use the Greenfield track instead)
+
 ## Before Editing Code
 
 Do not jump from a request directly to code. First identify the matching
@@ -28,7 +64,7 @@ are not available in the current AI tool:
 | `/dflow:bug-fix` | A defect can be described with expected vs actual behavior. |
 | `/dflow:new-phase` | An active feature needs another implementation slice. |
 | `/dflow:finish-feature` | Implementation is complete and needs drift closure. |
-| `/dflow:verify` | Specs, domain docs, implementation, and tests need consistency checks. |
+| `/dflow:verify` | A bounded context's domain docs (`rules.md` ↔ `behavior.md`) need a consistency / drift check. |
 | `/dflow:pr-review` | A change is ready for SDD/DDD review. |
 | `/dflow:report-dflow-feedback` | You found a Dflow issue or improvement and want a sanitized upstream feedback draft. |
 | `/dflow:status` | You need the current workflow state, current step, completed work, in-progress work, remaining work, pending decision, and next valid action. |
@@ -45,7 +81,7 @@ Machine-readable source for rendering tool-specific thin wrappers:
 | bug-fix | /dflow:bug-fix | Investigate a defect described by expected vs actual behavior. | expected vs actual | workflow |
 | new-phase | /dflow:new-phase | Add another implementation slice to an active feature. | feature id or phase goal | workflow |
 | finish-feature | /dflow:finish-feature | Close implementation with drift checks and archived feature state. | feature id | workflow |
-| verify | /dflow:verify | Check specs, domain docs, implementation, and tests for consistency. | area or feature id | workflow |
+| verify | /dflow:verify | Check a bounded context's domain docs (`rules.md` ↔ `behavior.md`) for consistency. | bounded context or all | workflow |
 | pr-review | /dflow:pr-review | Review a ready change for SDD/DDD alignment. | change or branch | workflow |
 | report-dflow-feedback | /dflow:report-dflow-feedback | Draft sanitized upstream feedback about Dflow. | issue or improvement | workflow |
 | status | /dflow:status | Report current workflow state and next valid action. | - | control |
@@ -53,6 +89,27 @@ Machine-readable source for rendering tool-specific thin wrappers:
 | cancel | /dflow:cancel | Abort the active workflow and return to free conversation. | - | control |
 <!-- dflow-command-registry:end -->
 
+## Routing Non-Command Input
+
+Not every developer message maps to a `/dflow:*` workflow. Route non-command
+input like this (supporting files live in the workflow bundle at
+`dflow/specs/shared/dflow-workflows/`):
+
+- **"Quick question about..." / "How does X work?"** → check
+  `dflow/specs/domain/` first and answer from the documented domain knowledge.
+  If no spec exists yet, suggest documenting the answer as domain knowledge.
+- **"What should I work on next?" / sprint planning** → review
+  `dflow/specs/features/backlog/` and suggest work based on migration value.
+- **"I'm creating a branch"** → read `references/git-integration.md`; verify
+  branch naming and ensure a spec exists before coding starts.
+- **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
+  guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
+  anything upstream automatically.
+- **Anything else code-related** → assess whether it touches business logic. If
+  it does, use the auto-trigger safety net (suggest the matching `/dflow:*`
+  command and wait for confirmation — see § Workflow Transparency); if not, help
+  directly with no ceremony.
+
 ## Status / Control Commands
 
 `/dflow:status` reports active workflow state. Include these fields: workflow,
@@ -71,6 +128,67 @@ workflow was cancelled.
 When no workflow is active, `/dflow:next` and `/dflow:cancel` must report that
 there is no active workflow to advance or cancel.
 
+## Workflow Transparency
+
+Dflow uses a hybrid interaction design: `/dflow:*` commands are the primary
+entry, natural-language auto-trigger is a safety net, and tiered transparency
+keeps the developer aware of where they are in a workflow.
+
+### Auto-Trigger Safety Net
+
+When natural language implies a development task, detect the intent — but do
+**not** auto-enter a workflow. Instead:
+
+1. State your judgment clearly:
+   > "I think this is a new-feature task."
+2. Offer the developer three options:
+   - Type `/dflow:new-feature` to start explicitly
+   - Reply "OK" / "繼續" to confirm this workflow
+   - Or correct the workflow (e.g., "no, this is a bug fix")
+3. Wait for confirmation before entering any workflow.
+
+This addresses three failure modes of pure auto-trigger: missed triggers, wrong
+workflow selection, and invisible state.
+
+### Three-Tier Transparency
+
+During an active workflow, communicate at three levels — no more, no less:
+
+| Level | Trigger point | AI behavior |
+|---|---|---|
+| **Flow entry (must confirm)** | After judging the workflow from NL | Stop and wait for confirmation (command, "OK", or implicit) |
+| **Step gate (notify + optional confirm)** | Before major milestones | Announce the transition; if the developer provides next-step input, treat it as implicit confirmation |
+| **Step-internal (notify only)** | Step N → Step N+1 | Announce "Step N complete, entering Step N+1" — do not wait |
+
+The specific step-gate positions for each workflow live in that flow's own file
+(`dflow/specs/shared/dflow-workflows/references/<flow>.md`), which is the source
+of truth for its gate sequence.
+
+### Confirmation Signals (NL ↔ Command Equivalence)
+
+Any of these count as "proceed to next step" — accept whichever the developer
+uses:
+
+- **Command**: `/dflow:next`
+- **Verbal (English)**: OK / yes / continue / go ahead / sounds good / proceed
+- **Verbal (Chinese)**: 好 / 對 / 繼續 / 可以 / 沒問題
+- **Implicit**: the developer provides the information needed for the next step
+  (e.g., the AI asks "Which Bounded Context?" and the developer answers with the
+  Bounded Context name → implicit confirmation)
+
+The implicit-confirmation rule matters — do not turn every transition into a
+ceremony where the developer must say "OK" before every sentence.
+
+### Completion Checklist Skip Guard
+
+Completion checklists and their step ordering live in the flow files and run at
+the gate each flow specifies (the feature-level completion gate in
+`new-feature-flow` / `modify-existing-flow`, the phase-level gate in
+`new-phase-flow`). Do not run a checklist opportunistically. But if the
+developer skips the gate and commits directly, use the auto-trigger safety net
+to prompt — "It looks like you're wrapping up — should I run the Step N
+completion checklist?" — before giving commit guidance.
+
 ## Source of Truth
 
 Dflow-owned project documents live under `dflow/specs/`.
@@ -85,6 +203,38 @@ Dflow-owned project documents live under `dflow/specs/`.
 | Completed feature snapshots | `dflow/specs/features/completed/` |
 | Technical debt | `dflow/specs/architecture/tech-debt.md` or `dflow/specs/migration/tech-debt.md` |
 
+### Project Structure
+
+The `dflow/specs/` layout Dflow seeds and maintains (Brownfield track):
+
+```
+dflow/specs/
+├── shared/                       # Project-level governance docs (seeded by npx dflow-sdd-ddd init)
+│   ├── _overview.md              # System status & migration strategy
+│   └── _conventions.md           # Spec writing conventions
+├── domain/                       # Domain knowledge (DDD preparation)
+│   ├── glossary.md               # Ubiquitous Language
+│   └── {bounded-context}/        # e.g., expense/, hr/, leave/
+│       ├── context.md            # Context boundary & responsibilities
+│       ├── models.md             # Entity, VO, Aggregate definitions
+│       ├── rules.md              # Business rules index (BR-ID + one-line)
+│       └── behavior.md           # Consolidated behavior (Given/When/Then)
+├── features/
+│   ├── active/                   # Currently in development
+│   │   └── {SPEC-ID}-{slug}/     # One feature = one directory
+│   │       ├── _index.md         # Feature dashboard + BR Snapshot + Resume Pointer
+│   │       ├── phase-spec-YYYY-MM-DD-{slug}.md   # T1: 0..N phase specs
+│   │       └── lightweight-YYYY-MM-DD-{slug}.md  # T2: 0..N lightweight specs
+│   │                                             #     (or BUG-{NUMBER}-{slug}.md)
+│   ├── completed/                # Done (whole feature directory archived here)
+│   └── backlog/                  # Planned
+│   #
+│   # SPEC-ID format: SPEC-YYYYMMDD-NNN; slug follows discussion language (中文 / 英文 both OK).
+│   # T3 trivial changes have NO independent file — just a row in _index.md Lightweight Changes.
+└── migration/
+    └── tech-debt.md              # Issues to fix in the target system
+```
+
 ## Core Rules
 
 1. Spec before code: meaningful behavior changes need a spec or lightweight bug spec before implementation.
@@ -93,6 +243,107 @@ Dflow-owned project documents live under `dflow/specs/`.
 4. Check drift before calling work complete.
 5. Follow `dflow/specs/shared/_conventions.md`, especially `## Prose Language`.
 
+## Ceremony Scaling
+
+Not everything needs full ceremony — match effort to impact. Dflow uses three
+tiers — **T1 Heavy / T2 Light / T3 Trivial** — chosen by the AI per change.
+`/dflow:new-feature` and `/dflow:new-phase` always default to T1 (no judgement
+needed). The criteria below apply when `/dflow:modify-existing` or
+`/dflow:bug-fix` decides which tier fits a modification.
+
+| Tier | Scenario | Output | Command / Trigger |
+|---|---|---|---|
+| **T1 Heavy** | New feature, new phase, architectural change, new BR | Independent `phase-spec-YYYY-MM-DD-{slug}.md` placed in the feature directory + `_index.md` Phase Specs row + refresh BR Snapshot | `/dflow:new-feature` / `/dflow:new-phase` |
+| **T2 Light** | Bug fix, UI input validation tweak, flow branch change — has BR Delta | Independent `lightweight-{YYYY-MM-DD}-{slug}.md` (or `BUG-{NUMBER}-{slug}.md`) inside the feature directory + `_index.md` Lightweight Changes row (outbound link) + refresh BR Snapshot | `/dflow:bug-fix` or `/dflow:modify-existing` (lightweight branch) |
+| **T3 Trivial** | Button colour, copy/text fix, typo, formatting, pure comments — **no BR change, no Domain concept change, no data structure change** | **Inline row in `_index.md` Lightweight Changes only** (no independent spec file) | `/dflow:modify-existing` (`_index-only` branch) |
+
+**T3 criteria** (the AI must satisfy **all four** before classifying T3):
+
+1. No BR-ID change (no ADDED / MODIFIED / REMOVED / RENAMED business rule)
+2. No Domain concept added or changed (Aggregate / Entity / VO / Event)
+3. No data structure change (table, column, relation, index)
+4. Only changes UI surface (colour, text, layout), pure comments, or pure formatting
+
+If any criterion fails → drop to T2; if Domain / BR / data structure is touched → escalate to T1.
+
+**Below T3 — Dflow doesn't track at all**: pure typo fixes, commit-message
+typos, pure formatting commits (e.g. `prettier` / `dotnet format` auto-runs).
+You can `git commit` directly without writing even a T3 inline row.
+
+**Lightweight spec** = Problem + Expected behavior + 1–2 Given/When/Then. The
+instantiated file is placed inside the feature directory (see
+`templates/lightweight-spec.md`).
+
+## Behavior Source of Truth (rules.md + behavior.md)
+
+Each Bounded Context has two complementary files that together describe the
+system's current behavior:
+
+- **`rules.md`** — declarative index: lists each BR-ID with a one-line summary.
+  Quick lookup, easy to scan.
+- **`behavior.md`** — scenario-level detail: the full Given/When/Then scenarios
+  for each BR-ID. This is the consolidated source of truth for "what does the
+  system actually do right now?"
+
+`dflow/specs/features/completed/` is a historical archive (individual change
+records). `behavior.md` is the **merged current state** — when a feature is
+completed, the AI merges its scenarios into `behavior.md`; when behavior is
+modified, the AI updates the corresponding section to reflect the new behavior
+(git preserves history). See the `behavior.md` template in the workflow bundle
+at `dflow/specs/shared/dflow-workflows/templates/behavior.md`.
+
+## Guiding Questions by Activity
+
+SDD has five conceptual activities (Understanding / Domain Analysis / Spec
+Writing / Implementation Planning / Tech Debt Awareness) that the AI walks the
+developer through inside a workflow. They cut across workflow steps — Activity 2
+(Domain Analysis) might span Step 2 and Step 3 of new-feature-flow, for example.
+
+When a developer starts working, guide them with these questions in order. Don't
+dump all questions at once — ask naturally as the conversation progresses.
+
+**Activity markers in the phase-spec template**: each section in
+`templates/phase-spec.md` carries an HTML comment (e.g.,
+`<!-- Fill timing: Activity 2: Domain Analysis -->`) indicating the activity in
+which that section should be filled. These markers align with the activities
+below and are used by `/dflow:status` and the completion checklist to track
+progress. When guiding a developer, fill sections in activity order; do not jump
+ahead to Activity 4 (Implementation Planning) before Activity 3 (Spec Writing)
+is agreed. The `Implementation Tasks` section at the end of the template is
+produced by the AI at the end of Activity 4 — see new-feature-flow.md Step 5 /
+new-phase-flow.md Step 4 / modify-existing-flow.md Step 4.
+
+Note: the phase-spec template HTML comments cover Activity 1–4; Activity 5 (Tech
+Debt Awareness) is a closeout-time concern handled when updating `tech-debt.md`
+during the completion checklist, not via template section markers.
+
+### Activity 1: Understanding (What & Why)
+- What problem does this solve? Who asked for it?
+- What's the expected behavior from the user's perspective?
+- Are there existing specs or domain docs related to this?
+
+### Activity 2: Domain Analysis (Where does it live?)
+- Which Bounded Context does this belong to? (Check dflow/specs/domain/)
+- What domain concepts are involved? (Entities, Value Objects, Services)
+- Are there new terms? → Update glossary.md
+- Are there new or changed business rules? → Document in rules.md
+
+### Activity 3: Spec Writing (Document before coding)
+- Write the spec using the template (see `templates/phase-spec.md`)
+- Define Given/When/Then scenarios for key behaviors
+- Identify edge cases and business rule interactions
+
+### Activity 4: Implementation Planning (How to build it)
+- Can the business logic live in `src/Domain/` as framework-pure code?
+- What interfaces are needed? (Repository, external services)
+- How thin can the delivery/entrypoint code be? (Ideally: parse input → call Domain → return or display result)
+
+### Activity 5: Tech Debt Awareness (What did we find?)
+- Did we discover scattered business logic? → Record in tech-debt.md
+- Are there duplicated calculations? → Record
+- Direct SQL in delivery/entrypoint code? → Record
+- Magic numbers or undocumented statuses? → Record and add to glossary
+
 ## Pre-V1 Artifacts Detection
 
 When working in a project that adopted Dflow before `dflow-sdd-ddd@0.1.0`,