project-librarian 0.5.8 → 0.6.0

package/docs/ko/benchmarks.md

@@ -17,17 +17,33 @@ npm run benchmark:release -- --allow-codex-run
 
 ## 위키 트랙
 
-비용 가중 토큰, Project Librarian 대 대조군:
-
-| 규모 | decision_lookup | aggregation | multi_session (2번째 세션) |
-| --- | --- | --- | --- |
-| 소형 | 14.4% 적음 | 81.0% 많음 | 22.0% 적음 |
-| 중형 | 52.0% 적음 | 19.0% 적음 | 54.1% 적음 |
-| 대형 | 71.1% 적음 | 29.0% 적음 | 71.8% 적음 |
-
-최신 합성 위키 트랙 릴리스 후보는 2026-06-19에 `gpt-5.5`로 측정했으며, 42개 시나리오를 각 3회 측정하고 1회 예열했습니다. 전체 주장 게이트는 **통과**했습니다. 42/42개 시나리오가 정확성 검사를 통과했고, 42개 시나리오가 모두 claimable이었으며, 모든 corpus gate가 3-run 최소 조건을 충족했습니다.
-
-이 릴리스 주장은 합성 위키 라우팅 트랙과 표기된 작업 유형에 한정됩니다. 코드 그래프 동작, 실제 저장소, 모든 에이전트 표면, 모든 질문 형태에 대한 주장이 아닙니다. 숨기지 않는 한계도 남습니다. 소형 `aggregation`은 위키를 켰을 때 81.0% 더 비싸고, 전체 보고서의 소형 `release_policy`도 9.4% 더 비싸며, `aggregation`은 토큰 비용이 줄어드는 규모에서도 실행 시간은 매번 더 느립니다.
+최신 clean 합성 위키 트랙 릴리스 근거는 2026-06-29에 `gpt-5.5`, `perf/small-repo-code-evidence-safeguards` 브랜치의 `ae79390` 커밋에서 측정했습니다. 42개 시나리오, 21개 with/without 쌍을 각 3회 측정하고 1회 예열했으며, 전체 주장 게이트는 **통과**했고 주장 ledger는 이 보고서를 release-claimable로 분류했습니다. repair 실행은 보존된 raw JSONL에서 claimable 측정 실행 125개를 재사용하고 남은 실패 슬롯 1개를 다시 측정했습니다.
+
+비용 가중 토큰, Project Librarian 대 대조군, 전체 규모 합산:
+
+| 작업 유형 | 변화 |
+| --- | ---: |
+| onboarding | 65.95% 적음 |
+| decision_lookup | 48.46% 적음 |
+| code_impact | 55.61% 적음 |
+| release_policy | 58.22% 적음 |
+| change_location | 29.59% 적음 |
+| multi_session | 52.58% 적음 |
+| aggregation | 42.53% 적음 |
+
+규모별 비용 가중 토큰 변화:
+
+| 작업 유형 | 소형 | 중형 | 대형 |
+| --- | ---: | ---: | ---: |
+| onboarding | 60.88% 적음 | 65.53% 적음 | 69.17% 적음 |
+| decision_lookup | 19.18% 적음 | 51.29% 적음 | 60.12% 적음 |
+| code_impact | 26.61% 적음 | 54.81% 적음 | 68.43% 적음 |
+| release_policy | 30.23% 적음 | 62.16% 적음 | 67.26% 적음 |
+| change_location | 7.79% 적음 | 2.86% 많음 | 57.27% 적음 |
+| multi_session | 54.29% 많음 | 35.32% 적음 | 82.77% 적음 |
+| aggregation | 7.66% 적음 | 51.32% 적음 | 49.17% 적음 |
+
+이 릴리스 주장은 합성 위키 라우팅 트랙과 표기된 작업 유형에 한정됩니다. 코드 그래프 동작, 실제 저장소, 모든 에이전트 표면, 모든 질문 형태에 대한 주장이 아닙니다. 숨기지 않는 한계도 남습니다. 비용 가중 토큰 기준으로 소형 `multi_session`과 중형 `change_location`은 위키를 켰을 때 더 비쌉니다. 또한 `code_impact`, `change_location`, `aggregation`은 작업 유형 집계에서 토큰과 출력 바이트가 개선됐더라도 이번 보고서의 실행 시간이나 명령 수에는 일부 역전이 남아 있습니다.
 
 ## 코드 그래프 트랙
 
