dflow-sdd-ddd 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {
@@ -41,7 +41,7 @@
   "scripts": {
     "test": "node test/smoke.mjs"
   },
-  "license": "MIT",
+  "license": "AGPL-3.0-or-later",
   "publishConfig": {
     "access": "public"
   }

package/templates/brownfield/references/dflow-feedback-flow.md

@@ -0,0 +1,251 @@
+# Dflow Feedback Draft Flow
+
+`/dflow:report-dflow-feedback` helps the developer turn a Dflow problem or
+improvement observed during real project work into a high-quality upstream
+feedback draft. The draft is rendered **field by field to match the upstream
+GitHub issue form**, so the developer pastes each field with no reformatting.
+
+This flow is **not** a project feature workflow and does not change the
+application being built. It is a standalone governance/support flow for Dflow
+itself.
+
+## Hard Boundaries
+
+- Do not submit anything to GitHub automatically.
+- Do not run `gh issue create`, `gh pr create`, `git push`, or any networked
+  submission command from this flow.
+- Do not expose private project details, business rules, customer data,
+  secrets, tokens, internal URLs, or proprietary source snippets.
+- Always show the draft to the developer before anything leaves the local
+  machine.
+- If the developer later asks to submit through GitHub CLI, stop and treat that
+  as a separate explicit task with fresh permission and environment checks.
+
+## Trigger Conditions
+
+Enter this flow when:
+
+- The developer explicitly runs `/dflow:report-dflow-feedback`.
+- The developer says the Dflow process, template, generated file, or docs seem
+  wrong or improvable.
+- The AI notices a clear contradiction or gap in Dflow guidance and asks:
+  "This looks like a possible Dflow upstream issue. Should I draft feedback for
+  you to review?"
+
+Do not interrupt normal development for minor preference differences. If the
+observation is speculative, ask before drafting.
+
+## Output Location
+
+Write the draft to:
+
+```text
+dflow/feedback/dflow-feedback-YYYY-MM-DD-{slug}.md
+```
+
+Create `dflow/feedback/` if it does not exist. The file is local project
+working material; the developer decides whether to copy it into a GitHub issue,
+turn it into a PR, or discard it.
+
+## Step 1: Classify the Feedback
+
+Classify the feedback as one of the following. Each maps to one upstream issue
+form (see "Upstream Issue Forms" below):
+
+| Classification | Upstream issue form | Title prefix |
+|---|---|---|
+| Bug report | Bug report | `[Bug]: ` |
+| Workflow change request | Workflow change request | `[Workflow]: ` |
+| Documentation feedback | Documentation feedback | `[Docs]: ` |
+| Question / unclear usage | Question | `[Question]: ` |
+| Maintainer release/process feedback | Workflow change request (closest form; the upstream repo disables blank issues) | `[Workflow]: ` |
+
+Capture:
+
+- Observed during which flow or command
+- Affected Dflow track: Greenfield, Brownfield, both, or unknown
+- Affected area: CLI, generated template, scaffolding, skill reference,
+  tutorial, README/docs, release/governance
+- Whether the issue blocks current project work
+
+## Step 2: Capture Evidence Safely
+
+Collect only the evidence needed to explain the Dflow issue.
+
+Allowed evidence:
+
+- Dflow command name
+- Dflow version if known
+- Template or reference file name
+- Generic project type, such as "existing brownfield app" or "legacy batch-processing system"
+- Minimal paraphrased symptom
+- Short sanitized snippets from Dflow-owned files
+
+Avoid:
+
+- Internal business rules
+- Customer or tenant names
+- Private repository names or URLs
+- Secrets, tokens, credentials, or auth headers
+- Long proprietary code snippets
+- Full logs containing private paths or environment data
+
+## Step 3: Redaction Pass
+
+Before writing any field content, run a redaction check and use it as your own
+gate. Confirm there are:
+
+- No secrets, tokens, credentials, or auth headers
+- No customer, tenant, or private organization names
+- No proprietary business rules beyond a sanitized paraphrase
+- No private repository URLs or internal hostnames
+- No long proprietary source snippets
+
+The draft ends with a short submitter self-check (Step 5); leave its items
+unchecked unless the developer explicitly confirms them.
+
+## Step 4: Resolve the Target Issue Form
+
+Submit upstream at: **https://github.com/weilung/dflow-sdd-ddd/issues/new/choose**
+
+Resolve the field schema for the chosen form using this priority chain (it
+avoids any network dependency at draft time):
+
+1. **Live upstream schema** — if you can read the target repo's
+   `.github/ISSUE_TEMPLATE/*.yml` (for example you are working inside a
+   `dflow-sdd-ddd` checkout), use that file; it is authoritative.
+2. **Bundled field map** — otherwise use the field map in "Upstream Issue
+   Forms" below. It is a snapshot of the upstream forms shipped with Dflow.
+3. **Generic fallback** — only if the feedback matches none of the forms, use
+   Step 6.
+
+## Step 5: Render the Draft Field by Field
+
+Write the draft as one block per upstream field, in the form's field order, so
+the developer copies each block straight into the matching field.
+
+Per field-type rules:
+
+| Field type | How to render |
+|---|---|
+| `input` | One short line inside a fenced block. |
+| `textarea` | Multi-line content inside a fenced block. If the field sets a non-empty `render:` attribute, do **not** add an extra fence (the form already code-blocks it). |
+| `dropdown` | State the **recommended option** plus a one-line reason. If `multiple: true`, list the chosen options. |
+| `checkboxes` | List every option as `- [x]` / `- [ ]`; mark any option whose schema sets `required: true`. |
+| `markdown` | Display-only text in the form — produce **no** field block for it. |
+| upload / attachment | Emit a manual step ("drag the relevant screenshot / log into the issue editor"); do not try to handle the file. |
+
+Always start with a **Title** block: the form's title prefix plus a concise
+one-line summary. GitHub pre-fills the prefix in the title box; the developer
+can paste the full line over it.
+
+Attribute handling: bring `value` / `default` in as starting content; surface
+`placeholder` as a hint; append "(required)" to the block heading when the
+field sets `required: true`.
+
+**Fence escaping (dynamic).** Wrap each field's content in a backtick fence
+whose length is *(longest backtick run in the content) + 1*, minimum 3. The
+fence is only a local wrapper so the content survives in the draft file — when
+pasting into the issue form, the developer copies the **inner** content, not
+the fence. State this in the draft.
+
+Draft skeleton:
+
+````markdown
+# {Issue form name} — {short title}
+
+## Where to submit
+
+https://github.com/weilung/dflow-sdd-ddd/issues/new/choose → choose
+**"{Issue form name}"**. (A GitHub account is all you need; the title is
+auto-prefixed with `{prefix}`.)
+
+## Title
+
+```
+{prefix}{concise one-line summary}
+```
+
+## {Field label} (required)
+
+```
+{field content; copy the inner text only, not this fence}
+```
+
+... one block per field, in form order ...
+
+## Before you submit (submitter self-check)
+
+- [ ] Any real file names / customer names / internal project code names to redact?
+- [ ] If you attach screenshots, do they show sensitive content (internal systems, tokens, passwords)?
+- [ ] Is opening a public issue within what your organization allows?
+````
+
+Keep the draft **submitter-facing only**: no maintainer tracking notes, no
+internal references, no "for your friend / for yourself" audience switches.
+
+## Upstream Issue Forms (bundled field map)
+
+> Snapshot of the `weilung/dflow-sdd-ddd` issue forms. If the live `.yml` is
+> reachable (Step 4 priority 1), prefer it. Resync this map when the upstream
+> forms change.
+
+### Bug report — title `[Bug]: `
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| Dflow version | input | yes | placeholder `0.2.0` |
+| Node.js version | input | yes | from `node --version` |
+| Project track | dropdown | yes | Greenfield / Brownfield / Not sure |
+| Command or workflow | textarea | yes | the command or `/dflow:*` workflow used |
+| Expected behavior | textarea | yes | |
+| Actual behavior | textarea | yes | include relevant output |
+| Reproduction steps | textarea | yes | smallest steps that reproduce |
+| Additional context | textarea | no | screenshots / snippets / environment |
+
+### Workflow change request — title `[Workflow]: `
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| Problem | textarea | yes | |
+| Proposed change | textarea | yes | |
+| Affected track | dropdown | yes | Greenfield / Brownfield / Both / Not sure |
+| Affected area | checkboxes | no | CLI command / Generated template / Generated scaffolding / Skill workflow guidance / Tutorial or examples / Documentation only |
+| Compatibility risk | textarea | yes | |
+| Alternatives considered | textarea | no | |
+
+### Documentation feedback — title `[Docs]: `
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| Affected page or file | input | yes | placeholder `README.md` |
+| Reader goal | textarea | yes | what you were trying to understand or do |
+| What was confusing? | textarea | yes | the missing, unclear, or misleading part |
+| Suggested improvement | textarea | no | optional wording or structure |
+
+### Question — title `[Question]: `
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| Project type | dropdown | yes | New project / Existing project / Not sure |
+| Dflow track you are considering | dropdown | yes | Greenfield / Brownfield / Not sure |
+| What are you trying to do? | textarea | yes | the workflow or decision you need help with |
+| Project context | textarea | no | framework, team workflow, AI agent, constraints |
+
+## Step 6: Generic Fallback
+
+Use this only when the feedback matches none of the forms above. The upstream
+repo disables blank issues, so direct the developer to pick the closest form at
+`https://github.com/weilung/dflow-sdd-ddd/issues/new/choose` and adapt. Emit
+two paste-ready blocks — a `Title` and a `Body` — plus the URL. Do **not** fall
+back to a generic `## Problem` / `## Evidence` Markdown draft.
+
+## Step 7: Present Submission Options
+
+After writing the draft, name the draft file path and whether any submitter
+self-check items remain unchecked, then summarize the options:
+
+- Open the chosen issue form and paste each field block.
+- Discard the draft if it was only a local observation.
+
+Do not submit anything automatically.

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

@@ -0,0 +1,183 @@
+# 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`, 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
+- 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
+```
+
+## 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` 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).
+
+## 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