opencode-wiki-historian 0.4.0 → 0.5.1

package/dist/surface.js

@@ -0,0 +1,391 @@
+/**
+ * src/surface.ts — human-interface & content-hygiene detectors (V6.1).
+ *
+ * maintain.ts owns per-page G5/G6 freshness; this module owns the WIKI-WIDE
+ * structural health of the human surface (HANDOFF issues #1-#6): navigation
+ * hygiene, map-vs-live coverage, redirect-stub reachability, broken / stacked /
+ * index-less links, orphans, twin divergence, zh-first language, unfinished
+ * skeletons and claim ledgers that beg re-verification.
+ *
+ * Pure functions over rows + live inventory + an injected readBody; the light
+ * tier costs nothing beyond the map baseline, the deep tier reads every body
+ * once (caller pools the reads).
+ */
+import { isInternalPath } from './tools/shared.js';
+import { lintBody } from './lint.js';
+import { classifyGenre } from './templates/genres.js';
+export const SURFACE_SCHEMA = 'historian.surface.v1';
+const MACHINE_SEG_RE = /^_/;
+// nav targets carry a leading slash and may pre-pend the locale segment
+// (/zh/_meta/x) — machine check runs on the first real path segment.
+const MACHINE_TARGET_RE = /^\/(?:(?:en|zh)\/)?_[^/]+/;
+const ROOT_EXEMPT = new Set(['home', 'wiki-index']);
+const visible = (r) => r.isPublished !== false && r.isPrivate !== true;
+const rowKey = (path, locale) => `${locale}\u0000${path}`;
+function isFrontPath(path) {
+    return !isInternalPath(path) && !path.startsWith('_sandbox/') && !path.startsWith('_data/');
+}
+// --- light tier ---------------------------------------------------------------
+function buildNav(rows, live, nav) {
+    const paths = new Set();
+    for (const r of rows)
+        paths.add(r.path);
+    for (const r of live ?? [])
+        paths.add(r.path);
+    const machinePaths = [...new Set([...paths].map((p) => p.split('/')[0]))]
+        .filter((s) => MACHINE_SEG_RE.test(s))
+        .sort();
+    const mode = nav?.mode ?? null;
+    const machineLinks = [];
+    for (const t of nav?.trees ?? []) {
+        for (const it of t.items) {
+            if (MACHINE_TARGET_RE.test(it.target)) {
+                machineLinks.push({ locale: t.locale, label: it.label, target: it.target });
+            }
+        }
+    }
+    const perDir = new Map();
+    for (const p of paths) {
+        const seg = p.split('/');
+        if (seg.length < 2 || MACHINE_SEG_RE.test(seg[0]))
+            continue;
+        perDir.set(seg[0], (perDir.get(seg[0]) ?? 0) + 1);
+    }
+    const sectionLandingMissing = [...perDir.entries()]
+        .filter(([dir, n]) => n >= 2 && !paths.has(dir))
+        .map(([dir, pagePaths]) => ({ dir, pagePaths }))
+        .sort((a, b) => b.pagePaths - a.pagePaths || a.dir.localeCompare(b.dir));
+    return {
+        available: nav != null,
+        mode,
+        filesystemExposed: mode === 'DYNAMIC' || mode === 'MIXED',
+        machineLinks,
+        machinePaths,
+        sectionLandingMissing,
+    };
+}
+function buildCoverage(rows, live) {
+    if (live === undefined)
+        return null;
+    const mapKeys = new Set(rows.map((r) => rowKey(r.path, r.locale)));
+    const liveVisible = live.filter(visible);
+    const liveKeys = new Set(liveVisible.map((r) => rowKey(r.path, r.locale)));
+    const missingFromMap = liveVisible
+        .filter((r) => !mapKeys.has(rowKey(r.path, r.locale)))
+        .map((r) => ({ path: r.path, locale: r.locale }))
+        .sort((a, b) => a.path.localeCompare(b.path) || a.locale.localeCompare(b.locale));
+    let removedFromLive = 0;
+    for (const k of mapKeys)
+        if (!liveKeys.has(k))
+            removedFromLive += 1;
+    return { liveRows: liveVisible.length, mapRows: rows.length, missingFromMap, removedFromLive };
+}
+const STACK_MD_RE = /\[([^\]]+)\]\((?:https?:\/\/[^\s)]+|\/[^\s)]*)\)/g;
+function anchorTexts(body) {
+    const out = [];
+    STACK_MD_RE.lastIndex = 0;
+    let m;
+    while ((m = STACK_MD_RE.exec(body)) !== null)
+        out.push({ raw: m[0], text: m[1].trim() });
+    return out;
+}
+function resolveTargetPath(baseUrl, rawHref) {
+    let t = rawHref.trim();
+    if (t === '' || t.startsWith('#') || /^(mailto:|javascript:)/i.test(t))
+        return null;
+    const host = baseUrl.replace(/\/+$/, '');
+    if (/^https?:\/\//i.test(t)) {
+        if (!t.toLowerCase().startsWith(host.toLowerCase()))
+            return null;
+        t = t.slice(host.length);
+    }
+    if (/\.(png|jpe?g|gif|svg|webp|pdf|zip|css|js)\b/i.test(t))
+        return null;
+    t = t.split('#')[0].split('?')[0];
+    t = t.replace(/^\/+/, '');
+    if (t === '')
+        return null;
+    if (t.startsWith('zh/'))
+        return { path: t.slice(3), locale: 'zh' };
+    if (t.startsWith('en/'))
+        return { path: t.slice(3), locale: 'en' };
+    return { path: t, locale: 'en' };
+}
+async function scanBodies(input) {
+    if (input.readBody === undefined)
+        return [];
+    const targets = input.rows.filter((r) => !isInternalPath(r.path));
+    const results = [];
+    const queue = [...targets];
+    const worker = async () => {
+        for (;;) {
+            const row = queue.shift();
+            if (row === undefined)
+                return;
+            const body = (await input.readBody?.(row.path, row.locale)) ?? '';
+            results.push({ row, lint: body === '' ? null : lintBody(body, { locale: row.locale, baseUrl: input.baseUrl, title: row.title }), body });
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(8, queue.length) }, () => worker()));
+    return results;
+}
+function buildDeep(input, scans) {
+    if (scans.length === 0)
+        return null;
+    const ok = scans.filter((s) => s.lint !== null);
+    const unfinished = ok
+        .filter((s) => !s.lint.isRedirectStub && isFrontPath(s.row.path))
+        .filter((s) => s.lint.todoMarkers > 0 || s.lint.emptySections.length > 0 || s.lint.introEmpty)
+        .map((s) => ({
+        path: s.row.path,
+        locale: s.row.locale,
+        title: s.row.title,
+        todo: s.lint.todoMarkers,
+        emptySections: s.lint.emptySections,
+        introEmpty: s.lint.introEmpty,
+        active: s.lint.state === 'active',
+        h1Mismatch: s.lint.h1 !== null && s.lint.h1.trim() !== s.row.title.trim(),
+    }))
+        .sort((a, b) => Number(b.active) - Number(a.active) || b.todo + b.emptySections.length - (a.todo + a.emptySections.length));
+    const pathSet = new Set();
+    for (const r of input.rows)
+        pathSet.add(r.path);
+    for (const r of input.liveInventory ?? [])
+        pathSet.add(r.path);
+    const stubPaths = new Map();
+    const stubs = [];
+    for (const s of ok.filter((x) => x.lint.isRedirectStub)) {
+        const target = s.lint.redirectTarget === null ? null : resolveTargetPath(input.baseUrl, s.lint.redirectTarget)?.path ?? null;
+        stubs.push({ path: s.row.path, locale: s.row.locale, target: s.lint.redirectTarget, clickable: s.lint.stubHasLink, targetLive: target !== null && pathSet.has(target) });
+        if (!stubPaths.has(s.row.path))
+            stubPaths.set(s.row.path, new Set());
+        stubPaths.get(s.row.path).add(s.row.locale);
+    }
+    stubs.sort((a, b) => Number(a.clickable) - Number(b.clickable) || a.path.localeCompare(b.path));
+    const broken = [];
+    const toStubs = [];
+    const inbound = new Map();
+    const indexTargets = new Set();
+    const sameTargetStacks = [];
+    for (const s of ok) {
+        const isIndex = s.row.path === 'wiki-index';
+        const byTarget = new Map();
+        for (const a of anchorTexts(s.body)) {
+            const t = resolveTargetPath(input.baseUrl, a.raw.slice(a.raw.indexOf('](') + 2, -1));
+            if (t === null)
+                continue;
+            if (!byTarget.has(t.path))
+                byTarget.set(t.path, new Set());
+            byTarget.get(t.path).add(a.text);
+        }
+        for (const link of s.lint.links) {
+            if (!isFrontPath(link.path) || ROOT_EXEMPT.has(link.path))
+                continue;
+            if (!link.path.startsWith('_sandbox/'))
+                inbound.set(link.path, (inbound.get(link.path) ?? 0) + 1);
+            if (isIndex)
+                indexTargets.add(link.path);
+            if (link.path === s.row.path)
+                continue;
+            if (!pathSet.has(link.path)) {
+                if (!broken.some((b) => b.from === s.row.path && b.locale === s.row.locale && b.target === link.path)) {
+                    broken.push({ from: s.row.path, locale: s.row.locale, target: link.path });
+                }
+            }
+            else if (stubPaths.has(link.path) && !broken.some((b) => b.target === link.path)) {
+                toStubs.push({ from: s.row.path, locale: s.row.locale, target: link.path });
+            }
+        }
+        for (const [target, texts] of byTarget) {
+            if (texts.size >= 3 && pathSet.has(target))
+                sameTargetStacks.push({ from: s.row.path, locale: s.row.locale, target, texts: texts.size });
+        }
+    }
+    const liveByPathLocale = new Map();
+    for (const s of ok)
+        liveByPathLocale.set(rowKey(s.row.path, s.row.locale), s);
+    const roleDivergence = [];
+    const twinParity = [];
+    const pathsAll = new Set();
+    for (const s of ok)
+        pathsAll.add(s.row.path);
+    for (const p of [...pathsAll].sort()) {
+        const en = liveByPathLocale.get(rowKey(p, 'en'));
+        const zh = liveByPathLocale.get(rowKey(p, 'zh'));
+        const enStub = stubPaths.get(p)?.has('en') ?? false;
+        const zhStub = stubPaths.get(p)?.has('zh') ?? false;
+        if (enStub !== zhStub && en !== undefined && zh !== undefined) {
+            roleDivergence.push({ path: p, stubIn: enStub ? 'en' : 'zh', liveIn: enStub ? 'zh' : 'en' });
+        }
+        if (en !== undefined && zh !== undefined && !enStub && !zhStub && isFrontPath(p)) {
+            const enLen = (en.body.match(/\S/g) ?? []).length;
+            const zhLen = (zh.body.match(/\S/g) ?? []).length;
+            if (enLen === 0 || zhLen === 0)
+                continue;
+            // Length must be script-weighted: a CJK glyph carries ~3x the information
+            // of a latin char, so raw lengths flagged faithful zh translations as
+            // "truncated" (0.47 ratio at 1.0 section parity in the live scan).
+            const eff = (n, cjkRatio) => n * (1 + 2 * cjkRatio);
+            // Structural, not literal: en/zh heading STRINGS are translations, so
+            // text-jaccard measured 0 on 85/98 live pairs (pure noise). What survives
+            // translation: level>=2 section count + Related Pages tail (SYN-9).
+            const h2 = (l) => (l?.headings ?? []).filter((h) => h.level >= 2).length;
+            const nEn = h2(en.lint);
+            const nZh = h2(zh.lint);
+            const sectionCountRatio = Math.max(nEn, nZh) === 0 ? 1 : Math.min(nEn, nZh) / Math.max(nEn, nZh);
+            const relatedMismatch = (en.lint?.hasRelatedPages ?? false) !== (zh.lint?.hasRelatedPages ?? false);
+            const lenRatio = Math.min(eff(enLen, en.lint?.cjkRatio ?? 0), eff(zhLen, zh.lint?.cjkRatio ?? 0))
+                / Math.max(eff(enLen, en.lint?.cjkRatio ?? 0), eff(zhLen, zh.lint?.cjkRatio ?? 0));
+            twinParity.push({
+                path: p,
+                lenRatio: Number(lenRatio.toFixed(2)),
+                sectionCountRatio: Number(sectionCountRatio.toFixed(2)),
+                relatedMismatch,
+                divergent: sectionCountRatio < 0.6 || lenRatio < 0.5 || relatedMismatch,
+            });
+        }
+    }
+    twinParity.sort((a, b) => Number(b.divergent) - Number(a.divergent) || a.lenRatio - b.lenRatio);
+    const zhEnglishDominant = ok
+        .filter((s) => s.row.locale === 'zh' && isFrontPath(s.row.path) && !s.lint.isRedirectStub)
+        .filter((s) => (s.body.match(/\S/g) ?? []).length > 400 && s.lint.cjkRatio < 0.06)
+        .map((s) => ({ path: s.row.path, cjkRatio: Number(s.lint.cjkRatio.toFixed(3)) }));
+    const ledgerClaims = [];
+    for (const s of ok) {
+        if (s.lint.isRedirectStub || !isFrontPath(s.row.path) || s.lint.hasStamp)
+            continue;
+        const genre = classifyGenre({ title: s.row.title, body: s.body }).genre;
+        if (!(genre === 'G4' || genre === 'G5' || genre === 'G6'))
+            continue;
+        if (s.lint.claimTotal < 3)
+            continue;
+        ledgerClaims.push({ path: s.row.path, locale: s.row.locale, genre, ports: s.lint.claims.ports, paths: s.lint.claims.paths, commands: s.lint.claims.commands });
+    }
+    ledgerClaims.sort((a, b) => b.ports + b.paths + b.commands - (a.ports + a.paths + a.commands));
+    const orphanPages = ok
+        .filter((s) => isFrontPath(s.row.path) && !s.lint.isRedirectStub && !ROOT_EXEMPT.has(s.row.path))
+        .map((s) => s.row.path)
+        .filter((p, i, arr) => arr.indexOf(p) === i && (inbound.get(p) ?? 0) === 0)
+        .sort();
+    const indexMissing = [...new Set(ok.filter((s) => isFrontPath(s.row.path)).map((s) => s.row.path))]
+        .filter((p) => !ROOT_EXEMPT.has(p) && !(stubPaths.get(p)?.has('en') ?? false) && !indexTargets.has(p))
+        .sort();
+    return {
+        unfinished,
+        stubs,
+        links: { broken, toStubs, sameTargetStacks, orphanPages, indexMissing },
+        roleDivergence,
+        twinParity,
+        zhEnglishDominant,
+        ledgerClaims,
+    };
+}
+// --- entry --------------------------------------------------------------------
+export async function buildSurfaceReport(input) {
+    const scans = input.deep === true ? await scanBodies(input) : [];
+    return {
+        schema: SURFACE_SCHEMA,
+        generatedAt: input.generatedAt,
+        deep: input.deep === true,
+        coverage: buildCoverage(input.rows, input.liveInventory),
+        nav: buildNav(input.rows, input.liveInventory, input.nav),
+        tagsEmpty: input.rows
+            .filter((r) => isFrontPath(r.path) && (r.tags?.length ?? 0) === 0)
+            .map((r) => ({ path: r.path, locale: r.locale }))
+            .sort((a, b) => a.path.localeCompare(b.path)),
+        deepReport: buildDeep(input, scans),
+    };
+}
+// --- render -------------------------------------------------------------------
+const cap = (arr, n) => arr.slice(0, n);
+export function renderSurfaceMarkdown(r) {
+    const L = [];
+    L.push(`# 界面健康 Surface Report (${r.deep ? 'deep' : 'light'})`, '');
+    L.push(`> ${r.generatedAt} · schema ${r.schema}`, '');
+    L.push('## 覆盖 Coverage（地图 vs 实时）', '');
+    if (r.coverage === null)
+        L.push('- （未提供 live inventory — 由 `maintain` 工具自动采集）');
+    else {
+        L.push(`- live ${r.coverage.liveRows} 行 / map ${r.coverage.mapRows} 行 · 地图外 missingFromMap ${r.coverage.missingFromMap.length} · 地图内已消失 removedFromLive ${r.coverage.removedFromLive}`);
+        for (const m of cap(r.coverage.missingFromMap, 40))
+            L.push(`  - \`${m.locale}/${m.path}\``);
+    }
+    L.push('', '## 导航 Nav（真相 = 实时导航树，非页面树推断）', '');
+    if (!r.nav.available) {
+        L.push('- ⚠ 导航树不可读（nav.available=false）— 机器段暴露无法核验，请检查 token 的导航读取权限');
+    }
+    else {
+        L.push(`- mode: \`${r.nav.mode}\` · 文件系统暴露 filesystemExposed: ${r.nav.filesystemExposed ? '⚠ 是 — DYNAMIC/MIXED 会把页面树镜像回侧栏（Issue #1 复发）' : '否'}`);
+        if (r.nav.machineLinks.length > 0) {
+            L.push(`- ⚠ 导航树内机器段链接 machineLinks (${r.nav.machineLinks.length}):`);
+            for (const m of cap(r.nav.machineLinks, 20))
+                L.push(`  - [${m.locale}] ${m.label} → \`${m.target}\``);
+        }
+        else {
+            L.push(`- 导航树内机器段链接: none ✓（页面树存档段 ${r.nav.machinePaths.map((s) => `\`${s}/\``).join(' ') || '—'} 属设计内，仅备查）`);
+        }
+    }
+    if (r.nav.sectionLandingMissing.length > 0) {
+        L.push(`- 落地页缺失 sectionLandingMissing（面包屑 404 / 空目录页）:`);
+        for (const s of r.nav.sectionLandingMissing)
+            L.push(`  - \`/${s.dir}\` — ${s.pagePaths} 页在此目录下`);
+    }
+    L.push('', `## 元数据卫生 Tags（前台空标签 ${r.tagsEmpty.length}）`, '');
+    if (r.tagsEmpty.length === 0)
+        L.push('- none');
+    else {
+        const byPath = new Map();
+        for (const t of r.tagsEmpty)
+            byPath.set(t.path, [...(byPath.get(t.path) ?? []), t.locale]);
+        for (const [p, ls] of cap([...byPath.entries()], 40))
+            L.push(`- \`${p}\` (${ls.join(',')})`);
+    }
+    if (r.deepReport === null) {
+        L.push('', '## Deep —（light 扫描未含正文级检测；用 deep:true）', '');
+        L.push('', '```json', JSON.stringify(r, null, 2), '```');
+        return L.join('\n');
+    }
+    const d = r.deepReport;
+    L.push('', `## 未完成正文 Unfinished skeletons (${d.unfinished.length})`, '');
+    L.push('| Path | 语言 | TODO | 空节 | 导言空 | Active谎报 | H1≠标题 |', '| --- | --- | --- | --- | --- | --- | --- |');
+    for (const u of cap(d.unfinished, 50)) {
+        L.push(`| \`${u.path}\` | ${u.locale} | ${u.todo} | ${u.emptySections.length} | ${u.introEmpty ? '✓' : ''} | ${u.active ? '**✓**' : ''} | ${u.h1Mismatch ? '✓' : ''} |`);
+    }
+    L.push('', `## 重定向存根 Redirect stubs (${d.stubs.length})`, '');
+    const dead = d.stubs.filter((s) => !s.clickable || !s.targetLive);
+    L.push(`- 无出口或死目标 dead/no-exit: ${dead.length}${dead.length > 0 ? '' : ' ✓'}`);
+    for (const s of cap(dead, 30))
+        L.push(`  - \`${s.locale}/${s.path}\` → ${s.target ?? '?'} ${s.clickable ? '' : '（正文无可点击链接）'}${s.targetLive ? '' : '（目标不存在）'}`);
+    L.push('', '## 链接 Links', '');
+    L.push(`- 断链 broken: ${d.links.broken.length}`);
+    for (const b of cap(d.links.broken, 30))
+        L.push(`  - \`${b.locale}/${b.from}\` → \`${b.target}\``);
+    L.push(`- 指向存根 toStubs: ${d.links.toStubs.length}`);
+    for (const b of cap(d.links.toStubs, 20))
+        L.push(`  - \`${b.locale}/${b.from}\` → 存根 \`${b.target}\``);
+    L.push(`- 同目标堆叠 sameTargetStacks（≥3 锚文本指同页）: ${d.links.sameTargetStacks.length}`);
+    for (const b of cap(d.links.sameTargetStacks, 20))
+        L.push(`  - \`${b.locale}/${b.from}\` × ${b.texts} → \`${b.target}\``);
+    L.push(`- 孤儿 orphanPages（全库无任何入链）: ${d.links.orphanPages.length}`);
+    for (const p of cap(d.links.orphanPages, 30))
+        L.push(`  - \`${p}\``);
+    L.push(`- 索引缺席 indexMissing（wiki-index 未收录）: ${d.links.indexMissing.length}`);
+    for (const p of cap(d.links.indexMissing, 40))
+        L.push(`  - \`${p}\``);
+    L.push('', `## 双语孪生 Twins`, '');
+    L.push(`- 角色分歧 roleDivergence（一侧存根一侧活页）: ${d.roleDivergence.length}`);
+    for (const t of d.roleDivergence)
+        L.push(`  - \`${t.path}\` — ${t.stubIn} 存根 / ${t.liveIn} 活页`);
+    const divergent = d.twinParity.filter((t) => t.divergent);
+    L.push(`- 内容分歧 divergent pairs: ${divergent.length} / ${d.twinParity.length}`);
+    for (const t of cap(divergent, 30))
+        L.push(`  - \`${t.path}\` 长度比 ${t.lenRatio} 小节比 ${t.sectionCountRatio}${t.relatedMismatch ? ' 相关页尾缺失' : ''}`);
+    L.push(`- zh 页英文主导 zhEnglishDominant（违背中文为主）: ${d.zhEnglishDominant.length}`);
+    for (const t of cap(d.zhEnglishDominant, 20))
+        L.push(`  - \`${t.path}\` cjk ${(t.cjkRatio * 100).toFixed(1)}%`);
+    L.push('', `## 台账风险 Ledger claims（G4/G5/G6 具体机器事实但无核实戳）: ${d.ledgerClaims.length}`, '');
+    for (const c of cap(d.ledgerClaims, 30))
+        L.push(`- \`${c.locale}/${c.path}\` (${c.genre}) ports:${c.ports} paths:${c.paths} cmds:${c.commands}`);
+    L.push('', '```json', JSON.stringify(r, null, 2), '```');
+    return L.join('\n');
+}

