project-librarian 0.4.1 → 0.4.3

package/README.ko.md

@@ -52,7 +52,7 @@ Project Librarian은 에이전트에게 두 가지 로컬 정본을 제공합니
 | 표면 | 에이전트가 얻는 것 |
 | --- | --- |
 | `wiki/startup.md` + `wiki/index.md` | 짧은 세션 시작 요약과 라우터. 관련 계획 페이지만 읽습니다. |
-| `wiki/canonical/` 및 `wiki/decisions/` | 현재 프로젝트 사실, 제약, 리스크, 패키지 계약, CLI 동작, 지속되는 결정. |
+| `wiki/canonical/`, `wiki/roadmaps/`, `wiki/plans/`, `wiki/decisions/` | 현재 정본은 canonical, 큰 미래 작업은 roadmaps, 상세 실행은 plans, 지속되는 근거는 decisions에 둡니다. |
 | `wiki/meta/document-taxonomy.md` | PRD, 정책, UX, 데이터, 개발, QA, 릴리즈, 운영 정본을 어디에 둘지 안내하는 서비스 생애주기 분류 지도. |
 | `.codex/`, `.claude/`, `.cursor/`, `.gemini/` 훅 | 전체 위키를 불러오지 않는 Codex/Claude Code/Cursor/Gemini CLI 시작 컨텍스트. |
 | `GEMINI.md` 및 `.cursor/rules/` | Gemini CLI와 Cursor를 같은 간결한 위키 우선 계약으로 안내하는 지침 파일. |
@@ -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회만 정답이었습니다. 실패한 대조군 실행은 날짜가 붙은 히스토리 파일에서 `2026-05-04`를 골랐고, 기대값은 결정 로그의 최신 벤치마크 근거 결정인 `2026-06-10`이었습니다. 따라서 이 표는 공개 릴리스 주장이 아니라 진단 근거로만 보아야 하며, 깨끗한 릴리스 실행이 주장 게이트를 통과해야 공개 주장으로 쓸 수 있습니다. 숨기지 않는 한계도 그대로 남습니다. 소형 `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,7 +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 코드 근거 캐시 health를 확인해줘." | `--code-index-health` |
+| 캐시 호환성 진단 | "Project Librarian 코드 근거 캐시 상태와 호환성을 진단해줘." | `--code-index-health` |
 | 캐시 상태 보기 | "Project Librarian 코드 근거 상태를 보여줘." | `--code-status` |
 | 인덱싱된 파일 목록 | "Project Librarian 코드 근거에 인덱싱된 파일을 보여줘." | `--code-files` |
 | 아키텍처/소유권 보고서 출력 | "Project Librarian 코드 보고서를 보여줘." | `--code-report` |
@@ -202,6 +207,8 @@ npx project-librarian install-skill --scope project --agents all
 
 ## 설치되는 파일
 
+새로 설정할 때는 `--agents`로 좁히지 않았고 프로젝트 범위 Project Librarian 스킬 설치도 없을 때 아래 지원 에이전트 표면을 설치합니다. 마이그레이션 없는 기존 설정 갱신은 기본적으로 감지된 표면만 보존해서 갱신하고, 공통 위키/git 훅 파일은 계속 갱신합니다.
+
 프로젝트 지침 파일:
 
 - `AGENTS.md`
@@ -229,6 +236,8 @@ Git 훅 파일:
 위키 디렉터리:
 
 - `wiki/canonical/`
+- `wiki/roadmaps/`
+- `wiki/plans/`
 - `wiki/decisions/`
 - `wiki/inbox/`
 - `wiki/meta/`
@@ -369,6 +378,9 @@ 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
@@ -376,19 +388,34 @@ npm pack --dry-run
 
 `src/` 아래 TypeScript를 수정할 때는 커밋 전에 빌드해 `dist/`를 최신 상태로 유지하세요.
 
-`npm run release:check`는 로컬 전용 관리자 게이트입니다. 테스트, 벤치마크 파서 smoke, 벤치마크 release preview, 벤치마크 claim ledger 분류, package dry-run 검사, dist 실행 가능 여부, README 벤치마크 claim 경계 문구를 확인합니다. publish하지 않고 measured Codex 벤치마크도 실행하지 않습니다.
+`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`를 포함한 체크인 샘플 corpus도 합성 scale fixture와 분리해 포함됩니다.
+코드 근거 런타임/스토리지 점검에는 `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 벤치마크 raw 출력은 격리 Codex home을 삭제하기 전에 dry-run-first 헬퍼로 먼저 감사할 수 있습니다.
+측정형 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

@@ -52,7 +52,7 @@ Project Librarian gives agents two local sources of truth:
 | Surface | What It Gives The Agent |
 | --- | --- |
 | `wiki/startup.md` + `wiki/index.md` | A compact session-start summary and router, so only the relevant planning pages are read. |
-| `wiki/canonical/` and `wiki/decisions/` | Current project facts, constraints, risks, package contracts, CLI behavior, and durable decisions. |
+| `wiki/canonical/`, `wiki/roadmaps/`, `wiki/plans/`, and `wiki/decisions/` | Current truth stays in canonical pages, broad future work stays in roadmaps, detailed execution stays in plans, and durable rationale stays in decisions. |
 | `wiki/meta/document-taxonomy.md` | A service-lifecycle classification map that tells agents where PRD, policy, UX, data, engineering, QA, release, and operations truth should live. |
 | `.codex/`, `.claude/`, `.cursor/`, and `.gemini/` hooks | Automatic startup context for Codex, Claude Code, Cursor, and Gemini CLI without loading the full wiki. |
 | `GEMINI.md` and `.cursor/rules/` | Gemini CLI and Cursor instruction files that route agents to the same compact wiki-first contract. |
@@ -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`
@@ -228,6 +236,8 @@ Git hook files:
 Wiki directories:
 
 - `wiki/canonical/`
+- `wiki/roadmaps/`
+- `wiki/plans/`
 - `wiki/decisions/`
 - `wiki/inbox/`
 - `wiki/meta/`
@@ -368,6 +378,9 @@ 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
@@ -375,19 +388,34 @@ npm pack --dry-run
 
 When editing TypeScript under `src/`, rebuild before committing so `dist/` stays current.
 
-`npm run release:check` is a local-only maintainer gate: it runs tests, benchmark parser smoke, benchmark release preview, benchmark claim-ledger classification, package dry-run inspection, dist executable checks, and README benchmark-claim boundary checks. It never publishes and never launches a measured Codex benchmark.
+`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 includes checked-in sample corpora, including `mixed-monorepo`, separately from synthetic scale fixtures.
+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.
 
-Old ignored LLM benchmark raw output can be audited with the dry-run-first helper before deleting retained isolated Codex homes:
+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/SKILL.md

