opencode-wiki-historian 0.3.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/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/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

@@ -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;

package/dist/templates/skeletons.js

@@ -556,3 +556,104 @@ export const G5_EN = `# Page Title (placeholder: replace with the real title, mu
 ## Related Pages
 
 <!-- List the real page paths that link here and back. Event histories go in G1 pages, cited in Evidence. -->`;
+/** 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 const G6_ZH = `# 如何做某事（占位：目标句式标题，须与页面 title 一致）
+
+**状态/Status**: Active <!-- or Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
+
+**本页回答：** 如何完成某事（占位：写明具体目标）
+
+> **提示**
+> 操作手册面向带着目标来的读者：步骤可复制、可执行、可核对。
+> 原理写 G4 概念页，命令清单写 G3 页，从相关页面链过来。
+{.is-info}
+
+## 目标
+
+<!-- 1–2 句：完成后读者得到什么结果。成功判据须可观察。 -->
+
+## 前置条件
+
+<!-- 权限、版本、依赖、环境变量逐项列出。每项须能当场自检。 -->
+
+| 条件 | 检查方法 | 预期结果 |
+| --- | --- | --- |
+| example-service 可达 | \`curl -s http://example.com:8000/health\` | HTTP 200 |
+
+## 操作步骤
+
+<!-- 编号步骤，每步三段：动作、预期结果、失败处置。命令须可直接复制。 -->
+
+1. **动作**：<!-- 做什么或运行哪条命令。 -->
+   **预期结果**：<!-- 正常时看到的输出或状态。 -->
+   **失败处置**：<!-- 未达预期时的补救，或链向 G1/G4 页。 -->
+
+## 回退
+
+<!-- 出错后如何恢复原状：撤销命令、备份位置。不可逆操作须前置警告。 -->
+
+## 元数据表
+
+| 元数据 | 值 |
+| --- | --- |
+| 状态 | <!-- Active / Superseded-by: <path> / Deprecated --> |
+| 上次核实 | <!-- YYYY-MM-DD，在哪套环境按本页步骤重跑过 --> |
+| 复核周期 | <!-- 如每 90 天，到期重跑本页步骤 --> |
+| 被取代于 | <!-- 新手册路径，无则填 — --> |
+| 来源类型 | <!-- human / agent / imported --> |
+
+## 相关页面
+
+<!-- 列出互链的真实页面路径。原理在 G4，清单在 G3，事故史在 G1。 -->`;
+/** 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
+
+**This page answers:** how to finish one concrete task (placeholder: name the goal)
+
+> **Tip**
+> A how-to serves readers who arrive with a goal: steps are copy-pasteable and checkable.
+> Concepts belong in G4 pages, raw command lists in G3 pages, linked under Related Pages.
+{.is-info}
+
+## Goal
+
+<!-- One or two sentences: the outcome the reader gets. State an observable success test. -->
+
+## Prerequisites
+
+<!-- Permissions, versions, dependencies, env vars: one row each. Every row must be self-checkable. -->
+
+| Condition | Check | Expected |
+| --- | --- | --- |
+| example-service reachable | \`curl -s http://example.com:8000/health\` | HTTP 200 |
+
+## Steps
+
+<!-- Numbered steps, three legs per step: action, expected result, on failure. Commands must be copy-pasteable. -->
+
+1. **Action**: <!-- what to run or change. -->
+   **Expected result**: <!-- the output or state that proves success. -->
+   **On failure**: <!-- the fix, or a link to the G1/G4 page. -->
+
+## Rollback
+
+<!-- How to restore the prior state: revert commands, backup locations. Warn before any irreversible step. -->
+
+## Metadata
+
+| Field | Value |
+| --- | --- |
+| Status | <!-- Active / Superseded-by: <path> / Deprecated --> |
+| Last verified | <!-- YYYY-MM-DD and the environment the steps were re-run in --> |
+| Review by | <!-- e.g. every 90 days; re-run the steps when due --> |
+| Superseded by | <!-- path of the newer manual, or — --> |
+| Source kind | <!-- human / agent / imported --> |
+
+## Related Pages
+
+<!-- Real page paths that link here and back. Why-it-works lives in G4, checklists in G3, incidents in G1. -->`;