project-librarian 0.3.0 → 0.4.1

package/dist/modes.js

@@ -63,6 +63,8 @@ const templates_1 = require("./templates");
 const migration_1 = require("./migration");
 const wiki_files_1 = require("./wiki-files");
 const wiki_graph_1 = require("./wiki-graph");
+const wiki_corpus_1 = require("./wiki-corpus");
+const wiki_diagnostics_1 = require("./wiki-diagnostics");
 const scopedAutoIndexThreshold = 40;
 const scopedAutoIndexMarker = "<!-- PROJECT-WIKI-SCOPED-AUTO-INDEX -->";
 function isScopedAutoIndex(file) {
@@ -170,35 +172,111 @@ This block is managed by \`--refresh-index\`. Move useful rows into a hand-writt
 | --- | --- | --- | --- |
 ${rows}<!-- PROJECT-WIKI-AUTO-INDEX:END -->`;
 }
+function termOccurrences(text, terms) {
+    const lowered = text.toLowerCase();
+    return terms.reduce((sum, term) => sum + (lowered.split(term).length - 1), 0);
+}
+function blockKindBoost(block) {
+    if (block.kind === "heading")
+        return 4;
+    if (block.kind === "table_row")
+        return 3;
+    if (block.kind === "list_item")
+        return 2;
+    return 1;
+}
+function scoreQueryBlock(block, terms) {
+    const occurrences = termOccurrences(`${block.headingPath.join(" ")}\n${block.text}`, terms);
+    return occurrences > 0 ? occurrences + blockKindBoost(block) : 0;
+}
+function hasMigrationQueryIntent(terms) {
+    return terms.some((term) => /^(migrat|legacy|coverage|unit|ledger|review)/.test(term));
+}
+function isMigrationSurface(file, meta) {
+    return file.startsWith("wiki/migration/")
+        || /(?:^|-)migration(?:-|$)/.test(file)
+        || /migration|legacy/.test(meta.scope);
+}
+function querySurfaceScore(file, meta, rawScore, terms) {
+    if (rawScore <= 0)
+        return 0;
+    if (isMigrationSurface(file, meta) && !hasMigrationQueryIntent(terms)) {
+        return Math.max(1, Math.floor(rawScore * 0.25) - 20);
+    }
+    let score = rawScore;
+    if (file.startsWith("wiki/canonical/") && meta.status === "active")
+        score += 12;
+    else if (meta.status === "active")
+        score += 2;
+    return score;
+}
 // Answer-shaped query output (2026-06-12 method-transfer decision): first line is
