project-librarian 0.4.0 → 0.4.2

package/README.ko.md

@@ -75,17 +75,19 @@ npm run benchmark:release:preview
 npm run benchmark:release -- --allow-codex-run
 ```
 
+실측 릴리스 실행은 stderr에 `[benchmark:progress]` 줄을 스트리밍하여 시나리오 수, 예상 Codex 실행 총량, 현재 실행 순번, 단계, 프롬프트 ID, 종료 상태, 경과 시간, 원시 JSONL 경로를 보여줍니다. stdout은 최종 JSON 결과 전용으로 유지됩니다.
+
 ### 위키 트랙 (계획 문서 라우팅)
 
 비용 가중 토큰, Project Librarian 대 대조군:
 
 | 규모 | decision_lookup | aggregation | multi_session (2번째 세션) |
 | --- | --- | --- | --- |
-| 소형 | 43.8% 적음 | 144.5% 많음 | 5.4% 많음 |
-| 중형 | 53.4% 적음 | 4.4% 적음 | 68.5% 적음 |
-| 대형 | 71.6% 적음* | 12.8% 적음 | 66.0% 적음 |
+| 소형 | 14.4% 적음 | 81.0% 많음 | 22.0% 적음 |
+| 중형 | 52.0% 적음 | 19.0% 적음 | 54.1% 적음 |
+| 대형 | 71.1% 적음 | 29.0% 적음 | 71.8% 적음 |
 
-최신 합성 위키 트랙 릴리스 후보는 2026-06-16에 `gpt-5.5`로 측정했으며, 42개 시나리오를 각 3회 측정하고 1회 예열했습니다. 전체 주장 게이트는 **실패**했습니다. 42개 중 41개 시나리오는 정확성 검사를 통과했지만, Project Librarian이 없는 대형 `decision_lookup` 대조군이 3회 중 2회만 정답이었습니다. 실패한 대조군 실행은 기대한 최신 benchmark evidence 결정인 `2026-06-10` decision log 항목 대신, dated history 파일의 `2026-05-04` 항목을 골랐습니다. 따라서 이 표는 공개 릴리스 주장이 아니라 진단 근거로만 보아야 하며, 깨끗한 릴리스 실행이 주장 게이트를 통과해야 공개 주장으로 쓸 수 있습니다. 숨기지 않는 한계도 그대로 남습니다. 소형 `aggregation`은 위키를 켰을 때 훨씬 비싸고, 소형 `multi_session`도 약간 더 비싸며, `aggregation`은 토큰 비용이 줄어드는 규모에서도 실행 시간은 매번 더 느립니다.
+최신 합성 위키 트랙 릴리스 후보는 2026-06-19에 `gpt-5.5`로 측정했으며, 42개 시나리오를 각 3회 측정하고 1회 예열했습니다. 전체 주장 게이트는 **통과**했습니다. 42/42개 시나리오가 정확성 검사를 통과했고, 42개 시나리오가 모두 claimable이었으며, 모든 corpus 게이트가 3회 실행 최소 조건을 충족했습니다. 이 릴리스 주장은 여전히 합성 위키 라우팅 트랙과 표기된 작업 유형에 한정됩니다. 코드 그래프 동작, 실제 저장소, 모든 에이전트 표면, 모든 질문 형태에 대한 주장이 아닙니다. 숨기지 않는 한계도 그대로 남습니다. 소형 `aggregation`은 위키를 켰을 때 여전히 81.0% 비싸고, 전체 보고서의 소형 `release_policy`도 9.4% 비싸며, `aggregation`은 토큰 비용이 줄어드는 규모에서도 실행 시간은 매번 더 느립니다.
 
 ### 코드 그래프 트랙 (코드 근거 인덱스, 실제 저장소)
 
@@ -143,6 +145,8 @@ npx project-librarian install-skill --scope project --agents all
 
 `--agents`는 `codex,claude,cursor,gemini`처럼 쉼표로 구분한 값도 받습니다. `all`은 지원하는 모든 에이전트를 대상으로 합니다. `--scope`는 `user` 또는 `project`를 받습니다.
 
+프로젝트 설정/갱신 실행기도 `--agents`를 받습니다. 새로 설정할 때는 프로젝트 범위 Project Librarian 스킬 설치가 없을 때만 지원하는 모든 에이전트 표면을 기본으로 만듭니다. 저장소에 이미 `.codex/skills/project-librarian/`, `.claude/skills/project-librarian/` 같은 프로젝트 범위 스킬이 있으면 첫 설정도 그 설치된 에이전트 집합을 기본값으로 사용합니다. 마이그레이션 없는 기존 설정 갱신은 저장소에 이미 있는 에이전트 표면만 보존해서 갱신합니다. 따라서 Codex와 Claude 파일만 있던 저장소는 일반 갱신만으로 Cursor나 Gemini 파일이 새로 생기지 않습니다. 새 표면을 의도적으로 추가하려면 `project-librarian update --agents cursor` 또는 `project-librarian update --agents all`처럼 명시합니다. 목록에 없는 표면을 삭제하지는 않습니다.
+
 ## 실행 경로
 
 이 경로들은 주로 에이전트와 자동화를 위한 참조입니다. 설치 후 에이전트는 `npx`가 아니라 설치된 로컬 복사본을 `node`로 실행해야 합니다. 이렇게 하면 제한된 에이전트 환경에서 네트워크 접근과 버전이 고정되지 않은 패키지 실행을 피할 수 있습니다.
@@ -168,6 +172,7 @@ npx project-librarian install-skill --scope project --agents all
 | --- | --- | --- |
 | 위키 생성 또는 갱신 | "Project Librarian으로 이 저장소의 계획 위키를 설정하거나 갱신해줘." | `[init]` |
 | 마이그레이션 없이 기존 설정 갱신 | "위키를 마이그레이션하지 말고 이 저장소의 Project Librarian 설정을 갱신해줘." | `update` |
+| 기존 설정에 특정 에이전트 표면 추가 | "위키 마이그레이션 없이 Cursor Project Librarian 표면을 추가해줘." | `update --agents cursor` |
 | 기존 문서/위키 마이그레이션 | "Project Librarian으로 기존 docs/wiki 내용을 마이그레이션해줘." | `--migrate` |
 | 생성된 설정 검증 | "Project Librarian 검증을 실행해줘." | `--lint` |
 | 링크와 문서 품질 점검 | "Project Librarian 진단을 실행해줘." | `--doctor` |
@@ -188,6 +193,7 @@ npx project-librarian install-skill --scope project --agents all
 | 증분 갱신 요구 | "Project Librarian 코드 근거 인덱스를 증분 갱신해줘." | `--code-index --incremental` |
 | 전체 재생성 강제 | "Project Librarian 코드 근거 인덱스를 전체 재생성해줘." | `--code-index --code-index-full` |
 | 선택적 Tree-sitter 백엔드 사용 | "Tree-sitter 파서로 Project Librarian 코드 근거를 만들어줘." | `--code-index --code-parser tree-sitter` |
+| 캐시 호환성 진단 | "Project Librarian 코드 근거 캐시 상태와 호환성을 진단해줘." | `--code-index-health` |
 | 캐시 상태 보기 | "Project Librarian 코드 근거 상태를 보여줘." | `--code-status` |
 | 인덱싱된 파일 목록 | "Project Librarian 코드 근거에 인덱싱된 파일을 보여줘." | `--code-files` |
 | 아키텍처/소유권 보고서 출력 | "Project Librarian 코드 보고서를 보여줘." | `--code-report` |
@@ -201,6 +207,8 @@ npx project-librarian install-skill --scope project --agents all
 
 ## 설치되는 파일
 
+새로 설정할 때는 `--agents`로 좁히지 않았고 프로젝트 범위 Project Librarian 스킬 설치도 없을 때 아래 지원 에이전트 표면을 설치합니다. 마이그레이션 없는 기존 설정 갱신은 기본적으로 감지된 표면만 보존해서 갱신하고, 공통 위키/git 훅 파일은 계속 갱신합니다.
+
 프로젝트 지침 파일:
 
 - `AGENTS.md`
@@ -240,7 +248,7 @@ Git 훅 파일:
 - `wiki/index.md`
 - `wiki/meta/document-taxonomy.md`
 
-`canonical/project-brief.md`, `canonical/open-questions.md`, `canonical/assumptions.md`, `canonical/risks.md`, ADR 템플릿처럼 실제 내용이 없는 빈 프로젝트 문서는 기본 생성하지 않습니다. 나중에 실제 내용이 생기면 문서를 만들고 `--refresh-index`로 라우팅할 수 있습니다. 마이그레이션 중 발견한 양식 전용 legacy 템플릿은 새 위키 페이지나 검토 row로 만들지 않고 `wiki/migration/inventory.md`에 스킵 사유만 남깁니다.
+`canonical/project-brief.md`, `canonical/open-questions.md`, `canonical/assumptions.md`, `canonical/risks.md`, ADR 템플릿처럼 실제 내용이 없는 빈 프로젝트 문서는 기본 생성하지 않습니다. 나중에 실제 내용이 생기면 문서를 만들고 `--refresh-index`로 라우팅할 수 있습니다. 마이그레이션 중 발견한 양식 전용 기존 템플릿은 새 위키 페이지나 검토 행으로 만들지 않고 `wiki/migration/inventory.md`에 스킵 사유만 남깁니다.
 
 MCP 서버 등록 (`mcpServers`에 기존 항목 보존하며 병합):
 
@@ -276,12 +284,12 @@ codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/ini
 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. 읽기 전용 위키 소비자는 공통 concept read model을 사용해 canonical 위키 스키마를 다시 쓰지 않고 경로와 frontmatter에서 사용자용 페이지 유형을 파생합니다.
-10. 위키 생산자는 기존 markdown/YAML 정본 스키마를 계속 작성하고, 진단·MCP·시각화 같은 읽기 전용 소비자는 원본 문서를 바꾸지 않는 파생 보기를 사용합니다.
-11. `--wiki-visualize`는 데이터베이스나 서버를 추가하지 않고 기존 위키 그래프와 concept read model을 재사용해 `.project-wiki/` 아래 정적 그래프 산출물을 작성합니다.
+9. 읽기 전용 위키 소비자는 공통 개념 읽기 모델을 사용해 정본 위키 스키마를 다시 쓰지 않고 경로와 frontmatter에서 사용자용 페이지 유형을 파생합니다.
+10. 위키 생산자는 기존 Markdown/YAML 정본 스키마를 계속 작성하고, 진단·MCP·시각화 같은 읽기 전용 소비자는 원본 문서를 바꾸지 않는 파생 보기를 사용합니다.
+11. `--wiki-visualize`는 데이터베이스나 서버를 추가하지 않고 기존 위키 그래프와 개념 읽기 모델을 재사용해 `.project-wiki/` 아래 정적 그래프 산출물을 작성합니다.
 12. 진단은 깨진 링크, 중복 route, 고아 페이지, 오래된 페이지, 누락된 TL;DR, 근거 누락, 마이그레이션 정책 위반을 보고합니다.
 
-마이그레이션은 검토를 우선합니다. `--migrate`는 기존 `wiki/`를 `wiki_legacy*`로 보존하고, 양식 전용 legacy 파일은 제외한 뒤, 여러 성격의 내용이 섞인 기존 페이지를 의미 단위로 나눕니다. 이후 각 단위를 문서 분류 체계에 따라 분류해 `wiki/migration/` 아래 검토 파일을 작성합니다.
+마이그레이션은 검토를 우선합니다. `--migrate`는 기존 `wiki/`를 `wiki_legacy*`로 보존하고, 양식 전용 기존 파일은 제외한 뒤, 여러 성격의 내용이 섞인 기존 페이지를 의미 단위로 나눕니다. 이후 각 단위를 문서 분류 체계에 따라 분류해 `wiki/migration/` 아래 검토 파일을 작성합니다.
 
 - `inventory.md`는 기존 마크다운 파일 목록과 파일 단위 분류를 기록합니다.
 - `unit-map.md`는 각 제목, 문단, 목록 항목, 표 행, 코드 블록의 권장 분류 영역과 대상 페이지를 기록합니다.
@@ -351,6 +359,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install-skill [--
 | `--review-migration`, `--semantic-migrate` | 마이그레이션 coverage와 수신함 상태를 마이그레이션 검토 파일에 동기화합니다. |
 | `--no-git-config` | `git core.hooksPath`를 바꾸지 않고 훅 파일을 설치합니다. |
 | `--code-index` | 폐기 가능한 코드 근거 인덱스를 빌드합니다. |
+| `--code-index-health` | 코드 근거 캐시 호환성을 검사하고 쓰기 없이 재빌드 안내를 출력합니다. |
 | `--code-report` | 근거 인덱스에서 아키텍처/소유권 요약을 출력합니다. |
 | `--code-report-section <section>` | 한 섹션만 출력: `coverage`, `ownership`, `languages`, `parsers`, `workspaces`, `workspace-graph`, `routes`, `hotspots`, `configs`, `edges`. |
 | `--code-impact <term>` | 파일, 심볼, route, import, edge, 소유자 영향 근거를 보여줍니다. |
@@ -367,13 +376,44 @@ npm install
 npm run typecheck
 npm run build
 npm test
+npm run test:coverage
+npm run benchmark:llm:raw-audit
+npm run benchmark:llm:delta-analysis
+npm run benchmark:claim-ledger
+npm run release:check
 npm pack --dry-run
 ```
 
 `src/` 아래 TypeScript를 수정할 때는 커밋 전에 빌드해 `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 벤치마크도 실행하지 않습니다.
+
+`release:check` 통과는 런타임 보증이 아니라 재현 가능한 릴리스 준비 근거로 봐야 합니다. 현재 checkout에서 위 로컬 게이트를 통과했음을 증명하며, package dry run이 예상 publish 경계(`agents/`, `dist/`, `LICENSE`, `README.md`, `README.ko.md`, `SKILL.md`) 안에 머물고 소스 파일, 테스트, 저장소 로컬 위키/워크플로 상태, raw 벤치마크 출력, 로컬 캐시를 제외하는지도 확인합니다.
+
+배포는 GitHub Release가 published 상태가 된 뒤 `.github/workflows/publish.yml`에서 처리합니다. 이 워크플로는 GitHub OIDC 기반 npm trusted publishing(`id-token: write`)과 `npm publish --access public`을 사용하므로 npm provenance가 자동 생성됩니다. `NODE_AUTH_TOKEN`이나 npm token secret을 쓰면 안 되며, 릴리스 핵심 GitHub 공식 Actions는 전체 commit SHA로 고정합니다. `release:check`는 이 워크플로 계약도 로컬에서 검사합니다.
+
+trusted publishing과 npm provenance는 패키지가 이 GitHub OIDC 워크플로를 통해 게시되었음을 증명합니다. 벤치마크 정확성, 최종 사용자 저장소의 코드 근거 freshness, 보안 감사를 증명하지는 않으며, 그런 항목은 별도의 근거 트랙으로 다룹니다.
+
 관리자 벤치마크 명령은 [benchmarks/README.md](benchmarks/README.md)에 있습니다. 이 명령은 릴리스 근거와 공개 주장 검증을 위한 것이며, 일반 사용자 설정 절차가 아닙니다.
 
+코드 근거 런타임/스토리지 점검에는 `npm run perf:code-efficiency`를 사용합니다. 이 명령은 3k/10k/50k 픽스처를 생성하고 `benchmarks/reports/code-performance-efficiency/current.json`과 `.md`를 작성합니다. 명령 시간에는 CLI 시작과 freshness 확인이 포함되며, `query_groups` 섹션은 대표 file/symbol/route/import/edge 쿼리의 직접 DB 시간을 따로 보고합니다. 보고서는 `mixed-monorepo`, `web-service`, `python-cli`, `docs-heavy` 체크인 corpus도 합성 scale fixture와 분리해 측정합니다.
+
+측정형 LLM 벤치마크 실행은 1일보다 오래된 이전 raw run 디렉터리와 격리 Codex home을 자동 삭제하고, claimable 실행 실패 시에도 현재 실행의 home을 삭제한 뒤 종료합니다. raw JSONL, stderr, 보고서, manifest는 보존 기간 안의 실행에 대해서만 감사용으로 유지됩니다. 무시된 오래된 raw 출력은 격리 Codex home을 삭제하기 전에 dry-run-first 헬퍼로 여전히 먼저 감사할 수 있습니다.
+
+```bash
+npm run benchmark:llm:raw-audit -- --older-than-days 14
+npm run benchmark:llm:prune-raw -- --older-than-days 14
+npm run benchmark:llm:prune-raw -- --older-than-days 14 --execute
+```
+
+`npm run benchmark:llm:delta-analysis`는 체크인된 measured LLM 보고서를 읽고 Codex를 실행하지 않은 채 cost-weighted regression을 순위화합니다. 대표 raw JSONL command trace와 broad-search/router-read driver 분류까지 보려면 `-- --include-traces`를 붙입니다. 작은 scale aggregation처럼 약한 셀을 새 공개 claim보다 먼저 진단하는 첫 경로입니다.
+
+측정형 LLM 실행은 기본적으로 `--scenario-order run-major-balanced`를 사용합니다. 각 measured run index마다 선택된 모든 scenario를 실행하고 반복마다 순서를 뒤집어, 반복 실행에서 with/without 조건이 한쪽으로 몰리지 않게 합니다. 이전의 scenario별 묶음 실행 진단을 재현할 때만 `--scenario-order scenario-major`를 사용하세요.
+
+`npm run typecheck:ts7`은 opt-in TypeScript 7 RC 호환성 probe입니다. `npx`를 사용하며, compiler API와 이 프로젝트 TypeScript extractor의 parity 기록이 생기기 전까지 `test`, `release:check`, CI 게이트 밖에 둡니다.
+
 ## 영감
 
 이 프로젝트는 Andrej Karpathy의 [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 패턴에서 영감을 받았습니다. 긴 대화 기록에서 프로젝트 상태를 재구성하는 대신, 지속되는 markdown 컨텍스트를 작업 가까이에 둡니다.

package/README.md

@@ -75,17 +75,19 @@ npm run benchmark:release:preview
 npm run benchmark:release -- --allow-codex-run
 ```
 