package/dist/templates/skeletons.d.ts

@@ -7,7 +7,7 @@
  *
  * Contract of every skeleton constant:
  *  - Rubric dimension C anatomy: H1 placeholder → status line
- *    `**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD`
+ *    `**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD`
  *    → one-line scope (`This page answers:` / `本页回答：`) → tail
  *    `Related Pages`/`相关页面` section with a real-link hint (SYN-9 fixed tail).
  *  - wiki.js 2.x expression pieces only: blockquote admonitions

package/dist/templates/skeletons.js

@@ -7,7 +7,7 @@
  *
  * Contract of every skeleton constant:
  *  - Rubric dimension C anatomy: H1 placeholder → status line
- *    `**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD`
+ *    `**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD`
  *    → one-line scope (`This page answers:` / `本页回答：`) → tail
  *    `Related Pages`/`相关页面` section with a real-link hint (SYN-9 fixed tail).
  *  - wiki.js 2.x expression pieces only: blockquote admonitions
@@ -26,7 +26,7 @@
 /** G1 — 事件/复盘页 (incident postmortem), zh. */
 export const G1_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 一句话范围句（占位：本页记录哪次故障/事件的起因、影响与处置）
 
@@ -117,7 +117,7 @@ export const G1_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G1 — incident postmortem, en (section-for-section twin of G1_ZH). */
 export const G1_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** one-line scope sentence (placeholder: which incident this page records, its impact and handling)
 
