project-librarian 0.2.1 → 0.3.0

package/dist/code-index-file-policy.js

@@ -33,20 +33,28 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.maxIndexedBytes = exports.ignoredDirectories = void 0;
+exports.SMALL_REPO_FILE_THRESHOLD = exports.maxIndexedBytes = exports.ignoredDirectories = exports.codeEvidenceDirectory = void 0;
 exports.fileLanguage = fileLanguage;
 exports.isJavaScriptLike = isJavaScriptLike;
 exports.shouldIndexFile = shouldIndexFile;
 exports.isIgnoredCodePath = isIgnoredCodePath;
+exports.discoverCodeFiles = discoverCodeFiles;
+exports.smallRepoCodeIndexGate = smallRepoCodeIndexGate;
+const childProcess = __importStar(require("node:child_process"));
+const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const workspace_1 = require("./workspace");
+// Single source of truth for the disposable code-evidence directory name. Both
+// the heavy code-index module and the light bootstrap path (hooks.ts) key off
+// this; keeping it here avoids loading typescript/node:sqlite during bootstrap.
+exports.codeEvidenceDirectory = ".project-wiki";
 exports.ignoredDirectories = new Set([
     ".git",
     ".codex",
     ".claude",
     ".cursor",
     ".gemini",
-    ".project-wiki",
+    exports.codeEvidenceDirectory,
     "node_modules",
     ".next",
     "dist",
@@ -120,3 +128,98 @@ function isIgnoredCodePath(relativePath) {
         .filter(Boolean)
         .some((part) => exports.ignoredDirectories.has(part));
 }
+// Mirrors normalizeProjectRelative in code-index.ts for git ls-files output, but
+// throws instead of exiting so the light bootstrap path can use discovery too.
+// Git emits repo-relative paths, so the escape branch is unreachable for real
+// output; it stays as a loud guard, not a recovery path.
+function normalizeGitIndexedFile(input) {
+    const raw = input.trim() || ".";
+    const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(workspace_1.root, raw);
+    const rootResolved = path.resolve(workspace_1.root);
+    if (resolved !== rootResolved && !resolved.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new Error(`git-indexed file must stay inside the project root: ${input}`);
+    }
+    return (0, workspace_1.normalizePath)(path.relative(rootResolved, resolved)) || ".";
+}
+function walkCodeFiles(relativePath, files = []) {
+    if (isIgnoredCodePath(relativePath))
+        return files.sort();
+    const target = (0, workspace_1.abs)(relativePath);
+    if (!fs.existsSync(target))
+        return files;
+    const stat = fs.statSync(target);
+    if (stat.isFile()) {
+        if (stat.size <= exports.maxIndexedBytes && shouldIndexFile(relativePath))
+            files.push(relativePath);
+        return files.sort();
+    }
+    for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+        const child = (0, workspace_1.normalizePath)(path.join(relativePath, entry.name));
+        if (entry.isDirectory()) {
+            if (!exports.ignoredDirectories.has(entry.name))
+                walkCodeFiles(child, files);
+        }
+        else if (entry.isFile() && shouldIndexFile(child)) {
+            const childStat = fs.statSync((0, workspace_1.abs)(child));
+            if (childStat.size <= exports.maxIndexedBytes)
+                files.push(child);
+        }
+    }
+    return files.sort();
+}
+function gitTrackedAndUnignoredFiles(scopes) {
+    try {
+        const output = childProcess.execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...scopes], {
+            cwd: workspace_1.root,
+            encoding: "buffer",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return output.toString("utf8").split("\0").filter(Boolean).map((file) => normalizeGitIndexedFile(file));
+    }
+    catch {
+        return null;
+    }
+}
+function discoverCodeFiles(scopes) {
+    const gitFiles = gitTrackedAndUnignoredFiles(scopes);
+    const candidates = gitFiles ?? scopes.flatMap((scope) => walkCodeFiles(scope));
+    return Array.from(new Set(candidates))
+        .filter((file) => !isIgnoredCodePath(file))
+        .filter((file) => fs.existsSync((0, workspace_1.abs)(file)))
+        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).isFile())
+        .filter((file) => shouldIndexFile(file))
+        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).size <= exports.maxIndexedBytes)
+        .sort();
+}
+// --- Scale-aware code-evidence gate ------------------------------------------
+//
+// Threshold in indexable files (the discoverCodeFiles count) below which the
+// code-evidence surfaces warn (--code-index) or skip by default (bootstrap MCP
+// auto-registration). Evidence: stageR1 real-corpus run, 2026-06-12
+// (benchmarks/reports/llm/stageR1-real.md) — the ~1.2k-file repo LOST every
+// measured question (impact_trace +116.9%, workspace_graph +106.5% cost-weighted
+// tokens vs direct reads) while the ~11.8k-file repo still lost the cheap
+// ownership lookup (+99.0%) and won only the expensive traversal questions
+// (impact_trace -27.7%, workspace_graph -2.6%); stage2d synthetic scales
+// (benchmarks/reports/llm/stage2d-codegraph.md) lost across the board. 5000 sits
+// between the two real measured points: an n=2 extrapolation (1.2k all-loss /
+// 11.8k partial win), explicitly subject to revision as more scales are measured.
+exports.SMALL_REPO_FILE_THRESHOLD = 5000;
+// Decision for the --code-index scale gate: below the threshold the build halts
+// with an evidence-citing warning unless the caller explicitly acknowledged the
+// measured cost. Consent is honored, never refused (2026-06-12 decision: defaults
+// follow the evidence, explicit requests get warning + consent).
+function smallRepoCodeIndexGate(indexableFileCount, acknowledged) {
+    if (acknowledged || indexableFileCount >= exports.SMALL_REPO_FILE_THRESHOLD)
+        return { proceed: true, warning: "" };
+    return {
+        proceed: false,
+        warning: [
+            `--code-index halted: ${indexableFileCount} indexable files is below the ${exports.SMALL_REPO_FILE_THRESHOLD}-file scale threshold.`,
+            "Measured evidence (real-corpus stageR1): on a ~1.2k-file repo the code-evidence track cost MORE on every measured question (impact_trace +116.9%, workspace_graph +106.5% cost-weighted tokens vs direct reads), and even on a ~11.8k-file repo ownership-style cheap lookups lost (+99.0%); only expensive traversal questions won there (impact_trace -27.7%).",
+            "Reports: benchmarks/reports/llm/stageR1-real.md and benchmarks/reports/llm/stage2d-codegraph.md in the project-librarian repo (threshold is an n=2 extrapolation, subject to revision).",
+            "Not measured, so not disproven: human-facing report value (--code-report) and answer accuracy/grounding value. This gate reflects measured LLM token cost only.",
+            "To build the index anyway, re-run with --acknowledge-small-repo.",
+        ].join("\n"),
+    };
+}

