opencode-wiki-historian 0.2.0 → 0.4.0

package/dist/maintain.js

@@ -0,0 +1,352 @@
+/**
+ * Maintain curation report (plan todo-7, D3 CURATE / D12): deterministic
+ * metric sweeps over already-fetched map rows (tier-1 light) plus optional
+ * injected page-body reads (deep). The chronology.ts precedent holds here —
+ * no client, no fs, no wiki logic: pure functions over MapRow-shaped input and
+ * a readBody dependency; the tool layer (tools/local.ts) supplies both.
+ *
+ * Output is dual-form: a human markdown report (renderMaintainMarkdown) and a
+ * machine-readable JSON tail with stable top-level keys (schema
+ * 'historian.maintain.v1') so later todos can parse it without re-deriving.
+ *
+ * allow: SIZE_OK — the plan pins this commit to src/maintain.ts +
+ * tools/local.ts + test/maintain.test.ts only, so the metric builder and its
+ * markdown renderer ship as one module instead of a third file.
+ */
+import { classifyGenre } from './templates/genres.js';
+import { isInternalPath } from './tools/shared.js';
+import { normalize } from './migrate-score.js';
+// --- Constants --------------------------------------------------------------
+export const MAINTAIN_SCHEMA = 'historian.maintain.v1';
+/** Trigram-Jaccard bar for calling two (different-path) titles near-duplicates. */
+export const DUP_TITLE_THRESHOLD = 0.75;
+const DAY_MS = 86_400_000;
+const DEFAULT_TOP_N = 10;
+/** Genres whose pages must carry the D4 last-verified stamp (G6 how-to joins
+ *  this set when todo-2 lands it — string membership, no type coupling). */
+// D4 freshness applies to knowledge-fact pages: G5 today; 'G6' is listed
+// pre-emptively so the deep sweep lights up when the genre lane lands.
+const FRESHNESS_GENRES = ['G5', 'G6'];
+const STAMP_RE = /上次核实|last verified/i;
+const REVIEW_LABEL_RE = /^(复核周期|复核期限|复核日期|review[-_ ]?by|review[-_ ]?due)$/i;
+const ISO_DATE_RE = /\d{4}-\d{2}-\d{2}/;
+const REDIRECT_RE = /^>\s*Redirect:/i;
+// --- Title similarity (trigram core copied from migrate-score.ts:289, where it
+// --- is private with a 0.95 roundtrip bar; maintain needs its own threshold) ---
+function titleGrams(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;
+}
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let inter = 0;
+    for (const g of a)
+        if (b.has(g))
+            inter++;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 1 : inter / union;
+}
+// --- Metric builders ----------------------------------------------------------
+function cmpStr(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function findDuplicates(rows) {
+    const units = rows.map((r) => ({
+        path: r.path,
+        title: r.title,
+        grams: titleGrams(normalize(r.title).toLowerCase()),
+    }));
+    const parent = units.map((_, i) => i);
+    const find = (i) => {
+        while (parent[i] !== i) {
+            parent[i] = parent[parent[i]];
+            i = parent[i];
+        }
+        return i;
+    };
+    for (let i = 0; i < units.length; i++) {
+        for (let j = i + 1; j < units.length; j++) {
+            // twins share a path by design — never a duplicate; cross-locale title
+            // similarity is low enough that same-path exclusion is the only guard needed
+            if (units[i].path === units[j].path)
+                continue;
+            if (jaccard(units[i].grams, units[j].grams) >= DUP_TITLE_THRESHOLD)
+                parent[find(i)] = find(j);
+        }
+    }
+    const clusters = new Map();
+    units.forEach((u, i) => {
+        const root = find(i);
+        const bucket = clusters.get(root) ?? { paths: new Set(), titles: new Set() };
+        bucket.paths.add(u.path);
+        bucket.titles.add(u.title);
+        clusters.set(root, bucket);
+    });
+    const out = [...clusters.values()]
+        .filter((c) => c.paths.size >= 2)
+        .map((c) => ({ paths: [...c.paths].sort(cmpStr), titles: [...c.titles].sort(cmpStr) }));
+    out.sort((a, b) => b.paths.length - a.paths.length || cmpStr(a.paths[0], b.paths[0]));
+    return out;
+}
+function staleness(rows, now, topN) {
+    const byPath = new Map();
+    for (const r of rows) {
+        const t = Date.parse(r.updatedAt);
+        if (Number.isNaN(t))
+            continue;
+        const cur = byPath.get(r.path);
+        if (cur === undefined)
+            byPath.set(r.path, { t, updatedAt: r.updatedAt, locales: new Set([r.locale]) });
+        else {
+            cur.locales.add(r.locale);
+            if (t > cur.t) {
+                cur.t = t;
+                cur.updatedAt = r.updatedAt;
+            }
+        }
+    }
+    const round1 = (x) => Math.round(x * 10) / 10;
+    return [...byPath.entries()]
+        .map(([path, v]) => ({
+        path,
+        updatedAt: v.updatedAt,
+        daysOld: round1((now.getTime() - v.t) / DAY_MS),
+        locales: [...v.locales].sort(cmpStr),
+    }))
+        .sort((a, b) => a.updatedAt.localeCompare(b.updatedAt) || cmpStr(a.path, b.path))
+        .slice(0, topN);
+}
+function singleChildDirs(paths) {
+    const subtree = new Map();
+    for (const path of paths) {
+        const segs = path.split('/');
+        for (let i = 1; i < segs.length; i++) {
+            const dir = segs.slice(0, i).join('/');
+            const bucket = subtree.get(dir) ?? new Set();
+            bucket.add(path);
+            subtree.set(dir, bucket);
+        }
+    }
+    const single = new Set([...subtree.entries()].filter(([, v]) => v.size === 1).map(([d]) => d));
+    const out = [];
+    for (const dir of [...single].sort(cmpStr)) {
+        const cut = dir.lastIndexOf('/');
+        if (cut > 0 && single.has(dir.slice(0, cut)))
+            continue; // report the shallowest of a chain
+        const children = subtree.get(dir);
+        if (children !== undefined)
+            out.push({ dir, childPath: [...children][0] });
+    }
+    return out;
+}
+function rootOrphans(paths) {
+    const bySection = new Map();
+    for (const path of paths) {
+        if (path.split('/').length !== 2)
+            continue;
+        const section = path.split('/')[0];
+        const bucket = bySection.get(section) ?? [];
+        bucket.push(path);
+        bySection.set(section, bucket);
+    }
+    return [...bySection.entries()]
+        .map(([section, ps]) => ({ section, paths: ps.sort(cmpStr) }))
+        .sort((a, b) => cmpStr(a.section, b.section));
+}
+function tagVocab(rows) {
+    const available = rows.some((r) => r.tags !== undefined);
+    if (!available)
+        return { available: false, vocabulary: [] };
+    const counts = new Map();
+    for (const r of rows)
+        for (const tag of r.tags ?? [])
+            counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    const vocabulary = [...counts.entries()]
+        .map(([tag, count]) => ({ tag, count }))
+        .sort((a, b) => b.count - a.count || cmpStr(a.tag, b.tag));
+    return { available: true, vocabulary };
+}
+function sectionDist(rows) {
+    const bySection = new Map();
+    for (const r of rows) {
+        const section = r.path.split('/')[0];
+        const bucket = bySection.get(section) ?? { paths: new Set(), rows: 0 };
+        bucket.paths.add(r.path);
+        bucket.rows += 1;
+        bySection.set(section, bucket);
+    }
+    return [...bySection.entries()]
+        .map(([section, v]) => ({ section, paths: v.paths.size, rows: v.rows }))
+        .sort((a, b) => b.paths - a.paths || cmpStr(a.section, b.section));
+}
+/** D4 review-by row inside a 元数据 markdown table (wiki.js has no front matter). */
+function reviewByOf(body) {
+    for (const line of body.split('\n')) {
+        if (!line.trimStart().startsWith('|'))
+            continue;
+        const cells = line.split('|').map((c) => c.trim());
+        if (cells.length < 3 || !REVIEW_LABEL_RE.test(cells[1]))
+            continue;
+        const m = cells.slice(2).join(' ').match(ISO_DATE_RE);
+        if (m !== null)
+            return m[0];
+    }
+    return null;
+}
+// --- buildMaintainReport --------------------------------------------------------
+export async function buildMaintainReport(input, opts = {}) {
+    const now = opts.now ?? new Date();
+    const topN = opts.topN ?? DEFAULT_TOP_N;
+    const deep = opts.deep ?? false;
+    if (deep && opts.readBody === undefined) {
+        throw new TypeError('buildMaintainReport: deep:true requires a readBody dependency');
+    }
+    const kept = input.rows.filter((r) => !isInternalPath(r.path));
+    const paths = [...new Set(kept.map((r) => r.path))].sort(cmpStr);
+    const perLocale = {};
+    for (const r of kept)
+        perLocale[r.locale] = (perLocale[r.locale] ?? 0) + 1;
+    const localeCount = new Map();
+    for (const r of kept)
+        localeCount.set(r.path, (localeCount.get(r.path) ?? 0) + 1);
+    let redirects = { available: false, count: 0, stubs: [] };
+    let freshness = null;
+    if (deep && opts.readBody !== undefined) {
+        const readBody = opts.readBody;
+        const stubs = [];
+        const missing = [];
+        const expired = [];
+        let scanned = 0;
+        let unreadable = 0;
+        for (const r of kept) {
+            const body = await readBody(r.path, r.locale);
+            if (body === null) {
+                unreadable += 1;
+                continue;
+            }
+            scanned += 1;
+            const firstLine = body.split('\n').find((l) => l.trim() !== '');
+            if (firstLine !== undefined && REDIRECT_RE.test(firstLine.trim())) {
+                stubs.push({ path: r.path, locale: r.locale, target: firstLine.trim().replace(REDIRECT_RE, '').trim() });
+                continue; // stubs are pointers — exempt from the freshness-stamp rule
+            }
+            const genre = classifyGenre({ title: r.title, body }).genre;
+            if (!FRESHNESS_GENRES.includes(genre))
+                continue;
+            if (!STAMP_RE.test(body))
+                missing.push({ path: r.path, locale: r.locale, genre });
+            const reviewBy = reviewByOf(body);
+            if (reviewBy !== null) {
+                const t = Date.parse(reviewBy);
+                if (!Number.isNaN(t) && t < now.getTime()) {
+                    expired.push({ path: r.path, locale: r.locale, reviewBy, daysExpired: Math.floor((now.getTime() - t) / DAY_MS) });
+                }
+            }
+        }
+        redirects = { available: true, count: stubs.length, stubs };
+        freshness = { scanned, unreadable, missingLastVerified: missing, expiredReviewBy: expired };
+    }
+    return {
+        schema: MAINTAIN_SCHEMA,
+        generatedAt: now.toISOString(),
+        rowCount: input.rows.length,
+        mapGeneratedAt: input.mapGeneratedAt ?? null,
+        mapStaleSeconds: input.mapStaleSeconds ?? null,
+        deep,
+        pages: {
+            rows: kept.length,
+            paths: paths.length,
+            perLocale,
+            missingTwinPaths: paths.filter((p) => localeCount.get(p) === 1),
+        },
+        duplicates: { threshold: DUP_TITLE_THRESHOLD, clusters: findDuplicates(kept) },
+        staleness: { topN, oldest: staleness(kept, now, topN) },
+        diffusion: { singleChildDirs: singleChildDirs(paths) },
+        rootOrphans: rootOrphans(paths),
+        tags: tagVocab(kept),
+        redirects,
+        sections: sectionDist(kept),
+        freshness,
+    };
+}
+// --- renderMaintainMarkdown -----------------------------------------------------
+const fmt = (n) => String(n);
+/** Human report + (always) a fenced machine-readable JSON block at the END —
+ *  the same MaintainReport object the tool envelope carries. */
+export function renderMaintainMarkdown(r) {
+    const L = [];
+    L.push(`# Maintain Report (${r.deep ? 'deep' : 'light'})`, '');
+    L.push(`> Generated ${r.generatedAt} · ${fmt(r.rowCount)} map rows · ` +
+        `map snapshot ${r.mapGeneratedAt ?? 'live build'}` +
+        `${r.mapStaleSeconds === null ? '' : ` · stale ${fmt(r.mapStaleSeconds)}s`}`, '');
+    L.push('## Pages & twins', '');
+    L.push(`- ${fmt(r.pages.rows)} kept rows / ${fmt(r.pages.paths)} paths (${Object.entries(r.pages.perLocale)
+        .map(([l, n]) => `${l}:${fmt(n)}`)
+        .join(' ')})`);
+    L.push(`- twin gap — paths missing one locale (${fmt(r.pages.missingTwinPaths.length)}):`);
+    for (const p of r.pages.missingTwinPaths)
+        L.push(`  - \`${p}\``);
+    L.push('', `## Near-duplicate title clusters (threshold ${r.duplicates.threshold})`, '');
+    if (r.duplicates.clusters.length === 0)
+        L.push('- none');
+    r.duplicates.clusters.forEach((c, i) => {
+        L.push(`${i + 1}. ${c.titles.map((t) => `"${t}"`).join(' ≡ ')}`);
+        for (const p of c.paths)
+            L.push(`   - \`${p}\``);
+    });
+    L.push('', `## Staleness — oldest ${fmt(r.staleness.topN)} paths`, '');
+    L.push('| Path | Updated | Days old | Locales |', '| --- | --- | --- | --- |');
+    for (const s of r.staleness.oldest) {
+        L.push(`| \`${s.path}\` | ${s.updatedAt.slice(0, 10)} | ${fmt(s.daysOld)} | ${s.locales.join(',')} |`);
+    }
+    L.push('', '## Diffusion candidates', '');
+    L.push('- single-child dirs (upmerge candidates):');
+    if (r.diffusion.singleChildDirs.length === 0)
+        L.push('  - none');
+    for (const d of r.diffusion.singleChildDirs)
+        L.push(`  - \`${d.dir}/\` holds only \`${d.childPath}\``);
+    L.push('- root-level orphans (depth-2 pages, no sub-shelf):');
+    if (r.rootOrphans.length === 0)
+        L.push('  - none');
+    for (const o of r.rootOrphans)
+        L.push(`  - \`${o.section}/\` (${fmt(o.paths.length)}): ${o.paths.map((p) => `\`${p}\``).join(', ')}`);
+    L.push('', '## Tag vocabulary', '');
+    if (!r.tags.available)
+        L.push('- no tag data: rows carry no tags (light mode over a tagless mirror) — refresh or pass list-joined rows');
+    else {
+        L.push('| Tag | Count |', '| --- | --- |');
+        for (const t of r.tags.vocabulary)
+            L.push(`| ${t.tag} | ${fmt(t.count)} |`);
+    }
+    L.push('', '## Redirect stubs', '');
+    if (!r.redirects.available)
+        L.push('- not visible from map rows (bodies unread) — rerun with `deep:true` to count `> Redirect:` stubs');
+    else {
+        L.push(`- ${fmt(r.redirects.count)} stub(s)`);
+        for (const s of r.redirects.stubs)
+            L.push(`  - \`${s.path}\` (${s.locale}) → ${s.target}`);
+    }
+    L.push('', '## Section distribution', '');
+    L.push('| Section | Paths | Rows |', '| --- | --- | --- |');
+    for (const s of r.sections)
+        L.push(`| ${s.section} | ${fmt(s.paths)} | ${fmt(s.rows)} |`);
+    if (r.freshness !== null) {
+        L.push('', '## Freshness (deep)', '');
+        L.push(`- scanned ${fmt(r.freshness.scanned)} bodies (${fmt(r.freshness.unreadable)} unreadable) · ` +
+            `missing 上次核实 stamp: ${fmt(r.freshness.missingLastVerified.length)} · expired review-by: ${fmt(r.freshness.expiredReviewBy.length)}`);
+        for (const m of r.freshness.missingLastVerified)
+            L.push(`  - stamp missing: \`${m.path}\` (${m.locale}, ${m.genre})`);
+        for (const e of r.freshness.expiredReviewBy)
+            L.push(`  - review overdue: \`${e.path}\` (${e.locale}) since ${e.reviewBy} (${fmt(e.daysExpired)}d)`);
+    }
+    L.push('', '## Machine-readable JSON', '', '```json', JSON.stringify(r, null, 2), '```', '');
+    return L.join('\n');
+}

