@rarusoft/dendrite-wiki 0.1.0-alpha.0

package/dist/maintenance-runner.js

@@ -0,0 +1,62 @@
+/**
+ * High-level driver that runs a maintenance action end-to-end.
+ *
+ * Wraps `executeMaintenanceAction` with the surrounding scaffolding the Review Board
+ * needs: refresh the generated wiki views before and after the action so the inbox
+ * reflects the new state, persist a latest-action artifact at
+ * `docs/public/maintenance-action-result.json` for the Review Board's "Done" overlay
+ * polling, and append a project-log entry summarizing the action so the change appears
+ * in `git log` next to the page it touched. Used by both the CLI (`dendrite-wiki
+ * wiki:action`) and the review bridge HTTP endpoint.
+ */
+import { executeMaintenanceAction } from './maintenance-actions.js';
+import { refreshGeneratedWikiDocs, writeLatestMaintenanceActionArtifact } from './generated-docs.js';
+import { appendProjectLog } from './store.js';
+export async function runMaintenanceActionAndRefresh(actionId, options = {}) {
+    const execution = await executeMaintenanceAction(actionId, options);
+    const changedPaths = extractChangedPaths(execution.result);
+    const projectLogEntry = buildProjectLogEntry(execution, changedPaths);
+    if (projectLogEntry) {
+        await appendProjectLog(projectLogEntry);
+    }
+    const refresh = await refreshGeneratedWikiDocs();
+    const artifact = {
+        ranAt: new Date().toISOString(),
+        refreshedPageCount: refresh.pageCount,
+        audit: {
+            artifactPath: 'docs/public/maintenance-action-result.json',
+            changedPaths,
+            projectLogEntry,
+            undoPath: buildUndoPath(changedPaths)
+        },
+        execution
+    };
+    await writeLatestMaintenanceActionArtifact(artifact);
+    return artifact;
+}
+function extractChangedPaths(result) {
+    const updatedPaths = result.updatedPaths;
+    return Array.isArray(updatedPaths) ? updatedPaths.filter((path) => typeof path === 'string') : [];
+}
+function buildProjectLogEntry(execution, changedPaths) {
+    // Log the action kinds that mutate canonical (committed) project state. We deliberately
+    // skip 'snoozed-page-drift' (local-data only — operator workflow noise) and the read-only
+    // result kinds; logging those would bloat the project log without adding signal.
+    const loggedResultKinds = new Set([
+        'applied-proposal',
+        'inserted-h1',
+        'archived-guidance-file',
+        'edited-page-summary'
+    ]);
+    if (!loggedResultKinds.has(execution.resultKind)) {
+        return undefined;
+    }
+    const changedSummary = changedPaths.length > 0 ? ` Changed paths: ${changedPaths.join(', ')}.` : '';
+    return `Accepted maintenance action ${execution.actionId}. ${execution.resultSummary}${changedSummary}`;
+}
+function buildUndoPath(changedPaths) {
+    if (changedPaths.length === 0) {
+        return 'No project files were changed, so no undo path is needed.';
+    }
+    return `Before committing, inspect git diff for ${changedPaths.join(', ')} and restore those paths from version control if the accepted maintenance action should be undone.`;
+}

package/dist/page-drift.js