@@ -200,6 +200,7 @@ Execution contract:
 3. Separate evidence mapping from canonical truth:
    - Code structure, entrypoints, module relationships, execution flows, read-on-demand routes, and evidence paths belong under `wiki/meta/` with descriptive project-specific filenames chosen by the LLM.
    - Code-backed current project behavior, features, policies, constraints, terminology, domain rules, and operational facts belong under `wiki/canonical/`.
+   - Broad future work belongs under `wiki/roadmaps/`; detailed execution plans belong under `wiki/plans/`. After completion, update canonical truth and remove completed roadmap/plan content after rationale and evidence are preserved.
    - Important design rationale or tradeoffs inferred from code may belong under `wiki/decisions/` when they meet the decision policy.
    - Unclear, conflicting, or low-confidence interpretations belong in `wiki/inbox/` or a focused canonical questions page created for the topic, not directly in canonical truth.
 4. Do not use fixed canonical filenames. Choose or create files from topic boundaries, expected read frequency, and token budget.
@@ -228,6 +229,8 @@ It installs:
 - `wiki/startup.md` compact session-start context.
 - `wiki/index.md` router with read/update/token-budget hints.
 - `wiki/canonical/` directory for project-current-truth documents, created only when real content exists.
+- `wiki/roadmaps/` for broad future scope and priority queues, created only when real content exists.
+- `wiki/plans/` for detailed future execution plans, created only when real content exists.
 - Optional `wiki/canonical/glossary.md` project terminology contract when `--glossary-init` is used.
 - `wiki/decisions/` project-decision directory and lightweight decision ledgers.
 - `wiki/meta/` wiki operating rules, project decision policy, and wiki-operations Decision Pack.
@@ -247,7 +250,7 @@ Project canonical wiki content should not default to Korean or English. Choose t
 
 ## Boundary Rule
 
-`wiki/canonical/` and `wiki/decisions/` are for project planning only. Do not store wiki operating decisions, hook/bootstrap/lint/migration details, LLM collaboration preferences, assistant reminders, or non-project workflow memory there.
+`wiki/canonical/`, `wiki/roadmaps/`, `wiki/plans/`, and `wiki/decisions/` are for project planning only. Do not store wiki operating decisions, hook/bootstrap/lint/migration details, LLM collaboration preferences, assistant reminders, or non-project workflow memory there.
 
 Use:
 
@@ -255,6 +258,8 @@ Use:
 - Root `AGENTS.md`, hooks, or skills for durable project-wide LLM instructions and collaboration memory.
 - `wiki/AGENTS.md` for wiki-internal editing rules that should apply only under `wiki/`.
 - `wiki/canonical/` only for current project truth.
+- `wiki/roadmaps/` only for broad future scope, priority queues, and milestone sequences.
+- `wiki/plans/` only for detailed future execution plans.
 - `wiki/decisions/` only for project decision history.
 
 Every wiki markdown file should include a compact metadata header with `status`, `updated`, `scope`, `read_budget`, `decision_ref`, and `review_trigger`.

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,80 +1,74 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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.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 = exports.codeIndexOutput = 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-health",
-    "--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;
@@ -135,37 +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"),
+        codeIndexFullMode: hasAnyFlag("--code-index-full"),
         codeIndexHealthMode: args.has("--code-index-health"),
-        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"),
+        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"),
@@ -176,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"),
@@ -189,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)
@@ -206,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;
@@ -214,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;

package/dist/code-index/modes.js