@@ -52,7 +68,11 @@ SHA로 고정한 오픈소스 저장소 2곳에서, 손으로 작성한 정답
 
 질문 유형:
 
+- **onboarding** - 프로젝트가 무엇인지, 현재 리스크, 다음에 읽을 문서를 요약합니다.
 - **decision_lookup** - 위키에서 가장 최근 프로젝트 결정과 그 날짜를 찾습니다.
+- **code_impact** - 벤치마크 보고서 스키마 변경 시 영향받을 파일이나 영역을 찾습니다.
+- **release_policy** - publish 또는 benchmark claim 전에 필요한 체크를 찾습니다.
+- **change_location** - Codex LLM benchmark runner 구현 시 어디를 수정해야 하는지 찾습니다.
 - **aggregation** - 여러 페이지에 흩어진 사실을 종합해야 답할 수 있는 질문입니다.
 - **multi_session** - 같은 프로젝트의 두 번째 세션으로, 지속되는 위키가 다음 세션에도 도움이 되는지 측정합니다.
 - **impact_trace** - 바뀌는 모듈의 직접/간접 importer 전체를 추적합니다.

package/docs/ko/cli-reference.md

@@ -19,7 +19,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `update --agents <list>` | 기존 설정과 기존 프로젝트 범위 스킬 복사본을 갱신합니다. 표면은 `codex`, `claude`, `cursor`, `gemini`, `all` 중 하나입니다. |
 | `--migrate`, `--adopt-existing` | 기존 위키를 `wiki_legacy*`로 보존하고 migration inbox, unit-map, split-plan, coverage 검토 파일을 만듭니다. |
 | `--lint` | 파일을 수정하지 않고 생성된 설정을 검증합니다. |
-| `--link-check` | 깨진 위키 링크, 중복 route, orphan page, 시작 라우터 depth 예산 안에서 닿지 않는 페이지를 보고합니다. |
+| `--link-check` | 깨진 위키 링크, 중복 route, orphan page, router reachability, warning-only topology 신호를 보고합니다. |
 | `--quality-check` | 오래되었거나 충돌하거나 품질이 낮은 위키 문서 신호를 보고합니다. |
 | `--doctor` | lint, link-check, quality-check를 함께 실행합니다. |
 | `--doctor --fix` | 진단 전에 생성된 index routing을 안전하게 갱신합니다. `--fix`는 `--doctor`의 modifier입니다. |
@@ -28,8 +28,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `--migration-doctor` | migration-lint와 migration-quality-check를 함께 실행합니다. |
 | `--query <terms>` | 위키 경로, 메타데이터, 제목, 본문을 검색하고 크기 제한이 있는 answer-first 출력을 제공합니다. |
 | `--wiki-impact <page-or-term>` | 일치하는 페이지의 backlinks, `decision_ref` 인용, outgoing link, router depth를 보여줍니다. |
-| `--wiki-visualize` | `.project-wiki/wiki-graph.html`에 독립 실행형 정적 위키 그래프를 작성합니다. |
-| `--wiki-visualize-out <path>` | `--wiki-visualize`와 함께 사용해 `.project-wiki/` 아래 사용자 지정 저장소 상대 경로에 작성합니다. |
+| `--wiki-neighborhood <page-or-term>` | link, `decision_ref`, metadata, page class, router depth를 사용해 가까운 위키 페이지의 제한된 읽기 순서를 보여줍니다. |
 | `--refresh-index` | 자동 발견된 위키 routing을 갱신합니다. |
 | `--capture-inbox --title <title> --content <content> --category <category>` | 후보 메모를 위키 inbox에 추가합니다. category 기본값은 `project-candidate`입니다. |
 | `--handoff-save --goal <goal> --state <state> --next <action>` | `.project-wiki/session/` 아래에 생성형 로컬 세션 핸드오프를 저장합니다. 필요하면 `--next`, `--decision`, `--blocked`, `--open-question`, `--verification`, `--last-success-command`, `--last-failure-command`를 반복합니다. |
