opencode-wiki-historian 0.3.0 → 0.5.0

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/genres.d.ts

@@ -24,11 +24,11 @@
  * see skeletons.ts for the raw strings. Consumers (tools.ts, todo 14/15 pilot)
  * import everything from this barrel.
  */
-export { G1_EN, G1_ZH, G2_EN, G2_ZH, G3_EN, G3_ZH, G4_EN, G4_ZH, G5_EN, G5_ZH, } from './skeletons.js';
-export type Genre = 'G1' | 'G2' | 'G3' | 'G4' | 'G5';
+export { G1_EN, G1_ZH, G2_EN, G2_ZH, G3_EN, G3_ZH, G4_EN, G4_ZH, G5_EN, G5_ZH, G6_EN, G6_ZH, } from './skeletons.js';
+export type Genre = 'G1' | 'G2' | 'G3' | 'G4' | 'G5' | 'G6';
 export type GenreLang = 'en' | 'zh';
 export type Confidence = 'high' | 'medium' | 'low';
-export declare const GENRES: readonly Genre[];
+export declare const GENRES: readonly ["G1", "G2", "G3", "G4", "G5", "G6"];
 export interface ClassifyInput {
     readonly title: string;
     readonly body: string;

package/dist/templates/genres.js

@@ -24,11 +24,11 @@
  * see skeletons.ts for the raw strings. Consumers (tools.ts, todo 14/15 pilot)
  * import everything from this barrel.
  */
-import { G1_EN, G1_ZH, G2_EN, G2_ZH, G3_EN, G3_ZH, G4_EN, G4_ZH, G5_EN, G5_ZH, } from './skeletons.js';
+import { G1_EN, G1_ZH, G2_EN, G2_ZH, G3_EN, G3_ZH, G4_EN, G4_ZH, G5_EN, G5_ZH, G6_EN, G6_ZH, } from './skeletons.js';
 // Contract re-exports: raw skeleton data stays reachable through the barrel
 // (todo 13 renders these double-checked strings into skill references).
-export { G1_EN, G1_ZH, G2_EN, G2_ZH, G3_EN, G3_ZH, G4_EN, G4_ZH, G5_EN, G5_ZH, } from './skeletons.js';
-export const GENRES = ['G1', 'G2', 'G3', 'G4', 'G5'];
+export { G1_EN, G1_ZH, G2_EN, G2_ZH, G3_EN, G3_ZH, G4_EN, G4_ZH, G5_EN, G5_ZH, G6_EN, G6_ZH, } from './skeletons.js';
+export const GENRES = ['G1', 'G2', 'G3', 'G4', 'G5', 'G6'];
 // --- genreSkeleton ----------------------------------------------------------
 const SKELETONS = {
     G1: { en: G1_EN, zh: G1_ZH },
@@ -36,6 +36,7 @@ const SKELETONS = {
     G3: { en: G3_EN, zh: G3_ZH },
     G4: { en: G4_EN, zh: G4_ZH },
     G5: { en: G5_EN, zh: G5_ZH },
+    G6: { en: G6_EN, zh: G6_ZH },
 };
 /** Full markdown skeleton for a genre × language pair. Pure string data —
  *  the author copies it, replaces placeholders, and fills the commented slots. */
@@ -60,6 +61,9 @@ const GENRE_KEYWORDS = {
     // Deployed-state cues only — bare 部署/版本 would collide with G3 "部署清单"
     // and general changelog talk, regressing existing corpus classifications.
     G5: ['现状卡', '当前状态', '已部署', '部署物', '现役', '上线', '端口', '上次核实', '失效策略', '验证命令', 'current state', 'deployed', 'last verified', 'running now'],
+    // Goal-titled how-to cues only — bare 步骤/操作 would steal G3 清单 pages
+    // that merely mention 验证步骤 and scratch notes titled 今日操作记录.
+    G6: ['如何', '怎么', '上手', '指南', '操作手册', '操作步骤', 'how to', 'steps to', 'runbook'],
 };
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -155,6 +159,28 @@ const G5_CHECKLIST_VARIANTS = {
         appliesTo: ['G5'],
     },
 };
+/** G6 swaps the genre-specific items 4–6 for how-to gates (goal-titled H1,
+ *  step triples, D4 freshness metadata); everything else is shared. */
+const G6_CHECKLIST_VARIANTS = {
+    4: {
+        id: 4,
+        label: '标题是目标句式 "How to X" / "如何/怎么做X"（goal-titled H1: the page name IS the reader\'s goal）',
+        kind: 'genre-specific',
+        appliesTo: ['G6'],
+    },
+    5: {
+        id: 5,
+        label: '操作步骤每条三段：动作 + 预期结果 + 失败处置（every numbered step carries action + expected result + on-failure handling）',
+        kind: 'genre-specific',
+        appliesTo: ['G6'],
+    },
+    6: {
+        id: 6,
+        label: '元数据表含「上次核实」与「复核周期」行（metadata table carries last-verified + review-by rows; 被取代于 once retired）',
+        kind: 'genre-specific',
+        appliesTo: ['G6'],
+    },
+};
 export function selfReviewChecklist(genre) {
     if (!GENRES.includes(genre)) {
         throw new Error(`unknown genre: ${genre}`);
@@ -221,8 +247,9 @@ export function selfReviewChecklist(genre) {
             appliesTo: 'all',
         },
     ];
-    if (genre === 'G5') {
-        return items.map((item) => G5_CHECKLIST_VARIANTS[item.id] ?? item);
+    const variants = genre === 'G5' ? G5_CHECKLIST_VARIANTS : genre === 'G6' ? G6_CHECKLIST_VARIANTS : undefined;
+    if (variants !== undefined) {
+        return items.map((item) => variants[item.id] ?? item);
     }
     return items;
 }

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
@@ -46,3 +46,10 @@ export declare const G4_EN: string;
 export declare const G5_ZH: string;
 /** G5 — current-state ledger, en (section-for-section twin of G5_ZH). */
 export declare const G5_EN: string;
+/** G6 — 操作手册/how-to 页 (goal-titled operational manual), zh. Diátaxis doing
+ *  leg: a reader with one goal follows the numbered steps to the outcome; every
+ *  step carries 动作 + 预期结果 + 失败处置. Concepts stay in G4 pages, raw
+ *  command lists in G3 pages, linked from 相关页面. */
+export declare const G6_ZH: string;
+/** G6 — how-to manual, en (section-for-section twin of G6_ZH). */
+export declare const G6_EN: string;