@@ -60,7 +60,13 @@ function printJson(value) {
 function requireCompatibleDatabase(database, runtime) {
     const schemaVersion = (0, schema_1.readMetaValue)(database, "schema_version");
     if (schemaVersion !== schema_1.codeIndexSchemaVersion) {
-        runtime.fail(`code evidence index schema version ${schemaVersion || "(missing)"} is incompatible with ${schema_1.codeIndexSchemaVersion}; rebuild with --code-index`);
+        const databasePath = runtime.codeEvidenceDatabasePath();
+        runtime.fail([
+            `code evidence index schema version ${schemaVersion || "(missing)"} is incompatible with ${schema_1.codeIndexSchemaVersion}`,
+            `inspect: project-librarian --code-index-health`,
+            `rebuild: project-librarian --code-index --code-index-full`,
+            `database: ${databasePath.relativePath}`,
+        ].join("\n"));
     }
 }
 function runCodeIndexMode(runtime) {

package/dist/init-project-wiki.js

@@ -2,6 +2,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const args_1 = require("./args");
+const agent_surfaces_1 = require("./agent-surfaces");
 const hooks_1 = require("./hooks");
 const install_skill_1 = require("./install-skill");
 const modes_1 = require("./modes");
@@ -39,6 +40,7 @@ Options:
   --refresh-index                  Update the managed auto-discovered wiki index block.
   --capture-inbox                  Append a candidate note with --title, --content, and optional --category.
   --glossary-init                  Create and route the optional glossary page.
+  --agents <list>                  With init/update, write only selected agent surfaces: codex, claude, cursor, gemini, or all. Existing project skill/setup surfaces are preserved by default.
   --prune-check                    Report active pages with stale or unresolved signals.
   --review-migration               Sync unit coverage and compatible inbox statuses into migration review files.
   --no-git-config                  Install hook files without changing git core.hooksPath.
@@ -107,6 +109,11 @@ if (args_1.missingValueOptions.length > 0) {
     printUsage();
     process.exit(1);
 }
+if (args_1.invalidAgentTargets.length > 0) {
+    console.error(`invalid --agents entr${args_1.invalidAgentTargets.length === 1 ? "y" : "ies"}: ${args_1.invalidAgentTargets.join(", ")}; expected codex, claude, cursor, gemini, or all`);
+    printUsage();
+    process.exit(1);
+}
 if (args_1.command === "update" && args_1.migrateMode) {
     console.error("update cannot be combined with --migrate or --adopt-existing; use project-librarian --migrate for migration.");
     process.exit(1);
@@ -247,6 +254,16 @@ function runInitCommand() {
         runRefreshIndexOnlyMode();
         process.exit(0);
     }
+    const selectedAgentSurfaces = args_1.agentTargets.length > 0
+        ? args_1.agentTargets
+        : args_1.migrateMode
+            ? Array.from(agent_surfaces_1.allAgentSurfaces)
+            : (0, agent_surfaces_1.resolveBootstrapAgentSurfaces)(args_1.agentTargets, workspace_1.exists, workspace_1.read);
+    const shouldWriteSurface = (surface) => (0, agent_surfaces_1.includesAgentSurface)(selectedAgentSurfaces, surface);
+    const writeCodexSurface = shouldWriteSurface("codex");
+    const writeClaudeSurface = shouldWriteSurface("claude");
+    const writeCursorSurface = shouldWriteSurface("cursor");
+    const writeGeminiSurface = shouldWriteSurface("gemini");
     const migrationState = args_1.migrateMode ? (0, migration_1.prepareMigrationMode)() : null;
     const results = [];
     if (migrationState)
@@ -256,11 +273,16 @@ function runInitCommand() {
     (0, workspace_1.mkdirp)("wiki/inbox");
     (0, workspace_1.mkdirp)("wiki/meta");
     (0, workspace_1.mkdirp)("wiki/sources");
-    (0, workspace_1.mkdirp)(".codex/hooks");
-    (0, workspace_1.mkdirp)(".claude/hooks");
-    (0, workspace_1.mkdirp)(".cursor/hooks");
-    (0, workspace_1.mkdirp)(".cursor/rules");
-    (0, workspace_1.mkdirp)(".gemini/hooks");
+    if (writeCodexSurface)
+        (0, workspace_1.mkdirp)(".codex/hooks");
+    if (writeClaudeSurface)
+        (0, workspace_1.mkdirp)(".claude/hooks");
+    if (writeCursorSurface) {
+        (0, workspace_1.mkdirp)(".cursor/hooks");
+        (0, workspace_1.mkdirp)(".cursor/rules");
+    }
+    if (writeGeminiSurface)
+        (0, workspace_1.mkdirp)(".gemini/hooks");
     (0, workspace_1.mkdirp)(".githooks");
     // B1 fallback: sync the CURRENT startup.md TL;DR into the managed AGENTS.md block
     // so non-interactive `codex exec` (which does not run SessionStart hooks) still
@@ -271,23 +293,34 @@ function runInitCommand() {
     const startupForSync = (0, workspace_1.exists)("wiki/startup.md") ? (0, workspace_1.read)("wiki/startup.md") : templates_1.startup;
     const startupTldrForAgents = (0, templates_1.extractStartupTldr)(startupForSync);
     results.push(["AGENTS.md", (0, workspace_1.upsertMarkedSection)("AGENTS.md", "<!-- PROJECT-WIKI-FIRST:START -->", "<!-- PROJECT-WIKI-FIRST:END -->", (0, templates_1.agentsSection)(startupTldrForAgents))]);
-    results.push(["CLAUDE.md", (0, workspace_1.upsertMarkedSection)("CLAUDE.md", "<!-- PROJECT-WIKI-CLAUDE:START -->", "<!-- PROJECT-WIKI-CLAUDE:END -->", templates_1.claudeSection)]);
-    results.push(["GEMINI.md", (0, workspace_1.upsertMarkedSection)("GEMINI.md", "<!-- PROJECT-WIKI-GEMINI:START -->", "<!-- PROJECT-WIKI-GEMINI:END -->", templates_1.geminiSection)]);
-    results.push([".cursor/rules/project-librarian.mdc", (0, workspace_1.writeManaged)(".cursor/rules/project-librarian.mdc", templates_1.cursorRule)]);
+    if (writeClaudeSurface)
+        results.push(["CLAUDE.md", (0, workspace_1.upsertMarkedSection)("CLAUDE.md", "<!-- PROJECT-WIKI-CLAUDE:START -->", "<!-- PROJECT-WIKI-CLAUDE:END -->", templates_1.claudeSection)]);
+    if (writeGeminiSurface)
+        results.push(["GEMINI.md", (0, workspace_1.upsertMarkedSection)("GEMINI.md", "<!-- PROJECT-WIKI-GEMINI:START -->", "<!-- PROJECT-WIKI-GEMINI:END -->", templates_1.geminiSection)]);
+    if (writeCursorSurface)
+        results.push([".cursor/rules/project-librarian.mdc", (0, workspace_1.writeManaged)(".cursor/rules/project-librarian.mdc", templates_1.cursorRule)]);
     results.push(["wiki/AGENTS.md", (0, workspace_1.upsertMarkedSection)("wiki/AGENTS.md", "<!-- PROJECT-WIKI-INTERNAL:START -->", "<!-- PROJECT-WIKI-INTERNAL:END -->", templates_1.wikiAgentsSection)]);
     results.push([".githooks/prepare-commit-msg", (0, workspace_1.writeManaged)(".githooks/prepare-commit-msg", hooks_1.gitPrepareCommitMsgHook)]);
     (0, workspace_1.makeExecutable)(".githooks/prepare-commit-msg");
     results.push([".githooks/wiki-commit-trailers.js", (0, workspace_1.writeManaged)(".githooks/wiki-commit-trailers.js", hooks_1.gitWikiCommitTrailersScript)]);
     (0, workspace_1.makeExecutable)(".githooks/wiki-commit-trailers.js");
     results.push(["git core.hooksPath", (0, hooks_1.upsertGitHooksPath)()]);
-    results.push([".codex/hooks.json", (0, hooks_1.upsertHookConfig)()]);
-    results.push([".codex/hooks/wiki-session-start.js", (0, workspace_1.writeManaged)(".codex/hooks/wiki-session-start.js", hooks_1.hookScript)]);
-    results.push([".claude/settings.json", (0, hooks_1.upsertClaudeHookConfig)()]);
-    results.push([".claude/hooks/wiki-session-start.js", (0, workspace_1.writeManaged)(".claude/hooks/wiki-session-start.js", hooks_1.hookScript)]);
-    results.push([".cursor/hooks.json", (0, hooks_1.upsertCursorHookConfig)()]);
-    results.push([".cursor/hooks/wiki-session-start.js", (0, workspace_1.writeManaged)(".cursor/hooks/wiki-session-start.js", hooks_1.cursorHookScript)]);
-    results.push([".gemini/settings.json", (0, hooks_1.upsertGeminiHookConfig)()]);
-    results.push([".gemini/hooks/wiki-session-start.js", (0, workspace_1.writeManaged)(".gemini/hooks/wiki-session-start.js", hooks_1.hookScript)]);
+    if (writeCodexSurface) {
+        results.push([".codex/hooks.json", (0, hooks_1.upsertHookConfig)()]);
+        results.push([".codex/hooks/wiki-session-start.js", (0, workspace_1.writeManaged)(".codex/hooks/wiki-session-start.js", hooks_1.hookScript)]);
+    }
+    if (writeClaudeSurface) {
+        results.push([".claude/settings.json", (0, hooks_1.upsertClaudeHookConfig)()]);
+        results.push([".claude/hooks/wiki-session-start.js", (0, workspace_1.writeManaged)(".claude/hooks/wiki-session-start.js", hooks_1.hookScript)]);
+    }
+    if (writeCursorSurface) {
+        results.push([".cursor/hooks.json", (0, hooks_1.upsertCursorHookConfig)()]);
+        results.push([".cursor/hooks/wiki-session-start.js", (0, workspace_1.writeManaged)(".cursor/hooks/wiki-session-start.js", hooks_1.cursorHookScript)]);
+    }
+    if (writeGeminiSurface) {
+        results.push([".gemini/settings.json", (0, hooks_1.upsertGeminiHookConfig)()]);
+        results.push([".gemini/hooks/wiki-session-start.js", (0, workspace_1.writeManaged)(".gemini/hooks/wiki-session-start.js", hooks_1.hookScript)]);
+    }
     // Bootstrap-managed MCP registration (preservation-first, idempotent). Claude
     // Code reads `.mcp.json`, Cursor reads `.cursor/mcp.json`, and Gemini reads
     // `mcpServers` inside `.gemini/settings.json`. Codex only supports user-level MCP
@@ -296,16 +329,24 @@ function runInitCommand() {
     // Registration is scale-gated (2026-06-12 decision): below the measured
     // file-count threshold with no existing .project-wiki index, the rows report the
     // skip reason instead of writing config; an existing index registers regardless.
-    const mcpGate = (0, hooks_1.mcpRegistrationGate)();
-    if (mcpGate.register) {
-        results.push([".mcp.json", (0, hooks_1.upsertClaudeMcpConfig)()]);
-        results.push([".cursor/mcp.json", (0, hooks_1.upsertCursorMcpConfig)()]);
-        results.push([".gemini/settings.json mcpServers", (0, hooks_1.upsertGeminiMcpConfig)()]);
-    }
-    else {
-        results.push([".mcp.json", mcpGate.reason]);
-        results.push([".cursor/mcp.json", mcpGate.reason]);
-        results.push([".gemini/settings.json mcpServers", mcpGate.reason]);
+    if (writeClaudeSurface || writeCursorSurface || writeGeminiSurface) {
+        const mcpGate = (0, hooks_1.mcpRegistrationGate)();
+        if (mcpGate.register) {
+            if (writeClaudeSurface)
+                results.push([".mcp.json", (0, hooks_1.upsertClaudeMcpConfig)()]);
+            if (writeCursorSurface)
+                results.push([".cursor/mcp.json", (0, hooks_1.upsertCursorMcpConfig)()]);
+            if (writeGeminiSurface)
+                results.push([".gemini/settings.json mcpServers", (0, hooks_1.upsertGeminiMcpConfig)()]);
+        }
+        else {
+            if (writeClaudeSurface)
+                results.push([".mcp.json", mcpGate.reason]);
+            if (writeCursorSurface)
+                results.push([".cursor/mcp.json", mcpGate.reason]);
+            if (writeGeminiSurface)
+                results.push([".gemini/settings.json mcpServers", mcpGate.reason]);
+        }
     }
     // Routers accumulate user-maintained project state after bootstrap, so they are
     // starter files: templates are written only when the file is absent, never rebuilt.

package/dist/install-skill.js

@@ -37,9 +37,9 @@ exports.runInstallSkillMode = runInstallSkillMode;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+const agent_surfaces_1 = require("./agent-surfaces");
 const args_1 = require("./args");
 const skillName = "project-librarian";
-const allAgentTargets = ["codex", "claude", "cursor", "gemini"];
 const packageFiles = [
     "SKILL.md",
     "dist",
@@ -65,10 +65,10 @@ function installAgents() {
     const agents = new Set();
     for (const part of parts) {
         if (part === "all") {
-            for (const agent of allAgentTargets)
+            for (const agent of agent_surfaces_1.allAgentSurfaces)
                 agents.add(agent);
         }
-        else if (allAgentTargets.includes(part)) {
+        else if (agent_surfaces_1.allAgentSurfaces.includes(part)) {
             agents.add(part);
         }
         else {

package/dist/modes.js

@@ -57,6 +57,7 @@ const fs = __importStar(require("node:fs"));
 const childProcess = __importStar(require("node:child_process"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+const agent_surfaces_1 = require("./agent-surfaces");
 const args_1 = require("./args");
 const workspace_1 = require("./workspace");
 const templates_1 = require("./templates");
@@ -66,6 +67,7 @@ const wiki_graph_1 = require("./wiki-graph");
 const wiki_corpus_1 = require("./wiki-corpus");
 const wiki_diagnostics_1 = require("./wiki-diagnostics");
 const scopedAutoIndexThreshold = 40;
+const scopedAutoIndexCharLimit = 7600;
 const scopedAutoIndexMarker = "<!-- PROJECT-WIKI-SCOPED-AUTO-INDEX -->";
 function isScopedAutoIndex(file) {
     return /^wiki\/indexes\/auto-[a-z0-9-]+\.md$/.test(file);
@@ -89,16 +91,18 @@ function routeAreaForWikiFile(file) {
         return slugPart(directory);
     return "misc";
 }
-function scopedIndexPath(area) {
-    return `wiki/indexes/auto-${slugPart(area)}.md`;
+function scopedIndexPath(area, partIndex = 0, partCount = 1) {
+    const slug = slugPart(area);
+    return partCount <= 1 ? `wiki/indexes/auto-${slug}.md` : `wiki/indexes/auto-${slug}-${partIndex + 1}.md`;
 }
-function scopedIndexContent(area, files) {
+function scopedIndexContent(area, files, partIndex = 0, partCount = 1) {
+    const title = partCount <= 1 ? area : `${area} (${partIndex + 1}/${partCount})`;
     const rows = files.map((file) => {
         const meta = (0, wiki_files_1.metadataSummary)(file, (0, workspace_1.read)(file));
         return `| ${(0, wiki_files_1.wikiLinkForFile)(file)} | ${meta.scope} | ${meta.status} | ${meta.budget} |`;
     }).join("\n");
     return `${(0, templates_1.metadata)("wiki-router", "medium", "wiki/meta/wiki-ops-v1-decisions.md", "auto-discovered scoped routes change")}${scopedAutoIndexMarker}
-# Auto Index: ${area}
+# Auto Index: ${title}
 
 ## TL;DR
 
@@ -110,6 +114,23 @@ function scopedIndexContent(area, files) {
 ${rows}
 `;
 }
+function splitScopedIndexFiles(area, files) {
+    const parts = [];
+    let current = [];
+    for (const file of files) {
+        const candidate = [...current, file];
+        if (current.length > 0 && scopedIndexContent(area, candidate).length > scopedAutoIndexCharLimit) {
+            parts.push(current);
+            current = [file];
+        }
+        else {
+            current = candidate;
+        }
+    }
+    if (current.length > 0)
+        parts.push(current);
+    return parts;
+}
 function removeStaleScopedAutoIndexes(keepPaths) {
     if (!(0, workspace_1.exists)("wiki/indexes"))
         return;
@@ -126,16 +147,23 @@ function syncScopedAutoIndexes(files) {
         const area = routeAreaForWikiFile(file);
         groups.set(area, [...(groups.get(area) ?? []), file]);
     }
-    const summaries = Array.from(groups.entries()).map(([area, areaFiles]) => ({
-        area,
-        count: areaFiles.length,
-        file: scopedIndexPath(area),
-        files: areaFiles.sort(),
-    })).sort((left, right) => right.count - left.count || left.area.localeCompare(right.area));
+    const summaries = Array.from(groups.entries()).flatMap(([area, areaFiles]) => {
+        const sortedFiles = areaFiles.sort();
+        const parts = splitScopedIndexFiles(area, sortedFiles);
+        return parts.map((files, partIndex) => ({
+            area: parts.length <= 1 ? area : `${area} ${partIndex + 1}`,
+            baseArea: area,
+            count: files.length,
+            file: scopedIndexPath(area, partIndex, parts.length),
+            files,
+            partIndex,
+            partCount: parts.length,
+        }));
+    }).sort((left, right) => right.count - left.count || left.area.localeCompare(right.area));
     const keepPaths = new Set(summaries.map((summary) => summary.file));
     removeStaleScopedAutoIndexes(keepPaths);
     for (const summary of summaries)
-        (0, workspace_1.write)(summary.file, scopedIndexContent(summary.area, summary.files));
+        (0, workspace_1.write)(summary.file, scopedIndexContent(summary.baseArea, summary.files, summary.partIndex, summary.partCount));
     return summaries.map(({ area, count, file }) => ({ area, count, file }));
 }
 function buildRefreshIndexBlock() {
@@ -149,8 +177,6 @@ function buildRefreshIndexBlock() {
         return `<!-- PROJECT-WIKI-AUTO-INDEX:START -->
 ## Auto-Discovered Pages
 
-This block is managed by \`--refresh-index\`. Large route sets are split into scoped generated routers to keep \`wiki/index.md\` within startup-hook budget.
-
 | Scoped Router | Area | Pages |
 | --- | --- | ---: |
 ${rows}
@@ -192,6 +218,10 @@ function scoreQueryBlock(block, terms) {
 function hasMigrationQueryIntent(terms) {
     return terms.some((term) => /^(migrat|legacy|coverage|unit|ledger|review)/.test(term));
 }
+function hasDeepReferenceQueryIntent(terms) {
+    return hasMigrationQueryIntent(terms)
+        || terms.some((term) => /^(archive|audit|decision|detail|history|ledger|raw|record|source|trace|verification)/.test(term));
+}
 function isMigrationSurface(file, meta) {
     return file.startsWith("wiki/migration/")
         || /(?:^|-)migration(?:-|$)/.test(file)
@@ -204,6 +234,9 @@ function querySurfaceScore(file, meta, rawScore, terms) {
         return Math.max(1, Math.floor(rawScore * 0.25) - 20);
     }
     let score = rawScore;
+    if (meta.budget === "on-demand" && !hasDeepReferenceQueryIntent(terms)) {
+        score = Math.max(1, Math.min(Math.floor(score * 0.5), 24));
+    }
     if (file.startsWith("wiki/canonical/") && meta.status === "active")
         score += 12;
     else if (meta.status === "active")
@@ -889,15 +922,9 @@ const commonLintRequiredFiles = [
     ".githooks/prepare-commit-msg",
     ".githooks/wiki-commit-trailers.js",
 ];
-const agentLintRequiredFiles = {
-    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"],
-};
 function activeLintAgentSurfaces() {
     const active = new Set();
-    for (const [agent, files] of Object.entries(agentLintRequiredFiles)) {
+    for (const [agent, files] of Object.entries(agent_surfaces_1.agentSurfaceRequiredFiles)) {
         if (files.some((file) => (0, workspace_1.exists)(file)))
             active.add(agent);
     }
@@ -909,7 +936,7 @@ function runLintMode(corpus) {
     const activeAgents = activeLintAgentSurfaces();
     const requiredFiles = [
         ...commonLintRequiredFiles,
-        ...Array.from(activeAgents).flatMap((agent) => agentLintRequiredFiles[agent]),
+        ...Array.from(activeAgents).flatMap((agent) => agent_surfaces_1.agentSurfaceRequiredFiles[agent]),
     ];
     for (const file of requiredFiles) {
         if (!(0, workspace_1.exists)(file))

package/dist/templates.js

@@ -70,7 +70,7 @@ At the start of every session:
 
 1. Review \`wiki/startup.md\` for compact current context.
 2. Review \`wiki/index.md\` as the router for which files to read next.
-3. Read detailed \`wiki/canonical/\`, \`wiki/decisions/\`, \`wiki/meta/\`, and \`wiki/sources/\` files on demand only when the current question needs them.
+3. Read detailed \`wiki/canonical/\`, \`wiki/roadmaps/\`, \`wiki/plans/\`, \`wiki/decisions/\`, \`wiki/meta/\`, and \`wiki/sources/\` files on demand only when the current question needs them.
 
 ### ${exports.startupTldrSyncLabel}
 
@@ -133,12 +133,14 @@ Language policy:
 Reading rules:
 
 - Treat \`startup.md\` as compact session context and \`index.md\` as the router.
-- Read detailed \`canonical/\`, \`decisions/\`, \`meta/\`, and \`sources/\` files on demand only when the current question needs them.
+- Read detailed \`canonical/\`, \`roadmaps/\`, \`plans/\`, \`decisions/\`, \`meta/\`, and \`sources/\` files on demand only when the current question needs them.
 - Prefer each file's TL;DR and metadata before reading the full body.
 
 Storage boundaries:
 
 - \`canonical/\` contains current project-planning truth only.
+- \`roadmaps/\` contains broad future scope, priority queues, and milestone sequences only; it is not canonical truth.
+- \`plans/\` contains detailed execution plans for roadmap items only; it is not canonical truth.
 - \`decisions/\` contains project decision history only.
 - \`meta/\` contains wiki operating rules, decision policy, bootstrap, lint, hook, and migration decisions.
 - \`sources/\` contains external reference summaries and source notes.
@@ -150,6 +152,8 @@ Classification rules:
 
 - Before adding or consolidating project content, classify it with \`meta/document-taxonomy.md\`.
 - Write current agreement to the narrowest durable canonical document that fits the taxonomy; do not append unrelated material to \`canonical/project-brief.md\`.
+- Put broad future work in \`roadmaps/\` and detailed execution plans in \`plans/\`, not \`canonical/\`.
+- When roadmap or plan work is completed, update canonical truth first, preserve rationale/evidence where needed, then remove the completed roadmap/plan content.
 - If one input crosses several lifecycle areas, split it into separate canonical updates and link the related pages.
 - If the input explains why a direction changed, update the relevant decision log or Decision Pack in addition to canonical truth.
 - If an external artifact is the better source of truth (for example Figma, OpenAPI, ERD, issue tracker, or code), keep a concise canonical summary and link the external source as the authoritative location.
@@ -187,10 +191,11 @@ exports.startup = `${(0, exports.metadata)("startup-router", "short", "wiki/meta
 ## TL;DR
 
 - This project is in an initial planning state unless the canonical wiki says otherwise.
-- Project truth lives in \`wiki/canonical/\`, project decision history lives in \`wiki/decisions/\`, and source summaries live in \`wiki/sources/\`.
+- Project truth lives in \`wiki/canonical/\`, future work in \`wiki/roadmaps/\` and \`wiki/plans/\`, project decisions in \`wiki/decisions/\`, and sources in \`wiki/sources/\`.
 - Wiki operating rules and wiki operating decisions live in \`wiki/meta/\`.
 - At session start, read only this file and \`wiki/index.md\` first; read detailed files on demand.
 - Project canonical content language is not fixed by this bootstrap. The LLM should choose the language that best matches the user and project context.
+- Completed roadmaps/plans are removed after truth/rationale/evidence capture.
 - Update the wiki in the same turn when project-planning content changes.
 - Classify new project-planning content with \`wiki/meta/document-taxonomy.md\` before writing or consolidating it.
 
@@ -239,7 +244,9 @@ This file is a router, not a file to expand into every answer. Read only the fil
 
 ## Boundary Rule
 
-- \`wiki/canonical/\` and \`wiki/decisions/\` contain project-planning content only.
+- \`wiki/canonical/\`: current accepted project truth only.
+- \`wiki/roadmaps/\`: broad future scope only; \`wiki/plans/\`: detailed execution only.
+- \`wiki/decisions/\`: project decision history only.
 - Wiki operating rules and wiki operating decisions live in \`wiki/meta/\`.
 - Non-project LLM memory, collaboration reminders, and workflow instructions belong in \`AGENTS.md\`, \`wiki/AGENTS.md\`, hooks, or skills, not in project canonical/decision docs.
 
@@ -254,7 +261,7 @@ This file is a router, not a file to expand into every answer. Read only the fil
 
 No empty canonical starter pages are created by default. Create focused pages under \`wiki/canonical/\` only when durable project truth exists, then route them here or with \`--refresh-index\`.
 
-## Project Decisions
+## Decisions
 
 - [[decisions/recent]]
   - Read: recent important project decisions.
@@ -335,6 +342,7 @@ exports.wikiOperatingModel = `${(0, exports.metadata)("wiki-meta", "medium", "wi
 - This wiki keeps project-planning knowledge as durable markdown.
 - Codex, Claude Code, Cursor, and Gemini CLI session-start hooks inject only \`wiki/startup.md\` and \`wiki/index.md\`.
 - Detailed canonical and decision files are read on demand.
+- Roadmaps and plans are separate from canonical truth; canonical pages keep the current accepted state.
 - Root \`AGENTS.md\` keeps the project-wide wiki-first contract; \`wiki/AGENTS.md\` keeps detailed wiki editing rules.
 - Operating documents generated by bootstrap are English by default.
 - Project canonical content language is selected from user/project context, not hardcoded by this bootstrap.
@@ -352,24 +360,28 @@ Karpathy's LLM Wiki pattern favors a continuously maintained markdown wiki over
 ## Layers
 
 1. Sources: external docs, links, user notes, and evidence summaries.
-2. Canonical project truth: current valid planning content under \`wiki/canonical/\`.
-3. Project decisions: rationale, rejected alternatives, and revisit triggers under \`wiki/decisions/\`.
-4. Startup context: compact session summary in \`wiki/startup.md\`.
-5. Router: read/update/token-budget guidance in \`wiki/index.md\`.
-6. Wiki meta: operating rules, decision policy, bootstrap, migration, lint, and language policy under \`wiki/meta/\`.
+2. Canonical project truth: current accepted specs, contracts, policies, and operating state under \`wiki/canonical/\`.
+3. Roadmaps: broad future scope, priority queues, and milestone sequences under \`wiki/roadmaps/\` or an external tracker.
+4. Plans: detailed execution plans for roadmap items under \`wiki/plans/\` or an external tracker.
+5. Project decisions: rationale, rejected alternatives, and revisit triggers under \`wiki/decisions/\`.
+6. Startup context: compact session summary in \`wiki/startup.md\`.
+7. Router: read/update/token-budget guidance in \`wiki/index.md\`.
+8. Wiki meta: operating rules, decision policy, bootstrap, migration, lint, and language policy under \`wiki/meta/\`.
 
 ## Content Classification Procedure
 
 Before writing or reorganizing project-planning content:
 
 1. Identify the content's lifecycle area with [[meta/document-taxonomy]].
-2. Decide whether the content is current truth, decision rationale, source evidence, an unresolved candidate, or a wiki operating rule.
-3. Write current truth to the narrowest relevant \`canonical/\` page, decision rationale to \`decisions/\`, source notes to \`sources/\`, candidates to \`inbox/\`, and wiki operating rules to \`meta/\`.
+2. Decide whether the content is current truth, roadmap, detailed plan, decision rationale, source evidence, an unresolved candidate, or a wiki operating rule.
+3. Write current truth to the narrowest relevant \`canonical/\` page, broad future scope to \`roadmaps/\`, detailed execution plans to \`plans/\`, decision rationale to \`decisions/\`, source notes to \`sources/\`, candidates to \`inbox/\`, and wiki operating rules to \`meta/\`.
 4. Split multi-area inputs instead of making one catch-all document.
 5. Link upstream and downstream pages when the content derives from another artifact or produces another artifact.
 
 Do not treat \`canonical/project-brief.md\` as a default dumping ground. It should summarize direction, audience, scope, and success criteria; detailed product, policy, UX, data, engineering, QA, release, or operations truth should move into focused pages when it grows.
 
+Do not treat \`wiki/canonical/\` as a plan archive. If a whole document is mainly about future scope, implementation sequence, migration wave, branch status, or work result log, keep it outside canonical truth and link it from the relevant current-spec page only when readers need that context. When the work is done, update canonical truth and then remove completed roadmap/plan content after rationale and evidence are preserved in their proper places.
+
 ## Language Policy
 
 - Bootstrap-generated operating documents are English.
@@ -448,14 +460,15 @@ exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki
 ## TL;DR
 
 - Classify new project-planning content before writing it into the wiki.
-- Use this page to classify content into \`canonical/\`, \`decisions/\`, \`sources/\`, \`inbox/\`, or \`meta/\`.
-- Keep \`canonical/project-brief.md\` compact; move detailed truth into focused canonical pages.
+- Classify into \`canonical/\`, \`roadmaps/\`, \`plans/\`, \`decisions/\`, \`sources/\`, \`inbox/\`, or \`meta/\`.
+- Keep \`canonical/project-brief.md\` compact; move details into focused pages.
+- Keep future work outside canonical; canonical pages may include brief change pointers.
 - Preserve derivation links: evidence -> strategy -> requirements -> design/data/engineering -> QA -> release/operations -> feedback.
 
 ## Top-Level Flow
 
 \`\`\`text
-0. Source-of-truth governance
+0. Governance
   -> 1. Research and evidence
     -> 2. Strategy and business model
       -> 3. Product scope and requirements
@@ -469,27 +482,37 @@ exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki
             -> 11. Release and operations
               -> 12. Business operations
                 -> 13. Improvement, migration, and end-of-life
-                  -> next product scope, policy, or roadmap change
+                  -> roadmap -> plan -> canonical update
 \`\`\`
 
 ## Storage Decision
 
 | Content Type | Store In | Notes |
 | --- | --- | --- |
-| Current valid project truth | \`wiki/canonical/\` | Split by topic and read frequency. |
+| Current project truth | \`wiki/canonical/\` | Accepted spec, contract, policy, or operating state. |
+| Roadmap, milestone sequence, or priority queue | \`wiki/roadmaps/\` or tracker | Broad future scope, not canonical truth. |
+| Detailed plan, proposal, migration, or task sequence | \`wiki/plans/\` or external tracker | Execution detail, not canonical truth. |
 | Why a choice was made | \`wiki/decisions/\` | Use log, Decision Pack, or ADR by impact. |
 | Source material or summarized evidence | \`wiki/sources/\` | Keep links, checked dates, and applicability. |
 | Unreviewed or ambiguous material | \`wiki/inbox/\` | Do not treat as canonical truth. |
 | Wiki operation, taxonomy, hooks, migration, lint, language rules | \`wiki/meta/\` | Keep outside project canonical truth. |
 | Better external source of truth | External artifact plus a concise wiki route | Examples: Figma, OpenAPI, ERD, Jira, code. |
 
+## Canonical vs Roadmap vs Plan Boundary
+
+\`wiki/canonical/\` is for the state readers should treat as true now. A page mainly about future change, implementation sequence, migration wave, branch status, or work log is not canonical truth.
+
+Use \`wiki/roadmaps/\` for broad ordered future work. Use \`wiki/plans/\` for one roadmap item's details. Put only short planned-change notes in canonical pages.
+
+After acceptance or release, rewrite canonical truth. Move rationale to \`wiki/decisions/\` and evidence to \`wiki/sources/\`, release notes, or reports. Then delete completed roadmap/plan content unless external retention is required.
+
 ## Lifecycle Areas
 
 | Area | Put Here | Usually Derives From | Usually Produces |
 | --- | --- | --- | --- |
 | 0. Governance | source-of-truth map, owners, RACI, approval flow, change rules, glossary, state dictionary, assumptions, risk register | team/process constraints | routing, ownership, conflict resolution |
 | 1. Research | market, competitor, user interviews, VOC, analytics, legal/regulatory, technical feasibility, cost, vendor, accessibility research | raw discovery | strategy, risks, sources |
-| 2. Strategy | service overview, vision, problem, target users, personas, jobs-to-be-done, value offer, positioning, business model, KPI/OKR, success/stop criteria, roadmap, MVP, non-goals | research | PRD, roadmap, scope |
+| 2. Strategy | service overview, vision, problem, target users, personas, jobs-to-be-done, value offer, positioning, business model, KPI/OKR, success/stop criteria, committed roadmap summary, MVP, non-goals | research | PRD, roadmap, scope |
 | 3. Product | PRD, user stories, use cases, priorities, backlog rules, acceptance criteria, feature spec, exceptions, state definitions, notification rules, search/filter/sort rules, admin requirements | strategy and policy | UX, API, data, QA |
 | 4. Policy | operations policy, auth/account, permissions, pricing, payment/refund, coupon/credit, content moderation, notifications, retention/deletion, abuse response, support, EOL | business model, law, risks | feature constraints, API rules, CS/ops |
 | 5. UX and Content | IA, sitemap, user flow, task flow, screen list, wireframes, screen specs, content model, UX writing, empty/error states, help/FAQ, localization, SEO, accessibility criteria | product and policy | design, frontend, QA |
@@ -498,7 +521,7 @@ exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki
 | 8. Engineering | architecture, technology decisions, API/OpenAPI, integrations, webhooks/idempotency, state machines, jobs/cron, error codes, env vars, secrets, local dev, conventions, branch/release strategy, CI/CD, feature flags, dependencies, migrations, performance, scalability, FinOps | product, UX, data, policy | implementation and verification |
 | 9. Security/Legal | security requirements, threat model, privacy rules, privacy impact, terms, privacy policy, audit logs, permission history, internal access controls, key rotation, vulnerability response, licenses, vendor and DPA documents | data, architecture, law | controls, tests, release gates |
 | 10. QA | test strategy, QA scenarios, test cases, regression checklist, UAT, browser/device matrix, accessibility tests, performance tests, security tests, data quality tests, design QA, quality gates | requirements, design, engineering | release approval |
-| 11. Release/Ops | release plan, deployment procedure, rollback, release notes, operator manual, runbooks, monitoring, observability, SLO/SLA, on-call/escalation, incident response, backup/restore, DR/BCP, recurring checks | QA and infrastructure | stable operation |
+| 11. Release/Ops | current release policy, deployment procedure, rollback, release notes, operator manual, runbooks, monitoring, observability, SLO/SLA, on-call/escalation, incident response, backup/restore, DR/BCP, recurring checks | QA and infrastructure | stable operation |
 | 12. Business Ops | CS macros, support policy, training, sales/adoption guide, CRM rules, onboarding playbook, churn/offboarding, admin operations, communication templates, revenue recognition, tax/invoice, partner operations | policy, release, sales motion | customer-facing operation |
 | 13. Improvement/EOL | VOC summary, retrospectives, experiments, experiment results, cohort/retention analysis, feature deprecation, migration/data transfer, service end-of-life | operations and analytics | next PRD, policy, roadmap |
 
@@ -507,11 +530,14 @@ exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki
 When a new note arrives:
 
 1. Identify the lifecycle area and storage location.
-2. Update an existing focused page when the topic already has a canonical home.
-3. Create a new focused page only when the topic is durable, likely to be read independently, or too large for its current page.
-4. Add an \`index.md\` route when the page becomes durable.
-5. Add upstream/downstream links in prose or tables when one artifact derives from another.
-6. Record decision rationale separately when the change explains why the project chose one option over another.
+2. Decide whether content is current truth, roadmap, plan, decision rationale, evidence, candidate, or wiki operating rule.
+3. Update an existing focused canonical page only when the content changes current truth.
+4. Create a new focused page only when the topic is durable, likely to be read independently, or too large for its current page.
+5. If the document is future-oriented, store broad scope in \`roadmaps/\` and detailed execution in \`plans/\`.
+6. Add an \`index.md\` route when the page becomes durable.
+7. Add upstream/downstream links in prose or tables when one artifact derives from another.
+8. Record decision rationale separately when the change explains why the project chose one option over another.
+9. When roadmap/plan work is done, update canonical truth, preserve rationale/evidence, then remove completed roadmap/plan content.
 
 ## Page Shape
 
@@ -670,7 +696,7 @@ No project decisions yet.
 ## TL;DR
 
 - This Decision Pack records accepted wiki operating choices for project-librarian.
-- It covers wiki structure, document taxonomy, startup hook scope, metadata, language policy, git hook behavior, migration review, and inbox handling.
+- It covers wiki structure, document taxonomy, startup hook scope, metadata, language policy, git hook behavior, migration review, inbox handling, and canonical/roadmap/plan boundaries.
 - Project product decisions belong in \`wiki/decisions/\`, while these operating decisions stay in \`wiki/meta/\`.
 
 Status: accepted
@@ -685,6 +711,8 @@ Canonical: [[meta/operating-model]], [[meta/decision-policy]], [[meta/document-t
 | ${workspace_1.today} | Inject only \`startup.md\` and \`index.md\` through Codex, Claude Code, Cursor, and Gemini CLI startup hooks; route detailed files Read On Demand. | Full canonical and decision bodies waste startup tokens. | Always read detailed canonical and decision files first. | Important context is repeatedly missed at startup. | [[startup]], [[index]] |
 | ${workspace_1.today} | Use metadata headers on wiki knowledge pages. | Agents and humans can quickly judge status, scope, budget, and review triggers. | Body-only conventions. | Header maintenance costs more than it saves. | [[meta/operating-model]] |
 | ${workspace_1.today} | Keep wiki operating docs in \`wiki/meta/\`. | Project truth stays focused on product/project content. | Store operating docs in \`canonical/\` or \`decisions/\`. | Meta docs become hard to discover. | [[meta/operating-model]] |
+| ${workspace_1.today} | Split future work into \`roadmaps/\` and \`plans/\`, outside canonical truth. | Roadmaps list broad future scope and sequencing; plans describe detailed execution for one roadmap item; canonical pages should show only the current accepted spec, contract, policy, or operating state. | Store roadmap, improvement, migration, and implementation plans directly in \`canonical/\` as if they were current truth, or mix roadmaps and detailed plans in one directory. | Teams need a different planning directory convention, or plan artifacts become the authoritative source for current behavior. | [[meta/document-taxonomy]], [[meta/operating-model]] |
+| ${workspace_1.today} | Remove completed roadmap and plan content after canonical truth, rationale, and evidence are updated. | Completed future-work documents become stale logs once their outcome is reflected in canonical pages, decisions, and evidence artifacts. | Keep completed roadmap/plan documents indefinitely inside the wiki. | Audit, legal, or release process requires retaining completed plan artifacts in a dedicated external system. | [[meta/document-taxonomy]], [[meta/operating-model]] |
 | ${workspace_1.today} | Bootstrap-generated operating documents are English by default. | Repository entry points and operating contracts are easier for public users to inspect. | Generate operating docs in a fixed non-English language. | The project intentionally targets a single-language local audience. | [[meta/operating-model]] |
 | ${workspace_1.today} | Project canonical content language is chosen from user/project context. | User language and source material should drive project truth, not the bootstrap tool. | Hardcode Korean or English as the canonical content language. | A team requires a fixed language policy. | [[startup]], [[index]] |
 | ${workspace_1.today} | Install git hook files but preserve existing \`core.hooksPath\` values and allow \`--no-git-config\`. | Public users may already have a hook chain such as Husky. | Always replace \`core.hooksPath\`. | Users prefer automatic setup and accept the side effect. | [[meta/operating-model]] |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-librarian",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",
@@ -41,19 +41,25 @@
     "benchmark:ci": "npm run benchmark:ci-smoke",
     "benchmark:ci-smoke": "npm run benchmark:llm:parse-smoke && npm run benchmark:llm:dry-run",
     "benchmark:llm": "npm run build && node benchmarks/codex-llm-metrics.js",
+    "benchmark:llm:delta-analysis": "node benchmarks/tools/analyze-llm-deltas.js",
     "benchmark:llm:dry-run": "npm run build && node benchmarks/codex-llm-metrics.js --dry-run",
     "benchmark:llm:parse-smoke": "node tests/validators/codex-llm-benchmark-smoke.js",
     "benchmark:llm:prune-raw": "node benchmarks/tools/prune-llm-raw.js",
+    "benchmark:llm:raw-audit": "node benchmarks/tools/audit-llm-raw.js",
     "benchmark:injection-sentinel": "node benchmarks/tools/injection-sentinel.js",
+    "benchmark:agent-surface-smoke": "node benchmarks/tools/agent-surface-smoke.js",
     "benchmark:claim-ledger": "node benchmarks/tools/benchmark-claim-ledger.js benchmarks/llm/samples/codex-measured-report.json benchmarks/reports/llm/payload-preview.json",
     "benchmark:real-corpus:demo": "npm run build && node benchmarks/tools/real-corpus-offline-demo.js",
     "benchmark:release:preview": "npm run benchmark:llm -- --payload-preview benchmarks/reports/llm/payload-preview.json --sanitized-pack --full-matrix --runs 3 --warmup-runs 1 --min-runs-for-claim 3 --require-clean --require-claimable --model gpt-5.5",
+    "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",
     "perf:code-efficiency": "node benchmarks/tools/code-performance-efficiency.js --full",
     "release:check": "node benchmarks/tools/release-readiness.js",
     "typecheck": "tsc --noEmit",
+    "typecheck:ts7": "npx --yes -p typescript@rc tsc --noEmit --project tsconfig.json",
     "unit": "node --test tests/unit/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=dist/**/*.js --test-coverage-include=benchmarks/**/*.js --test-coverage-lines=65 --test-coverage-branches=65 --test-coverage-functions=65 tests/unit/*.test.js",
     "test": "npm run build && npm run typecheck && npm run unit && bash tests/smoke.sh",
     "prepack": "npm run build"
   },