dflow-sdd-ddd 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {
@@ -39,10 +39,13 @@
   },
   "homepage": "https://github.com/weilung/dflow-sdd-ddd#readme",
   "scripts": {
-    "test": "node test/smoke.mjs && node test/registry-parity.mjs && node test/agent-inject.mjs && node test/bundle-guards.mjs"
+    "test": "node test/smoke.mjs && node test/skill-default.mjs && node test/registry-parity.mjs && node test/agent-inject.mjs && node test/bundle-guards.mjs && node test/render.mjs"
   },
   "license": "AGPL-3.0-or-later",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "marked": "18.0.5"
   }
 }

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

@@ -55,6 +55,10 @@ proceeding (do not flip status, do not archive, do not emit summary).
 - [ ] 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`
+- [ ] Every Tier = T2 row in `_index.md` Lightweight Changes references an
+      existing `lightweight-*.md` / `BUG-*.md` file in the feature directory
+- [ ] Every such lightweight / BUG 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
@@ -65,6 +69,7 @@ If any check fails:
 > found:
 >   ✗ phase-spec-2026-04-15-foo.md status is still `in-progress`
 >   ✗ Phase Specs table row 3 references missing file phase-spec-...
+>   ✗ lightweight-2026-06-20-rounding.md frontmatter status is still `in-progress`
 >
 > Address these (run `/dflow:new-phase` to add missing work, or fix the
 > stale status manually), then re-run `/dflow:finish-feature`."
@@ -92,11 +97,17 @@ branch: feature/{SPEC-ID}-{slug}
 ---
 ```
 
-Also update the **Resume Pointer** to reflect closeout:
+Also update the **Resume Pointer** to reflect closeout — this writes the
+cursor's terminal state (after closeout no workflow is active on this
+feature; do not edit the cursor again after the Step 4 closeout commit):
 
 ```
 **Current Progress**: feature completed ({date}); all phase-specs status = completed.
 **Next Action**: integration — push / merge / PR per the selected Git policy.
+**Active Workflow**: none
+**Current Step**: n/a
+**Gates Passed**: n/a
+**Awaiting**: none
 ```
 
 **→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (status flipped). Entering Step 3: Sync BR Snapshot to BC layer." and continue.
