dflow-sdd-ddd 0.12.0 → 0.14.0

package/docs/using-with-github-copilot.md

@@ -137,11 +137,14 @@ dflow configure-agents --command-adapters
 **連字號** `/dflow-<id>`，不是 canonical 的**冒號** `/dflow:<id>`——後者是
 Claude / Codex 的命令寫法，在 Copilot 只能當文字稱呼、不能當命令輸入。
 
-### `--skills` flag 與 Copilot 的 skill 觸發
+### Copilot 的 skill 觸發（init 預設安裝）
 
-`dflow configure-agents --skills` 會為 **Claude Code、Codex 與 GitHub Copilot**
+Dflow 會為 **Claude Code、Codex 與 GitHub Copilot**
 各自投影同一份工具中立的 thin skill 到它們的 project-level skill 路徑；Copilot 的是
-`.github/skills/dflow/SKILL.md`。實測（2026-06-05）確認 Copilot 會從**自己原生的
+`.github/skills/dflow/SKILL.md`。這份 skill 現在**預設安裝**：`dflow init` 有選
+Copilot 就裝（互動問一題預設 Y、非互動直接裝）、`dflow configure-agents` 對新選且
+尚無 skill 的 Copilot 也補問；`dflow configure-agents --skills` 用於補裝或強制
+重生成。實測（2026-06-05）確認 Copilot 會從**自己原生的
 `.github/skills/`** 探索並運作（即使移除 `.claude`/`.agents` 的跨讀路徑也成立），
 觸發方式依介面而異——**VS Code Chat 自然語言自動觸發**、**Copilot CLI 需打 `/dflow`
 手動喚起**（細節見上方介面 A / B）。
@@ -175,8 +178,10 @@ git rm --cached .github/prompts/dflow-*.prompt.md
 （`--cached` 只移出版控、保留工作目錄檔案。）
 
 升級 dflow 後重跑 `dflow configure-agents --command-adapters`，prompt adapter 會用**新版 registry**
-重投影；但既有 `dflow/specs/shared/AI-AGENT-GUIDE.md` **不會**被覆寫——「重投影 adapter」不等於
-「升級 canonical guide」。請以**相同的 dflow CLI 版本**重投影。
+重投影；`dflow/specs/shared/AI-AGENT-GUIDE.md` 內**帶 marker 的 canonical 區**也會原地刷新
+（marker 以外——含 `## Project Context`——保留不動）。較舊專案的 guide 還沒有 marker 時，
+互動執行會詢問是否採用（預設 N）、非互動則跳過並警告。請以**相同的 dflow CLI 版本**重投影，
+升級後先跑 `dflow doctor` 檢視殘餘漂移（read-only）。
 
 ### 對話範例
 
@@ -206,7 +211,9 @@ Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
 
 如果你的專案中已有 `.github/copilot-instructions.md`，`init` 不會覆蓋自訂內容。
 已是 Dflow-generated shim 的檔案會原地刷新；其他已指向
