project-librarian 0.5.2 → 0.5.3

package/README.ko.md

@@ -293,7 +293,7 @@ MCP 서버 등록 (`mcpServers`에 기존 항목 보존하며 병합):
 
 `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://wiki/startup`, `project-librarian://wiki/index`, `project-librarian://code/status` — 와 위키 분류 갱신, 코드 영향 추적, 검색 품질 검토용 프롬프트 템플릿도 제공합니다. 리소스 읽기는 임의 파일 경로가 아니라 고정 URI 레지스트리에서만 처리합니다.
+서버는 고정 리소스 — `project-librarian://wiki/startup`, `project-librarian://wiki/index`, `project-librarian://code/status` — 와 위키 분류 갱신, 코드 영향 추적, 유지보수 개선 검토, 검색 품질 검토용 프롬프트 템플릿도 제공합니다. 리소스 읽기는 임의 파일 경로가 아니라 고정 URI 레지스트리에서만 처리합니다.
 
 부트스트랩은 Claude Code(`.mcp.json`), Cursor(`.cursor/mcp.json`), Gemini CLI(`.gemini/settings.json`의 `mcpServers`)에 서버를 등록하며, 기존 서버와 키를 보존하고 다시 실행하면 `exists`를 보고합니다. 저장소에 로컬 실행 경로가 있으면 `node <runner> mcp`로, 없으면 설치된 `project-librarian mcp` 바이너리로 등록합니다.
 
@@ -407,6 +407,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 npm install
 npm run typecheck
 npm run build
+npm run check:dist
 npm test
 npm run test:coverage
 npm run benchmark:llm:raw-audit
@@ -416,11 +417,11 @@ npm run release:check
 npm pack --dry-run
 ```
 
-`src/` 아래 TypeScript를 수정할 때는 커밋 전에 빌드해 `dist/`를 최신 상태로 유지하세요.
+`src/` 아래 TypeScript를 수정할 때는 커밋 전에 빌드해 `dist/`를 최신 상태로 유지하세요. `npm run check:dist`는 체크인된 생성 파일이 최신 빌드 출력과 일치하는지 확인합니다.
 
 `npm run test:coverage`는 Node 내장 test coverage에 보수적인 line, branch, function threshold를 적용하므로 coverage를 단순 보고서가 아니라 회귀 게이트로 사용합니다.
 
-`npm run release:check`는 로컬 전용 관리자 게이트입니다. 테스트, Node 내장 coverage, 벤치마크 파서 smoke, real-corpus 오프라인 데모, 벤치마크 release preview, 벤치마크 claim ledger 분류, raw 보관 상태 감사, package dry-run 검사, dist 실행 가능 여부, README 벤치마크 claim 경계 문구를 확인합니다. publish하지 않고 raw 벤치마크 산출물을 삭제하지 않으며 measured Codex 벤치마크도 실행하지 않습니다.
+`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

@@ -293,7 +293,7 @@ Disposable code evidence cache:
 
 `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.
 
-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, and retrieval quality reviews. Resource reads come from a fixed URI registry rather than arbitrary filesystem paths.
+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.
 
 Bootstrap registers the server for Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`), and Gemini CLI (`mcpServers` in `.gemini/settings.json`), preserving any existing servers and keys and reporting `exists` on a re-run. When the repository contains a local runner the registration uses `node <runner> mcp`; otherwise it uses the installed `project-librarian mcp` binary.
 
@@ -407,6 +407,7 @@ The source is TypeScript. The committed `dist/` directory is the compiled JavaSc
 npm install
 npm run typecheck
 npm run build
+npm run check:dist
 npm test
 npm run test:coverage
 npm run benchmark:llm:raw-audit
@@ -416,11 +417,11 @@ npm run release:check
 npm pack --dry-run
 ```
 
-When editing TypeScript under `src/`, rebuild before committing so `dist/` stays current.
+When editing TypeScript under `src/`, rebuild before committing so `dist/` stays current. `npm run check:dist` verifies that the checked-in generated files still match the latest build output.
 
 `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.
 
-`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 checks, and README benchmark-claim boundary checks. It never publishes, never deletes raw benchmark artifacts, and never launches a measured Codex benchmark.
+`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/SKILL.md

@@ -22,6 +22,7 @@ Supported actions:
 - Check for pending, stale, proposed, or undecided wiki pages.
 - Draft a GitHub issue body for problems or side effects found while using the skill.
 - Initialize a project glossary.
+- Turn broad maintenance, automation, efficiency, or "improve this project" requests into an analyze-first backlog and execution plan before editing.
 - Analyze existing code and canonicalize code-backed project behavior, features, policies, constraints, terminology, domain rules, and open questions into the wiki.
 - Build and query an optional SQLite code evidence index for large repositories.
 - Migrate an existing wiki/docs structure.
@@ -48,6 +49,16 @@ Use `npx` or `npm exec` only when no local runner exists and registry access is
 
 If the resolved runner fails, report the real error and stop or fix the cause. Do not manually recreate bootstrap or migration output as a fallback.
 
