project-librarian 0.5.4 → 0.5.5

package/README.ko.md

@@ -64,7 +64,7 @@ npx project-librarian@latest install --scope user --agents all
 - **검토 가능한 위키 그래프.** `--wiki-visualize`는 `.project-wiki/` 아래에 독립 실행형 HTML 그래프를 작성해, 시작 컨텍스트를 늘리지 않고 페이지 유형·라우터 깊이·역링크·결정 참조를 보여줍니다.
 - **막연한 표현이 아니라 측정값.** 모든 성능 주장은 격리된 Codex 벤치마크에서 나오며, 손해를 본 경우도 이긴 경우 바로 옆에 보여 줍니다.
 - **로컬 세션 핸드오프.** `--handoff-save`는 `.project-wiki/session/` 아래에 생성형 재개 메모를 저장합니다. 시작 훅은 존재만 알려주므로 실행 로그가 canonical 위키 정본으로 섞이지 않습니다.
-- **선택적 코드 근거.** 재생성 가능한 SQLite 인덱스와 답변 형태 MCP 도구가 영향·소유권·워크스페이스 그래프 질문에 답하며, 추가 런타임 의존성이 전혀 없습니다.
+- **선택적 코드 근거.** 재생성 가능한 SQLite 인덱스와 답변 형태 MCP 도구가 영향·소유권·워크스페이스 그래프 질문에 답하며, MCP SDK 의존성은 추가하지 않습니다.
 - **다시 실행해도 안전.** 부트스트랩은 멱등하고 기존 내용 보존을 우선하며, 진단은 깨진 경로·도달 불가 페이지·오래된 사실을 에이전트가 오해하기 전에 잡아냅니다.
 
 ## 존재 이유
@@ -297,7 +297,9 @@ MCP 서버 등록 (`mcpServers`에 기존 항목 보존하며 병합):
 
 ## 코드 근거 MCP 서버
 
-`project-librarian mcp`는 직접 구현한 stdio MCP 서버(줄바꿈 구분 JSON 위의 JSON-RPC 2.0, 추가 런타임 의존성 없음)를 실행해 기존 `.project-wiki` 코드 근거 인덱스를 읽기 전용으로 제공합니다. 답변 형태 도구 — `code_context_pack`, `code_impact`, `code_ownership`(CODEOWNERS 마지막 일치 우선순위), `code_workspace_graph`, `code_search`, `code_status` — 를 노출하며, 각 응답은 한 줄 답변으로 시작해 간결한 경로/심볼/시그니처 근거가 뒤따르고, 응답마다 길이를 제한하며, `code_status`가 인덱스가 오래되었다고 보고하면 경고를 앞에 붙입니다.
+`project-librarian mcp`는 직접 구현한 stdio MCP 서버(줄바꿈 구분 JSON 위의 JSON-RPC 2.0, MCP SDK 의존성 없음)를 실행해 기존 `.project-wiki` 코드 근거 인덱스를 읽기 전용으로 제공합니다. 패키지의 필수 런타임 의존성은 `typescript`이며, 코드 근거 기능은 Node의 `node:sqlite`도 사용하고 Tree-sitter 문법 패키지는 선택 사항입니다. 답변 형태 도구 — `code_context_pack`, `code_impact`, `code_ownership`(CODEOWNERS 마지막 일치 우선순위), `code_workspace_graph`, `code_search`, `code_status` — 를 노출하며, 각 응답은 한 줄 답변으로 시작해 간결한 경로/심볼/시그니처 근거가 뒤따르고, 응답마다 길이를 제한하며, `code_status`가 인덱스가 오래되었다고 보고하면 경고를 앞에 붙입니다.
+
+`--code-report`, `--code-impact`, `--code-context-pack`, MCP 도구 출력을 현재 코드 구조 근거로 인용하기 전에는 `project-librarian --code-status` 또는 MCP `code_status`를 실행해 `stale_files: 0`인지 확인하세요. 오래된 보고서는 재빌드가 필요하다는 신호이지 권위 있는 프로젝트 진실이 아닙니다.
 
 서버는 고정 리소스 — `project-librarian://wiki/startup`, `project-librarian://wiki/index`, `project-librarian://code/status` — 와 위키 분류 갱신, 코드 영향 추적, 유지보수 개선 검토, 검색 품질 검토용 프롬프트 템플릿도 제공합니다. 리소스 읽기는 임의 파일 경로가 아니라 고정 URI 레지스트리에서만 처리합니다.
 
@@ -431,6 +433,8 @@ npm pack --dry-run
 
 `npm run test:coverage`는 Node 내장 test coverage에 보수적인 line, branch, function threshold를 적용하므로 coverage를 단순 보고서가 아니라 회귀 게이트로 사용합니다.
 
