@zosmaai/pi-llm-wiki 0.11.5 → 0.11.7

package/README.de.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/README.es.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/README.fr.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/README.hi.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/README.ja.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/README.ko.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/README.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/README.pt.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/README.ru.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/README.zh.md

@@ -9,6 +9,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://zosmaai.github.io/pi-llm-wiki/)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)
 

package/dist/extensions/llm-wiki/lib/ingest-worker.js

@@ -2,9 +2,11 @@ import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { Type } from "typebox";
 import { createKnowledgeDocument, patchKnowledgeDocument, readKnowledgeDocumentFile, serializeKnowledgeDocument, writeKnowledgeDocumentFile, } from "./knowledge-document.js";
+import { auditWikilinks, buildWikilinkIndex, } from "./knowledge-links.js";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
 import { runSubAgent } from "./subagent.js";
-import { fmtDate, slugify } from "./utils.js";
+import { resolveWikilinkValidation } from "./task-config.js";
+import { fmtDate, readJson, slugify } from "./utils.js";
 import { VaultWriteError, assertWritableVault } from "./vault-format.js";
 /**
  * Background ingest synthesis (issue #65, part of epic #63).
@@ -141,32 +143,22 @@ function getHeadings(lang) {
         contradiction: "⚠️ **Contradiction**",
     };
 }
-function buildEntityPageBody(title, description, sourceId, lang) {
+function buildEntityPageBody(title, description, sourceId) {
     const desc = description.trim() || "One-line description.";
-    const h = getHeadings(lang);
     return `# ${title}
 
 ${desc}
 
-## ${h.overview}
-
-[Key facts]
-
 ## Links
 
 - [${sourceId}](/sources/${sourceId}.md)`;
 }
-function buildConceptPageBody(title, definition, sourceId, lang) {
+function buildConceptPageBody(title, definition, sourceId) {
     const def = definition.trim() || "One-line definition.";
-    const h = getHeadings(lang);
     return `# ${title}
 
 ${def}
 
-## ${h.definition}
-
-[Clear explanation]
-
 ## Links
 
 - [${sourceId}](/sources/${sourceId}.md)`;
@@ -241,12 +233,29 @@ export function buildIngestedSourcePage(manifest, data, date, lang) {
     }, body);
     return serializeKnowledgeDocument(doc);
 }
+/**
+ * Build the wikilink index used by the pre-write gate: every existing page id
+ * (from the registry) plus the page ids this commit is about to create, so a
+ * link to a sibling created in the same ingest resolves instead of
+ * false-positiving as missing.
+ */
+function buildIngestAuditIndex(paths, sourceId, data) {
+    const registry = readJson(join(paths.meta, "registry.json"), {
+        pages: {},
+    });
+    const newIds = [
+        `sources/${sourceId}`,
+        ...data.entities.filter((e) => slugify(e.title)).map((e) => `entities/${slugify(e.title)}`),
+        ...data.concepts.filter((c) => slugify(c.title)).map((c) => `concepts/${slugify(c.title)}`),
+    ];
+    return buildWikilinkIndex([...Object.keys(registry.pages), ...newIds]);
+}
 /**
  * Persist a synthesis deterministically: rewrite the source page (status →
  * ingested), create missing entity/concept pages (existing pages are linked,
  * never overwritten), and log the event. Pure file I/O — no LLM, no network.
  */
-export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(), lang) {
+export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(), lang, wikilinkValidation) {
     const result = {
         sourceId,
         sourcePage: join(paths.wiki, "sources", `${sourceId}.md`),
@@ -265,6 +274,20 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
         }
         throw error;
     }
