opencode-wiki-historian 0.2.0

package/dist/map.js

@@ -0,0 +1,196 @@
+/**
+ * Locale-aware page map (todo 10): full cross-locale inventory with en/zh twin
+ * pairing, rendered as the markdown `_meta/page-map` cache page + local mirror.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { isRecord } from './jsonc.js';
+import { assertLocalePair, localeUrl, normalizeLocale, PathValidationError, twinOf } from './wiki/locale.js';
+import { createPage, readPage, updatePage } from './wiki/pages.js';
+import { listPages } from './wiki/pages.read.js';
+// --- Constants --------------------------------------------------------------
+export const CACHE_PATH = '_meta/page-map';
+const CACHE_TITLE = 'Page Map Cache';
+export const HEADER_ROW = '| ID | Locale | Path | Title | View URL | Twin | Updated At |';
+export function mirrorPath(home) {
+    return join(home, '.config', 'opencode', 'historian-map.json');
+}
+// --- buildPageMap -----------------------------------------------------------
+/** URLs for a server-reported path. assertLocalePair validates paths — but
+ *  that guard protects MUTATIONS; a live page can legally sit on a reserved
+ *  path (the instance hosts a page at 'home'). For inventory reads the raw
+ *  join is the fallback, not a failure. */
+function urlsOf(path, baseUrl, locale) {
+    try {
+        return assertLocalePair(path, locale, baseUrl);
+    }
+    catch (err) {
+        if (!(err instanceof PathValidationError))
+            throw err;
+        const twinLocale = twinOf(locale);
+        return {
+            path,
+            locale,
+            url: `${baseUrl.replace(/\/+$/, '')}/${locale}/${path}`,
+            twinLocale,
+            twinUrl: `${baseUrl.replace(/\/+$/, '')}/${twinLocale}/${path}`,
+        };
+    }
+}
+/** Full inventory: every page of every configured locale (only private-
+ *  namespace pages are excluded — they are not anonymously reachable), twins
+ *  paired by exact path, rows sorted by path then locale. */
+export async function buildPageMap(deps) {
+    const locales = [...new Set(deps.options.locales.map(normalizeLocale))].sort();
+    const lists = await Promise.all(locales.map((locale) => listPages(deps.client, { locale })));
+    const byPath = new Map();
+    for (let i = 0; i < locales.length; i++) {
+        for (const item of lists[i]) {
+            if (item.privateNS !== null)
+                continue;
+            let perLocale = byPath.get(item.path);
+            if (perLocale === undefined) {
+                perLocale = new Map();
+                byPath.set(item.path, perLocale);
+            }
+            perLocale.set(item.locale, item);
+        }
+    }
+    const rows = [];
+    const missingTwinPaths = [];
+    const sortedPaths = [...byPath.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    for (const [path, perLocale] of sortedPaths) {
+        if (perLocale.size === 1)
+            missingTwinPaths.push(path);
+        for (const locale of locales) {
+            const item = perLocale.get(locale);
+            if (item === undefined)
+                continue;
+            const pair = urlsOf(path, deps.options.baseUrl, locale);
+            const twin = perLocale.get(twinOf(locale));
+            rows.push({
+                id: item.id,
+                locale,
+                path,
+                title: item.title,
+                updatedAt: item.updatedAt,
+                url: pair.url,
+                twinUrl: twin === undefined ? null : pair.twinUrl,
+                twinId: twin === undefined ? null : twin.id,
+            });
+        }
+    }
+    const perLocaleCounts = {};
+    for (const locale of locales)
+        perLocaleCounts[locale] = 0;
+    for (const row of rows)
+        perLocaleCounts[row.locale] += 1;
+    return { rows, stats: { rows: rows.length, paths: sortedPaths.length, perLocale: perLocaleCounts, missingTwinPaths } };
+}
+// --- renderMapMarkdown ------------------------------------------------------
+export function renderMapMarkdown(rows) {
+    const lines = rows.map((r) => `| ${r.id} | ${r.locale} | ${r.path} | ${r.title.replaceAll('|', '\\|')} | ${r.url} | ${r.twinUrl ?? '—'} | ${r.updatedAt} |`);
+    return [HEADER_ROW, '| --- | --- | --- | --- | --- | --- | --- |', ...lines, ''].join('\n');
+}
+// --- Local mirror -----------------------------------------------------------
+function writeMirror(home, mirror) {
+    const file = mirrorPath(home);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(mirror, null, 2)}\n`);
+}
+function isMapRow(v) {
+    if (!isRecord(v))
+        return false;
+    return (typeof v.id === 'number' &&
+        (v.locale === 'en' || v.locale === 'zh') &&
+        typeof v.path === 'string' &&
+        typeof v.title === 'string' &&
+        typeof v.updatedAt === 'string' &&
+        typeof v.url === 'string' &&
+        (v.twinUrl === null || typeof v.twinUrl === 'string') &&
+        (v.twinId === null || typeof v.twinId === 'number'));
+}
+function parseStats(v) {
+    if (typeof v.rows !== 'number' || typeof v.paths !== 'number' || !isRecord(v.perLocale) || !Array.isArray(v.missingTwinPaths)) {
+        return null;
+    }
+    const perLocale = {};
+    for (const [key, value] of Object.entries(v.perLocale)) {
+        if (typeof value !== 'number')
+            return null;
+        perLocale[key] = value;
+    }
+    const missingTwinPaths = v.missingTwinPaths.filter((p) => typeof p === 'string');
+    if (missingTwinPaths.length !== v.missingTwinPaths.length)
+        return null;
+    return { rows: v.rows, paths: v.paths, perLocale, missingTwinPaths };
+}
+/** Missing or malformed mirror → null: the mirror is a regenerable cache, not
+ *  a trustworthy boundary — a damaged file falls back to a live build. */
+function readMirror(home) {
+    const file = mirrorPath(home);
+    if (!existsSync(file))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(raw) || typeof raw.generatedAt !== 'string')
+        return null;
+    if (!Array.isArray(raw.rows) || !isRecord(raw.stats))
+        return null;
+    const rows = raw.rows.filter(isMapRow);
+    if (rows.length !== raw.rows.length)
+        return null;
+    const stats = parseStats(raw.stats);
+    if (stats === null)
+        return null;
+    return { generatedAt: raw.generatedAt, rows, stats };
+}
+/** Rebuild + write cycle: fresh map → local mirror → `_meta/page-map` upsert.
+ *  An existing cache page is patched content-only — updatePage is a full RMW,
+ *  so the machine-fact isPrivate/isPublished/tags survive (pitfall #1). */
+export async function refreshMapCache(deps, opts) {
+    const now = opts?.now ?? new Date();
+    const home = opts?.homeDir ?? homedir();
+    const { rows, stats } = await buildPageMap(deps);
+    writeMirror(home, { generatedAt: now.toISOString(), rows, stats });
+    const markdown = renderMapMarkdown(rows);
+    const existing = await readPage(deps.client, CACHE_PATH, 'en');
+    if (existing === null) {
+        await createPage(deps, {
+            path: CACHE_PATH,
+            locale: 'en',
+            title: CACHE_TITLE,
+            content: markdown,
+            tags: ['meta'],
+            isPublished: false,
+            isPrivate: true,
+            twin: false,
+        });
+    }
+    else {
+        await updatePage(deps, existing.id, { content: markdown });
+    }
+    return { stats, cacheUrl: localeUrl(deps.options.baseUrl, 'en', CACHE_PATH) };
+}
+// --- getMap -----------------------------------------------------------------
+/** Read the local mirror with staleness in whole seconds; absent or damaged
+ *  mirror → a live build (read-only — no cache page write, no mirror write). */
+export async function getMap(deps, homeDir) {
+    const home = homeDir ?? homedir();
+    const mirror = readMirror(home);
+    if (mirror === null) {
+        const { rows, stats } = await buildPageMap(deps);
+        return { rows, stats, generatedAt: null, staleSeconds: null };
+    }
+    const parsed = Date.parse(mirror.generatedAt);
+    const staleSeconds = Number.isNaN(parsed)
+        ? null
+        : Math.max(0, Math.floor((Date.now() - parsed) / 1000));
+    return { rows: mirror.rows, stats: mirror.stats, generatedAt: mirror.generatedAt, staleSeconds };
+}

package/dist/migrate-apply.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Migration engine — apply side (plan todo 14): the write pipeline. Order is
+ * the safety contract: ① pre-image backup FIRST (before any write; both
+ * locales, missing twin recorded null), ② per-locale upsert (present →
+ * updatePage RMW; missing twin → auto-created via the translation engine,
+ * isPublished/tags inherited from the source — never publishes fixtures),
+ * ③ path-level checkpoint (~/.config/opencode/historian-migrate.json;
+ * re-apply of the same path+pre-state contentHash is a no-op skip),
+ * ④ second-pass verification: checklist re-scored on the STORED content.
+ * Mid-apply failure → {ok:false}, backup left, NO checkpoint → resumable.
+ */
+import { type MigrateDeps } from './migrate.js';
+import { type Genre } from './templates/genres.js';
+import { type ChecklistVerdict } from './migrate-score.js';
+import { type Locale } from './wiki/pages.read.js';
+export interface ApplyArgs {
+    readonly path: string;
+    readonly genre?: Genre;
+    readonly draft?: string;
+    readonly now?: Date;
+}
+export interface AppliedEntry {
+    readonly locale: Locale;
+    readonly action: 'updated' | 'created';
+    readonly urls: {
+        en: string;
+        zh: string;
+    };
+    readonly checklist: readonly ChecklistVerdict[];
+}
+export type ApplyOutcome = {
+    ok: true;
+    applied: readonly AppliedEntry[];
+    backupPath: string;
+    skipped?: string;
+} | {
+    ok: false;
+    error: Error;
+};
+export declare function applyMigration(deps: MigrateDeps, args: ApplyArgs): Promise<ApplyOutcome>;

package/dist/migrate-apply.js

@@ -0,0 +1,144 @@
+/**
+ * Migration engine — apply side (plan todo 14): the write pipeline. Order is
+ * the safety contract: ① pre-image backup FIRST (before any write; both
+ * locales, missing twin recorded null), ② per-locale upsert (present →
+ * updatePage RMW; missing twin → auto-created via the translation engine,
+ * isPublished/tags inherited from the source — never publishes fixtures),
+ * ③ path-level checkpoint (~/.config/opencode/historian-migrate.json;
+ * re-apply of the same path+pre-state contentHash is a no-op skip),
+ * ④ second-pass verification: checklist re-scored on the STORED content.
+ * Mid-apply failure → {ok:false}, backup left, NO checkpoint → resumable.
+ */
+import { reformatPageDraft, urlsOf } from './migrate.js';
+import { makeTranslator } from './translate.js';
+import { scoreChecklist } from './migrate-score.js';
+import { backupFileFor, dateKey, defaultResultsDir, hashText, readBackup, readCheckpoint, sectionOf, writeBackup, writeCheckpoint, } from './migrate-store.js';
+import { createPage, PageNotFoundError, updatePage } from './wiki/pages.js';
+import { readPage } from './wiki/pages.read.js';
+import { readPageState } from './wiki/pages.write.js';
+function resolveTranslator(deps) {
+    if (deps.translate !== undefined)
+        return deps.translate;
+    // Production has no injected translator: fall back to the real-fetch engine.
+    return deps.fetchImpl !== undefined ? makeTranslator(deps.options, { fetchImpl: deps.fetchImpl }) : makeTranslator(deps.options);
+}
+async function preImageOf(deps, en, zh) {
+    const capture = async (p) => {
+        if (p === null)
+            return null;
+        const s = await readPageState(deps.client, p.id);
+        return {
+            content: s.content,
+            title: s.title,
+            description: s.description,
+            tags: s.tags,
+            isPublished: s.isPublished,
+            publishStartDate: s.publishStartDate,
+            publishEndDate: s.publishEndDate,
+        };
+    };
+    return { en: await capture(en), zh: await capture(zh) };
+}
+export async function applyMigration(deps, args) {
+    const now = args.now ?? (deps.now !== undefined ? deps.now() : new Date());
+    const resultsDir = deps.resultsDir ?? defaultResultsDir();
+    const backupFile = backupFileFor(sectionOf(args.path), dateKey(now), resultsDir);
+    const en = await readPage(deps.client, args.path, 'en');
+    const zh = await readPage(deps.client, args.path, 'zh');
+    const source = en ?? zh;
+    if (source === null) {
+        return { ok: false, error: new PageNotFoundError(`page '${args.path}' does not exist (checked en and zh locales)`) };
+    }
+    let draft;
+    let genre;
+    if (args.draft === undefined || args.genre === undefined) {
+        const r = await reformatPageDraft(deps, { path: args.path, genre: args.genre });
+        if (!r.ok)
+            return { ok: false, error: r.error };
+        draft = r.draft;
+        genre = r.genre;
+    }
+    else {
+        draft = args.draft;
+        genre = args.genre;
+    }
+    const translator = resolveTranslator(deps);
+    if (translator === undefined) {
+        return { ok: false, error: new Error('translator not wired — the twin locale content must be translated; add translate config or pass a translator to buildTools') };
+    }
+    const pageDeps = { client: deps.client, options: deps.options, translate: translator };
+    // Checkpoint latch: identical pre-state (path + contentHash) → no-op skip.
+    const cp = readCheckpoint(deps.homeDir);
+    const recorded = cp.paths[args.path];
+    const curHash = hashText(source.content);
+    const curZhHash = zh === null ? null : hashText(zh.content);
+    if (recorded !== undefined && recorded.contentHash === curHash && recorded.zhHash === curZhHash) {
+        return {
+            ok: true,
+            applied: [],
+            backupPath: backupFile,
+            skipped: `checkpoint no-op: '${args.path}' unchanged since applied at ${recorded.appliedAt} — nothing to redo`,
+        };
+    }
+    // ① pre-image backup FIRST — before any write (restore program of record).
+    const backup = readBackup(backupFile);
+    if (backup.paths[args.path] === undefined) {
+        const paths = { ...backup.paths, [args.path]: await preImageOf(deps, en, zh) };
+        writeBackup(backupFile, { section: sectionOf(args.path), createdAt: now.toISOString(), paths });
+    }
+    // ② per-locale upsert (source locale gets the raw draft, twin gets the
+    //    engine translation — the twin is created, never spuriously duplicating
+    //    createPage's internal twin flow, which would re-parse the draft).
+    try {
+        const applied = [];
+        for (const locale of ['en', 'zh']) {
+            const existing = locale === 'en' ? en : zh;
+            const isSource = locale === source.locale;
+            if (existing !== null) {
+                const content = isSource ? draft : await translator(draft, source.locale, locale);
+                const after = await updatePage(pageDeps, existing.id, { content });
+                applied.push({
+                    locale,
+                    action: 'updated',
+                    urls: urlsOf(deps.options.baseUrl, existing.path, locale),
+                    checklist: scoreChecklist(genre, after.page.content),
+                });
+            }
+            else {
+                const twinTitle = await translator(source.title, source.locale, locale);
+                const twinContent = await translator(draft, source.locale, locale);
+                await createPage(pageDeps, {
+                    path: args.path,
+                    locale,
+                    title: twinTitle,
+                    content: twinContent,
+                    tags: source.tags,
+                    isPublished: source.isPublished,
+                    twin: false,
+                });
+                const stored = await readPage(deps.client, args.path, locale);
+                if (stored === null) {
+                    throw new Error(`create reported success but the re-read of '${args.path}' (${locale}) returned nothing`);
+                }
+                applied.push({
+                    locale,
+                    action: 'created',
+                    urls: urlsOf(deps.options.baseUrl, source.path, locale),
+                    checklist: scoreChecklist(genre, stored.content),
+                });
+            }
+        }
+        // ③ checkpoint — written only after ALL writes succeeded.
+        writeCheckpoint(deps.homeDir, {
+            version: 1,
+            paths: {
+                ...cp.paths,
+                [args.path]: { contentHash: curHash, zhHash: curZhHash, appliedAt: now.toISOString(), genre },
+            },
+        });
+        return { ok: true, applied, backupPath: backupFile };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err : new Error(String(err)) };
+    }
+}

package/dist/migrate-score.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Deterministic self-review checklist scoring (plan todo 14/15): the 10-item
+ * gate is scored by CODE on the reformatted draft — the LLM only restyles,
+ * it never scores (an auditable gate). Verdict contract:
+ *   - items 1-8 (content)   → 'pass' | 'fail' by the checks below
+ *   - items 4-6 are 'na'    → when the page genre is not in appliesTo
+ *   - items 9-10 (post-write) → 'deferred' until after apply (they are FAIL
+ *     by construction pre-write; todo 15 writes them into the pilot report)
+ *
+ * Every threshold below is tolerant-but-real: it catches egregious
+ * violations, never bikesheds a conformant page. Measured values ride in the
+ * verdict note so a reviewer sees exactly what was counted.
+ */
+import type { Genre } from './templates/genres.js';
+export type Verdict = 'pass' | 'fail' | 'na' | 'deferred';
+export interface ChecklistVerdict {
+    readonly id: number;
+    readonly verdict: Verdict;
+    readonly note?: string;
+}
+/** Score the full 10-item gate on a draft. `genre` decides items 4-6:
+ *  the base gate's item 4 applies to G2 only and items 5-6 to G1 only
+ *  (G3/G4 → 'na'); G5 pages get the ledger variants of all three
+ *  (last-verified column, verification commands, table-not-prose). */
+export declare function scoreChecklist(genre: Genre, draft: string): readonly ChecklistVerdict[];
+/** Whitespace-normalized equality (the strong signal); otherwise trigram
+ *  Jaccard similarity ≥ 0.95. Deterministic, diff-based — never prose. */
+export declare function contentSimilar(a: string, b: string): boolean;
+export declare function normalize(s: string): string;

package/dist/migrate-score.js

@@ -0,0 +1,267 @@
+/**
+ * Deterministic self-review checklist scoring (plan todo 14/15): the 10-item
+ * gate is scored by CODE on the reformatted draft — the LLM only restyles,
+ * it never scores (an auditable gate). Verdict contract:
+ *   - items 1-8 (content)   → 'pass' | 'fail' by the checks below
+ *   - items 4-6 are 'na'    → when the page genre is not in appliesTo
+ *   - items 9-10 (post-write) → 'deferred' until after apply (they are FAIL
+ *     by construction pre-write; todo 15 writes them into the pilot report)
+ *
+ * Every threshold below is tolerant-but-real: it catches egregious
+ * violations, never bikesheds a conformant page. Measured values ride in the
+ * verdict note so a reviewer sees exactly what was counted.
+ */
+import { selfReviewChecklist } from './templates/genres.js';
+// --- Text preprocessing (prose extraction for sentence metrics) -------------
+const FENCED = /```[\s\S]*?```/g;
+const INLINE_CODE = /`[^`]+`/g;
+const TABLE_LINE = /^\s*\|.*\|.*\|/;
+const HEADING_LINE = /^\s{0,3}#{1,6}\s/;
+const QUOTE_LINE = /^\s{0,3}>\s?/;
+const HR_LINE = /^\s{0,3}(---|\*\*\*|___)\s*$/;
+/** Prose-only view of a draft: code blocks, inline code, table rows, headings
+ *  and blockquotes are not sentence prose (tables are scored by items 4-6). */
+function proseOf(markdown) {
+    return markdown
+        .replace(FENCED, ' ')
+        .replace(INLINE_CODE, ' ')
+        .split('\n')
+        .filter((l) => !TABLE_LINE.test(l) && !HEADING_LINE.test(l) && !QUOTE_LINE.test(l) && !HR_LINE.test(l))
+        .join('\n');
+}
+const SENTENCE_BREAK = /[。！？!?]+/;
+const CJK_RE = /[\u4e00-\u9fff]/g;
+function sentencesOf(prose) {
+    return prose
+        .split(SENTENCE_BREAK)
+        .map((s) => s.replace(/[|*_`#>-]/g, '').trim())
+        .filter((s) => s.length > 0)
+        .slice(0, 30);
+}
+/** zh: ≤20 chars (CJK chars + latin tokens); en: ≤25 words. A sentence with
+ *  any CJK char is judged by the zh rule. */
+function sentenceTooLong(sentence) {
+    const tokens = sentence.match(/[A-Za-z0-9][\w-]*/g) ?? [];
+    const cjkChars = (sentence.match(CJK_RE) ?? []).length;
+    const effectiveLength = cjkChars > 0 ? cjkChars + tokens.length : tokens.length;
+    return cjkChars > 0 ? effectiveLength > 20 : effectiveLength > 25;
+}
+/** Tables = a header row (`| a | b |`) followed by a separator row. Cells are
+ *  de-fenced and lowercased for the header checks. */
+function tablesOf(markdown) {
+    const lines = markdown.split('\n');
+    const tables = [];
+    for (let i = 0; i < lines.length - 1; i++) {
+        const next = lines[i + 1];
+        if (/^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(next)) {
+            const cells = lines[i].split('|').map((c) => c.trim().replace(/`/g, '').toLowerCase()).filter((c) => c.length > 0);
+            if (cells.length >= 3)
+                tables.push({ header: cells });
+        }
+    }
+    return tables;
+}
+// --- Scoring ----------------------------------------------------------------
+function leadRatio(draft) {
+    const firstH2 = draft.search(/\n#{2,3}\s/);
+    if (firstH2 === -1)
+        return 1;
+    const lead = draft.slice(0, firstH2);
+    const total = Math.max(draft.length, 1);
+    return lead.length / total;
+}
+function scoreItem1(draft) {
+    const measured = leadRatio(draft);
+    const pass = measured >= 0.04 && measured <= 0.45;
+    return { id: 1, verdict: pass ? 'pass' : 'fail', note: pass ? undefined : `lead=${(measured * 100).toFixed(1)}% of body (tol 4-45%)` };
+}
+function scoreItem2(draft) {
+    const sentences = sentencesOf(proseOf(draft));
+    if (sentences.length === 0)
+        return { id: 2, verdict: 'pass', note: 'no prose sentences sampled' };
+    const overflow = sentences.filter(sentenceTooLong).length;
+    const allowance = Math.max(1, Math.floor(sentences.length / 10));
+    const pass = overflow <= allowance;
+    return {
+        id: 2,
+        verdict: pass ? 'pass' : 'fail',
+        note: pass ? undefined : `${overflow}/${sentences.length} sampled sentences exceed the cap (zh ≤20 chars, en ≤25 words)`,
+    };
+}
+function scoreItem3(draft) {
+    const hasTable = tablesOf(draft).length > 0;
+    return { id: 3, verdict: hasTable ? 'pass' : 'fail', note: hasTable ? undefined : 'no ≥3-column markdown table found' };
+}
+function scoreItem4(draft) {
+    const offenders = tablesOf(draft).filter((t) => !t.header.some((c) => /来源|source|reference/.test(c)));
+    return {
+        id: 4,
+        verdict: offenders.length === 0 ? 'pass' : 'fail',
+        note: offenders.length === 0 ? undefined : `${offenders.length} table(s) lack a source column`,
+    };
+}
+function scoreItem5(draft) {
+    const timeline = tablesOf(draft).find((t) => t.header.some((c) => /时间|time/.test(c)));
+    if (timeline === undefined)
+        return { id: 5, verdict: 'fail', note: 'no timeline table (时间|事件|来源) found' };
+    const hasSource = timeline.header.some((c) => /来源|source/.test(c));
+    return { id: 5, verdict: hasSource ? 'pass' : 'fail', note: hasSource ? undefined : 'timeline table has no source column' };
+}
+const FIVE_ESSENTIALS_ZH = ['类型', '负责人', '期限', '验证', '状态'];
+const FIVE_ESSENTIALS_EN = [
+    ['type'],
+    ['owner'],
+    ['due', 'deadline'],
+    ['verif'],
+    ['status', 'state'],
+];
+function scoreItem6(draft) {
+    const actionTable = tablesOf(draft).find((t) => {
+        if (t.header.length < 5)
+            return false;
+        const five = FIVE_ESSENTIALS_ZH.every((k) => t.header.some((c) => c.includes(k)))
+            ? FIVE_ESSENTIALS_ZH
+            : FIVE_ESSENTIALS_EN.every((k) => k.some((pre) => t.header.some((c) => c.startsWith(pre))))
+                ? 'en'
+                : null;
+        return five !== null;
+    });
+    return {
+        id: 6,
+        verdict: actionTable !== undefined ? 'pass' : 'fail',
+        note: actionTable !== undefined ? undefined : 'no action-item table with the five essentials (类型|负责人|期限|验证|状态) as columns',
+    };
+}
+const CATCH_ALL = ['其他', '杂项', 'miscellaneous', 'misc', 'other'];
+const EXEMPT_TAILS = ['附录', 'appendix', '参见', 'see also', 'see-also', '参考'];
+function scoreItem7(draft) {
+    const headings = draft.split('\n').filter((l) => /^\s{0,3}##{1,3}\s/.test(l));
+    const h = (line) => line.replace(/^\s{0,3}#+/, '').replace(/[#*`]/g, '').trim().toLowerCase();
+    const banned = headings.map(h).find((t) => CATCH_ALL.some((w) => t.includes(w)) && !EXEMPT_TAILS.some((w) => t.includes(w)));
+    return {
+        id: 7,
+        verdict: banned === undefined ? 'pass' : 'fail',
+        note: banned === undefined ? undefined : `catch-all section heading: "${banned}"`,
+    };
+}
+const MARKETING = [
+    ['robust', 'streamline', 'leverage', 'utilize', 'world-class', 'cutting-edge', 'delve'],
+    ['强大的', '领先的', '先进的', '赋能'],
+];
+function scoreItem8(draft) {
+    const body = draft.replace(FENCED, ' ');
+    const hit = MARKETING[0].find((w) => new RegExp(`\\b${w}`, 'i').test(body)) ?? MARKETING[1].find((w) => body.includes(w));
+    return { id: 8, verdict: hit === undefined ? 'pass' : 'fail', note: hit === undefined ? undefined : `unbacked praise term: "${hit}"` };
+}
+// --- G5 ledger scorers (selfReviewChecklist G5 variants of items 4-6) --------
+const G5_LEDGER_COL = /(组件|component)/;
+const G5_VERSION_COL = /(版本|version)/;
+const G5_VERIFIED_COL = /(核实|verif)/;
+const COMMENT_ONLY_LINE = /^\s*<!--.*-->\s*$/;
+function scoreG5Item4(draft) {
+    const ledgers = tablesOf(draft).filter((t) => t.header.some((c) => G5_LEDGER_COL.test(c)) && t.header.some((c) => G5_VERSION_COL.test(c)));
+    if (ledgers.length === 0) {
+        return { id: 4, verdict: 'fail', note: 'no component ledger table (组件|版本|…|上次核实于) found' };
+    }
+    const missing = ledgers.filter((t) => !t.header.some((c) => G5_VERIFIED_COL.test(c)));
+    return {
+        id: 4,
+        verdict: missing.length === 0 ? 'pass' : 'fail',
+        note: missing.length === 0 ? undefined : `${missing.length} ledger table(s) lack a last-verified (上次核实于) column`,
+    };
+}
+function scoreG5Item5(draft) {
+    const lines = draft.split('\n');
+    const start = lines.findIndex((l) => /^#{2,3}\s/.test(l) && /验证方法|verification/i.test(l));
+    if (start === -1) {
+        return { id: 5, verdict: 'fail', note: 'no 验证方法/Verification section' };
+    }
+    const end = lines.findIndex((l, i) => i > start && /^#{1,3}\s/.test(l));
+    const section = lines.slice(start + 1, end === -1 ? lines.length : end).join('\n');
+    const hasCommand = /`[^`\n]+`/.test(section) || /```/.test(section);
+    return {
+        id: 5,
+        verdict: hasCommand ? 'pass' : 'fail',
+        note: hasCommand ? undefined : '验证方法 section carries no executable command (inline code or fenced block)',
+    };
+}
+function scoreG5Item6(draft) {
+    const tableLines = draft.split('\n').filter((l) => TABLE_LINE.test(l)).length;
+    const narrative = proseOf(draft)
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !COMMENT_ONLY_LINE.test(l)).length;
+    const pass = tablesOf(draft).length > 0 && narrative <= Math.max(tableLines, 6);
+    return {
+        id: 6,
+        verdict: pass ? 'pass' : 'fail',
+        note: pass ? undefined : `narrative lines (${narrative}) outnumber table lines (${tableLines}) — a ledger is status + tables, not prose`,
+    };
+}
+/** Score the full 10-item gate on a draft. `genre` decides items 4-6:
+ *  the base gate's item 4 applies to G2 only and items 5-6 to G1 only
+ *  (G3/G4 → 'na'); G5 pages get the ledger variants of all three
+ *  (last-verified column, verification commands, table-not-prose). */
+export function scoreChecklist(genre, draft) {
+    const items = selfReviewChecklist(genre);
+    const na = (item) => ({
+        id: item.id,
+        verdict: 'na',
+        note: `N/A — genre ${genre} not in appliesTo`,
+    });
+    const deferred = (item) => ({
+        id: item.id,
+        verdict: 'deferred',
+        note: 'post-write item — score after apply and write into the pilot report',
+    });
+    const ledger = genre === 'G5';
+    return items.map((item) => {
+        const applies = item.appliesTo === 'all' || item.appliesTo.includes(genre);
+        switch (item.id) {
+            case 1: return scoreItem1(draft);
+            case 2: return scoreItem2(draft);
+            case 3: return scoreItem3(draft);
+            case 4: return applies ? (ledger ? scoreG5Item4(draft) : scoreItem4(draft)) : na(item);
+            case 5: return applies ? (ledger ? scoreG5Item5(draft) : scoreItem5(draft)) : na(item);
+            case 6: return applies ? (ledger ? scoreG5Item6(draft) : scoreItem6(draft)) : na(item);
+            case 7: return scoreItem7(draft);
+            case 8: return scoreItem8(draft);
+            default: return deferred(item);
+        }
+    });
+}
+// --- Conformance signal (todo 14 roundtrip step ③) ---------------------------
+/** Whitespace-normalized equality (the strong signal); otherwise trigram
+ *  Jaccard similarity ≥ 0.95. Deterministic, diff-based — never prose. */
+export function contentSimilar(a, b) {
+    const na = normalize(a);
+    if (na === normalize(b))
+        return true;
+    return trigramSimilarity(na, normalize(b)) >= 0.95;
+}
+export function normalize(s) {
+    return s.trim().replace(/\s+/g, ' ');
+}
+function trigramSimilarity(a, b) {
+    const grams = (s) => {
+        const out = new Set();
+        if (s.length < 3) {
+            if (s.length > 0)
+                out.add(s);
+            return out;
+        }
+        for (let i = 0; i <= s.length - 3; i++)
+            out.add(s.slice(i, i + 3));
+        return out;
+    };
+    const ga = grams(a);
+    const gb = grams(b);
+    if (ga.size === 0 && gb.size === 0)
+        return 1;
+    let inter = 0;
+    for (const g of ga)
+        if (gb.has(g))
+            inter++;
+    const union = ga.size + gb.size - inter;
+    return union === 0 ? 1 : inter / union;
+}