@@ -170,7 +181,8 @@ 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 status   # confirm rename detection AND check for `RM` — an `M` next to
+             # a rename means unstaged edits you must re-add before committing
 ```
 
 `git mv` is mandatory — never use plain `mv` + `git add`. This preserves
@@ -179,37 +191,74 @@ 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`, `glossary.md`, `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
+✓ Feature archived to completed/ and closeout ready to stage
    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.
+Then, in this order:
+
+1. **Record the checkpoint row first.** Write one row in the moved
+   `_index.md` Checkpoint Log — `closeout | committed` for Y, `closeout |
+   skipped` for N. The closeout row carries **no commit hash**: the closeout
+   commit cannot contain its own hash. Trace it later via
+   `git log -1 -- dflow/specs/features/completed/{SPEC-ID}-{slug}` (or the
+   optional `Dflow-Checkpoint` trailer). The "hash only after success" rule
+   still applies to spec / implementation rows — closeout is the documented
+   exception (see `references/git-integration.md` § Commit Checkpoints,
+   Branch Gate & AI Commits).
+2. **Stage the whole archived feature directory:**
+
+   ```bash
+   git add dflow/specs/features/completed/{SPEC-ID}-{slug}
+   ```
+
+   This is required, not optional: `git mv` stages the rename with the
+   **last-committed** content, so working-tree edits made earlier in this
+   flow to the moved files — the Step 2 status flip and Resume Pointer
+   update, plus the checkpoint row you just wrote — stay **unstaged** until
+   this `git add`. In `git status`, the moved `_index.md` showing `RM`
+   instead of plain `R` is exactly this signal. Then also `git add` the
+   files updated in Step 3 (the updated `rules.md`, `behavior.md`,
+   `glossary.md`, `tech-debt.md`, etc.) into the same stage.
+3. **Commit (Y) or stop (N).** For Y the AI commits. If a pre-commit hook
+   rejects it or the commit fails, flip the checkpoint row to `failed` (the
+   row is not committed yet — edit it directly), surface the error, and
+   treat the gate as unsatisfied.
+
+**Post-commit closeout verification** — after a successful commit, and before
+declaring the Local-closeout gate satisfied, AI runs and reports `✓` / `✗` for
+every item:
+
+- [ ] `git show HEAD:dflow/specs/features/completed/{SPEC-ID}-{slug}/_index.md`
+      — one blob read verifying **two** things: frontmatter `status: completed`
+      **and** the Checkpoint Log contains the closeout row. This reads the
+      **committed** content, not the working tree — the former catches "rename
+      carried stale content", the latter catches "row never made it into the
+      commit".
+- [ ] `dflow/specs/features/active/{SPEC-ID}-{slug}/` no longer exists (the
+      directory was moved, not copied)
+- [ ] `git status --short` shows no leftovers related to this feature
+      (working tree clean; identify any unrelated dirty files explicitly)
+
+If any item fails, do **not** declare closeout complete — fix it (re-add and
+amend, or a follow-up commit; the developer chooses) and re-verify.
+
+The Local-closeout gate is satisfied **only when the closeout is committed and
+the verification above passes**. 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 and verified, the gate stands on its own
+offline; integration happens in Step 5 when you have network.
+
+**→ Transition (step-internal)**: Step 4 complete. Branch on the verification result:
+
+- **Closeout commit landed and post-commit verification passed** → announce "Step 4 complete (feature archived; Local-closeout gate satisfied). Entering Step 5: Integration / PR gate." and continue.
+- **Closeout commit was declined (N), failed, or verification reported `✗`** → **stop here.** Announce "Step 4 complete (feature archived), but the Local-closeout gate is not satisfied yet — the closeout is staged but uncommitted, or the committed content failed verification. Commit the staged changes (or fix the failure), then resume to Step 5." Do **not** enter Step 5 with uncommitted or unverified closeout changes.
 
 ## Step 5: Emit Integration Summary (Git-strategy-neutral)
 
@@ -266,10 +315,17 @@ the developer:
 
 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."
+> directory is now at `dflow/specs/features/completed/{SPEC-ID}-{slug}/`,
+> with the Local-closeout gate satisfied (closeout committed and verified).
+> Integration — merge / push / PR — follows the selected Git policy, at
+> your discretion."
+
+**In-flight reminder** — after the closeout announcement (with or without
+Step 6), run the in-flight overview scan (see `AI-AGENT-GUIDE.md` § Status /
+Control Commands) and list any other unfinished features in `active/` and any
+in-flight feature / bugfix branches. Surfacing them at closeout is deliberate:
+attention is about to move elsewhere, and this is exactly where half-done work
+sinks.
 
 ## Step 6: Reverse-Update Follow-up Tracking (only if follow-up)
 

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

@@ -37,9 +37,9 @@ main (or your project's base branch)
 ```
 feature/{SPEC-ID}-{slug}
   Examples:
-    feature/EXP-001-jpy-currency-support
-    feature/HR-003-leave-approval-workflow
-    feature/SHARED-002-audit-logging
+    feature/SPEC-20260424-001-jpy-currency-support
+    feature/SPEC-20260430-001-leave-approval-workflow
+    feature/SPEC-20260502-002-audit-logging
 
 bugfix/{BUG-ID}-{slug}
   Examples:
@@ -148,10 +148,30 @@ 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.
 Whether you choose Y or N, the AI records one row in the feature `_index.md`