+    // Pre-write wikilink gate (issue #172, Layer 2). Applies only to the
+    // model-authored source body; entity/concept pages are generated templates.
+    const mode = resolveWikilinkValidation({ wikilinkValidation });
+    let sourceBody = buildIngestedSourcePageBody(manifest, data, date, lang);
+    if (mode !== "off") {
+        const audit = auditWikilinks(sourceBody, buildIngestAuditIndex(paths, sourceId, data), sourceId, mode);
+        if (mode === "strict" && audit.diagnostics.length > 0) {
+            return { ok: false, sourceId, diagnostics: audit.diagnostics };
+        }
+        if (mode === "normalize")
+            sourceBody = audit.body;
+        if (audit.diagnostics.length > 0)
+            result.wikilinkDiagnostics = audit.diagnostics;
+    }
     // Patch existing documents so unknown fields, legacy sources, and titles survive.
     let sourceDocument;
     if (existsSync(result.sourcePage)) {
@@ -273,7 +296,7 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
             return { ok: false, sourceId, diagnostics: parsed.diagnostics };
         sourceDocument = patchKnowledgeDocument(parsed.document, {
             fields: { status: "ingested", updated: date },
-            body: buildIngestedSourcePageBody(manifest, data, date, lang),
+            body: sourceBody,
         });
     }
     else {
@@ -286,7 +309,7 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
             captured: String(manifest.captured || date),
             status: "ingested",
             updated: date,
-        }, buildIngestedSourcePageBody(manifest, data, date, lang));
+        }, sourceBody);
     }
     mkdirSync(join(paths.wiki, "sources"), { recursive: true });
     writeKnowledgeDocumentFile(result.sourcePage, sourceDocument);
@@ -307,7 +330,7 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
                 description: e.description.trim() || "One-line description.",
                 created: date,
                 updated: date,
-            }, buildEntityPageBody(e.title, e.description, sourceId, lang), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
+            }, buildEntityPageBody(e.title, e.description, sourceId), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
             writeKnowledgeDocumentFile(pagePath, entityDoc);
             result.entitiesCreated.push(slug);
         }
@@ -329,7 +352,7 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
                 description: c.definition.trim() || "One-line definition.",
                 created: date,
                 updated: date,
-            }, buildConceptPageBody(c.title, c.definition, sourceId, lang), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
+            }, buildConceptPageBody(c.title, c.definition, sourceId), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
             writeKnowledgeDocumentFile(pagePath, conceptDoc);
             result.conceptsCreated.push(slug);
         }