+Measured release runs stream `[benchmark:progress]` lines to stderr for the scenario count, expected Codex exec total, current exec ordinal, phase, prompt id, exit status, elapsed time, and raw JSONL path. stdout stays reserved for the final JSON result.
+
 ### Wiki track (planning-doc routing)
 
 Cost-weighted tokens, Project Librarian vs control:
 
 | Scale | decision_lookup | aggregation | multi_session (2nd session) |
 | --- | --- | --- | --- |
-| Small | 43.8% less | 144.5% more | 5.4% more |
-| Medium | 53.4% less | 4.4% less | 68.5% less |
-| Large | 71.6% less* | 12.8% less | 66.0% less |
+| Small | 14.4% less | 81.0% more | 22.0% less |
+| Medium | 52.0% less | 19.0% less | 54.1% less |
+| Large | 71.1% less | 29.0% less | 71.8% less |
 
-Latest synthetic wiki-track release candidate: 2026-06-16, `gpt-5.5`, 42 scenarios, 3 measured runs plus 1 warmup each. The overall claim gate **failed**: 41/42 scenarios passed correctness, but `decision_lookup` at large scale on the no-Project-Librarian control had only 2/3 correct measured runs. The failed control run selected `2026-05-04` from a dated history file instead of the expected latest benchmark-evidence decision `2026-06-10` from the decision log. Treat this table as diagnostic evidence, not a public release claim, until a clean release run passes the claim gate. Published boundaries remain visible: small `aggregation` is much more expensive with the wiki, small `multi_session` is slightly more expensive, and `aggregation` stays slower at every scale even when token cost drops.
+Latest synthetic wiki-track release candidate: 2026-06-19, `gpt-5.5`, 42 scenarios, 3 measured runs plus 1 warmup each. The overall claim gate **passed**: 42/42 scenarios passed correctness, all 42 scenarios were claimable, and every corpus gate met the 3-run minimum. The release claim is still bounded to the synthetic wiki-routing track and the listed task families; it is not a claim about code-graph behavior, real repositories, every agent surface, or every question shape. Published boundaries remain visible: small `aggregation` still costs 81.0% more with the wiki, small `release_policy` costs 9.4% more in the full report, and `aggregation` stays slower at every scale even when token cost drops.
 
 ### Code-graph track (code evidence index, real repositories)
 