@@ -59,3 +58,14 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `--code-context-pack <term>` | 구조 파일, 심볼, route, import, edge, 소유권 근거를 담은 예산 제한 first-pass context pack을 출력합니다. |
 | `--code-search-symbol <term>` | 인덱싱된 심볼을 검색합니다. |
 | `--code-query <sql>` | 근거 인덱스에서 보수적 읽기 전용 SQL을 실행합니다. |
+
+### Topology Warnings
+
+`--link-check`의 topology finding은 warning-only입니다. 그래서 bootstrap, update, release 흐름을 막지 않으면서 정리 방향을 알려줍니다.
+
+| 코드 | 의미 |
+| --- | --- |
+| `hub-overload` | 사람이 관리하는 router 또는 meta 페이지가 너무 많은 위키 페이지를 링크하므로 분리하거나 범위를 좁혀야 합니다. |
+| `weak-authority-route` | decision 또는 evidence 권위 신호가 있는 active canonical page가 generated auto-index routing으로만 도달 가능합니다. |
+| `missing-evidence-link` | active canonical page가 source-backed claim을 하지만 source link 또는 `decision_ref`가 없습니다. |
+| `stale-fanout` | 많이 링크된 active page가 topology-sensitive edit에 비해 너무 넓은 review trigger를 갖고 있습니다. |

package/docs/ko/usage.md

@@ -69,7 +69,7 @@ npx project-librarian@latest install --scope project --agents all
 | 진단 전 라우팅 갱신 | "Project Librarian 라우팅을 갱신한 뒤 진단을 실행해줘." | `--doctor --fix` |
 | 위키 내용 검색 | "Project Librarian 위키에서 authentication decisions를 찾아줘." | `--query "authentication decisions"` |
 | 페이지 영향도 확인 | "decisions/release-policy의 Project Librarian 위키 영향도를 보여줘." | `--wiki-impact "decisions/release-policy"` |
-| 위키 그래프 생성 | "Project Librarian 위키 그래프 시각화를 생성해줘." | `--wiki-visualize` |
+| 가까운 위키 맥락 찾기 | "canonical/project-brief의 Project Librarian wiki neighborhood를 보여줘." | `--wiki-neighborhood "canonical/project-brief"` |
 | 후보 메모 저장 | "이 내용을 Project Librarian 후보 메모로 저장해줘: <내용>." | `--capture-inbox --title "Candidate" --content "Details"` |
 | 세션 핸드오프 저장 | "현재 작업을 Project Librarian 세션 핸드오프로 저장해줘." | `--handoff-save --goal "..." --state "..." --next "..."` |
 | 핸드오프 보기 | "마지막 Project Librarian 세션 핸드오프를 보여줘." | `--handoff-show` |
@@ -160,9 +160,7 @@ MCP 서버 등록은 Claude Code(`.mcp.json`), Cursor(`.cursor/mcp.json`), Gemin
 6. `--refresh-index`는 새로 발견한 위키 페이지를 라우팅합니다. route가 많으면 `wiki/indexes/auto-*.md` 범위별 라우터로 나눕니다.
 7. `--code-index`는 `.project-wiki/` 아래 폐기 가능한 SQLite 근거 캐시를 만듭니다.
 8. `--code-report`, `--code-impact`, `--code-context-pack`, `--code-search-symbol`, `--code-query`는 계획 업데이트에 쓸 코드 기반 근거를 노출합니다.
