opencode-wiki-historian 0.4.0 → 0.5.0

package/dist/lint.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Body lint: one fence-aware pass over a page body producing the structural
+ * facts every hard gate and surface detector reuses (plan v0.5.0 #6).
+ * Pure functions, zero wiki I/O — the deep scanner injects bodies, the write
+ * tools lint drafts before they hit the API. This is the module the
+ * architecture-page audit (HANDOFF Issue #6) forced into existence: nothing
+ * here was optional before, which is exactly how a page with five empty
+ * sections shipped for three days claiming `状态: Active`.
+ */
+import type { Locale } from './wiki/pages.read.js';
+/** Machine rule keys; the human report renders zh labels from these. */
+export type GateViolation = 'redirect-stub-no-exit' | 'active-with-unfinished-skeleton';
+export interface LintFinding {
+    readonly key: 'todo-markers' | 'empty-sections' | 'intro-empty' | 'no-related-pages' | 'no-state-block' | 'h1-mismatch' | 'zh-english-dominant' | 'claims-without-stamp';
+    readonly detail: string;
+}
+export interface PageLink {
+    /** Normalized wiki path (locale prefix stripped, leading `/` removed, no anchor/query). */
+    readonly path: string;
+    readonly locale: Locale;
+    /** True when the raw target was a same-page anchor (`#…`) — never resolved. */
+    readonly anchor: boolean;
+}
+export interface ClaimCounts {
+    readonly ports: number;
+    readonly paths: number;
+    readonly commands: number;
+}
+export interface BodyLint {
+    readonly isRedirectStub: boolean;
+    readonly redirectTarget: string | null;
+    readonly stubHasLink: boolean;
+    readonly hasStateBlock: boolean;
+    readonly state: 'active' | 'draft' | 'superseded' | 'deprecated' | null;
+    readonly todoMarkers: number;
+    /** Heading text of sections whose body (before the next heading ≤ level) is empty. */
+    readonly emptySections: readonly string[];
+    readonly introEmpty: boolean;
+    readonly hasRelatedPages: boolean;
+    readonly h1: string | null;
+    /** All heading spans in document order (twin-parity + structure checks). */
+    readonly headings: readonly HeadingSpan[];
+    readonly links: readonly PageLink[];
+    readonly hasStamp: boolean;
+    readonly claims: ClaimCounts;
+    readonly claimTotal: number;
+    /** CJK chars / non-whitespace chars, zh body only meaningful; 0..1. */
+    readonly cjkRatio: number;
+}
+export interface HeadingSpan {
+    readonly level: number;
+    readonly heading: string;
+    /** Subtree body: weighted length until the next heading ≤ level, INCLUDING
+     *  descendant sections' content (masked+comment-free). */
+    readonly bodyChars: number;
+    /** Direct body only: weighted length until the next heading at ANY level.
+     *  Used for the intro ratio so an H1 span never swallows the whole page. */
+    readonly directChars: number;
+}
+/** Section headings (##+) whose SUBTREE holds no content. A parent that groups
+ *  non-empty subsections is an outline container, not an unfinished product;
+ *  only wholly-empty subtrees indicate an unfilled skeleton section. */
+export declare function emptySectionsOf(headings: readonly HeadingSpan[]): readonly string[];
+export interface LinkScanOpts {
+    readonly baseUrl: string;
+}
+/** Extract internal page links (relative wiki paths + same-host absolute URLs). */
+export declare function extractLinks(masked: string, opts: LinkScanOpts): readonly PageLink[];
+export interface LintOpts {
+    readonly locale: Locale;
+    readonly baseUrl: string;
+    /** Page title for the h1-mismatch check. */
+    readonly title?: string;
+}
+export declare function lintBody(body: string, opts: LintOpts): BodyLint;
+/** Structural h1≠title flag (kept out of BodyLint's hot fields on purpose). */
+export declare function h1TitleMismatch(lint: BodyLint, title: string | undefined): boolean;
+/** The two hard publish-gate rules (shared.ts refuses the write on a hit). */
+export declare function publishGateViolations(lint: BodyLint): readonly GateViolation[];

package/dist/lint.js

@@ -0,0 +1,254 @@
+/**
+ * Body lint: one fence-aware pass over a page body producing the structural
+ * facts every hard gate and surface detector reuses (plan v0.5.0 #6).
+ * Pure functions, zero wiki I/O — the deep scanner injects bodies, the write
+ * tools lint drafts before they hit the API. This is the module the
+ * architecture-page audit (HANDOFF Issue #6) forced into existence: nothing
+ * here was optional before, which is exactly how a page with five empty
+ * sections shipped for three days claiming `状态: Active`.
+ */
+// --- fence + comment masking ----------------------------------------------------
+/** Blank out fenced code-block interiors (keep line structure) so markers,
+ *  headings and links inside code fences never count (SYN fence rule). */
+function maskFences(body) {
+    const lines = body.split('\n');
+    let fence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = /^(`{3,}|~{3,})/.exec(line.trimStart());
+        if (fence === null && m !== null) {
+            fence = m[1][0];
+            continue;
+        }
+        if (fence !== null) {
+            if (line.trimStart().startsWith(fence.repeat(3))) {
+                fence = null;
+            }
+            else {
+                lines[i] = '';
+            }
+        }
+    }
+    return lines.join('\n');
+}
+const COMMENT_RE = /<!--[\s\S]*?-->/g;
+// --- redirect stub --------------------------------------------------------------
+const REDIRECT_LINE_RE = /^>\s*Redirect:\s*(\S.*?)\s*$/im;
+function redirectTarget(masked) {
+    const m = REDIRECT_LINE_RE.exec(masked);
+    return m !== null ? m[1] : null;
+}
+/** Clickable exit (Issue #5.1): a stub only lives if it carries at least one
+ *  real internal link — a bare `<code>` path or an in-page anchor is a dead
+ *  end for the reader who lands here. Wrong-target links belong to the
+ *  dead-link scanner, not this gate. */
+function hasClickableExit(visibleNoAnchors) {
+    return visibleNoAnchors > 0;
+}
+// --- status block -----------------------------------------------------------------
+const STATE_LINE_RE = /(?:^|\n)\s*\*{0,2}\s*(?:状态\s*\/\s*Status|状态|Status)\s*\*{0,2}\s*[:：]\s*([A-Za-z\u4e00-\u9fff][^\n·|<]*)/i;
+function parseState(maskedNoComments) {
+    const m = STATE_LINE_RE.exec(maskedNoComments);
+    if (m === null)
+        return { has: false, state: null };
+    const v = m[1].trim().toLowerCase();
+    if (v.startsWith('active'))
+        return { has: true, state: 'active' };
+    if (v.startsWith('draft'))
+        return { has: true, state: 'draft' };
+    if (v.startsWith('superseded'))
+        return { has: true, state: 'superseded' };
+    if (v.startsWith('deprecated'))
+        return { has: true, state: 'deprecated' };
+    return { has: true, state: null };
+}
+// --- markers, headings, intro -------------------------------------------------------
+const TODO_COMMENT_RE = /(TODO|TBD|PLACEHOLDER|占位)/i;
+const LITERAL_TODO_RE = /\bTODO:/g;
+function countTodoMarkers(masked) {
+    let n = 0;
+    for (const m of masked.matchAll(COMMENT_RE)) {
+        if (TODO_COMMENT_RE.test(m[0]))
+            n++;
+    }
+    // literal TODO: outside comments (comments already masked to '' for this pass)
+    const noComments = masked.replace(COMMENT_RE, '');
+    n += (noComments.match(LITERAL_TODO_RE) ?? []).length;
+    return n;
+}
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*$/;
+const STATUS_BOILERPLATE_RE = /状态\s*\/\s*Status|日期\s*\/\s*Date|本页回答|This page answers/i;
+/** Parse headings + emptiness over masked, comment-stripped text. Also returns
+ *  the intro span (before the first heading) for the 导言占比 detector. */
+function parseStructure(masked) {
+    const noComments = masked.replace(COMMENT_RE, '');
+    const lines = noComments.split('\n');
+    const headings = [];
+    let h1 = null;
+    let intro = 0;
+    const stack = [];
+    // CJK glyphs carry ~3x the visual weight of a latin char per cell — count
+    // weight, not raw chars, so a terse Chinese intro is not flagged empty.
+    const weight = (s) => {
+        const stripped = s.replace(/\s/g, '');
+        const cjk = (stripped.match(CJK_WEIGHT_RE) ?? []).length;
+        return cjk * 3 + (stripped.length - cjk);
+    };
+    const closeTo = (level) => {
+        const closing = [];
+        for (;;) {
+            const s = stack[stack.length - 1];
+            if (s === undefined || s.level < level)
+                break;
+            stack.pop();
+            closing.push({ level: s.level, heading: s.heading, bodyChars: s.subtree, directChars: s.direct });
+        }
+        // inner-first pop order must be flipped back to document order
+        headings.push(...closing.reverse());
+    };
+    for (const line of lines) {
+        const m = HEADING_RE.exec(line);
+        if (m !== null) {
+            const level = m[1].length;
+            closeTo(level);
+            if (level === 1 && h1 === null)
+                h1 = m[2].trim();
+            stack.push({ level, heading: m[2].trim(), direct: 0, subtree: 0 });
+            continue;
+        }
+        if (STATUS_BOILERPLATE_RE.test(line))
+            continue;
+        const w = weight(line);
+        if (stack.length === 0) {
+            intro += w;
+            continue;
+        }
+        for (const s of stack)
+            s.subtree += w;
+        stack[stack.length - 1].direct += w;
+    }
+    closeTo(1);
+    // The intro is the H1 section's DIRECT span (real pages all open with
+    // `# 标题`); the pre-heading accumulator only carries weight on heading-less bodies.
+    const firstH1 = headings.find((h) => h.level === 1);
+    const introWeight = firstH1 !== undefined ? firstH1.directChars : intro;
+    return { headings, introEmpty: introWeight < 40, h1 };
+}
+/** Section headings (##+) whose SUBTREE holds no content. A parent that groups
+ *  non-empty subsections is an outline container, not an unfinished product;
+ *  only wholly-empty subtrees indicate an unfilled skeleton section. */
+export function emptySectionsOf(headings) {
+    return headings.filter((h) => h.level >= 2 && h.bodyChars === 0).map((h) => h.heading);
+}
+// --- links -----------------------------------------------------------------------
+const LINK_MD_RE = /\]\(([^)\s]+)[^)]*\)/g;
+const LINK_HREF_RE = /href="([^"]+)"/gi;
+/** Extract internal page links (relative wiki paths + same-host absolute URLs). */
+export function extractLinks(masked, opts) {
+    const out = [];
+    const host = opts.baseUrl.replace(/\/+$/, '');
+    const seen = new Set();
+    const push = (raw) => {
+        let target = raw.trim();
+        if (target === '' || target.startsWith('#')) {
+            if (target.startsWith('#'))
+                out.push({ path: target.slice(1), locale: 'en', anchor: true });
+            return;
+        }
+        if (/^(mailto:|javascript:)/i.test(target))
+            return;
+        let locale = 'en';
+        if (/^https?:\/\//i.test(target)) {
+            if (!target.toLowerCase().startsWith(host.toLowerCase()))
+                return; // external
+            target = target.slice(host.length);
+        }
+        if (/\.(png|jpe?g|gif|svg|webp|pdf|zip|css|js)\b/i.test(target))
+            return;
+        target = target.split('#')[0];
+        target = target.split('?')[0];
+        target = target.replace(/^\/+/, '');
+        if (target === '')
+            return;
+        if (target.startsWith('zh/')) {
+            locale = 'zh';
+            target = target.slice(3);
+        }
+        else if (target.startsWith('en/')) {
+            target = target.slice(3);
+        }
+        const key = `${locale}\u0000${target}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ path: target, locale, anchor: false });
+    };
+    for (const re of [LINK_MD_RE, LINK_HREF_RE]) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(masked)) !== null)
+            push(m[1] ?? '');
+    }
+    return out;
+}
+// --- claims + stamps + language -----------------------------------------------------
+const STAMP_RE = /上次核实|上次验证|last verified/i;
+const PORT_RE = /:\d{4,5}\b/g;
+const FS_PATH_RE = /\/(?:opt|var|etc|usr|srv)\/[\w./-]+/g;
+const CMD_RE = /\b(?:systemctl|journalctl|docker|curl|nc|wget|iptables|nginx|caddy)\b/gi;
+const CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff\u3040-\u30ff]/g;
+const CJK_WEIGHT_RE = /[\u3400-\u4dbf\u4e00-\u9fff\u3040-\u30ff]/g;
+function distinct(text, re) {
+    return new Set(text.match(re) ?? []).size;
+}
+// --- main entry ---------------------------------------------------------------------
+export function lintBody(body, opts) {
+    const masked = maskFences(body);
+    const visible = masked.replace(COMMENT_RE, '');
+    const target = redirectTarget(masked);
+    const isRedirectStub = /^\s*>\s*Redirect:/im.test(masked);
+    const { headings, introEmpty, h1 } = parseStructure(masked);
+    const links = extractLinks(visible, { baseUrl: opts.baseUrl }).filter((l) => !l.anchor);
+    const nonSpace = (visible.match(/\S/g) ?? []).length;
+    const cjk = (visible.match(CJK_RE) ?? []).length;
+    const claims = {
+        ports: distinct(visible, PORT_RE),
+        paths: distinct(visible, FS_PATH_RE),
+        commands: distinct(visible, CMD_RE),
+    };
+    const stateInfo = parseState(visible);
+    return {
+        isRedirectStub,
+        redirectTarget: target,
+        stubHasLink: !isRedirectStub || hasClickableExit(links.length),
+        hasStateBlock: stateInfo.has,
+        state: stateInfo.state,
+        todoMarkers: countTodoMarkers(masked),
+        emptySections: emptySectionsOf(headings),
+        introEmpty,
+        hasRelatedPages: /^#{1,6}\s+.*(相关页面|Related Pages)/im.test(masked),
+        h1,
+        headings,
+        links,
+        hasStamp: STAMP_RE.test(visible),
+        claims,
+        claimTotal: claims.ports + claims.paths + claims.commands,
+        cjkRatio: nonSpace === 0 ? 0 : cjk / nonSpace,
+    };
+}
+/** Structural h1≠title flag (kept out of BodyLint's hot fields on purpose). */
+export function h1TitleMismatch(lint, title) {
+    if (title === undefined || lint.h1 === null)
+        return false;
+    return lint.h1.trim().toLowerCase() !== title.trim().toLowerCase();
+}
+/** The two hard publish-gate rules (shared.ts refuses the write on a hit). */
+export function publishGateViolations(lint) {
+    const out = [];
+    if (lint.isRedirectStub && !lint.stubHasLink)
+        out.push('redirect-stub-no-exit');
+    if (lint.state === 'active' && (lint.todoMarkers > 0 || lint.emptySections.length > 0)) {
+        out.push('active-with-unfinished-skeleton');
+    }
+    return out;
+}

package/dist/surface.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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 type { MaintainRow } from './maintain.js';
+import type { Locale } from './wiki/pages.read.js';
+export declare const SURFACE_SCHEMA: "historian.surface.v1";
+/** Minimal shape of a live `pages.list` row the surface diff needs. */
+export interface LiveRow {
+    readonly path: string;
+    readonly locale: Locale;
+    readonly isPublished?: boolean;
+    readonly isPrivate?: boolean;
+}
+export interface SurfaceInput {
+    readonly rows: readonly MaintainRow[];
+    readonly generatedAt: string;
+    readonly baseUrl: string;
+    readonly liveInventory?: readonly LiveRow[];
+    readonly deep?: boolean;
+    readonly readBody?: (path: string, locale: Locale) => Promise<string | null>;
+}
+export interface SurfaceCoverage {
+    readonly liveRows: number;
+    readonly mapRows: number;
+    readonly missingFromMap: {
+        readonly path: string;
+        readonly locale: Locale;
+    }[];
+    readonly removedFromLive: number;
+}
+export interface SurfaceNav {
+    readonly machineSections: readonly string[];
+    readonly sectionLandingMissing: {
+        readonly dir: string;
+        readonly pagePaths: number;
+    }[];
+}
+export interface SurfaceUnfinished {
+    readonly path: string;
+    readonly locale: Locale;
+    readonly title: string;
+    readonly todo: number;
+    readonly emptySections: readonly string[];
+    readonly introEmpty: boolean;
+    readonly active: boolean;
+    readonly h1Mismatch: boolean;
+}
+export interface SurfaceStub {
+    readonly path: string;
+    readonly locale: Locale;
+    readonly target: string | null;
+    readonly clickable: boolean;
+    readonly targetLive: boolean;
+}
+export interface SurfaceLinks {
+    readonly broken: {
+        readonly from: string;
+        readonly locale: Locale;
+        readonly target: string;
+    }[];
+    readonly toStubs: {
+        readonly from: string;
+        readonly locale: Locale;
+        readonly target: string;
+    }[];
+    readonly sameTargetStacks: {
+        readonly from: string;
+        readonly locale: Locale;
+        readonly target: string;
+        readonly texts: number;
+    }[];
+    readonly orphanPages: readonly string[];
+    readonly indexMissing: readonly string[];
+}
+export interface SurfaceTwin {
+    readonly path: string;
+    readonly lenRatio: number;
+    readonly sectionCountRatio: number;
+    readonly relatedMismatch: boolean;
+    readonly divergent: boolean;
+}
+export interface SurfaceDeep {
+    readonly unfinished: SurfaceUnfinished[];
+    readonly stubs: SurfaceStub[];
+    readonly links: SurfaceLinks;
+    readonly roleDivergence: {
+        readonly path: string;
+        readonly stubIn: Locale;
+        readonly liveIn: Locale;
+    }[];
+    readonly twinParity: SurfaceTwin[];
+    readonly zhEnglishDominant: {
+        readonly path: string;
+        readonly cjkRatio: number;
+    }[];
+    readonly ledgerClaims: {
+        readonly path: string;
+        readonly locale: Locale;
+        readonly genre: string;
+        readonly ports: number;
+        readonly paths: number;
+        readonly commands: number;
+    }[];
+}
+export interface SurfaceReport {
+    readonly schema: typeof SURFACE_SCHEMA;
+    readonly generatedAt: string;
+    readonly deep: boolean;
+    readonly coverage: SurfaceCoverage | null;
+    readonly nav: SurfaceNav;
+    readonly tagsEmpty: {
+        readonly path: string;
+        readonly locale: Locale;
+    }[];
+    readonly deepReport: SurfaceDeep | null;
+}
+export declare function buildSurfaceReport(input: SurfaceInput): Promise<SurfaceReport>;
+export declare function renderSurfaceMarkdown(r: SurfaceReport): string;

package/dist/surface.js

@@ -0,0 +1,359 @@
+/**
+ * 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 = /^_/;
+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) {
+    const paths = new Set();
+    for (const r of rows)
+        paths.add(r.path);
+    for (const r of live ?? [])
+        paths.add(r.path);
+    const machineSections = [...new Set([...paths].map((p) => p.split('/')[0]))]
+        .filter((s) => MACHINE_SEG_RE.test(s))
+        .sort();
+    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 { machineSections, 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),
+        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（动态侧栏镜像）', '');
+    L.push(`- 机器命名空间暴露 machineSections: ${r.nav.machineSections.map((s) => `\`${s}/\``).join(' ') || 'none'}`);
+    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,6 +9,7 @@ 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 { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
@@ -59,7 +60,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 +70,55 @@ 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 surface = await buildSurfaceReport({
+        rows,
+        generatedAt: report.generatedAt,
+        baseUrl: deps.options.baseUrl,
+        liveInventory,
+        deep,
+        readBody,
+    });
     return {
         action: 'maintain',
+        schema: 'historian.maintain.v2',
         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 +131,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;

package/dist/tools/shared.js

@@ -11,6 +11,7 @@
 import { assertLocalePair, PathValidationError } from '../wiki/locale.js';
 import { scoreChecklist } from '../migrate-score.js';
 import { selfReviewChecklist } from '../templates/genres.js';
+import { lintBody, publishGateViolations } from '../lint.js';
 /** Engine deps for one operation; client resolved lazily at use time. */
 export function pageDeps(deps) {
     return { client: deps.getClient(), options: deps.options, translate: deps.translate };
@@ -83,6 +84,8 @@ function hintFor(errorKind) {
             return 'The wiki endpoint is unreachable or misconfigured — check baseUrl and network.';
         case 'GraphQLError':
             return 'The wiki answered a GraphQL error — check the path/locale arguments.';
+        case 'PublishGateError':
+            return '消除 TODO/空节并把状态置 Active，或保留 状态:draft 待自检通过后发布；重定向存根正文必须带可点击的 [链接](目标URL)。';
         default:
             return 'Inspect the message and retry.';
     }
@@ -304,3 +307,23 @@ export function sectionRefusalJson(path, allowedSections) {
     const violation = sectionGuard(path, allowedSections);
     return violation === null ? null : errEnvelope(new ConfigError(violation));
 }
+// --- publish gate (V6.1, HANDOFF #5.1 / #6.1) --------------------------------
+export class PublishGateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PublishGateError';
+    }
+}
+/** 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 function publishGateRefusalJson(content, locale, path, baseUrl) {
+    if (path.startsWith('_sandbox/') || isInternalPath(path))
+        return null;
+    const violations = publishGateViolations(lintBody(content, { locale, baseUrl }));
+    if (violations.length === 0)
+        return null;
+    return errEnvelope(new PublishGateError(`publish-gate: ${violations.join('; ')} on '${path}' (${locale})`));
+}

package/dist/tools/write.js

@@ -7,7 +7,7 @@
 import { tool } from '@opencode-ai/plugin';
 import { appendSection, createPage, updatePage, PageNotFoundError } from '../wiki/pages.js';
 import { readPage } from '../wiki/pages.read.js';
-import { enforceTierPath, errEnvelope, frontDumpAdvisory, isInternalPath, MACHINE_TIER_NOTE, monolingualRefusalJson, okJson, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
+import { enforceTierPath, errEnvelope, frontDumpAdvisory, isInternalPath, MACHINE_TIER_NOTE, monolingualRefusalJson, okJson, publishGateRefusalJson, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
 const s = tool.schema;
 const UPDATE_ARGS = {
     path: s.string(),
@@ -33,6 +33,11 @@ export function makeUpdateTool(deps) {
                 if (page === null) {
                     return errEnvelope(new PageNotFoundError(`page '${args.path}' (${args.locale}) does not exist`));
                 }
+                if (args.content !== undefined) {
+                    const gate = publishGateRefusalJson(args.content, args.locale, page.path, deps.options.baseUrl);
+                    if (gate !== null)
+                        return gate;
+                }
                 const result = await updatePage(pageDeps(deps), page.id, {
                     title: args.title,
                     content: args.content,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-wiki-historian",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "opencode plugin that manages a wiki.js knowledge base with bilingual pages, genre templates, and migration tooling.",
   "type": "module",
   "license": "MIT",

package/skills/historian/SKILL.md

@@ -200,7 +200,7 @@ G5 现状卡的硬约束：状态块是机读单行（`Active` / `Superseded-by:
 | `historian_translate_snippet` | 翻译片段 | `text`, `from`(en/zh), `to`(en/zh) |
 | `historian_search` | 搜索页面 | `query`, `kind`(title/content), `tags?`(1-5 个), `tagsMode?`(all 缺省/any) |
 | `historian_read` | 读取页面 | `path`, `locale` |
-| `historian_map` | 页面地图/时间线/维护扫描 | `action`(show/refresh/timeline/maintain)；maintain 可选 `deep`（缺省 false=light 扫）；timeline 可选 `days`（近 N 天）与 `path`（前缀过滤）；输出人读 markdown + 机读 JSON，zh/en 行独立 |
+| `historian_map` | 页面地图/时间线/维护扫描 | `action`(show/refresh/timeline/maintain)；maintain 可选 `deep`（缺省 false=light 扫）；timeline 可选 `days`（近 N 天）与 `path`（前缀过滤）；输出人读 markdown + 机读 JSON，zh/en 行独立；maintain 同时返回 surface 接口面体检（信封 `historian.maintain.v2`） |
 | `historian_migrate` | 迁移页面到规范 | `path`, `genre?`, `apply`(false/true) |
 | `historian_delete` | 删除页面 | `path`, `locale`, `confirm`(必须 "yes") |
 | `historian_move` | 移动页面 | `path`, `locale`, `newPath`, `newLocale?`, `confirm`(必须 "yes") |
@@ -327,6 +327,8 @@ historian_map action:'refresh'
 - **light 扫：每次批量写后必跑**——只基于地图行 + 每 locale 一次只读 `pages.list`（便宜，随批走）
 - **deep 扫：每周至多一次**——逐页读正文，跑新鲜度（缺「上次核实于」/ 复核过期）与 `> Redirect:` 存根计数（贵，克制用）
 
+light 扫在 maintain 行之外附带 **surface-light**：`coverage`（live 页面与地图不一致）、`nav`（`_*` 机器命名空间暴露于侧栏 / 章节缺落地页→面包屑 404）、`tagsEmpty`；deep 扫附带 **surface-deep**：正文级检测，逐页一次读取、双消费者共享缓存。
+
 报告行 → 处置映射表：
 
 | 报告行 | 含义 | 处置 |
@@ -338,6 +340,16 @@ historian_map action:'refresh'
 | `tags.vocabulary` | 标签漂移 | 词表映射：近义标签收敛到主词，`historian_page_update` 批量改 |
 | `redirects.stubs`（deep） | 重定向存根清单 | 核对目标存在、入链已改写；死链存根即修 |
 | `freshness`（deep） | 缺核实戳 / reviewBy 过期 | 回 G5 卡补核；到期页列入下周复核 |
+| `coverage.missingFromMap`（surface） | 新页/迁移未进地图 | `action:'refresh'` 后重扫 |
+| `nav.machineSections`（surface） | `_*` 机器命名空间进侧栏 | 导航树手工策划，只挂主题章节 |
+| `nav.sectionLandingMissing`（surface） | 章节缺落地页（面包屑 404） | 建章节总览页并链入 wiki-index |
+| `unfinished`（surface deep） | Active 页含 TODO/空节/导言空 | 补全或降回 draft |
+| `stubs` / `links.broken` / `toStubs` / `sameTargetStacks`（deep） | 存根无可点出口 / 死链 / 指存根 / 同页多锚点 | 修出口与目标；锚点收敛到规范页 |
+| `orphanPages` / `indexMissing`（deep） | 无入链 / 未入索引 | 归架：从相关页与 wiki-index 补链 |
+| `roleDivergence`（deep） | 同题页 en/zh 一存根一活页 | 双侧收敛到同一权威页 |
+| `twinParity`（deep） | 孪生正文分叉（长度/节结构） | 重译或重排落后的孪生腿 |
+| `zhEnglishDominant`（deep） | zh 页英文为主（违反中文为主） | 按 zh-first 政策重写 |
+| `ledgerClaims`（deep） | 事实密集页缺「上次核实于」戳 | 逐条对机器核实后补戳，或标 stale |
 
 ### 闸门回路 (gate)：reading loop + sections guard
 
@@ -350,6 +362,14 @@ historian_map action:'refresh'
 - 注入语义为**单块追加**：advisory 拼接到 system 提示的最后一个块（`\n\n` 分隔），system 为空数组时才新建块——绝不产生第二条 system 消息。严格 OpenAI 兼容后端（如 vLLM）会以 `System message must be at the beginning.` 拒绝多 system 请求，单块追加从根上规避此坑。
 - 幂等去重：同一请求的任一 system 块已含 `historian_search` 字样则跳过注入。
 
+#### 发布闸门 publish gate（写入硬拒，v0.5.0）
+
+`historian_page_create` 与带 `content` 的 `historian_page_update` 在**任何写入前**硬检正文，违例即零写入拒绝（`errorKind: PublishGateError`）：
+
+- **R1 存根须有出口**：`> Redirect:` 开头的正文必须含 ≥1 条可点击链接；纯行内代码路径不算出口
+- **R2 Active 不许半成品**：状态行为 `Active` 且正文含 TODO/TBD/占位注释或空节 → 拒绝；未完稿保持 `draft`——G1-G6 骨架状态行缺省即 `draft`，翻 Active 就是过闸动作
+- 豁免：`_sandbox/**` 与内部层（`_meta/`、`_evidence/`）；`append` 不过闸（增量语义），由 deep 扫描兜底
+
 #### sections guard（路径闸门）
 
 写入路径首段受插件选项 `sections` 白名单强制（配置后不在白名单的前缀被拒）。豁免段恒可写：`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence`——机构记忆不能反锁落地的着陆页与机器命名空间。`tier:"evidence"` 的页面不校验（证据层是原材料归宿）。白名单为空的部署不做前缀限制，实际权限由 wiki.js token 的 page rules 决定。