@@ -143,6 +145,8 @@ npx project-librarian install-skill --scope project --agents all
 
 `--agents` also accepts comma-separated values such as `codex,claude,cursor,gemini`. `all` targets every supported agent. `--scope` accepts `user` or `project`.
 
+The project setup/update runner also accepts `--agents`. Fresh setup defaults to all supported agent surfaces only when no project-scoped Project Librarian skill install is present. If the repository already has project-scoped skills such as `.codex/skills/project-librarian/` and `.claude/skills/project-librarian/`, the first setup uses that installed agent set by default. Existing non-migration updates preserve the agent surfaces already present in the repository, so a repo that has only Codex and Claude files will not gain Cursor or Gemini files on a plain update. Use `project-librarian update --agents cursor` or `project-librarian update --agents all` when you intentionally want to add newly supported surfaces; unlisted surfaces are not deleted.
+
 ## Runner Paths
 
 These paths are mainly for agents and automation. After installation, agents should run the installed local copy with `node`, not `npx`. This avoids network access and unpinned package execution in restricted agent environments.
@@ -168,6 +172,7 @@ Wiki setup and maintenance:
 | --- | --- | --- |
 | Create or update the wiki | "Use Project Librarian to set up or update this repository's planning wiki." | `[init]` |
 | Update existing setup without migration | "Update this repository's Project Librarian setup without migrating the wiki." | `update` |
