@rarusoft/dendrite-wiki 0.1.0-alpha.0

package/dist/store.js

@@ -0,0 +1,1617 @@
+/**
+ * The wiki page store and the heart of the read/write/search/lint surface.
+ *
+ * Owns everything about wiki pages as filesystem markdown: listing pages under
+ * `docs/wiki/**`, parsing frontmatter into `WikiPageMetadata`, reading and writing page
+ * content, extracting source-backed claims, building the graph of inbound/outbound links,
+ * surfacing lint findings (`missing-h1`, `orphan-page`, `stale-claim`, `page-drift`, etc.),
+ * and assembling the task-scoped briefing returned by `wiki_context`. The lint pass exempts
+ * `lifecycle: generated` pages so auto-managed surfaces (the API reference tree) don't
+ * surface findings humans can't act on.
+ *
+ * Most other modules in `src/wiki/` consume this module rather than the filesystem directly.
+ * `memory-store.ts` joins memories to pages here, `synthesis.ts` reads pages for claim
+ * synthesis prompts, `generated-docs.ts` rebuilds derived artifacts from the page list.
+ */
+import { promises as fs, statSync } from 'node:fs';
+import path from 'node:path';
+import { createPatch } from 'diff';
+import { recallProjectHandoffs, recallProjectMemories, summarizeMemoryBacklog } from '@rarusoft/dendrite-memory';
+import { recallProjectSkills } from '@rarusoft/dendrite-memory';
+import { getCachedWikiContext, invalidateWikiContextCache, setCachedWikiContext } from './context-cache.js';
+import { buildContradictsShippedMemoryMessage, detectContradictsShippedMemory } from './contradicts-shipped-memory.js';
+import { listProjectMemories } from '@rarusoft/dendrite-memory';
+import { buildPageDriftMessage, detectPageDrift } from './page-drift.js';
+import { buildMemoryTrailReason, loadMemoryTrailBonusLookup, reinforceQueryEdges } from '@rarusoft/dendrite-memory';
+import { loadActivePageDriftSnoozes } from '@rarusoft/dendrite-memory';
+import { buildWikiSearchIndex, fallbackSearchResults, searchResultToContextPage, searchWikiIndex, tokenizeSearchQuery } from './search-index.js';
+const proposalPageMarker = 'Reviewable deterministic maintenance proposal.';
+export async function listWikiProposals() {
+    const duplicateGroups = await findDuplicateGuidanceGroups();
+    const guidanceFiles = await listProjectGuidanceFiles();
+    const mergeProposals = duplicateGroups.map((group) => {
+        const [canonical, ...duplicates] = group;
+        return {
+            kind: 'merge-guidance',
+            summary: `Merge duplicate guidance into ${canonical.path}`,
+            currentStateSummary: `${duplicates.map((guidance) => guidance.path).join(', ')} currently duplicate ${canonical.path}.`,
+            afterApplySummary: `${duplicates.map((guidance) => guidance.path).join(', ')} become short pointers to ${canonical.path} while the canonical file stays unchanged.`,
+            canonicalPath: canonical.path,
+            duplicatePaths: duplicates.map((guidance) => guidance.path),
+            archiveTargets: duplicates.map((guidance) => ({
+                sourcePath: guidance.path,
+                suggestedPath: buildGuidanceArchivePath(guidance.path),
+                reviewStatus: 'pending-review',
+                reason: 'Archive only after the duplicate guidance has been reviewed and the pointer rewrite has been accepted.'
+            })),
+            rationale: `These guidance files share the same normalized content and should route through one canonical entry file before the redundant copies are archived.`
+        };
+    });
+    const routeProposals = [];
+    for (const guidance of guidanceFiles.filter((candidate) => candidate.kind !== 'skill')) {
+        const content = await fs.readFile(path.join(repoRoot, guidance.path), 'utf8').catch(() => '');
+        if (countLines(content) <= maxGuidanceLineCount) {
+            continue;
+        }
+        const targetPaths = listGuidanceRouteTargets(content, guidance.path);
+        if (targetPaths.length === 0) {
+            continue;
+        }
+        routeProposals.push({
+            kind: 'route-guidance',
+            summary: `Trim ${guidance.path} and route to ${targetPaths[0]}`,
+            currentStateSummary: `${guidance.path} is longer than the preferred guidance length.`,
+            afterApplySummary: `${guidance.path} becomes a short entry file that routes to ${targetPaths[0]}.`,
+            guidancePath: guidance.path,
+            targetPaths,
+            rationale: 'This guidance file exceeds the preferred length and already links to canonical local docs pages that can carry the detailed workflow.'
+        });
+    }
+    return attachProposalReviewPages([...mergeProposals, ...routeProposals].sort((left, right) => left.summary.localeCompare(right.summary)));
+}
+export async function writeWikiProposalPages() {
+    const result = await syncGeneratedProposalPages();
+    return result.pages;
+}
+export async function applyWikiProposal(reviewSlug) {
+    const proposals = await listWikiProposals();
+    const proposal = proposals.find((candidate) => candidate.reviewSlug === reviewSlug);
+    if (!proposal) {
+        throw new Error(`Unknown active proposal: ${reviewSlug}`);
+    }
+    if (proposal.kind === 'route-guidance') {
+        const absolutePath = path.join(repoRoot, proposal.guidancePath);
+        const existingContent = await fs.readFile(absolutePath, 'utf8').catch(() => '');
+        const nextContent = await renderRouteGuidanceApplyContent(proposal, existingContent);
+        await fs.writeFile(absolutePath, nextContent.endsWith('\n') ? nextContent : `${nextContent}\n`, 'utf8');
+        const syncResult = await syncGeneratedProposalPages();
+        return {
+            reviewSlug: proposal.reviewSlug,
+            proposalKind: proposal.kind,
+            updatedPaths: [proposal.guidancePath],
+            removedReviewSlugs: syncResult.removedSlugs,
+            activeReviewSlugs: syncResult.pages.map((page) => page.slug)
+        };
+    }
+    if (proposal.kind === 'merge-guidance') {
+        const canonicalContent = await fs.readFile(path.join(repoRoot, proposal.canonicalPath), 'utf8').catch(() => '');
+        const updatedPaths = [];
+        for (const duplicatePath of proposal.duplicatePaths) {
+            const absolutePath = path.join(repoRoot, duplicatePath);
+            const existingContent = await fs.readFile(absolutePath, 'utf8').catch(() => '');
+            const nextContent = await renderMergeGuidanceApplyContent(proposal, duplicatePath, existingContent, canonicalContent);
+            await fs.writeFile(absolutePath, nextContent.endsWith('\n') ? nextContent : `${nextContent}\n`, 'utf8');
+            updatedPaths.push(duplicatePath);
+        }
+        const syncResult = await syncGeneratedProposalPages();
+        return {
+            reviewSlug: proposal.reviewSlug,
+            proposalKind: proposal.kind,
+            updatedPaths,
+            removedReviewSlugs: syncResult.removedSlugs,
+            activeReviewSlugs: syncResult.pages.map((page) => page.slug)
+        };
+    }
+    throw new Error(`Auto-apply is not supported for proposal kind: ${reviewSlug}`);
+}
+export async function previewWikiProposal(reviewSlug) {
+    const proposals = await listWikiProposals();
+    const proposal = proposals.find((candidate) => candidate.reviewSlug === reviewSlug);
+    if (!proposal) {
+        throw new Error(`Unknown active proposal: ${reviewSlug}`);
+    }
+    const fileChanges = [];
+    const warnings = [];
+    if (proposal.kind === 'route-guidance') {
+        const absolutePath = path.join(repoRoot, proposal.guidancePath);
+        const existingContent = await fs.readFile(absolutePath, 'utf8').catch(() => '');
+        if (!existingContent) {
+            warnings.push(`${proposal.guidancePath} does not currently exist; applying will create it.`);
+        }
+        const renderedContent = await renderRouteGuidanceApplyContent(proposal, existingContent);
+        const proposedContent = ensureTrailingNewline(renderedContent);
+        fileChanges.push(buildFileChange(proposal.guidancePath, existingContent, proposedContent));
+    }
+    else if (proposal.kind === 'merge-guidance') {
+        const canonicalContent = await fs.readFile(path.join(repoRoot, proposal.canonicalPath), 'utf8').catch(() => '');
+        if (!canonicalContent) {
+            warnings.push(`Canonical guidance file ${proposal.canonicalPath} does not exist; the merge will run with empty canonical content.`);
+        }
+        for (const duplicatePath of proposal.duplicatePaths) {
+            const absolutePath = path.join(repoRoot, duplicatePath);
+            const existingContent = await fs.readFile(absolutePath, 'utf8').catch(() => '');
+            const renderedContent = await renderMergeGuidanceApplyContent(proposal, duplicatePath, existingContent, canonicalContent);
+            const proposedContent = ensureTrailingNewline(renderedContent);
+            fileChanges.push(buildFileChange(duplicatePath, existingContent, proposedContent));
+        }
+    }
+    else {
+        throw new Error(`Preview is not supported for proposal kind: ${proposal.kind}`);
+    }
+    if (fileChanges.every((change) => change.skippedBecauseUnchanged)) {
+        warnings.unshift('Every affected file already matches the proposed content; applying will be a no-op.');
+    }
+    return {
+        mode: 'preview',
+        reviewSlug: proposal.reviewSlug,
+        proposalKind: proposal.kind,
+        summary: proposal.summary,
+        rationale: proposal.rationale,
+        warnings,
+        fileChanges
+    };
+}
+function ensureTrailingNewline(content) {
+    return content.endsWith('\n') ? content : `${content}\n`;
+}
+function buildFileChange(filePath, currentContent, proposedContent) {
+    const skippedBecauseUnchanged = currentContent === proposedContent;
+    // Render the diff with the entire file as context (not the diff library's default 4-line window)
+    // so the operator sees the whole file surrounding the change. Same convention as memory-promotion.
+    const unifiedDiff = createPatch(filePath, currentContent, proposedContent, 'current', 'after apply', { context: 100_000 });
+    return { path: filePath, currentContent, proposedContent, unifiedDiff, skippedBecauseUnchanged };
+}
+async function syncGeneratedProposalPages() {
+    const proposals = await listWikiProposals();
+    const pages = [];
+    const existingSlugs = await listGeneratedProposalPageSlugs();
+    const currentSlugs = new Set();
+    const removedSlugs = [];
+    for (const proposal of proposals) {
+        const content = renderProposalPage(proposal);
+        await writeWikiPage(proposal.reviewSlug, content);
+        const title = content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? proposal.reviewSlug;
+        pages.push({
+            slug: proposal.reviewSlug,
+            title,
+            path: proposal.reviewPath,
+            proposalKind: proposal.kind
+        });
+        currentSlugs.add(proposal.reviewSlug);
+    }
+    for (const staleSlug of existingSlugs) {
+        if (currentSlugs.has(staleSlug)) {
+            continue;
+        }
+        await fs.rm(pagePathFromSlug(staleSlug), { force: true });
+        removedSlugs.push(staleSlug);
+    }
+    return {
+        pages: pages.sort((left, right) => left.slug.localeCompare(right.slug)),
+        removedSlugs: removedSlugs.sort((left, right) => left.localeCompare(right))
+    };
+}
+function attachProposalReviewPages(proposals) {
+    const usedSlugs = new Set();
+    return proposals.map((proposal) => {
+        const reviewSlug = buildProposalPageSlug(proposal, usedSlugs);
+        return {
+            ...proposal,
+            reviewSlug,
+            reviewPath: `docs/wiki/${reviewSlug}.md`
+        };
+    });
+}
+async function listGeneratedProposalPageSlugs() {
+    const pendingReviewDirectory = path.join(wikiRoot, 'pending-review');
+    const matches = [];
+    async function walk(directory) {
+        const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const fullPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.md')) {
+                continue;
+            }
+            const content = await fs.readFile(fullPath, 'utf8').catch(() => '');
+            if (!content.includes(proposalPageMarker)) {
+                continue;
+            }
+            const relative = path.relative(wikiRoot, fullPath).replace(/\\/g, '/');
+            matches.push(relative.replace(/\.md$/i, ''));
+        }
+    }
+    await walk(pendingReviewDirectory);
+    return matches.sort((left, right) => left.localeCompare(right));
+}
+function buildGuidanceArchivePath(relativePath) {
+    const safeName = relativePath.replace(/^[./]+/, '').replace(/[\\/]/g, '__');
+    return `docs/wiki/archive-guidance/${safeName}`;
+}
+function buildProposalPageSlug(proposal, usedSlugs) {
+    const key = proposal.kind === 'merge-guidance' ? proposal.canonicalPath : proposal.guidancePath;
+    const base = `pending-review/${proposal.kind}-${slugifyProposalKey(key)}`;
+    let slug = base;
+    let counter = 2;
+    while (usedSlugs.has(slug)) {
+        slug = `${base}-${counter}`;
+        counter += 1;
+    }
+    usedSlugs.add(slug);
+    return slug;
+}
+function slugifyProposalKey(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'proposal';
+}
+function renderProposalPage(proposal) {
+    if (proposal.kind === 'merge-guidance') {
+        return [
+            `# Review merge guidance for ${proposal.canonicalPath}`,
+            '',
+            proposalPageMarker,
+            '',
+            '## Summary',
+            proposal.summary,
+            '',
+            '## Current State',
+            `- ${proposal.currentStateSummary}`,
+            `- ${proposal.canonicalPath} is the canonical guidance entry.`,
+            ...proposal.duplicatePaths.map((duplicatePath) => `- ${duplicatePath} currently repeats that guidance content.`),
+            '',
+            '## After Apply',
+            `- ${proposal.afterApplySummary}`,
+            `- ${proposal.canonicalPath} stays unchanged as the canonical guidance entry.`,
+            ...proposal.duplicatePaths.map((duplicatePath) => `- ${duplicatePath} becomes a short pointer to the canonical guidance and wiki pages.`),
+            ...proposal.archiveTargets.map((target) => `- If you want to keep history, archive ${target.sourcePath} at ${target.suggestedPath} before deleting or moving it later. ${target.reason}`),
+            '',
+            '## Rationale',
+            proposal.rationale,
+        ].join('\n');
+    }
+    return [
+        `# Review route guidance for ${proposal.guidancePath}`,
+        '',
+        proposalPageMarker,
+        '',
+        '## Summary',
+        proposal.summary,
+        '',
+        '## Current State',
+        `- ${proposal.currentStateSummary}`,
+        `- ${proposal.guidancePath} is longer than the preferred guidance length.`,
+        ...proposal.targetPaths.map((targetPath) => `- It already points readers toward ${targetPath}.`),
+        '',
+        '## After Apply',
+        `- ${proposal.afterApplySummary}`,
+        `- ${proposal.guidancePath} becomes a short entry file.`,
+        ...proposal.targetPaths.map((targetPath) => `- Detailed workflow is routed to ${targetPath}.`),
+        '',
+        '## Rationale',
+        proposal.rationale
+    ].join('\n');
+}
+async function renderRouteGuidanceApplyContent(proposal, existingContent) {
+    const heading = extractHeading(existingContent) || defaultGuidanceHeading(proposal.guidancePath);
+    const summary = extractSummaryParagraph(existingContent) || 'This entry file now routes to canonical local docs pages.';
+    const routeLines = await Promise.all(proposal.targetPaths.map(async (targetPath) => {
+        const label = await readMarkdownTitle(targetPath);
+        const relativeLink = buildRelativeMarkdownLink(proposal.guidancePath, targetPath);
+        return `- Read [${label}](${relativeLink}).`;
+    }));
+    return [
+        `# ${heading}`,
+        '',
+        summary,
+        '',
+        'Detailed workflow lives in the wiki pages below.',
+        '',
+        ...routeLines
+    ].join('\n');
+}
+async function renderMergeGuidanceApplyContent(proposal, duplicatePath, duplicateContent, canonicalContent) {
+    const heading = extractHeading(duplicateContent) || defaultGuidanceHeading(duplicatePath);
+    const summary = extractSummaryParagraph(duplicateContent) || 'This entry file now points to the canonical guidance file and wiki pages.';
+    const canonicalTitle = await readMarkdownTitle(proposal.canonicalPath);
+    const canonicalLink = buildRelativeMarkdownLink(duplicatePath, proposal.canonicalPath);
+    const targetPaths = listGuidanceRouteTargets(duplicateContent, duplicatePath);
+    const fallbackTargetPaths = targetPaths.length > 0 ? targetPaths : listGuidanceRouteTargets(canonicalContent, proposal.canonicalPath);
+    const routeLines = await Promise.all(fallbackTargetPaths.map(async (targetPath) => {
+        const label = await readMarkdownTitle(targetPath);
+        const relativeLink = buildRelativeMarkdownLink(duplicatePath, targetPath);
+        return `- Read [${label}](${relativeLink}).`;
+    }));
+    return [
+        `# ${heading}`,
+        '',
+        summary,
+        '',
+        `Canonical guidance lives in [${canonicalTitle}](${canonicalLink}).`,
+        '',
+        'Detailed workflow lives in the wiki pages below.',
+        '',
+        ...routeLines
+    ].join('\n');
+}
+function extractHeading(content) {
+    return content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? '';
+}
+function defaultGuidanceHeading(guidancePath) {
+    return path.basename(guidancePath, '.md').replace(/[-_]+/g, ' ').trim() || 'Guidance';
+}
+async function readMarkdownTitle(relativePath) {
+    const content = await fs.readFile(path.join(repoRoot, relativePath), 'utf8').catch(() => '');
+    return extractHeading(content) || path.basename(relativePath, '.md');
+}
+function buildRelativeMarkdownLink(sourcePath, targetPath) {
+    const sourceDir = path.posix.dirname(sourcePath.replace(/\\/g, '/'));
+    return path.posix.relative(sourceDir, targetPath.replace(/\\/g, '/'));
+}
+const repoRoot = path.resolve(process.cwd());
+const docsRoot = path.resolve(repoRoot, 'docs');
+const wikiRoot = path.join(docsRoot, 'wiki');
+// Tests reload this module per fixture (different cwd → different `repoRoot`), but
+// `context-cache.js` is imported once and shared across all instances. Without this
+// invalidation, a buildWikiContext call from a prior fixture's instance could serve
+// a cached result whose `findings` were computed against a different `repoRoot`.
+// On a fast Linux runner this surfaced as flaky lint assertions where guidance files
+// from one fixture would silently bleed into another. Cheap to call at module init.
+invalidateWikiContextCache();
+const defaultContextPageLimit = 4;
+const defaultLogEntryLimit = 3;
+const maxGuidanceLineCount = 40;
+const contextStopTerms = new Set(['current', 'latest', 'need', 'project', 'question', 'recent', 'task']);
+const projectLogHintTerms = new Set(['change', 'changes', 'history', 'log', 'recent', 'ship', 'status', 'update', 'updates']);
+export function pagePathFromSlug(slug) {
+    const slashNormalized = slug.replace(/\\/g, '/').trim();
+    const normalized = slashNormalized.replace(/\.md$/i, '');
+    if (!normalized ||
+        slashNormalized.startsWith('/') ||
+        normalized.endsWith('/') ||
+        normalized.split('/').some((segment) => !segment || segment === '.' || segment === '..') ||
+        !/^[a-z0-9][a-z0-9/_-]*$/i.test(normalized)) {
+        throw new Error(`Invalid wiki slug: ${slug}`);
+    }
+    return path.join(wikiRoot, `${normalized}.md`);
+}
+export async function readWikiPage(slug) {
+    return fs.readFile(pagePathFromSlug(slug), 'utf8');
+}
+export async function writeWikiPage(slug, content) {
+    const filePath = pagePathFromSlug(slug);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content.endsWith('\n') ? content : `${content}\n`, 'utf8');
+    invalidateWikiContextCache();
+}
+export async function appendProjectLog(entry, date = new Date()) {
+    const filePath = pagePathFromSlug('project-log');
+    const isoDate = date.toISOString().slice(0, 10);
+    // VitePress runs every page through the Vue compiler, so unescaped `<word>` tokens
+    // in log entries get parsed as custom Vue tags and break the docs build (the
+    // memory-promotion and maintenance-inbox writers already do this; project-log
+    // needs the same treatment). Escape inside backtick spans is preserved by markdown.
+    const line = `\n- ${escapeMarkdownAngleBrackets(entry.trim())}\n`;
+    let content = await fs.readFile(filePath, 'utf8').catch(() => '# Project Log\n');
+    const heading = `## ${isoDate}`;
+    if (!content.includes(heading)) {
+        content += `\n${heading}\n`;
+    }
+    content += line;
+    await fs.writeFile(filePath, content, 'utf8');
+    invalidateWikiContextCache();
+}
+function escapeMarkdownAngleBrackets(value) {
+    return value.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+// Insert an H1 heading derived from the page slug. Used by the maintenance inbox's
+// `missing-h1` lint action so the operator can resolve the finding with one click instead
+// of editing the file by hand. The inserted heading lands AFTER the frontmatter block
+// (if present) and BEFORE the first body line. Idempotent: if the page already has an
+// H1, returns false and writes nothing.
+export async function insertH1FromSlug(slug) {
+    const filePath = pagePathFromSlug(slug);
+    const content = await fs.readFile(filePath, 'utf8');
+    if (hasH1(content)) {
+        return false;
+    }
+    const title = titleCaseFromSlug(slug);
+    const frontmatterMatch = content.match(/^(---\r?\n[\s\S]*?\r?\n---\r?\n)/);
+    if (frontmatterMatch) {
+        const frontmatter = frontmatterMatch[1];
+        const rest = content.slice(frontmatter.length);
+        const restNoLeadingBlank = rest.replace(/^\r?\n+/, '');
+        const next = `${frontmatter}\n# ${title}\n\n${restNoLeadingBlank}`;
+        await fs.writeFile(filePath, next.endsWith('\n') ? next : `${next}\n`, 'utf8');
+    }
+    else {
+        const restNoLeadingBlank = content.replace(/^\r?\n+/, '');
+        const next = `# ${title}\n\n${restNoLeadingBlank}`;
+        await fs.writeFile(filePath, next.endsWith('\n') ? next : `${next}\n`, 'utf8');
+    }
+    invalidateWikiContextCache();
+    return true;
+}
+function titleCaseFromSlug(slug) {
+    return slug
+        .split(/[\/-]/)
+        .filter((part) => part.length > 0)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+export async function editPageSummary(slug, newFirstParagraph) {
+    const trimmedNew = newFirstParagraph.replace(/\r\n/g, '\n').trim();
+    if (!trimmedNew) {
+        throw new Error('editPageSummary requires a non-empty replacement paragraph.');
+    }
+    const filePath = pagePathFromSlug(slug);
+    const content = await fs.readFile(filePath, 'utf8');
+    const frontmatterMatch = content.match(/^(---\r?\n[\s\S]*?\r?\n---\r?\n)/);
+    const frontmatter = frontmatterMatch ? frontmatterMatch[1] : '';
+    const body = content.slice(frontmatter.length);
+    const h1Match = body.match(/^(\s*\r?\n)*(#\s+[^\n]+\r?\n)/);
+    if (!h1Match) {
+        throw new Error(`Page ${slug} has no H1 heading; resolve the missing-h1 finding before rewriting the summary.`);
+    }
+    const headerBlock = h1Match[0];
+    const afterHeader = body.slice(headerBlock.length);
+    // Identify the existing first paragraph: skip leading blank lines, then capture lines
+    // until the next blank line OR a heading. Everything after that is the rest of the page.
+    const lines = afterHeader.split(/\r?\n/);
+    let cursor = 0;
+    while (cursor < lines.length && lines[cursor].trim() === '') {
+        cursor += 1;
+    }
+    const paragraphStart = cursor;
+    while (cursor < lines.length) {
+        const line = lines[cursor];
+        if (line.trim() === '' || line.startsWith('#')) {
+            break;
+        }
+        cursor += 1;
+    }
+    const previousSummary = lines.slice(paragraphStart, cursor).join('\n').trim();
+    const remainder = lines.slice(cursor).join('\n');
+    const remainderNoLeadingBlank = remainder.replace(/^\r?\n+/, '');
+    if (previousSummary === trimmedNew) {
+        return { slug, changed: false, previousSummary, newSummary: trimmedNew };
+    }
+    const next = `${frontmatter}${headerBlock}\n${trimmedNew}\n\n${remainderNoLeadingBlank}`;
+    const finalText = next.endsWith('\n') ? next : `${next}\n`;
+    await fs.writeFile(filePath, finalText, 'utf8');
+    invalidateWikiContextCache();
+    return { slug, changed: true, previousSummary, newSummary: trimmedNew };
+}
+// Archive a dormant guidance file (e.g., a skill markdown that no other doc links to)
+// by moving it into a sibling `archive/` directory. Idempotent: if the file is already
+// under an `archive/` segment, returns the existing path with no work. The caller is
+// expected to pass a relative-from-repo-root path (matching the lint finding's `path`).
+export async function archiveGuidanceFile(relativePath) {
+    const trimmed = relativePath.trim().replace(/\\/g, '/');
+    if (!trimmed || trimmed.includes('..')) {
+        throw new Error(`Invalid guidance path for archive: ${relativePath}`);
+    }
+    const absoluteFrom = path.resolve(repoRoot, trimmed);
+    const stat = await fs.stat(absoluteFrom).catch(() => undefined);
+    if (!stat || !stat.isFile()) {
+        throw new Error(`Guidance file not found: ${trimmed}`);
+    }
+    const dir = path.posix.dirname(trimmed);
+    const fileName = path.posix.basename(trimmed);
+    if (dir.split('/').includes('archive')) {
+        return { from: trimmed, to: trimmed, moved: false };
+    }
+    const archiveDir = `${dir}/archive`;
+    const archiveRelative = `${archiveDir}/${fileName}`;
+    const absoluteTo = path.resolve(repoRoot, archiveRelative);
+    await fs.mkdir(path.dirname(absoluteTo), { recursive: true });
+    await fs.rename(absoluteFrom, absoluteTo);
+    invalidateWikiContextCache();
+    return { from: trimmed, to: archiveRelative, moved: true };
+}
+export function extractWikiPageMetadata(content) {
+    const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/)?.[1] ?? '';
+    const fields = new Map(frontmatter
+        .split(/\r?\n/)
+        .map((line) => line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$/))
+        .filter((match) => Boolean(match))
+        .map((match) => [normalizeMetadataKey(match[1]), match[2].replace(/^['"]|['"]$/g, '')]));
+    return {
+        lifecycle: parsePageLifecycle(fields.get('lifecycle')),
+        owner: fields.get('owner') || 'unassigned',
+        lastReviewed: fields.get('lastreviewed') || fields.get('last-reviewed') || '',
+        sourceCoverage: parseSourceCoverage(fields.get('sourcecoverage') || fields.get('source-coverage'))
+    };
+}
+function normalizeMetadataKey(value) {
+    return value.toLowerCase().replace(/_/g, '-');
+}
+function parsePageLifecycle(value) {
+    switch (value?.trim()) {
+        case 'dormant':
+        case 'superseded':
+        case 'pending-review':
+        case 'generated':
+            return value.trim();
+        default:
+            return 'active';
+    }
+}
+function parseSourceCoverage(value) {
+    switch (value?.trim()) {
+        case 'none':
+        case 'partial':
+        case 'complete':
+            return value.trim();
+        default:
+            return 'unknown';
+    }
+}
+export async function listWikiPages() {
+    const pages = [];
+    async function walk(directory) {
+        const entries = await fs.readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.md')) {
+                continue;
+            }
+            const relative = path.relative(wikiRoot, fullPath).replace(/\\/g, '/');
+            const slug = relative.replace(/\.md$/i, '');
+            const content = await fs.readFile(fullPath, 'utf8');
+            const title = content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? slug;
+            pages.push({ slug, title, path: `docs/wiki/${relative}`, metadata: extractWikiPageMetadata(content) });
+        }
+    }
+    await walk(wikiRoot);
+    return pages.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+export async function listGuidanceLifecycle() {
+    const [guidanceFiles, pages, proposals, findings] = await Promise.all([
+        listProjectGuidanceFiles(),
+        listWikiPages(),
+        listWikiProposals(),
+        lintWikiPages()
+    ]);
+    const linkedFromByPath = await collectMarkdownInboundSources(guidanceFiles, pages);
+    const proposalByPath = new Map();
+    const archiveTargetByPath = new Map();
+    for (const proposal of proposals) {
+        if (proposal.kind === 'merge-guidance') {
+            for (const duplicatePath of proposal.duplicatePaths) {
+                proposalByPath.set(duplicatePath, proposal);
+            }
+            for (const archiveTarget of proposal.archiveTargets) {
+                archiveTargetByPath.set(archiveTarget.sourcePath, archiveTarget.suggestedPath);
+            }
+        }
+        else {
+            proposalByPath.set(proposal.guidancePath, proposal);
+        }
+    }
+    const dormantPaths = new Set(findings.filter((finding) => finding.rule === 'dormant-skill').map((finding) => finding.path));
+    return guidanceFiles.map((guidance) => {
+        const linkedFrom = linkedFromByPath.get(guidance.path) ?? [];
+        const proposal = proposalByPath.get(guidance.path);
+        const archiveTarget = archiveTargetByPath.get(guidance.path);
+        if (proposal) {
+            return {
+                ...guidance,
+                status: 'pending-review',
+                linkedFrom,
+                archiveTarget,
+                reviewStatus: 'pending-review',
+                reason: `Active ${proposal.kind} proposal is waiting for operator review.`
+            };
+        }
+        if (archiveTarget) {
+            return {
+                ...guidance,
+                status: 'superseded',
+                linkedFrom,
+                archiveTarget,
+                reviewStatus: 'pending-review',
+                reason: 'Guidance has a concrete archive destination after review.'
+            };
+        }
+        if (dormantPaths.has(guidance.path)) {
+            return {
+                ...guidance,
+                status: 'dormant',
+                linkedFrom,
+                reviewStatus: 'none',
+                reason: 'Guidance is not linked from project docs or active guidance files.'
+            };
+        }
+        return {
+            ...guidance,
+            status: 'active',
+            linkedFrom,
+            reviewStatus: 'none',
+            reason: linkedFrom.length > 0 ? 'Guidance is linked from project docs or another active guidance file.' : 'Guidance is an active entry file.'
+        };
+    }).sort((left, right) => left.status.localeCompare(right.status) || left.path.localeCompare(right.path));
+}
+export async function lintWikiPages() {
+    const pages = await listWikiPages();
+    const findings = [];
+    const inboundLinks = await collectInboundWikiLinks(pages);
+    const pageByPath = new Map(pages.map((page) => [page.path, page.slug]));
+    const guidanceFiles = await listProjectGuidanceFiles();
+    // Read project-log once so per-page drift detection doesn't re-read for each page.
+    const projectLogContent = await fs.readFile(pagePathFromSlug('project-log'), 'utf8').catch(() => '');
+    // Load active page-drift snoozes so we can suppress findings the operator has already
+    // acknowledged as noise. Expired snoozes are pruned lazily inside the loader.
+    const snoozedPageDrifts = await loadActivePageDriftSnoozes().catch(() => new Map());
+    // Load active project-local memories once for the contradicts-shipped-memory rule.
+    // Includes superseded records because being promoted-then-superseded still proves the
+    // feature exists in the wiki — that's the strongest possible evidence against a
+    // "this is missing" assertion.
+    const activeMemoriesForContradictionCheck = await listProjectMemories({ includeArchived: true })
+        .then((records) => records.filter((record) => record.status === 'active' || record.status === 'superseded'))
+        .catch(() => []);
+    for (const page of pages) {
+        // Generated pages are managed by the API reference generator (or any future
+        // generator that uses the same `lifecycle: generated` frontmatter convention).
+        // Their source of truth lives outside the wiki — humans don't review them, and
+        // surfacing lint findings on them in the maintenance inbox is noise. Skip every
+        // per-page rule for these.
+        if (page.metadata?.lifecycle === 'generated') {
+            continue;
+        }
+        const content = await readWikiPage(page.slug);
+        if (!hasH1(content)) {
+            findings.push({
+                rule: 'missing-h1',
+                slug: page.slug,
+                path: page.path,
+                message: 'Page is missing a top-level H1 heading.'
+            });
+        }
+        if (!hasSummaryParagraph(content)) {
+            findings.push({
+                rule: 'missing-summary',
+                slug: page.slug,
+                path: page.path,
+                message: 'Page is missing a short summary paragraph after its H1.'
+            });
+        }
+        if ((inboundLinks.get(page.slug) ?? 0) === 0) {
+            findings.push({
+                rule: 'orphan-page',
+                slug: page.slug,
+                path: page.path,
+                message: 'Page is not linked from the project index or another wiki page.'
+            });
+        }
+        for (const claim of extractWikiClaims(page.slug, content, pageByPath)) {
+            if (claim.sources.length === 0) {
+                findings.push({
+                    rule: 'unsupported-claim',
+                    slug: page.slug,
+                    path: page.path,
+                    message: `Claim is missing supporting sources: ${claim.text}`
+                });
+            }
+            if (claim.status === 'current') {
+                continue;
+            }
+            findings.push({
+                rule: 'stale-claim',
+                slug: page.slug,
+                path: page.path,
+                message: `Claim is marked ${claim.status}: ${claim.text}`
+            });
+        }
+        // Page drift: only check pages that aren't the project-log itself (which trivially mentions every other page).
+        // Skip pages the operator has snoozed — these are findings already acknowledged as noise.
+        if (page.slug !== 'project-log' && projectLogContent && !snoozedPageDrifts.has(page.slug)) {
+            const drift = detectPageDrift(content, page.slug, projectLogContent);
+            if (drift) {
+                findings.push({
+                    rule: 'page-drift',
+                    slug: page.slug,
+                    path: page.path,
+                    message: buildPageDriftMessage(drift)
+                });
+            }
+        }
+        // contradicts-shipped-memory: catch sections that claim X doesn't exist while shipped
+        // memories say it does. Skipped on the project-log itself (chronological log of changes,
+        // not a claims surface) — same exclusion as page-drift, for the same reason.
+        if (page.slug !== 'project-log' && activeMemoriesForContradictionCheck.length > 0) {
+            const contradictions = detectContradictsShippedMemory(content, activeMemoriesForContradictionCheck, projectLogContent);
+            for (const signal of contradictions) {
+                findings.push({
+                    rule: 'contradicts-shipped-memory',
+                    slug: page.slug,
+                    path: page.path,
+                    message: buildContradictsShippedMemoryMessage(signal)
+                });
+            }
+        }
+    }
+    for (const guidance of guidanceFiles) {
+        const content = await fs.readFile(path.join(repoRoot, guidance.path), 'utf8').catch(() => '');
+        const lineCount = countLines(content);
+        if (lineCount > maxGuidanceLineCount) {
+            findings.push({
+                rule: 'oversized-guidance',
+                slug: guidance.path,
+                path: guidance.path,
+                message: `Guidance file exceeds ${maxGuidanceLineCount} lines: ${guidance.path} (${lineCount} lines).`
+            });
+        }
+        for (const brokenLink of findBrokenGuidanceLinks(content, guidance.path)) {
+            findings.push({
+                rule: 'stale-guidance-reference',
+                slug: guidance.path,
+                path: guidance.path,
+                message: `Guidance file links to missing markdown: ${brokenLink}`
+            });
+        }
+        if (guidance.kind !== 'skill' && !hasGuidanceRoute(content, guidance.path)) {
+            findings.push({
+                rule: 'unrouted-guidance',
+                slug: guidance.path,
+                path: guidance.path,
+                message: 'Guidance file should link to at least one canonical local docs page.'
+            });
+        }
+    }
+    const guidanceInboundLinks = await collectMarkdownInboundLinks(guidanceFiles, pages);
+    for (const guidance of guidanceFiles.filter((candidate) => candidate.kind === 'skill')) {
+        if ((guidanceInboundLinks.get(guidance.path) ?? 0) > 0) {
+            continue;
+        }
+        findings.push({
+            rule: 'dormant-skill',
+            slug: guidance.path,
+            path: guidance.path,
+            message: 'Skill file is not linked from project docs or active guidance files.'
+        });
+    }
+    for (const duplicateGroup of await findDuplicateGuidanceGroups()) {
+        const joinedPaths = duplicateGroup.map((guidance) => guidance.path).sort().join(', ');
+        for (const guidance of duplicateGroup) {
+            findings.push({
+                rule: 'duplicate-guidance',
+                slug: guidance.path,
+                path: guidance.path,
+                message: `Guidance content duplicates: ${joinedPaths}`
+            });
+        }
+    }
+    for (const conflict of await findConflictingGuidanceRules()) {
+        const joinedPaths = conflict.paths.join(', ');
+        for (const guidancePath of conflict.paths) {
+            findings.push({
+                rule: 'conflicting-guidance',
+                slug: guidancePath,
+                path: guidancePath,
+                message: `Guidance conflicts on "${conflict.rule}": ${joinedPaths}`
+            });
+        }
+    }
+    return findings.sort((a, b) => a.slug.localeCompare(b.slug) || a.rule.localeCompare(b.rule));
+}
+export async function searchWikiPages(query) {
+    const index = await buildCurrentWikiSearchIndex();
+    return searchWikiIndex(index, query);
+}
+export async function buildWikiContext(query, options = {}) {
+    const cached = getCachedWikiContext(query, options);
+    if (cached) {
+        return cached;
+    }
+    const maxPages = Math.max(1, options.maxPages ?? defaultContextPageLimit);
+    const maxLogEntries = Math.max(0, options.maxLogEntries ?? defaultLogEntryLimit);
+    const maxSkills = Math.max(1, Math.min(options.maxSkills ?? 3, 20));
+    const index = await buildCurrentWikiSearchIndex();
+    const queryTerms = tokenizeSearchQuery(query);
+    const searchResults = searchWikiIndex(index, query);
+    const rankedResults = searchResults.length > 0 ? searchResults : fallbackSearchResults(index);
+    const selectedResults = rankedResults.slice(0, maxPages);
+    // Cap the omittedPageReasons payload: 96+ omitted entries with full reason strings
+    // can dominate the wiki_context payload (single largest contributor at session start).
+    // The full omitted count is still reported via `omittedPages`; the reasons here are
+    // a triage hint, not a full audit trail. Operators who want more can wiki_search.
+    const maxOmittedPageReasons = Math.max(0, options.maxOmittedPageReasons ?? 12);
+    const maxOmittedReasonChars = Math.max(20, options.maxOmittedReasonChars ?? 80);
+    const omittedPageReasons = rankedResults
+        .slice(maxPages, maxPages + maxOmittedPageReasons)
+        .map((result) => ({
+        slug: result.slug,
+        score: result.score,
+        reason: truncateForBriefing(result.reasons.join('; '), maxOmittedReasonChars)
+    }));
+    const selectedPages = selectedResults.map((result) => searchResultToContextPage(result));
+    // Memory Trails: page→query edges (shadow mode for the bonus, active for reinforcement).
+    // Reinforcement runs unconditionally so edges accrue from real usage. Bonus is surfaced
+    // as a `[shadow] page recall trail: ...` reason on each page that has accumulated edges,
+    // but is NOT added to the score yet — same kill-switch principle as the bipartite
+    // projection shadow mode. Watch the recall benchmark before promoting to active ranking.
+    const pageTrailLookup = await loadMemoryTrailBonusLookup('page', query).catch(() => () => undefined);
+    for (const page of selectedPages) {
+        const bonus = pageTrailLookup(page.slug);
+        if (bonus) {
+            const trailReason = `[shadow] page recall trail: ${buildMemoryTrailReason(bonus)} (not yet applied to ranking)`;
+            page.reason = page.reason ? `${page.reason}; ${trailReason}` : trailReason;
+        }
+    }
+    if (selectedPages.length > 0) {
+        await reinforceQueryEdges('page', selectedPages.map((page) => page.slug), query).catch(() => undefined);
+    }
+    const recentLogEntries = maxLogEntries > 0 ? await listRecentProjectLogEntries(maxLogEntries) : [];
+    const findings = options.includeLint === false ? [] : await lintWikiPages();
+    const handoffs = await recallProjectHandoffs({
+        relatedPages: selectedPages.map((page) => page.slug),
+        maxItems: Math.max(1, Math.min(maxPages, 2))
+    });
+    const memories = (await recallProjectMemories(query, {
+        relatedPages: selectedPages.map((page) => page.slug),
+        maxItems: Math.max(1, Math.min(maxPages, 5))
+    })).filter((memory) => memory.kind !== 'handoff' && !handoffs.some((handoff) => handoff.id === memory.id));
+    const skills = await recallProjectSkills({
+        query,
+        relatedFiles: options.relatedFiles,
+        languages: options.languages,
+        frameworks: options.frameworks,
+        maxItems: maxSkills
+    });
+    const claims = rankContextClaims(selectedResults.flatMap((result) => index.pages.find((document) => document.page.slug === result.slug)?.claims ?? []), queryTerms).slice(0, maxPages * 2);
+    const guidanceFiles = await listProjectGuidanceFiles();
+    const openQuestions = buildOpenQuestions(claims, findings);
+    // Brain-faithfulness roadmap B5: surface the unprocessed memory backlog so the
+    // briefing tells the operator/agent what is sitting in the inbox waiting for
+    // triage. Lightweight — counts only, no findings list.
+    const memoryBacklog = await summarizeMemoryBacklog().catch(() => ({
+        promotionReady: 0,
+        skillPromotionReady: 0,
+        staleUnsupported: 0,
+        total: 0
+    }));
+    // Cap handoff/memory/skill body text in the briefing payload. The recall functions
+    // return full records; the briefing is meant to be a *briefing*, not a memory dump.
+    // Full bodies remain available via memory_recall, wiki_skill_load, and (for handoffs)
+    // a memory_recall call by id. Truncated records still carry every other field — ids,
+    // tags, sources, relatedFiles, recallCount — so the agent knows exactly what to fetch
+    // for a deeper read.
+    const maxHandoffTextChars = Math.max(120, options.maxHandoffTextChars ?? 1200);
+    const maxMemoryTextChars = Math.max(120, options.maxMemoryTextChars ?? 600);
+    const maxSkillTextChars = Math.max(120, options.maxSkillTextChars ?? 800);
+    const trimmedHandoffs = handoffs.map((handoff) => ({
+        ...handoff,
+        text: truncateForBriefing(handoff.text, maxHandoffTextChars)
+    }));
+    const trimmedMemories = memories.map((memory) => ({
+        ...memory,
+        text: truncateForBriefing(memory.text, maxMemoryTextChars)
+    }));
+    const trimmedSkills = skills.map((skill) => ({
+        ...skill,
+        text: truncateForBriefing(skill.text, maxSkillTextChars)
+    }));
+    const result = {
+        query,
+        briefing: buildContextBriefing(selectedPages, trimmedHandoffs, trimmedMemories, trimmedSkills, claims, guidanceFiles, recentLogEntries, findings, omittedPageReasons, memoryBacklog),
+        readFirst: selectedPages.map((page) => page.slug),
+        handoffs: trimmedHandoffs,
+        pages: selectedPages,
+        memories: trimmedMemories,
+        skills: trimmedSkills,
+        claims,
+        guidanceFiles,
+        omittedPages: Math.max(rankedResults.length - maxPages, 0),
+        omittedPageReasons,
+        recentLogEntries,
+        findings,
+        openQuestions,
+        memoryBacklog
+    };
+    setCachedWikiContext(query, options, result);
+    return result;
+}
+export async function buildWikiGraphSnapshot() {
+    const index = await buildCurrentWikiSearchIndex();
+    const nodes = index.pages.map(({ page, claims }) => {
+        const graph = index.graph.get(page.slug) ?? {
+            slug: page.slug,
+            inboundLinks: 0,
+            outgoingLinks: [],
+            relatedPages: []
+        };
+        return {
+            ...graph,
+            title: page.title,
+            path: page.path,
+            claimCount: claims.length,
+            staleClaimCount: claims.filter((claim) => claim.status !== 'current').length
+        };
+    });
+    return {
+        pages: nodes.length,
+        nodes: nodes.sort((left, right) => left.slug.localeCompare(right.slug))
+    };
+}
+async function buildCurrentWikiSearchIndex() {
+    const pages = await listWikiPages();
+    const pageByPath = new Map(pages.map((page) => [page.path, page.slug]));
+    const documents = await Promise.all(pages.map(async (page) => {
+        const content = await readWikiPage(page.slug);
+        return {
+            page,
+            content,
+            claims: extractWikiClaims(page.slug, content, pageByPath)
+        };
+    }));
+    const indexContent = await fs.readFile(path.join(docsRoot, 'index.md'), 'utf8').catch(() => '');
+    return buildWikiSearchIndex({ pages: documents, indexContent });
+}
+async function collectInboundWikiLinks(pages) {
+    const counts = new Map(pages.map((page) => [page.slug, 0]));
+    const pageByPath = new Map(pages.map((page) => [page.path, page.slug]));
+    const sources = [
+        { path: 'docs/index.md', content: await fs.readFile(path.join(docsRoot, 'index.md'), 'utf8').catch(() => '') },
+        ...(await Promise.all(pages.map(async (page) => ({ path: page.path, content: await readWikiPage(page.slug) }))))
+    ];
+    for (const source of sources) {
+        const sourceDir = path.posix.dirname(source.path);
+        for (const link of extractMarkdownLinks(source.content)) {
+            const linkedSlug = resolveWikiLinkSlug(link, sourceDir, pageByPath);
+            if (!linkedSlug) {
+                continue;
+            }
+            counts.set(linkedSlug, (counts.get(linkedSlug) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+function hasH1(content) {
+    return /^#\s+\S+/m.test(content);
+}
+function hasSummaryParagraph(content) {
+    const lines = content.split(/\r?\n/);
+    const h1Index = lines.findIndex((line) => /^#\s+\S+/.test(line));
+    if (h1Index === -1) {
+        return false;
+    }
+    for (const line of lines.slice(h1Index + 1)) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        if (trimmed.startsWith('#')) {
+            return false;
+        }
+        return !trimmed.startsWith('|') && !trimmed.startsWith('- ') && !/^\d+\.\s/.test(trimmed);
+    }
+    return false;
+}
+function extractSummaryParagraph(content) {
+    const lines = content.split(/\r?\n/);
+    const h1Index = lines.findIndex((line) => /^#\s+\S+/.test(line));
+    const bodyLines = lines.slice(h1Index === -1 ? 0 : h1Index + 1);
+    for (const line of bodyLines) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        if (trimmed.startsWith('#') || trimmed.startsWith('|') || trimmed.startsWith('- ') || /^\d+\.\s/.test(trimmed)) {
+            continue;
+        }
+        return trimmed;
+    }
+    return '';
+}
+function tokenizeQuery(query) {
+    return Array.from(new Set(query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .map((part) => part.trim())
+        .filter((part) => part.length >= 2 && !contextStopTerms.has(part))));
+}
+function scoreContextPage(page, content, queryTerms, inboundLinks, pageByPath) {
+    const summary = extractSummaryParagraph(content) || page.title;
+    const title = page.title.toLowerCase();
+    const slug = page.slug.toLowerCase();
+    const haystack = content.toLowerCase();
+    const reasons = new Set();
+    const matchedTerms = new Set();
+    let score = 0;
+    for (const term of queryTerms) {
+        if (title.includes(term)) {
+            score += 6;
+            reasons.add(`title matches "${term}"`);
+            matchedTerms.add(term);
+        }
+        else if (slug.includes(term)) {
+            score += 5;
+            reasons.add(`slug matches "${term}"`);
+            matchedTerms.add(term);
+        }
+        if (haystack.includes(term)) {
+            score += 2;
+            reasons.add(`content mentions "${term}"`);
+            matchedTerms.add(term);
+        }
+    }
+    if (page.slug === 'project-log' && queryTerms.some((term) => projectLogHintTerms.has(term))) {
+        score += 4;
+        reasons.add('project log helps with recent changes');
+    }
+    if (score > 0 || queryTerms.length === 0) {
+        const inboundCount = inboundLinks.get(page.slug) ?? 0;
+        if (inboundCount > 0) {
+            score += Math.min(inboundCount, 3);
+            reasons.add(inboundCount > 1 ? `${inboundCount} inbound links` : 'linked from the wiki');
+        }
+    }
+    const inboundCount = inboundLinks.get(page.slug) ?? 0;
+    const relatedPages = extractRelatedWikiSlugs(content, page.path, pageByPath).slice(0, 3);
+    return {
+        ...page,
+        score,
+        summary,
+        reason: Array.from(reasons).slice(0, 3).join('; ') || 'fallback page for broad project briefing',
+        evidence: {
+            matchedTerms: Array.from(matchedTerms),
+            inboundLinks: inboundCount,
+            relatedPages
+        }
+    };
+}
+function fallbackContextPage(page, inboundLinks) {
+    const inboundCount = inboundLinks.get(page.slug) ?? 0;
+    let score = Math.min(inboundCount, 3);
+    let reason = inboundCount > 0 ? `fallback page with ${inboundCount} inbound links` : 'fallback page for broad project briefing';
+    if (page.slug === 'architecture') {
+        score += 4;
+        reason = 'default architecture briefing page';
+    }
+    else if (page.slug === 'project-log') {
+        score += 3;
+        reason = 'default recent changes briefing page';
+    }
+    return {
+        ...page,
+        score,
+        reason,
+        evidence: {
+            ...page.evidence,
+            inboundLinks: inboundCount
+        }
+    };
+}
+function buildContextBriefing(pages, handoffs, memories, skills, claims, guidanceFiles, recentLogEntries, findings, omittedPageReasons, memoryBacklog) {
+    const lines = [];
+    // Brain-faithfulness roadmap B5: surface unprocessed memory backlog so the agent
+    // sees waiting triage work at every wiki_context call. Cache invalidates on any
+    // memory mutation so the banner stays accurate; suppressed entirely when zero.
+    if (memoryBacklog.total > 0) {
+        const parts = [];
+        if (memoryBacklog.promotionReady > 0) {
+            parts.push(`${memoryBacklog.promotionReady} promotion-ready`);
+        }
+        if (memoryBacklog.skillPromotionReady > 0) {
+            parts.push(`${memoryBacklog.skillPromotionReady} skill-promotion-ready`);
+        }
+        if (memoryBacklog.staleUnsupported > 0) {
+            parts.push(`${memoryBacklog.staleUnsupported} stale-unsupported`);
+        }
+        lines.push(`Memory backlog: ${parts.join(', ')} memor${memoryBacklog.total === 1 ? 'y' : 'ies'} waiting in the inbox. Call wiki_maintenance_inbox to triage, or memory_review for the full findings list.`);
+    }
+    if (pages.length > 0) {
+        const readFirst = pages.map((page) => page.slug).join(', ');
+        lines.push(`Read first: ${readFirst}.`);
+        lines.push(`Top page: ${pages[0]?.slug} because ${pages[0]?.reason}.`);
+    }
+    if (recentLogEntries.length > 0) {
+        lines.push(`${recentLogEntries.length} recent project log entr${recentLogEntries.length === 1 ? 'y is' : 'ies are'} included.`);
+    }
+    if (handoffs.length > 0) {
+        lines.push(`${handoffs.length} recent session handoff${handoffs.length === 1 ? ' is' : 's are'} included.`);
+    }
+    if (memories.length > 0) {
+        lines.push(`${memories.length} project-local memor${memories.length === 1 ? 'y is' : 'ies are'} included.`);
+    }
+    if (skills.length > 0) {
+        lines.push(`${skills.length} matching skill${skills.length === 1 ? '' : 's'} included; call wiki_skill_load(id) for full content.`);
+    }
+    if (claims.length > 0) {
+        lines.push(`${claims.length} source-backed claim${claims.length === 1 ? ' is' : 's are'} included.`);
+    }
+    if (guidanceFiles.length > 0) {
+        lines.push(`${guidanceFiles.length} project guidance file${guidanceFiles.length === 1 ? ' is' : 's are'} included.`);
+    }
+    if (omittedPageReasons.length > 0) {
+        const omittedSummary = omittedPageReasons
+            .slice(0, 3)
+            .map((page) => `${page.slug} (${page.reason})`)
+            .join('; ');
+        lines.push(`${omittedPageReasons.length} ranked page${omittedPageReasons.length === 1 ? ' was' : 's were'} omitted by the page budget: ${omittedSummary}.`);
+    }
+    if (findings.length === 0) {
+        lines.push('No current lint findings are blocking the briefing.');
+    }
+    else {
+        lines.push(`${findings.length} lint finding${findings.length === 1 ? '' : 's'} should be treated as context risk.`);
+    }
+    return lines.join(' ');
+}
+// Trim a body field for inclusion in the wiki_context briefing payload. Appends an
+// ellipsis when truncated so the agent can tell at a glance that the full body lives
+// elsewhere (call wiki_skill_load / memory_recall by id to fetch it).
+function truncateForBriefing(text, maxChars) {
+    if (!text || text.length <= maxChars)
+        return text;
+    return `${text.slice(0, Math.max(1, maxChars - 1)).trimEnd()}…`;
+}
+export async function listProjectGuidanceFiles() {
+    const results = new Map();
+    const candidateFiles = [
+        { relativePath: 'AGENTS.md', kind: 'agents' },
+        { relativePath: '.github/copilot-instructions.md', kind: 'copilot-instructions' }
+    ];
+    const candidateDirectories = [
+        { relativeDir: '.github/instructions', kind: 'instruction', pattern: /\.instructions\.md$/i },
+        { relativeDir: '.github/prompts', kind: 'prompt', pattern: /\.prompt\.md$/i },
+        { relativeDir: '.github/agents', kind: 'agent', pattern: /\.agent\.md$/i },
+        { relativeDir: 'skills', kind: 'skill', pattern: /SKILL\.md$/i }
+    ];
+    for (const candidate of candidateFiles) {
+        const guidance = await readGuidanceFile(repoRoot, candidate.relativePath, candidate.kind);
+        if (guidance) {
+            results.set(guidance.path, guidance);
+        }
+    }
+    for (const candidate of candidateDirectories) {
+        for (const relativePath of await findGuidanceFiles(path.join(repoRoot, candidate.relativeDir), candidate.pattern, repoRoot)) {
+            const guidance = await readGuidanceFile(repoRoot, relativePath, candidate.kind);
+            if (guidance) {
+                results.set(guidance.path, guidance);
+            }
+        }
+    }
+    return Array.from(results.values()).sort((left, right) => left.path.localeCompare(right.path));
+}
+async function readGuidanceFile(repoRoot, relativePath, kind) {
+    const absolutePath = path.join(repoRoot, relativePath);
+    // Retry transient empty/error reads. Observed on ubuntu-latest CI: the same
+    // guidance file (e.g. AGENTS.md, 2222 bytes, untouched on disk) intermittently
+    // returns empty content from fs.readFile when many sequential reads happen
+    // through the test suite, which silently drops the file from the guidance
+    // listing and cascades into surprising downstream test failures (lint
+    // findings missing, route-guidance proposals not generated, etc.).
+    //
+    // We treat this as a transient I/O hiccup and retry up to 3 times with brief
+    // backoff. ENOENT (file genuinely doesn't exist) is the common
+    // "skip silently" path so it short-circuits the retry. Any other error code
+    // is surfaced via console.warn on the final retry so a real bug doesn't hide
+    // behind the silent-failure semantic.
+    let lastErr;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        let content;
+        try {
+            content = await fs.readFile(absolutePath, 'utf8');
+        }
+        catch (err) {
+            const e = err;
+            if (e?.code === 'ENOENT') {
+                // File doesn't exist — caller's contract is "return undefined" silently.
+                return undefined;
+            }
+            lastErr = e;
+        }
+        if (content) {
+            return {
+                path: relativePath.replace(/\\/g, '/'),
+                kind,
+                summary: extractSummaryParagraph(content) || path.basename(relativePath)
+            };
+        }
+        if (attempt < 2) {
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
+    if (lastErr) {
+        // eslint-disable-next-line no-console
+        console.warn(`[dendrite] readGuidanceFile: persistent error reading ${relativePath} (${lastErr.code ?? 'unknown'}): ${lastErr.message}. Returning undefined; downstream lint/proposals will not see this guidance file.`);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.warn(`[dendrite] readGuidanceFile: ${relativePath} read returned empty content on 3 attempts. Returning undefined; downstream lint/proposals will not see this guidance file. If you can reproduce this on CI, please open an issue with the runner OS and Node version.`);
+    }
+    return undefined;
+}
+async function findGuidanceFiles(directory, pattern, repoRoot) {
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    const matches = [];
+    for (const entry of entries) {
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            matches.push(...(await findGuidanceFiles(fullPath, pattern, repoRoot)));
+            continue;
+        }
+        if (entry.isFile() && pattern.test(entry.name)) {
+            matches.push(path.relative(repoRoot, fullPath));
+        }
+    }
+    return matches;
+}
+async function collectMarkdownInboundLinks(guidanceFiles, pages) {
+    const sources = await collectMarkdownInboundSources(guidanceFiles, pages);
+    return new Map([...sources.entries()].map(([targetPath, sourcePaths]) => [targetPath, sourcePaths.length]));
+}
+async function collectMarkdownInboundSources(guidanceFiles, pages) {
+    const inboundLinks = new Map(guidanceFiles.map((guidance) => [guidance.path, 0]));
+    const inboundSources = new Map(guidanceFiles.map((guidance) => [guidance.path, []]));
+    const sourceFiles = [
+        'docs/index.md',
+        'docs/project-plan.md',
+        ...pages.map((page) => page.path),
+        ...guidanceFiles.map((guidance) => guidance.path)
+    ];
+    for (const sourcePath of Array.from(new Set(sourceFiles)).sort()) {
+        const content = await fs.readFile(path.join(repoRoot, sourcePath), 'utf8').catch(() => '');
+        const sourceDir = path.posix.dirname(sourcePath);
+        for (const link of extractMarkdownLinks(content)) {
+            const targetPath = resolveMarkdownLinkPath(link, sourceDir);
+            if (!targetPath || targetPath === sourcePath || !inboundLinks.has(targetPath)) {
+                continue;
+            }
+            inboundLinks.set(targetPath, (inboundLinks.get(targetPath) ?? 0) + 1);
+            inboundSources.get(targetPath)?.push(sourcePath);
+        }
+    }
+    return new Map([...inboundSources.entries()].map(([targetPath, sourcePaths]) => [
+        targetPath,
+        Array.from(new Set(sourcePaths)).sort((left, right) => left.localeCompare(right))
+    ]));
+}
+async function findDuplicateGuidanceGroups() {
+    const guidanceFiles = await listProjectGuidanceFiles();
+    const fingerprintGroups = new Map();
+    for (const guidance of guidanceFiles) {
+        const content = await fs.readFile(path.join(repoRoot, guidance.path), 'utf8').catch(() => '');
+        const fingerprint = buildGuidanceFingerprint(content);
+        if (!fingerprint) {
+            continue;
+        }
+        const group = fingerprintGroups.get(fingerprint) ?? [];
+        group.push(guidance);
+        fingerprintGroups.set(fingerprint, group);
+    }
+    return Array.from(fingerprintGroups.values())
+        .filter((group) => group.length > 1)
+        .map((group) => group.sort((left, right) => left.path.localeCompare(right.path)));
+}
+async function findConflictingGuidanceRules() {
+    const guidanceFiles = await listProjectGuidanceFiles();
+    const directiveMap = new Map();
+    for (const guidance of guidanceFiles) {
+        const content = await fs.readFile(path.join(repoRoot, guidance.path), 'utf8').catch(() => '');
+        for (const directive of extractGuidanceDirectives(content)) {
+            const current = directiveMap.get(directive.rule) ?? { positive: new Set(), negative: new Set() };
+            current[directive.polarity].add(guidance.path);
+            directiveMap.set(directive.rule, current);
+        }
+    }
+    return Array.from(directiveMap.entries())
+        .filter(([, polarities]) => polarities.positive.size > 0 && polarities.negative.size > 0)
+        .map(([rule, polarities]) => ({
+        rule,
+        paths: Array.from(new Set([...polarities.positive, ...polarities.negative])).sort((left, right) => left.localeCompare(right))
+    }));
+}
+function extractGuidanceDirectives(content) {
+    return Array.from(new Map(content
+        .split(/\r?\n/)
+        .map((line) => parseGuidanceDirective(line))
+        .filter((directive) => Boolean(directive))
+        .map((directive) => [`${directive.polarity}:${directive.rule}`, directive])).values());
+}
+function parseGuidanceDirective(line) {
+    const trimmed = line.trim();
+    if (!trimmed || /^#/.test(trimmed)) {
+        return undefined;
+    }
+    const normalized = trimmed
+        .replace(/^[-*]\s+/, '')
+        .replace(/^\d+\.\s+/, '')
+        .replace(/[.?!]+$/, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const negativeMatch = normalized.match(/^(do not|don't|never|avoid|must not|should not)\s+(.+)$/i);
+    if (negativeMatch) {
+        return { polarity: 'negative', rule: negativeMatch[2].trim().toLowerCase() };
+    }
+    const positiveMatch = normalized.match(/^(always|must|should|prefer)\s+(.+)$/i);
+    if (positiveMatch) {
+        return { polarity: 'positive', rule: positiveMatch[2].trim().toLowerCase() };
+    }
+    return undefined;
+}
+function buildGuidanceFingerprint(content) {
+    const normalizedLines = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line, index) => line.length > 0 && !(index === 0 && /^#\s+/.test(line)))
+        .map((line) => line.replace(/\[[^\]]+\]\(([^)]+)\)/g, (match, _target, offset, fullLine) => {
+        const labelMatch = fullLine.slice(offset).match(/^\[([^\]]+)\]\([^)]+\)/);
+        return labelMatch ? `[${labelMatch[1]}](link)` : match;
+    }))
+        .map((line) => line.replace(/\s+/g, ' '));
+    return normalizedLines.join('\n').toLowerCase();
+}
+function findBrokenGuidanceLinks(content, guidancePath) {
+    const sourceDir = path.posix.dirname(guidancePath);
+    return Array.from(new Set(extractMarkdownLinks(content).filter((link) => !guidanceLinkExists(link, sourceDir)))).sort();
+}
+function hasGuidanceRoute(content, guidancePath) {
+    const sourceDir = path.posix.dirname(guidancePath);
+    return extractMarkdownLinks(content).some((link) => guidanceLinkExists(link, sourceDir) && isDocsRoute(link, sourceDir));
+}
+function listGuidanceRouteTargets(content, guidancePath) {
+    const sourceDir = path.posix.dirname(guidancePath);
+    return Array.from(new Set(extractMarkdownLinks(content)
+        .map((link) => resolveMarkdownLinkPath(link, sourceDir))
+        .filter((targetPath) => Boolean(targetPath))
+        .filter((targetPath) => targetPath.startsWith('docs/') && requirePathExists(path.join(repoRoot, targetPath))))).sort((left, right) => left.localeCompare(right));
+}
+function resolveMarkdownLinkPath(link, sourceDir) {
+    if (/^[a-z]+:/i.test(link) || path.isAbsolute(link)) {
+        return undefined;
+    }
+    return path.posix.normalize(path.posix.join(sourceDir, link.replace(/\\/g, '/')));
+}
+function guidanceLinkExists(link, sourceDir) {
+    const normalized = resolveMarkdownLinkPath(link, sourceDir);
+    if (!normalized) {
+        return true;
+    }
+    const absolutePath = path.join(repoRoot, normalized);
+    return requirePathExists(absolutePath);
+}
+function isDocsRoute(link, sourceDir) {
+    const normalized = resolveMarkdownLinkPath(link, sourceDir);
+    if (!normalized) {
+        return false;
+    }
+    return normalized.startsWith('docs/');
+}
+function requirePathExists(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function countLines(content) {
+    if (!content) {
+        return 0;
+    }
+    return content.split(/\r?\n/).length;
+}
+export function extractWikiClaims(pageSlug, content, pageByPath) {
+    const claimSection = stripFencedCodeBlocks(extractMarkdownSection(content, 'Claims'));
+    const pagePath = `docs/wiki/${pageSlug}.md`;
+    return claimSection
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('- ['))
+        .map((line) => parseClaimLine(line, pageSlug, pagePath, pageByPath))
+        .filter((claim) => claim !== undefined);
+}
+function extractMarkdownSection(content, heading) {
+    const lines = content.split(/\r?\n/);
+    let headingIndex = -1;
+    let activeFence;
+    for (const [index, line] of lines.entries()) {
+        const trimmed = line.trim();
+        const fenceMarker = trimmed.startsWith('```') ? '`' : trimmed.startsWith('~~~') ? '~' : undefined;
+        if (fenceMarker) {
+            if (!activeFence) {
+                activeFence = fenceMarker;
+            }
+            else if (activeFence === fenceMarker) {
+                activeFence = undefined;
+            }
+            continue;
+        }
+        if (!activeFence && trimmed === `## ${heading}`) {
+            headingIndex = index;
+            break;
+        }
+    }
+    if (headingIndex === -1) {
+        return '';
+    }
+    const sectionLines = [];
+    activeFence = undefined;
+    for (const line of lines.slice(headingIndex + 1)) {
+        const trimmed = line.trim();
+        const fenceMarker = trimmed.startsWith('```') ? '`' : trimmed.startsWith('~~~') ? '~' : undefined;
+        if (!activeFence && /^##\s+/.test(trimmed)) {
+            break;
+        }
+        sectionLines.push(line);
+        if (fenceMarker) {
+            if (!activeFence) {
+                activeFence = fenceMarker;
+            }
+            else if (activeFence === fenceMarker) {
+                activeFence = undefined;
+            }
+        }
+    }
+    return sectionLines.join('\n');
+}
+function stripFencedCodeBlocks(content) {
+    const lines = content.split(/\r?\n/);
+    const keptLines = [];
+    let activeFence;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        const fenceMarker = trimmed.startsWith('```') ? '`' : trimmed.startsWith('~~~') ? '~' : undefined;
+        if (fenceMarker) {
+            if (!activeFence) {
+                activeFence = fenceMarker;
+            }
+            else if (activeFence === fenceMarker) {
+                activeFence = undefined;
+            }
+            continue;
+        }
+        if (!activeFence) {
+            keptLines.push(line);
+        }
+    }
+    return keptLines.join('\n');
+}
+function parseClaimLine(line, pageSlug, pagePath, pageByPath) {
+    const match = line.match(/^- \[(current|needs-review|superseded|unknown)\]\s+(.+)$/i);
+    if (!match) {
+        return undefined;
+    }
+    const status = match[1].toLowerCase();
+    const body = match[2].trim();
+    return {
+        pageSlug,
+        text: body.replace(/\s*Sources:\s*.+$/i, '').trim(),
+        status,
+        sources: extractClaimSources(body, pagePath, pageByPath)
+    };
+}
+function extractClaimSources(body, pagePath, pageByPath) {
+    const sourceDir = path.posix.dirname(pagePath);
+    const sourceText = body.match(/\sSources:\s*(.+)$/i)?.[1]?.trim() ?? '';
+    const sources = new Map();
+    for (const match of sourceText.matchAll(/\[([^\]]+)\]\(([^)]+)\)/g)) {
+        const label = match[1]?.trim() ?? '';
+        const slug = resolveWikiLinkSlug(match[2]?.trim() ?? '', sourceDir, pageByPath);
+        if (slug) {
+            sources.set(`wiki:${slug}`, { kind: 'wiki', label, slug });
+        }
+    }
+    for (const rawSource of sourceText.replace(/\[[^\]]+\]\([^)]+\)/g, '').split(',')) {
+        const typedSource = parseTypedClaimSource(rawSource);
+        if (typedSource) {
+            sources.set(`${typedSource.kind}:${typedSource.slug}`, typedSource);
+        }
+    }
+    return Array.from(sources.values());
+}
+function parseTypedClaimSource(value) {
+    const match = value.trim().match(/^(file|command|decision):\s*(.+)$/i);
+    if (!match) {
+        return undefined;
+    }
+    const kind = match[1].toLowerCase();
+    const slug = match[2].trim();
+    if (!slug) {
+        return undefined;
+    }
+    return {
+        kind,
+        label: slug,
+        slug
+    };
+}
+function rankContextClaims(claims, queryTerms) {
+    return [...claims].sort((left, right) => {
+        const scoreDelta = scoreClaim(right, queryTerms) - scoreClaim(left, queryTerms);
+        if (scoreDelta !== 0) {
+            return scoreDelta;
+        }
+        return left.pageSlug.localeCompare(right.pageSlug) || left.text.localeCompare(right.text);
+    });
+}
+function scoreClaim(claim, queryTerms) {
+    const haystack = `${claim.pageSlug} ${claim.text}`.toLowerCase();
+    let score = claim.sources.length * 3;
+    for (const term of queryTerms) {
+        if (haystack.includes(term)) {
+            score += 2;
+        }
+    }
+    if (claim.status === 'current') {
+        score += 1;
+    }
+    return score;
+}
+function buildOpenQuestions(claims, findings) {
+    const claimQuestions = claims
+        .map((claim) => {
+        if (claim.status !== 'current' && claim.sources.length === 0) {
+            return `Verify ${claim.pageSlug}: ${claim.text} (status: ${claim.status}). Add at least one supporting source.`;
+        }
+        if (claim.status !== 'current') {
+            return `Verify ${claim.pageSlug}: ${claim.text} (status: ${claim.status}). Review ${claim.sources.map((source) => source.slug).join(', ')}.`;
+        }
+        if (claim.sources.length === 0) {
+            return `Add at least one supporting source for ${claim.pageSlug}: ${claim.text}.`;
+        }
+        return undefined;
+    })
+        .filter((question) => Boolean(question));
+    const guidanceQuestions = findings
+        .filter((finding) => guidanceLintRules.has(finding.rule))
+        .map((finding) => `Resolve ${finding.rule} in ${finding.path}: ${finding.message}`);
+    return [...claimQuestions, ...guidanceQuestions];
+}
+const guidanceLintRules = new Set([
+    'dormant-skill',
+    'oversized-guidance',
+    'duplicate-guidance',
+    'stale-guidance-reference',
+    'conflicting-guidance',
+    'unrouted-guidance'
+]);
+async function listRecentProjectLogEntries(maxEntries) {
+    const content = await fs.readFile(pagePathFromSlug('project-log'), 'utf8').catch(() => '');
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('- '))
+        .slice(-maxEntries)
+        .reverse();
+}
+function extractRelatedWikiSlugs(content, sourcePath, pageByPath) {
+    const sourceDir = path.posix.dirname(sourcePath);
+    return Array.from(new Set(extractMarkdownLinks(content)
+        .map((link) => resolveWikiLinkSlug(link, sourceDir, pageByPath))
+        .filter((slug) => Boolean(slug))));
+}
+function extractMarkdownLinks(content) {
+    return Array.from(content.matchAll(/\[[^\]]+\]\(([^)]+)\)/g), (match) => match[1]?.trim() ?? '')
+        .filter(Boolean)
+        .map((link) => link.split('#')[0]?.split('?')[0]?.trim() ?? '')
+        .filter((link) => link.endsWith('.md'));
+}
+function resolveWikiLinkSlug(link, sourceDir, pageByPath) {
+    if (/^[a-z]+:/i.test(link) || path.isAbsolute(link)) {
+        return undefined;
+    }
+    const normalized = path.posix.normalize(path.posix.join(sourceDir, link.replace(/\\/g, '/')));
+    return pageByPath.get(normalized);
+}