package/dist/map.d.ts

@@ -1,6 +1,12 @@
 /**
  * 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.
+ *
+ * Intended readers: harness cache-read scripts, the admin UI, and
+ * remote/cross-machine review. Role split — live queries (getMap) read the
+ * LOCAL MIRROR (historian-map.json) only and never this wiki page; the wiki
+ * page exists as the audit ledger (each refresh commits a new revision) and
+ * for human inspection.
  */
 import type { HistorianOptions } from './config.js';
 import type { GqlClient } from './wiki/client.js';
@@ -40,7 +46,7 @@ export declare function mirrorPath(home: string): string;
  *  namespace pages are excluded — they are not anonymously reachable), twins
  *  paired by exact path, rows sorted by path then locale. */
 export declare function buildPageMap(deps: MapDeps): Promise<PageMap>;
-export declare function renderMapMarkdown(rows: readonly MapRow[]): string;
+export declare function renderMapMarkdown(rows: readonly MapRow[], generatedAt: string): string;
 export interface RefreshOptions {
     readonly now?: Date;
     readonly homeDir?: string;

package/dist/map.js

@@ -1,6 +1,12 @@
 /**
  * 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.
+ *
+ * Intended readers: harness cache-read scripts, the admin UI, and
+ * remote/cross-machine review. Role split — live queries (getMap) read the
+ * LOCAL MIRROR (historian-map.json) only and never this wiki page; the wiki
+ * page exists as the audit ledger (each refresh commits a new revision) and
+ * for human inspection.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -89,9 +95,17 @@ export async function buildPageMap(deps) {
     return { rows, stats: { rows: rows.length, paths: sortedPaths.length, perLocale: perLocaleCounts, missingTwinPaths } };
 }
 // --- renderMapMarkdown ------------------------------------------------------
-export function renderMapMarkdown(rows) {
+export function renderMapMarkdown(rows, generatedAt) {
+    const perLocale = { en: 0, zh: 0 };
+    for (const r of rows)
+        if (r.locale === 'en' || r.locale === 'zh')
+            perLocale[r.locale] += 1;
+    const preamble = `> Snapshot generated ${generatedAt} · ${rows.length} pages (${perLocale.en}/${perLocale.zh}). ` +
+        `This page is the audit ledger: each 'historian_map refresh' commits a new wiki revision (page ` +
+        `history = chronological record of the whole wiki). Live queries read the local mirror ` +
+        `(historian-map.json); this page serves harness audits, the admin UI, and cross-machine review.`;
     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');
+    return [preamble, '', HEADER_ROW, '| --- | --- | --- | --- | --- | --- | --- |', ...lines, ''].join('\n');
 }
 // --- Local mirror -----------------------------------------------------------
 function writeMirror(home, mirror) {
@@ -159,7 +173,7 @@ export async function refreshMapCache(deps, opts) {
     const home = opts?.homeDir ?? homedir();
     const { rows, stats } = await buildPageMap(deps);
     writeMirror(home, { generatedAt: now.toISOString(), rows, stats });
-    const markdown = renderMapMarkdown(rows);
+    const markdown = renderMapMarkdown(rows, now.toISOString());
     const existing = await readPage(deps.client, CACHE_PATH, 'en');
     if (existing === null) {
         await createPage(deps, {

package/dist/migrate-score.d.ts

@@ -21,7 +21,8 @@ export interface ChecklistVerdict {
 /** 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). */
+ *  (last-verified column, verification commands, table-not-prose) and G6
+ *  pages the how-to variants (goal-titled H1, step triples, freshness rows). */
 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. */

package/dist/migrate-score.js

@@ -198,10 +198,63 @@ function scoreG5Item6(draft) {
         note: pass ? undefined : `narrative lines (${narrative}) outnumber table lines (${tableLines}) — a ledger is status + tables, not prose`,
     };
 }