-Checkpoint Log. A commit hash is written only after the commit succeeds; a hook
-rejection or failed commit is recorded as `failed` (never a fake hash). After
-several consecutive skips in a project the AI mentions you can turn checkpoints
-off in config — it does not turn them off for you.
+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
+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
+`Dflow-Checkpoint` trailer below. After several consecutive skips in a project
+the AI mentions you can turn checkpoints off in config — it does not turn them
+off for you.
+
+**Optional machine-greppable trailer.** Teams that want cross-flow checkpoint
+accounting can append a commit trailer at checkpoint commits:
+
+```
+Dflow-Checkpoint: {SPEC-ID} {spec|impl|closeout}
+```
+
+The `_index.md` Checkpoint Log **remains the source of truth**; the trailer is
+a cheap derived mirror (`git log --grep 'Dflow-Checkpoint: {SPEC-ID}'`). Use
+role names, not (k/N) counts — the checkpoint total can change mid-feature
+(tier escalation, follow-ups), and a role gap ("impl exists but no closeout for
+this SPEC-ID") is detectable without predicting N, even across flows.
 
 ### AI commits
 
@@ -325,8 +345,8 @@ Tie commits to specs:
 [SPEC-ID] Short description
 
 Examples:
-[EXP-001] Add JPY currency support to Money value object
-[EXP-001] Extract exchange rate logic to Domain service
+[SPEC-20260424-001] Add JPY currency support to Money value object
+[SPEC-20260424-001] Extract exchange rate logic to Domain service
 [BUG-042] Fix rounding inconsistency, extract to Money.Round()
 ```
 

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

@@ -167,6 +167,32 @@ Wait for answers.
 > and refreshes it in place on re-run. Merge snippets under
 > `dflow/specs/shared/` are used only if Dflow markers conflict."
 
+Wait for answers.
+
+### Q9. Project-level skill (agent-gated, default yes)
+
+Asked only when Q8 selected at least one agent — with no agents there is no
+projection target and this question is skipped entirely.
+
+> "Install the project-level Dflow skill for natural-language auto-trigger?
+> (Y/n)
+>
+> The skill is what makes requests like 'I want to add a feature' surface the
+> matching workflow automatically; without it, triggering relies on the
+> instruction files alone and degrades in long sessions. Skill files are
+> Dflow-generated derivatives — the recommended default is to gitignore them
+> and re-project after cloning."
+
+Wait for the answer. **Blank defaults to yes.** On `n`, tell the developer:
+
+> "Skipped the project-level skill; add it later with
+> `dflow configure-agents --skills`."
+
+CLI note: the CLI asks this question only on an interactive terminal. A
+non-interactive (piped) `dflow init` never reads an extra stdin answer for it
+— existing scripted answer sequences keep their structure and keep working —
+and installs the skill for the selected agents by default.
+
 **→ Transition (step-internal)**: Step 2 complete. Announce
 > "Step 2 complete (project information captured). Entering Step 3:
 > File-list preview."
@@ -274,7 +300,7 @@ skip, and wait for developer confirmation:
 **→ Step Gate: Step 3 → Step 4**
 
 Wait for explicit confirmation. If the developer asks to change the
-selection, go back to the relevant Step 2 question (Q5–Q8) and re-run Step 3.
+selection, go back to the relevant Step 2 question (Q5–Q9) and re-run Step 3.
 
 ---
 
@@ -346,6 +372,22 @@ For each selected tool-specific file (`AGENTS.md`, `CLAUDE.md`,
   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
 
+If the developer chose to install the project-level skill (Q9), the CLI also
+creates the skill file for each selected tool at its native project-level
+path:
+
+- `.claude/skills/dflow/SKILL.md` — Claude Code
+- `.agents/skills/dflow/SKILL.md` — Codex
+- `.github/skills/dflow/SKILL.md` — GitHub Copilot
+
+All three are the same edition-neutral thin skill projected from the single
+canonical source in the npm package. An existing file at one of those paths
+that is **not** Dflow-generated (missing the
+`<!-- dflow-generated: skill-adapter -->` marker) is left unchanged with a
+warning. Manual AI fallback (no npm available): do **not** hand-write SKILL.md
+content — report that the skill install is deferred and the developer should
+run `dflow configure-agents --skills` once npm is available.
+
 ### 4.4 Directory-only entries
 
 For directories that Git otherwise wouldn't track (empty `active/` /

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

@@ -7,6 +7,8 @@ Step-by-step guide for when a developer triggers `/dflow:modify-existing` or `/d
 - Step 4 → Step 5 (extraction decision → start implementation)
 - Step 5 → Step 6 (implementation done → update artifacts)
 
+Crossing any step gate above also updates the host feature's `_index.md` Resume Pointer cursor (Active Workflow / Current Step / Gates Passed / Awaiting) once the host feature directory exists — fold it into that gate's existing `_index.md` / Resume Pointer edit, no separate ceremony (see the `_index.md` template's Resume Pointer notes).
+
 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 (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).
@@ -63,6 +65,16 @@ Walk through these in order:
    this is a new concern. For T1, use `/dflow:new-feature`. For T2 / T3
    on a standalone bug, see Step 1.5 — `/dflow:bug-fix` will create a
    minimal feature directory to host the lightweight-spec.
+4. **In-flight overlap scan (cross-branch)**: this branch's `active/` is not
+   everything in flight. Run the in-flight scan (classification and dedup
+   rules in `AI-AGENT-GUIDE.md` § Status / Control Commands) — `git fetch`
+   when the network allows, then
+   `git branch --all --list '*feature/*' --list '*bugfix/*'` — and also list
+   other unfinished features in this branch's `active/` (one cursor line
+   each). If a scanned branch classified as in flight elsewhere, closed out
+   awaiting integration, or unknown — or an unfinished feature — semantically
+   overlaps this change, surface it and wait for the developer to decide
+   before creating anything new (stale branches are non-blocking).
 
 > **Why scan completed too?** Completed features are frozen history
 > and **cannot accept** any T2 / T3 directly
@@ -316,6 +328,17 @@ has no separate Aggregates section, do not invent one; update the Repository
 row if one exists. If the developer defers, **record the emergence observation
 in `tech-debt.md`** so the boundary decision is not silently lost.
 
+**Established-model re-read (the emergence check's mirror).** When the rule
+you are extracting lands on an **already-modeled** Aggregate / concept,
+re-read what was recorded when it was shaped (its `models.md` row + Notes
+and the relevant `rules.md` entries) before extending it. If this change
+matches a recorded re-evaluation condition ("revisit when …") or trips a
+model-resistance signal, follow `references/ddd-modeling-guide.md`
+§ "Revising an Established Model": record one short passage in the spec's
+design decisions / open questions — proceed as-is, split, or rename, with
+the reason. Deciding to keep the current model, recorded, is a valid
+outcome; extending silently is not.
+
 If the context is **`generic`** (Subdomain Type), emergence is usually a
 *replacement / adapter-boundary* debt signal, not a cue for deep T1 modeling —
 record the replacement intent (consistent with the generic extraction fallback

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

@@ -8,6 +8,8 @@ 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)
 
+Crossing any step gate above also updates the host feature's `_index.md` Resume Pointer cursor (Active Workflow / Current Step / Gates Passed / Awaiting) once the feature directory exists — fold it into that gate's existing `_index.md` / Resume Pointer edit, no separate ceremony (see the `_index.md` template's Resume Pointer notes).
+
 All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See AI-AGENT-GUIDE.md § Workflow Transparency for the full transparency protocol and confirmation signals.
 
 **Ceremony**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (T1 / T2 / T3) only applies to `/dflow:modify-existing` (see `references/modify-existing-flow.md` and AI-AGENT-GUIDE.md § Ceremony Scaling).
@@ -30,6 +32,27 @@ Then check existing assets:
 - Search `dflow/specs/features/` for related or overlapping features
 - Check `dflow/specs/domain/glossary.md` for relevant terms
 
+**In-flight overlap scan (cross-branch + other unfinished features)** — this
+branch's `dflow/specs/` does not show everything in flight. Run the in-flight
+scan (classification and dedup rules in `AI-AGENT-GUIDE.md` § Status / Control
+Commands):
+
+```bash
+git fetch   # when the network allows; skip gracefully offline
+git branch --all --list '*feature/*' --list '*bugfix/*'
+```
+
+- List other unfinished features already in this branch's `active/` (one
+  cursor line each, from their `_index.md` Resume Pointer).
+- Classify every listed branch by the guide's rules — in flight elsewhere /
+  closed out awaiting integration / stale (completed here) / unknown — do
+  not shortcut the classification. If a branch classified as **in flight
+  elsewhere, closed out awaiting integration, or unknown** has an ID / slug
+  that semantically overlaps this request, surface it and wait for the
+  developer to decide — continue there / integrate it first / treat as
+  related / unrelated — **before creating any new directory, spec, or
+  branch**. Only stale (completed here) branches are non-blocking.
+
 Share what you found: "I see we already have [X] documented. This new feature seems to extend
 that — is that right?"
 
@@ -90,6 +113,16 @@ classification, set-based / uniqueness rules, value objects, aggregate sizing
 read `references/ddd-modeling-guide.md` (its **Edition note** maps recording
 surfaces to brownfield's `models.md` / `rules.md`).
 
+The mirror case — the concept is **already modeled**: when extending an
+existing Aggregate / modeled concept, re-read what was recorded when it was
+shaped (its `models.md` row + Notes and the relevant `rules.md` entries)
+before extending it. If this change matches a recorded re-evaluation
+condition ("revisit when …") or trips a model-resistance signal, follow
+`references/ddd-modeling-guide.md` § "Revising an Established Model":
+record one short passage in the spec's design decisions / open questions —
+proceed as-is, split, or rename, with the reason. Deciding to keep the
+current model, recorded, is a valid outcome; extending silently is not.
+
 For each new concept:
 1. Check glossary — add if missing
 2. Check if it already exists in models.md — extend if needed
@@ -170,7 +203,7 @@ dflow/specs/features/active/{SPEC-ID}-{slug}/
    - Current BR Snapshot: initialise from the first phase's planned BRs
      (will be refreshed when the phase-spec finalises)
    - Lightweight Changes: empty table at start
-   - Resume Pointer: "phase-1 in progress: drafting phase-spec." / "Next Action: finish phase-spec, then implement."
+   - Resume Pointer: "phase-1 in progress: drafting phase-spec." / "Next Action: finish phase-spec, then implement." / cursor fields: Active Workflow `new-feature`, Current Step `Step 4 — write the spec`, Gates Passed `3→3.5`, Awaiting `none (mid-step)`
 3. **Create the first phase-spec** at `phase-spec-{YYYY-MM-DD}-{slug}.md`
    using `templates/phase-spec.md`. The "Delta from prior phases" section
    is filled with "首 phase，無前置 Delta" (first phase has nothing to

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

@@ -19,6 +19,8 @@ adds a new phase to an in-progress feature only.
 - Step 5 → Step 6 (`_index.md` refreshed → start implementation)
 - Step 6 → Step 7 (implementation done → complete the phase)
 
+Crossing any step gate above also updates the feature's `_index.md` Resume Pointer cursor (Active Workflow / Current Step / Gates Passed / Awaiting) — fold it into that gate's existing `_index.md` / Resume Pointer edit, no separate ceremony (see the `_index.md` template's Resume Pointer notes).
+
 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.
@@ -63,6 +65,11 @@ AI must locate the target feature and load its current state:
    - Read the most recent phase-spec to understand where the prior phase
      left off (its Business Rules and Delta-from-prior-phases sections in
      particular)
+   - Run the in-flight overlap scan (classification and dedup rules in
+     `AI-AGENT-GUIDE.md` § Status / Control Commands): list other unfinished
+     features in `active/` and any feature / bugfix branches whose work is
+     not visible on this branch — if the incoming phase scope overlaps one
+     of them, surface it before writing the phase-spec.
 
 4. **Branch gate — ensure you are on this feature's branch (before any commit)**
 
@@ -99,7 +106,11 @@ Walk the developer through what the new phase covers:
    Entity row (no separate Aggregates section). For how to model it (invariant
    classification, set-based / uniqueness rules, aggregate sizing), read
    `references/ddd-modeling-guide.md` (its **Edition note** maps recording
-   surfaces to brownfield's `models.md` / `rules.md`).
+   surfaces to brownfield's `models.md` / `rules.md`). If the phase **extends
+   an already-modeled Aggregate / concept**, apply the established-model
+   re-read from `references/ddd-modeling-guide.md` § "Revising an Established
+   Model" (match recorded re-evaluation conditions; record proceed / split /
+   rename in the phase-spec).
 4. **Data structure impact?** New tables, columns, indices?
 5. **Why now?** Priority — informs sequencing relative to other phases.
 

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

@@ -108,6 +108,11 @@ input like this (supporting files live in the workflow bundle at
   is written with Greenfield artifact names; see its **Edition note** for where
   Brownfield records the same decisions (`models.md` / `rules.md` /
   `behavior.md` / `migration/tech-debt.md`).
+- **"Turn the specs into HTML" / "make the specs easier to read"** → run the
+  CLI command `dflow render` (a human-readability tool, not a `/dflow:*`
+  workflow). It mirrors `dflow/specs/` into a browsable static HTML tree
+  (default output: `dflow-specs-html/`); re-run it after specs change —
+  Markdown stays the AI-facing source of truth.
 - **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
   guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
   anything upstream automatically.
@@ -118,10 +123,43 @@ input like this (supporting files live in the workflow bundle at
 
 ## Status / Control Commands
 
-`/dflow:status` reports active workflow state. Include these fields: workflow,
-step, completed, in-progress, remaining, pending decision, and next valid action.
-If no workflow is active, say that no workflow is active and list valid flow-entry
-or standalone commands.
+`/dflow:status` reports in two parts.
+
+**Part 1 — in-flight overview (always shown, workflow active or not).**
+Aggregate every in-flight feature so unfinished work surfaces without anyone
+remembering to look:
+
+- Scan this branch's `dflow/specs/features/active/*/_index.md` and print one
+  line per feature: SPEC-ID / Active Workflow / Current Step / Awaiting / last
+  Checkpoint Log row (read from each Resume Pointer cursor).
+- Cross-branch: run `git fetch` when the network allows (skip gracefully
+  offline), then `git branch --all --list '*feature/*' --list '*bugfix/*'`,
+  deduplicating local and remote refs of the same branch (prefer local). For
+  each branch, classify in order: (1) its feature directory exists in this
+  branch's `active/` → already covered above; (2) exists in this branch's
+  `completed/` → a stale undeleted branch — list as "completed; branch can be
+  deleted", **not** in-flight; (3)
+  `git show {branch}:dflow/specs/features/active/{dir}/_index.md` is readable
+  → in flight on that branch, print its cursor line (no branch switching);
+  (4) the `completed/` path is readable on that branch → closed out there,
+  awaiting integration; (5) nothing readable → list the branch as unknown
+  state.
+- If `features/backlog/` is non-empty, append one count line.
+- Inherent limit: work never committed anywhere is invisible to any git scan.
+
+**Part 2 — current feature detail (when a workflow is active).** Read the
+Resume Pointer cursor as the **declared** state, then cross-check it against
+derived evidence (Checkpoint Log, phase-spec statuses, recent git log). On
+mismatch, report both sides explicitly and ask the developer to correct the
+cursor — the cursor is a claim; evidence wins. If the cursor fields are absent
+(an older `_index.md`), fall back to pure derivation. For readability you may
+expand the cursor into a step checklist (done / in progress / not started)
+derived live from the flow file — display only, never stored.
+
+Include these fields: workflow, step, completed, in-progress, remaining,
+pending decision, and next valid action. If no workflow is active, say so and
+list valid flow-entry or standalone commands (Part 1 still shows the
+in-flight overview).
 
 `/dflow:next` is valid only at a step gate in an active workflow. Treat it as
 developer confirmation equivalent to "OK" or "continue", then move to the next
@@ -129,7 +167,9 @@ workflow step.
 
 `/dflow:cancel` aborts the current workflow and returns to free conversation.
 Do not rollback changes, delete artifacts, or rewrite specs merely because the
-workflow was cancelled.
+workflow was cancelled. If the feature directory exists, set the Resume
+Pointer cursor's Active Workflow to `none` (keep Current Progress as a trace
+of where the cancellation happened).
 
 When no workflow is active, `/dflow:next` and `/dflow:cancel` must report that
 there is no active workflow to advance or cancel.

package/templates/brownfield/scaffolding/Git-principles-gitflow.md

@@ -140,7 +140,7 @@ When applicable, prefix with a type (conventional commits-style):
 | test | tests only |
 | chore | build / tooling |
 
-Example: `[EXP-001] feat: add JPY currency support to Money VO`
+Example: `[SPEC-20260424-001] feat: add JPY currency support to Money VO`
 
 ---
 

package/templates/brownfield/scaffolding/Git-principles-trunk.md

@@ -95,8 +95,8 @@ adopted, the format is:
 | test | tests only |
 | chore | build / tooling |
 
-Example: `feat(expense): add JPY currency support` with `[EXP-001]` in
-the body.
+Example: `feat(expense): add JPY currency support` with
+`[SPEC-20260424-001]` in the body.
 
 ---
 

package/templates/brownfield/templates/_index.md

@@ -39,6 +39,8 @@ Template note (for AI):
     initial BR Snapshot + Resume Pointer. The other sections can stay empty.
 -->
 
+<!-- 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. -->
+
 # {Feature Title}
 
 ## Goals & Scope
@@ -97,23 +99,42 @@ Template note (for AI):
 > T3 單一 commit。
 >
 > commit hash 只在 commit 實際成功後填入；pre-commit hook reject 或 commit
-> 失敗記 `failed`、不寫假 hash。
+> 失敗記 `failed`、不寫假 hash。**例外：closeout 列不填 hash**——closeout
+> commit 無法自含自身 hash，該列於 commit 前寫入、隨歸檔目錄一起進 commit；
+> 溯源用 `git log -1 -- completed/{SPEC-ID}-{slug}` 或選配的
+> `Dflow-Checkpoint` trailer（見 references/git-integration.md）。
 
 | Timestamp | Checkpoint | Result |
 |---|---|---|
 | {YYYY-MM-DD HH:MM} | spec-baseline | committed ({hash}) / skipped / failed |
 | {YYYY-MM-DD HH:MM} | implementation | committed ({hash}) / skipped / failed |
-| {YYYY-MM-DD HH:MM} | closeout | committed ({hash}) / skipped / failed |
+| {YYYY-MM-DD HH:MM} | closeout | committed / skipped / failed |
 
 ## Resume Pointer
 
-> 一句話：目前進展到哪？下一個動作是什麼？
-> 開新對話接續工作時，從這裡讀起。
+> 目前進展到哪？下一個動作是什麼？開新對話接續工作時，從這裡讀起。
+>
+> 下方四個 cursor 欄位是 workflow 進度的**存放層（宣告，claim）**：
+> 進入 flow 時設 Active Workflow；**每過一個 step gate** 更新 Current Step /
+> Gates Passed / Awaiting（與該 gate 既有的 `_index.md` 更新合併，不另加儀式）；
+> closeout / `/dflow:cancel` 時 Active Workflow 設回 `none`。
+> `/dflow:status` 讀 cursor 後會與推導證據（Checkpoint Log、phase-spec
+> status、git log）交叉，不一致會明確報 mismatch——cursor 是宣告、證據優先。
+> Phase 粒度進度由上方 Phase Specs 表承載；cursor 只補 workflow step / gate
+> 粒度，不展開成 per-step 全表（步驟線性，游標可推導每一步的完成/未做）。
 
 **Current Progress**: {one-line summary}
 
 **Next Action**: {suggested next action}
 
+**Active Workflow**: {new-feature | modify-existing | bug-fix | new-phase | finish-feature | none}
+
+**Current Step**: {Step N — short step name | n/a}
+
+**Gates Passed**: {e.g. "3→3.5, 4→5" | n/a}
+
+**Awaiting**: {step-gate description | none}
+
 <!--
 ## Follow-up Tracking
 >（選用段；只有當本 feature 衍生出 follow-up feature 時才填）

package/templates/brownfield/templates/context-definition.md

@@ -5,6 +5,8 @@ owner: {負責的開發者或團隊}
 created: {YYYY-MM-DD}
 ---
 
+<!-- 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. -->
+
 # {ContextName} Bounded Context
 
 ## Responsibilities

package/templates/brownfield/templates/context-map.md

@@ -1,4 +1,5 @@
 <!-- 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. -->
 
 # Context Map
 

package/templates/brownfield/templates/glossary.md

@@ -1,4 +1,5 @@
 <!-- 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. -->
 
 # Glossary