package/dist/code-index.js

@@ -33,6 +33,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeEvidenceIndexUnavailableError = void 0;
+exports.codeIndexStaleness = codeIndexStaleness;
+exports.codeownerRules = codeownerRules;
+exports.matchedCodeownerRules = matchedCodeownerRules;
+exports.ownershipContext = ownershipContext;
+exports.ownershipInfo = ownershipInfo;
+exports.evidenceCoverage = evidenceCoverage;
+exports.workspaceSummary = workspaceSummary;
+exports.workspaceDependencyGraph = workspaceDependencyGraph;
+exports.codeReportMetadata = codeReportMetadata;
+exports.codeImpact = codeImpact;
+exports.searchSymbols = searchSymbols;
+exports.openCodeEvidenceDatabaseForServing = openCodeEvidenceDatabaseForServing;
 exports.runCodeIndexMode = runCodeIndexMode;
 exports.runCodeQueryMode = runCodeQueryMode;
 exports.runCodeReportMode = runCodeReportMode;
@@ -43,7 +56,6 @@ exports.runCodeSearchSymbolMode = runCodeSearchSymbolMode;
 exports.isCodeEvidenceMode = isCodeEvidenceMode;
 exports.isCodeEvidenceModeFor = isCodeEvidenceModeFor;
 const crypto = __importStar(require("node:crypto"));