+지원 런타임 하한은 Node.js 22.13+입니다. TypeScript가 지원 사용자에게 없는 API를 허용하지 않도록 개발용 타입 정의는 Node 22 지원 계약에 맞추거나 Node 22 호환성 검사를 함께 둬야 합니다.
+
 `npm run release:check`는 로컬 전용 관리자 게이트입니다. 테스트, Node 내장 coverage, 벤치마크 파서 smoke, real-corpus 오프라인 데모, 벤치마크 release preview, 벤치마크 claim ledger 분류, raw 보관 상태 감사, package dry-run 검사, dist 실행 가능 여부와 소스 동기화, README 벤치마크 claim 경계 문구를 확인합니다. publish하지 않고 raw 벤치마크 산출물을 삭제하지 않으며 measured Codex 벤치마크도 실행하지 않습니다.
 
 `release:check` 통과는 런타임 보증이 아니라 재현 가능한 릴리스 준비 근거로 봐야 합니다. 현재 checkout에서 위 로컬 게이트를 통과했음을 증명하며, package dry run이 예상 publish 경계(`agents/`, `dist/`, `LICENSE`, `README.md`, `README.ko.md`, `SKILL.md`) 안에 머물고 소스 파일, 테스트, 저장소 로컬 위키/워크플로 상태, raw 벤치마크 출력, 로컬 캐시를 제외하는지도 확인합니다.

package/README.md

@@ -64,7 +64,7 @@ npx project-librarian@latest install --scope user --agents all
 - **Inspectable wiki graph.** `--wiki-visualize` writes a self-contained HTML graph under `.project-wiki/`, showing page types, router depth, backlinks, and decision references without adding to startup context.
 - **Measured, not hand-wavy.** Every performance claim comes from hermetic Codex benchmarks — and the cases where it costs *more* are shown right next to the wins.
 - **Local session handoff.** `--handoff-save` writes generated resume notes under `.project-wiki/session/`; startup hooks only point to it, so rolling execution memory does not become canonical wiki truth.
-- **Optional code evidence.** A regenerable SQLite index plus answer-shaped MCP tools answer impact, ownership, and workspace-graph questions, with zero extra runtime dependencies.
+- **Optional code evidence.** A regenerable SQLite index plus answer-shaped MCP tools answer impact, ownership, and workspace-graph questions without adding an MCP SDK dependency.
 - **Safe to re-run.** Bootstrap is idempotent and preservation-first; diagnostics flag broken routes, unreachable pages, and stale truth before they mislead an agent.
 
 ## Why It Exists
@@ -297,7 +297,9 @@ Disposable code evidence cache:
 
 ## Code Evidence MCP Server
 
-`project-librarian mcp` runs a hand-rolled stdio MCP server (JSON-RPC 2.0 over newline-delimited JSON, no extra runtime dependencies) that serves the existing `.project-wiki` code-evidence index read-only. It exposes answer-shaped tools — `code_context_pack`, `code_impact`, `code_ownership` (CODEOWNERS last-match precedence), `code_workspace_graph`, `code_search`, and `code_status` — whose responses lead with a one-line answer, follow with compact path/symbol/signature evidence, cap each reply, and prepend a warning when `code_status` reports the index is stale.
+`project-librarian mcp` runs a hand-rolled stdio MCP server (JSON-RPC 2.0 over newline-delimited JSON, no MCP SDK dependency) that serves the existing `.project-wiki` code-evidence index read-only. The package's hard runtime dependency is `typescript`; code evidence also uses Node's `node:sqlite`, with Tree-sitter grammars remaining optional. The server exposes answer-shaped tools — `code_context_pack`, `code_impact`, `code_ownership` (CODEOWNERS last-match precedence), `code_workspace_graph`, `code_search`, and `code_status` — whose responses lead with a one-line answer, follow with compact path/symbol/signature evidence, cap each reply, and prepend a warning when `code_status` reports the index is stale.
+
+Before citing `--code-report`, `--code-impact`, `--code-context-pack`, or MCP tool output as current code-structure evidence, run `project-librarian --code-status` or MCP `code_status` and require `stale_files: 0`. Stale reports are pointers for rebuild, not authoritative project truth.
 
 The server also exposes fixed resources — `project-librarian://wiki/startup`, `project-librarian://wiki/index`, and `project-librarian://code/status` — plus prompt templates for wiki taxonomy updates, code impact traces, maintenance improvement reviews, and retrieval quality reviews. Resource reads come from a fixed URI registry rather than arbitrary filesystem paths.
 
@@ -431,6 +433,8 @@ When editing TypeScript under `src/`, rebuild before committing so `dist/` stays
 
 `npm run test:coverage` uses Node's native test coverage with conservative line, branch, and function thresholds so coverage is a regression gate, not only a report.
 
+The supported runtime floor is Node.js 22.13+. Development type definitions should stay aligned with the Node 22 support contract or be backed by a Node 22 compatibility check so TypeScript does not admit APIs unavailable to supported users.
+
 `npm run release:check` is a local-only maintainer gate: it runs tests, native Node coverage, benchmark parser smoke, the real-corpus offline demo, benchmark release preview, benchmark claim-ledger classification, raw hygiene audit, package dry-run inspection, dist executable/parity checks, and README benchmark-claim boundary checks. It never publishes, never deletes raw benchmark artifacts, and never launches a measured Codex benchmark.
 
 Treat a green `release:check` as a reproducible release-readiness bundle, not a runtime guarantee: it proves those local gates on the current checkout, including that the package dry run stays inside the expected publish boundary (`agents/`, `dist/`, `LICENSE`, `README.md`, `README.ko.md`, and `SKILL.md`) and excludes source files, tests, repo-local wiki/workflow state, raw benchmark output, and local caches.

package/dist/code-index/ownership.js