+| Add a specific agent surface to an existing setup | "Add the Cursor Project Librarian surface without migrating the wiki." | `update --agents cursor` |
 | Migrate existing docs/wiki content | "Use Project Librarian to migrate the existing docs/wiki content." | `--migrate` |
 | Validate generated setup | "Run Project Librarian validation." | `--lint` |
 | Check links and document quality | "Run Project Librarian diagnostics." | `--doctor` |
@@ -188,6 +193,7 @@ Code evidence:
 | Require incremental update | "Update the Project Librarian code evidence index incrementally." | `--code-index --incremental` |
 | Force a full rebuild | "Fully rebuild the Project Librarian code evidence index." | `--code-index --code-index-full` |
 | Use optional Tree-sitter backend | "Build Project Librarian code evidence with the Tree-sitter parser." | `--code-index --code-parser tree-sitter` |
+| Inspect cache compatibility | "Inspect Project Librarian code evidence cache health." | `--code-index-health` |
 | Show cache status | "Show Project Librarian code evidence status." | `--code-status` |
 | List indexed files | "List files in the Project Librarian code evidence index." | `--code-files` |
 | Print architecture and ownership report | "Show the Project Librarian code report." | `--code-report` |
@@ -201,6 +207,8 @@ Only one code evidence mode can run at a time. `--incremental`, `--code-index-fu
 
 ## What Gets Installed
 
+Fresh setup installs the supported agent surfaces below unless you pass `--agents` or the repository already has project-scoped Project Librarian skills for a narrower agent set. Existing non-migration updates preserve the detected surface set by default and update only those selected surfaces plus the common wiki/git-hook files.
+
 Project instruction files:
 
 - `AGENTS.md`
@@ -351,6 +359,7 @@ Important options:
 | `--review-migration`, `--semantic-migrate` | Sync migration coverage and inbox statuses into migration review files. |
 | `--no-git-config` | Install hook files without changing `git core.hooksPath`. |
 | `--code-index` | Build the disposable code evidence index. |
+| `--code-index-health` | Inspect code evidence cache compatibility and print rebuild guidance without writing. |
 | `--code-report` | Print architecture and ownership summaries from the evidence index. |
 | `--code-report-section <section>` | Print one section: `coverage`, `ownership`, `languages`, `parsers`, `workspaces`, `workspace-graph`, `routes`, `hotspots`, `configs`, or `edges`. |
 | `--code-impact <term>` | Show file, symbol, route, import, edge, and owner impact evidence. |
@@ -367,13 +376,44 @@ npm install
 npm run typecheck
 npm run build
 npm test
+npm run test:coverage
+npm run benchmark:llm:raw-audit
+npm run benchmark:llm:delta-analysis
+npm run benchmark:claim-ledger
+npm run release:check
 npm pack --dry-run
 ```
 
 When editing TypeScript under `src/`, rebuild before committing so `dist/` stays current.
 
