@rarusoft/dendrite-wiki 0.1.0-alpha.0

package/dist/generated-docs.js

@@ -0,0 +1,219 @@
+/**
+ * The wiki refresh orchestrator — `npm run wiki:refresh` entry point.
+ *
+ * Rebuilds every deterministic derived view in the project: the catalog block in
+ * `docs/index.md`, `docs/wiki/maintenance-inbox.md` (and its JSON twin), the recent raw
+ * observation stream, the guidance-lifecycle table, the wiki search index (JSON +
+ * SQLite FTS5), and — since A5 of the API reference roadmap — the entire `docs/wiki/api/`
+ * tree via `refreshApiReference()` from `./api-reference.ts`.
+ *
+ * The order matters: API reference generation runs first so the page catalog and search
+ * index built later in the same call see the fresh generated pages. Every write goes
+ * through `writeIfChanged` so untouched files don't bump mtime, which keeps `npm run check`
+ * idempotent across repeated runs.
+ *
+ * This module deliberately does NOT write technical narrative pages like architecture.md.
+ * It only rebuilds derived views that map cleanly from primary data; humans own the prose.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { refreshApiReference } from './api-reference.js';
+import { reviewProjectMemories } from '@rarusoft/dendrite-memory';
+import { buildWikiGraphSnapshot, extractWikiClaims, lintWikiPages, listGuidanceLifecycle, listWikiPages, listWikiProposals, readWikiPage, searchWikiPages } from './store.js';
+import { buildMaintenanceInboxPage, buildMaintenanceInboxSnapshot } from './maintenance-inbox.js';
+import { detectRawObservationClusters, readRawObservations } from '@rarusoft/dendrite-memory';
+const indexPath = path.resolve(process.cwd(), 'docs', 'index.md');
+const maintenanceInboxPath = path.resolve(process.cwd(), 'docs', 'wiki', 'maintenance-inbox.md');
+const maintenanceInboxDataPath = path.resolve(process.cwd(), 'docs', 'public', 'maintenance-inbox.json');
+const observationStreamDataPath = path.resolve(process.cwd(), 'docs', 'public', 'raw-observations-recent.json');
+const observationStreamRecentSampleSize = 200;
+const guidanceLifecyclePath = path.resolve(process.cwd(), 'docs', 'wiki', 'guidance-lifecycle.md');
+const guidanceLifecycleDataPath = path.resolve(process.cwd(), 'docs', 'public', 'guidance-lifecycle.json');
+const maintenanceActionResultPath = path.resolve(process.cwd(), 'docs', 'public', 'maintenance-action-result.json');
+const wikiSearchIndexPath = path.resolve(process.cwd(), 'docs', 'public', 'wiki-search-index.json');
+const sqliteSearchIndexPath = path.resolve(process.cwd(), process.env.DENDRITE_WIKI_DATA_DIR ?? 'local-data', 'wiki-search.sqlite');
+const markerStart = '<!-- WIKI_CATALOG_START -->';
+const markerEnd = '<!-- WIKI_CATALOG_END -->';
+export async function refreshGeneratedWikiDocs() {
+    // Regenerate the API reference first so listWikiPages() and the lint pass below see the
+    // current set of generated pages. Projects without a `src/` directory get a harmless
+    // empty-result no-op (walkProjectSources returns []). Generation failures escalate so
+    // `npm run check` surfaces real breakage rather than silently shipping a stale catalog.
+    await refreshApiReference();
+    const [findings, proposals, memoryReview, observationClusters] = await Promise.all([
+        lintWikiPages(),
+        listWikiProposals(),
+        reviewProjectMemories(),
+        detectRawObservationClusters()
+    ]);
+    const index = await fs.readFile(indexPath, 'utf8');
+    const indexEol = detectEol(index);
+    const maintenanceInbox = await fs.readFile(maintenanceInboxPath, 'utf8').catch(() => '');
+    const maintenanceInboxEol = '\n';
+    const reviewPageExists = async (reviewPath) => {
+        try {
+            await fs.access(path.resolve(process.cwd(), reviewPath));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const nextMaintenanceInbox = normalizeEol(await buildMaintenanceInboxPage(findings, proposals, {
+        reviewPageExists,
+        memoryFindings: memoryReview.findings,
+        observationClusters
+    }), maintenanceInboxEol);
+    await writeIfChanged(maintenanceInboxPath, maintenanceInbox, nextMaintenanceInbox);
+    const maintenanceInboxData = await fs.readFile(maintenanceInboxDataPath, 'utf8').catch(() => '');
+    const nextMaintenanceInboxData = ensureTrailingEol(JSON.stringify(await buildMaintenanceInboxSnapshot(findings, proposals, {
+        reviewPageExists,
+        memoryFindings: memoryReview.findings,
+        observationClusters
+    }), null, 2), '\n');
+    await writeIfChanged(maintenanceInboxDataPath, maintenanceInboxData, nextMaintenanceInboxData);
+    const observationStreamData = await fs.readFile(observationStreamDataPath, 'utf8').catch(() => '');
+    const recentObservations = await readRawObservations({ limit: observationStreamRecentSampleSize });
+    const nextObservationStreamData = ensureTrailingEol(JSON.stringify({
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        sampleSize: observationStreamRecentSampleSize,
+        observationCount: recentObservations.length,
+        clusterCount: observationClusters.length,
+        observations: recentObservations
+    }, null, 2), '\n');
+    await writeIfChanged(observationStreamDataPath, observationStreamData, nextObservationStreamData);
+    const guidanceLifecycle = await listGuidanceLifecycle();
+    const currentGuidanceLifecycle = await fs.readFile(guidanceLifecyclePath, 'utf8').catch(() => '');
+    const nextGuidanceLifecycle = normalizeEol(buildGuidanceLifecyclePage(guidanceLifecycle), '\n');
+    await writeIfChanged(guidanceLifecyclePath, currentGuidanceLifecycle, nextGuidanceLifecycle);
+    const guidanceLifecycleData = await fs.readFile(guidanceLifecycleDataPath, 'utf8').catch(() => '');
+    const nextGuidanceLifecycleData = ensureTrailingEol(JSON.stringify({ guidance: guidanceLifecycle }, null, 2), '\n');
+    await writeIfChanged(guidanceLifecycleDataPath, guidanceLifecycleData, nextGuidanceLifecycleData);
+    const pages = await listWikiPages();
+    const searchIndexData = await fs.readFile(wikiSearchIndexPath, 'utf8').catch(() => '');
+    const nextSearchIndexData = ensureTrailingEol(JSON.stringify({
+        graph: await buildWikiGraphSnapshot(),
+        sampleSearch: await searchWikiPages('project wiki')
+    }, null, 2), '\n');
+    await writeIfChanged(wikiSearchIndexPath, searchIndexData, nextSearchIndexData);
+    await writeSqliteSearchIndex(sqliteSearchIndexPath, pages);
+    const catalog = normalizeEol([
+        markerStart,
+        '',
+        '| Page | Slug |',
+        '|---|---|',
+        ...pages.map((page) => `| [${page.title}](./wiki/${page.slug}.md) | \`${page.slug}\` |`),
+        '',
+        markerEnd
+    ].join('\n'), indexEol);
+    let nextIndex = index;
+    if (nextIndex.includes(markerStart) && nextIndex.includes(markerEnd)) {
+        nextIndex = nextIndex.replace(new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`), catalog);
+    }
+    else {
+        nextIndex += `${indexEol}${indexEol}## Generated Catalog${indexEol}${indexEol}${catalog}${indexEol}`;
+    }
+    await writeIfChanged(indexPath, index, ensureTrailingEol(nextIndex, indexEol));
+    return { pageCount: pages.length };
+}
+function buildGuidanceLifecyclePage(guidance) {
+    const statusCounts = [...new Map(guidance.map((item) => [item.status, guidance.filter((candidate) => candidate.status === item.status).length])).entries()]
+        .sort(([left], [right]) => left.localeCompare(right));
+    return [
+        '# Guidance Lifecycle',
+        '',
+        'This generated page shows active, dormant, superseded, and pending-review guidance files from the current project.',
+        '',
+        '## Status',
+        guidance.length > 0 ? `- Guidance files: ${guidance.length}` : '- Guidance files: none.',
+        statusCounts.length > 0
+            ? `- Status groups: ${statusCounts.map(([status, count]) => `\`${status}\` (${count})`).join(', ')}`
+            : '- Status groups: none.',
+        '',
+        '## Lifecycle Table',
+        guidance.length === 0
+            ? 'No guidance files found.'
+            : [
+                '| Path | Kind | Status | Review | Archive Target | Linked From | Reason |',
+                '|---|---|---|---|---|---|---|',
+                ...guidance.map((item) => `| ${escapeTableCell(item.path)} | \`${item.kind}\` | \`${item.status}\` | ${item.reviewStatus ?? 'none'} | ${escapeTableCell(item.archiveTarget ?? '')} | ${escapeTableCell(item.linkedFrom.join(', ') || 'none')} | ${escapeTableCell(item.reason)} |`)
+            ].join('\n'),
+        ''
+    ].join('\n');
+}
+function escapeTableCell(value) {
+    return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+export async function writeLatestMaintenanceActionArtifact(artifact) {
+    const currentContent = await fs.readFile(maintenanceActionResultPath, 'utf8').catch(() => '');
+    const nextContent = ensureTrailingEol(JSON.stringify(artifact, null, 2), '\n');
+    await writeIfChanged(maintenanceActionResultPath, currentContent, nextContent);
+}
+function detectEol(content) {
+    return content.includes('\r\n') ? '\r\n' : '\n';
+}
+function normalizeEol(content, eol) {
+    return content.replace(/\r?\n/g, eol);
+}
+function ensureTrailingEol(content, eol) {
+    const withoutTrailingEol = content.replace(/(?:\r?\n)+$/g, '');
+    return `${withoutTrailingEol}${eol}`;
+}
+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 || trimmed.startsWith('#') || trimmed.startsWith('|') || trimmed.startsWith('- ') || /^\d+\.\s/.test(trimmed)) {
+            continue;
+        }
+        return trimmed;
+    }
+    return '';
+}
+async function writeIfChanged(filePath, currentContent, nextContent) {
+    if (currentContent === nextContent) {
+        return;
+    }
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, nextContent, 'utf8');
+}
+async function writeSqliteSearchIndex(filePath, pages) {
+    const sqliteModule = await loadNodeSqliteModule();
+    if (!sqliteModule) {
+        return;
+    }
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.rm(filePath, { force: true });
+    const database = new sqliteModule.DatabaseSync(filePath);
+    try {
+        database.exec([
+            'CREATE VIRTUAL TABLE pages_fts USING fts5(slug, title, path, summary, content);',
+            'CREATE VIRTUAL TABLE claims_fts USING fts5(page_slug, status, text, sources);',
+            'CREATE TABLE graph_edges(source_slug TEXT NOT NULL, target_slug TEXT NOT NULL);'
+        ].join('\n'));
+        const pageByPath = new Map(pages.map((page) => [page.path, page.slug]));
+        const insertPage = database.prepare('INSERT INTO pages_fts(slug, title, path, summary, content) VALUES (?, ?, ?, ?, ?)');
+        const insertClaim = database.prepare('INSERT INTO claims_fts(page_slug, status, text, sources) VALUES (?, ?, ?, ?)');
+        const insertEdge = database.prepare('INSERT INTO graph_edges(source_slug, target_slug) VALUES (?, ?)');
+        for (const page of pages) {
+            const content = await readWikiPage(page.slug);
+            insertPage.run(page.slug, page.title, page.path, extractSummaryParagraph(content) || page.title, content);
+            for (const claim of extractWikiClaims(page.slug, content, pageByPath)) {
+                insertClaim.run(claim.pageSlug, claim.status, claim.text, claim.sources.map((source) => source.slug).join(' '));
+                for (const source of claim.sources) {
+                    insertEdge.run(page.slug, source.slug);
+                }
+            }
+        }
+    }
+    finally {
+        database.close();
+    }
+}
+async function loadNodeSqliteModule() {
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    return dynamicImport('node:sqlite').catch(() => undefined);
+}

package/dist/i18n.js

@@ -0,0 +1,71 @@
+// C7 slice 2: per-language modes for agent-facing strings.
+//
+// This is intentionally minimal: a single string-table per language code, resolved at call
+// time via the DENDRITE_LANG env var. The default is English. The framework is the
+// deliverable here; translations ship as forks or follow-up PRs once a real operator asks
+// for one.
+//
+// Storage rules stay English-only: memory bodies, wiki pages, claims, and project-log
+// entries are never translated by this module. Only operator-facing message text (cluster
+// templates, ritual reminders, hook output) is routed through the i18n table.
+//
+// Adding a new language:
+// 1. Pick an ISO 639-1 code (zh, ja, es, fr, de, etc.).
+// 2. Add an entry to the `translations` map below with the message keys you want to
+//    localize. Missing keys fall back to English automatically.
+// 3. Document the new code in docs/wiki/competitive-feature-roadmap.md (phase C7).
+const englishMessages = {
+    'observation-cluster-template-header': ({ kind, target, observationCount, distinctSessionCount, lastSeen }) => `Recurring activity detected: ${kind} on ${target} (${observationCount} observation${observationCount === 1 ? '' : 's'} across ${distinctSessionCount} session${distinctSessionCount === 1 ? '' : 's'}, last seen ${lastSeen}).`,
+    'observation-cluster-template-considerations': () => 'Consider documenting why this {kindLabel} keeps coming up — for example:',
+    'observation-cluster-template-options-edit-or-read': () => [
+        '- a setup or onboarding gotcha future agents should know about',
+        '- a refactoring target that has accumulated repeated edits',
+        '- a frequently-broken integration or test',
+        '- a workflow pattern worth promoting to a scope-bound skill'
+    ].join('\n'),
+    'observation-cluster-template-options-default': () => [
+        '- a setup or onboarding gotcha future agents should know about',
+        '- a refactoring target that has accumulated repeated activity',
+        '- a frequently-broken integration or test',
+        '- a workflow pattern worth promoting to a scope-bound skill'
+    ].join('\n'),
+    'observation-cluster-template-replace-instruction': () => 'Replace this template text with the actual lesson, then optionally promote to a skill via memory_promote_skill once the lesson has been recalled enough times.'
+};
+// Sample non-English bundle — Spanish — so the routing has a real second path to test.
+// Operators adding more languages should follow this exact shape.
+const spanishMessages = {
+    'observation-cluster-template-header': ({ kind, target, observationCount, distinctSessionCount, lastSeen }) => `Actividad recurrente detectada: ${kind} en ${target} (${observationCount} observación${observationCount === 1 ? '' : 'es'} en ${distinctSessionCount} sesión${distinctSessionCount === 1 ? '' : 'es'}, vista por última vez ${lastSeen}).`,
+    'observation-cluster-template-replace-instruction': () => 'Reemplaza este texto plantilla con la lección real y luego promociónalo a una skill mediante memory_promote_skill una vez que la lección haya sido recordada suficientes veces.'
+};
+const translations = {
+    en: englishMessages,
+    es: spanishMessages
+};
+export function resolveDendriteLang(env = process.env) {
+    const raw = (env.DENDRITE_LANG ?? '').trim().toLowerCase();
+    if (!raw) {
+        return 'en';
+    }
+    // Accept full BCP-47 codes like en-US by stripping to the primary subtag.
+    return raw.split('-')[0];
+}
+export function translate(key, values = {}, options = {}) {
+    const lang = options.lang ?? resolveDendriteLang();
+    const bundle = translations[lang];
+    const fallback = translations.en;
+    const localized = bundle?.[key];
+    if (localized) {
+        return localized(values);
+    }
+    const fallbackEntry = fallback?.[key];
+    if (fallbackEntry) {
+        return fallbackEntry(values);
+    }
+    // Never throw on a missing key — agent-facing surfaces would prefer to render the key
+    // than fail. Operators can grep for any literal key in output to catch missing entries.
+    return key;
+}
+// Public helper used in tests + by anyone who wants to inspect available languages.
+export function listAvailableDendriteLangs() {
+    return Object.keys(translations).sort();
+}

package/dist/index.js

@@ -0,0 +1,49 @@
+// Public surface of @rarusoft/dendrite-wiki.
+//
+// Phase 4 slice D wave 2 of the Library Extraction Roadmap. The markdown-wiki
+// adapter for @rarusoft/dendrite-memory: implements `CanonicalTarget` against
+// VitePress-rendered `docs/wiki/`, owns the wiki page store + lint + search +
+// synthesis + maintenance review surface + browser-side review bridge.
+//
+// The canonical-target.ts module has a top-level side effect that registers
+// `WikiCanonicalTarget` as the brain's default canonical target — any consumer
+// that imports from `@rarusoft/dendrite-wiki` therefore auto-wires the wiki adapter for
+// brain promotion functions.
+// canonical-target.ts MUST be re-exported first so its top-level
+// setDefaultCanonicalTarget side effect fires before anything else.
+export * from './canonical-target.js';
+// Core wiki page store + search + lint + context briefing surface.
+export * from './store.js';
+export * from './search-index.js';
+export * from './context-cache.js';
+// Maintenance review surface.
+export * from './maintenance-actions.js';
+export * from './maintenance-inbox.js';
+export * from './maintenance-runner.js';
+// Wiki page drift + contradicts-shipped-memory lint surface.
+export * from './page-drift.js';
+export * from './contradicts-shipped-memory.js';
+// Per-page inbox + librarian audit (the multi-category maintenance aggregator).
+export * from './page-inbox.js';
+export * from './librarian.js';
+// Browser-side review bridge.
+export * from './review-bridge.js';
+// API reference generator + chart insertion + chart prompts.
+export * from './api-reference.js';
+export * from './chart-insert.js';
+export * from './chart-prompts.js';
+// Synthesis provider (LLM-assisted wiki narration).
+export * from './wiki-synthesis.js';
+// Telemetry + benchmark + report/binder exports + doctor + diff-context.
+export * from './telemetry.js';
+export * from './telemetry-defaults.js';
+export * from './telemetry-report.js';
+export * from './benchmark.js';
+export * from './benchmark-events.js';
+export * from './report-export.js';
+export * from './binder-export.js';
+export * from './doctor.js';
+export * from './diff-context.js';
+export * from './generated-docs.js';
+// i18n translation table.
+export * from './i18n.js';

package/dist/librarian.js

@@ -0,0 +1,255 @@
+/**
+ * Wiki Librarian audit — one-shot maintenance briefing for an agent that's been told
+ * "organize the wiki".
+ *
+ * Aggregates every open maintenance signal (lint findings, page-drift, contradicts-
+ * shipped-memory, promotion-ready memories) into a single structured payload with
+ * pre-gathered evidence and a per-item `recommendedAction` sentence. The agent reads
+ * this once, plans across categories, and then acts using the existing tool surface
+ * (`memory_promote`, `wiki_write`, `memory_forget`, etc.). Every change still flows
+ * through the audited write paths, so the operator's safety story stays exactly what
+ * it was for manual edits: git diff + project-log entry per change.
+ *
+ * This module is deliberately a projection — it doesn't write anything itself, it just
+ * gathers the evidence an LLM needs to make good organizing decisions in one tool call
+ * instead of forcing it to chain a dozen exploratory reads.
+ */
+import { detectContradictsShippedMemory } from './contradicts-shipped-memory.js';
+// Side-effect import: registers WikiCanonicalTarget on the brain DI surface.
+import './canonical-target.js';
+import { listProjectMemories, previewProjectMemoryPromotion, resolvePromotionTargetSlug, reviewProjectMemories } from '@rarusoft/dendrite-memory';
+import { detectPageDrift, extractPageIntent, extractRecentEntriesMentioningPage } from './page-drift.js';
+import { lintWikiPages, pagePathFromSlug, readWikiPage } from './store.js';
+import { promises as fs } from 'node:fs';
+const DEFAULT_MAX_PER_CATEGORY = 25;
+const PLAYBOOK_TEXT = [
+    'Librarian mode: work down this list category by category, highest-leverage first.',
+    '',
+    '1. promotion-ready: call memory_promote(memoryIds, mode="apply", targetPage) for each item — applies the memory text into the target page and marks the memory superseded.',
+    '2. contradicts-shipped-memory: read the page with wiki_read, study the contradicting memories in evidence.contradictingMemoryIds, then rewrite the offending section with wiki_write so the prose matches shipped reality. Add `contradicts-shipped-memory: ignore` to frontmatter if the negation is intentional design language.',
+    '3. page-drift: read the page intent + recent activity in the evidence block, then rewrite the first paragraph with wiki_write so it reflects what the page is now about. If the drift is healthy (e.g., a roadmap mostly delivered), the new paragraph should say so.',
+    '4. unsupported-claim / stale-claim: read the page, either attach a source citation or mark the claim status, then wiki_write the updated page.',
+    '5. orphan-page / missing-h1 / missing-summary: structural fixes — add an H1, add a summary paragraph, or link the page from a canonical surface.',
+    '',
+    'Every wiki_write call goes through the audited path — project-log entry is appended automatically and git diff is the operator review surface. Memory promotions mark the source memory superseded in the same operation.'
+].join('\n');
+export async function buildLibrarianAudit(options = {}) {
+    const maxPerCategory = options.maxPerCategory ?? DEFAULT_MAX_PER_CATEGORY;
+    const allowCategory = (cat) => !options.categories || options.categories.includes(cat);
+    const [lintFindings, memoryReview, allMemories, projectLogContent] = await Promise.all([
+        lintWikiPages(),
+        reviewProjectMemories(),
+        listProjectMemories({ includeArchived: true }),
+        fs.readFile(pagePathFromSlug('project-log'), 'utf8').catch(() => '')
+    ]);
+    const activeMemories = allMemories.filter((record) => record.status === 'active' || record.status === 'superseded');
+    const memoriesById = new Map(allMemories.map((record) => [record.id, record]));
+    const items = [];
+    const counts = {
+        'page-drift': 0,
+        'contradicts-shipped-memory': 0,
+        'promotion-ready': 0,
+        'unsupported-claim': 0,
+        'stale-claim': 0,
+        'orphan-page': 0,
+        'missing-h1': 0,
+        'missing-summary': 0,
+        'other-lint': 0
+    };
+    // 1) Promotion-ready memories — highest leverage, fully deterministic apply path.
+    if (allowCategory('promotion-ready')) {
+        for (const finding of memoryReview.findings) {
+            if (finding.kind !== 'promotion-ready')
+                continue;
+            if (counts['promotion-ready'] >= maxPerCategory)
+                break;
+            const targetSlug = resolvePromotionTargetSlug(finding.records);
+            let proposedTextPreview = '';
+            let proposedHeading = '## Promoted Lessons';
+            try {
+                const preview = await previewProjectMemoryPromotion(finding.memoryIds, { targetPage: targetSlug });
+                proposedTextPreview = truncate(preview.proposedText, 400);
+                proposedHeading = preview.sectionHeading;
+            }
+            catch {
+                // preview may fail if a memory was archived between review and preview — skip evidence.
+            }
+            items.push({
+                category: 'promotion-ready',
+                slug: targetSlug,
+                summary: finding.summary,
+                evidence: {
+                    memoryIds: finding.memoryIds,
+                    recallCount: finding.records[0]?.recallCount ?? 0,
+                    sourceRefs: finding.records.flatMap((record) => record.sources.map((source) => `${source.kind}:${source.slug}`)),
+                    targetSlug,
+                    proposedHeading,
+                    proposedTextPreview
+                },
+                recommendedAction: `Call memory_promote(memoryIds=${JSON.stringify(finding.memoryIds)}, mode="apply", targetPage="${targetSlug}"). The memory becomes a "Promoted Lessons" bullet on the page and is marked superseded so the inbox stops surfacing it.`,
+                recommendedTools: ['memory_promote']
+            });
+            counts['promotion-ready'] += 1;
+        }
+    }
+    // 2) Contradicts-shipped-memory + page-drift findings need page-level evidence,
+    //    so we read each affected page once and produce both kinds of items from it.
+    const driftableSlugs = new Set(lintFindings
+        .filter((finding) => finding.rule === 'contradicts-shipped-memory' || finding.rule === 'page-drift')
+        .map((finding) => finding.slug));
+    for (const slug of driftableSlugs) {
+        const content = await readWikiPage(slug).catch(() => '');
+        if (!content)
+            continue;
+        if (allowCategory('contradicts-shipped-memory') && counts['contradicts-shipped-memory'] < maxPerCategory) {
+            const signals = detectContradictsShippedMemory(content, activeMemories, projectLogContent);
+            for (const signal of signals) {
+                if (counts['contradicts-shipped-memory'] >= maxPerCategory)
+                    break;
+                const contradictingTexts = signal.contradictingMemoryIds.map((id) => {
+                    const record = memoriesById.get(id);
+                    return record ? { id, summary: record.summary, kind: record.kind } : { id };
+                });
+                items.push({
+                    category: 'contradicts-shipped-memory',
+                    slug,
+                    summary: `${slug}: section "${signal.sectionHeading}" denies a feature that shipped`,
+                    evidence: {
+                        sectionHeading: signal.sectionHeading,
+                        matchedNegation: signal.matchedNegation,
+                        objectTokens: signal.objectTokens,
+                        contradictingMemories: contradictingTexts,
+                        affirmingSnippets: signal.affirmingSnippets
+                    },
+                    recommendedAction: `Read the page with wiki_read(slug="${slug}"). Locate the section "${signal.sectionHeading}". Rewrite its prose so the negation "${signal.matchedNegation}" is replaced with current shipped state — the contradicting memories prove the feature exists. Apply with wiki_write. If the negation is genuinely intentional design language (e.g., privacy boundary), instead add \`contradicts-shipped-memory: ignore\` to the page frontmatter.`,
+                    recommendedTools: ['wiki_read', 'wiki_write']
+                });
+                counts['contradicts-shipped-memory'] += 1;
+            }
+        }
+        if (allowCategory('page-drift') && counts['page-drift'] < maxPerCategory) {
+            const hasDriftFinding = lintFindings.some((finding) => finding.slug === slug && finding.rule === 'page-drift');
+            if (hasDriftFinding) {
+                const drift = detectPageDrift(content, slug, projectLogContent);
+                const intent = extractPageIntent(content);
+                const activityMatch = extractRecentEntriesMentioningPage(projectLogContent, slug, 8, 7);
+                items.push({
+                    category: 'page-drift',
+                    slug,
+                    summary: `${slug}: page intent diverged from recent activity (~${drift ? Math.round(drift.similarity * 100) : 0}% overlap across ${activityMatch.distinctDays} day${activityMatch.distinctDays === 1 ? '' : 's'})`,
+                    evidence: {
+                        currentIntent: intent,
+                        recentActivityEntries: activityMatch.entries,
+                        matchedDistinctDays: activityMatch.distinctDays,
+                        similarityPercent: drift ? Math.round(drift.similarity * 100) : 0
+                    },
+                    recommendedAction: `Read the page with wiki_read(slug="${slug}"). Read the recent activity in evidence.recentActivityEntries. Rewrite the first paragraph (right after the H1) so it reflects what the page is NOW about. If the drift is healthy — e.g., a roadmap that's mostly delivered — the new paragraph should say so explicitly. Apply with wiki_write.`,
+                    recommendedTools: ['wiki_read', 'wiki_write']
+                });
+                counts['page-drift'] += 1;
+            }
+        }
+    }
+    // 3) Remaining lint findings — surface in their own categories so the agent can
+    //    triage them with appropriate care. Skipping ones we already processed above.
+    for (const finding of lintFindings) {
+        if (finding.rule === 'contradicts-shipped-memory' || finding.rule === 'page-drift') {
+            continue;
+        }
+        const category = mapLintRuleToCategory(finding.rule);
+        if (!allowCategory(category))
+            continue;
+        if (counts[category] >= maxPerCategory)
+            continue;
+        items.push(buildLintItem(category, finding));
+        counts[category] += 1;
+    }
+    // Stable sort: promotion-ready first (highest deterministic safety), then drift,
+    // then contradicts, then everything else alphabetically by slug.
+    const categoryOrder = {
+        'promotion-ready': 0,
+        'contradicts-shipped-memory': 1,
+        'page-drift': 2,
+        'stale-claim': 3,
+        'unsupported-claim': 4,
+        'orphan-page': 5,
+        'missing-h1': 6,
+        'missing-summary': 7,
+        'other-lint': 8
+    };
+    items.sort((left, right) => {
+        const delta = categoryOrder[left.category] - categoryOrder[right.category];
+        if (delta !== 0)
+            return delta;
+        return (left.slug ?? '').localeCompare(right.slug ?? '');
+    });
+    return {
+        totalItems: items.length,
+        byCategory: counts,
+        items,
+        playbook: PLAYBOOK_TEXT
+    };
+}
+function mapLintRuleToCategory(rule) {
+    switch (rule) {
+        case 'stale-claim':
+            return 'stale-claim';
+        case 'unsupported-claim':
+            return 'unsupported-claim';
+        case 'orphan-page':
+            return 'orphan-page';
+        case 'missing-h1':
+            return 'missing-h1';
+        case 'missing-summary':
+            return 'missing-summary';
+        default:
+            return 'other-lint';
+    }
+}
+function buildLintItem(category, finding) {
+    const summary = `${finding.slug}: ${finding.rule} — ${finding.message}`;
+    let recommendedAction = '';
+    const recommendedTools = [];
+    switch (category) {
+        case 'unsupported-claim':
+            recommendedAction = `Read the page with wiki_read(slug="${finding.slug}"). Locate the unsupported claim. Either attach a source citation (file, wiki page, decision) and write it back with wiki_write, or downgrade the claim status from [current] to [stale] if it's no longer accurate.`;
+            recommendedTools.push('wiki_read', 'wiki_write');
+            break;
+        case 'stale-claim':
+            recommendedAction = `Read the page with wiki_read(slug="${finding.slug}"). Locate the stale claim. Either update it to current truth (and flip status to [current]) or remove it. Apply with wiki_write.`;
+            recommendedTools.push('wiki_read', 'wiki_write');
+            break;
+        case 'orphan-page':
+            recommendedAction = `Page is not linked from anywhere. Either link it from a canonical surface (project plan, architecture, an index page) — wiki_read + wiki_write — or, if the page is no longer relevant, archive/delete it.`;
+            recommendedTools.push('wiki_read', 'wiki_write');
+            break;
+        case 'missing-h1':
+            recommendedAction = `Add a top-level H1 heading to the page. wiki_read + wiki_write.`;
+            recommendedTools.push('wiki_read', 'wiki_write');
+            break;
+        case 'missing-summary':
+            recommendedAction = `Add a short summary paragraph immediately after the H1 explaining what the page is about. wiki_read + wiki_write.`;
+            recommendedTools.push('wiki_read', 'wiki_write');
+            break;
+        default:
+            recommendedAction = `Open the finding in the central Review Board — this lint rule has a specialized action there (snooze, archive guidance, insert H1, etc.). Or read the page and resolve manually with wiki_write.`;
+            recommendedTools.push('wiki_read', 'wiki_write');
+    }
+    return {
+        category,
+        slug: finding.slug,
+        summary,
+        evidence: {
+            rule: finding.rule,
+            message: finding.message,
+            path: finding.path
+        },
+        recommendedAction,
+        recommendedTools
+    };
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1).trimEnd()}…`;
+}