@@ -52,8 +52,10 @@ function pathOwnerKey(filePath) {
     return parts[0] ?? ".";
 }
 function readJsonObject(relativePath) {
+    if (!(0, workspace_1.containedProjectFileStat)(relativePath))
+        return null;
     try {
-        const parsed = JSON.parse(fs.readFileSync((0, workspace_1.abs)(relativePath), "utf8"));
+        const parsed = JSON.parse((0, workspace_1.read)(relativePath));
         return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
     }
     catch {
@@ -83,19 +85,19 @@ function workspacePatternCandidates(pattern) {
     const suffix = normalized.slice(starIndex + 1).replace(/^\/+/, "");
     const base = prefix || ".";
     const basePath = (0, workspace_1.abs)(base);
-    if (!fs.existsSync(basePath) || !fs.statSync(basePath).isDirectory())
+    if (!(0, workspace_1.containedProjectDirectoryStat)(base))
         return [];
     return fs.readdirSync(basePath, { withFileTypes: true })
         .filter((entry) => entry.isDirectory())
         .map((entry) => (0, workspace_1.normalizePath)(path.join(base, entry.name, suffix)))
-        .filter((candidate) => fs.existsSync((0, workspace_1.abs)(candidate)) && fs.statSync((0, workspace_1.abs)(candidate)).isDirectory());
+        .filter((candidate) => (0, workspace_1.containedProjectDirectoryStat)(candidate));
 }
 function workspacePackages() {
     const packages = new Map();
     for (const pattern of workspacePatternsFromRootPackage()) {
         for (const candidate of workspacePatternCandidates(pattern)) {
             const packageJsonPath = (0, workspace_1.normalizePath)(path.join(candidate, "package.json"));
-            if (!fs.existsSync((0, workspace_1.abs)(packageJsonPath)))
+            if (!(0, workspace_1.containedProjectFileStat)(packageJsonPath))
                 continue;
             const packageJson = readJsonObject(packageJsonPath);
             const packageName = typeof packageJson?.name === "string" ? packageJson.name : candidate;
@@ -119,9 +121,9 @@ function codeownerRules() {
     const files = [".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"];
     const rules = [];
     for (const filePath of files) {
-        if (!fs.existsSync((0, workspace_1.abs)(filePath)))
+        if (!(0, workspace_1.containedProjectFileStat)(filePath))
             continue;
-        const lines = fs.readFileSync((0, workspace_1.abs)(filePath), "utf8").split(/\r?\n/);
+        const lines = (0, workspace_1.read)(filePath).split(/\r?\n/);
         lines.forEach((lineText, index) => {
             const trimmed = lineText.trim();
             if (!trimmed || trimmed.startsWith("#"))

package/dist/code-index-db.js

@@ -4,17 +4,27 @@ exports.codeEvidenceNodeRuntimeRequirement = void 0;
 exports.loadDatabaseSync = loadDatabaseSync;
 exports.openDatabase = openDatabase;
 exports.codeEvidenceNodeRuntimeRequirement = "Node.js 22.13+ or 24+; node:sqlite was added in Node.js 22.5.0 and became available without --experimental-sqlite in Node.js 22.13.0";
+function warningType(option) {
+    if (typeof option === "string")
+        return option;
+    if (typeof option !== "object" || option === null || !("type" in option))
+        return "";
+    const value = option.type;
+    return typeof value === "string" ? value : "";
+}
+function isSqliteExperimentalWarning(warning, options) {
+    const message = warning instanceof Error ? warning.message : typeof warning === "string" ? warning : "";
+    const type = warning instanceof Error ? warning.name : warningType(options[0]);
+    return type === "ExperimentalWarning" && message.includes("SQLite");
+}
 function loadDatabaseSync(fail) {
-    const previousListeners = process.listeners("warning");
-    const suppressExperimentalSqliteWarning = (warning) => {
-        if (warning.name !== "ExperimentalWarning" || !warning.message.includes("SQLite")) {
-            for (const listener of previousListeners)
-                listener.call(process, warning);
-        }
-    };
+    const previousEmitWarning = process.emitWarning;
     try {
-        process.removeAllListeners("warning");
-        process.on("warning", suppressExperimentalSqliteWarning);
+        process.emitWarning = ((warning, ...options) => {
+            if (isSqliteExperimentalWarning(warning, options))
+                return;
+            previousEmitWarning.call(process, warning, ...options);
+        });
         const sqlite = require("node:sqlite");
         return sqlite.DatabaseSync;
     }
@@ -23,9 +33,7 @@ function loadDatabaseSync(fail) {
         return fail(`code evidence index requires Node.js 22.13+ because it uses node:sqlite without experimental flags; current Node is ${process.version}. Runtime policy: ${exports.codeEvidenceNodeRuntimeRequirement}. Error: ${message}`);
     }
     finally {
-        process.removeAllListeners("warning");
-        for (const listener of previousListeners)
-            process.on("warning", listener);
+        process.emitWarning = previousEmitWarning;
     }
 }
 function openDatabase(databasePath, fail) {

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

@@ -92,6 +92,8 @@ function isBlockedSensitiveConfigFile(relativePath) {
     const base = path.basename(relativePath).toLowerCase();
     if (base === ".env.example")
         return false;
+    if (base.startsWith("."))
+        return true;
     return /(^|[._-])(secret|secrets|credential|credentials|token|tokens|private|key|keys)([._-]|$)/i.test(base);
 }
 function isJavaScriptLike(relativePath) {
@@ -130,7 +132,9 @@ function walkCodeFiles(relativePath, files = []) {
     const target = (0, workspace_1.abs)(relativePath);
     if (!fs.existsSync(target))
         return files;
-    const stat = fs.statSync(target);
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink())
+        return files.sort();
     if (stat.isFile()) {
         if (stat.size <= exports.maxIndexedBytes && shouldIndexFile(relativePath))
             files.push(relativePath);
@@ -143,8 +147,8 @@ function walkCodeFiles(relativePath, files = []) {
                 walkCodeFiles(child, files);
         }
         else if (entry.isFile() && shouldIndexFile(child)) {
-            const childStat = fs.statSync((0, workspace_1.abs)(child));
-            if (childStat.size <= exports.maxIndexedBytes)
+            const childStat = (0, workspace_1.containedProjectFileStat)(child);
+            if (childStat && childStat.size <= exports.maxIndexedBytes)
                 files.push(child);
         }
     }
@@ -164,13 +168,7 @@ function gitTrackedAndUnignoredFiles(scopes) {
     }
 }
 function indexableFileStat(file) {
-    try {
-        const stat = fs.statSync((0, workspace_1.abs)(file));
-        return stat.isFile() ? stat : null;
-    }
-    catch {
-        return null;
-    }
+    return (0, workspace_1.containedProjectFileStat)(file);
 }
 function discoverCodeFiles(scopes) {
     const gitFiles = gitTrackedAndUnignoredFiles(scopes);

package/dist/code-index.js

@@ -114,7 +114,7 @@ function normalizedMtimeMs(stat) {
     return Number(stat.mtimeMs.toFixed(3));
 }
 function readCodeFileFingerprint(relativePath) {
-    const stat = fs.statSync((0, workspace_1.abs)(relativePath));
+    const { stat } = (0, workspace_1.requireContainedProjectFile)(relativePath, "code-index file");
     return {
         mtimeMs: normalizedMtimeMs(stat),
         path: relativePath,
@@ -122,7 +122,8 @@ function readCodeFileFingerprint(relativePath) {
     };
 }
 function readCodeFile(relativePath, parserMode = "default") {
-    const text = fs.readFileSync((0, workspace_1.abs)(relativePath), "utf8");
+    const { absolutePath } = (0, workspace_1.requireContainedProjectFile)(relativePath, "code-index file");
+    const text = fs.readFileSync(absolutePath, "utf8");
     const fingerprint = readCodeFileFingerprint(relativePath);
     const language = (0, code_index_file_policy_1.fileLanguage)(relativePath) || "config";
     return {
@@ -383,7 +384,7 @@ function prepareOutputPath() {
     const databasePath = codeEvidenceDatabasePath();
     (0, workspace_1.mkdirp)(path.dirname(databasePath.relativePath));
     (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");
+    (0, workspace_1.write)(`${code_index_file_policy_1.codeEvidenceDirectory}/.gitignore`, "*\n!.gitignore\n");
 }
 function codeIndexModeRuntime() {
     return {

package/dist/hooks.js

@@ -372,15 +372,15 @@ exports.gitPrepareCommitMsgHook = `#!/bin/sh
 MSG_FILE="$1"
 SOURCE="$2"
 
+# Security boundary: prepare-commit-msg runs before the commit is created, so it
+# must not execute scripts from the mutable worktree. Trailer generation remains
+# available as an explicit maintainer action, but this hook is intentionally
+# passive.
 case "$SOURCE" in
-  merge|squash|commit)
+  merge|squash|commit|*)
     exit 0
     ;;
 esac
-
-if command -v node >/dev/null 2>&1 && [ -f ".githooks/wiki-commit-trailers.js" ]; then
-  node .githooks/wiki-commit-trailers.js "$MSG_FILE"
-fi
 `;
 exports.gitWikiCommitTrailersScript = `#!/usr/bin/env node
 

package/dist/init-project-wiki.js

@@ -17,7 +17,7 @@ function codeIndex() {
 function printUsage() {
     console.log(`Usage:
   project-librarian [init|update] [options]
-  project-librarian install [--scope user|project] [--agents codex|claude|cursor|gemini|all]
+  project-librarian install [--scope user|project] [--agents codex|claude|cursor|gemini|all] [--dry-run]
   project-librarian mcp
 
 Options:
@@ -34,6 +34,7 @@ Options:
   --issue-draft                    Print a problem/side-effect GitHub issue body draft.
   --issue-body-file <path>         With --issue-create, use an existing Markdown body file.
   --issue-title <title>            Override the generated issue draft title.
+  --dry-run                        With install, preview copied skill files without writing them.
   --query <terms>                  Search wiki paths, metadata, titles, and bodies (answer-shaped, capped output).
   --wiki-impact <page-or-term>     Show wiki backlinks, decision_ref citations, and router depth for matching pages.
   --wiki-visualize                 Write a static wiki graph visualizer to .project-wiki/wiki-graph.html.

package/dist/install-skill.js

@@ -112,26 +112,119 @@ function installTarget(agent, scope) {
     const base = scope === "user" ? userAgentRoot(agent) : path.join(process.cwd(), projectAgentRoot(agent));
     return path.join(base, "skills", skillName);
 }
+function assertNoTargetSymlink(targetRoot, target, includeLeaf) {
+    const rootResolved = path.resolve(targetRoot);
+    const targetResolved = path.resolve(target);
+    if (targetResolved !== rootResolved && !targetResolved.startsWith(`${rootResolved}${path.sep}`)) {
+        fail(`skill install target escaped target root: ${target}`);
+    }
+    if (fs.existsSync(rootResolved) && fs.lstatSync(rootResolved).isSymbolicLink()) {
+        fail("skill install refuses to follow destination symlink: .");
+    }
+    const relative = path.relative(rootResolved, targetResolved);
+    const parts = relative ? relative.split(path.sep).filter(Boolean) : [];
+    const checkedParts = includeLeaf ? parts : parts.slice(0, -1);
+    let current = rootResolved;
+    for (const part of checkedParts) {
+        current = path.join(current, part);
+        if (!fs.existsSync(current))
+            continue;
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink()) {
+            fail(`skill install refuses to follow destination symlink: ${path.relative(rootResolved, current) || "."}`);
+        }
+        if (current !== targetResolved && !stat.isDirectory()) {
+            fail(`skill install target has a non-directory path component: ${path.relative(rootResolved, current)}`);
+        }
+    }
+}
+function isInsidePath(base, target) {
+    const baseResolved = path.resolve(base);
+    const targetResolved = path.resolve(target);
+    return targetResolved === baseResolved || targetResolved.startsWith(`${baseResolved}${path.sep}`);
+}
+function mkdirFromBaseNoSymlink(base, target) {
+    const baseResolved = path.resolve(base);
+    const targetResolved = path.resolve(target);
+    if (!isInsidePath(baseResolved, targetResolved)) {
+        fail(`skill install target escaped checked base: ${target}`);
+    }
+    let current = baseResolved;
+    const parts = path.relative(baseResolved, targetResolved).split(path.sep).filter(Boolean);
+    for (const part of parts) {
+        current = path.join(current, part);
+        if (fs.existsSync(current)) {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink()) {
+                fail(`skill install refuses to follow destination symlink: ${path.relative(baseResolved, current)}`);
+            }
+            if (!stat.isDirectory()) {
+                fail(`skill install target has a non-directory path component: ${path.relative(baseResolved, current)}`);
+            }
+            continue;
+        }
+        fs.mkdirSync(current);
+    }
+}
+function mkdirpNoTargetSymlink(targetRoot, target) {
+    const rootResolved = path.resolve(targetRoot);
+    const targetResolved = path.resolve(target);
+    const cwdResolved = path.resolve(process.cwd());
+    if (isInsidePath(cwdResolved, rootResolved)) {
+        mkdirFromBaseNoSymlink(cwdResolved, rootResolved);
+    }
+    else {
+        fs.mkdirSync(rootResolved, { recursive: true });
+    }
+    const relative = path.relative(rootResolved, targetResolved);
+    let current = rootResolved;
+    if (!relative) {
+        if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) {
+            fail("skill install refuses to follow destination symlink: .");
+        }
+        if (!fs.existsSync(current))
+            fs.mkdirSync(current);
+        return;
+    }
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        if (fs.existsSync(current)) {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink()) {
+                fail(`skill install refuses to follow destination symlink: ${path.relative(rootResolved, current)}`);
+            }
+            if (!stat.isDirectory()) {
+                fail(`skill install target has a non-directory path component: ${path.relative(rootResolved, current)}`);
+            }
+            continue;
+        }
+        fs.mkdirSync(current);
+    }
+}
 function sameFile(source, target) {
-    if (!fs.existsSync(target) || !fs.statSync(target).isFile())
+    if (!fs.existsSync(target))
+        return false;
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink() || !stat.isFile())
         return false;
     return fs.readFileSync(source).equals(fs.readFileSync(target));
 }
-function copyPath(source, target, dryRun) {
+function copyPath(source, target, targetRoot, dryRun) {
     if (!fs.existsSync(source))
         fail(`missing package file: ${source}`);
     const existed = fs.existsSync(target);
     if (dryRun)
         return "dry-run";
     const sourceStat = fs.statSync(source);
+    assertNoTargetSymlink(targetRoot, target, true);
     if (sourceStat.isDirectory()) {
-        fs.mkdirSync(target, { recursive: true });
+        mkdirpNoTargetSymlink(targetRoot, target);
         for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
-            copyPath(path.join(source, entry.name), path.join(target, entry.name), false);
+            copyPath(path.join(source, entry.name), path.join(target, entry.name), targetRoot, false);
         }
         return existed ? "updated" : "created";
     }
-    fs.mkdirSync(path.dirname(target), { recursive: true });
+    mkdirpNoTargetSymlink(targetRoot, path.dirname(target));
     if (sameFile(source, target))
         return "exists";
     fs.copyFileSync(source, target);
@@ -146,7 +239,7 @@ function copyPackageFiles(targetRoot, dryRun, labelRoot = targetRoot) {
     return packageFiles.map((relativePath) => {
         const source = path.join(root, relativePath);
         const target = path.join(targetRoot, relativePath);
-        return [path.join(labelRoot, relativePath), copyPath(source, target, dryRun)];
+        return [path.join(labelRoot, relativePath), copyPath(source, target, targetRoot, dryRun)];
     });
 }
 function syncProjectSkillInstall(agent) {

package/dist/mcp-server.js

@@ -1,10 +1,10 @@
 "use strict";
 // Hand-rolled MCP stdio server for the code-evidence index.
 //
-// Why hand-rolled: the product holds a zero-runtime-dependency posture (only
-// node:sqlite plus optional tree-sitter grammars). Adopting @modelcontextprotocol/sdk
-// would add a hard runtime dependency, so we implement the small slice of MCP we
-// need directly: JSON-RPC 2.0 over newline-delimited JSON on stdio.
+// Why hand-rolled: the package keeps the MCP surface dependency-light. Code
+// evidence already depends on node:sqlite, the package's TypeScript dependency,
+// and optional tree-sitter grammars; adopting @modelcontextprotocol/sdk would add
+// another hard runtime dependency for a small stdio slice.
 //
 // Transport: MCP stdio transport carries one JSON-RPC message per line on stdin
 // and stdout (newline-delimited JSON, "ndjson"); stderr is free for logging. We

package/dist/migration.js

@@ -57,6 +57,7 @@ exports.migrationCoverageStatusMap = migrationCoverageStatusMap;
 exports.semanticStatusForInboxStatus = semanticStatusForInboxStatus;
 exports.runReviewMigrationMode = runReviewMigrationMode;
 const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const taxonomy_1 = require("./taxonomy");
 const workspace_1 = require("./workspace");
 const templates_1 = require("./templates");
@@ -317,9 +318,31 @@ function activeMigrationLegacyRoots() {
     const verifiedRoot = migrationVerificationLegacyRoot();
     return verifiedRoot ? [verifiedRoot] : legacyWikiRoots();
 }
+function migrationDirectoryPath(relativePath) {
+    const resolved = path.resolve(workspace_1.root, relativePath);
+    const rootResolved = path.resolve(workspace_1.root);
+    if (resolved !== rootResolved && !resolved.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new Error(`migration directory must stay inside the project root: ${relativePath}`);
+    }
+    const stat = fs.lstatSync(resolved);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`migration refuses to follow symlinked wiki directory: ${relativePath}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`migration path is not a directory: ${relativePath}`);
+    }
+    const realPath = fs.realpathSync(resolved);
+    if (realPath !== rootResolved && !realPath.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new Error(`migration directory must resolve inside the project root: ${relativePath}`);
+    }
+    return resolved;
+}
 function expectedMigrationUnits() {
     return activeMigrationLegacyRoots()
-        .flatMap((legacyRoot) => (0, wiki_files_1.walkMarkdownFiles)((0, workspace_1.abs)(legacyRoot), [], (0, workspace_1.abs)(legacyRoot)))
+        .flatMap((legacyRoot) => {
+        const legacyPath = migrationDirectoryPath(legacyRoot);
+        return (0, wiki_files_1.walkMarkdownFiles)(legacyPath, [], legacyPath);
+    })
         .flatMap((file) => extractMigrationUnits(file.basePath, (0, workspace_1.read)(file.path)));
 }
 function loadMigrationUnitContext() {
@@ -962,6 +985,7 @@ function nextLegacyPath() {
 }
 function prepareMigrationMode() {
     if ((0, workspace_1.exists)("wiki")) {
+        migrationDirectoryPath("wiki");
         const legacyPath = nextLegacyPath();
         fs.renameSync((0, workspace_1.abs)("wiki"), (0, workspace_1.abs)(legacyPath));
         return { legacyPath, note: `moved wiki to ${legacyPath}` };
@@ -981,7 +1005,8 @@ function migrationTargetForKind(kind) {
 }
 function runMigrationMode(migrationState) {
     const legacyPath = migrationState.legacyPath;
-    const markdownFiles = legacyPath && (0, workspace_1.exists)(legacyPath) ? (0, wiki_files_1.walkMarkdownFiles)((0, workspace_1.abs)(legacyPath), [], (0, workspace_1.abs)(legacyPath)) : [];
+    const legacyRootPath = legacyPath && (0, workspace_1.exists)(legacyPath) ? migrationDirectoryPath(legacyPath) : "";
+    const markdownFiles = legacyRootPath ? (0, wiki_files_1.walkMarkdownFiles)(legacyRootPath, [], legacyRootPath) : [];
     const fileRecords = markdownFiles.map((file) => {
         const text = (0, workspace_1.read)(file.path);
         return { file, text, formOnlyReason: formOnlyMigrationDocumentReason(file.basePath, text) };

package/dist/templates.js

@@ -87,7 +87,7 @@ During conversation:
 - Do not store non-project LLM memory, assistant preferences, collaboration reminders, or workflow instructions in project wiki canonical or decision docs.
 - Follow \`wiki/AGENTS.md\` for detailed rules when editing files under \`wiki/\`.
 - Treat broad maintenance/improvement automation requests that do not name a concrete command (for example "improve this project", "start improvement automation", or "개선 자동화 시작해") as analyze-first project work, not as a plain bootstrap/update. Inspect repo, wiki, CI, test, release, dependency, and code-structure evidence; produce a ranked backlog with evidence and verification paths; persist the plan in \`wiki/plans/\` when project-planning content changes; then execute safe high-priority items with tests.
-- Let \`.githooks/prepare-commit-msg\` append wiki trailers automatically for staged wiki, hook, AGENTS, or project-librarian files.
+- Do not execute worktree-controlled commit hooks for wiki trailers; add trailers explicitly when needed.
 - ${exports.wikiTrustContract}
 - ${exports.codeEvidenceTrustContract}
 - ${exports.guidanceClaimEvidenceContract}
@@ -177,9 +177,9 @@ Update rules:
 Commit rules:
 
 - Follow the repository's commit-message policy when one exists.
-- Let \`.githooks/prepare-commit-msg\` append wiki trailers automatically when git hooks are enabled.
+- Do not execute worktree-controlled commit hooks for wiki trailers; add trailers explicitly when needed.
 - If bootstrap was run with \`--no-git-config\`, hook files are installed but \`core.hooksPath\` is not changed.
-- Do not hand-write wiki trailers unless the hook is unavailable or a trailer needs correction.
+- Hand-write wiki trailers when project policy requires them; keep them accurate and evidence-backed.
 <!-- PROJECT-WIKI-INTERNAL:END -->`;
 const metadata = (scope, budget, decisionRef, trigger, status = "active") => `---
 status: ${status}
@@ -415,6 +415,7 @@ node dist/init-project-wiki.js --query "search terms"
 ## Git Hook Setup
 
 - The script installs \`.githooks/prepare-commit-msg\` and \`.githooks/wiki-commit-trailers.js\`.
+- \`.githooks/prepare-commit-msg\` is intentionally passive and must not execute worktree-controlled scripts.
 - By default, git repositories with an unset \`core.hooksPath\` are configured with \`git config core.hooksPath .githooks\`.
 - Existing \`core.hooksPath\` values are preserved so an existing hook chain is not replaced.
 - Run bootstrap with \`--no-git-config\` to install hook files without changing git config.

package/dist/workspace.js

@@ -51,31 +51,105 @@ exports.normalizePath = normalizePath;
 exports.commandOk = commandOk;
 exports.isGitRepository = isGitRepository;
 exports.makeExecutable = makeExecutable;
+exports.containedProjectFileStat = containedProjectFileStat;
+exports.containedProjectDirectoryStat = containedProjectDirectoryStat;
+exports.requireContainedProjectFile = requireContainedProjectFile;
 exports.walkFilesUnder = walkFilesUnder;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const childProcess = __importStar(require("node:child_process"));
 exports.root = process.cwd();
 exports.today = new Date().toISOString().slice(0, 10);
+const projectRoot = path.resolve(exports.root);
 function abs(relativePath) {
     return path.join(exports.root, relativePath);
 }
+function isInsideProject(absolutePath) {
+    const resolved = path.resolve(absolutePath);
+    return resolved === projectRoot || resolved.startsWith(`${projectRoot}${path.sep}`);
+}
+function resolveProjectPath(relativePath, label = "path") {
+    const resolved = path.isAbsolute(relativePath) ? path.resolve(relativePath) : path.resolve(exports.root, relativePath);
+    if (!isInsideProject(resolved)) {
+        throw new Error(`${label} must stay inside the project root: ${relativePath}`);
+    }
+    return resolved;
+}
+function assertNoSymlinkInProjectPath(relativePath, includeLeaf, label = "path") {
+    const target = resolveProjectPath(relativePath, label);
+    const relative = path.relative(projectRoot, target);
+    if (!relative)
+        return target;
+    const parts = relative.split(path.sep).filter(Boolean);
+    const checkedParts = includeLeaf ? parts : parts.slice(0, -1);
+    let current = projectRoot;
+    for (const part of checkedParts) {
+        current = path.join(current, part);
+        if (!fs.existsSync(current))
+            continue;
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`${label} refuses to follow symlink: ${normalizePath(path.relative(projectRoot, current))}`);
+        }
+        if (current !== target && !stat.isDirectory()) {
+            throw new Error(`${label} has a non-directory path component: ${normalizePath(path.relative(projectRoot, current))}`);
+        }
+    }
+    return target;
+}
+function mkdirpAbsolute(target, label = "path") {
+    if (!isInsideProject(target)) {
+        throw new Error(`${label} must stay inside the project root: ${target}`);
+    }
+    const relative = path.relative(projectRoot, target);
+    if (!relative)
+        return;
+    let current = projectRoot;
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        if (fs.existsSync(current)) {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink()) {
+                throw new Error(`${label} refuses to follow symlink: ${normalizePath(path.relative(projectRoot, current))}`);
+            }
+            if (!stat.isDirectory()) {
+                throw new Error(`${label} has a non-directory path component: ${normalizePath(path.relative(projectRoot, current))}`);
+            }
+            continue;
+        }
+        fs.mkdirSync(current);
+    }
+}
+function writeFileNoFollow(filePath, content) {
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | noFollow, 0o666);
+    try {
+        fs.writeFileSync(fd, content);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 function exists(relativePath) {
     return fs.existsSync(abs(relativePath));
 }
 function read(relativePath) {
-    return fs.readFileSync(abs(relativePath), "utf8");
+    const filePath = assertNoSymlinkInProjectPath(relativePath, true, "managed read");
+    return fs.readFileSync(filePath, "utf8");
 }
 function write(relativePath, content) {
-    const filePath = abs(relativePath);
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, content);
+    const filePath = assertNoSymlinkInProjectPath(relativePath, true, "managed write");
+    mkdirpAbsolute(path.dirname(filePath), "managed write");
+    writeFileNoFollow(filePath, content);
 }
 function mkdirp(relativePath) {
-    fs.mkdirSync(abs(relativePath), { recursive: true });
+    const dirPath = assertNoSymlinkInProjectPath(relativePath, true, "managed directory");
+    mkdirpAbsolute(dirPath, "managed directory");
 }
 function writeManaged(relativePath, content) {
-    const previous = exists(relativePath) ? read(relativePath) : "";
+    const previous = exists(relativePath)
+        ? (assertNoSymlinkInProjectPath(relativePath, true, "managed read"), read(relativePath))
+        : "";
     if (previous === content)
         return "exists";
     write(relativePath, content);
@@ -86,6 +160,7 @@ function writeStarter(relativePath, content) {
         write(relativePath, content);
         return "created";
     }
+    assertNoSymlinkInProjectPath(relativePath, true, "managed read");
     const current = read(relativePath);
     if (current === content)
         return "exists";
@@ -111,6 +186,7 @@ function upsertMarkedSection(relativePath, startMarker, endMarker, section) {
         write(relativePath, `${section.trim()}\n`);
         return "created";
     }
+    assertNoSymlinkInProjectPath(relativePath, true, "managed read");
     const current = read(relativePath);
     const start = current.indexOf(startMarker);
     const end = current.indexOf(endMarker);
@@ -133,15 +209,17 @@ function upsertMarkedSection(relativePath, startMarker, endMarker, section) {
 function deleteIfGenerated(relativePath, sentinels) {
     if (!exists(relativePath))
         return "absent";
+    const filePath = assertNoSymlinkInProjectPath(relativePath, true, "managed delete");
     const current = read(relativePath);
     if (!sentinels.some((sentinel) => current.includes(sentinel)))
         return "manual-review";
-    fs.unlinkSync(abs(relativePath));
+    fs.unlinkSync(filePath);
     return "removed";
 }
 function parseJson(relativePath, fallback) {
     if (!exists(relativePath))
         return fallback;
+    assertNoSymlinkInProjectPath(relativePath, true, "managed read");
     try {
         return JSON.parse(read(relativePath));
     }
@@ -191,11 +269,60 @@ function isGitRepository() {
 function makeExecutable(relativePath) {
     if (!exists(relativePath))
         return;
-    const currentMode = fs.statSync(abs(relativePath)).mode;
-    fs.chmodSync(abs(relativePath), currentMode | 0o755);
+    const filePath = assertNoSymlinkInProjectPath(relativePath, true, "managed chmod");
+    const currentMode = fs.statSync(filePath).mode;
+    fs.chmodSync(filePath, currentMode | 0o755);
+}
+function containedProjectFileStat(relativePath) {
+    const filePath = resolveProjectPath(relativePath, "project file");
+    let stat;
+    try {
+        stat = fs.lstatSync(filePath);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        return null;
+    let realPath = "";
+    try {
+        realPath = fs.realpathSync(filePath);
+    }
+    catch {
+        return null;
+    }
+    return isInsideProject(realPath) ? stat : null;
+}
+function containedProjectDirectoryStat(relativePath) {
+    const dirPath = resolveProjectPath(relativePath, "project directory");
+    let stat;
+    try {
+        stat = fs.lstatSync(dirPath);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        return null;
+    let realPath = "";
+    try {
+        realPath = fs.realpathSync(dirPath);
+    }
+    catch {
+        return null;
+    }
+    return isInsideProject(realPath) ? stat : null;
+}
+function requireContainedProjectFile(relativePath, label = "project file") {
+    const filePath = resolveProjectPath(relativePath, label);
+    const stat = containedProjectFileStat(relativePath);
+    if (!stat) {
+        throw new Error(`${label} must be a regular file inside the project root and must not be a symlink: ${relativePath}`);
+    }
+    return { absolutePath: filePath, stat };
 }
 function walkFilesUnder(relativePath, predicate, acc = []) {
-    const dirPath = abs(relativePath);
+    const dirPath = assertNoSymlinkInProjectPath(relativePath, true, "managed walk");
     if (!fs.existsSync(dirPath))
         return acc;
     for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-librarian",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",
@@ -58,6 +58,7 @@
     "benchmark:release": "npm run benchmark:llm -- --sanitized-pack --full-matrix --runs 3 --warmup-runs 1 --min-runs-for-claim 3 --require-clean --require-claimable --model gpt-5.5 --out benchmarks/reports/llm/current.json --markdown benchmarks/reports/llm/current.md",
     "build": "tsc && chmod +x dist/init-project-wiki.js",
     "check:dist": "node benchmarks/tools/release-readiness.js --only-dist-parity",
+    "audit:supply-chain": "npm audit --omit=dev",
     "perf:code-efficiency": "node benchmarks/tools/code-performance-efficiency.js --full",
     "release:check": "node benchmarks/tools/release-readiness.js",
     "typecheck": "tsc --noEmit",
@@ -86,6 +87,6 @@
     "@sengac/tree-sitter-typescript": "^0.25.15"
   },
   "devDependencies": {
-    "@types/node": "^25.9.2"
+    "@types/node": "^22.20.0"
   }
 }