-const childProcess = __importStar(require("node:child_process"));
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const ts = __importStar(require("typescript"));
@@ -52,7 +64,6 @@ const code_index_db_1 = require("./code-index-db");
 const code_index_file_policy_1 = require("./code-index-file-policy");
 const code_index_sql_1 = require("./code-index-sql");
 const workspace_1 = require("./workspace");
-const codeEvidenceDirectory = ".project-wiki";
 const codeIndexSchemaVersion = "3";
 const httpMethods = new Set(["all", "delete", "get", "patch", "post", "put"]);
 const treeSitterGrammarPackages = {
@@ -117,11 +128,11 @@ function normalizeProjectRelative(input, label) {
     return (0, workspace_1.normalizePath)(path.relative(rootResolved, resolved)) || ".";
 }
 function codeEvidenceDatabasePath() {
-    const raw = args_1.codeIndexOutput.trim() || `${codeEvidenceDirectory}/code-evidence.sqlite`;
+    const raw = args_1.codeIndexOutput.trim() || `${code_index_file_policy_1.codeEvidenceDirectory}/code-evidence.sqlite`;
     const absolutePath = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(workspace_1.root, raw);
-    const evidenceRoot = path.resolve(workspace_1.root, codeEvidenceDirectory);
+    const evidenceRoot = path.resolve(workspace_1.root, code_index_file_policy_1.codeEvidenceDirectory);
     if (absolutePath === evidenceRoot || !absolutePath.startsWith(`${evidenceRoot}${path.sep}`)) {
-        fail(`--code-index-out must stay inside ${codeEvidenceDirectory}/`);
+        fail(`--code-index-out must stay inside ${code_index_file_policy_1.codeEvidenceDirectory}/`);
     }
     return {
         absolutePath,
@@ -182,56 +193,6 @@ function extractionProfile(relativePath, parserMode) {
         return "config";
     return "inventory-only";
 }
-function walkCodeFiles(relativePath, files = []) {
-    if ((0, code_index_file_policy_1.isIgnoredCodePath)(relativePath))
-        return files.sort();
-    const target = (0, workspace_1.abs)(relativePath);
-    if (!fs.existsSync(target))
-        return files;
-    const stat = fs.statSync(target);
-    if (stat.isFile()) {
-        if (stat.size <= code_index_file_policy_1.maxIndexedBytes && (0, code_index_file_policy_1.shouldIndexFile)(relativePath))
-            files.push(relativePath);
-        return files.sort();
-    }
-    for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
-        const child = (0, workspace_1.normalizePath)(path.join(relativePath, entry.name));
-        if (entry.isDirectory()) {
-            if (!code_index_file_policy_1.ignoredDirectories.has(entry.name))
-                walkCodeFiles(child, files);
-        }
-        else if (entry.isFile() && (0, code_index_file_policy_1.shouldIndexFile)(child)) {
-            const childStat = fs.statSync((0, workspace_1.abs)(child));
-            if (childStat.size <= code_index_file_policy_1.maxIndexedBytes)
-                files.push(child);
-        }
-    }
-    return files.sort();
-}
-function gitTrackedAndUnignoredFiles(scopes) {
-    try {
-        const output = childProcess.execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...scopes], {
-            cwd: workspace_1.root,
-            encoding: "buffer",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return output.toString("utf8").split("\0").filter(Boolean).map((file) => normalizeProjectRelative(file, "git-indexed file"));
-    }
-    catch {
-        return null;
-    }
-}
-function discoverCodeFiles(scopes) {
-    const gitFiles = gitTrackedAndUnignoredFiles(scopes);
-    const candidates = gitFiles ?? scopes.flatMap((scope) => walkCodeFiles(scope));
-    return Array.from(new Set(candidates))
-        .filter((file) => !(0, code_index_file_policy_1.isIgnoredCodePath)(file))
-        .filter((file) => fs.existsSync((0, workspace_1.abs)(file)))
-        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).isFile())
-        .filter((file) => (0, code_index_file_policy_1.shouldIndexFile)(file))
-        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).size <= code_index_file_policy_1.maxIndexedBytes)
-        .sort();
-}
 function readCodeFile(relativePath, parserMode = "default") {
     const text = fs.readFileSync((0, workspace_1.abs)(relativePath), "utf8");
     return {
@@ -1163,7 +1124,7 @@ function removeDatabaseFiles(databasePath) {
 function codeIndexStaleness(database) {
     const scopes = indexedScopes(database);
     const parserMode = indexedParserMode(database);
-    const current = new Map(discoverCodeFiles(scopes.length > 0 ? scopes : ["."]).map((file) => {
+    const current = new Map((0, code_index_file_policy_1.discoverCodeFiles)(scopes.length > 0 ? scopes : ["."]).map((file) => {
         const codeFile = readCodeFile(file, parserMode);
         return [codeFile.path, codeFile.hash];
     }));
@@ -1311,6 +1272,13 @@ function matchingCodeowners(filePath, rules) {
     const matches = rules.filter((rule) => codeownerPatternMatches(rule.pattern, filePath));
     return matches[matches.length - 1]?.owners ?? [];
 }
+// Return every CODEOWNERS rule that matches a path, in file order. The last entry
+// is the effective owner under last-match-wins; earlier entries are overridden.
+// Reuses the same matcher as matchingCodeowners so precedence answers stay
+// consistent with --code-report / --code-impact.
+function matchedCodeownerRules(filePath, rules) {
+    return rules.filter((rule) => codeownerPatternMatches(rule.pattern, filePath));
+}
 function ownershipContext() {
     return {
         codeownerRules: codeownerRules(),
@@ -1670,16 +1638,66 @@ function codeImpact(database, target) {
         })).sort((left, right) => right.files - left.files || left.owner.localeCompare(right.owner)),
     };
 }
+// Symbol search reusing the exact SELECT behind --code-search-symbol so the MCP
+// code_search tool returns identical rows without duplicating the query string.
+function searchSymbols(database, term) {
+    const like = `%${term}%`;
+    return database.prepare("SELECT name, kind, file_path, line, signature FROM symbols WHERE name LIKE ? OR signature LIKE ? ORDER BY file_path, line LIMIT 50").all(like, like);
+}
+// Error thrown when the code-evidence index is missing or schema-incompatible.
+// The MCP server catches this to return an isError tool result (tools/list still
+// works); CLI modes keep their own process.exit path via requireExistingIndex.
+class CodeEvidenceIndexUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CodeEvidenceIndexUnavailableError";
+    }
+}
+exports.CodeEvidenceIndexUnavailableError = CodeEvidenceIndexUnavailableError;
+// Open the existing .project-wiki code-evidence index READ-ONLY for serving:
+// validates existence and schema version, then pins PRAGMA query_only = ON. Uses
+// the same path resolution and schema constant as the indexer so the server and
+// the writer share one contract. Throws CodeEvidenceIndexUnavailableError (never
+// exits) so the MCP server can answer with guidance to run --code-index.
+function openCodeEvidenceDatabaseForServing() {
+    const databasePath = codeEvidenceDatabasePath();
+    if (!fs.existsSync(databasePath.absolutePath)) {
+        throw new CodeEvidenceIndexUnavailableError(`missing code evidence index: ${databasePath.relativePath}; run \`project-librarian --code-index\` first`);
+    }
+    const database = openDatabase(databasePath.absolutePath);
+    let schemaVersion = "";
+    try {
+        schemaVersion = readMetaValue(database, "schema_version");
+    }
+    catch (error) {
+        database.close();
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CodeEvidenceIndexUnavailableError(`code evidence index at ${databasePath.relativePath} is not readable; rebuild with \`project-librarian --code-index\`. Error: ${message}`);
+    }
+    if (schemaVersion !== codeIndexSchemaVersion) {
+        database.close();
+        throw new CodeEvidenceIndexUnavailableError(`code evidence index schema version ${schemaVersion || "(missing)"} is incompatible with ${codeIndexSchemaVersion}; rebuild with \`project-librarian --code-index\``);
+    }
+    database.exec("PRAGMA query_only = ON");
+    return { database, relativePath: databasePath.relativePath };
+}
 function prepareOutputPath() {
     const databasePath = codeEvidenceDatabasePath();
     (0, workspace_1.mkdirp)(path.dirname(databasePath.relativePath));
-    (0, workspace_1.mkdirp)(codeEvidenceDirectory);
-    fs.writeFileSync((0, workspace_1.abs)(`${codeEvidenceDirectory}/.gitignore`), "*\n!.gitignore\n");
+    (0, workspace_1.mkdirp)(code_index_file_policy_1.codeEvidenceDirectory);
+    fs.writeFileSync((0, workspace_1.abs)(`${code_index_file_policy_1.codeEvidenceDirectory}/.gitignore`), "*\n!.gitignore\n");
 }
 function runCodeIndexMode() {
     const databasePath = codeEvidenceDatabasePath();
     const scopes = codeScopes();
     const parserMode = selectedCodeParserMode();
+    // Scale gate before ANY write or database work: below the measured threshold
+    // the build halts with the evidence-citing warning unless --acknowledge-small-repo
+    // was passed (2026-06-12 scale-aware guidance decision).
+    const discoveredFiles = (0, code_index_file_policy_1.discoverCodeFiles)(scopes);
+    const scaleGate = (0, code_index_file_policy_1.smallRepoCodeIndexGate)(discoveredFiles.length, args_1.acknowledgeSmallRepoMode);
+    if (!scaleGate.proceed)
+        fail(scaleGate.warning);
     const existingIndex = fs.existsSync(databasePath.absolutePath);
     if (args_1.codeIndexIncrementalMode && !existingIndex) {
         fail(`--incremental requires an existing compatible code evidence index: ${databasePath.relativePath}`);
@@ -1706,7 +1724,7 @@ function runCodeIndexMode() {
         if (!incremental)
             setupDatabase(database);
         const statements = createIndexStatements(database);
-        const currentFiles = discoverCodeFiles(scopes).map((filePath) => readCodeFile(filePath, parserMode));
+        const currentFiles = discoveredFiles.map((filePath) => readCodeFile(filePath, parserMode));
         const currentByPath = new Map(currentFiles.map((file) => [file.path, file]));
         const indexed = incremental ? new Map(database.prepare("SELECT path, hash FROM files").all().map((row) => [String(row.path), String(row.hash)])) : new Map();
         const deletedPaths = incremental ? Array.from(indexed.keys()).filter((filePath) => !currentByPath.has(filePath)) : [];

package/dist/hooks.js

@@ -39,8 +39,15 @@ exports.upsertHookConfig = upsertHookConfig;
 exports.upsertClaudeHookConfig = upsertClaudeHookConfig;
 exports.upsertGeminiHookConfig = upsertGeminiHookConfig;
 exports.upsertCursorHookConfig = upsertCursorHookConfig;
+exports.codeEvidenceIndexExists = codeEvidenceIndexExists;
+exports.mcpRegistrationGate = mcpRegistrationGate;
+exports.upsertClaudeMcpConfig = upsertClaudeMcpConfig;
+exports.upsertCursorMcpConfig = upsertCursorMcpConfig;
+exports.upsertGeminiMcpConfig = upsertGeminiMcpConfig;
 const childProcess = __importStar(require("node:child_process"));
+const fs = __importStar(require("node:fs"));
 const args_1 = require("./args");
+const code_index_file_policy_1 = require("./code-index-file-policy");
 const workspace_1 = require("./workspace");
 function upsertGitHooksPath() {
     if (args_1.noGitConfigMode)
@@ -136,6 +143,75 @@ function upsertCursorHookConfig() {
     (0, workspace_1.write)(relativePath, next);
     return previous === next ? "exists" : previous ? "updated" : "created";
 }
+const mcpServerName = "project-librarian";
+// Candidate local-runner paths, project root relative, in the recorded
+// local-runner-first order (mirrors validationTrailers()). The first existing
+// runner wins; absent any local install we register the published binary.
+const localRunnerCandidates = [
+    "tools/project-librarian/dist/init-project-wiki.js",
+    ".codex/skills/project-librarian/dist/init-project-wiki.js",
+    ".claude/skills/project-librarian/dist/init-project-wiki.js",
+    ".cursor/skills/project-librarian/dist/init-project-wiki.js",
+    ".gemini/skills/project-librarian/dist/init-project-wiki.js",
+];
+// Deterministic command policy for the registered MCP server: if the repo
+// contains a local runner, register `node <runner> mcp`; otherwise register the
+// installed binary `project-librarian mcp`. This mirrors the local-runner-first
+// skill policy (run the installed local copy with node, not npx) so registration
+// does not depend on network/registry access. The runner path is stored project
+// relative so the registration stays portable across clones.
+function mcpServerEntry() {
+    const runner = localRunnerCandidates.find((candidate) => fs.existsSync((0, workspace_1.abs)(candidate)));
+    if (runner)
+        return { command: "node", args: [runner, "mcp"] };
+    return { command: mcpServerName, args: ["mcp"] };
+}
+// Preservation-first, idempotent merge of the project-librarian MCP server into a
+// JSON config file's `mcpServers` map. Unknown keys and other servers are never
+// clobbered; only `mcpServers["project-librarian"]` is set. A second run with an
+// unchanged entry returns "exists". Used for Claude `.mcp.json`, Cursor
+// `.cursor/mcp.json`, and (via the same map) Gemini `.gemini/settings.json`.
+//
+// Codex boundary: `codex mcp` only manages USER-level config (~/.codex/config.toml
+// via `codex mcp add`); there is no documented project-level MCP config file under
+// `.codex/`. Per the no-user-level-writes rule we do not register Codex here; the
+// README documents running `codex mcp add project-librarian -- node <runner> mcp`.
+function upsertMcpServersFile(relativePath) {
+    const config = (0, workspace_1.parseJson)(relativePath, {});
+    if (!config.mcpServers || typeof config.mcpServers !== "object" || Array.isArray(config.mcpServers)) {
+        config.mcpServers = {};
+    }
+    config.mcpServers[mcpServerName] = mcpServerEntry();
+    const next = `${JSON.stringify(config, null, 2)}\n`;
+    const previous = (0, workspace_1.exists)(relativePath) ? (0, workspace_1.read)(relativePath) : "";
+    if (previous === next)
+        return "exists";
+    (0, workspace_1.write)(relativePath, next);
+    return previous ? "updated" : "created";
+}
+function codeEvidenceIndexExists() {
+    return (0, workspace_1.walkFilesUnder)(code_index_file_policy_1.codeEvidenceDirectory, (file) => file.endsWith(".sqlite")).length > 0;
+}
+function mcpRegistrationGate() {
+    if (codeEvidenceIndexExists())
+        return { register: true };
+    const indexableFileCount = (0, code_index_file_policy_1.discoverCodeFiles)(["."]).length;
+    if (indexableFileCount >= code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD)
+        return { register: true };
+    return {
+        register: false,
+        reason: `skipped-small-repo ${indexableFileCount} indexable files < ${code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD} (code-evidence tools measured costlier than direct reads at this scale: stageR1; opt in via --code-index --acknowledge-small-repo, then re-run bootstrap)`,
+    };
+}
+function upsertClaudeMcpConfig() {
+    return upsertMcpServersFile(".mcp.json");
+}
+function upsertCursorMcpConfig() {
+    return upsertMcpServersFile(".cursor/mcp.json");
+}
+function upsertGeminiMcpConfig() {
+    return upsertMcpServersFile(".gemini/settings.json");
+}
 function buildStartupHookScript(output) {
     return `#!/usr/bin/env node
 
@@ -183,6 +259,8 @@ const sections = files
 
 const additionalContext = [
   "[Project wiki startup review]",
+  "Injected context: wiki/startup.md and wiki/index.md are ALREADY included below this line.",
+  "Do not re-read these two files this session; route any further reads through the index.",
   "Use ./wiki as the project-planning source of truth only. Start with compact routing context; read detailed project canonical, decision, or meta files on demand.",
   "Project canonical content language is selected from user/project context; do not assume a fixed default language.",
   "When project planning content is added, changed, or removed, update ./wiki in the same turn.",