+// --- G6 how-to scorers (selfReviewChecklist G6 variants of items 4-6) --------
+const G6_GOAL_H1 = /(?:如何|怎么|怎样|how\s+to)/i;
+const G6_STEPS_HEADING = /^#{2,3}\s.*(?:操作步骤|\bsteps\b)/i;
+function stepsSectionOf(draft) {
+    const lines = draft.split('\n');
+    const start = lines.findIndex((l) => /^#{2,3}\s/.test(l) && G6_STEPS_HEADING.test(l));
+    if (start === -1)
+        return undefined;
+    const end = lines.findIndex((l, i) => i > start && /^#{1,3}\s/.test(l));
+    return lines.slice(start + 1, end === -1 ? lines.length : end).join('\n');
+}
+function scoreG6Item4(draft) {
+    const h1 = draft.split('\n').find((l) => /^#\s/.test(l)) ?? '';
+    const pass = G6_GOAL_H1.test(h1);
+    return {
+        id: 4,
+        verdict: pass ? 'pass' : 'fail',
+        note: pass ? undefined : `H1 is not goal-titled ("How to X" / "如何(怎么)做X"): "${h1.replace(/^#\s*/, '').slice(0, 40)}"`,
+    };
+}
+function scoreG6Item5(draft) {
+    const section = stepsSectionOf(draft);
+    if (section === undefined) {
+        return { id: 5, verdict: 'fail', note: 'no 操作步骤/Steps section' };
+    }
+    const numbered = /^\s*1[.、]/m.test(section);
+    const expected = /(预期|expected)/i.test(section);
+    const failure = /(失败|on failure|fallback)/i.test(section);
+    const pass = numbered && expected && failure;
+    return {
+        id: 5,
+        verdict: pass ? 'pass' : 'fail',
+        note: pass ? undefined : `steps section lacks ${numbered ? '' : 'numbered items '}${expected ? '' : 'expected-result leg '}${failure ? '' : 'on-failure leg '}`.trim(),
+    };
+}
+function scoreG6Item6(draft) {
+    const verified = /(上次核实|last verified)/i.test(draft);
+    const review = /(复核周期|review[- ]by|cadence)/i.test(draft);
+    const pass = verified && review;
+    return {
+        id: 6,
+        verdict: pass ? 'pass' : 'fail',
+        note: pass ? undefined : `metadata table lacks ${verified ? '' : 'last-verified (上次核实) '}${review ? '' : 'review-by (复核周期)'}row(s)`,
+    };
+}
+/** Items 4-6 genre variants: G5 ledgers and G6 how-tos swap in their own
+ *  gates; every other genre keeps the base trio. */
+const GENRE_SCORERS = {
+    G5: [scoreG5Item4, scoreG5Item5, scoreG5Item6],
+    G6: [scoreG6Item4, scoreG6Item5, scoreG6Item6],
+};
+const BASE_SCORERS = [scoreItem4, scoreItem5, scoreItem6];
 /** 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). */
+ *  (last-verified column, verification commands, table-not-prose) and G6
+ *  pages the how-to variants (goal-titled H1, step triples, freshness rows). */
 export function scoreChecklist(genre, draft) {
     const items = selfReviewChecklist(genre);
     const na = (item) => ({
@@ -214,16 +267,16 @@ export function scoreChecklist(genre, draft) {
         verdict: 'deferred',
         note: 'post-write item — score after apply and write into the pilot report',
     });
-    const ledger = genre === 'G5';
+    const [score4, score5, score6] = GENRE_SCORERS[genre] ?? BASE_SCORERS;
     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 4: return applies ? score4(draft) : na(item);
+            case 5: return applies ? score5(draft) : na(item);
+            case 6: return applies ? score6(draft) : na(item);
             case 7: return scoreItem7(draft);
             case 8: return scoreItem8(draft);
             default: return deferred(item);

package/dist/templates/evidence.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Machine-tier evidence page skeleton (v3 todo 5).
+ *
+ * Evidence pages live under the internal namespaces (`_meta/`, `_evidence/`),
+ * are hidden and monolingual — the wiki is their only store (no local mirror,
+ * no bilingual twin machinery). They are deliberately NOT genre-templated:
+ * the G1–G5 anatomy rubric targets human front pages, while an evidence page
+ * is a verbatim capture plus provenance, and nothing else.
+ *
+ * The shape mirrors the `_meta/page-map` cache precedent (src/map.ts): header
+ * blockquote with source/captured/context metadata, an empty fenced block the
+ * caller fills with the raw material verbatim, and a capture-context section
+ * whose three placeholder lines the caller replaces at capture time.
+ */
+export interface EvidenceSkeletonInput {
+    /** Path of the human page this evidence backs (placeholder hint when unknown). */
+    readonly sourcePath: string;
+    /** URL of that human page. */
+    readonly sourceUrl: string;
+    /** ISO-8601 capture timestamp, supplied by the caller (pure function: no clock reads). */
+    readonly capturedAt: string;
+    /** One-line context for why this material was captured. */
+    readonly context: string;
+}
+/** Full markdown skeleton for one machine-tier evidence page. Pure string
+ *  transform — deterministic, no state, no I/O; empty inputs degrade to
+ *  visible placeholders, never `undefined` leakage. */
+export declare function evidenceSkeleton(o: EvidenceSkeletonInput): string;

package/dist/templates/evidence.js

@@ -0,0 +1,34 @@
+/**
+ * Machine-tier evidence page skeleton (v3 todo 5).
+ *
+ * Evidence pages live under the internal namespaces (`_meta/`, `_evidence/`),
+ * are hidden and monolingual — the wiki is their only store (no local mirror,
+ * no bilingual twin machinery). They are deliberately NOT genre-templated:
+ * the G1–G5 anatomy rubric targets human front pages, while an evidence page
+ * is a verbatim capture plus provenance, and nothing else.
+ *
+ * The shape mirrors the `_meta/page-map` cache precedent (src/map.ts): header
+ * blockquote with source/captured/context metadata, an empty fenced block the
+ * caller fills with the raw material verbatim, and a capture-context section
+ * whose three placeholder lines the caller replaces at capture time.
+ */
+/** Full markdown skeleton for one machine-tier evidence page. Pure string
+ *  transform — deterministic, no state, no I/O; empty inputs degrade to
+ *  visible placeholders, never `undefined` leakage. */
+export function evidenceSkeleton(o) {
+    return [
+        `> 机器层证据页 (machine-tier evidence). 来源页 (source): [${o.sourcePath}](${o.sourceUrl})` +
+            ` · 采集 (captured): ${o.capturedAt} · 上下文 (context): ${o.context}`,
+        '',
+        '## 原文 (verbatim)',
+        '',
+        '```',
+        '```',
+        '',
+        '## 采集环境 (capture context)',
+        '',
+        '- 命令 (command): `<the exact command as executed>`',
+        '- 目录 (cwd): `<working directory at capture time>`',
+        '- 时间 (time): `<capture timestamp>`',
+    ].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;
 }