@@ -0,0 +1,225 @@
+/**
+ * Page drift detection.
+ *
+ * Computes Jaccard token overlap between a page's stated intent (its title + first
+ * paragraph) and the recent project-log entries that mention this page's slug. Low overlap
+ * means the page declares one purpose but recent activity has been about something else —
+ * the page is drifting away from its title.
+ *
+ * Ported from dendrite-mcp's drift-detection-via-Jaccard pattern. Pure deterministic, no
+ * LLM, no embeddings — just token sets compared by intersection-over-union. Surfaces as a
+ * `page-drift` wiki lint finding so it lands in the existing maintenance review board
+ * without needing new UI. The operator can suppress false-positive drifts via the snooze
+ * store in `./page-drift-snoozes.ts` rather than being forced to perform a fake edit on
+ * the page just to clear the finding.
+ */
+// Tunable defaults. After the first dogfood pass on this repo flagged 14 of 32 pages
+// (a busy session pushed the project log full of campaign-specific entries that legitimately
+// don't share vocabulary with the abstract page intents), we made two adjustments:
+//
+// 1. Threshold dropped from 0.5 to 0.35 so only genuinely-divergent pages flag.
+// 2. A 7-day recency filter on log entries means a single busy week doesn't accumulate
+//    enough activity-side tokens to swamp the intent-side tokens.
+//
+// Both are overridable via detectPageDrift({ thresholdSimilarity, maxLogEntryAgeDays })
+// so the lint can be retuned per project as real usage signals emerge.
+const DEFAULT_SIMILARITY_THRESHOLD = 0.35;
+const DEFAULT_MAX_LOG_ENTRY_AGE_DAYS = 7;
+const MIN_INTENT_TOKEN_COUNT = 4;
+const MIN_ACTIVITY_TOKEN_COUNT = 4;
+const MAX_RECENT_LOG_ENTRIES_FOR_PAGE = 8;
+const MIN_RECENT_LOG_ENTRIES_FOR_DRIFT_CHECK = 2;
+// Drift requires activity to recur across at least this many distinct date headings within
+// the recency window. A single busy day's burst — even if it produces many log entries —
+// is not enough to signal drift; that's session noise, not divergence. Real drift means
+// the project has been talking about the page in different terms across multiple days.
+const MIN_DISTINCT_DAYS_FOR_DRIFT_CHECK = 2;
+const STOP_TOKENS = new Set([
+    'the',
+    'and',
+    'for',
+    'from',
+    'into',
+    'this',
+    'that',
+    'with',
+    'have',
+    'been',
+    'should',
+    'must',
+    'when',
+    'than',
+    'these',
+    'those',
+    'their',
+    'what',
+    'about',
+    'where',
+    'page',
+    'wiki',
+    'project'
+]);
+export function detectPageDrift(pageContent, pageSlug, recentProjectLogText, options = {}) {
+    const intent = extractPageIntent(pageContent);
+    if (!intent) {
+        return undefined;
+    }
+    const intentTokens = tokenize(intent);
+    if (intentTokens.size < MIN_INTENT_TOKEN_COUNT) {
+        return undefined;
+    }
+    const threshold = options.thresholdSimilarity ?? DEFAULT_SIMILARITY_THRESHOLD;
+    const maxAgeDays = options.maxLogEntryAgeDays ?? DEFAULT_MAX_LOG_ENTRY_AGE_DAYS;
+    const minDistinctDays = options.minDistinctDays ?? MIN_DISTINCT_DAYS_FOR_DRIFT_CHECK;
+    const match = extractRecentEntriesMentioningPage(recentProjectLogText, pageSlug, MAX_RECENT_LOG_ENTRIES_FOR_PAGE, maxAgeDays, options.referenceDate ?? new Date());
+    if (match.entries.length < MIN_RECENT_LOG_ENTRIES_FOR_DRIFT_CHECK) {
+        return undefined;
+    }
+    // Distinct-days gate: a single concentrated burst of activity (even if it produces many
+    // log entries under one date heading) is session noise, not drift. Drift requires the
+    // page to keep getting off-topic mentions across multiple working days.
+    if (match.distinctDays < minDistinctDays) {
+        return undefined;
+    }
+    const activityText = match.entries.join(' ');
+    const activityTokens = tokenize(activityText);
+    if (activityTokens.size < MIN_ACTIVITY_TOKEN_COUNT) {
+        return undefined;
+    }
+    const similarity = jaccardSimilarity(intentTokens, activityTokens);
+    if (similarity >= threshold) {
+        return undefined;
+    }
+    return {
+        similarity,
+        intentTokens: [...intentTokens].sort(),
+        activityTokens: [...activityTokens].sort(),
+        matchedLogEntries: match.entries.length,
+        matchedDistinctDays: match.distinctDays,
+        sampleIntent: truncate(intent, 120),
+        sampleActivity: truncate(match.entries[match.entries.length - 1] ?? '', 120)
+    };
+}
+export function extractPageIntent(pageContent) {
+    const withoutFrontmatter = pageContent.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+    const lines = withoutFrontmatter.split(/\r?\n/);
+    let title = '';
+    const paragraphLines = [];
+    let foundTitle = false;
+    let collectingParagraph = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!foundTitle) {
+            const titleMatch = trimmed.match(/^#\s+(.+)$/);
+            if (titleMatch) {
+                title = titleMatch[1].trim();
+                foundTitle = true;
+                continue;
+            }
+            continue;
+        }
+        // After the H1, look for the first non-empty, non-heading paragraph.
+        if (!collectingParagraph) {
+            if (trimmed === '' || trimmed.startsWith('#')) {
+                continue;
+            }
+            collectingParagraph = true;
+            paragraphLines.push(trimmed);
+            continue;
+        }
+        // Stop the paragraph at the next blank line or heading.
+        if (trimmed === '' || trimmed.startsWith('#')) {
+            break;
+        }
+        paragraphLines.push(trimmed);
+    }
+    if (!title) {
+        return '';
+    }
+    const paragraph = paragraphLines.join(' ');
+    return paragraph ? `${title}. ${paragraph}` : title;
+}
+export function extractRecentEntriesMentioningPage(projectLogText, pageSlug, maxEntries, maxAgeDays = DEFAULT_MAX_LOG_ENTRY_AGE_DAYS, referenceDate = new Date()) {
+    if (!projectLogText) {
+        return { entries: [], distinctDays: 0 };
+    }
+    // Project log entries are bullet lines under date headings of the form `## YYYY-MM-DD`.
+    // We forward-scan tracking the current date heading; entries are kept only when their
+    // associated date is within maxAgeDays of referenceDate. Entries that appear before any
+    // date heading or after a heading older than the cutoff are skipped.
+    //
+    // We also track which distinct date headings produced matches, so the caller can tell a
+    // single-day burst (session noise) apart from multi-day drift (real divergence).
+    //
+    // Note: appendProjectLog only adds a date heading once per day, so multiple entries from
+    // the same day all live under that single heading. Old entries in the file may have
+    // stale headings that fail the recency check, which is exactly what we want — drift
+    // detection should reflect *recent* activity, not the project's entire history.
+    const lines = projectLogText.split(/\r?\n/);
+    const slugTokens = [
+        pageSlug.toLowerCase(),
+        pageSlug.toLowerCase().replace(/-/g, ' '),
+        pageSlug.toLowerCase().replace(/-/g, '_')
+    ];
+    const cutoffMs = referenceDate.getTime() - maxAgeDays * 86_400_000;
+    const matches = [];
+    const matchedDateHeadings = new Set();
+    let currentHeadingIsRecent = false;
+    let currentHeadingDate = '';
+    for (const line of lines) {
+        const trimmed = line.trim();
+        const dateHeading = trimmed.match(/^##\s+(\d{4}-\d{2}-\d{2})/);
+        if (dateHeading) {
+            const headingMs = Date.parse(dateHeading[1]);
+            currentHeadingIsRecent = Number.isFinite(headingMs) && headingMs >= cutoffMs;
+            currentHeadingDate = dateHeading[1];
+            continue;
+        }
+        if (!currentHeadingIsRecent) {
+            continue;
+        }
+        if (!trimmed.startsWith('- ')) {
+            continue;
+        }
+        const lowered = trimmed.toLowerCase();
+        if (slugTokens.some((token) => lowered.includes(token))) {
+            matches.push(trimmed.replace(/^-\s*/, ''));
+            matchedDateHeadings.add(currentHeadingDate);
+        }
+    }
+    // Project log appends newest entries at the file end. We walked forward, so `matches`
+    // is in document order (oldest → newest). Reverse and cap so callers see newest-first,
+    // matching the original recency-biased ordering before the date-window filter landed.
+    return {
+        entries: matches.slice(-maxEntries).reverse(),
+        distinctDays: matchedDateHeadings.size
+    };
+}
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 4 && !STOP_TOKENS.has(token)));
+}
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 || b.size === 0) {
+        return 0;
+    }
+    let intersection = 0;
+    for (const token of a) {
+        if (b.has(token))
+            intersection += 1;
+    }
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1).trimEnd()}…`;
+}
+export function buildPageDriftMessage(signal) {
+    const pct = Math.round(signal.similarity * 100);
+    return `Page drift suspected: only ${pct}% token overlap between page intent and ${signal.matchedLogEntries} recent project-log entries mentioning this page. Page may have outgrown its stated purpose.`;
+}

package/dist/page-inbox.js

@@ -0,0 +1,168 @@
+/**
+ * Per-page maintenance projection — the data behind the in-page "memory pending" badge.
+ *
+ * The central Maintenance Review Board is the right surface for an operator triaging the
+ * whole backlog, but it forces a context switch off the page they were actually reading.
+ * This module answers a narrower question: "for THIS specific wiki page, what memories
+ * want to land on it, and what lint findings does it have right now?" The browser-side
+ * `PageMemoryBadge` Vue component renders the result as a small floating pill that
+ * expands into an inline action panel — apply a pending promotion without leaving the
+ * page.
+ *
+ * Everything here is a projection of the same `reviewProjectMemories` + `lintWikiPages`
+ * pipelines the central board uses. The action ids are byte-identical to the ones
+ * `buildMaintenanceInboxSnapshot` emits, so `/actions/execute` accepts them unchanged.
+ * That keeps the audit story intact: apply still writes through `maintenance-runner.ts`,
+ * still appends a project-log entry, still marks the source memory superseded.
+ */
+// Side-effect import: registers WikiCanonicalTarget on the brain DI surface.
+import './canonical-target.js';
+import { previewProjectMemoryPromotion, resolvePromotionTargetSlug } from '@rarusoft/dendrite-memory';
+import { reviewProjectMemories } from '@rarusoft/dendrite-memory';
+import { lintWikiPages, readWikiPage } from './store.js';
+const PROPOSED_TEXT_PREVIEW_CHARS = 320;
+/**
+ * One-shot projection across every page: which slugs have any pending memory promotions
+ * or lint findings, and how many. Powers the sidebar-link decoration so the operator
+ * sees pending counts on every link in the wiki nav without having to visit each page.
+ */
+export async function buildPageInboxSummary() {
+    const [memoryReview, lintFindings] = await Promise.all([
+        reviewProjectMemories(),
+        lintWikiPages()
+    ]);
+    const counts = new Map();
+    const bump = (slug) => {
+        let entry = counts.get(slug);
+        if (!entry) {
+            entry = { memoryCount: 0, lintCount: 0, hasUrgent: false };
+            counts.set(slug, entry);
+        }
+        return entry;
+    };
+    for (const finding of memoryReview.findings) {
+        if (finding.kind !== 'promotion-ready')
+            continue;
+        const target = resolvePromotionTargetSlug(finding.records);
+        bump(target).memoryCount += 1;
+    }
+    for (const finding of lintFindings) {
+        const entry = bump(finding.slug);
+        entry.lintCount += 1;
+        if (finding.rule === 'contradicts-shipped-memory' || finding.rule === 'page-drift') {
+            entry.hasUrgent = true;
+        }
+    }
+    return Array.from(counts.entries())
+        .map(([slug, entry]) => ({
+        slug,
+        total: entry.memoryCount + entry.lintCount,
+        memoryCount: entry.memoryCount,
+        lintCount: entry.lintCount,
+        hasUrgent: entry.hasUrgent
+    }))
+        .filter((entry) => entry.total > 0)
+        .sort((a, b) => a.slug.localeCompare(b.slug));
+}
+export async function buildPageInboxSnapshot(slug) {
+    const trimmed = slug.trim();
+    if (!trimmed) {
+        throw new Error('page-inbox requires a non-empty slug.');
+    }
+    const [memoryReview, lintFindings, pageContent] = await Promise.all([
+        reviewProjectMemories(),
+        lintWikiPages(),
+        readWikiPage(trimmed).catch(() => '')
+    ]);
+    const memoryItems = await collectPageMemoryItems(trimmed, memoryReview.findings);
+    const lintItems = lintFindings
+        .filter((finding) => finding.slug === trimmed)
+        .map((finding) => ({
+        kind: 'lint',
+        rule: finding.rule,
+        message: finding.message
+    }));
+    return {
+        slug: trimmed,
+        pageExists: pageContent !== '',
+        memoryItems,
+        lintItems,
+        total: memoryItems.length + lintItems.length
+    };
+}
+async function collectPageMemoryItems(slug, findings) {
+    const items = [];
+    for (const finding of findings) {
+        if (finding.kind !== 'promotion-ready') {
+            continue;
+        }
+        // resolvePromotionTargetSlug mirrors what previewProjectMemoryPromotion does when
+        // no explicit target is passed — so the badge filter exactly matches the page the
+        // apply would actually write to. If the operator picks a different target via the
+        // central board's modal, that's outside the badge's view, which is fine.
+        const resolvedTarget = resolvePromotionTargetSlug(finding.records);
+        if (resolvedTarget !== slug) {
+            continue;
+        }
+        const memoryIds = finding.memoryIds;
+        const applyActionId = buildMemoryActionId('promotion-ready', memoryIds, 'apply-memory-promotion');
+        const draftActionId = buildMemoryActionId('promotion-ready', memoryIds, 'draft-memory-promotion');
+        let proposedSectionAnchor = '';
+        let proposedHeading = '';
+        let proposedTextPreview = '';
+        try {
+            // Reusing the existing preview avoids drift between "what the badge promises" and
+            // "what apply does" — the same module computes both. The cost is one preview build
+            // per pending item, which is cheap for the small numbers a single page sees.
+            const preview = await previewProjectMemoryPromotion(memoryIds, { targetPage: slug });
+            proposedSectionAnchor = preview.proposedSectionAnchor;
+            proposedHeading = preview.sectionHeading;
+            proposedTextPreview = truncatePreview(preview.proposedText);
+        }
+        catch {
+            // Promotion preview can throw if the memory id resolves to a record that's been
+            // archived between the review and the preview call. Skip the preview text in that
+            // case; the action ids are still valid for the central board.
+        }
+        items.push({
+            kind: 'memory-promotion',
+            reviewKind: finding.kind,
+            applyActionId,
+            draftActionId,
+            summary: finding.summary,
+            reason: finding.reason,
+            memoryIds,
+            records: finding.records.map(toInboxRecord),
+            proposedSectionAnchor,
+            proposedHeading,
+            proposedTextPreview
+        });
+    }
+    return items;
+}
+function toInboxRecord(record) {
+    return {
+        id: record.id,
+        kind: record.kind,
+        summary: record.summary,
+        text: record.text,
+        recallCount: record.recallCount,
+        sources: record.sources.map((source) => `${source.kind}:${source.slug}`),
+        relatedFiles: record.relatedFiles,
+        relatedPages: record.relatedPages
+    };
+}
+// Mirrors `buildMemoryActionId` from maintenance-inbox.ts. Kept inline here rather than
+// imported because the inbox module is the heavy lifter; this surface only needs the id
+// shape and a single review kind. If the id format ever changes, both call sites have to
+// move in lockstep, and the maintenance-inbox tests already lock the shape.
+function buildMemoryActionId(reviewKind, memoryIds, actionKind) {
+    return `memory:${reviewKind}:${memoryIds.join('+')}:${actionKind}`;
+}
+function truncatePreview(proposedText) {
+    const normalized = proposedText.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= PROPOSED_TEXT_PREVIEW_CHARS) {
+        return normalized;
+    }
+    return `${normalized.slice(0, PROPOSED_TEXT_PREVIEW_CHARS - 1).trimEnd()}…`;
+}