dsh-plugin-guide 0.3.31 → 0.3.33

package/dist/dsh-plugin-dev.js

@@ -1655,6 +1655,183 @@ async function initGit(targetDir) {
 	});
 }
 
+//#endregion
+//#region src/cli/lib/seams.ts
+/** Resolve the index path, tolerating the source tree and the bundled dist. */
+function resolveSeamIndexPath() {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const candidates = [
+		join(here, "..", "..", "..", "data", "seams", "index.json"),
+		join(here, "..", "..", "data", "seams", "index.json"),
+		join(here, "..", "data", "seams", "index.json"),
+		join(here, "data", "seams", "index.json")
+	];
+	for (const c of candidates) try {
+		readFileSync(c);
+		return c;
+	} catch {}
+	throw new Error("seam index not found; expected data/seams/index.json next to the package root");
+}
+/** Load and parse the seam index. */
+function loadSeamIndex(path = resolveSeamIndexPath()) {
+	return JSON.parse(readFileSync(path, "utf8"));
+}
+/**
+* Look up a seam or capability by id, area, or a free-text substring.
+*
+* @param index - parsed seam index.
+* @param query - id (`L3`, `A20`), area substring, or any word in a title.
+* @returns matches, or `state: 'unknown'` with a reason when nothing matches.
+*/
+function lookupSeam(index, query) {
+	const q = query.trim().toLowerCase();
+	const exactSeam = index.seams.filter((s) => s.id.toLowerCase() === q);
+	const exactCap = index.capabilities.filter((c) => c.id.toLowerCase() === q);
+	if (exactSeam.length || exactCap.length) return {
+		query,
+		state: "found",
+		seams: exactSeam,
+		capabilities: exactCap
+	};
+	const seams = index.seams.filter((s) => s.title.toLowerCase().includes(q) || s.kind.toLowerCase().includes(q) || s.target.toLowerCase().includes(q) || s.removed.some((r) => r.toLowerCase().includes(q)) || (s.ids ?? []).some((i) => i.toLowerCase().includes(q)));
+	const capabilities = index.capabilities.filter((c) => c.area.toLowerCase().includes(q) || c.introducedIn.toLowerCase().includes(q));
+	if (!seams.length && !capabilities.length) return {
+		query,
+		state: "unknown",
+		seams: [],
+		capabilities: [],
+		reason: `no seam or capability matches "${query}". This is an absence of evidence in the knowledge base, not evidence that the API is absent from your target host — check references/official-docs/ before concluding either way.`
+	};
+	return {
+		query,
+		state: "found",
+		seams,
+		capabilities
+	};
+}
+/** Total order over DSH version strings. */
+function rank(v) {
+	const m = /^(?:dsh-v)?(\d+)\.(\d+)\.(\d+)(?:-([a-z]+)(?:\.(\d+))?)?$/i.exec(v.trim());
+	if (!m) return [
+		NaN,
+		0,
+		0,
+		0,
+		0
+	];
+	const channel = m[4] === "alpha" ? 1 : m[4] === "rc" ? 2 : m[4] === void 0 ? 3 : 0;
+	return [
+		Number(m[1]),
+		Number(m[2]),
+		Number(m[3]),
+		channel,
+		Number(m[5] ?? 0)
+	];
+}
+/** Compare two ranks; a NaN on either side compares as "unknown", never "after". */
+function cmp(a, b) {
+	if (Number.isNaN(a[0]) || Number.isNaN(b[0])) return NaN;
+	for (let i = 0; i < 5; i++) if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+	return 0;
+}
+/**
+* Every recorded change that lands AFTER the given target version.
+*
+* A target this build cannot parse yields an empty list rather than everything:
+* reporting the whole index for an unparseable query would read as "all of this
+* changed for you", which is worse than reporting nothing.
+*
+* @param index - parsed seam index.
+* @param target - the version the plugin targets.
+* @returns matching seam records.
+*/
+function seamsAfter(index, target) {
+	const want = rank(target);
+	if (Number.isNaN(want[0])) return [];
+	return index.seams.filter((s) => {
+		const got = cmp(rank(s.target.replace(/^(?:removed|retired) in /, "")), want);
+		return !Number.isNaN(got) && got > 0;
+	});
+}
+
+//#endregion
+//#region src/cli/commands/seams.ts
+/** Render one seam record as human-readable text. */
+function renderSeam(s, out) {
+	out.push(`${s.id}  ${s.title}`);
+	out.push(`    kind        ${s.kind}`);
+	out.push(`    lands in    ${s.target}`);
+	out.push(`    confidence  ${s.confidence}${s.inferredFrom ? ` (${s.inferredFrom})` : ""}`);
+	out.push(`    official    ${s.doc}`);
+	if (s.removed.length) out.push(`    removed     ${s.removed.join("; ")}`);
+	out.push(`    instead     ${s.replacement}`);
+	out.push(s.detectable ? `    detectable  yes — inspect: ${s.targets.join(", ")}` : `    detectable  NO — ${s.undetectableReason ?? "no reason recorded"}`);
+	out.push("");
+}
+/** Render one capability record. */
+function renderCapability(c, out) {
+	out.push(`${c.id}  ${c.area}`);
+	out.push(`    introduced  ${c.introducedIn}`);
+	out.push(`    anchor      ${c.anchor}`);
+	out.push(`    confidence  ${c.confidence}${c.inferredFrom ? ` (${c.inferredFrom})` : ""}`);
+	out.push("");
+}
+/**
+* Run the seams command.
+*
+* @param index - parsed seam index.
+* @param options - query, since, json.
+* @returns exit code: 0 when answered, 2 for a usage problem, 3 for unknown.
+*/
+function runSeams(index, options) {
+	if (options.since !== void 0) {
+		const hits = seamsAfter(index, options.since);
+		if (options.json) {
+			process.stdout.write(`${JSON.stringify({
+				since: options.since,
+				count: hits.length,
+				seams: hits
+			}, null, 2)}\n`);
+			return 0;
+		}
+		if (hits.length === 0) {
+			process.stdout.write(`No recorded change lands after ${options.since}.\nThat is bounded by this index's coverage (${index.seams.length} records, measured ${index.measuredAt}, baseline ${index.hostBaseline}) — not a guarantee about releases newer than the baseline.\n`);
+			return 0;
+		}
+		const out = [`${hits.length} change(s) land after ${options.since}:`, ""];
+		for (const s of hits) renderSeam(s, out);
+		const undetectable = hits.filter((s) => !s.detectable).length;
+		out.push(`Note: ${undetectable} of ${hits.length} cannot be detected by static inspection; they are advisory and must not be reported as passing.`);
+		process.stdout.write(`${out.join("\n")}\n`);
+		return 0;
+	}
+	const query = options.query;
+	if (!query) {
+		process.stderr.write("seams: give a query (a seam id, a capability area, or a word) or --since <version>\n");
+		return 2;
+	}
+	const result = lookupSeam(index, query);
+	if (options.json) {
+		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+		return result.state === "unknown" ? 3 : 0;
+	}
+	if (result.state === "unknown") {
+		process.stdout.write(`${result.reason}\n`);
+		return 3;
+	}
+	const out = [];
+	if (result.seams.length) {
+		out.push(`${result.seams.length} seam(s):`, "");
+		for (const s of result.seams) renderSeam(s, out);
+	}
+	if (result.capabilities.length) {
+		out.push(`${result.capabilities.length} capability record(s):`, "");
+		for (const c of result.capabilities) renderCapability(c, out);
+	}
+	process.stdout.write(`${out.join("\n")}\n`);
+	return 0;
+}
+
 //#endregion
 //#region src/cli/commands/verify.ts
 /**
@@ -1929,6 +2106,13 @@ Commands:
                   Flags: --cwd <dir> --dsh <bin> --pnpm <bin> --profile <name>
                          --base <spec> --headless <spec> --timeout <ms>
                          --smoke-timeout <ms>
+  seams <query>   Ask whether an API or capability exists in a target host:
+                  a seam id (L3), a capability id (A20), a version, or a word.
+                  Exits 3 when the knowledge base does not establish an answer —
+                  which is NOT a "no". Flags: --json
+  seams --since <version>
+                  List every recorded breaking change that lands AFTER a version
+                  you target, flagging which ones static inspection cannot see.
 
 Global:
   -h, --help      Show this help
@@ -1975,7 +2159,9 @@ async function main(argv, cwd = process.cwd()) {
 		"base",
 		"headless",
 		"timeout",
-		"smoke-timeout"
+		"smoke-timeout",
+		"since",
+		"query"
 	];
 	let parsed;
 	try {
@@ -2043,6 +2229,15 @@ async function main(argv, cwd = process.cwd()) {
 				} else process.stdout.write("verify: OK\n");
 				return result.exitCode;
 			}
+			case "seams": {
+				const since = flagString(flags, "since");
+				const query = positionals[1] ?? flagString(flags, "query");
+				return runSeams(loadSeamIndex(), {
+					query,
+					since,
+					json: flagBool(flags, "json")
+				});
+			}
 			default:
 				process.stderr.write(`unknown command "${command}"\n\n${HELP}`);
 				return 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.3.31",
+  "version": "0.3.33",
   "description": "DSH plugin development as an on-demand agent skill: official docs mirror, version-compatibility matrix, migration seams, measured pitfalls, plus a scaffolder, checker and pack verifier CLI.",
   "type": "module",
   "main": "index.js",
@@ -23,6 +23,7 @@
     "locale/*.json",
     "icon.svg",
     "SKILL.md",
+    "data",
     "guide",
     "references",
     "scripts",
@@ -65,6 +66,9 @@
     "test": "vitest run",
     "check:readmes": "node scripts/check-readme-sync.mjs",
     "check:parity": "node scripts/check-readme-parity.mjs",
+    "check:facts": "node scripts/check-facts.mjs",
+    "check:docs-drift-detail": "node scripts/check-docs-drift-detail.mjs",
+    "measure:mirror": "node scripts/measure-mirror-references.mjs",
     "check:ps1-bom": "node scripts/check-ps1-bom.mjs",
     "build:llms": "node scripts/build-llms-full.mjs",
     "check:kit": "pwsh -File scripts/verify-kit.ps1",

package/references/cli-positioning-decision.md

@@ -0,0 +1,78 @@
+# CLI 定位决策：`dsh-plugin-dev check` / `verify` 该不该存在（2026-10-13）
+
+> **本文回答一个具体的工程质疑**（来自 `_analysis/v2-6-forward-compat.md` §5）：
+> 同族已有 33 项、带裁定语义与退出码契约的 `dsh-plugin-doctor`，本库的 16 项检查是不是**更弱的重复**，
+> 该不该削减甚至删掉？
+>
+> **结论：保留，但把分工写成不可含糊的三条。** 下面是判据与"什么情况下该反过来削减"的触发条件。
+
+---
+
+## 1. 先摆事实（实测，不是估计）
+
+| 事实 | 值 | 来源 |
+|---|---|---|
+| 本库检查项 | **16** | `src/cli/skill-sections.ts` 的引用表，`check-facts.mjs` 断言 |
+| 同族 `dsh-plugin-doctor` 检查项 | **33**（规范门禁 21） | `guide/family-toolchain.md` §2 |
+| 本库**独有**的检查 | **5** | `guide/family-toolchain.md` §3.2 交叉对照表 |
+| `check` 是否跑在任何工作流里 | **否** | `.github/workflows/` 无任何步骤调用它 |
+| `dsh-plugin-doctor` 是否是本仓 CI 门禁 | **是** | `plugin-doctor.yml` 以精确版本钉住调用 |
+| 本库 `check` 的代码量 | 781 行 + 13 个测试块 | `src/cli/commands/check.ts` |
+
+**光看这张表，"砍掉"是合理结论**：11 项是更弱的重复，且它不在任何门禁里——一份没人跑、又和别人重叠的检查，维护成本是纯支出。
+
+## 2. 但有三个事实让"砍掉"不成立
+
+### 2.1 独有 5 项里有 1 项是家族唯一的检测器
+
+`redline-async-apply-registration` 检测 **async `apply()` 在首个 `await` 之后注册**——这个缺陷在卸载窗口内
+静默丢失注册，表现为"装了、日志全绿、能力时有时无"。同族 `dsh-plugin-upgrade` 的 `legC` 走廊卡
+**明确点名本库这个 lint** 作为 seam E2 的预防门（见 `guide/family-toolchain.md` §3.2）。
+`dsh-plugin-doctor` 的 `K5` 只查 `apply` 的**返回形态**，查不到注册顺序。
+
+删掉它，家族内就没有任何东西能机械发现这个缺陷。
+
+### 2.2 本库的检查**每一项都链回可读章节**
+
+`dsh-plugin-doctor` 的裁定有严格的退出码契约与降级语义，但它的输出是**判定**；
+本库 `check` 的每一项都带 `skillRef`，指向该规则在知识库里的**正文**。
+两者面向不同需求：**"过没过" vs "为什么、该改哪一行"**。这是本库存在的理由，不是重复。
+
+> 这条承诺此前**部分是空的**——审计发现 2 项引用了根本没写该规则的章节，11 项引用的标题已漂移。
+> 本轮已全部修正，并加 `tests/skill-sections.test.ts` 防再漂。**承诺现在是可验证的。**
+
+### 2.3 `verify` 的价值不在强度，而在**零依赖自足**
+
+`verify` 在 D 组各轴都弱于 doctor（D9 甚至是反的：它删掉自己的沙箱）。
+但它**只用 Node 内置模块**，能在没有 network、没有 pnpm 全局状态、没有 doctor 安装的机器上跑完
+`pack → 干净 DSH_HOME 安装 → 启动 → 卸载`。对"第一次接手的作者"和离线环境，这是唯一能跑的那条。
+
+## 3. 因此的分工（写死，不再含糊）
+
+| 问题 | 用哪个 | 为什么 |
+|---|---|---|
+| "我这项改动过没过？给个裁定和 CI 退出码" | **`dsh-plugin-doctor`** | 33 项、有裁定语义、有降级检测、已是本仓门禁 |
+| "为什么这条规则存在？我该改哪一行？" | **本库 `check`** | 每项带 `kb` 引用，指向正文 |
+| "我这台机器什么都没有，先自证一下" | **本库 `verify`** | 零依赖、离线可跑 |
+| "这个缺陷同族还有谁能发现？" | **本库 `check`** 的 async-apply lint | 家族唯一 |
+
+**发布前建议两个都跑**，`SKILL.md` 与 README 已这样写。
+
+## 4. 反过来：什么情况下应该削减
+
+本文不是"永远保留"。以下任一条件成立，就该重新裁定：
+
+1. **`dsh-plugin-doctor` 获得异步注册顺序检查**（例如 `K5` 扩展为同时校验注册时序）——
+   那 2.1 的唯一性消失，本库的 `check` 就退化为"带文档链接的 doctor 子集"，应削减到文档链接层。
+2. **doctor 的裁定输出开始携带正文引用**——那 2.2 的差异消失。
+3. **本库 `check` 连续 3 个版本没有新增或修正任何检查**——说明它已停止演化，
+   而维护成本（781 行 + 13 测试块 + 约 45% 的历史 churn）仍在支付。
+
+**触发条件应定期核**：`guide/family-toolchain.md` 的交叉对照表是唯一需要更新的地方。
+
+## 5. 本轮已做的、与此决策无关的改进
+
+- 修掉 11 处 citation 漂移与 2 处"引用不存在的规则"（`tests/skill-sections.test.ts` 现在守着）。
+- `check --stirct` 这类拼写错误此前静默退出 0，现在报 `UsageError` 并以退出码 2 结束。
+- `manifest-files` 此前无条件要求 `lib`/`dist` 目录，导致 `new --lang js` 过不了自己的 `check`；已修，
+  并在 `verify-artifacts.mjs` 里加了 **scaffold → check 往返断言**——这正是当初漏掉它的原因。

package/references/mirror-scope-decision.md

@@ -5,14 +5,17 @@
 审计（`v2-2`、`v2-7`）建议剔除零引用内容以回收约 80% 体积。**精确复测后这个建议不成立**，
 因为"零引用"是按**窄口径**统计的，而本库自己声明的路由是**宽 glob**。
 
-## 复测数据（`_analysis/_mirror-trim-plan.mjs`，可复跑）
+## 复测数据（可复跑）
 
-扫描 33 份自有文档，把镜像 708 个文件按"被引用强度"分档：
+复现命令：`node scripts/measure-mirror-references.mjs`（随包发布，不需要网络）。
+
+扫描 33 份自有文档，把镜像文件按"被引用强度"分档：
 
 | 引用强度 | 文件数 | 体积 |
 |---|---:|---:|
-| 按确切路径被点名 | 73 | 2.22 MB |
-| 仅被目录 glob 覆盖 | 623 | 20.17 MB |
+| 按确切路径被点名 | 79 | 2.29 MB |
+| 仅被目录 glob 覆盖 | 617 | 20.10 MB |
+| 纯按 basename 命中 | 5 | 0.04 MB |
 | **完全无引用** | **3** | **≈4 KB** |
 
 仅被 glob 覆盖的部分按扩展名拆开：
@@ -20,10 +23,14 @@
 | 扩展名 | 文件数 | 体积 |
 |---|---:|---:|
 | `.json`（历史 session-format schema） | 45 | **13.97 MB** |
-| `.md` | 362 | 5.26 MB |
+| `.md` | 356 | 5.19 MB |
 | `.yaml`（`.i18n.yaml` 翻译哈希） | 212 | 0.54 MB |
 | `.png` | 4 | 0.39 MB |
 
+> **口径**：只有当 glob 目录是路径的**前缀**时才算覆盖（`docs/persistence-changes/**` 覆盖其下文件，
+> 而裸 `docs/**` 不能推导出"`docs/` 下全部都被引用"）。最初的审计按"段名出现在任意位置"匹配，
+> 因此把镜像算成"绝大多数无引用"——**这正是本轮复测推翻它的地方**。
+
 ## 为什么不能按"零引用"删
 
 本库**自己声明**的路由就是宽 glob，这些 glob 出现在 `SKILL.md` 与多份指南里：
@@ -68,5 +75,5 @@
 **镜像保持逐字完整**。本文件的作用是把 R1 从"待清理"改判为
 "**已评估、结论是不做，理由是被 glob 覆盖而非零引用**"，避免下一个会话重复提出同一建议。
 
-> 复跑方式：`node _analysis/_mirror-trim-plan.mjs`
-> （`_analysis/` 在 `.gitignore` 中；如需长期保留本结论，见 `guide/family-toolchain.md` 的说明）
+> 复跑方式：`node scripts/measure-mirror-references.mjs`
+> （脚本随包发布，在 `scripts/` 下；无需网络，不依赖任何一次性工作稿。）

package/scripts/check-docs-drift-detail.mjs

@@ -0,0 +1,145 @@
+// Answer "WHAT changed upstream?", not just "is the mirror stale?".
+//
+// `check-docs-drift.ps1` compares the upstream branch-tip SHA against the SHA
+// recorded in `references/official-docs/SNAPSHOT.md`. When they differ it says so
+// and stops — a maintainer still has to work out which of ~700 mirrored files
+// moved. A drift report that names no file is why the weekly job can sit red for
+// eleven weeks without anyone acting on it.
+//
+// This script names the files: it compares the pinned commit's tree against the
+// upstream head's tree and lists added, removed, and modified paths inside the
+// mirror's declared scope.
+//
+// Usage:
+//   node scripts/check-docs-drift-detail.mjs [--commit <sha>] [--json]
+//   node scripts/check-docs-drift-detail.mjs --checkout D:\deepseek-harness
+//
+// Exit codes: 0 = fresh or report produced, 2 = could not probe, 1 = drift (with --fail-on-drift).
+
+import { execFileSync } from 'node:child_process'
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const root = process.cwd()
+const argv = process.argv.slice(2)
+const flag = (name, fallback) => {
+  const i = argv.indexOf(name)
+  return i >= 0 ? (argv[i + 1] ?? true) : fallback
+}
+const asJson = argv.includes('--json')
+const failOnDrift = argv.includes('--fail-on-drift')
+const checkout = flag('--checkout', null)
+
+const SNAPSHOT = join(root, 'references', 'official-docs', 'SNAPSHOT.md')
+const MIRROR = join(root, 'references', 'official-docs')
+
+// The mirror's declared scope, matching sync-official-docs.ps1 `$paths` exactly.
+// `packages/` contributes only AGENTS.md and README.md, and `vendor/` only
+// README.md — a bare directory prefix would report every package file as
+// "missing from the mirror", which is 2,000 paths of noise.
+const SCOPE_EXACT = new Set([
+  'AGENTS.md',
+  'BENCHMARK.md',
+  'CONTRIBUTING.md',
+  'CONTRIBUTING.zh.md',
+  'CONTRIBUTING.i18n.yaml',
+  'README.zh.md',
+  'README.i18n.yaml',
+  'THIRD_PARTY_NOTICES.md',
+  'LICENSE',
+  'packages/AGENTS.md',
+  'packages/README.md',
+  'vendor/README.md',
+  'website/docs.ts',
+])
+const inScope = (p) => p.startsWith('docs/') || SCOPE_EXACT.has(p)
+
+/** The scope, for the report header. */
+const SCOPE = ['docs/', ...SCOPE_EXACT]
+
+/** Read the pinned SHA and scope out of SNAPSHOT.md. */
+function readSnapshot() {
+  const text = readFileSync(SNAPSHOT, 'utf8')
+  const sha = /^\|\s*Source commit\s*\|\s*`([0-9a-f]{40})`\s*\|/m.exec(text)?.[1]
+  if (!sha) throw new Error(`cannot parse the pinned Source commit from ${SNAPSHOT}`)
+  return { sha, text }
+}
+
+/** git against the local checkout. */
+function git(args) {
+  return execFileSync('git', ['-C', checkout, ...args], { encoding: 'utf8', maxBuffer: 1 << 28 })
+}
+
+/** path -> blob sha for a commit's tree, via the local checkout. */
+function treeOf(rev) {
+  const out = git(['ls-tree', '-r', '--format=%(objectname) %(path)', rev])
+  const map = new Map()
+  for (const line of out.split('\n')) {
+    const sp = line.indexOf(' ')
+    if (sp < 0) continue
+    map.set(line.slice(sp + 1), line.slice(0, sp))
+  }
+  return map
+}
+
+const report = { scope: SCOPE, added: [], removed: [], modified: [] }
+
+if (checkout) {
+  if (!existsSync(checkout)) {
+    console.error(`ERROR: checkout not found: ${checkout}`)
+    process.exit(2)
+  }
+  const { sha: pinned } = readSnapshot()
+  const head = git(['rev-parse', 'HEAD']).trim()
+  const upstreamRev = git(['rev-parse', 'origin/master']).trim()
+  const target = flag('--commit', upstreamRev)
+  let a
+  let b
+  try {
+    a = treeOf(pinned)
+    b = treeOf(target)
+  } catch (err) {
+    console.error(`ERROR: cannot read a tree (${err.message.split('\n')[0]}). Is ${pinned.slice(0, 7)} present in the checkout?`)
+    process.exit(2)
+  }
+  for (const [p, s] of b) {
+    if (!inScope(p)) continue
+    if (!a.has(p)) report.added.push(p)
+    else if (a.get(p) !== s) report.modified.push(p)
+  }
+  for (const p of a.keys()) if (inScope(p) && !b.has(p)) report.removed.push(p)
+  report.pinned = pinned
+  report.target = target
+  report.head = head
+  report.mode = 'checkout'
+} else {
+  console.error('ERROR: pass --checkout <deepseek-harness>; the API mode is not implemented (the mirror is pinned to a commit, and a tree comparison needs both trees).')
+  process.exit(2)
+}
+
+const total = report.added.length + report.removed.length + report.modified.length
+if (asJson) {
+  console.log(JSON.stringify({ ...report, total }, null, 2))
+} else {
+  console.log(`pinned : ${report.pinned}`)
+  console.log(`target : ${report.target}${report.target === report.head ? ' (checkout HEAD)' : ''}`)
+  console.log('')
+  if (total === 0) {
+    console.log('FRESH: no in-scope file differs between the pinned commit and the target.')
+  } else {
+    console.log(`DRIFT: ${total} in-scope file(s) differ`)
+    const show = (label, list) => {
+      if (!list.length) return
+      console.log(`\n  ${label} (${list.length}):`)
+      for (const p of list.slice(0, 25)) console.log(`    ${p}`)
+      if (list.length > 25) console.log(`    ... and ${list.length - 25} more`)
+    }
+    show('ADDED upstream (the mirror is missing these)', report.added)
+    show('REMOVED upstream (the mirror still carries these)', report.removed)
+    show('MODIFIED upstream (the mirror has stale content)', report.modified)
+    console.log('\nAction: run  pwsh -File scripts/sync-official-docs.ps1  to refresh the mirror (never hand-edit it).')
+  }
+}
+
+if (total > 0 && failOnDrift) process.exit(1)
+process.exit(0)