-`dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過。若既有檔案尚未指向 guide，
+`dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過並警告——之後在互動終端跑
+`dflow configure-agents` 會詢問是否附加帶 marker 的管理區塊（預設 N），非互動
+執行維持略過並警告。若既有檔案尚未指向 guide，
 Dflow 會在確認 preview 顯示並於檔案末尾附加帶有
 `<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block；重跑會
 原地更新同一段，不會重複。這樣可以避免破壞你已有的自訂 Copilot 指示。若你刪除
@@ -287,7 +294,7 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 
 如果你已執行 `init` 且想查看端到端的 workflow 範例：
 
-- 閱讀 [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../sdd-ddd-greenfield-skill/scaffolding/AI-AGENT-GUIDE.md)
+- 閱讀 [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../templates/greenfield/scaffolding/AI-AGENT-GUIDE.md)
   （或 brownfield 等效版本）後再開始 workflow。
 - 閱讀 [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)，
   其中有展示 Copilot chat flow 的對話範例。

package/lib/doctor-checks.js

@@ -0,0 +1,178 @@
+// PROPOSAL-058: pure, shippable drift-detection helpers for `dflow doctor`.
+//
+// The dev-only cross-ref resolver (scripts/check-cross-refs.mjs, PROPOSAL-055)
+// is not part of the npm package, so the runtime checks reimplement the narrow
+// subset doctor needs: fence-aware heading extraction, "<file> § Heading"
+// reference extraction with soft-wrap joining, tolerant heading matching, and
+// template-shape comparison. Everything here is I/O-free — callers read the
+// files and pass contents — which keeps the checks unit-testable.
+
+'use strict';
+
+// Machine-readable context lines. Shared with lib/init.js inference so the
+// doctor "machine format" checks can never drift from what inference actually
+// parses: inferGitPolicy / inferAiCommitMarker / inferProseLanguage read
+// _conventions.md; inferTechStackSummary / inferMigrationContext read the
+// `| Tech stack |` / `| Migration / legacy context |` rows of the guide's
+// "## Project Context" table (PROPOSAL-076 — no packaged _overview.md template
+// ever carried those rows).
+const GIT_POLICY_LINE_RE = /Selected Git policy:\s*`([^`]+)`/;
+const AI_COMMIT_MARKER_LINE_RE = /AI commit marker:\s*`([^`]+)`/;
+const PROSE_LANGUAGE_LINE_RE = /Project prose language:\s*`([^`]+)`/;
+// The row values accept Markdown-escaped pipes (`\|`) so a cell like
+// `Node \| Express` is captured whole; parseContextLine unescapes them
+// (PROPOSAL-076 gate G1 — a bare `[^|\n]` capture silently truncated at the
+// escaped pipe while doctor still called the row machine-readable).
+const TECH_STACK_ROW_RE = /\|\s*Tech stack\s*\|\s*((?:\\\||[^|\n])+?)\s*\|/i;
+const MIGRATION_CONTEXT_ROW_RE = /\|\s*Migration \/ legacy context\s*\|\s*((?:\\\||[^|\n])+?)\s*\|/i;
+
+const GIT_POLICY_VALUES = new Set(['gitflow', 'trunk']);
+const AI_COMMIT_MARKER_VALUES = new Set(['none', 'co-authored-by', 'prefix']);
+
+// Trimmed capture of a machine-readable context line, or null when the line is
+// absent or its value is whitespace-only. Inference and the doctor checks must
+// both parse through this helper: a value doctor accepts has to be the exact
+// value configure-agents consumes (e.g. a stray space inside the backticks
+// would otherwise pass doctor's trimmed validation yet miss strict comparisons
+// like buildSubstitutionMap's `gitflow` check downstream).
+function parseContextLine(content, re) {
+  const match = content.match(re);
+  if (!match) return null;
+  // Unescape Markdown-escaped pipes captured by the table-row patterns; the
+  // backtick context lines never contain `\|`, so this is a no-op for them.
+  const value = match[1].replace(/\\\|/g, '|').trim();
+  return value === '' ? null : value;
+}
+
+// Blank out fenced code blocks (``` / ~~~) line-by-line so headings and § refs
+// inside examples are never extracted. Line positions are preserved. CommonMark
+// close rules (PROPOSAL-076 gates G4/G6): a block closes only on the same fence
+// character repeated at least the opening length, indented at most three
+// spaces, with nothing but whitespace after — so a three-backtick line inside a
+// four-backtick example, or an info-string line like ```js inside an open
+// fence, is content and does not end the block early.
+function blankFencedBlocks(content) {
+  const lines = content.split(/\r?\n/);
+  const out = [];
+  let fenceChar = null;
+  let fenceLen = 0;
+  for (const line of lines) {
+    if (fenceChar) {
+      out.push('');
+      const close = line.match(/^[ \t]{0,3}(```+|~~~+)[ \t]*$/);
+      if (close && close[1][0] === fenceChar && close[1].length >= fenceLen) {
+        fenceChar = null;
+        fenceLen = 0;
+      }
+      continue;
+    }
+    const open = line.match(/^[ \t]{0,3}(```+|~~~+)/);
+    if (open) {
+      fenceChar = open[1][0];
+      fenceLen = open[1].length;
+      out.push('');
+      continue;
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+// All Markdown heading texts (any level), fence-aware.
+function extractHeadings(content) {
+  const headings = [];
+  for (const line of blankFencedBlocks(content)) {
+    const m = line.match(/^#{1,6}\s+(.+?)\s*#*\s*$/);
+    if (m) headings.push(m[1].trim());
+  }
+  return headings;
+}
+
+// H2 ("## ") heading texts only, fence-aware — the section shape of a template.
+function extractH2Headings(content) {
+  const headings = [];
+  for (const line of blankFencedBlocks(content)) {
+    const m = line.match(/^##\s+(.+?)\s*#*\s*$/);
+    if (m) headings.push(m[1].trim());
+  }
+  return headings;
+}
+
+// `<file>.md § Heading` references whose file basename is `targetBasename`.
+// A soft-wrapped heading name is captured by joining the next line; a match
+// anchored beyond the current line is left to that line's own iteration.
+function extractSectionRefs(content, targetBasename) {
+  const lines = blankFencedBlocks(content);
+  const refs = [];
+  lines.forEach((line, i) => {
+    const firstLen = line.replace(/\s+$/, '').length;
+    const joined = line.replace(/\s+$/, '') + ' ' + (lines[i + 1] || '').replace(/^\s+/, '');
+    for (const m of joined.matchAll(/`?([A-Za-z0-9._/-]+\.md)`?\s*§\s*"?([^."`)\n]+)/g)) {
+      if (m.index > firstLen) continue;
+      const base = m[1].split('/').pop();
+      if (base !== targetBasename) continue;
+      refs.push({ line: i + 1, headingText: m[2].trim() });
+    }
+  });
+  return refs;
+}
+
+function normalizeHeading(text) {
+  return text.replace(/[`*_]/g, '').trim();
+}
+
+// Tolerant heading resolution: a reference resolves when it prefix-matches a
+// real heading in either direction (covers soft wraps like "§ Workflow" for
+// "Workflow Transparency" and shorthand references).
+function headingResolves(referenceText, headings) {
+  const want = normalizeHeading(referenceText);
+  if (!want) return true;
+  return headings.some((heading) => {
+    const have = normalizeHeading(heading);
+    return have.startsWith(want) || want.startsWith(have);
+  });
+}
+
+// Which of the template's H2 sections are missing from a filled document — the
+// "created from an older template shape" signal.
+function missingTemplateSections(templateContent, documentContent) {
+  const have = new Set(extractH2Headings(documentContent).map(normalizeHeading));
+  return extractH2Headings(templateContent).filter((heading) => !have.has(normalizeHeading(heading)));
+}
+
+// True when `content` matches `templateContent` up to placeholder substitution:
+// every single-line `{...}` placeholder in the template may match any text.
+// Distinguishes "pristine current starter" from "edited or older starter"
+// without knowing the values init substituted.
+function matchesTemplateWithPlaceholders(content, templateContent) {
+  const normalize = (s) => s.replace(/\r\n/g, '\n').replace(/\s+$/, '');
+  const parts = normalize(templateContent).split(/\{[^}\n]*\}/);
+  const pattern = `^${parts.map(escapeRegExp).join('[\\s\\S]*?')}$`;
+  try {
+    return new RegExp(pattern).test(normalize(content));
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = {
+  GIT_POLICY_LINE_RE,
+  AI_COMMIT_MARKER_LINE_RE,
+  PROSE_LANGUAGE_LINE_RE,
+  TECH_STACK_ROW_RE,
+  MIGRATION_CONTEXT_ROW_RE,
+  GIT_POLICY_VALUES,
+  AI_COMMIT_MARKER_VALUES,
+  parseContextLine,
+  blankFencedBlocks,
+  extractHeadings,
+  extractH2Headings,
+  extractSectionRefs,
+  headingResolves,
+  missingTemplateSections,
+  matchesTemplateWithPlaceholders
+};