@@ -208,7 +208,7 @@ See footnote[^1].
 /** G2 — 对比/选型页 (comparison / selection), zh. */
 export const G2_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 一句话范围句（占位：本页在哪些对象之间、按什么维度对比，结论是什么）
 
@@ -258,7 +258,7 @@ export const G2_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G2 — comparison / selection, en (section-for-section twin of G2_ZH). */
 export const G2_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** one-line scope sentence (placeholder: what is compared, on which dimensions, and the pick)
 
@@ -308,7 +308,7 @@ export const G2_EN = `# Page Title (placeholder: replace with the real title, mu
 /** G3 — 清单/参考页 (inventory / reference), zh. */
 export const G3_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 一句话范围句（占位：本页收录哪类条目、覆盖到哪里、不覆盖什么）
 
@@ -343,7 +343,7 @@ export const G3_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G3 — inventory / reference, en (section-for-section twin of G3_ZH). */
 export const G3_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** one-line scope sentence (placeholder: which entries are covered, up to what boundary)
 
@@ -378,7 +378,7 @@ export const G3_EN = `# Page Title (placeholder: replace with the real title, mu
 /** G4 — 概念/原理解析页 (concept / explanation), zh. */
 export const G4_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 一句话范围句（占位：本页解释哪个概念，读者看完能理解什么）
 