-// the answer, each result carries the page's TL;DR first bullet so the agent can
-// pick a page without opening it, and the whole body sits under the shared hard
-// cap with an explicit truncation notice.
+// the answer, each result carries the page's TL;DR first bullet and the strongest
+// matching block so the agent can pick a page without opening it, and the whole
+// body sits under the shared hard cap with an explicit truncation notice.
 function runQueryMode() {
     if (!args_1.queryTerm.trim()) {
         console.error("missing query: use --query \"search terms\"");
         process.exit(1);
     }
     const terms = args_1.queryTerm.toLowerCase().split(/\s+/).filter(Boolean);
-    const matches = (0, wiki_files_1.wikiMarkdownFiles)().map((file) => {
-        const text = (0, workspace_1.read)(file);
+    const corpus = (0, wiki_corpus_1.loadWikiCorpus)();
+    const pages = corpus.pages;
+    const graph = (0, wiki_corpus_1.wikiCorpusGraph)(corpus);
+    const routerDepths = (0, wiki_graph_1.wikiRouterDepths)(graph);
+    const matches = pages.map(({ file, text }) => {
         const body = (0, workspace_1.stripMetadataHeader)(text);
         const title = (0, wiki_files_1.wikiTitleForFile)(file, text);
         const meta = (0, wiki_files_1.metadataSummary)(file, text);
-        const weighted = `${file}\n${title}\n${meta.scope}\n${(0, workspace_1.metadataValue)(text, "tags")}\n${body}`.toLowerCase();
-        const score = terms.reduce((sum, term) => sum + (weighted.split(term).length - 1) + (file.toLowerCase().includes(term) ? 3 : 0) + (title.toLowerCase().includes(term) ? 5 : 0), 0);
-        return { file, title, score, tldr: (0, wiki_files_1.firstTldrBullet)(text), ...meta };
+        const metadataScore = termOccurrences(`${file}\n${title}\n${meta.scope}\n${(0, workspace_1.metadataValue)(text, "tags")}`, terms)
+            + terms.reduce((sum, term) => sum + (file.toLowerCase().includes(term) ? 3 : 0) + (title.toLowerCase().includes(term) ? 5 : 0), 0);
+        const blocks = (0, wiki_files_1.extractMarkdownBlocks)(body)
+            .map((block) => ({ block, score: scoreQueryBlock(block, terms) }))
+            .filter((item) => item.score > 0)
+            .sort((left, right) => right.score - left.score || left.block.line - right.block.line || left.block.id.localeCompare(right.block.id));
+        const topBlock = blocks[0]?.block;
+        const blockScore = blocks.slice(0, 5).reduce((sum, item) => sum + item.score, 0);
+        const score = querySurfaceScore(file, meta, metadataScore + blockScore, terms);
+        return {
+            blockKind: topBlock?.kind ?? "",
+            blockLine: topBlock?.line ?? 0,
+            blockSnippet: topBlock ? (0, wiki_files_1.markdownBlockSnippet)(topBlock) : "",
+            file,
+            graphEvidence: (0, wiki_graph_1.wikiQueryGraphEvidence)(graph, file, routerDepths),
+            title,
+            score,
+            tldr: (0, wiki_files_1.firstTldrBullet)(text),
+            ...meta,
+        };
     }).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
-    const results = matches.slice(0, 10);
-    const best = results[0];
-    const lines = [best
-            ? `Project wiki query "${args_1.queryTerm}": best match ${best.file} — ${best.title} (${matches.length} matching page${matches.length === 1 ? "" : "s"}, top ${results.length} shown).`
-            : `Project wiki query "${args_1.queryTerm}": no matches.`];
-    for (const item of results) {
-        lines.push(`${item.score.toString().padStart(3)}  ${item.file}  [${item.scope}|${item.status}|${item.budget}]  ${item.title}`);
+    const resultBlocks = matches.slice(0, 10).map((item) => {
+        const lines = [`${item.score.toString().padStart(3)}  ${item.file}  [${item.scope}|${item.status}|${item.budget}]  ${item.title}`];
         if (item.tldr)
             lines.push(`     tldr: ${item.tldr}`);
+        if (item.blockSnippet)
+            lines.push(`     match: ${item.blockKind}@L${item.blockLine}: ${item.blockSnippet}`);
+        if (item.graphEvidence)
+            lines.push(`     graph: ${item.graphEvidence}`);
+        return lines;
+    });
+    const selectedBlocks = [];
+    const answerBudget = wiki_graph_1.wikiAnswerCharCap - wiki_graph_1.wikiAnswerTruncationNotice.length - 1;
+    const headlineFor = (shown) => matches[0]
+        ? `Project wiki query "${args_1.queryTerm}": best match ${matches[0].file} — ${matches[0].title} (${matches.length} matching page${matches.length === 1 ? "" : "s"}, top ${shown} shown).`
+        : `Project wiki query "${args_1.queryTerm}": no matches.`;
+    for (const block of resultBlocks) {
+        const candidateBlocks = [...selectedBlocks, block];
+        const candidate = [headlineFor(candidateBlocks.length), ...candidateBlocks.flat()].join("\n");
+        if (candidate.length > answerBudget && selectedBlocks.length > 0)
+            break;
+        selectedBlocks.push(block);
     }
+    const best = matches[0];
+    const lines = [best
+            ? headlineFor(selectedBlocks.length)
+            : `Project wiki query "${args_1.queryTerm}": no matches.`];
+    for (const block of selectedBlocks)
+        lines.push(...block);
     console.log((0, wiki_graph_1.finalizeWikiAnswer)(lines.join("\n")));
 }
 // Wiki impact mode: backlink/decision_ref/routing evidence for a page so wiki
@@ -208,8 +286,8 @@ function runWikiImpactMode() {
         console.error("missing wiki impact target: use --wiki-impact \"page-or-term\"");
         process.exit(1);
     }
-    const pages = (0, wiki_files_1.wikiMarkdownFiles)().map((file) => ({ file, text: (0, workspace_1.read)(file) }));
-    console.log((0, wiki_graph_1.wikiImpactAnswer)(pages, args_1.wikiImpactTarget.trim()));
+    const corpus = (0, wiki_corpus_1.loadWikiCorpus)();
+    console.log((0, wiki_graph_1.wikiImpactAnswer)(corpus.pages, args_1.wikiImpactTarget.trim(), (0, wiki_corpus_1.wikiCorpusGraph)(corpus)));
 }
 function projectCandidatesContent() {
     return `${(0, templates_1.metadata)("inbox", "on-demand", "wiki/meta/wiki-ops-v1-decisions.md", "candidates are adopted, rejected, or stale")}
@@ -479,11 +557,11 @@ function printDiagnostics(title, diagnostics, checked) {
     console.log(`passed: ${checked} wiki markdown files checked, ${warnings} warnings`);
     return true;
 }
-function collectLinkDiagnostics() {
+function collectLinkDiagnostics(corpus = (0, wiki_corpus_1.loadWikiCorpus)()) {
     const diagnostics = [];
-    const files = (0, wiki_files_1.wikiMarkdownFiles)();
-    const fileSet = new Set(files);
-    const graph = (0, wiki_graph_1.buildWikiGraph)(files.map((file) => ({ file, text: (0, workspace_1.read)(file) })));
+    const files = corpus.files;
+    const fileSet = corpus.fileSet;
+    const graph = (0, wiki_corpus_1.wikiCorpusGraph)(corpus);
     for (const link of graph.links) {
         if (!fileSet.has(link.normalizedTarget)) {
             diagnostics.push({
@@ -589,10 +667,10 @@ function shouldGuardAgainstLegacyReference(file) {
         return false;
     return !file.endsWith("/migration-inbox.md");
 }
-function migrationLegacyReferenceDiagnostics(files) {
+function migrationLegacyReferenceDiagnostics(files, corpus) {
     return files
         .filter(shouldGuardAgainstLegacyReference)
-        .filter((file) => /\bwiki_legacy(?:_|\b|\/)/.test((0, workspace_1.stripMetadataHeader)((0, workspace_1.read)(file))))
+        .filter((file) => /\bwiki_legacy(?:_|\b|\/)/.test((0, workspace_1.stripMetadataHeader)((0, wiki_corpus_1.wikiCorpusText)(corpus, file))))
         .map((file) => ({
         code: "migration-legacy-reference",
         severity: "error",
@@ -600,12 +678,12 @@ function migrationLegacyReferenceDiagnostics(files) {
         message: "new project truth must not link to or cite wiki_legacy*; migrate the meaning or keep unresolved material in migration inboxes",
     }));
 }
-function collectQualityDiagnostics() {
+function collectQualityDiagnostics(corpus = (0, wiki_corpus_1.loadWikiCorpus)()) {
     const diagnostics = [];
-    const files = (0, wiki_files_1.wikiMarkdownFiles)();
+    const files = corpus.files;
     const titles = new Map();
     for (const file of files) {
-        const text = (0, workspace_1.read)(file);
+        const text = (0, wiki_corpus_1.wikiCorpusText)(corpus, file);
         const body = (0, workspace_1.stripMetadataHeader)(text);
         const title = (0, wiki_files_1.wikiTitleForFile)(file, text).toLowerCase();
         titles.set(title, [...(titles.get(title) ?? []), file]);
@@ -617,8 +695,9 @@ function collectQualityDiagnostics() {
         if (tldrExpected && !/##\s+TL;DR/.test(body)) {
             diagnostics.push({ code: "missing-tldr", severity: "warn", file, message: "add a compact TL;DR near the top" });
         }
-        if (status === "active" && updated && updated < workspace_1.today && /project-canonical|project-decisions|source-summary|wiki-meta/.test(scope)) {
-            diagnostics.push({ code: "stale-review", severity: "warn", file, message: `updated before today: ${updated}` });
+        const reviewAge = updated ? (0, wiki_diagnostics_1.staleReviewAge)(updated, workspace_1.today) : null;
+        if (status === "active" && reviewAge !== null && /project-canonical|project-decisions|source-summary|wiki-meta/.test(scope)) {
+            diagnostics.push({ code: "stale-review", severity: "warn", file, message: `updated ${reviewAge} days ago: ${updated}` });
         }
         if (status === "active" && !/inbox|migration-inbox/.test(scope) && /proposed|undecided|TODO|TBD|미정/i.test(body)) {
             diagnostics.push({ code: "unresolved-signal", severity: "warn", file, message: "contains pending/proposed/undecided language" });
@@ -646,9 +725,8 @@ function collectQualityDiagnostics() {
     }
     return diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code));
 }
-function collectMigrationQualityDiagnostics() {
-    const files = (0, wiki_files_1.wikiMarkdownFiles)();
-    return migrationLegacyReferenceDiagnostics(files).sort((a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code));
+function collectMigrationQualityDiagnostics(corpus = (0, wiki_corpus_1.loadWikiCorpus)()) {
+    return migrationLegacyReferenceDiagnostics(corpus.files, corpus).sort((a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code));
 }
 function collectMigrationLintDiagnostics() {
     if (legacyWikiRoots().length === 0)
@@ -674,23 +752,27 @@ function collectMigrationLintDiagnostics() {
         file,
         message: "migration review files are missing; run --migrate or keep migration diagnostics out of normal doctor",
     }));
-    diagnostics.push(...(0, migration_1.collectMigrationCoverageDiagnostics)());
-    diagnostics.push(...(0, migration_1.collectMigrationUnitMapDiagnostics)());
-    diagnostics.push(...(0, migration_1.collectMigrationSplitPlanDiagnostics)());
+    const migrationContext = (0, migration_1.loadMigrationUnitContext)();
+    diagnostics.push(...(0, migration_1.collectMigrationCoverageDiagnostics)(migrationContext));
+    diagnostics.push(...(0, migration_1.collectMigrationUnitMapDiagnostics)(migrationContext));
+    diagnostics.push(...(0, migration_1.collectMigrationSplitPlanDiagnostics)(migrationContext));
     return diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code) || a.message.localeCompare(b.message));
 }
 function runLinkCheckMode() {
-    const ok = printDiagnostics("Project wiki link-check", collectLinkDiagnostics(), (0, wiki_files_1.wikiMarkdownFiles)().length);
+    const corpus = (0, wiki_corpus_1.loadWikiCorpus)();
+    const ok = printDiagnostics("Project wiki link-check", collectLinkDiagnostics(corpus), corpus.files.length);
     if (!ok)
         process.exit(1);
 }
 function runQualityCheckMode() {
-    const ok = printDiagnostics("Project wiki quality-check", collectQualityDiagnostics(), (0, wiki_files_1.wikiMarkdownFiles)().length);
+    const corpus = (0, wiki_corpus_1.loadWikiCorpus)();
+    const ok = printDiagnostics("Project wiki quality-check", collectQualityDiagnostics(corpus), corpus.files.length);
     if (!ok)
         process.exit(1);
 }
 function runMigrationQualityCheckMode() {
-    const ok = printDiagnostics("Project wiki migration quality-check", collectMigrationQualityDiagnostics(), (0, wiki_files_1.wikiMarkdownFiles)().length);
+    const corpus = (0, wiki_corpus_1.loadWikiCorpus)();
+    const ok = printDiagnostics("Project wiki migration quality-check", collectMigrationQualityDiagnostics(corpus), corpus.files.length);
     if (!ok)
         process.exit(1);
 }
@@ -700,8 +782,9 @@ function runMigrationLintMode() {
         process.exit(1);
 }
 function runMigrationDoctorMode() {
-    const lintOk = printDiagnostics("Project wiki migration lint", collectMigrationLintDiagnostics(), (0, wiki_files_1.wikiMarkdownFiles)().length);
-    const qualityOk = printDiagnostics("Project wiki migration quality-check", collectMigrationQualityDiagnostics(), (0, wiki_files_1.wikiMarkdownFiles)().length);
+    const corpus = (0, wiki_corpus_1.loadWikiCorpus)();
+    const lintOk = printDiagnostics("Project wiki migration lint", collectMigrationLintDiagnostics(), corpus.files.length);
+    const qualityOk = printDiagnostics("Project wiki migration quality-check", collectMigrationQualityDiagnostics(corpus), corpus.files.length);
     if (!lintOk || !qualityOk)
         process.exit(1);
 }
@@ -740,11 +823,12 @@ function extractSectionBody(markdown, headingText) {
     const nextHeading = /^##\s/m.exec(afterHeading);
     return nextHeading ? afterHeading.slice(0, nextHeading.index) : afterHeading;
 }
-function collectRouterTruthDiagnostics() {
+function collectRouterTruthDiagnostics(corpus) {
     const logPath = "wiki/decisions/log.md";
-    if (!(0, workspace_1.exists)(logPath))
+    const hasLog = corpus ? corpus.fileSet.has(logPath) : (0, workspace_1.exists)(logPath);
+    if (!hasLog)
         return [];
-    const logHasDatedEntry = /\b\d{4}-\d{2}-\d{2}\b/.test((0, workspace_1.stripMetadataHeader)((0, workspace_1.read)(logPath)));
+    const logHasDatedEntry = /\b\d{4}-\d{2}-\d{2}\b/.test((0, workspace_1.stripMetadataHeader)((0, wiki_corpus_1.wikiCorpusText)(corpus, logPath)));
     if (!logHasDatedEntry)
         return [];
     const diagnostics = [];
@@ -756,9 +840,10 @@ function collectRouterTruthDiagnostics() {
         ["wiki/decisions/recent.md", "Decisions", "Decisions"],
     ];
     for (const [file, heading, surface] of routers) {
-        if (!(0, workspace_1.exists)(file))
+        const hasFile = corpus ? corpus.fileSet.has(file) : (0, workspace_1.exists)(file);
+        if (!hasFile)
             continue;
-        const section = extractSectionBody((0, workspace_1.stripMetadataHeader)((0, workspace_1.read)(file)), heading);
+        const section = extractSectionBody((0, workspace_1.stripMetadataHeader)((0, wiki_corpus_1.wikiCorpusText)(corpus, file)), heading);
         if (section === "")
             continue; // section absent — skip rather than false-positive
         if (ROUTER_TRUTH_NONE_YET_REGEX.test(section)) {
@@ -783,11 +868,11 @@ function runDoctorMode(fix) {
             console.log("skipped wiki/index.md auto-discovered pages: missing wiki/index.md");
         }
     }
-    const files = (0, wiki_files_1.wikiMarkdownFiles)();
-    const linkOk = printDiagnostics("Project wiki link-check", collectLinkDiagnostics(), files.length);
-    const qualityOk = printDiagnostics("Project wiki quality-check", collectQualityDiagnostics(), files.length);
-    const routerTruthOk = printDiagnostics("Project wiki router-truth check", collectRouterTruthDiagnostics(), files.length);
-    runLintMode();
+    const corpus = (0, wiki_corpus_1.loadWikiCorpus)();
+    const linkOk = printDiagnostics("Project wiki link-check", collectLinkDiagnostics(corpus), corpus.files.length);
+    const qualityOk = printDiagnostics("Project wiki quality-check", collectQualityDiagnostics(corpus), corpus.files.length);
+    const routerTruthOk = printDiagnostics("Project wiki router-truth check", collectRouterTruthDiagnostics(corpus), corpus.files.length);
+    runLintMode(corpus);
     if (!linkOk || !qualityOk || !routerTruthOk)
         process.exit(1);
 }
@@ -818,7 +903,7 @@ function activeLintAgentSurfaces() {
     }
     return active;
 }
-function runLintMode() {
+function runLintMode(corpus) {
     const errors = [];
     const warnings = [];
     const activeAgents = activeLintAgentSurfaces();
@@ -830,10 +915,10 @@ function runLintMode() {
         if (!(0, workspace_1.exists)(file))
             errors.push(`missing required file: ${file}`);
     }
-    const files = (0, wiki_files_1.wikiMarkdownFiles)();
+    const files = corpus?.files ?? (0, wiki_files_1.wikiMarkdownFiles)();
     const requiredMetadataKeys = ["status", "updated", "scope", "read_budget", "decision_ref", "review_trigger"];
     for (const file of files) {
-        const text = (0, workspace_1.read)(file);
+        const text = (0, wiki_corpus_1.wikiCorpusText)(corpus, file);
         if (!(0, workspace_1.hasMetadataHeader)(text)) {
             errors.push(`missing metadata header: ${file}`);
             continue;
@@ -843,8 +928,8 @@ function runLintMode() {
                 errors.push(`missing metadata key ${key}: ${file}`);
         }
     }
-    const startupLength = (0, workspace_1.exists)("wiki/startup.md") ? (0, workspace_1.read)("wiki/startup.md").length : 0;
-    const indexLength = (0, workspace_1.exists)("wiki/index.md") ? (0, workspace_1.read)("wiki/index.md").length : 0;
+    const startupLength = (0, workspace_1.exists)("wiki/startup.md") ? (0, wiki_corpus_1.wikiCorpusText)(corpus, "wiki/startup.md").length : 0;
+    const indexLength = (0, workspace_1.exists)("wiki/index.md") ? (0, wiki_corpus_1.wikiCorpusText)(corpus, "wiki/index.md").length : 0;
     if (startupLength > 3500)
         warnings.push(`startup exceeds hook budget: ${startupLength}/3500 chars`);
     if (indexLength > 4500)

package/dist/path-ignore-policy.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commonIgnoredDirectories = void 0;
+exports.ignoredDirectorySet = ignoredDirectorySet;
+exports.pathContainsIgnoredDirectory = pathContainsIgnoredDirectory;
+const workspace_1 = require("./workspace");
+exports.commonIgnoredDirectories = [
+    ".git",
+    ".codex",
+    ".claude",
+    ".cursor",
+    ".gemini",
+    "node_modules",
+    ".next",
+    "dist",
+    "build",
+    "coverage",
+    "vendor",
+    "tmp",
+    "temp",
+];
+function ignoredDirectorySet(extraDirectories = []) {
+    return new Set([...exports.commonIgnoredDirectories, ...extraDirectories]);
+}
+function pathContainsIgnoredDirectory(relativePath, ignoredDirectories) {
+    return (0, workspace_1.normalizePath)(relativePath)
+        .split("/")
+        .filter(Boolean)
+        .some((part) => ignoredDirectories.has(part));
+}

package/dist/retrieval-eval.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRetrievalMetrics = computeRetrievalMetrics;
+function bytesOf(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+function finiteNonNegativeInteger(value, fallback) {
+    if (value === undefined || !Number.isFinite(value) || value < 0)
+        return fallback;
+    return Math.floor(value);
+}
+function itemKeys(item) {
+    return new Set([item.id, item.sourceId ?? "", item.blockId ?? ""].filter(Boolean));
+}
+function itemMatches(item, expectedId) {
+    return itemKeys(item).has(expectedId);
+}
+function ratio(numerator, denominator, emptyValue) {
+    if (denominator === 0)
+        return emptyValue;
+    return numerator / denominator;
+}
+function uniqueNonEmptyStrings(values) {
+    return [...new Set((values ?? []).filter((value) => value.length > 0))];
+}
+function answerCorrect(outputText, terms) {
+    const requiredTerms = uniqueNonEmptyStrings(terms);
+    if (requiredTerms.length === 0)
+        return null;
+    const lowered = outputText.toLowerCase();
+    return requiredTerms.every((term) => lowered.includes(term.toLowerCase()));
+}
+function computeRetrievalMetrics(results, expectation, options = {}) {
+    const topK = finiteNonNegativeInteger(options.topK, results.length);
+    const considered = results.slice(0, topK);
+    const requiredSourceIds = uniqueNonEmptyStrings(expectation.requiredSourceIds);
+    const relevantSourceIds = expectation.relevantSourceIds === undefined
+        ? requiredSourceIds
+        : uniqueNonEmptyStrings(expectation.relevantSourceIds);
+    const requiredHits = requiredSourceIds.filter((sourceId) => considered.some((item) => itemMatches(item, sourceId))).length;
+    const relevantHits = relevantSourceIds.length === 0
+        ? 0
+        : considered.filter((item) => relevantSourceIds.some((sourceId) => itemMatches(item, sourceId))).length;
+    const intactBlocks = considered.filter((item) => item.blockIntact !== false).length;
+    const maxHop = considered.reduce((currentMax, item) => Math.max(currentMax, finiteNonNegativeInteger(item.hop, 0)), 0);
+    const outputText = options.outputText ?? considered.map((item) => item.text ?? "").join("\n");
+    const computedScanBytes = considered.reduce((sum, item) => {
+        if (item.bytes !== undefined && Number.isFinite(item.bytes) && item.bytes >= 0)
+            return sum + Math.floor(item.bytes);
+        return sum + bytesOf(item.text ?? "");
+    }, 0);
+    const scanBytes = options.scanBytes === undefined
+        ? computedScanBytes
+        : finiteNonNegativeInteger(options.scanBytes, 0);
+    return {
+        answer_correct: answerCorrect(outputText, expectation.requiredAnswerTerms),
+        block_integrity: ratio(intactBlocks, considered.length, 1),
+        considered_results: considered.length,
+        evidence_precision: ratio(relevantHits, considered.length, 0),
+        max_hop_count: maxHop,
+        output_bytes: bytesOf(outputText),
+        required_source_count: requiredSourceIds.length,
+        required_source_hits: requiredHits,
+        scan_bytes: scanBytes,
+        source_hit_rate: ratio(requiredHits, requiredSourceIds.length, 1),
+        top_k: topK,
+    };
+}

package/dist/wiki-concepts.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conceptIdForFile = conceptIdForFile;
+exports.wikiConceptType = wikiConceptType;
+exports.conceptFromPage = conceptFromPage;
+exports.readWikiConcepts = readWikiConcepts;
+const wiki_files_1 = require("./wiki-files");
+const workspace_1 = require("./workspace");
+function conceptIdForFile(file) {
+    return file.replace(/^wiki\//, "").replace(/\.(md|mdx)$/i, "");
+}
+function wikiConceptType(file, scope) {
+    if (scope === "startup-router" || file === "wiki/startup.md")
+        return "Startup Router";
+    if (scope === "wiki-router" || file === "wiki/index.md" || /^wiki\/indexes\//.test(file))
+        return "Wiki Router";
+    if (scope === "project-canonical" || /^wiki\/canonical\//.test(file))
+        return "Project Canonical Concept";
+    if (scope === "project-decisions" || /^wiki\/decisions\//.test(file))
+        return "Project Decision";
+    if (scope === "source-summary" || /^wiki\/sources\//.test(file))
+        return "Source Summary";
+    if (scope === "wiki-meta" || /^wiki\/meta\//.test(file))
+        return "Wiki Operations Concept";
+    if (/^migration-/.test(scope) || /^wiki\/migration\//.test(file))
+        return "Migration Ledger";
+    if (scope === "inbox" || /^wiki\/inbox\//.test(file))
+        return "Project Candidate";
+    return "Wiki Concept";
+}
+function conceptFromPage(file, text) {
+    const scope = (0, workspace_1.metadataValue)(text, "scope") || "-";
+    const tldr = (0, wiki_files_1.firstTldrBullet)(text);
+    return {
+        budget: (0, workspace_1.metadataValue)(text, "read_budget") || "-",
+        conceptId: conceptIdForFile(file),
+        description: tldr || (0, wiki_files_1.compactSummary)(text),
+        file,
+        reviewTrigger: (0, workspace_1.metadataValue)(text, "review_trigger"),
+        scope,
+        status: (0, workspace_1.metadataValue)(text, "status") || "-",
+        timestamp: (0, workspace_1.metadataValue)(text, "updated"),
+        title: (0, wiki_files_1.wikiTitleForFile)(file, text),
+        type: wikiConceptType(file, scope),
+    };
+}
+function readWikiConcepts(files = (0, wiki_files_1.wikiMarkdownFiles)()) {
+    return files.map((file) => conceptFromPage(file, (0, workspace_1.read)(file)));
+}

package/dist/wiki-corpus.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadWikiCorpus = loadWikiCorpus;
+exports.wikiCorpusGraph = wikiCorpusGraph;
+exports.wikiCorpusText = wikiCorpusText;
+const wiki_graph_1 = require("./wiki-graph");
+const workspace_1 = require("./workspace");
+const wiki_files_1 = require("./wiki-files");
+function loadWikiCorpus() {
+    const files = (0, wiki_files_1.wikiMarkdownFiles)();
+    const pages = files.map((file) => ({ file, text: (0, workspace_1.read)(file) }));
+    return {
+        files,
+        fileSet: new Set(files),
+        pages,
+        textByFile: new Map(pages.map((page) => [page.file, page.text])),
+    };
+}
+function wikiCorpusGraph(corpus) {
+    corpus.graph ??= (0, wiki_graph_1.buildWikiGraph)(corpus.pages);
+    return corpus.graph;
+}
+function wikiCorpusText(corpus, file) {
+    return corpus?.textByFile.get(file) ?? (0, workspace_1.read)(file);
+}

package/dist/wiki-diagnostics.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staleReviewAgeDays = void 0;
+exports.staleReviewAge = staleReviewAge;
+exports.staleReviewAgeDays = 30;
+function dateOnlyMillis(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return null;
+    const millis = Date.parse(`${value}T00:00:00Z`);
+    return Number.isNaN(millis) ? null : millis;
+}
+function staleReviewAge(updated, currentDate) {
+    const updatedMillis = dateOnlyMillis(updated);
+    const currentMillis = dateOnlyMillis(currentDate);
+    if (updatedMillis === null || currentMillis === null)
+        return null;
+    const ageDays = Math.floor((currentMillis - updatedMillis) / 86_400_000);
+    return ageDays > exports.staleReviewAgeDays ? ageDays : null;
+}