+Broad improvement automation requests are discovery-and-execution work, not routine bootstrap updates. When the user says something like "improve this project", "start improvement automation", "개선 자동화 시작해", or asks for maintainability/automation/efficiency improvements without naming a concrete lifecycle flag:
+
+- Do not map the request directly to `$PROJECT_LIBRARIAN update` or a single diagnostic command.
+- Inspect the repo's wiki contract, code structure, package scripts, CI, tests, release gates, generated surfaces, dependency posture, and obvious maintenance bottlenecks.
+- Use code-evidence tools or reports when the repo is large or the question is structural; use direct targeted reads for small repos and simple lookups.
+- Produce a ranked backlog with file/command evidence, confidence, expected verification, and risk.
+- Persist durable planning output under `wiki/plans/` when the request changes project-planning state, then refresh the index and run lint when practical.
+- If the user asked to start or continue work, implement safe high-priority items in a branch, update generated outputs, and verify with targeted tests plus the smallest broad gate that proves the claim.
+- Keep unresolved, high-risk, or dependency-changing candidates in the backlog instead of silently skipping them.
+
 2. For project bootstrap requests, choose the matching command and run it from the project root. The examples below use `$PROJECT_LIBRARIAN` to mean the resolved runner from step 1:
 
 ```bash

package/dist/hooks.js

@@ -249,18 +249,35 @@ const files = [
   ["wiki/index.md", 4500],
 ];
 
-const sections = files
-  .map(([relativePath, maxChars]) => {
-    const text = readIfExists(relativePath, maxChars);
+const fileReads = files.map(([relativePath, maxChars]) => {
+  const text = readIfExists(relativePath, maxChars);
+  return { relativePath, text };
+});
+
+const sections = fileReads
+  .map(({ relativePath, text }) => {
     if (!text) return "";
     return \`## \${relativePath}\\n\\n\${text}\`;
   })
   .filter(Boolean);
 
+const missingFiles = fileReads
+  .filter(({ text }) => !text)
+  .map(({ relativePath }) => relativePath);
+
+const inclusionNotice = missingFiles.length === 0
+  ? [
+    "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.",
+  ]
+  : [
+    \`Project wiki startup files were not fully included; missing or empty: \${missingFiles.join(", ")}.\`,
+    "Run Project Librarian to bootstrap or restore the missing wiki files before relying on wiki-first routing.",
+  ];
+
 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.",
+  ...inclusionNotice,
   "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.",

package/dist/mcp-server.js

@@ -255,6 +255,29 @@ const PROMPTS = [
             ].join("\n");
         },
     },
+    {
+        name: "maintenance_improvement_review",
+        title: "Maintenance Improvement Review",
+        description: "Turn broad maintainability, automation, or efficiency requests into an analyze-first backlog and execution plan.",
+        arguments: [
+            { name: "request", description: "The user's broad improvement or automation request.", required: true },
+            { name: "scope", description: "Optional repository area, package, workflow, or concern to prioritize." },
+        ],
+        get: (args) => {
+            const request = requiredPromptArg(args, "request");
+            const scope = optionalPromptArg(args, "scope", "whole repository unless the user named a narrower scope");
+            return [
+                "Handle this as analyze-first maintenance improvement work, not as a routine bootstrap/update command.",
+                "1. Read project-librarian://wiki/startup, project-librarian://wiki/index, and project-librarian://code/status before deciding the work path.",
+                "2. Inspect repo, wiki, package scripts, CI, tests, release gates, generated surfaces, dependencies, and code-structure evidence relevant to the request.",
+                "3. Produce a ranked backlog with concrete file/command evidence, confidence, risk, and a verification path for each candidate.",
+                "4. Persist a durable plan under wiki/plans/ when project-planning state changes, then refresh the wiki index and run lint when practical.",
+                "5. If execution is requested, implement safe high-priority items first, update generated outputs, and verify with targeted tests plus the smallest broad gate that proves the claim.",
+                `Request: ${request}`,
+                `Scope: ${scope}`,
+            ].join("\n");
+        },
+    },
     {
         name: "retrieval_quality_review",
         title: "Retrieval Quality Review",

package/dist/templates.js

@@ -86,6 +86,7 @@ During conversation:
 - Classify new project-planning content with \`wiki/meta/document-taxonomy.md\` before writing or consolidating it.
 - 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.
 - ${exports.wikiTrustContract}
 - ${exports.codeEvidenceTrustContract}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-librarian",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",
@@ -56,6 +56,7 @@
     "benchmark:release:diagnose": "npm run benchmark:llm -- --sanitized-pack --runs 1 --warmup-runs 0 --model gpt-5.5 --out benchmarks/reports/llm/diagnostic-current.json --markdown benchmarks/reports/llm/diagnostic-current.md",
     "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",
     "perf:code-efficiency": "node benchmarks/tools/code-performance-efficiency.js --full",
     "release:check": "node benchmarks/tools/release-readiness.js",
     "typecheck": "tsc --noEmit",