-9. 읽기 전용 위키 소비자는 경로와 frontmatter에서 사용자-facing page type을 파생하는 concept read model을 공유합니다.
-10. 위키 생산자는 canonical markdown/YAML 스키마를 계속 쓰고, 진단/MCP/시각화 같은 읽기 전용 소비자는 파생 projection을 사용합니다.
-11. `--wiki-visualize`는 데이터베이스나 서버 없이 `.project-wiki/` 아래 정적 그래프 산출물을 작성합니다.
-12. 진단은 깨진 링크, 중복 route, orphan page, stale page, TL;DR 누락, 근거 공백, 마이그레이션 정책 위반을 보고합니다.
+9. 위키 생산자는 canonical markdown/YAML 스키마를 계속 쓰고, 진단/MCP 같은 읽기 전용 소비자는 원본 문서를 변경하지 않고 검사합니다.
+10. 진단은 깨진 링크, 중복 route, orphan page, topology warning, stale page, TL;DR 누락, 근거 공백, 마이그레이션 정책 위반을 보고합니다.
 
 마이그레이션은 검토 우선입니다. `--migrate`는 기존 `wiki/`를 `wiki_legacy*`로 보존하고, 양식 전용 파일은 건너뛰며, 여러 성격이 섞인 기존 페이지를 의미 단위로 나눕니다. 이후 각 단위를 분류해 `wiki/migration/` 아래 검토 파일을 작성합니다.

package/docs/usage.md

@@ -67,7 +67,7 @@ Wiki setup and maintenance:
 | Refresh generated routing before diagnostics | "Refresh Project Librarian routing and then run diagnostics." | `--doctor --fix` |
 | Search project wiki content | "Search the Project Librarian wiki for authentication decisions." | `--query "authentication decisions"` |
 | Show backlinks and decision citations for a page | "Show Project Librarian wiki impact for decisions/release-policy." | `--wiki-impact "decisions/release-policy"` |
-| Generate a wiki graph visualizer | "Generate the Project Librarian wiki graph visualizer." | `--wiki-visualize` |
+| Find nearby wiki context | "Show Project Librarian wiki neighborhood for canonical/project-brief." | `--wiki-neighborhood "canonical/project-brief"` |
 | Capture a candidate note | "Capture this as a Project Librarian candidate note: <details>." | `--capture-inbox --title "Candidate" --content "Details"` |
 | Save a session handoff | "Save a Project Librarian session handoff for the current work." | `--handoff-save --goal "..." --state "..." --next "..."` |
 | Resume from a handoff | "Show the last Project Librarian session handoff." | `--handoff-show` |
@@ -158,10 +158,8 @@ MCP server registration is a preservation-first merge into `mcpServers` for Clau
 6. `--refresh-index` routes newly discovered wiki pages; large route sets are split into `wiki/indexes/auto-*.md` scoped routers.
 7. `--code-index` creates a disposable SQLite evidence cache under `.project-wiki/`.
 8. `--code-report`, `--code-impact`, `--code-context-pack`, `--code-search-symbol`, and `--code-query` expose code-backed evidence for planning updates.
-9. Read-only wiki consumers share a concept read model that derives user-facing page types from paths and frontmatter without rewriting the canonical wiki schema.
-10. Wiki producers keep writing the canonical markdown/YAML schema, while read-only consumers such as diagnostics, MCP, and the visualizer use derived projections instead of mutating source documents.
-11. `--wiki-visualize` writes a static graph artifact to `.project-wiki/`, reusing the wiki graph and concept read model instead of introducing a database or server.
-12. Diagnostics report broken links, duplicate routes, orphan pages, stale pages, missing TL;DRs, evidence gaps, and migration policy violations.
+9. Wiki producers keep writing the canonical markdown/YAML schema, while read-only consumers such as diagnostics and MCP inspect source documents without mutating them.
+10. Diagnostics report broken links, duplicate routes, orphan pages, topology warnings, stale pages, missing TL;DRs, evidence gaps, and migration policy violations.
 
 Migration is intentionally review-first. `--migrate` preserves an existing `wiki/` as `wiki_legacy*`, skips form-only/template legacy files, splits mixed legacy pages into meaning units, classifies each unit through the document taxonomy, and writes review files under `wiki/migration/`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-librarian",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",
@@ -97,6 +97,6 @@
     "@sengac/tree-sitter-typescript": "^0.25.15"
   },
   "devDependencies": {
-    "@types/node": "^22.20.0"
+    "@types/node": "^26.1.0"
   }
 }

package/dist/wiki-concepts.js

@@ -1,49 +0,0 @@
-"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)));
-}