@modusensus/dsh-mneme 0.13.0 → 0.14.0-beta.1

package/lib/wiki/claims.js

@@ -0,0 +1,267 @@
+// dsh-mneme/src/wiki/claims.js
+// Claim 粒度的失效判定——借自 openwiki 的 Grounded Claims 设计：每条结论挂着「哪个
+// 文件、哪几行」的证据，代码一动就先算出「哪几条结论失准」，而不是把整个仓库判成
+// 过期、把全部语义段重跑一遍。
+//
+// 为什么值得做：choro_claims 早就存了 source_path / start_line / end_line（见 store.js
+// 的 choro_claims 表定义），三列本来就是为这件事准备的；可 t0.js 重跑时整页 claims 会被
+// 清空（replaceChoroGraph 的 pages[].claims = []），于是改一行代码就让所有页的语义段
+// 变成无主孤儿。本模块把「整仓过期」降成「哪页哪条」，代价是一次 git diff 加几十行
+// 纯计算：零模型、零网络、零写入。
+//
+// 只算「相对上次生成基线改了什么」，不判断代码本体——结论要留给读它的人。
+import { execFileSync } from "node:child_process";
+
+// git 对「含非 ASCII / 控制字符」的路径会加双引号并按 C 风格转义（core.quotepath 默认
+// 就是开的），例如中文名会写成 "a/\344\270\255\346\226\207.js"。只脱引号不解转义的话，
+// 归一出来的字符串永远对不上 choro_claims.source_path，这些文件上的结论就再也判不成
+// touched —— **漏判**比误判更难发现，因为它看起来一切正常。
+const GIT_PATH_ESCAPES = { a: "\x07", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t", v: "\v", '"': '"', "\\": "\\" };
+
+function unescapeQuotedGitPath(s) {
+  if (!s.includes("\\")) return s;
+  const bytes = [];
+  const pushStr = (str) => { for (const b of Buffer.from(str, "utf8")) bytes.push(b); };
+  for (let i = 0; i < s.length; i += 1) {
+    const ch = s[i];
+    if (ch !== "\\" || i === s.length - 1) { pushStr(ch); continue; }
+    const octal = /^[0-7]{3}/.exec(s.slice(i + 1));
+    if (octal) { bytes.push(parseInt(octal[0], 8) & 0xff); i += 3; continue; }
+    const escaped = GIT_PATH_ESCAPES[s[i + 1]];
+    if (escaped !== undefined) { pushStr(escaped); i += 1; continue; }
+    pushStr(ch);
+  }
+  return Buffer.from(bytes).toString("utf8");
+}
+
+// 路径归一：choro_claims.source_path 存的是仓库相对路径（正斜杠）；git 侧也是正斜杠，
+// 但 `--- a/x` `+++ b/x` 带前缀，可能需要去掉。转义只出现在被引号包起来的那种写法里，
+// 所以解转义严格跟着「这次是否脱过引号」走——不能对未加引号的路径无条件解，
+// 否则 Windows 风格的反斜杠会被当成转义序列吃掉。
+function normDiffPath(p) {
+  let s = String(p ?? "").trim();
+  const quoted = s.length >= 2 && s.startsWith('"') && s.endsWith('"');
+  if (quoted) s = unescapeQuotedGitPath(s.slice(1, -1));
+  if (s.startsWith("a/") || s.startsWith("b/")) s = s.slice(2);
+  return s.replace(/\\/g, "/");
+}
+
+/**
+ * 解析 `git diff --unified=0 <baseline> HEAD` 的文本。
+ *
+ * 只认 hunk 头 `@@ -a,b +c,d @@`：不解析正文，正文里带 `@@` 的代码行不会干扰，
+ * 因为 hunk 头必须匹配完整形状。两个计数都要——旧侧计数是新旧行坐标的唯一来源，
+ * claims 的行号记在**旧侧**（写 claim 时那一版就是 HEAD）。
+ *
+ * 不传 -M 还不够：git 在 `--unified=0` 下**仍会**自动开重命名检测（实测输出
+ * `similarity index 100% / rename from / rename to`，既不出 hunk 也不进 /dev/null），
+ * 于是重命名后旧路径上的 claim 会被判成「没事」。必须显式 `--no-renames`，让重命名
+ * 按「删旧 + 增新」处理：旧路径上的 claim 落进 deleted 是对的（锚点跟着文件走了，得
+ * 重新指），新路径没有 claim 自然也不会误报。
+ *
+ * 返回 { files: Map<path, [{oldStart, oldCount, newStart, newCount}]>, deleted: string[] }。
+ */
+export function parseDiffRanges(diffText) {
+  const files = new Map();
+  const deleted = [];
+  let livePath = null;
+  let oldPath = null;
+  for (const line of String(diffText ?? "").split("\n")) {
+    if (line.startsWith("diff --git ")) { livePath = null; oldPath = null; continue; }
+    if (line.startsWith("--- ")) { oldPath = normDiffPath(line.slice(4)); continue; }
+    if (line.startsWith("+++ ")) {
+      const raw = line.slice(4).trim();
+      if (raw === "/dev/null") {
+        // 整文件删除：claims 指向它的全部作废（没有出处就没有可校验的结论）。
+        if (oldPath) deleted.push(oldPath);
+        livePath = null;
+      } else {
+        livePath = normDiffPath(raw);
+        if (!files.has(livePath)) files.set(livePath, []);
+      }
+      continue;
+    }
+    const m = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (!m || livePath === null) continue;
+    files.get(livePath).push({
+      oldStart: Number(m[1]),
+      oldCount: m[2] === undefined ? 1 : Number(m[2]),
+      newStart: Number(m[3]),
+      newCount: m[4] === undefined ? 1 : Number(m[4]),
+    });
+  }
+  return { files, deleted };
+}
+
+/**
+ * 取基线到当前 HEAD 的 diff。基线不在仓库里（force-push / 浅克隆 / 换机重拉）时
+ * 不猜：回 { ok: false, reason }，调用方据此说「基线认不出了，建议重建」而不是
+ * 拿空 diff 报「全部结论都还准」——空 diff 与「算不出来」在页面上是两句话。
+ */
+export function diffSince(repoRoot, baseline, head) {
+  const clean = (v) => /^[0-9a-f]{7,40}$/i.test(String(v ?? "").trim());
+  if (!clean(baseline) || !clean(head)) return { ok: false, reason: "baseline-unreadable" };
+  try {
+    const text = execFileSync(
+      "git",
+      ["diff", "--unified=0", "--no-color", "--no-ext-diff", "--no-renames", `${baseline}..${head}`],
+      // --no-renames 是必需的，不是保险：git 会按配置自动开重命名检测（实测在
+      // --unified=0 下也开），一旦识别成 rename 就既不产生 hunk、也不产生 /dev/null，
+      // 旧路径上的 claim 会被静默判成 untouched。见本函数上方 parseDiffRanges 的说明。
+      // stdio 显式接管 stderr：execFileSync 默认把子进程 stderr 直接漏到父进程，
+      // 「不是 git 仓库」那条几十行的 usage 会污染面板日志，也会在测试输出里刷屏。
+      { cwd: repoRoot, encoding: "utf8", maxBuffer: 32 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }
+    );
+    return { ok: true, ...parseDiffRanges(text) };
+  } catch (err) {
+    // 两种情况在这里合流：`<基线>..HEAD` 里有 git 认不出的 rev（force-push 后
+    // 旧基线消失、浅克隆截断历史），或这个目录根本不是 git 仓库。对调用方是同一件
+    // 事：**算不出来**。别把 exit code 当 reason 抛给面板——面板要说的是人话。
+    return { ok: false, reason: "diff-failed", detail: String(err?.stderr ?? err?.message ?? err).trim().slice(0, 200) };
+  }
+}
+
+function normPath(p) {
+  return String(p ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+/**
+ * 逐条 claim 判「还准不准」。
+ *
+ * 四档理由，全部能从 diff 与三列证据机械算出：
+ *   - deleted      证据文件在基线之后被删了，这条结论没有出处了。
+ *   - touched      改动的行与 claim 的行区间相交，结论本身可能已经不对。
+ *   - shifted      claim 区间没被碰，但它上方有增删，行号整体偏移——内容还在，
+ *                  锚点要重新指。刻意与 touched 分开：混成一个「失效」，面板就会
+ *                  对着一堆只是行号错位的结论喊「要重写」，喊几次就没人信了。
+ *   - unverifiable 所属文件改过，可这条 claim 当初就没记行号，无法定位到具体一行。
+ *
+ * 输入 diff 为 { files: Map, deleted: string[] }；输出与输入等长，未受影响的
+ * reason 为 null（调用方自行过滤）。
+ */
+export function assessClaims(claims, diff) {
+  const files = diff?.files ?? new Map();
+  const deleted = new Set(diff?.deleted ?? []);
+  return (claims ?? []).map((claim) => {
+    const path = normPath(claim.sourcePath);
+    if (path === "") return { ...claim, reason: null };
+    if (deleted.has(path)) return { ...claim, reason: "deleted" };
+    const hunks = files.get(path);
+    if (!hunks || hunks.length === 0) return { ...claim, reason: null };
+    const start = Number.isInteger(claim.startLine) ? claim.startLine : null;
+    const end = Number.isInteger(claim.endLine) ? claim.endLine : start;
+    if (start === null || start < 1) return { ...claim, reason: "unverifiable" };
+    const sorted = [...hunks].sort((a, b) => a.oldStart - b.oldStart);
+    let shift = 0;
+    for (const h of sorted) {
+      const hOldEnd = h.oldCount === 0 ? h.oldStart : h.oldStart + h.oldCount - 1;
+      // 纯插入（`@@ -a,0 +c,d @@`，oldCount === 0）没有「旧行区间」，但它插在旧第 a 行
+      // 之后、第 a+1 行之前。落进 claim 区间内部（a >= start 且 a < end）就是真碰到了，
+      // 与「删除/替换」一样算 touched；插在 claim 首行之前只是把它推下去，仍算 shifted。
+      // 老写法 `h.oldCount > 0 && ...` 让纯插入永远不算相交——多行结论被插进新行时，
+      // 结论原文已被改变却报「没事」。
+      const overlaps = h.oldCount > 0
+        ? start <= hOldEnd && end >= h.oldStart
+        : h.oldStart >= start && h.oldStart < end;
+      if (overlaps) return { ...claim, reason: "touched", shift };
+      if (hOldEnd < start) shift += h.newCount - h.oldCount;
+    }
+    return shift === 0 ? { ...claim, reason: null } : { ...claim, reason: "shifted", shift };
+  });
+}
+
+/**
+ * 仓库级汇总：逐条判定 → 「哪几页、几条、因为什么」。
+ *
+ * claims 每项需带 pageSlug；pages 每项 { slug, title, hasT1, verifiedBaseline,
+ * verifiedAt, diffBaseline, baselineApprox, baselineUnknown, anchorStale }。
+ *
+ * 为什么 pages 要带验证基线、为什么还要 diffByPage：claims 的行号是**各自那页被
+ * 富化的那一刻**记下的。全仓只有一个 git_baseline（T0 的时点），拿它当所有 claims
+ * 的比对起点，会把「T1 之前就发生、claim 早已算进去」的改动误报成 touched——页越晚
+ * 富化越容易误报。所以每页按自己的 verifiedBaseline 分组各算一次 diff。
+ *
+ * hasT1 是页面正文里有 T1 段标记的页——这类页「正文有语义段、库里零条 claims」是
+ * t1.js 落盘非原子留下的残局（文件先落盘、DB 后写，中途崩了就成这样）。单独记进
+ * inconsistent：不修它的话这页永远「看起来没有可校验的证据」，一次都不会被标成需要复核。
+ *
+ * diffByPage(slug) 三态：diff 对象 = 算过了；null = 这一页没有可用的起点（判不了）。
+ * 「判不了」的结论一条都不标，页面用 baselineUnknown / anchorStale 两种不同的说法交代。
+ */
+export function summarizeClaims(claims, diff, { pages = [], diffByPage = null } = {}) {
+  const assessed = diffByPage
+    ? (claims ?? []).flatMap((claim) => assessClaims([claim], diffByPage(claim.pageSlug)))
+    : assessClaims(claims, diff);
+  const bySlug = new Map();
+  for (const page of pages) {
+    bySlug.set(page.slug, {
+      slug: page.slug,
+      title: page.title ?? page.slug,
+      hasT1: Boolean(page.hasT1),
+      verifiedBaseline: page.verifiedBaseline ?? null,
+      verifiedAt: page.verifiedAt ?? null,
+      // 实际拿来跑 diff 的起点：新数据就是 verifiedBaseline；老数据（本功能之前富化）
+      // 退到全仓基线，baselineApprox 标记「这不是当真的验证点，是保底起点」。
+      diffBaseline: page.diffBaseline ?? page.verifiedBaseline ?? null,
+      baselineApprox: Boolean(page.baselineApprox),
+      baselineUnknown: Boolean(page.baselineUnknown),
+      anchorStale: Boolean(page.anchorStale),
+      claims: 0,
+      atRisk: [],
+      inconsistent: false,
+    });
+  }
+  for (const claim of assessed) {
+    const slug = claim.pageSlug;
+    if (!bySlug.has(slug)) {
+      bySlug.set(slug, { slug, title: claim.pageTitle ?? slug, hasT1: false, claims: 0, atRisk: [], inconsistent: false });
+    }
+    const bucket = bySlug.get(slug);
+    bucket.claims += 1;
+    if (!claim.reason) continue;
+    bucket.atRisk.push({
+      claimId: claim.id ?? null,
+      statement: claim.statement,
+      kind: claim.kind ?? null,
+      sourcePath: claim.sourcePath,
+      startLine: claim.startLine ?? null,
+      endLine: claim.endLine ?? null,
+      reason: claim.reason,
+      shift: claim.shift ?? 0,
+    });
+  }
+  for (const bucket of bySlug.values()) {
+    bucket.inconsistent = bucket.hasT1 && bucket.claims === 0;
+    // 零条结论的页谈不上「哪次验证的」——骨架页不该因为没富化过就被标成「判不了」。
+    if (bucket.claims === 0) bucket.baselineUnknown = false;
+  }
+  const list = [...bySlug.values()].sort((a, b) => {
+    // 有风险的排前面，然后依次是：锚点对不上账的、起点认不出的、本来就是空的、
+    // 干净的。依次递减的严重度，是为了让「要动手」的永远在第一屏。
+    const rank = (p) =>
+      p.atRisk.length > 0 ? 0
+        : p.inconsistent ? 1
+          : p.anchorStale ? 2
+            : p.baselineUnknown ? 3
+              : 4;
+    return rank(a) - rank(b) || a.slug.localeCompare(b.slug);
+  });
+  const flat = list.flatMap((p) => p.atRisk);
+  const count = (reason) => flat.filter((c) => c.reason === reason).length;
+  return {
+    pages: list,
+    totals: {
+      pages: list.length,
+      claims: assessed.length,
+      atRiskClaims: flat.length,
+      atRiskPages: list.filter((p) => p.atRisk.length > 0).length,
+      touched: count("touched"),
+      shifted: count("shifted"),
+      deleted: count("deleted"),
+      unverifiable: count("unverifiable"),
+      inconsistentPages: list.filter((p) => p.inconsistent).length,
+      baselineUnknownPages: list.filter((p) => p.baselineUnknown).length,
+      anchorStalePages: list.filter((p) => p.anchorStale).length,
+    },
+  };
+}

package/lib/wiki/queries.js

@@ -13,7 +13,10 @@ import { join, resolve, sep } from "node:path";
 // 面板侧不另造一套判据——两套判据迟早会对同一仓库给出两个答案。
 import { gitHead } from "./t0.js";
 import { loadPlanFromRepo } from "./plan.js";
-import { TEMPLATE_VERSION } from "./render.js";
+import { TEMPLATE_VERSION, T1_SECTION_START } from "./render.js";
+// claim 失效判定的纯函数（借 openwiki 的 Grounded Claims）：解析 diff + 逐条比对
+// 三列证据。放独立模块是因为它零 DB、零 IO（除 diffSince 那一次 git），可单测。
+import { diffSince, summarizeClaims } from "./claims.js";
 
 // 页正文去 frontmatter / CHORO 标记行后作为嵌入文本（P40：嵌页级全文）。
 function pageEmbedText(content) {
@@ -94,10 +97,27 @@ export function createChoroQueries({ store }) {
       // legacy = 这个仓库里有页面是用旧模板（或 M0 的 NULL）渲染的：重跑一次 T0 就
       // 会把它们升级成当前模板，面板据此提示「建议重建」而不是让用户自己比对版本。
       legacy: legacyPages(row.id) > 0,
+      // enrichedPages：已经富化过（页面里有 T1 语义段、库里有 claims）的页数。
+      // 自动刷新要看它：这类页重跑 T0 会退回骨架，所以那条路必须先问一句。
+      enrichedPages: enrichedPageCount(row.id),
       lastRunAt: row.updated_at ?? null
     };
   }
 
+  /**
+   * 已富化的页数。判据取库里的 status（T1 成功后会写 enriched），而不是读盘找
+   * T1 标记——这是条给面板列表用的轻查询，几百页也不该逐文件 readFileSync。
+   * 两边可能短暂不一致（例如有人手改了 MD），但「要不要提醒」这种提示用途，
+   * 库里的账本就是最合适的真源；真正判断「会丢什么」的仍是 T0 的 collectT1Loss（读盘）。
+   */
+  function enrichedPageCount(repoId) {
+    const hit = db.prepare(
+      `SELECT COUNT(*) AS n FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id
+        WHERE m.repo_id = ? AND p.status = 'enriched'`
+    ).get(repoId);
+    return Number(hit?.n ?? 0);
+  }
+
   function legacyPages(repoId) {
     const hit = db.prepare(
       `SELECT COUNT(*) AS n FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id
@@ -368,6 +388,152 @@ export function createChoroQueries({ store }) {
     };
   }
 
+  /**
+   * Claim 粒度的失效清单（借 openwiki 的 Grounded Claims）：把「仓库代码变过就整仓过期」
+   * 降成「这 2 页里的 5 条结论被改动碰过」。
+   *
+   * 为什么放读侧而不写成后台任务：判据是纯机械的（git diff 的 hunk 区间 × claims 的
+   * 三列证据），不需要模型，一次 diff 几十毫秒——面板打开时现算，永远比任何落库的
+   * 缓存新鲜。写路径一条不加，红线不动。
+   *
+   * **比对起点是每页自己的 verified_baseline，不是全仓 git_baseline。** claims 的行号
+   * 是那页被富化的那一刻记下的；全仓基线是 T0 的时点。若 T1 晚于 T0（常态），用全仓
+   * 基线起算就会把「T1 之前就发生、claim 早已算进去」的改动也算进 diff，误报 touched。
+   * 所以按 verified_baseline 分组、每组各跑一次 git diff（同一起点只跑一次）。
+   *
+   * 五种「说不清」要分开说，别混成一个空清单：
+   *   - repo 不存在                      → null（调用方 404）
+   *   - git 读不到 HEAD                  → 全仓 anchorStale + reason "git-unreadable"
+   *   - 某页基线认不出（浅克隆/force-push）→ 该页 anchorStale，**其余页照常判**
+   *   - 某页没记过验证基线（老数据/拿不到 HEAD）→ 该页 baselineUnknown，一条不判
+   *   - 起点 == HEAD                     → 那组真没变，clean
+   */
+  function claimDrift(repoId) {
+    const repo = db.prepare("SELECT id, root_path, name, git_baseline FROM choro_repos WHERE id = ?").get(repoId);
+    if (!repo) return null;
+    const rootPath = String(repo.root_path ?? "");
+    const rows = db.prepare(
+      `SELECT c.id, c.statement, c.kind, c.source_path, c.start_line, c.end_line,
+              m.slug AS page_slug, m.title AS page_title, p.rel_path
+         FROM choro_claims c
+         JOIN choro_pages p ON c.page_id = p.id
+         JOIN choro_modules m ON p.module_id = m.id
+        WHERE m.repo_id = ? ORDER BY m.slug, c.id`
+    ).all(repoId);
+    // 页面清单单算：hasT1 只能读盘（标记写在正文里，库里没有这一列）；验证基线在库里。
+    const pageRows = db.prepare(
+      `SELECT m.slug, m.title, p.rel_path, p.verified_baseline, p.verified_at
+         FROM choro_pages p
+         JOIN choro_modules m ON p.module_id = m.id WHERE m.repo_id = ? ORDER BY m.slug`
+    ).all(repoId);
+    const head = rootPath === "" ? null : gitHead(rootPath);
+    const baseline = String(repo.git_baseline ?? "").trim();
+    // 每组验证基线只跑一次 diff：富化往往成批完成，同一基线的页占多数。
+    const diffCache = new Map();
+    const diffFor = (verified) => {
+      if (head === null) return null;
+      const key = String(verified ?? "").trim();
+      if (key === "") return null; // 没记过起点 → 判不了，别拿别的页的起点凑
+      if (diffCache.has(key)) return diffCache.get(key);
+      let value = null;
+      if (key === head) value = { ok: true, files: new Map(), deleted: [] };
+      else {
+        const diff = diffSince(rootPath, key, head);
+        value = diff.ok ? diff : { ok: false, reason: diff.reason };
+      }
+      diffCache.set(key, value);
+      return value;
+    };
+    const pages = pageRows.map((p) => {
+      let hasT1 = false;
+      try {
+        hasT1 = readFileSync(join(rootPath, p.rel_path), "utf8").includes(T1_SECTION_START);
+      } catch { hasT1 = false; }
+      const verifiedBaseline = String(p.verified_baseline ?? "").trim() || null;
+      const verifiedAt = p.verified_at ?? null;
+      // 老数据（本功能之前富化的页）只有全仓基线可依。退到它是**保守**方向：它早于
+      // 那页被富化的时刻，diff 会把「T1 之前就发生」的改动也算进来，只会多报不会漏报。
+      // 记 baselineApprox 是为了面板能说清「这是退而求其次的起点」，不是当真的验证点。
+      //
+      // 但「验证过、却没记下基线」不是老数据，是**验证没留下凭据**（T1 那次富化写了
+      // verified_at 却没写 verified_baseline，比如中途失败）。这种情况退到全仓基线
+      // 就会把「富化之后才发生」的改动当成「富化之前就有的」而放过——方向是漏报，
+      // 与上面那条恰好相反。所以判成 baselineUnknown：不知道起点，就不装作知道。
+      const verifyWithoutBaseline = verifiedBaseline === null && verifiedAt !== null;
+      const effective = verifyWithoutBaseline ? null : (verifiedBaseline ?? (baseline || null));
+      const computed = diffFor(effective);
+      return {
+        slug: p.slug,
+        title: p.title,
+        hasT1,
+        verifiedBaseline,
+        verifiedAt,
+        diffBaseline: effective,
+        baselineApprox: !verifyWithoutBaseline && verifiedBaseline === null && effective !== null,
+        baselineUnknown: effective === null,
+        anchorStale: computed !== null && computed.ok === false,
+      };
+    });
+    const claims = rows.map((r) => ({
+      id: r.id,
+      statement: r.statement,
+      kind: r.kind,
+      sourcePath: r.source_path,
+      startLine: r.start_line,
+      endLine: r.end_line,
+      pageSlug: r.page_slug,
+      pageTitle: r.page_title,
+    }));
+    const base = {
+      repo: { id: repo.id, name: repo.name, rootPath, gitBaseline: baseline || null },
+      head: head ?? null,
+      baseline: baseline || null,
+    };
+    if (head === null) {
+      return { ...base, clean: false, anchorStale: true, reason: "git-unreadable", ...summarizeClaims(claims, null, { pages }) };
+    }
+    // 仓库级 anchorStale 保留原来的语义：**骨架**（T0 页的文件清单、模块划分）记下的
+    // 那次基线还认不认得出。它和逐页 claims 的起点是两件事，面板上也是两句话——
+    // 「骨架要重建」不等于「结论都过时」。两条都算，谁也不掩盖谁。
+    let repoStale = false;
+    let repoStaleReason = null;
+    if (baseline !== "" && baseline !== head) {
+      const repoDiff = diffSince(rootPath, baseline, head);
+      if (!repoDiff.ok) { repoStale = true; repoStaleReason = repoDiff.reason; }
+    }
+    const diffByPage = (slug) => {
+      const page = pages.find((p) => p.slug === slug);
+      if (!page) return null;
+      const computed = diffFor(page.diffBaseline);
+      return computed !== null && computed.ok ? { files: computed.files, deleted: computed.deleted } : null;
+    };
+    const summary = summarizeClaims(claims, null, { pages, diffByPage });
+    // clean 的判据：每条结论都真判过、且一条都没被碰到。
+    // 「有结论但起点认不出 / 没记过」不算 clean——那是不知道，不是没事（#607 的病根）；
+    // 一条结论都没有时也没有「没事」可说（那是「还没富化」，不是「全部干净」）。
+    // 仓库基线 == HEAD → 整仓一条提交都没发生，任何 claims 都不可能被碰过。这一条既短路
+    // 「逐页基线没记」的老数据（缺列不是判不了），也覆盖「刚跑完 T0、还没有 conclusion」
+    // 的情形：没变就是没变，不必等富化完才敢说。
+    // 不是这个情形时才逐页看：有哪页判不了就不说 clean，一条结论都没有也不说 clean
+    // （那是「还没富化」，不是「全部干净」——面板上这两句不一样）。
+    const repoAtHead = baseline !== "" && baseline === head;
+    const undecidable = summary.totals.baselineUnknownPages + summary.totals.anchorStalePages > 0;
+    // inconsistentPages 不参与 repoAtHead 的短路：它说的不是「起点认不出」，而是
+    // **页面有语义正文、库里却一条 claims 都没有**（上次 T1 没写完的残局）。这种页的
+    // 证据根本无法核对，与仓库有没有新提交无关；只要还有这种页，就不能说「全部干净」，
+    // 否则面板会把一次没落库的富化说成没事。
+    const clean = summary.totals.atRiskClaims === 0
+      && summary.totals.inconsistentPages === 0
+      && (repoAtHead || (summary.totals.claims > 0 && !undecidable && !repoStale));
+    return {
+      ...base,
+      clean,
+      anchorStale: repoStale,
+      reason: repoStale ? repoStaleReason : null,
+      ...summary,
+    };
+  }
+
   // --- chorography 向量（收尾档 P37–P39）---------------------------------
   // 惰性物化（P37）：只在 host 侧检索路径调用（embedder 由 index.js 注入）；
   // CLI 环境没有 embedder → 向量永不物化，检索退关键词。staleness 两维：
@@ -468,7 +634,7 @@ export function createChoroQueries({ store }) {
 
   return {
     listRepos, listRepoFacts, repoFacts, repoFactsById, repoFromRow, listRepoRow, repoByRoot,
-    resolveRepo, moduleMap, readPage, search, repoByCwd, outline,
+    resolveRepo, moduleMap, readPage, search, repoByCwd, outline, claimDrift,
     embedPageVectors, searchSemantic, embedQueryText, semanticTopN,
   };
 }

package/lib/wiki/render.js

@@ -23,6 +23,80 @@ export const HUMAN_END = "<!-- CHORO:HUMAN:END -->";
 export const T1_SECTION_START = "<!-- CHORO:T1:START -->";
 export const T1_SECTION_END = "<!-- CHORO:T1:END -->";
 
+// 验证溯源的两个 frontmatter 键（issue #615 之后的 ①：语义段带上「对着哪次提交验证的」）。
+// 只有 T1 写它们，T0 渲染时一个字节都不产出——骨架页没有语义段，也就没有「哪次验证的」
+// 这回事；反过来说，T0 重建整页时这两个键随 T1 正文一起消失，与「T0 丢弃语义段」是
+// 同一件事，不新增语义。放在这里而不是 t1.js：frontmatter 的形状属于页面格式。
+export const FM_VERIFIED_BASELINE = "verifiedBaseline";
+export const FM_VERIFIED_AT = "verifiedAt";
+
+/** frontmatter 边界：首行 --- 与下一个 --- 的行号；不存在返回 null。 */
+function frontmatterBounds(lines) {
+  if (String(lines[0] ?? "").trim() !== "---") return null;
+  for (let i = 1; i < lines.length; i++) {
+    if (String(lines[i]).trim() === "---") return { open: 0, close: i };
+  }
+  return null;
+}
+
+/**
+ * 取 frontmatter 里某个顶层键的字符串值。
+ *
+ * 只认顶层键（`key: value`），缩进的列表项（`  - x`）不会误命中；值两侧的引号剥掉
+ * （yamlScalar 会给含特殊字符的值加引号，读回来要还原成原文）。
+ * 没有 frontmatter、键不存在、值为空 → 一律 null：调用方据此说「没记下」，
+ * 而不是把空串当成一个合法的提交号。
+ */
+export function readFrontmatterKey(pageText, key) {
+  const lines = String(pageText ?? "").split("\n");
+  const bounds = frontmatterBounds(lines);
+  if (!bounds) return null;
+  const re = new RegExp(`^${escapeRegExp(key)}\\s*:\\s*(.*)$`);
+  for (let i = bounds.open + 1; i < bounds.close; i++) {
+    const m = re.exec(lines[i]);
+    if (!m) continue;
+    let v = m[1].trim();
+    if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+      try { v = JSON.parse(v); } catch { v = v.slice(1, -1); }
+    }
+    return v === "" ? null : v;
+  }
+  return null;
+}
+
+/**
+ * 就地设置 frontmatter 顶层键：有则覆盖、无则追加在收尾 --- 之前（按传入顺序）。
+ *
+ * value 为 null / undefined / 空串 = **删掉**这个键，不留 `key:` 空行——「这一页是哪次
+ * 提交验证的，T1 没记下来」本身要能在文件里查得出来，而不是显示成一片空白。
+ * 没有 frontmatter 的正文原样返回：绝不给人写的坏文件凭空造一个块。
+ *
+ * @param {string} pageText
+ * @param {Array<[string, string|null]>} entries
+ */
+export function setFrontmatterKeys(pageText, entries) {
+  const lines = String(pageText ?? "").split("\n");
+  const bounds = frontmatterBounds(lines);
+  if (!bounds) return String(pageText ?? "");
+  const pending = new Map(entries.map(([k, v]) => [k, v === undefined || v === null || String(v).trim() === "" ? null : String(v)]));
+  const out = lines.slice(0, bounds.open + 1);
+  for (let i = bounds.open + 1; i < bounds.close; i++) {
+    const m = /^([A-Za-z_][\w-]*)\s*:/.exec(lines[i]);
+    if (m && pending.has(m[1])) {
+      const v = pending.get(m[1]);
+      pending.delete(m[1]);
+      if (v !== null) out.push(`${m[1]}: ${v}`);
+      continue;
+    }
+    out.push(lines[i]);
+  }
+  for (const [k, v] of pending) {
+    if (v !== null) out.push(`${k}: ${v}`);
+  }
+  out.push(...lines.slice(bounds.close));
+  return out.join("\n");
+}
+
 /** 抽出全部保留区。返回 { blocks: string[]（含标记本身，原样）, count }。 */
 export function extractHumanBlocks(pageText) {
   if (typeof pageText !== "string") return { blocks: [], count: 0 };

package/lib/wiki/t0.js

@@ -39,9 +39,10 @@ export class ChoroRefusal extends Error {
  * @param {string} opts.repoRoot 仓库路径（内部 realpath）
  * @param {object|null} opts.store createStore 产物（apply 时必传；dry-run 可为 null）
  * @param {boolean} [opts.apply=false] false = dry-run（零写入）
+ * @param {boolean} [opts.guardT1Loss=false] 会丢掉已有语义段时整轮拒绝（自动刷新用）
  * @param {() => string} [opts.now] ISO 时刻（测试注入假时钟）
  */
-export function runChoroT0({ repoRoot, store = null, apply = false, now = () => new Date().toISOString() }) {
+export function runChoroT0({ repoRoot, store = null, apply = false, guardT1Loss = false, now = () => new Date().toISOString() }) {
   let rootPath;
   try {
     rootPath = realpathSync(resolve(repoRoot));
@@ -177,6 +178,36 @@ export function runChoroT0({ repoRoot, store = null, apply = false, now = () =>
       + "要留住语义段就别在这里重跑 T0；需要时再用 --t1 重新富化。"
     );
   }
+  if (t1Loss.unreadable.length > 0) {
+    warnings.push(
+      `${t1Loss.unreadable.length} 页读不出来`
+      + `（${t1Loss.unreadable.slice(0, 3).map((u) => u.relPath).join("、")}${t1Loss.unreadable.length > 3 ? " 等" : ""}），`
+      + "无法确认其中是否有 T1 语义段；自动刷新会因此拒绝，手动重建会按骨架重写这些页。"
+    );
+  }
+  // guardT1Loss（自动刷新专用）：读路径上「顺手」重跑 T0 会把用户花模型调用换来的
+  // 语义段和 claims 一起清掉——那不是顺手，那是在用户只点开一页的时候替他做了一次
+  // 破坏性写盘。手动重建不受此限：用户点了按钮，回执里的 warnings 会如实列出丢了什么。
+  //
+  // 拒绝而不是「跳过有语义段的那几页」：T0 的整仓 replaceChoroGraph 是一次事务，
+  // 只保几页会留下「页面有 T1 正文、库里 claims 已被清空」的半截状态，比整体不写更糟。
+  //
+  // 读不出来的页同样要拒绝：清点靠读盘，读失败就先不知道它有没有语义段。放行等于
+  // 赌它没有，赌输就是把它那份语义段和 claims 一起抹掉；拒绝只是这次不刷新。
+  if (guardT1Loss && (t1Loss.pages.length > 0 || t1Loss.unreadable.length > 0)) {
+    const names = t1Loss.pages.slice(0, 3).join("、");
+    const blockedBy = t1Loss.unreadable.length > 0
+      ? `另有 ${t1Loss.unreadable.length} 页读不出来（${t1Loss.unreadable.slice(0, 3).map((u) => u.relPath).join("、")}`
+        + `${t1Loss.unreadable.length > 3 ? " 等" : ""}），无法确认它们有没有语义段。`
+      : "";
+    throw new ChoroRefusal(
+      "would-drop-t1",
+      `这个仓库有 ${t1Loss.pages.length} 页已经富化过（${names}${t1Loss.pages.length > 3 ? " 等" : ""}）。`
+      + blockedBy
+      + "自动刷新会退回骨架、清空 claims，所以这次没有动："
+      + "要保留语义段就先别刷新，确实要重建骨架请在面板里手动点「重建骨架」（回执会列出丢了哪几页）。"
+    );
+  }
 
   if (!apply) {
     return {
@@ -196,7 +227,7 @@ export function runChoroT0({ repoRoot, store = null, apply = false, now = () =>
       skippedFiles: graph.skipped,
       unresolvedCount: unresolvedTotal,
       humanBlocksSeen: countExistingHumanBlocks(rootPath, pageTargets),
-      t1Loss: { pages: t1Loss.pages, orphanEvidence: t1Loss.orphanEvidence },
+      t1Loss: { pages: t1Loss.pages, unreadable: t1Loss.unreadable, orphanEvidence: t1Loss.orphanEvidence },
       wouldWrite: [...pageTargets.map((p) => ({ path: p.relPath, bytes: Buffer.byteLength(p.content, "utf8") })),
         { path: indexRelPath, bytes: Buffer.byteLength(indexContent, "utf8") },
         { path: `${CHORO_DIR}/state.json`, bytes: 0 }],
@@ -282,7 +313,7 @@ export function runChoroT0({ repoRoot, store = null, apply = false, now = () =>
     unresolvedCount: unresolvedTotal,
     humanBlocksPreserved,
     bytes,
-    t1Loss: { pages: t1Loss.pages, orphanEvidence: t1Loss.orphanEvidence },
+    t1Loss: { pages: t1Loss.pages, unreadable: t1Loss.unreadable, orphanEvidence: t1Loss.orphanEvidence },
     warnings,
     moduleSummary: modules.map((m) => ({
       slug: m.slug, title: m.title, fileCount: m.fileCount,
@@ -421,13 +452,19 @@ function existingHumanBlockCount(absPath) {
 // 引用者。两者都是「会失去什么」的清点，不构成阻止：丢弃是设计意图，静默才是 bug。
 function collectT1Loss(rootPath, pageTargets) {
   const pages = [];
+  const unreadable = [];
   for (const target of pageTargets) {
     const abs = join(rootPath, target.relPath);
     if (!existsSync(abs)) continue;
     try {
       if (readFileSync(abs, "utf8").includes(T1_SECTION_START)) pages.push(target.relPath);
-    } catch {
-      /* 读不了就当没有：清点不该让 T0 失败 */
+    } catch (err) {
+      // **读不了不等于没有**：权限、占用、编码错误都会走到这里，而「有没有 T1 语义段」
+      // 恰恰要靠读那一眼才知道。吞成「没有」的直接后果是 guard 放行，然后一整仓
+      // replaceChoroGraph 把读不到的页连同它可能有的语义段一起退回骨架、清空 claims。
+      // 清点本身不该让 T0 失败（下面 warnings 只如实记一笔），但**守卫**必须把它当成
+      // 「有会丢的东西、但我数不清」而拒绝——见 guardT1Loss 分支。
+      unreadable.push({ relPath: target.relPath, reason: String(err?.code ?? err?.message ?? err) });
     }
   }
   let orphanEvidence = 0;
@@ -437,7 +474,7 @@ function collectT1Loss(rootPath, pageTargets) {
   } catch {
     orphanEvidence = 0;
   }
-  return { pages, orphanEvidence };
+  return { pages, unreadable, orphanEvidence };
 }
 
 function countExistingHumanBlocks(rootPath, pageTargets) {