opencode-wiki-historian 0.3.0 → 0.4.0

package/dist/tools/create.js

@@ -7,16 +7,16 @@
 import { tool } from '@opencode-ai/plugin';
 import { validatePath } from '../wiki/locale.js';
 import { createPage } from '../wiki/pages.js';
-import { classifyGenre, genreSkeleton } from '../templates/genres.js';
+import { listPages, readPage } from '../wiki/pages.read.js';
+import { classifyGenre, genreSkeleton, GENRES } from '../templates/genres.js';
 import { evidenceSkeleton } from '../templates/evidence.js';
-import { enforceTierPath, errEnvelope, frontDumpAdvisory, MACHINE_TIER_NOTE, okJson, pageDeps, tierMismatchJson, TIERS, urlPair, URL_MANDATE, } from './shared.js';
+import { checklistAdvisory, collisionAdvisory, enforceTierPath, errEnvelope, frontDumpAdvisory, MACHINE_TIER_NOTE, okJson, pageDeps, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, } from './shared.js';
 const s = tool.schema;
-const GENRES = ['G1', 'G2', 'G3', 'G4', 'G5'];
 const ARGS_SHAPE = {
     path: s.string().describe('Wiki path, e.g. docs/guides/foo (first segment must NOT look like a locale code)'),
     title: s.string().describe('Page title'),
     content: s.string().optional().describe('Page body (markdown). ABSENT → local template mode, nothing written'),
-    genre: s.enum(GENRES).optional().describe('Genre hint: G1..G5 (template mode / classification)'),
+    genre: s.enum(GENRES).optional().describe('Genre hint: G1..G6 (template mode / classification)'),
     locale: s.enum(['en', 'zh']).default('en'),
     isPublished: s.boolean().default(true),
     tags: s.array(s.string()).default([]),
@@ -25,6 +25,28 @@ const ARGS_SHAPE = {
     tier: s.enum(TIERS).default('front').describe('front = bilingual human page; evidence = machine page under _meta/ or _evidence/ (hidden, unpublished, monolingual en)'),
 };
 const ArgsSchema = s.object(ARGS_SHAPE);
+/** Best-effort collision advice for the content branch: read-only pre-checks
+ *  whose every failure is SWALLOWED — the write proceeds with no advice
+ *  rather than being blocked or errored by the adviser itself (the
+ *  "hint, never throw" precedent above). */
+async function collisionAdvice(deps, probe) {
+    const client = deps.getClient();
+    let exists = false;
+    try {
+        exists = (await readPage(client, probe.path, probe.locale)) !== null;
+    }
+    catch {
+        /* failed existence read → assume absence: never advise on unknowns */
+    }
+    let inventory = [];
+    try {
+        inventory = await listPages(client);
+    }
+    catch {
+        /* failed inventory read → no duplicate advice */
+    }
+    return collisionAdvisory({ ...probe, exists, inventory });
+}
 export function makeCreateTool(deps) {
     return tool({
         description: `Create a wiki page: primary locale content plus an optional auto-translated twin. ` +
@@ -40,6 +62,9 @@ export function makeCreateTool(deps) {
             catch (err) {
                 return errEnvelope(err);
             }
+            const offSections = sectionRefusalJson(args.path, deps.options.sections);
+            if (offSections !== null)
+                return offSections;
             const mismatch = enforceTierPath(tier, args.path);
             if (mismatch !== null)
                 return tierMismatchJson(mismatch);
@@ -50,6 +75,10 @@ export function makeCreateTool(deps) {
             const localeHint = isEvidence && args.locale === 'zh'
                 ? 'evidence pages are monolingual en — the locale argument was forced to "en"'
                 : undefined;
+            // Genre is resolved ONCE, above the template/content fork (v4 todo 4):
+            // the template branch feeds it the skeleton, the content branch the
+            // pre-write checklist gate. Explicit arg wins over classification.
+            const genre = args.genre ?? classifyGenre({ title: args.title, body: args.description ?? '' }).genre;
             if (args.content === undefined || args.content.trim() === '') {
                 if (isEvidence) {
                     // Evidence pages are not genre-templated: echo the machine skeleton.
@@ -70,7 +99,6 @@ export function makeCreateTool(deps) {
                         ...(localeHint === undefined ? {} : { localeHint }),
                     });
                 }
-                const genre = args.genre ?? classifyGenre({ title: args.title, body: args.description ?? '' }).genre;
                 return okJson({
                     mode: 'template',
                     genre,
@@ -81,6 +109,13 @@ export function makeCreateTool(deps) {
                 });
             }
             try {
+                const collision = await collisionAdvice(deps, {
+                    tier,
+                    path: args.path,
+                    locale,
+                    title: args.title,
+                    baseUrl: deps.options.baseUrl,
+                });
                 const result = await createPage(pageDeps(deps), {
                     path: args.path,
                     locale,
@@ -92,7 +127,12 @@ export function makeCreateTool(deps) {
                     twin: isEvidence ? false : args.twin,
                     description: args.description,
                 });
-                const advisory = frontDumpAdvisory(tier, args.content);
+                const advisories = [
+                    frontDumpAdvisory(tier, args.content),
+                    collision,
+                    // Evidence raw material is not a genre page — the gate is front-only.
+                    isEvidence ? null : checklistAdvisory(genre, args.content),
+                ].filter((a) => a !== null);
                 return okJson({
                     mode: 'create',
                     path: args.path,
@@ -104,7 +144,7 @@ export function makeCreateTool(deps) {
                     urls: urlPair(result),
                     ...(isEvidence ? { note: MACHINE_TIER_NOTE } : {}),
                     ...(localeHint === undefined ? {} : { localeHint }),
-                    ...(advisory === null ? {} : { advisory }),
+                    ...(advisories.length === 0 ? {} : { advisory: advisories.join('\n') }),
                 });
             }
             catch (err) {

package/dist/tools/local.js

@@ -8,6 +8,9 @@ import { tool } from '@opencode-ai/plugin';
 import { TranslateError } from '../translate.js';
 import { buildChronology, filterRowsByPath } from '../chronology.js';
 import { getMap, refreshMapCache, CACHE_PATH } from '../map.js';
+import { buildMaintainReport, renderMaintainMarkdown } from '../maintain.js';
+import { normalizeLocale, PathValidationError } from '../wiki/locale.js';
+import { listPages, readPage } from '../wiki/pages.read.js';
 import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
 const s = tool.schema;
 const TRANSLATE_ARGS = {
@@ -53,11 +56,50 @@ export function makeTranslateSnippetTool(deps) {
     });
 }
 const MAP_ARGS = {
-    action: s.enum(['show', 'refresh', 'timeline']).default('show'),
+    action: s.enum(['show', 'refresh', 'timeline', 'maintain']).default('show'),
     days: s.number().int().positive().optional().describe('timeline: keep only rows updated within the last N days'),
     path: s.string().optional().describe('timeline: section/path prefix filter (e.g. ops)'),
+    deep: s.boolean().optional().describe('maintain: additionally read every page body (freshness stamps + redirect stubs) — one bounded read per row'),
 };
 const MapArgsSchema = s.object(MAP_ARGS);
+/** maintain: light tier is map rows + ONE read-only pages.list pass per locale
+ *  (the mirror's MapRow carries no tags; the list join restores the vocab view);
+ *  deep additionally reads each body via readPage. Reserved-path pages (e.g.
+ *  'home', probe p1) answer null instead of killing the sweep. Read-only. */
+async function runMaintain(deps, mapDeps, snapshot, deep) {
+    const client = deps.getClient();
+    const tagIndex = new Map();
+    const locales = [...new Set(deps.options.locales.map(normalizeLocale))].sort();
+    for (const locale of locales) {
+        for (const item of await listPages(client, { locale })) {
+            tagIndex.set(`${item.locale}\u0000${item.path}`, item.tags);
+        }
+    }
+    const rows = snapshot.rows.map((r) => ({ ...r, tags: tagIndex.get(`${r.locale}\u0000${r.path}`) ?? [] }));
+    const readBody = deep
+        ? async (path, locale) => {
+            try {
+                return (await readPage(client, path, locale))?.content ?? null;
+            }
+            catch (err) {
+                // Unreadable page (invalid path / transport) is a scan miss, not a report failure.
+                if (err instanceof PathValidationError)
+                    return null;
+                throw err;
+            }
+        }
+        : undefined;
+    const report = await buildMaintainReport({ rows, mapGeneratedAt: snapshot.generatedAt, mapStaleSeconds: snapshot.staleSeconds }, { deep, readBody });
+    return {
+        action: 'maintain',
+        deep: report.deep,
+        generatedAt: report.generatedAt,
+        rowCount: report.rowCount,
+        report,
+        markdown: renderMaintainMarkdown(report),
+        urls: reportUrls(deps.options.baseUrl, CACHE_PATH, 'en'),
+    };
+}
 // --- historian_map -----------------------------------------------------------
 export function makeMapTool(deps) {
     return tool({
@@ -67,7 +109,9 @@ export function makeMapTool(deps) {
             `show reads the local mirror (zero writes); refresh rebuilds from the wiki and writes the mirror + cache page ` +
             `(idempotent — the engine upserts via full RMW); timeline groups mirror rows by ISO week (newest first, ` +
             `optional days window + section/path prefix filter) into a human markdown table + machine-readable weeks JSON. ` +
-            `${URL_MANDATE}.`,
+            `maintain runs the read-only curation sweep (twin gap, near-duplicate titles, staleness, diffusion/orphan ` +
+            `candidates, tag vocab, section distribution; deep:true adds per-body freshness stamps + redirect stubs) and ` +
+            `answers a markdown report with a stable-key JSON tail. ${URL_MANDATE}.`,
         args: MAP_ARGS,
         execute: async (raw) => {
             const args = MapArgsSchema.parse(raw);
@@ -92,6 +136,9 @@ export function makeMapTool(deps) {
                         urls: reportUrls(deps.options.baseUrl, CACHE_PATH, 'en'),
                     });
                 }
+                if (args.action === 'maintain') {
+                    return okJson(await runMaintain(deps, mapDeps, snapshot, args.deep ?? false));
+                }
                 return okJson({
                     action: 'show',
                     generatedAt: snapshot.generatedAt,

package/dist/tools/mutate.js

@@ -6,12 +6,11 @@
  */
 import { tool } from '@opencode-ai/plugin';
 import { deletePage, movePage } from '../wiki/pages.js';
-import { selfReviewChecklist } from '../templates/genres.js';
-import { confirmRequiredJson, errEnvelope, okJson, urlPair, URL_MANDATE, pageDeps } from './shared.js';
+import { GENRES, selfReviewChecklist } from '../templates/genres.js';
+import { confirmRequiredJson, errEnvelope, okJson, sectionRefusalJson, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
 import { reformatPageDraft } from '../migrate.js';
 import { applyMigration } from '../migrate-apply.js';
 const s = tool.schema;
-const GENRES = ['G1', 'G2', 'G3', 'G4', 'G5'];
 const DELETE_ARGS = {
     path: s.string(),
     locale: s.enum(['en', 'zh']).default('en'),
@@ -28,6 +27,9 @@ export function makeDeleteTool(deps) {
             const args = DeleteArgsSchema.parse(raw);
             if (args.confirm !== 'yes')
                 return confirmRequiredJson('historian_delete', args.confirm);
+            const offSections = sectionRefusalJson(args.path, deps.options.sections);
+            if (offSections !== null)
+                return offSections;
             try {
                 const result = await deletePage(pageDeps(deps), args.path, args.locale, 'yes');
                 return okJson({
@@ -62,6 +64,11 @@ export function makeMoveTool(deps) {
             const args = MoveArgsSchema.parse(raw);
             if (args.confirm !== 'yes')
                 return confirmRequiredJson('historian_move', args.confirm);
+            // The allow-list guards the DESTINATION (the write target); the source
+            // page may legally live somewhere the new configuration no longer admits.
+            const offSections = sectionRefusalJson(args.newPath, deps.options.sections);
+            if (offSections !== null)
+                return offSections;
             try {
                 const destLocale = args.newLocale ?? args.locale;
                 const result = await movePage(pageDeps(deps), args.path, args.locale, args.newPath, destLocale, 'yes');

package/dist/tools/read.js

@@ -5,7 +5,7 @@
  */
 import { tool } from '@opencode-ai/plugin';
 import { normalizeLocale } from '../wiki/locale.js';
-import { readPage, searchPages } from '../wiki/pages.js';
+import { listPages, readPage, searchPages } from '../wiki/pages.js';
 import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
 const s = tool.schema;
 const READ_ARGS = {
@@ -56,22 +56,89 @@ export function makeReadTool(deps) {
         },
     });
 }
+const TAG_MODES = ['any', 'all'];
 const SEARCH_ARGS = {
     query: s.string(),
     kind: s.enum(['title', 'content']).default('content').describe('Informational intent; the wiki index covers both title and content'),
+    tags: s
+        .array(s.string().min(1))
+        .min(1)
+        .max(5)
+        .refine((arr) => arr.every((t) => t.trim().length > 0), {
+        message: 'tags entries must be non-blank (whitespace-only rejected)',
+    })
+        .optional()
+        .describe('Filter to pages carrying these tags (1-5). tagsMode "all" (DEFAULT) = EVERY listed tag ' +
+        'must be present on the page — the server $tags mechanism is AND-only. tagsMode "any" = at ' +
+        'LEAST ONE tag matches (client-side per-tag fan-out + union). Entries are trimmed and ' +
+        'deduped; blank entries are rejected. Result rows include each page\'s tags so the agent ' +
+        'can see the live tag vocabulary.'),
+    tagsMode: s
+        .enum(TAG_MODES)
+        .default('all')
+        .describe('"all" (default): every tag must match (server-side AND, one request). "any": at least one tag (client-side union).'),
 };
 const SearchArgsSchema = s.object(SEARCH_ARGS);
+/** (path, locale) identity for union dedupe and query intersection. The NUL
+ *  separator cannot appear in a path or locale, so concatenation stays injective. */
+const matchKey = (path, locale) => `${locale}\u0000${path}`;
+/** Keys of the text-query result set, locale-normalized. Rows whose locale is
+ *  outside the en/zh whitelist never equal a list row (those are always en/zh),
+ *  so they simply cannot join the intersection. */
+function textKeysOf(resp) {
+    const keys = new Set();
+    for (const r of resp.results) {
+        try {
+            keys.add(matchKey(r.path, normalizeLocale(r.locale)));
+        }
+        catch {
+            /* unsupported locale — legacy mapper keeps the row with url:null; the tag
+               intersection just ignores it */
+        }
+    }
+    return keys;
+}
+/** tagsMode "any": one list call PER tag, unioned and deduped by (path, locale).
+ *  Resilience contract: a failed leg is dropped and named in `failed` — no new
+ *  error class surfaces while ≥1 leg survives; only when EVERY leg fails does
+ *  the original rejection propagate unchanged (standard error envelope). */
+async function unionByAnyTag(client, tags) {
+    const legs = await Promise.allSettled(tags.map((t) => listPages(client, { tags: [t] })));
+    const seen = new Set();
+    const rows = [];
+    const failures = [];
+    legs.forEach((leg, i) => {
+        if (leg.status === 'fulfilled') {
+            for (const row of leg.value) {
+                const k = matchKey(row.path, row.locale);
+                if (!seen.has(k)) {
+                    seen.add(k);
+                    rows.push(row);
+                }
+            }
+        }
+        else {
+            failures.push({ tag: tags[i], reason: leg.reason });
+        }
+    });
+    if (failures.length === tags.length)
+        throw failures[0].reason; // schema guarantees tags.length ≥ 1
+    return { rows, failed: failures.map((f) => f.tag) };
+}
 // --- historian_search --------------------------------------------------------
 export function makeSearchTool(deps) {
     return tool({
         description: `Full-text search over the wiki. kind is informational intent only — the live wiki.js ` +
             `search indexes title AND content (the engine signature is search(query, path, locale), no field scope). ` +
+            `Optional tags filter: tagsMode "all" (DEFAULT) requires EVERY tag on the page (server-side ` +
+            `AND); "any" matches AT LEAST ONE tag. Result rows carry each page's tags. ` +
             `Results carry their en/zh URLs. ${URL_MANDATE}.`,
         args: SEARCH_ARGS,
         execute: async (raw) => {
             const args = SearchArgsSchema.parse(raw);
             try {
-                const resp = await searchPages(deps.getClient(), args.query);
+                const client = deps.getClient();
+                const resp = await searchPages(client, args.query);
                 const results = resp.results.map((r) => {
                     try {
                         const locale = normalizeLocale(r.locale);
@@ -88,12 +155,53 @@ export function makeSearchTool(deps) {
                         return { id: r.id, title: r.title, description: r.description, path: r.path, locale: r.locale, url: null };
                     }
                 });
+                if (args.tags === undefined) {
+                    // Legacy path — no tags given, no tags keys leak into the envelope.
+                    return okJson({
+                        query: args.query,
+                        kind: args.kind,
+                        totalHits: resp.totalHits,
+                        suggestions: resp.suggestions,
+                        results,
+                    });
+                }
+                const wanted = [...new Set(args.tags.map((t) => t.trim()))];
+                let tagged;
+                let tagsFailed;
+                switch (args.tagsMode) {
+                    case 'all':
+                        // Straight passthrough: ONE request, the server's $tags AND mechanism.
+                        tagged = await listPages(client, { tags: wanted });
+                        tagsFailed = [];
+                        break;
+                    case 'any': {
+                        const union = await unionByAnyTag(client, wanted);
+                        tagged = union.rows;
+                        tagsFailed = union.failed;
+                        break;
+                    }
+                }
+                const textKeys = textKeysOf(resp);
+                const matched = tagged
+                    .filter((row) => textKeys.has(matchKey(row.path, row.locale)))
+                    .map((row) => ({
+                    id: row.id,
+                    title: row.title,
+                    description: row.description,
+                    path: row.path,
+                    locale: row.locale,
+                    url: reportUrls(deps.options.baseUrl, row.path, row.locale)[row.locale],
+                    tags: row.tags,
+                }));
                 return okJson({
                     query: args.query,
                     kind: args.kind,
-                    totalHits: resp.totalHits,
+                    tags: wanted,
+                    tagsMode: args.tagsMode,
+                    tagsFailed,
+                    totalHits: matched.length,
                     suggestions: resp.suggestions,
-                    results,
+                    results: matched,
                 });
             }
             catch (err) {

package/dist/tools/shared.d.ts

@@ -12,8 +12,9 @@ import type { ToolResult } from '@opencode-ai/plugin';
 import type { GqlClient } from '../wiki/client.js';
 import type { HistorianOptions } from '../config.js';
 import type { PageDeps } from '../wiki/pages.write.js';
-import type { TranslateFn, Locale } from '../wiki/pages.read.js';
+import type { TranslateFn, Locale, PageListItem } from '../wiki/pages.read.js';
 import { type LocalePair } from '../wiki/locale.js';
+import { type Genre } from '../templates/genres.js';
 /** Per-tool dependency bag; the client is a thunk so a bad key surface at
  *  buildTools time as nothing — only the first execution that touches the
  *  wiki resolves it (and then yields a ConfigError envelope, not a crash).
@@ -77,3 +78,51 @@ export declare function monolingualRefusalJson(toolName: string, argumentName: s
  *  fence at or under the limit). The advisory is informational only: every
  *  caller still performs the write. */
 export declare function frontDumpAdvisory(tier: Tier, content: string): string | null;
+export interface CollisionInput {
+    readonly tier: Tier;
+    readonly path: string;
+    readonly locale: Locale;
+    readonly title: string;
+    readonly baseUrl: string;
+    /** Exact-(path, locale) pre-read result. A FAILED read must pass false — a
+     *  transport hiccup never masquerades as a collision (the write proceeds
+     *  with no advice rather than with wrong advice). */
+    readonly exists: boolean;
+    /** listPages inventory snapshot; a failed listPages read yields [] → no
+     *  duplicate advice, only the (independent) path-existence line can fire. */
+    readonly inventory: readonly PageListItem[];
+}
+/** Advisory-only duplicate detector for historian_page_create:
+ *  (a) the exact target (path, locale) already exists → prefer
+ *      historian_page_update, with the page URL;
+ *  (b) the same normalized title lives on a DIFFERENT non-machine path →
+ *      疑似重复 … 先读再写, with each path's URLs (first 3, then a count).
+ *  Pure over its inputs and advisory-only: it NEVER throws and NEVER blocks —
+ *  a same-path other-locale twin is not a duplicate, evidence-tier writes skip
+ *  (b) (raw-material pages legitimately echo human titles), and machine
+ *  namespaces (_meta/, _evidence/) never surface as duplicates. */
+export declare function collisionAdvisory(input: CollisionInput): string | null;
+/**
+ * Pre-write self-check advisory (plan todo 4): score the draft with the SAME
+ * 10-item gate the migrate pipeline uses (scoreChecklist — no duplicated
+ * scoring logic), purely locally, zero network. 3+ failing items produce a
+ * hint naming them; items 9-10 are 'deferred' pre-write by the scorer's own
+ * contract (migrate-score.ts) and can never count as fail. Informational
+ * only — the write always proceeds; evidence tier is exempt (callers pass
+ * front only: raw material is not a genre page).
+ */
+export declare function checklistAdvisory(genre: Genre, draft: string): string | null;
+/** Config-level write refusal, paralleling PathValidationError's shape. The
+ *  class NAME is the routing key errEnvelope dispatches on: this shares the
+ *  'ConfigError' hint case with jsonc.ConfigError (which adds a code field
+ *  this pure path rule does not need). */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/** Pure allow-list check on a write target path: null = allowed, string =
+ *  refusal message. Empty/undefined allow-list = allow-all (the documented
+ *  default, config.ts HistorianOptions.sections). Match is segment-wise and
+ *  case-sensitive: section 'doc' authorizes 'doc' and 'doc/x', never 'docs/x'. */
+export declare function sectionGuard(path: string, allowedSections: readonly string[] | undefined): string | null;
+/** Guard + envelope in one step: null = proceed, ToolResult = refuse. */
+export declare function sectionRefusalJson(path: string, allowedSections: readonly string[] | undefined): ToolResult | null;

package/dist/tools/shared.js

@@ -9,6 +9,8 @@
  * here.
  */
 import { assertLocalePair, PathValidationError } from '../wiki/locale.js';
+import { scoreChecklist } from '../migrate-score.js';
+import { selfReviewChecklist } from '../templates/genres.js';
 /** Engine deps for one operation; client resolved lazily at use time. */
 export function pageDeps(deps) {
     return { client: deps.getClient(), options: deps.options, translate: deps.translate };
@@ -185,3 +187,120 @@ export function frontDumpAdvisory(tier, content) {
     return (`content contains a ${lines}-line fenced block; per contract, move raw material to a ` +
         `tier:"evidence" page under _evidence/ and link it from the human page (SYN-16)`);
 }
+// --- Create-path collision advisory (v4 todo 3) --------------------------------
+/** Title equality for duplicate detection: trim, collapse internal whitespace,
+ *  casefold — 'LLM Eval' == ' llm\neval '. */
+function normalizeTitle(title) {
+    return title.trim().replace(/\s+/gu, ' ').toLocaleLowerCase();
+}
+/** Number of duplicate paths shown verbatim before the overflow count. */
+const COLLISION_DUPE_DISPLAY_LIMIT = 3;
+/** Advisory-only duplicate detector for historian_page_create:
+ *  (a) the exact target (path, locale) already exists → prefer
+ *      historian_page_update, with the page URL;
+ *  (b) the same normalized title lives on a DIFFERENT non-machine path →
+ *      疑似重复 … 先读再写, with each path's URLs (first 3, then a count).
+ *  Pure over its inputs and advisory-only: it NEVER throws and NEVER blocks —
+ *  a same-path other-locale twin is not a duplicate, evidence-tier writes skip
+ *  (b) (raw-material pages legitimately echo human titles), and machine
+ *  namespaces (_meta/, _evidence/) never surface as duplicates. */
+export function collisionAdvisory(input) {
+    const parts = [];
+    if (input.exists) {
+        const urls = reportUrls(input.baseUrl, input.path, input.locale);
+        parts.push(`path exists — '${input.path}' (${input.locale}) already holds a page; ` +
+            `prefer historian_page_update to amend it; ${urls[input.locale]}`);
+    }
+    const norm = normalizeTitle(input.title);
+    if (input.tier === 'front' && norm !== '') {
+        const dupes = input.inventory.filter((row) => row.path !== input.path && !isInternalPath(row.path) && normalizeTitle(row.title) === norm);
+        const paths = [...new Set(dupes.map((row) => row.path))];
+        if (paths.length > 0) {
+            const shown = paths.slice(0, COLLISION_DUPE_DISPLAY_LIMIT).map((p) => {
+                const urls = reportUrls(input.baseUrl, p, input.locale);
+                return `${p} (en=${urls.en} zh=${urls.zh})`;
+            });
+            const overflow = paths.length - shown.length;
+            parts.push(`疑似重复: title matches other path(s) ${shown.join('; ')}` +
+                (overflow > 0 ? ` +${overflow} more` : '') +
+                ` — 先读再写 (historian_read the existing page, prefer historian_page_update over a new twin)`);
+        }
+    }
+    return parts.length === 0 ? null : parts.join('\n');
+}
+// --- Create-path pre-write checklist gate (v4 todo 4) --------------------------
+/** Failing items needed to speak up: 1-2 stragglers are noise, 3+ is a draft
+ *  worth flagging. Threshold per the plan (todo 4). */
+const CHECKLIST_FAIL_TRIGGER = 3;
+/** The zh short name of a checklist item: its label up to the first
+ *  full-width/latin colon or bracket — '导言占比 10–15%'. */
+function itemShortName(label) {
+    const cut = (label.split(/[：:（(]/u, 1)[0] ?? label).trim();
+    return cut === '' ? label.trim() : cut;
+}
+/**
+ * Pre-write self-check advisory (plan todo 4): score the draft with the SAME
+ * 10-item gate the migrate pipeline uses (scoreChecklist — no duplicated
+ * scoring logic), purely locally, zero network. 3+ failing items produce a
+ * hint naming them; items 9-10 are 'deferred' pre-write by the scorer's own
+ * contract (migrate-score.ts) and can never count as fail. Informational
+ * only — the write always proceeds; evidence tier is exempt (callers pass
+ * front only: raw material is not a genre page).
+ */
+export function checklistAdvisory(genre, draft) {
+    const failed = scoreChecklist(genre, draft).filter((v) => v.verdict === 'fail');
+    if (failed.length < CHECKLIST_FAIL_TRIGGER)
+        return null;
+    const labels = new Map(selfReviewChecklist(genre).map((item) => [item.id, item.label]));
+    const names = failed.map((v) => `#${v.id} ${itemShortName(labels.get(v.id) ?? '?')}`).join('; ');
+    return `自检 ${failed.length}/10 未通过: ${names} (不阻断, 发布前请补齐)`;
+}
+// --- options.sections enforcement (v4 todo 5) ---------------------------------
+/** Config-level write refusal, paralleling PathValidationError's shape. The
+ *  class NAME is the routing key errEnvelope dispatches on: this shares the
+ *  'ConfigError' hint case with jsonc.ConfigError (which adds a code field
+ *  this pure path rule does not need). */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+/** First path segments the plugin maintains for its own bookkeeping — always
+ *  writable regardless of sections: a topic taxonomy configured for human
+ *  knowledge must never lock out the home landing page, the wiki-index map,
+ *  the _sandbox scratch area, the _data store, or the machine namespaces. */
+const SECTION_EXEMPT_SEGMENTS = [
+    'home',
+    'wiki-index',
+    '_sandbox',
+    '_data',
+    ...INTERNAL_NAMESPACES,
+];
+/** Section entry as configured → comparable form (strip slashes/whitespace). */
+function normalizeSection(entry) {
+    return entry.trim().replace(/^\/+|\/+$/gu, '');
+}
+/** Pure allow-list check on a write target path: null = allowed, string =
+ *  refusal message. Empty/undefined allow-list = allow-all (the documented
+ *  default, config.ts HistorianOptions.sections). Match is segment-wise and
+ *  case-sensitive: section 'doc' authorizes 'doc' and 'doc/x', never 'docs/x'. */
+export function sectionGuard(path, allowedSections) {
+    if (allowedSections === undefined)
+        return null;
+    const sections = allowedSections.map(normalizeSection).filter((sec) => sec !== '');
+    if (sections.length === 0)
+        return null;
+    const first = path.split('/')[0];
+    if (SECTION_EXEMPT_SEGMENTS.includes(first))
+        return null;
+    if (sections.some((sec) => path === sec || path.startsWith(`${sec}/`)))
+        return null;
+    return (`section '${first}' is not in the configured sections [${sections.join(', ')}] — ` +
+        `write the page under an allowed section or add '${first}' to the plugin's sections option`);
+}
+/** Guard + envelope in one step: null = proceed, ToolResult = refuse. */
+export function sectionRefusalJson(path, allowedSections) {
+    const violation = sectionGuard(path, allowedSections);
+    return violation === null ? null : errEnvelope(new ConfigError(violation));
+}

package/dist/tools/write.js

@@ -7,7 +7,7 @@
 import { tool } from '@opencode-ai/plugin';
 import { appendSection, createPage, updatePage, PageNotFoundError } from '../wiki/pages.js';
 import { readPage } from '../wiki/pages.read.js';
-import { enforceTierPath, errEnvelope, frontDumpAdvisory, isInternalPath, MACHINE_TIER_NOTE, monolingualRefusalJson, okJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
+import { enforceTierPath, errEnvelope, frontDumpAdvisory, isInternalPath, MACHINE_TIER_NOTE, monolingualRefusalJson, okJson, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
 const s = tool.schema;
 const UPDATE_ARGS = {
     path: s.string(),
@@ -25,6 +25,9 @@ export function makeUpdateTool(deps) {
         args: UPDATE_ARGS,
         execute: async (raw) => {
             const args = UpdateArgsSchema.parse(raw);
+            const offSections = sectionRefusalJson(args.path, deps.options.sections);
+            if (offSections !== null)
+                return offSections;
             try {
                 const page = await readPage(deps.getClient(), args.path, args.locale);
                 if (page === null) {
@@ -116,6 +119,9 @@ export function makeAppendTool(deps) {
             if (isEvidence && args.sectionZh !== undefined) {
                 return monolingualRefusalJson('historian_page_append', 'sectionZh');
             }
+            const offSections = sectionRefusalJson(args.path, deps.options.sections);
+            if (offSections !== null)
+                return offSections;
             try {
                 const appended = await appendSection(pageDeps(deps), args.path, args.locale, args.section);
                 let zhStatus;

package/dist/wiki/locale.d.ts

@@ -22,7 +22,8 @@ export declare class PathValidationError extends Error {
  *  5. first segment matches the locale shape (pitfall #9)
  *  6. any segment is length 1 (wiki.js rejects single-char path components)
  *  7. any segment contains characters outside `[A-Za-z0-9._-]`
- *  8. any segment is a reserved word (wiki.js endpoint collision)
+ *  8. any segment is a reserved word (wiki.js endpoint collision), except the
+ *     exact top-level 'home' (a live published path — see D9 note at the check)
  *
  * Order matters: cheap substring checks first, then per-segment rules.
  * Every rejection names the offending segment + the rule in the message.

package/dist/wiki/locale.js

@@ -44,7 +44,8 @@ const SEGMENT_CHARS = /^[A-Za-z0-9._-]+$/;
  *  5. first segment matches the locale shape (pitfall #9)
  *  6. any segment is length 1 (wiki.js rejects single-char path components)
  *  7. any segment contains characters outside `[A-Za-z0-9._-]`
- *  8. any segment is a reserved word (wiki.js endpoint collision)
+ *  8. any segment is a reserved word (wiki.js endpoint collision), except the
+ *     exact top-level 'home' (a live published path — see D9 note at the check)
  *
  * Order matters: cheap substring checks first, then per-segment rules.
  * Every rejection names the offending segment + the rule in the message.
@@ -84,7 +85,12 @@ export function validatePath(p) {
         if (!SEGMENT_CHARS.test(seg)) {
             throw new PathValidationError(`segment '${seg}' contains invalid characters (allowed: [A-Za-z0-9._-])`);
         }
-        if (RESERVED_WORDS.has(seg.toLowerCase())) {
+        // D9 bypass (probe p1): wiki.js 2.5.314 hosts a live published page at
+        // path=home (id48, en+zh) — the reserved-word block was plugin-side
+        // folklore, not a server limit. Allow the EXACT top-level segment 'home'
+        // only; nested 'home' (foo/home) and case variants (HOME) stay rejected.
+        const isExactTopLevelHome = segments.length === 1 && seg === 'home';
+        if (!isExactTopLevelHome && RESERVED_WORDS.has(seg.toLowerCase())) {
             throw new PathValidationError(`segment '${seg}' is a reserved wiki.js word (home|login|register|graphql|healthz|_assets|favicon)`);
         }
     }

package/package.json

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