@@ -416,7 +416,7 @@ export const G4_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G4 — concept / explanation, en (section-for-section twin of G4_ZH). */
 export const G4_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** one-line scope sentence (placeholder: which concept is explained and what the reader will understand)
 
@@ -457,7 +457,7 @@ export const G4_EN = `# Page Title (placeholder: replace with the real title, mu
  *  belongs to G1 event pages, linked from 变更记录. */
 export const G5_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 复核后改 Active / Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 当前部署状态（占位：写明范围）
 
@@ -508,7 +508,7 @@ export const G5_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G5 — current-state ledger, en (section-for-section twin of G5_ZH). */
 export const G5_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 复核后改 Active / Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** what is deployed and running right now (placeholder: name the system and scope)
 
@@ -562,7 +562,7 @@ export const G5_EN = `# Page Title (placeholder: replace with the real title, mu
  *  command lists in G3 pages, linked from 相关页面. */
 export const G6_ZH = `# 如何做某事（占位：目标句式标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 复核后改 Active / Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 如何完成某事（占位：写明具体目标）
 
@@ -611,7 +611,7 @@ export const G6_ZH = `# 如何做某事（占位：目标句式标题，须与
 /** G6 — how-to manual, en (section-for-section twin of G6_ZH). */
 export const G6_EN = `# How to Do X (placeholder: goal-titled heading, must match the page title)
 
-**状态/Status**: Active <!-- or Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 复核后改 Active / Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** how to finish one concrete task (placeholder: name the goal)
 

package/dist/tools/create.js

@@ -10,7 +10,7 @@ import { createPage } from '../wiki/pages.js';
 import { listPages, readPage } from '../wiki/pages.read.js';
 import { classifyGenre, genreSkeleton, GENRES } from '../templates/genres.js';
 import { evidenceSkeleton } from '../templates/evidence.js';
-import { checklistAdvisory, collisionAdvisory, enforceTierPath, errEnvelope, frontDumpAdvisory, MACHINE_TIER_NOTE, okJson, pageDeps, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, } from './shared.js';
+import { checklistAdvisory, collisionAdvisory, enforceTierPath, errEnvelope, frontDumpAdvisory, MACHINE_TIER_NOTE, okJson, pageDeps, publishGateRefusalJson, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, } from './shared.js';
 const s = tool.schema;
 const ARGS_SHAPE = {
     path: s.string().describe('Wiki path, e.g. docs/guides/foo (first segment must NOT look like a locale code)'),
@@ -109,6 +109,9 @@ export function makeCreateTool(deps) {
                 });
             }
             try {
+                const gate = publishGateRefusalJson(args.content, locale, args.path, deps.options.baseUrl);
+                if (gate !== null)
+                    return gate;
                 const collision = await collisionAdvice(deps, {
                     tier,
                     path: args.path,

package/dist/tools/local.js

@@ -9,8 +9,10 @@ import { TranslateError } from '../translate.js';
 import { buildChronology, filterRowsByPath } from '../chronology.js';
 import { getMap, refreshMapCache, CACHE_PATH } from '../map.js';
 import { buildMaintainReport, renderMaintainMarkdown } from '../maintain.js';
+import { buildSurfaceReport, renderSurfaceMarkdown } from '../surface.js';
 import { normalizeLocale, PathValidationError } from '../wiki/locale.js';
 import { listPages, readPage } from '../wiki/pages.read.js';
+import { readPrimaryNav } from '../wiki/nav.js';
 import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
 const s = tool.schema;
 const TRANSLATE_ARGS = {
@@ -59,7 +61,7 @@ const MAP_ARGS = {
     action: s.enum(['show', 'refresh', 'timeline', 'maintain']).default('show'),
     days: s.number().int().positive().optional().describe('timeline: keep only rows updated within the last N days'),
     path: s.string().optional().describe('timeline: section/path prefix filter (e.g. ops)'),
-    deep: s.boolean().optional().describe('maintain: additionally read every page body (freshness stamps + redirect stubs) — one bounded read per row'),
+    deep: s.boolean().optional().describe('maintain: additionally read every page body (freshness + stubs + broken/stacked links + twin parity + zh-first + unfinished skeletons + claim ledgers) — one bounded read per row, cached across both scans'),
 };
 const MapArgsSchema = s.object(MAP_ARGS);
 /** maintain: light tier is map rows + ONE read-only pages.list pass per locale
@@ -69,34 +71,57 @@ const MapArgsSchema = s.object(MAP_ARGS);
 async function runMaintain(deps, mapDeps, snapshot, deep) {
     const client = deps.getClient();
     const tagIndex = new Map();
+    const liveInventory = [];
     const locales = [...new Set(deps.options.locales.map(normalizeLocale))].sort();
     for (const locale of locales) {
         for (const item of await listPages(client, { locale })) {
             tagIndex.set(`${item.locale}\u0000${item.path}`, item.tags);
+            liveInventory.push({ path: item.path, locale: item.locale, isPublished: item.isPublished });
         }
     }
     const rows = snapshot.rows.map((r) => ({ ...r, tags: tagIndex.get(`${r.locale}\u0000${r.path}`) ?? [] }));
+    const bodyCache = new Map();
     const readBody = deep
-        ? async (path, locale) => {
-            try {
-                return (await readPage(client, path, locale))?.content ?? null;
-            }
-            catch (err) {
-                // Unreadable page (invalid path / transport) is a scan miss, not a report failure.
-                if (err instanceof PathValidationError)
-                    return null;
-                throw err;
-            }
+        ? (path, locale) => {
+            const key = `${locale}\u0000${path}`;
+            const hit = bodyCache.get(key);
+            if (hit !== undefined)
+                return hit;
+            const pending = (async () => {
+                try {
+                    return (await readPage(client, path, locale))?.content ?? null;
+                }
+                catch (err) {
+                    // Unreadable page (invalid path / transport) is a scan miss, not a report failure.
+                    if (err instanceof PathValidationError)
+                        return null;
+                    throw err;
+                }
+            })();
+            bodyCache.set(key, pending);
+            return pending;
         }
         : undefined;
     const report = await buildMaintainReport({ rows, mapGeneratedAt: snapshot.generatedAt, mapStaleSeconds: snapshot.staleSeconds }, { deep, readBody });
+    const nav = await readPrimaryNav(client);
+    const surface = await buildSurfaceReport({
+        rows,
+        generatedAt: report.generatedAt,
+        baseUrl: deps.options.baseUrl,
+        liveInventory,
+        nav,
+        deep,
+        readBody,
+    });
     return {
         action: 'maintain',
+        schema: 'historian.maintain.v3',
         deep: report.deep,
         generatedAt: report.generatedAt,
         rowCount: report.rowCount,
         report,
-        markdown: renderMaintainMarkdown(report),
+        surface,
+        markdown: `${renderMaintainMarkdown(report)}\n\n${renderSurfaceMarkdown(surface)}`,
         urls: reportUrls(deps.options.baseUrl, CACHE_PATH, 'en'),
     };
 }
@@ -109,8 +134,10 @@ export function makeMapTool(deps) {
             `show reads the local mirror (zero writes); refresh rebuilds from the wiki and writes the mirror + cache page ` +
             `(idempotent — the engine upserts via full RMW); timeline groups mirror rows by ISO week (newest first, ` +
             `optional days window + section/path prefix filter) into a human markdown table + machine-readable weeks JSON. ` +
-            `maintain runs the read-only curation sweep (twin gap, near-duplicate titles, staleness, diffusion/orphan ` +
-            `candidates, tag vocab, section distribution; deep:true adds per-body freshness stamps + redirect stubs) and ` +
+            `maintain runs the read-only curation sweep + surface report (twin gap, near-duplicate titles, staleness, ` +
+            `diffusion/orphan candidates, tag vocab, section distribution, map-vs-live coverage, nav hygiene; ` +
+            `deep:true adds per-body freshness, stub reachability, broken/stacked/index-less links, twin parity, ` +
+            `unfinished skeletons, claim ledgers) and ` +
             `answers a markdown report with a stable-key JSON tail. ${URL_MANDATE}.`,
         args: MAP_ARGS,
         execute: async (raw) => {

package/dist/tools/shared.d.ts

@@ -126,3 +126,12 @@ export declare class ConfigError extends Error {
 export declare function sectionGuard(path: string, allowedSections: readonly string[] | undefined): string | null;
 /** Guard + envelope in one step: null = proceed, ToolResult = refuse. */
 export declare function sectionRefusalJson(path: string, allowedSections: readonly string[] | undefined): ToolResult | null;
+export declare class PublishGateError extends Error {
+    constructor(message: string);
+}
+/** Hard gate on front-tier writes: refuses the two shapes that shipped real
+ *  incidents — a page claiming Active with TODO markers or empty skeleton
+ *  sections, and a redirect stub whose body carries no clickable exit.
+ *  `_sandbox/*` and internal namespaces are exempt; 状态:draft stays the
+ *  sanctioned work-in-progress escape hatch. Null = proceed. */
+export declare function publishGateRefusalJson(content: string, locale: Locale, path: string, baseUrl: string): ToolResult | null;