+`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.
+
+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.
+
+Publishing is handled by `.github/workflows/publish.yml` after a GitHub Release is published. The workflow uses npm trusted publishing through GitHub OIDC (`id-token: write`) and `npm publish --access public`, which generates npm provenance automatically; it must not use `NODE_AUTH_TOKEN` or npm token secrets, and release-critical first-party GitHub Actions are pinned to full commit SHAs. `release:check` verifies this workflow contract locally.
+
+Trusted publishing and npm provenance prove the package was published through that GitHub OIDC workflow. They do not prove benchmark correctness, code-evidence freshness in an end-user repository, or a security audit; those remain separate evidence tracks.
+
 Maintainer benchmark commands live in [benchmarks/README.md](benchmarks/README.md). They are for release evidence and public claim validation, not normal end-user setup.
 
+For code-evidence runtime/storage checks, `npm run perf:code-efficiency` generates 3k/10k/50k fixtures and writes `benchmarks/reports/code-performance-efficiency/current.json` plus `.md`. Command timings include CLI startup and freshness checks; the `query_groups` section reports direct DB timings for representative file/symbol/route/import/edge queries. The report also measures checked-in `mixed-monorepo`, `web-service`, `python-cli`, and `docs-heavy` corpora separately from synthetic scale fixtures.
+
+Measured LLM benchmark runs automatically prune stale prior raw run directories and isolated Codex homes older than 1 day, then prune the current run's homes even on claimable-run failure; raw JSONL, stderr, reports, and manifests remain for runs inside the retention window. Old ignored raw output can still be audited with the dry-run-first helper before deleting retained isolated Codex homes:
+
+```bash
+npm run benchmark:llm:raw-audit -- --older-than-days 14
+npm run benchmark:llm:prune-raw -- --older-than-days 14
+npm run benchmark:llm:prune-raw -- --older-than-days 14 --execute
+```
+
+`npm run benchmark:llm:delta-analysis` reads the checked-in measured LLM report and ranks cost-weighted regressions without launching Codex. Add `-- --include-traces` to include representative raw JSONL command traces and classify broad-search/router-read drivers. It is the first diagnostic stop for weak cells such as small-scale aggregation before adding new benchmark claims.
+
+Measured LLM runs default to `--scenario-order run-major-balanced`: each measured run index executes all selected scenarios, reversing the order on alternating repetitions so with/without pairs are not grouped by condition across repeated runs. Use `--scenario-order scenario-major` only when reproducing older scenario-grouped diagnostics.
+
+`npm run typecheck:ts7` is an opt-in TypeScript 7 RC compatibility probe. It uses `npx` and is intentionally outside `test`, `release:check`, and CI gates until the compiler API and this project's TypeScript extractor have a measured parity record.
+
 ## Inspiration
 
 This project is inspired by Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern: keep persistent markdown context close to the work instead of reconstructing project state from long chat history.

package/dist/agent-surfaces.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentSurfaceRequiredFiles = exports.allAgentSurfaces = void 0;
+exports.parseAgentSurfaceValues = parseAgentSurfaceValues;
+exports.hasProjectLibrarianInstall = hasProjectLibrarianInstall;
+exports.activeAgentSurfaces = activeAgentSurfaces;
+exports.resolveBootstrapAgentSurfaces = resolveBootstrapAgentSurfaces;
+exports.includesAgentSurface = includesAgentSurface;
+exports.allAgentSurfaces = ["codex", "claude", "cursor", "gemini"];
+exports.agentSurfaceRequiredFiles = {
+    codex: [".codex/hooks/wiki-session-start.js", ".codex/hooks.json"],
+    claude: ["CLAUDE.md", ".claude/hooks/wiki-session-start.js", ".claude/settings.json"],
+    cursor: [".cursor/rules/project-librarian.mdc", ".cursor/hooks/wiki-session-start.js", ".cursor/hooks.json"],
+    gemini: ["GEMINI.md", ".gemini/hooks/wiki-session-start.js", ".gemini/settings.json"],
+};
+const agentSurfaceProjectSkillFiles = {
+    codex: [".codex/skills/project-librarian/SKILL.md"],
+    claude: [".claude/skills/project-librarian/SKILL.md"],
+    cursor: [".cursor/skills/project-librarian/SKILL.md"],
+    gemini: [".gemini/skills/project-librarian/SKILL.md"],
+};
+const projectLibrarianCommonInstallFiles = [
+    "wiki/startup.md",
+    "wiki/index.md",
+    "wiki/AGENTS.md",
+];
+function parseAgentSurfaceValues(values) {
+    const surfaces = new Set();
+    const invalid = [];
+    for (const value of values) {
+        if (value === "all") {
+            for (const surface of exports.allAgentSurfaces)
+                surfaces.add(surface);
+        }
+        else if (exports.allAgentSurfaces.includes(value)) {
+            surfaces.add(value);
+        }
+        else {
+            invalid.push(value);
+        }
+    }
+    return { surfaces: Array.from(surfaces), invalid };
+}
+function hasProjectLibrarianInstall(fileExists, readFile) {
+    if (projectLibrarianCommonInstallFiles.some((file) => fileExists(file)))
+        return true;
+    if (exports.allAgentSurfaces.some((surface) => agentSurfaceProjectSkillFiles[surface].some((file) => fileExists(file))))
+        return true;
+    if (fileExists("AGENTS.md") && readFile) {
+        return readFile("AGENTS.md").includes("PROJECT-WIKI-FIRST:START");
+    }
+    return false;
+}
+function activeAgentSurfaces(fileExists) {
+    return exports.allAgentSurfaces.filter((surface) => (exports.agentSurfaceRequiredFiles[surface].some((file) => fileExists(file))
+        || agentSurfaceProjectSkillFiles[surface].some((file) => fileExists(file))));
+}
+function resolveBootstrapAgentSurfaces(explicitSurfaces, fileExists, readFile) {
+    if (explicitSurfaces.length > 0)
+        return Array.from(explicitSurfaces);
+    if (hasProjectLibrarianInstall(fileExists, readFile))
+        return activeAgentSurfaces(fileExists);
+    return Array.from(exports.allAgentSurfaces);
+}
+function includesAgentSurface(surfaces, surface) {
+    return surfaces.includes(surface);
+}

package/dist/args.js

@@ -1,79 +1,74 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.codeIndexOutput = exports.codeSearchSymbol = exports.codeReportSection = exports.codeQuerySql = exports.codeImpactTarget = exports.codeContextPackTarget = exports.wikiVisualizeOutput = exports.wikiVisualizeMode = exports.wikiImpactTarget = exports.wikiImpactMode = exports.queryTerm = exports.codeSearchSymbolMode = exports.codeQueryMode = exports.codeImpactMode = exports.codeParserMode = exports.codeContextPackMode = exports.codeFilesMode = exports.codeStatusMode = exports.codeReportMode = exports.codeIndexFullMode = exports.codeIndexIncrementalMode = exports.codeIndexMode = exports.acknowledgeSmallRepoMode = exports.noGitConfigMode = exports.reviewMigrationMode = exports.pruneCheckMode = exports.captureInboxMode = exports.refreshIndexMode = exports.issueDraftMode = exports.issueCreateMode = exports.glossaryMode = exports.fixMode = exports.doctorMode = exports.qualityCheckMode = exports.linkCheckMode = exports.migrationQualityCheckMode = exports.migrationLintMode = exports.migrationDoctorMode = exports.lintMode = exports.migrateMode = exports.missingValueOptions = exports.unexpectedValueOptions = exports.unknownOptions = exports.args = exports.commandArgs = exports.command = exports.unknownCommand = exports.helpMode = exports.parsedArgs = exports.rawArgs = void 0;
-exports.issueDraftTitle = exports.issueBodyFile = exports.captureCategory = exports.captureContent = exports.captureTitle = exports.codeIndexScopes = exports.codeParser = void 0;
+exports.codeQuerySql = exports.codeImpactTarget = exports.codeContextPackTarget = exports.wikiVisualizeOutput = exports.wikiVisualizeMode = exports.wikiImpactTarget = exports.wikiImpactMode = exports.queryTerm = exports.codeSearchSymbolMode = exports.codeQueryMode = exports.codeImpactMode = exports.codeParserMode = exports.codeContextPackMode = exports.codeFilesMode = exports.codeStatusMode = exports.codeReportMode = exports.codeIndexHealthMode = exports.codeIndexFullMode = exports.codeIndexIncrementalMode = exports.codeIndexMode = exports.acknowledgeSmallRepoMode = exports.noGitConfigMode = exports.reviewMigrationMode = exports.pruneCheckMode = exports.captureInboxMode = exports.refreshIndexMode = exports.issueDraftMode = exports.issueCreateMode = exports.glossaryMode = exports.fixMode = exports.doctorMode = exports.qualityCheckMode = exports.linkCheckMode = exports.migrationQualityCheckMode = exports.migrationLintMode = exports.migrationDoctorMode = exports.lintMode = exports.migrateMode = exports.invalidAgentTargets = exports.missingValueOptions = exports.unexpectedValueOptions = exports.unknownOptions = exports.args = exports.commandArgs = exports.command = exports.unknownCommand = exports.helpMode = exports.agentTargets = exports.parsedArgs = exports.rawArgs = void 0;
+exports.issueDraftTitle = exports.issueBodyFile = exports.captureCategory = exports.captureContent = exports.captureTitle = exports.codeIndexScopes = exports.codeParser = exports.codeIndexOutput = exports.codeSearchSymbol = exports.codeReportSection = void 0;
 exports.parseArgs = parseArgs;
 exports.argValue = argValue;
 exports.argValues = argValues;
+const agent_surfaces_1 = require("./agent-surfaces");
 exports.rawArgs = process.argv.slice(2);
 const knownCommands = new Set(["init", "update", "install-skill", "mcp"]);
-const flagsWithoutValues = new Set([
-    "--acknowledge-small-repo",
-    "--adopt-existing",
-    "--capture-inbox",
-    "--code-evidence-files",
-    "--code-evidence-index",
-    "--code-evidence-status",
-    "--code-files",
-    "--code-incremental",
-    "--code-index",
-    "--code-index-full",
-    "--code-index-incremental",
-    "--code-evidence-index-full",
-    "--code-evidence-index-incremental",
-    "--code-report",
-    "--code-status",
-    "--code-evidence-report",
-    "--dry-run",
-    "--glossary-init",
-    "--doctor",
-    "--fix",
-    "--issue-create",
-    "--issue-draft",
-    "--incremental",
-    "--link-check",
-    "--lint",
-    "--migrate",
-    "--migration-doctor",
-    "--migration-lint",
-    "--migration-quality-check",
-    "--no-git-config",
-    "--prune-check",
-    "--quality-check",
-    "--refresh-index",
-    "--review-migration",
-    "--semantic-migrate",
-    "--wiki-graph-html",
-    "--wiki-visualize",
-]);
-const flagsWithValues = new Set([
-    "--agents",
-    "--category",
-    "--code-evidence-context-pack",
-    "--code-evidence-impact",
-    "--code-context-pack",
-    "--code-evidence-out",
-    "--code-evidence-parser",
-    "--code-evidence-query",
-    "--code-evidence-report-section",
-    "--code-evidence-scope",
-    "--code-evidence-symbol",
-    "--code-impact",
-    "--code-index-out",
-    "--code-parser",
-    "--code-query",
-    "--code-report-section",
-    "--code-scope",
-    "--code-search-symbol",
-    "--content",
-    "--issue-body-file",
-    "--issue-title",
-    "--query",
-    "--scope",
-    "--title",
-    "--wiki-impact",
-    "--wiki-visualize-out",
-]);
+const flagDefinitions = [
+    { name: "--acknowledge-small-repo", value: "none" },
+    { name: "--adopt-existing", value: "none" },
+    { name: "--agents", value: "value" },
+    { name: "--capture-inbox", value: "none" },
+    { name: "--category", value: "value" },
+    { name: "--code-context-pack", value: "value", aliases: ["--code-evidence-context-pack"] },
+    { name: "--code-files", value: "none", aliases: ["--code-evidence-files"] },
+    { name: "--code-impact", value: "value", aliases: ["--code-evidence-impact"] },
+    { name: "--code-index", value: "none", aliases: ["--code-evidence-index"] },
+    { name: "--code-index-full", value: "none", aliases: ["--code-evidence-index-full"] },
+    { name: "--code-index-health", value: "none" },
+    { name: "--code-index-incremental", value: "none", aliases: ["--incremental", "--code-incremental", "--code-evidence-index-incremental"] },
+    { name: "--code-index-out", value: "value", aliases: ["--code-evidence-out"] },
+    { name: "--code-parser", value: "value", aliases: ["--code-evidence-parser"] },
+    { name: "--code-query", value: "value", aliases: ["--code-evidence-query"] },
+    { name: "--code-report", value: "none", aliases: ["--code-evidence-report"] },
+    { name: "--code-report-section", value: "value", aliases: ["--code-evidence-report-section"] },
+    { name: "--code-scope", value: "value", aliases: ["--code-evidence-scope"] },
+    { name: "--code-search-symbol", value: "value", aliases: ["--code-evidence-symbol"] },
+    { name: "--code-status", value: "none", aliases: ["--code-evidence-status"] },
+    { name: "--content", value: "value" },
+    { name: "--doctor", value: "none" },
+    { name: "--dry-run", value: "none" },
+    { name: "--fix", value: "none" },
+    { name: "--glossary-init", value: "none" },
+    { name: "--issue-body-file", value: "value" },
+    { name: "--issue-create", value: "none" },
+    { name: "--issue-draft", value: "none" },
+    { name: "--issue-title", value: "value" },
+    { name: "--link-check", value: "none" },
+    { name: "--lint", value: "none" },
+    { name: "--migrate", value: "none" },
+    { name: "--migration-doctor", value: "none" },
+    { name: "--migration-lint", value: "none" },
+    { name: "--migration-quality-check", value: "none" },
+    { name: "--no-git-config", value: "none" },
+    { name: "--prune-check", value: "none" },
+    { name: "--quality-check", value: "none" },
+    { name: "--query", value: "value" },
+    { name: "--refresh-index", value: "none" },
+    { name: "--review-migration", value: "none", aliases: ["--semantic-migrate"] },
+    { name: "--scope", value: "value" },
+    { name: "--title", value: "value" },
+    { name: "--wiki-graph-html", value: "none" },
+    { name: "--wiki-impact", value: "value" },
+    { name: "--wiki-visualize", value: "none" },
+    { name: "--wiki-visualize-out", value: "value" },
+];
+function definitionNames(definition) {
+    return [definition.name, ...(definition.aliases ?? [])];
+}
+function flagNamesByPolicy(value) {
+    return flagDefinitions.filter((definition) => definition.value === value).flatMap(definitionNames);
+}
+function namesForFlag(name) {
+    const definition = flagDefinitions.find((candidate) => definitionNames(candidate).includes(name));
+    return definition ? definitionNames(definition) : [name];
+}
+const flagsWithoutValues = new Set(flagNamesByPolicy("none"));
+const flagsWithValues = new Set(flagNamesByPolicy("value"));
 const knownFlags = new Set([...flagsWithoutValues, ...flagsWithValues, "--help", "-h"]);
 function flagName(arg) {
     return arg.startsWith("--") ? arg.split("=", 1)[0] ?? arg : arg;
@@ -134,36 +129,42 @@ function parseArgs(argv) {
     const hasFlag = (name) => hasFlagIn(commandArgs, name);
     const argValue = (name) => argValueFrom(commandArgs, name);
     const argValues = (name) => argValuesFrom(commandArgs, name);
-    const codeImpactTarget = argValue("--code-impact") || argValue("--code-evidence-impact");
-    const codeContextPackTarget = argValue("--code-context-pack") || argValue("--code-evidence-context-pack");
-    const codeQuerySql = argValue("--code-query") || argValue("--code-evidence-query");
-    const codeSearchSymbol = argValue("--code-search-symbol") || argValue("--code-evidence-symbol");
+    const hasAnyFlag = (name) => namesForFlag(name).some(hasFlag);
+    const argValueFromAny = (name) => namesForFlag(name).map(argValue).find(Boolean) ?? "";
+    const argValuesFromAny = (name) => namesForFlag(name).flatMap(argValues);
+    const codeImpactTarget = argValueFromAny("--code-impact");
+    const codeContextPackTarget = argValueFromAny("--code-context-pack");
+    const codeQuerySql = argValueFromAny("--code-query");
+    const codeSearchSymbol = argValueFromAny("--code-search-symbol");
+    const parsedAgentTargets = (0, agent_surfaces_1.parseAgentSurfaceValues)(argValues("--agents"));
     return {
         acknowledgeSmallRepoMode: args.has("--acknowledge-small-repo"),
+        agentTargets: parsedAgentTargets.surfaces,
         args,
         captureCategory: argValue("--category") || "project-candidate",
         captureContent: argValue("--content"),
         captureInboxMode: args.has("--capture-inbox"),
         captureTitle: argValue("--title"),
-        codeContextPackMode: hasFlag("--code-context-pack") || hasFlag("--code-evidence-context-pack"),
+        codeContextPackMode: hasAnyFlag("--code-context-pack"),
         codeContextPackTarget,
-        codeFilesMode: args.has("--code-files") || args.has("--code-evidence-files"),
-        codeImpactMode: hasFlag("--code-impact") || hasFlag("--code-evidence-impact"),
+        codeFilesMode: hasAnyFlag("--code-files"),
+        codeImpactMode: hasAnyFlag("--code-impact"),
         codeImpactTarget,
-        codeIndexFullMode: args.has("--code-index-full") || args.has("--code-evidence-index-full"),
-        codeIndexIncrementalMode: args.has("--incremental") || args.has("--code-incremental") || args.has("--code-index-incremental") || args.has("--code-evidence-index-incremental"),
-        codeIndexMode: args.has("--code-index") || args.has("--code-evidence-index"),
-        codeIndexOutput: argValue("--code-index-out") || argValue("--code-evidence-out") || ".project-wiki/code-evidence.sqlite",
-        codeIndexScopes: [...argValues("--code-scope"), ...argValues("--code-evidence-scope")],
-        codeParser: argValue("--code-parser") || argValue("--code-evidence-parser") || "default",
-        codeParserMode: hasFlag("--code-parser") || hasFlag("--code-evidence-parser"),
-        codeQueryMode: hasFlag("--code-query") || hasFlag("--code-evidence-query"),
+        codeIndexFullMode: hasAnyFlag("--code-index-full"),
+        codeIndexHealthMode: args.has("--code-index-health"),
+        codeIndexIncrementalMode: hasAnyFlag("--code-index-incremental"),
+        codeIndexMode: hasAnyFlag("--code-index"),
+        codeIndexOutput: argValueFromAny("--code-index-out") || ".project-wiki/code-evidence.sqlite",
+        codeIndexScopes: argValuesFromAny("--code-scope"),
+        codeParser: argValueFromAny("--code-parser") || "default",
+        codeParserMode: hasAnyFlag("--code-parser"),
+        codeQueryMode: hasAnyFlag("--code-query"),
         codeQuerySql,
-        codeReportMode: args.has("--code-report") || args.has("--code-evidence-report"),
-        codeReportSection: argValue("--code-report-section") || argValue("--code-evidence-report-section"),
+        codeReportMode: hasAnyFlag("--code-report"),
+        codeReportSection: argValueFromAny("--code-report-section"),
         codeSearchSymbol,
-        codeSearchSymbolMode: hasFlag("--code-search-symbol") || hasFlag("--code-evidence-symbol"),
-        codeStatusMode: args.has("--code-status") || args.has("--code-evidence-status"),
+        codeSearchSymbolMode: hasAnyFlag("--code-search-symbol"),
+        codeStatusMode: hasAnyFlag("--code-status"),
         command,
         commandArgs,
         doctorMode: args.has("--doctor"),
@@ -174,6 +175,7 @@ function parseArgs(argv) {
         issueCreateMode: args.has("--issue-create"),
         issueDraftMode: args.has("--issue-draft"),
         issueDraftTitle: argValue("--issue-title"),
+        invalidAgentTargets: parsedAgentTargets.invalid,
         linkCheckMode: args.has("--link-check"),
         lintMode: args.has("--lint"),
         migrationDoctorMode: args.has("--migration-doctor"),
@@ -187,7 +189,7 @@ function parseArgs(argv) {
         queryTerm: argValue("--query"),
         rawArgs: argv,
         refreshIndexMode: args.has("--refresh-index"),
-        reviewMigrationMode: args.has("--review-migration") || args.has("--semantic-migrate"),
+        reviewMigrationMode: hasAnyFlag("--review-migration"),
         unexpectedValueOptions: Array.from(new Set(commandArgs
             .filter((arg) => arg.startsWith("--") && arg.includes("="))
             .map(flagName)
@@ -204,6 +206,7 @@ function parseArgs(argv) {
     };
 }
 exports.parsedArgs = parseArgs(exports.rawArgs);
+exports.agentTargets = exports.parsedArgs.agentTargets;
 exports.helpMode = exports.parsedArgs.helpMode;
 exports.unknownCommand = exports.parsedArgs.unknownCommand;
 exports.command = exports.parsedArgs.command;
@@ -212,6 +215,7 @@ exports.args = exports.parsedArgs.args;
 exports.unknownOptions = exports.parsedArgs.unknownOptions;
 exports.unexpectedValueOptions = exports.parsedArgs.unexpectedValueOptions;
 exports.missingValueOptions = exports.parsedArgs.missingValueOptions;
+exports.invalidAgentTargets = exports.parsedArgs.invalidAgentTargets;
 exports.migrateMode = exports.parsedArgs.migrateMode;
 exports.lintMode = exports.parsedArgs.lintMode;
 exports.migrationDoctorMode = exports.parsedArgs.migrationDoctorMode;
@@ -233,6 +237,7 @@ exports.acknowledgeSmallRepoMode = exports.parsedArgs.acknowledgeSmallRepoMode;
 exports.codeIndexMode = exports.parsedArgs.codeIndexMode;
 exports.codeIndexIncrementalMode = exports.parsedArgs.codeIndexIncrementalMode;
 exports.codeIndexFullMode = exports.parsedArgs.codeIndexFullMode;
+exports.codeIndexHealthMode = exports.parsedArgs.codeIndexHealthMode;
 exports.codeReportMode = exports.parsedArgs.codeReportMode;
 exports.codeStatusMode = exports.parsedArgs.codeStatusMode;
 exports.codeFilesMode = exports.parsedArgs.codeFilesMode;