@@ -365,7 +388,7 @@ Rules:
  * synthesis.
  */
 export async function runIngestSynthesis(args) {
-    const { model, apiKey, headers, paths, sourceId, manifest, extracted, maxChars, signal, synthesisLanguage, synthesisMaxTokens, } = args;
+    const { model, apiKey, headers, paths, sourceId, manifest, extracted, maxChars, signal, synthesisLanguage, synthesisMaxTokens, wikilinkValidation, } = args;
     const content = extracted.slice(0, maxChars ?? 24_000);
     if (!content.trim())
         return undefined;
@@ -380,7 +403,7 @@ export async function runIngestSynthesis(args) {
         description: "Persist the structured synthesis of this source into wiki pages. Call exactly once.",
         parameters: CommitSynthesisSchema,
         execute: async (_id, params) => {
-            const outcome = commitSynthesis(paths, sourceId, manifest, params, undefined, synthesisLanguage);
+            const outcome = commitSynthesis(paths, sourceId, manifest, params, undefined, synthesisLanguage, wikilinkValidation);
             if (!outcome.ok) {
                 return {
                     content: [{ type: "text", text: `Failed: ${outcome.diagnostics[0].message}` }],

package/dist/extensions/llm-wiki/lib/knowledge-links.js

@@ -1,4 +1,5 @@
 import { fromMarkdown } from "mdast-util-from-markdown";
+import { slugify } from "./utils.js";
 import { compareCodePoint } from "./vault-format.js";
 function diag(severity, code, path, message) {
     return { severity, code, path, message };
@@ -79,6 +80,55 @@ export function extractLegacyWikilinks(body) {
     }
     return links;
 }
+export function buildWikilinkIndex(ids) {
+    const byExact = new Map();
+    const byNormPath = new Map();
+    const byNormSlug = new Map();
+    function push(map, key, value) {
+        const existing = map.get(key);
+        if (existing)
+            existing.push(value);
+        else
+            map.set(key, [value]);
+    }
+    for (const id of ids) {
+        byExact.set(id.normalize("NFC"), id);
+        const segments = id.split("/");
+        const normFull = segments.map((s) => slugify(s)).join("/");
+        const normBase = slugify(segments[segments.length - 1]);
+        push(byNormPath, normFull, id);
+        push(byNormSlug, normBase, id);
+    }
+    return { byExact, byNormPath, byNormSlug };
+}
+export function resolveWikilink(target, index) {
+    const cleaned = target.trim().replace(/\\$/, "");
+    if (!cleaned)
+        return { kind: "missing", target: "" };
+    // Fast path: exact NFC match
+    const exact = index.byExact.get(cleaned.normalize("NFC"));
+    if (exact)
+        return { kind: "resolved", id: exact };
+    // Normalized full path (fixes case/space/slug drift in folder-qualified links)
+    const normFull = cleaned
+        .split("/")
+        .map((s) => slugify(s))
+        .join("/");
+    const pathHits = index.byNormPath.get(normFull);
+    if (pathHits && pathHits.length === 1)
+        return { kind: "resolved", id: pathHits[0] };
+    if (pathHits && pathHits.length > 1)
+        return { kind: "ambiguous", target: cleaned, candidates: pathHits };
+    // Bare title: match by slugified basename (handles [[zosma harness]] → entities/zosma-harness)
+    if (!cleaned.includes("/")) {
+        const baseHits = index.byNormSlug.get(slugify(cleaned));
+        if (baseHits && baseHits.length === 1)
+            return { kind: "resolved", id: baseHits[0] };
+        if (baseHits && baseHits.length > 1)
+            return { kind: "ambiguous", target: cleaned, candidates: baseHits };
+    }
+    return { kind: "missing", target: cleaned };
+}
 function resolveMarkdownTarget(target, sourceId) {
     // Strip query and fragment (earliest delimiter)
     const qIndex = target.indexOf("?");
@@ -156,14 +206,7 @@ function resolveMarkdownTarget(target, sourceId) {
     }
     return { kind: "empty" };
 }
-function resolveWikilinkTarget(target) {
-    // Wikilinks are already bundle-relative concept IDs
-    const cleaned = target.trim();
-    if (!cleaned)
-        return { kind: "empty" };
-    return { kind: "concept", id: cleaned };
-}
-export function buildResolvedBacklinks(sourceId, body, knownIds) {
+export function buildResolvedBacklinks(sourceId, body, index) {
     const diagnostics = [];
     const unresolved = [];
     const targets = new Set();
@@ -178,32 +221,92 @@ export function buildResolvedBacklinks(sourceId, body, knownIds) {
             diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Malformed percent-encoded link: ${link.target}`));
         }
         else if (resolved.kind === "concept") {
-            const normalizedId = resolved.id.normalize("NFC");
-            if (knownIds.has(normalizedId)) {
-                targets.add(normalizedId);
+            const canonical = index.byExact.get(resolved.id.normalize("NFC"));
+            if (canonical) {
+                targets.add(canonical);
             }
             else {
-                unresolved.push({ target: normalizedId, syntax: "markdown" });
-                diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved link: ${normalizedId}`));
+                unresolved.push({ target: resolved.id, syntax: "markdown" });
+                diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved link: ${resolved.id}`));
             }
         }
         // external and empty are silently ignored
     }
-    // Process wikilinks
+    // Process wikilinks (lenient: exact → normalized path → bare title)
     for (const link of allLinks.wikilinks) {
-        const resolved = resolveWikilinkTarget(link.target);
-        if (resolved.kind === "concept") {
-            const normalizedId = resolved.id.normalize("NFC");
-            if (knownIds.has(normalizedId)) {
-                targets.add(normalizedId);
-            }
-            else {
-                unresolved.push({ target: normalizedId, syntax: "wikilink" });
-                diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved wikilink: ${normalizedId}`));
-            }
+        const res = resolveWikilink(link.target, index);
+        if (res.kind === "resolved") {
+            targets.add(res.id);
+        }
+        else if (res.kind === "ambiguous") {
+            diagnostics.push(diag("warning", "link_ambiguous", `${sourceId}.md`, `Ambiguous wikilink: ${res.target} (candidates: ${res.candidates.join(", ")})`));
+        }
+        else {
+            unresolved.push({ target: res.target, syntax: "wikilink" });
+            diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved wikilink: ${res.target}`));
         }
     }
     // Sort and deduplicate
     const sorted = [...targets].sort(compareCodePoint);
     return { targets: sorted, unresolved, diagnostics };
 }
+const WIKILINK_REPLACE_RE = /\[\[([^\]|]+)(\|[^\]]*)?\]\]/g;
+/**
+ * Audit a markdown body's wikilinks against the page index.
+ *
+ * - Collects `link_unresolved` / `link_ambiguous` diagnostics for every link
+ *   that does not resolve to exactly one page (skipped for "off").
+ * - In "normalize" mode, additionally rewrites each link that DOES resolve to
+ *   its canonical page id. Only the target token is replaced (the parser's own
+ *   regex is reused), so `|alias`, escaping, and surrounding text are preserved.
+ *
+ * Pure: no I/O. The caller supplies the index (typically `buildWikilinkIndex`
+ * over existing page ids plus the ids created by the same commit).
+ */
+export function auditWikilinks(body, index, sourceId, mode) {
+    if (mode === "off")
+        return { diagnostics: [], body, changed: false };
+    const diagnostics = [];
+    for (const { target } of extractKnowledgeLinks(body).wikilinks) {
+        const resolved = resolveWikilink(target, index);
+        if (resolved.kind === "ambiguous") {
+            diagnostics.push({
+                severity: "warning",
+                code: "link_ambiguous",
+                path: sourceId,
+                message: `Wikilink target "${target}" matches multiple pages (${resolved.candidates.join(", ")}).`,
+            });
+        }
+        else if (resolved.kind === "missing") {
+            diagnostics.push({
+                severity: "warning",
+                code: "link_unresolved",
+                path: sourceId,
+                message: `Wikilink target "${target}" does not match any page.`,
+            });
+        }
+    }
+    let out = body;
+    if (mode === "normalize") {
+        out = body.replace(WIKILINK_REPLACE_RE, (full, raw, alias) => {
+            const resolved = resolveWikilink(normalizeWikilinkTarget(raw), index);
+            return resolved.kind === "resolved" ? `[[${resolved.id}${alias ?? ""}]]` : full;
+        });
+    }
+    return { diagnostics, body: out, changed: out !== body };
+}
+/**
+ * Apply the pre-write wikilink gate to a body. Wraps {@link auditWikilinks}:
+ * blocks (ok:false) only in strict mode with issues, rewrites in normalize mode,
+ * and always returns the diagnostics so callers can surface them (warn/normalize).
+ */
+export function applyWikilinkGate(body, index, sourceId, mode) {
+    if (mode === "off")
+        return { ok: true, body, diagnostics: [] };
+    const audit = auditWikilinks(body, index, sourceId, mode);
+    return {
+        ok: !(mode === "strict" && audit.diagnostics.length > 0),
+        body: mode === "normalize" ? audit.body : body,
+        diagnostics: audit.diagnostics,
+    };
+}

package/dist/extensions/llm-wiki/lib/metadata.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
-import { buildResolvedBacklinks } from "./knowledge-links.js";
+import { buildResolvedBacklinks, buildWikilinkIndex, } from "./knowledge-links.js";
 import { isPathWithin, readJson } from "./utils.js";
 import { assertWritableVault, compareCodePoint, discoverKnowledgeDocuments, inspectVaultFormat, } from "./vault-format.js";
 /** Rebuild the complete metadata layer with fail-closed semantics. */
@@ -24,8 +24,8 @@ export function rebuildMetadata(paths) {
     // Step 3: Build registry from documents + raw fallbacks
     const registry = buildRegistry(paths, documents);
     // Step 4: Build backlinks from discovered documents
-    const knownIds = new Set(documents.map((d) => d.id));
-    const backlinks = buildBacklinks(documents, knownIds, allDiagnostics);
+    const wikilinkIndex = buildWikilinkIndex(documents.map((d) => d.id));
+    const backlinks = buildBacklinks(documents, wikilinkIndex, allDiagnostics);
     const eventSource = readEventSource(join(paths.meta, "events.jsonl"));
     const eventLogResult = eventSource.available ? buildOkfLog(eventSource.content) : undefined;
     if (eventLogResult)
@@ -157,7 +157,7 @@ function getSemanticTitle(doc) {
     return doc.id.split("/").pop() || "Untitled";
 }
 /** Build backlinks from discovered documents using shared link resolution. */
-function buildBacklinks(documents, knownIds, diagnostics) {
+function buildBacklinks(documents, index, diagnostics) {
     const inbound = {};
     // Initialize parsed concept IDs with empty arrays
     for (const doc of documents) {
@@ -165,7 +165,7 @@ function buildBacklinks(documents, knownIds, diagnostics) {
     }
     // Resolve links for each document
     for (const doc of documents) {
-        const result = buildResolvedBacklinks(doc.id, doc.body, knownIds);
+        const result = buildResolvedBacklinks(doc.id, doc.body, index);
         diagnostics.push(...result.diagnostics);
         for (const target of result.targets) {
             if (inbound[target] && !inbound[target].includes(doc.id)) {

package/dist/extensions/llm-wiki/lib/retro.js

@@ -1,9 +1,11 @@
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { Type } from "typebox";
 import { scheduleReindex } from "./indexing.js";
 import { createKnowledgeDocument, writeKnowledgeDocumentFile } from "./knowledge-document.js";
+import { applyWikilinkGate, buildWikilinkIndex } from "./knowledge-links.js";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
-import { fmtDate, resolveVaultPaths } from "./utils.js";
+import { loadTaskConfig, resolveWikilinkValidation } from "./task-config.js";
+import { fmtDate, readJson, resolveVaultPaths } from "./utils.js";
 import { assertWritableVault, inspectWritableVault } from "./vault-format.js";
 /**
  * Save an atomic insight into the wiki as a single markdown file.
@@ -115,9 +117,34 @@ export function registerWikiRetro(pi, runtime) {
                     isError: true,
                 };
             }
+            // Pre-write wikilink gate (#172): validate/normalize caller-supplied body.
+            const mode = resolveWikilinkValidation(loadTaskConfig(ctx.cwd ?? process.cwd()));
+            let body = params.body;
+            let wikilinkIssues = [];
+            if (mode !== "off") {
+                const registry = readJson(join(paths.meta, "registry.json"), { pages: {} });
+                const gate = applyWikilinkGate(body, buildWikilinkIndex(Object.keys(registry.pages)), `sources/${params.slug}`, mode);
+                wikilinkIssues = gate.diagnostics.map((d) => d.message);
+                if (!gate.ok) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Rejected write — unresolved/ambiguous wikilinks:\n${wikilinkIssues
+                                    .map((m) => `- ${m}`)
+                                    .join("\n")}`,
+                            },
+                        ],
+                        details: { error: "link_validation", issues: wikilinkIssues },
+                        isError: true,
+                    };
+                }
+                if (mode === "normalize")
+                    body = gate.body;
+            }
             let result;
             try {
-                result = saveInsight(paths, params.slug, params.title, params.body, params.category, {
+                result = saveInsight(paths, params.slug, params.title, body, params.category, {
                     rebuild: !runtime,
                 });
             }
@@ -134,6 +161,9 @@ export function registerWikiRetro(pi, runtime) {
             if (runtime) {
                 scheduleReindex(runtime, { hasUI: ctx.hasUI, ui: ctx.ui }, paths);
             }
+            const gateNote = wikilinkIssues.length
+                ? `\n\n⚠️ ${wikilinkIssues.length} wikilink issue(s):\n${wikilinkIssues.map((m) => `- ${m}`).join("\n")}`
+                : "";
             return {
                 content: [
                     {
@@ -144,13 +174,17 @@ export function registerWikiRetro(pi, runtime) {
                             `- Page: \`${result.sourcePagePath}\``,
                             "",
                             "This insight will be auto-surfaced by wiki_recall in future sessions.",
-                        ].join("\n"),
+                            gateNote,
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
                     },
                 ],
                 details: {
                     slug: params.slug,
                     title: params.title,
                     category: params.category || null,
+                    wikilinkIssues,
                 },
             };
         },

package/dist/extensions/llm-wiki/lib/runtime.js

@@ -64,11 +64,11 @@ export class Runtime {
             };
         }
         const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-        if (!auth.ok || !auth.apiKey) {
+        if (!auth.ok) {
             const provider = model.provider ?? "unknown";
             return { ok: false, reason: `no API key for provider "${provider}"` };
         }
-        return { ok: true, model, apiKey: auth.apiKey, headers: auth.headers };
+        return { ok: true, model, apiKey: auth.apiKey ?? "", headers: auth.headers };
     }
     /**
      * Fire-and-forget a background task.

package/dist/extensions/llm-wiki/lib/task-config.js

@@ -10,6 +10,23 @@ export const TASK_DEFAULTS = {};
 export function noticesEnabled(config) {
     return config?.notices !== false;
 }
+const WIKILINK_VALIDATION_MODES = [
+    "off",
+    "warn",
+    "strict",
+    "normalize",
+];
+/**
+ * Resolve the wikilink write-gate mode (issue #172, Layer 2). Defaults to
+ * `warn` — ingest always writes and reports; only an explicit `strict` blocks.
+ * Unknown values fall back to `warn` rather than failing the ingest.
+ */
+export function resolveWikilinkValidation(config) {
+    const v = config?.wikilinkValidation;
+    if (v && WIKILINK_VALIDATION_MODES.includes(v))
+        return v;
+    return "warn";
+}
 /**
  * Resolve whether the personal vault may serve as this project's ambient
  * vault. Explicit `ambientPersonalVault` wins; otherwise the host decides
@@ -91,6 +108,22 @@ function readNamespacedConfig(path) {
         if (typeof maxTokens === "number" && Number.isFinite(maxTokens) && maxTokens > 0) {
             out.synthesisMaxTokens = Math.floor(maxTokens);
         }
+        const wl = section.wikilinkValidation;
+        if (typeof wl === "string" && WIKILINK_VALIDATION_MODES.includes(wl)) {
+            out.wikilinkValidation = wl;
+        }
+        const ct = section.customTypes;
+        if (ct && typeof ct === "object" && !Array.isArray(ct)) {
+            const entries = Object.entries(ct);
+            const valid = {};
+            for (const [k, v] of entries) {
+                if (typeof k === "string" && typeof v === "string" && k && v) {
+                    valid[k] = v;
+                }
+            }
+            if (Object.keys(valid).length)
+                out.customTypes = valid;
+        }
         return out;
     }
     catch {
@@ -260,6 +293,8 @@ const KNOWN_KEYS = [
     "trajectories",
     "synthesisLanguage",
     "synthesisMaxTokens",
+    "wikilinkValidation",
+    "customTypes",
 ];
 export function loadTaskConfigSources(cwd) {
     const globalResult = {};