project-librarian 0.5.2 → 0.5.4

package/README.ko.md

@@ -63,6 +63,7 @@ npx project-librarian@latest install --scope user --agents all
 - **구조적인 위키 작성.** 새 프로젝트 내용은 작성하거나 취합하기 전에 `wiki/meta/document-taxonomy.md`로 분류하므로 PRD, 정책, UX, 데이터, API, QA, 릴리즈, 운영 메모가 하나의 잡다한 페이지로 합쳐지지 않습니다.
 - **검토 가능한 위키 그래프.** `--wiki-visualize`는 `.project-wiki/` 아래에 독립 실행형 HTML 그래프를 작성해, 시작 컨텍스트를 늘리지 않고 페이지 유형·라우터 깊이·역링크·결정 참조를 보여줍니다.
 - **막연한 표현이 아니라 측정값.** 모든 성능 주장은 격리된 Codex 벤치마크에서 나오며, 손해를 본 경우도 이긴 경우 바로 옆에 보여 줍니다.
+- **로컬 세션 핸드오프.** `--handoff-save`는 `.project-wiki/session/` 아래에 생성형 재개 메모를 저장합니다. 시작 훅은 존재만 알려주므로 실행 로그가 canonical 위키 정본으로 섞이지 않습니다.
 - **선택적 코드 근거.** 재생성 가능한 SQLite 인덱스와 답변 형태 MCP 도구가 영향·소유권·워크스페이스 그래프 질문에 답하며, 추가 런타임 의존성이 전혀 없습니다.
 - **다시 실행해도 안전.** 부트스트랩은 멱등하고 기존 내용 보존을 우선하며, 진단은 깨진 경로·도달 불가 페이지·오래된 사실을 에이전트가 오해하기 전에 잡아냅니다.
 
@@ -80,6 +81,7 @@ Project Librarian은 에이전트에게 두 가지 로컬 정본을 제공합니
 | `.codex/`, `.claude/`, `.cursor/`, `.gemini/` 훅 | 전체 위키를 불러오지 않는 Codex/Claude Code/Cursor/Gemini CLI 시작 컨텍스트. |
 | `GEMINI.md` 및 `.cursor/rules/` | Gemini CLI와 Cursor를 같은 간결한 위키 우선 계약으로 안내하는 지침 파일. |
 | `.project-wiki/code-evidence.sqlite` | 파일, 심볼, import, route, 소유권, 워크스페이스 그래프, 보고서, 영향 확인을 위한 재생성 가능한 코드 근거. |
+| `.project-wiki/session/last-handoff.md` | 마지막 세션의 목표, 상태, 막힘, 다음 액션, 결정, 명령, 검증을 담는 선택적 생성형 로컬 핸드오프입니다. 프로젝트 정본이 아니라 참고 데이터입니다. |
 | `.project-wiki/wiki-graph.html` | 파생 concept type, 라우터 도달성, 링크, 역링크, 결정 참조를 보여주는 선택적 정적 위키 그래프 시각화. |
 | 진단 및 마이그레이션 모드 | 링크 확인, 품질 확인, 마이그레이션 수신함, 오래된 신호 보고, 작업 흐름에서 문제가 드러날 때의 이슈 초안. |
 
@@ -207,6 +209,10 @@ npx project-librarian@latest install --scope project --agents all
 | 페이지의 역링크/결정 인용 확인 | "decisions/release-policy의 Project Librarian 위키 영향도를 보여줘." | `--wiki-impact "decisions/release-policy"` |
 | 위키 그래프 시각화 생성 | "Project Librarian 위키 그래프 시각화를 생성해줘." | `--wiki-visualize` |
 | 후보 메모 저장 | "이 내용을 Project Librarian 후보 메모로 저장해줘: <내용>." | `--capture-inbox --title "Candidate" --content "Details"` |
+| 세션 핸드오프 저장 | "현재 작업을 Project Librarian 세션 핸드오프로 저장해줘." | `--handoff-save --goal "..." --state "..." --next "..."` |
+| 핸드오프에서 재개 | "마지막 Project Librarian 세션 핸드오프를 보여줘." | `--handoff-show` |
+| 핸드오프 후보 승격 | "마지막 Project Librarian 핸드오프를 위키 수신함 후보로 승격해줘." | `--handoff-promote-inbox` |
+| 전체 핸드오프 주입 실험 켜기 | "Project Librarian 전체 핸드오프 주입 실험을 켜줘." | `--handoff-injection-enable` |
 | 오래되었거나 미해결인 위키 페이지 보고 | "Project Librarian에서 오래되었거나 미해결인 페이지를 확인해줘." | `--prune-check` |
 | 신호가 높은 오래되었거나 미해결인 위키 페이지만 보고 | "Project Librarian에서 엄격한 기준으로 오래되었거나 미해결인 페이지를 확인해줘." | `--prune-check --prune-check-strict` |
 | git 설정 변경 없이 훅 파일 설치 | "git 설정은 바꾸지 말고 Project Librarian 훅 파일만 설정해줘." | `--no-git-config` |
@@ -293,7 +299,7 @@ MCP 서버 등록 (`mcpServers`에 기존 항목 보존하며 병합):
 
 `project-librarian mcp`는 직접 구현한 stdio MCP 서버(줄바꿈 구분 JSON 위의 JSON-RPC 2.0, 추가 런타임 의존성 없음)를 실행해 기존 `.project-wiki` 코드 근거 인덱스를 읽기 전용으로 제공합니다. 답변 형태 도구 — `code_context_pack`, `code_impact`, `code_ownership`(CODEOWNERS 마지막 일치 우선순위), `code_workspace_graph`, `code_search`, `code_status` — 를 노출하며, 각 응답은 한 줄 답변으로 시작해 간결한 경로/심볼/시그니처 근거가 뒤따르고, 응답마다 길이를 제한하며, `code_status`가 인덱스가 오래되었다고 보고하면 경고를 앞에 붙입니다.
 
-서버는 고정 리소스 — `project-librarian://wiki/startup`, `project-librarian://wiki/index`, `project-librarian://code/status` — 와 위키 분류 갱신, 코드 영향 추적, 검색 품질 검토용 프롬프트 템플릿도 제공합니다. 리소스 읽기는 임의 파일 경로가 아니라 고정 URI 레지스트리에서만 처리합니다.
+서버는 고정 리소스 — `project-librarian://wiki/startup`, `project-librarian://wiki/index`, `project-librarian://code/status` — 와 위키 분류 갱신, 코드 영향 추적, 유지보수 개선 검토, 검색 품질 검토용 프롬프트 템플릿도 제공합니다. 리소스 읽기는 임의 파일 경로가 아니라 고정 URI 레지스트리에서만 처리합니다.
 
 부트스트랩은 Claude Code(`.mcp.json`), Cursor(`.cursor/mcp.json`), Gemini CLI(`.gemini/settings.json`의 `mcpServers`)에 서버를 등록하며, 기존 서버와 키를 보존하고 다시 실행하면 `exists`를 보고합니다. 저장소에 로컬 실행 경로가 있으면 `node <runner> mcp`로, 없으면 설치된 `project-librarian mcp` 바이너리로 등록합니다.
 
@@ -383,6 +389,10 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `--wiki-visualize-out <path>` | `--wiki-visualize`와 함께 사용해 `.project-wiki/` 아래의 사용자 지정 저장소 상대 경로에 작성합니다. |
 | `--refresh-index` | 생성된 자동 발견 위키 라우팅을 갱신합니다. |
 | `--capture-inbox --title <title> --content <content>` | 위키 수신함에 후보 메모를 추가합니다. |
+| `--handoff-save --goal <goal> --state <state> --next <action>` | `.project-wiki/session/` 아래에 생성형 로컬 세션 핸드오프를 저장합니다. 필요하면 `--next`, `--decision`, `--blocked`, `--open-question`, `--verification`을 반복합니다. |
+| `--handoff-show`, `--handoff-status`, `--handoff-clear` | 생성된 세션 핸드오프를 출력, 점검, 삭제합니다. 시작 훅은 핸드오프 존재만 알리고 기본적으로 전체 파일을 주입하지 않습니다. |
+| `--handoff-promote-inbox` | 생성된 핸드오프의 선별된 사실만 `wiki/inbox/project-candidates.md`에 pending 후보로 추가합니다. canonical, plan, decision 문서는 쓰지 않습니다. |
+| `--handoff-injection-enable`, `--handoff-injection-disable`, `--handoff-injection-status` | 2,500자 상한의 전체 핸드오프 주입 실험을 켜고, 끄고, 상태를 확인합니다. 기본 시작 동작은 계속 pointer-only입니다. |
 | `--issue-draft --issue-title <title>` | 문제 또는 부작용에 대한 읽기 전용 GitHub 이슈 본문 초안을 출력합니다. |
 | `--issue-create --issue-title <title>` | 명시적 사용자 승인 후 `gh`로 GitHub 이슈를 생성합니다. |
 | `--glossary-init` | 선택적 용어집 페이지를 만들고 라우팅합니다. |
@@ -407,6 +417,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 npm install
 npm run typecheck
 npm run build
+npm run check:dist
 npm test
 npm run test:coverage
 npm run benchmark:llm:raw-audit
@@ -416,11 +427,11 @@ npm run release:check
 npm pack --dry-run
 ```
 
-`src/` 아래 TypeScript를 수정할 때는 커밋 전에 빌드해 `dist/`를 최신 상태로 유지하세요.
+`src/` 아래 TypeScript를 수정할 때는 커밋 전에 빌드해 `dist/`를 최신 상태로 유지하세요. `npm run check:dist`는 체크인된 생성 파일이 최신 빌드 출력과 일치하는지 확인합니다.
 
 `npm run test:coverage`는 Node 내장 test coverage에 보수적인 line, branch, function threshold를 적용하므로 coverage를 단순 보고서가 아니라 회귀 게이트로 사용합니다.
 
-`npm run release:check`는 로컬 전용 관리자 게이트입니다. 테스트, Node 내장 coverage, 벤치마크 파서 smoke, real-corpus 오프라인 데모, 벤치마크 release preview, 벤치마크 claim ledger 분류, raw 보관 상태 감사, package dry-run 검사, dist 실행 가능 여부, README 벤치마크 claim 경계 문구를 확인합니다. publish하지 않고 raw 벤치마크 산출물을 삭제하지 않으며 measured Codex 벤치마크도 실행하지 않습니다.
+`npm run release:check`는 로컬 전용 관리자 게이트입니다. 테스트, Node 내장 coverage, 벤치마크 파서 smoke, real-corpus 오프라인 데모, 벤치마크 release preview, 벤치마크 claim ledger 분류, raw 보관 상태 감사, package dry-run 검사, dist 실행 가능 여부와 소스 동기화, README 벤치마크 claim 경계 문구를 확인합니다. publish하지 않고 raw 벤치마크 산출물을 삭제하지 않으며 measured Codex 벤치마크도 실행하지 않습니다.
 
 `release:check` 통과는 런타임 보증이 아니라 재현 가능한 릴리스 준비 근거로 봐야 합니다. 현재 checkout에서 위 로컬 게이트를 통과했음을 증명하며, package dry run이 예상 publish 경계(`agents/`, `dist/`, `LICENSE`, `README.md`, `README.ko.md`, `SKILL.md`) 안에 머물고 소스 파일, 테스트, 저장소 로컬 위키/워크플로 상태, raw 벤치마크 출력, 로컬 캐시를 제외하는지도 확인합니다.
 

package/README.md

@@ -63,6 +63,7 @@ npx project-librarian@latest install --scope user --agents all
 - **Structured wiki writing.** New project content is classified through `wiki/meta/document-taxonomy.md` before it is written or consolidated, so PRDs, policies, UX, data, APIs, QA, release, and operations notes do not collapse into one catch-all page.
 - **Inspectable wiki graph.** `--wiki-visualize` writes a self-contained HTML graph under `.project-wiki/`, showing page types, router depth, backlinks, and decision references without adding to startup context.
 - **Measured, not hand-wavy.** Every performance claim comes from hermetic Codex benchmarks — and the cases where it costs *more* are shown right next to the wins.
+- **Local session handoff.** `--handoff-save` writes generated resume notes under `.project-wiki/session/`; startup hooks only point to it, so rolling execution memory does not become canonical wiki truth.
 - **Optional code evidence.** A regenerable SQLite index plus answer-shaped MCP tools answer impact, ownership, and workspace-graph questions, with zero extra runtime dependencies.
 - **Safe to re-run.** Bootstrap is idempotent and preservation-first; diagnostics flag broken routes, unreachable pages, and stale truth before they mislead an agent.
 
@@ -80,6 +81,7 @@ Project Librarian gives agents two local sources of truth:
 | `.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. |
 | `.project-wiki/code-evidence.sqlite` | Regenerable code evidence for files, symbols, imports, routes, ownership, workspace graph, reports, and impact checks. |
+| `.project-wiki/session/last-handoff.md` | Optional generated local handoff for the last session's goal, state, blockers, next actions, decisions, commands, and verification. It is reference data, not project truth. |
 | `.project-wiki/wiki-graph.html` | Optional static wiki graph visualizer with derived concept types, router reachability, links, backlinks, and decision references. |
 | Diagnostics and migration modes | Link checks, quality checks, migration inboxes, stale-signal reports, and issue drafts when the workflow exposes a problem. |
 
@@ -207,6 +209,10 @@ Wiki setup and maintenance:
 | Show backlinks and decision citations for a page | "Show Project Librarian wiki impact for decisions/release-policy." | `--wiki-impact "decisions/release-policy"` |
 | Generate a wiki graph visualizer | "Generate the Project Librarian wiki graph visualizer." | `--wiki-visualize` |
 | Capture a candidate note | "Capture this as a Project Librarian candidate note: <details>." | `--capture-inbox --title "Candidate" --content "Details"` |
+| Save a session handoff | "Save a Project Librarian session handoff for the current work." | `--handoff-save --goal "..." --state "..." --next "..."` |
+| Resume from a handoff | "Show the last Project Librarian session handoff." | `--handoff-show` |
+| Promote handoff candidates | "Promote the last Project Librarian handoff to the wiki inbox." | `--handoff-promote-inbox` |
+| Opt in to full handoff injection | "Enable the Project Librarian full handoff injection experiment." | `--handoff-injection-enable` |
 | Report stale or unresolved wiki pages | "Check Project Librarian for stale or unresolved pages." | `--prune-check` |
 | Report only higher-signal stale or unresolved wiki pages | "Check Project Librarian for strict stale or unresolved pages." | `--prune-check --prune-check-strict` |
 | Install hook files without changing git config | "Set up Project Librarian hook files without changing git config." | `--no-git-config` |
@@ -293,7 +299,7 @@ Disposable code evidence cache:
 
 `project-librarian mcp` runs a hand-rolled stdio MCP server (JSON-RPC 2.0 over newline-delimited JSON, no extra runtime dependencies) that serves the existing `.project-wiki` code-evidence index read-only. It exposes answer-shaped tools — `code_context_pack`, `code_impact`, `code_ownership` (CODEOWNERS last-match precedence), `code_workspace_graph`, `code_search`, and `code_status` — whose responses lead with a one-line answer, follow with compact path/symbol/signature evidence, cap each reply, and prepend a warning when `code_status` reports the index is stale.
 
-The server also exposes fixed resources — `project-librarian://wiki/startup`, `project-librarian://wiki/index`, and `project-librarian://code/status` — plus prompt templates for wiki taxonomy updates, code impact traces, and retrieval quality reviews. Resource reads come from a fixed URI registry rather than arbitrary filesystem paths.
+The server also exposes fixed resources — `project-librarian://wiki/startup`, `project-librarian://wiki/index`, and `project-librarian://code/status` — plus prompt templates for wiki taxonomy updates, code impact traces, maintenance improvement reviews, and retrieval quality reviews. Resource reads come from a fixed URI registry rather than arbitrary filesystem paths.
 
 Bootstrap registers the server for Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`), and Gemini CLI (`mcpServers` in `.gemini/settings.json`), preserving any existing servers and keys and reporting `exists` on a re-run. When the repository contains a local runner the registration uses `node <runner> mcp`; otherwise it uses the installed `project-librarian mcp` binary.
 
@@ -383,6 +389,10 @@ Important options:
 | `--wiki-visualize-out <path>` | With `--wiki-visualize`, write to a custom repository-relative path under `.project-wiki/`. |
 | `--refresh-index` | Update generated auto-discovered wiki routing. |
 | `--capture-inbox --title <title> --content <content>` | Append a candidate note to the wiki inbox. |
+| `--handoff-save --goal <goal> --state <state> --next <action>` | Save generated local session handoff state under `.project-wiki/session/`. Repeat `--next`, `--decision`, `--blocked`, `--open-question`, and `--verification` as needed. |
+| `--handoff-show`, `--handoff-status`, `--handoff-clear` | Print, inspect, or remove generated session handoff state. Startup hooks mention the handoff when it exists but do not inject the full file by default. |
+| `--handoff-promote-inbox` | Append selected generated handoff facts to `wiki/inbox/project-candidates.md` as a pending candidate. It does not write canonical, plan, or decision pages. |
+| `--handoff-injection-enable`, `--handoff-injection-disable`, `--handoff-injection-status` | Opt in, opt out, or inspect the capped full handoff injection experiment. Default startup behavior remains pointer-only. |
 | `--issue-draft --issue-title <title>` | Print a read-only GitHub issue body draft for problems or side effects. |
 | `--issue-create --issue-title <title>` | Create a GitHub issue through `gh` after explicit user approval. |
 | `--glossary-init` | Create and route the optional glossary page. |
@@ -407,6 +417,7 @@ The source is TypeScript. The committed `dist/` directory is the compiled JavaSc
 npm install
 npm run typecheck
 npm run build
+npm run check:dist
 npm test
 npm run test:coverage
 npm run benchmark:llm:raw-audit
@@ -416,11 +427,11 @@ npm run release:check
 npm pack --dry-run
 ```
 
-When editing TypeScript under `src/`, rebuild before committing so `dist/` stays current.
+When editing TypeScript under `src/`, rebuild before committing so `dist/` stays current. `npm run check:dist` verifies that the checked-in generated files still match the latest build output.
 
 `npm run test:coverage` uses Node's native test coverage with conservative line, branch, and function thresholds so coverage is a regression gate, not only a report.
 
-`npm run release:check` is a local-only maintainer gate: it runs tests, native Node coverage, benchmark parser smoke, the real-corpus offline demo, benchmark release preview, benchmark claim-ledger classification, raw hygiene audit, package dry-run inspection, dist executable checks, and README benchmark-claim boundary checks. It never publishes, never deletes raw benchmark artifacts, and never launches a measured Codex benchmark.
+`npm run release:check` is a local-only maintainer gate: it runs tests, native Node coverage, benchmark parser smoke, the real-corpus offline demo, benchmark release preview, benchmark claim-ledger classification, raw hygiene audit, package dry-run inspection, dist executable/parity checks, and README benchmark-claim boundary checks. It never publishes, never deletes raw benchmark artifacts, and never launches a measured Codex benchmark.
 
 Treat a green `release:check` as a reproducible release-readiness bundle, not a runtime guarantee: it proves those local gates on the current checkout, including that the package dry run stays inside the expected publish boundary (`agents/`, `dist/`, `LICENSE`, `README.md`, `README.ko.md`, and `SKILL.md`) and excludes source files, tests, repo-local wiki/workflow state, raw benchmark output, and local caches.
 

package/SKILL.md

@@ -19,9 +19,11 @@ Supported actions:
 - Search project wiki content.
 - Refresh the wiki index.
 - Capture a candidate note into the wiki inbox.
+- Save, show, inspect, promote, inject, or clear generated local session handoff state under `.project-wiki/session/`.
 - Check for pending, stale, proposed, or undecided wiki pages.
 - Draft a GitHub issue body for problems or side effects found while using the skill.
 - Initialize a project glossary.
+- Turn broad maintenance, automation, efficiency, or "improve this project" requests into an analyze-first backlog and execution plan before editing.
 - Analyze existing code and canonicalize code-backed project behavior, features, policies, constraints, terminology, domain rules, and open questions into the wiki.
 - Build and query an optional SQLite code evidence index for large repositories.
 - Migrate an existing wiki/docs structure.
@@ -48,6 +50,16 @@ Use `npx` or `npm exec` only when no local runner exists and registry access is
 
 If the resolved runner fails, report the real error and stop or fix the cause. Do not manually recreate bootstrap or migration output as a fallback.
 
+Broad improvement automation requests are discovery-and-execution work, not routine bootstrap updates. When the user says something like "improve this project", "start improvement automation", "개선 자동화 시작해", or asks for maintainability/automation/efficiency improvements without naming a concrete lifecycle flag:
+
+- Do not map the request directly to `$PROJECT_LIBRARIAN update` or a single diagnostic command.
+- Inspect the repo's wiki contract, code structure, package scripts, CI, tests, release gates, generated surfaces, dependency posture, and obvious maintenance bottlenecks.
+- Use code-evidence tools or reports when the repo is large or the question is structural; use direct targeted reads for small repos and simple lookups.
+- Produce a ranked backlog with file/command evidence, confidence, expected verification, and risk.
+- Persist durable planning output under `wiki/plans/` when the request changes project-planning state, then refresh the index and run lint when practical.
+- If the user asked to start or continue work, implement safe high-priority items in a branch, update generated outputs, and verify with targeted tests plus the smallest broad gate that proves the claim.
+- Keep unresolved, high-risk, or dependency-changing candidates in the backlog instead of silently skipping them.
+
 2. For project bootstrap requests, choose the matching command and run it from the project root. The examples below use `$PROJECT_LIBRARIAN` to mean the resolved runner from step 1:
 
 ```bash
@@ -79,6 +91,12 @@ Map lifecycle requests to these internal operations:
 - Search the wiki: `$PROJECT_LIBRARIAN --query "search terms"`.
 - Refresh wiki routing/index: `$PROJECT_LIBRARIAN --refresh-index`.
 - Capture a project candidate: `$PROJECT_LIBRARIAN --capture-inbox --title "Candidate title" --content "Candidate content"`.
+- Save generated session handoff state: `$PROJECT_LIBRARIAN --handoff-save --goal "Goal" --state "Current state" --next "Next action"`.
+- Show the last generated session handoff: `$PROJECT_LIBRARIAN --handoff-show`.
+- Inspect generated session handoff status: `$PROJECT_LIBRARIAN --handoff-status`.
+- Clear generated session handoff state: `$PROJECT_LIBRARIAN --handoff-clear`.
+- Promote selected generated handoff facts to the wiki inbox: `$PROJECT_LIBRARIAN --handoff-promote-inbox`.
+- Enable, disable, or inspect the capped full handoff injection experiment: `$PROJECT_LIBRARIAN --handoff-injection-enable`, `$PROJECT_LIBRARIAN --handoff-injection-disable`, or `$PROJECT_LIBRARIAN --handoff-injection-status`.
 - Check stale/pending pages: `$PROJECT_LIBRARIAN --prune-check`.
 - Draft a GitHub issue body for a skill problem or side effect: `$PROJECT_LIBRARIAN --issue-draft --issue-title "Issue title"`.
 - After explicit user approval in a GitHub-backed repository, create the issue through GitHub CLI: `$PROJECT_LIBRARIAN --issue-create --issue-title "Issue title"`.
@@ -121,7 +139,9 @@ Use `--lint` for read-only validation:
 $PROJECT_LIBRARIAN --lint
 ```
 
-Use `--query`, `--prune-check`, `--issue-draft`, `--link-check`, `--quality-check`, `--doctor`, `--migration-lint`, `--migration-quality-check`, and `--migration-doctor` for read-only inspection/output through the resolved runner. Use `--doctor --fix` when safe generated routing refresh is intended. Use `--refresh-index`, `--capture-inbox`, `--glossary-init`, and `--migrate` only when updating wiki files is intended.
+Use `--query`, `--handoff-show`, `--handoff-status`, `--prune-check`, `--issue-draft`, `--link-check`, `--quality-check`, `--doctor`, `--migration-lint`, `--migration-quality-check`, and `--migration-doctor` for read-only inspection/output through the resolved runner. Use `--doctor --fix` when safe generated routing refresh is intended. Use `--refresh-index`, `--capture-inbox`, `--handoff-save`, `--handoff-clear`, `--glossary-init`, and `--migrate` only when updating local project-librarian files is intended.
+
+Session handoff files are generated local reference data, not canonical wiki truth. Do not promote handoff content into `wiki/canonical/`, `wiki/plans/`, or `wiki/decisions/` automatically; capture stable project-planning facts through the inbox/taxonomy workflow first.
 
 Use `--review-migration` or `--semantic-migrate` after migration coverage or compatible inbox rows are processed. It syncs unit coverage and safe file-level inbox statuses into `wiki/migration/review.md` and `wiki/migration/verification.md`.
 
@@ -309,6 +329,10 @@ These modes preserve this project's stricter source-of-truth boundaries:
 - `--issue-draft --issue-title "..."`: read-only Markdown problem-report draft for skill failures, side effects, confusing behavior, or generated-file surprises. It does not create a GitHub issue or require network access.
 - `--refresh-index`: updates a managed auto-discovered block in `wiki/index.md` for wiki files not routed by the hand-written index.
 - `--capture-inbox --title "..." --content "..."`: appends a project-candidate row to `wiki/inbox/project-candidates.md` and routes the inbox from `wiki/index.md`.
+- `--handoff-save --goal "..." --state "..." --next "..."`: writes generated local resume context under `.project-wiki/session/`; repeat `--next`, `--decision`, `--blocked`, `--open-question`, and `--verification` as needed.
+- `--handoff-show`, `--handoff-status`, `--handoff-clear`: print, inspect, or remove generated handoff state. Startup hooks only mention that a handoff exists; they do not inject the full handoff by default.
+- `--handoff-promote-inbox`: appends selected generated handoff facts to `wiki/inbox/project-candidates.md` as pending candidate material. It does not write canonical, plan, or decision pages.
+- `--handoff-injection-enable`, `--handoff-injection-disable`, `--handoff-injection-status`: opt in, opt out, or inspect the capped full handoff injection experiment. Keep it off by default unless measured resume behavior justifies the added startup context.
 - `--prune-check`: read-only report of active wiki pages with pending/proposed/stale review signals.
 
 Captured inbox entries are not canonical. Fold them into `wiki/canonical/`, `wiki/decisions/`, `wiki/sources/`, or `wiki/meta/` only after review.

package/dist/args.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.pruneCheckStrictMode = 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 = exports.codeQuerySql = void 0;
+exports.codeIndexMode = exports.acknowledgeSmallRepoMode = exports.noGitConfigMode = exports.reviewMigrationMode = exports.pruneCheckStrictMode = exports.pruneCheckMode = exports.captureInboxMode = exports.refreshIndexMode = exports.issueDraftMode = exports.issueCreateMode = exports.handoffVerification = exports.handoffStatusMode = exports.handoffState = exports.handoffShowMode = exports.handoffSaveMode = exports.handoffPromoteInboxMode = exports.handoffInjectionStatusMode = exports.handoffInjectionEnableMode = exports.handoffInjectionDisableMode = exports.handoffOpenQuestions = exports.handoffNextActions = exports.handoffLastSuccessCommand = exports.handoffLastFailureCommand = exports.handoffInputMode = exports.handoffGoal = exports.handoffDecisions = exports.handoffClearMode = exports.handoffBlocked = 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 = 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 = void 0;
 exports.parseArgs = parseArgs;
 exports.argValue = argValue;
 exports.argValues = argValues;
@@ -34,6 +34,23 @@ const flagDefinitions = [
     { name: "--dry-run", value: "none" },
     { name: "--fix", value: "none" },
     { name: "--glossary-init", value: "none" },
+    { name: "--blocked", value: "value" },
+    { name: "--decision", value: "value" },
+    { name: "--goal", value: "value" },
+    { name: "--handoff-clear", value: "none" },
+    { name: "--handoff-injection-disable", value: "none" },
+    { name: "--handoff-injection-enable", value: "none" },
+    { name: "--handoff-injection-status", value: "none" },
+    { name: "--handoff-promote-inbox", value: "none" },
+    { name: "--handoff-save", value: "none" },
+    { name: "--handoff-show", value: "none" },
+    { name: "--handoff-status", value: "none" },
+    { name: "--last-failure-command", value: "value" },
+    { name: "--last-success-command", value: "value" },
+    { name: "--next", value: "value" },
+    { name: "--open-question", value: "value" },
+    { name: "--state", value: "value" },
+    { name: "--verification", value: "value" },
     { name: "--issue-body-file", value: "value" },
     { name: "--issue-create", value: "none" },
     { name: "--issue-draft", value: "none" },
@@ -138,6 +155,17 @@ function parseArgs(argv) {
     const codeQuerySql = argValueFromAny("--code-query");
     const codeSearchSymbol = argValueFromAny("--code-search-symbol");
     const parsedAgentTargets = (0, agent_surfaces_1.parseAgentSurfaceValues)(argValues("--agents"));
+    const handoffInputMode = [
+        "--blocked",
+        "--decision",
+        "--goal",
+        "--last-failure-command",
+        "--last-success-command",
+        "--next",
+        "--open-question",
+        "--state",
+        "--verification",
+    ].some(hasFlag);
     return {
         acknowledgeSmallRepoMode: args.has("--acknowledge-small-repo"),
         agentTargets: parsedAgentTargets.surfaces,
@@ -172,6 +200,24 @@ function parseArgs(argv) {
         fixMode: args.has("--fix"),
         glossaryMode: args.has("--glossary-init"),
         helpMode: argv.includes("--help") || argv.includes("-h"),
+        handoffBlocked: argValues("--blocked"),
+        handoffClearMode: args.has("--handoff-clear"),
+        handoffDecisions: argValues("--decision"),
+        handoffGoal: argValue("--goal"),
+        handoffInputMode,
+        handoffLastFailureCommand: argValue("--last-failure-command"),
+        handoffLastSuccessCommand: argValue("--last-success-command"),
+        handoffNextActions: argValues("--next"),
+        handoffOpenQuestions: argValues("--open-question"),
+        handoffInjectionDisableMode: args.has("--handoff-injection-disable"),
+        handoffInjectionEnableMode: args.has("--handoff-injection-enable"),
+        handoffInjectionStatusMode: args.has("--handoff-injection-status"),
+        handoffPromoteInboxMode: args.has("--handoff-promote-inbox"),
+        handoffSaveMode: args.has("--handoff-save"),
+        handoffShowMode: args.has("--handoff-show"),
+        handoffState: argValue("--state"),
+        handoffStatusMode: args.has("--handoff-status"),
+        handoffVerification: argValues("--verification"),
         issueBodyFile: argValue("--issue-body-file"),
         issueCreateMode: args.has("--issue-create"),
         issueDraftMode: args.has("--issue-draft"),
@@ -228,6 +274,24 @@ exports.qualityCheckMode = exports.parsedArgs.qualityCheckMode;
 exports.doctorMode = exports.parsedArgs.doctorMode;
 exports.fixMode = exports.parsedArgs.fixMode;
 exports.glossaryMode = exports.parsedArgs.glossaryMode;
+exports.handoffBlocked = exports.parsedArgs.handoffBlocked;
+exports.handoffClearMode = exports.parsedArgs.handoffClearMode;
+exports.handoffDecisions = exports.parsedArgs.handoffDecisions;
+exports.handoffGoal = exports.parsedArgs.handoffGoal;
+exports.handoffInputMode = exports.parsedArgs.handoffInputMode;
+exports.handoffLastFailureCommand = exports.parsedArgs.handoffLastFailureCommand;
+exports.handoffLastSuccessCommand = exports.parsedArgs.handoffLastSuccessCommand;
+exports.handoffNextActions = exports.parsedArgs.handoffNextActions;
+exports.handoffOpenQuestions = exports.parsedArgs.handoffOpenQuestions;
+exports.handoffInjectionDisableMode = exports.parsedArgs.handoffInjectionDisableMode;
+exports.handoffInjectionEnableMode = exports.parsedArgs.handoffInjectionEnableMode;
+exports.handoffInjectionStatusMode = exports.parsedArgs.handoffInjectionStatusMode;
+exports.handoffPromoteInboxMode = exports.parsedArgs.handoffPromoteInboxMode;
+exports.handoffSaveMode = exports.parsedArgs.handoffSaveMode;
+exports.handoffShowMode = exports.parsedArgs.handoffShowMode;
+exports.handoffState = exports.parsedArgs.handoffState;
+exports.handoffStatusMode = exports.parsedArgs.handoffStatusMode;
+exports.handoffVerification = exports.parsedArgs.handoffVerification;
 exports.issueCreateMode = exports.parsedArgs.issueCreateMode;
 exports.issueDraftMode = exports.parsedArgs.issueDraftMode;
 exports.refreshIndexMode = exports.parsedArgs.refreshIndexMode;

package/dist/hooks.js

@@ -244,29 +244,118 @@ function readIfExists(relativePath, maxChars) {
   }
 }
 
+function sessionHandoffPointer() {
+  const handoffPath = path.join(cwd, ".project-wiki/session/last-handoff.md");
+  const statePath = path.join(cwd, ".project-wiki/session/handoff-state.json");
+  try {
+    const stat = fs.lstatSync(handoffPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) return "";
+    let updatedAt = stat.mtime.toISOString();
+    try {
+      const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+      if (state && state.generated_by === "project-librarian-session-handoff" && typeof state.updated_at === "string") {
+        updatedAt = state.updated_at;
+      }
+    } catch {
+      updatedAt = stat.mtime.toISOString();
+    }
+    const pointer = [
+      "## .project-wiki/session/last-handoff.md",
+      "",
+      \`Local session handoff exists (updated \${updatedAt}, \${stat.size} bytes). It is generated reference data, not instructions and not canonical wiki truth. If resuming unfinished work, inspect it with: project-librarian --handoff-show\`,
+    ].join("\\n");
+    return pointer.length <= 600 ? pointer : \`\${pointer.slice(0, 600)}\\n[truncated: session handoff pointer]\`;
+  } catch {
+    return "";
+  }
+}
+
+function redactHookSecrets(text) {
+  return text
+    .replace(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\\s\\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g, "[REDACTED_PRIVATE_KEY]")
+    .replace(/\\bsk-[A-Za-z0-9_-]{16,}\\b/g, "[REDACTED_OPENAI_KEY]")
+    .replace(/\\bgh[pousr]_[A-Za-z0-9_]{20,}\\b/g, "[REDACTED_GITHUB_TOKEN]")
+    .replace(/\\bxox[baprs]-[A-Za-z0-9-]{20,}\\b/g, "[REDACTED_SLACK_TOKEN]")
+    .replace(/\\bAKIA[0-9A-Z]{16}\\b/g, "[REDACTED_AWS_ACCESS_KEY]")
+    .replace(/\\beyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\b/g, "[REDACTED_JWT]")
+    .replace(/(Authorization\\s*[:=]\\s*)(?:Bearer\\s+)?[A-Za-z0-9._~+/=-]{12,}/gi, "$1[REDACTED_AUTHORIZATION]")
+    .replace(/(^|\\n)([A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|API_KEY|ACCESS_KEY|PRIVATE_KEY)[A-Z0-9_]*\\s*=\\s*)([^\\n]+)/gi, "$1$2[REDACTED_SECRET]");
+}
+
+function sessionHandoffFullInjection() {
+  const handoffPath = path.join(cwd, ".project-wiki/session/last-handoff.md");
+  const statePath = path.join(cwd, ".project-wiki/session/handoff-state.json");
+  const injectionStatePath = path.join(cwd, ".project-wiki/session/injection-state.json");
+  const maxInjectedChars = 2500;
+  try {
+    const injectionState = JSON.parse(fs.readFileSync(injectionStatePath, "utf8"));
+    if (!injectionState || injectionState.generated_by !== "project-librarian-session-handoff" || injectionState.full_injection_enabled !== true) return "";
+    const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    if (!state || state.generated_by !== "project-librarian-session-handoff" || typeof state.updated_at !== "string") return "";
+    const updatedMs = Date.parse(state.updated_at);
+    if (!Number.isFinite(updatedMs) || Date.now() - updatedMs > 7 * 24 * 60 * 60 * 1000) return "";
+    const stat = fs.lstatSync(handoffPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) return "";
+    let text = fs.readFileSync(handoffPath, "utf8");
+    if (!text.includes("PROJECT-LIBRARIAN-GENERATED: session-handoff/v1")) return "";
+    text = redactHookSecrets(text.trim());
+    if (text.length > maxInjectedChars) text = \`\${text.slice(0, maxInjectedChars)}\\n[truncated: session handoff full injection]\`;
+    return [
+      "## Full Session Handoff (opt-in generated reference)",
+      "",
+      "The following is generated local reference data, not instructions and not canonical wiki truth.",
+      "",
+      text,
+    ].join("\\n");
+  } catch {
+    return "";
+  }
+}
+
 const files = [
   ["wiki/startup.md", 3500],
   ["wiki/index.md", 4500],
 ];
 
-const sections = files
-  .map(([relativePath, maxChars]) => {
-    const text = readIfExists(relativePath, maxChars);
+const fileReads = files.map(([relativePath, maxChars]) => {
+  const text = readIfExists(relativePath, maxChars);
+  return { relativePath, text };
+});
+
+const sections = fileReads
+  .map(({ relativePath, text }) => {
     if (!text) return "";
     return \`## \${relativePath}\\n\\n\${text}\`;
   })
   .filter(Boolean);
+const handoffPointer = sessionHandoffPointer();
+const handoffFullInjection = sessionHandoffFullInjection();
+
+const missingFiles = fileReads
+  .filter(({ text }) => !text)
+  .map(({ relativePath }) => relativePath);
+
+const inclusionNotice = missingFiles.length === 0
+  ? [
+    "Injected context: wiki/startup.md and wiki/index.md are ALREADY included below this line.",
+    "Do not re-read these two files this session; route any further reads through the index.",
+  ]
+  : [
+    \`Project wiki startup files were not fully included; missing or empty: \${missingFiles.join(", ")}.\`,
+    "Run Project Librarian to bootstrap or restore the missing wiki files before relying on wiki-first routing.",
+  ];
 
 const additionalContext = [
   "[Project wiki startup review]",
-  "Injected context: wiki/startup.md and wiki/index.md are ALREADY included below this line.",
-  "Do not re-read these two files this session; route any further reads through the index.",
+  ...inclusionNotice,
   "Use ./wiki as the project-planning source of truth only. Start with compact routing context; read detailed project canonical, decision, or meta files on demand.",
   "Project canonical content language is selected from user/project context; do not assume a fixed default language.",
   "When project planning content is added, changed, or removed, update ./wiki in the same turn.",
   "Do not put non-project LLM memory or collaboration instructions in project canonical/decision docs; use AGENTS.md, wiki/AGENTS.md, hooks, or skills.",
   "",
   ...sections,
+  handoffPointer,
+  handoffFullInjection,
 ].join("\\n");
 
 process.stdout.write(JSON.stringify({

package/dist/init-project-wiki.js

@@ -7,6 +7,7 @@ const hooks_1 = require("./hooks");
 const install_skill_1 = require("./install-skill");
 const modes_1 = require("./modes");
 const migration_1 = require("./migration");
+const session_handoff_1 = require("./session-handoff");
 const templates_1 = require("./templates");
 const wiki_visualizer_1 = require("./wiki-visualizer");
 const workspace_1 = require("./workspace");
@@ -39,6 +40,16 @@ Options:
   --wiki-visualize-out <path>      With --wiki-visualize, write under a custom .project-wiki/ path.
   --refresh-index                  Update the managed auto-discovered wiki index block.
   --capture-inbox                  Append a candidate note with --title, --content, and optional --category.
+  --handoff-save                   Save local generated session handoff state under .project-wiki/session/.
+  --handoff-show                   Print the current local session handoff.
+  --handoff-status                 Print JSON status for the local session handoff.
+  --handoff-clear                  Remove generated session handoff files.
+  --handoff-promote-inbox          Promote selected generated handoff facts into wiki/inbox/project-candidates.md.
+  --handoff-injection-enable       Opt in to capped full handoff injection in startup hooks.
+  --handoff-injection-disable      Remove the generated full handoff injection opt-in.
+  --handoff-injection-status       Print JSON status for the full handoff injection experiment.
+  --goal, --state, --blocked       With --handoff-save, provide resume context fields.
+  --next, --decision               With --handoff-save, repeat for next actions and decisions.
   --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.
@@ -161,6 +172,24 @@ if (args_1.codeIndexIncrementalMode && args_1.codeIndexFullMode) {
     console.error("Use one code index update mode at a time: --incremental or --code-index-full.");
     process.exit(1);
 }
+const activeHandoffModes = [
+    args_1.handoffSaveMode ? "--handoff-save" : "",
+    args_1.handoffShowMode ? "--handoff-show" : "",
+    args_1.handoffStatusMode ? "--handoff-status" : "",
+    args_1.handoffClearMode ? "--handoff-clear" : "",
+    args_1.handoffPromoteInboxMode ? "--handoff-promote-inbox" : "",
+    args_1.handoffInjectionEnableMode ? "--handoff-injection-enable" : "",
+    args_1.handoffInjectionDisableMode ? "--handoff-injection-disable" : "",
+    args_1.handoffInjectionStatusMode ? "--handoff-injection-status" : "",
+].filter(Boolean);
+if (activeHandoffModes.length > 1) {
+    console.error(`Use one session handoff mode at a time: ${activeHandoffModes.join(", ")}.`);
+    process.exit(1);
+}
+if (args_1.handoffInputMode && !args_1.handoffSaveMode) {
+    console.error("--goal, --state, --blocked, --next, --decision, --open-question, --last-success-command, --last-failure-command, and --verification are only supported with --handoff-save.");
+    process.exit(1);
+}
 if (args_1.command === "install" || args_1.command === "install-skill") {
     (0, install_skill_1.runInstallSkillMode)();
     process.exit(0);
@@ -176,6 +205,33 @@ else {
     runInitCommand();
 }
 function runInitCommand() {
+    const activeHandoffMode = activeHandoffModes[0];
+    if (activeHandoffMode) {
+        try {
+            if (args_1.handoffSaveMode)
+                (0, session_handoff_1.runHandoffSaveMode)();
+            else if (args_1.handoffShowMode)
+                (0, session_handoff_1.runHandoffShowMode)();
+            else if (args_1.handoffStatusMode)
+                (0, session_handoff_1.runHandoffStatusMode)();
+            else if (args_1.handoffClearMode)
+                (0, session_handoff_1.runHandoffClearMode)();
+            else if (args_1.handoffPromoteInboxMode)
+                (0, session_handoff_1.runHandoffPromoteInboxMode)();
+            else if (args_1.handoffInjectionEnableMode)
+                (0, session_handoff_1.runHandoffInjectionEnableMode)();
+            else if (args_1.handoffInjectionDisableMode)
+                (0, session_handoff_1.runHandoffInjectionDisableMode)();
+            else if (args_1.handoffInjectionStatusMode)
+                (0, session_handoff_1.runHandoffInjectionStatusMode)();
+            exitAfterStdoutDrain(0);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        return;
+    }
     const activeCodeModes = activeCodeEvidenceCliModes();
     if (activeCodeModes.length > 1) {
         console.error("Use one code evidence mode at a time: --code-index, --code-index-health, --code-query, --code-report, --code-status, --code-files, --code-impact, --code-context-pack, or --code-search-symbol.");

package/dist/mcp-server.js

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

package/dist/modes.js

@@ -37,6 +37,7 @@ exports.buildRefreshIndexBlock = buildRefreshIndexBlock;
 exports.runQueryMode = runQueryMode;
 exports.runWikiImpactMode = runWikiImpactMode;
 exports.projectCandidatesContent = projectCandidatesContent;
+exports.appendProjectCandidate = appendProjectCandidate;
 exports.appendCaptureInbox = appendCaptureInbox;
 exports.runIssueDraftMode = runIssueDraftMode;
 exports.runIssueCreateMode = runIssueCreateMode;
@@ -338,23 +339,29 @@ function projectCandidatesContent() {
 | --- | --- | --- | --- | --- |
 `;
 }
-function appendCaptureInbox() {
+function appendProjectCandidate(input = {}) {
     (0, workspace_1.mkdirp)("wiki/inbox");
     const relativePath = "wiki/inbox/project-candidates.md";
     const existed = (0, workspace_1.exists)(relativePath);
     if (!existed)
         (0, workspace_1.write)(relativePath, projectCandidatesContent());
-    if (!args_1.captureTitle && !args_1.captureContent)
+    const candidateTitle = input.title ?? args_1.captureTitle;
+    const candidateContent = input.content ?? args_1.captureContent;
+    const candidateCategory = input.category ?? args_1.captureCategory;
+    if (!candidateTitle && !candidateContent)
         return existed ? "exists" : "created";
-    const title = (args_1.captureTitle || "Untitled candidate").replace(/\|/g, "/");
-    const content = (args_1.captureContent || "").replace(/\r?\n/g, "<br>").replace(/\|/g, "/");
-    const row = `| ${workspace_1.today} | ${title} | ${args_1.captureCategory.replace(/\|/g, "/")} | ${content} | pending |`;
+    const title = (candidateTitle || "Untitled candidate").replace(/\|/g, "/");
+    const content = (candidateContent || "").replace(/\r?\n/g, "<br>").replace(/\|/g, "/");
+    const row = `| ${workspace_1.today} | ${title} | ${candidateCategory.replace(/\|/g, "/")} | ${content} | pending |`;
     const current = (0, workspace_1.read)(relativePath);
     if (current.includes(row))
         return "exists";
     (0, workspace_1.write)(relativePath, `${current.trimEnd()}\n${row}\n`);
     return "updated";
 }
+function appendCaptureInbox() {
+    return appendProjectCandidate();
+}
 function gitOutput(args) {
     try {
         return childProcess.execFileSync("git", args, {

package/dist/session-handoff.js

@@ -0,0 +1,627 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handoffSentinel = exports.handoffGeneratedBy = exports.handoffSchema = exports.handoffInjectionStatePath = exports.handoffStatePath = exports.handoffPath = exports.handoffDirectory = void 0;
+exports.redactSecrets = redactSecrets;
+exports.saveHandoffFromCli = saveHandoffFromCli;
+exports.getHandoffStatus = getHandoffStatus;
+exports.showHandoff = showHandoff;
+exports.clearHandoff = clearHandoff;
+exports.promoteHandoffToInbox = promoteHandoffToInbox;
+exports.enableHandoffInjection = enableHandoffInjection;
+exports.disableHandoffInjection = disableHandoffInjection;
+exports.getHandoffInjectionStatus = getHandoffInjectionStatus;
+exports.runHandoffSaveMode = runHandoffSaveMode;
+exports.runHandoffShowMode = runHandoffShowMode;
+exports.runHandoffStatusMode = runHandoffStatusMode;
+exports.runHandoffClearMode = runHandoffClearMode;
+exports.runHandoffPromoteInboxMode = runHandoffPromoteInboxMode;
+exports.runHandoffInjectionEnableMode = runHandoffInjectionEnableMode;
+exports.runHandoffInjectionDisableMode = runHandoffInjectionDisableMode;
+exports.runHandoffInjectionStatusMode = runHandoffInjectionStatusMode;
+const childProcess = __importStar(require("node:child_process"));
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const args_1 = require("./args");
+const modes_1 = require("./modes");
+const templates_1 = require("./templates");
+const workspace_1 = require("./workspace");
+const workspace_2 = require("./workspace");
+exports.handoffDirectory = ".project-wiki/session";
+exports.handoffPath = `${exports.handoffDirectory}/last-handoff.md`;
+exports.handoffStatePath = `${exports.handoffDirectory}/handoff-state.json`;
+exports.handoffInjectionStatePath = `${exports.handoffDirectory}/injection-state.json`;
+exports.handoffSchema = "project-librarian-session-handoff/v1";
+exports.handoffGeneratedBy = "project-librarian-session-handoff";
+exports.handoffSentinel = "<!-- PROJECT-LIBRARIAN-GENERATED: session-handoff/v1 -->";
+const maxHandoffChars = 8000;
+const maxInjectedHandoffChars = 2500;
+const maxFieldChars = 800;
+const maxGitFactsChars = 2000;
+const staleAfterMs = 7 * 24 * 60 * 60 * 1000;
+function rootRealPath() {
+    return fs.realpathSync(workspace_1.root);
+}
+function assertInsideRoot(absolutePath) {
+    const relative = path.relative(rootRealPath(), absolutePath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`refusing to access path outside project root: ${absolutePath}`);
+    }
+}
+function resolveUnderRoot(relativePath) {
+    if (path.isAbsolute(relativePath))
+        throw new Error(`expected repository-relative path: ${relativePath}`);
+    const absolutePath = path.resolve(workspace_1.root, relativePath);
+    assertInsideRoot(absolutePath);
+    return absolutePath;
+}
+function ensureDirectoryNoSymlink(relativePath) {
+    const segments = relativePath.split(/[\\/]+/).filter(Boolean);
+    let current = rootRealPath();
+    for (const segment of segments) {
+        current = path.join(current, segment);
+        try {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink())
+                throw new Error(`refusing to use symlinked directory: ${path.relative(rootRealPath(), current)}`);
+            if (!stat.isDirectory())
+                throw new Error(`refusing to use non-directory path: ${path.relative(rootRealPath(), current)}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            fs.mkdirSync(current);
+        }
+    }
+    assertInsideRoot(fs.realpathSync(current));
+}
+function assertWritableFilePath(relativePath) {
+    const absolutePath = resolveUnderRoot(relativePath);
+    ensureDirectoryNoSymlink(path.dirname(relativePath));
+    try {
+        const stat = fs.lstatSync(absolutePath);
+        if (stat.isSymbolicLink())
+            throw new Error(`refusing to write symlinked file: ${relativePath}`);
+        if (!stat.isFile())
+            throw new Error(`refusing to overwrite non-file path: ${relativePath}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    return absolutePath;
+}
+function writeFileNoFollow(relativePath, content) {
+    const absolutePath = assertWritableFilePath(relativePath);
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(absolutePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | noFollow, 0o600);
+    try {
+        fs.writeFileSync(fd, content, "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function readFileNoSymlink(relativePath) {
+    const absolutePath = resolveUnderRoot(relativePath);
+    const stat = fs.lstatSync(absolutePath);
+    if (stat.isSymbolicLink())
+        throw new Error(`refusing to read symlinked file: ${relativePath}`);
+    if (!stat.isFile())
+        throw new Error(`expected file: ${relativePath}`);
+    return fs.readFileSync(absolutePath, "utf8");
+}
+function removeGeneratedFile(relativePath, isGenerated) {
+    const absolutePath = resolveUnderRoot(relativePath);
+    if (!fs.existsSync(absolutePath))
+        return "absent";
+    const text = readFileNoSymlink(relativePath);
+    if (!isGenerated(text))
+        throw new Error(`refusing to remove non-generated file: ${relativePath}`);
+    fs.unlinkSync(absolutePath);
+    return "removed";
+}
+function capText(value, maxChars = maxFieldChars) {
+    const compact = value.replace(/\r\n/g, "\n").trim();
+    if (compact.length <= maxChars)
+        return compact;
+    return `${compact.slice(0, Math.max(0, maxChars - 24)).trimEnd()}\n[truncated]`;
+}
+function redactSecrets(text) {
+    let next = text;
+    next = next.replace(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g, "[REDACTED_PRIVATE_KEY]");
+    next = next.replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, "[REDACTED_OPENAI_KEY]");
+    next = next.replace(/\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, "[REDACTED_GITHUB_TOKEN]");
+    next = next.replace(/\bxox[baprs]-[A-Za-z0-9-]{20,}\b/g, "[REDACTED_SLACK_TOKEN]");
+    next = next.replace(/\bAKIA[0-9A-Z]{16}\b/g, "[REDACTED_AWS_ACCESS_KEY]");
+    next = next.replace(/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, "[REDACTED_JWT]");
+    next = next.replace(/(Authorization\s*[:=]\s*)(?:Bearer\s+)?[A-Za-z0-9._~+/=-]{12,}/gi, "$1[REDACTED_AUTHORIZATION]");
+    next = next.replace(/(^|\n)([A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|API_KEY|ACCESS_KEY|PRIVATE_KEY)[A-Z0-9_]*\s*=\s*)([^\n]+)/gi, "$1$2[REDACTED_SECRET]");
+    return next;
+}
+function normalizeList(value) {
+    if (Array.isArray(value))
+        return value.flatMap((item) => normalizeList(item));
+    if (typeof value !== "string")
+        return [];
+    return value.split(/\n/).map((item) => capText(redactSecrets(item))).filter(Boolean);
+}
+function normalizeString(value) {
+    return typeof value === "string" ? capText(redactSecrets(value)) : "";
+}
+function arrayValue(record, snakeKey, camelKey) {
+    if (snakeKey === camelKey)
+        return normalizeList(record[snakeKey]);
+    return normalizeList(record[snakeKey]).concat(normalizeList(record[camelKey]));
+}
+function stringValue(record, snakeKey, camelKey) {
+    return normalizeString(record[snakeKey] ?? record[camelKey]);
+}
+function payloadFromRecord(record) {
+    return {
+        blocked: arrayValue(record, "blocked", "blocked").slice(0, 6),
+        currentState: stringValue(record, "current_state", "currentState"),
+        goal: stringValue(record, "goal", "goal"),
+        lastFailureCommand: stringValue(record, "last_failure_command", "lastFailureCommand"),
+        lastSuccessCommand: stringValue(record, "last_success_command", "lastSuccessCommand"),
+        nextActions: arrayValue(record, "next_actions", "nextActions").slice(0, 3),
+        openQuestions: arrayValue(record, "open_questions", "openQuestions").slice(0, 6),
+        recentDecisions: arrayValue(record, "recent_decisions", "recentDecisions").slice(0, 6),
+        verification: arrayValue(record, "verification", "verification").slice(0, 6),
+    };
+}
+function cliPayloadRecord() {
+    return {
+        blocked: args_1.handoffBlocked,
+        current_state: args_1.handoffState,
+        goal: args_1.handoffGoal,
+        last_failure_command: args_1.handoffLastFailureCommand,
+        last_success_command: args_1.handoffLastSuccessCommand,
+        next_actions: args_1.handoffNextActions,
+        open_questions: args_1.handoffOpenQuestions,
+        recent_decisions: args_1.handoffDecisions,
+        verification: args_1.handoffVerification,
+    };
+}
+function mergePayloads(base, overlay) {
+    return {
+        blocked: overlay.blocked.length > 0 ? overlay.blocked : base.blocked,
+        currentState: overlay.currentState || base.currentState,
+        goal: overlay.goal || base.goal,
+        lastFailureCommand: overlay.lastFailureCommand || base.lastFailureCommand,
+        lastSuccessCommand: overlay.lastSuccessCommand || base.lastSuccessCommand,
+        nextActions: overlay.nextActions.length > 0 ? overlay.nextActions : base.nextActions,
+        openQuestions: overlay.openQuestions.length > 0 ? overlay.openQuestions : base.openQuestions,
+        recentDecisions: overlay.recentDecisions.length > 0 ? overlay.recentDecisions : base.recentDecisions,
+        verification: overlay.verification.length > 0 ? overlay.verification : base.verification,
+    };
+}
+function readStdinText() {
+    try {
+        if (process.stdin.isTTY)
+            return "";
+        return fs.readFileSync(0, "utf8").trim();
+    }
+    catch {
+        return "";
+    }
+}
+function payloadFromStdin() {
+    const text = readStdinText();
+    if (!text)
+        return emptyPayload();
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("expected a JSON object");
+        }
+        return payloadFromRecord(parsed);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`invalid --handoff-save JSON payload: ${message}`);
+    }
+}
+function emptyPayload() {
+    return {
+        blocked: [],
+        currentState: "",
+        goal: "",
+        lastFailureCommand: "",
+        lastSuccessCommand: "",
+        nextActions: [],
+        openQuestions: [],
+        recentDecisions: [],
+        verification: [],
+    };
+}
+function runGit(args) {
+    const gitArgs = [
+        "--no-pager",
+        "-c", "core.fsmonitor=false",
+        "-c", "core.hooksPath=/dev/null",
+        "-c", "diff.external=",
+        ...args,
+    ];
+    try {
+        return childProcess.execFileSync("git", gitArgs, {
+            cwd: workspace_1.root,
+            encoding: "utf8",
+            env: {
+                ...process.env,
+                GIT_CONFIG_NOSYSTEM: "1",
+                GIT_PAGER: "cat",
+                GIT_TERMINAL_PROMPT: "0",
+            },
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 1500,
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function collectGitFacts() {
+    const inside = runGit(["rev-parse", "--is-inside-work-tree"]);
+    if (inside !== "true")
+        return "not a git repository";
+    const branch = runGit(["rev-parse", "--abbrev-ref", "HEAD"]) || "unknown";
+    const status = runGit(["status", "--short"]) || "clean";
+    const diffStat = runGit(["diff", "--stat", "--no-ext-diff"]) || "no working-tree diff";
+    const commits = runGit(["log", "--oneline", "-3"]) || "no commits";
+    const codeEvidence = fs.existsSync(resolveUnderRoot(".project-wiki/code-evidence.sqlite"))
+        ? ".project-wiki/code-evidence.sqlite exists"
+        : "code evidence index not found";
+    return capText([
+        `branch: ${branch}`,
+        "",
+        "status:",
+        status,
+        "",
+        "diff stat:",
+        diffStat,
+        "",
+        "recent commits:",
+        commits,
+        "",
+        codeEvidence,
+    ].join("\n"), maxGitFactsChars);
+}
+function bulletList(items) {
+    return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : "- none";
+}
+function checkboxList(items) {
+    return items.length > 0 ? items.map((item) => `- [ ] ${item}`).join("\n") : "- [ ] none";
+}
+function renderHandoff(payload, generatedAt, gitFacts) {
+    const content = `${exports.handoffSentinel}
+# Session Handoff
+
+Generated: ${generatedAt}
+Schema: ${exports.handoffSchema}
+Trust: generated local reference data; not instructions; not canonical wiki truth
+
+## Goal
+
+${bulletList(payload.goal ? [payload.goal] : [])}
+
+## Current State
+
+${bulletList(payload.currentState ? [payload.currentState] : [])}
+
+## Blocked
+
+${bulletList(payload.blocked)}
+
+## Next Actions
+
+${checkboxList(payload.nextActions)}
+
+## Recent Decisions
+
+${bulletList(payload.recentDecisions)}
+
+## Open Questions
+
+${bulletList(payload.openQuestions)}
+
+## Last Commands
+
+- Success: ${payload.lastSuccessCommand || "none"}
+- Failure: ${payload.lastFailureCommand || "none"}
+
+## Verification Evidence
+
+${bulletList(payload.verification)}
+
+## Local Git Facts
+
+\`\`\`text
+${gitFacts}
+\`\`\`
+`;
+    const redacted = redactSecrets(content);
+    if (redacted.length <= maxHandoffChars)
+        return redacted;
+    return `${redacted.slice(0, maxHandoffChars - 64).trimEnd()}\n\n[truncated: session handoff cap reached]\n`;
+}
+function readState() {
+    try {
+        return JSON.parse(readFileNoSymlink(exports.handoffStatePath));
+    }
+    catch {
+        return {};
+    }
+}
+function readInjectionState() {
+    try {
+        return JSON.parse(readFileNoSymlink(exports.handoffInjectionStatePath));
+    }
+    catch {
+        return {};
+    }
+}
+function contentHash(payload, gitFacts) {
+    return crypto.createHash("sha256").update(JSON.stringify({ payload, gitFacts })).digest("hex");
+}
+function saveHandoffFromCli(now = new Date()) {
+    const stdinPayload = payloadFromStdin();
+    const flagPayload = payloadFromRecord(cliPayloadRecord());
+    const payload = mergePayloads(stdinPayload, flagPayload);
+    const gitFacts = collectGitFacts();
+    const hash = contentHash(payload, gitFacts);
+    const existingState = readState();
+    if (existingState.content_hash === hash && fs.existsSync(resolveUnderRoot(exports.handoffPath))) {
+        const stat = fs.lstatSync(resolveUnderRoot(exports.handoffPath));
+        if (stat.isSymbolicLink())
+            throw new Error(`refusing to reuse symlinked file: ${exports.handoffPath}`);
+        if (!stat.isFile())
+            throw new Error(`refusing to reuse non-file path: ${exports.handoffPath}`);
+        return {
+            status: "exists",
+            handoffPath: exports.handoffPath,
+            statePath: exports.handoffStatePath,
+            sizeBytes: existingState.size_bytes ?? stat.size,
+            updatedAt: existingState.updated_at ?? "",
+        };
+    }
+    const updatedAt = now.toISOString();
+    const content = renderHandoff(payload, updatedAt, gitFacts);
+    writeFileNoFollow(exports.handoffPath, content);
+    const sizeBytes = Buffer.byteLength(content, "utf8");
+    const state = {
+        content_hash: hash,
+        full_injection_enabled: false,
+        generated: true,
+        generated_by: exports.handoffGeneratedBy,
+        path: exports.handoffPath,
+        schema: exports.handoffSchema,
+        size_bytes: sizeBytes,
+        updated_at: updatedAt,
+    };
+    writeFileNoFollow(exports.handoffStatePath, `${JSON.stringify(state, null, 2)}\n`);
+    return { status: "written", handoffPath: exports.handoffPath, statePath: exports.handoffStatePath, sizeBytes, updatedAt };
+}
+function getHandoffStatus(now = new Date()) {
+    const absoluteHandoffPath = resolveUnderRoot(exports.handoffPath);
+    if (!fs.existsSync(absoluteHandoffPath)) {
+        return {
+            ageSeconds: null,
+            exists: false,
+            path: exports.handoffPath,
+            reason: "handoff file not found",
+            safeToInject: false,
+            schema: exports.handoffSchema,
+            sizeBytes: 0,
+            stale: false,
+            statePath: exports.handoffStatePath,
+            updatedAt: "",
+        };
+    }
+    const stat = fs.lstatSync(absoluteHandoffPath);
+    if (stat.isSymbolicLink()) {
+        return {
+            ageSeconds: null,
+            exists: true,
+            path: exports.handoffPath,
+            reason: "handoff path is a symlink",
+            safeToInject: false,
+            schema: exports.handoffSchema,
+            sizeBytes: 0,
+            stale: true,
+            statePath: exports.handoffStatePath,
+            updatedAt: "",
+        };
+    }
+    const state = readState();
+    const updatedAt = state.updated_at || stat.mtime.toISOString();
+    const updatedMs = Date.parse(updatedAt);
+    const ageSeconds = Number.isFinite(updatedMs) ? Math.max(0, Math.floor((now.getTime() - updatedMs) / 1000)) : null;
+    const stale = ageSeconds === null || ageSeconds * 1000 > staleAfterMs;
+    const sizeBytes = stat.size;
+    const generated = state.generated === true && state.generated_by === exports.handoffGeneratedBy;
+    const safeToInject = generated && !stale && sizeBytes <= maxHandoffChars;
+    return {
+        ageSeconds,
+        exists: true,
+        path: exports.handoffPath,
+        reason: safeToInject ? "ok" : generated ? "stale or over size cap" : "missing generated state",
+        safeToInject,
+        schema: state.schema || exports.handoffSchema,
+        sizeBytes,
+        stale,
+        statePath: exports.handoffStatePath,
+        updatedAt,
+    };
+}
+function showHandoff() {
+    const status = getHandoffStatus();
+    if (!status.exists)
+        return "Project Librarian handoff: none found.\n";
+    const text = readFileNoSymlink(exports.handoffPath);
+    return [
+        `Project Librarian handoff: updated ${status.updatedAt || "unknown"}, ${status.sizeBytes} bytes, stale=${String(status.stale)}`,
+        "",
+        text,
+    ].join("\n");
+}
+function clearHandoff() {
+    const handoffResult = removeGeneratedFile(exports.handoffPath, (text) => text.includes(exports.handoffSentinel));
+    const stateResult = removeGeneratedFile(exports.handoffStatePath, (text) => {
+        try {
+            const state = JSON.parse(text);
+            return state.generated === true && state.generated_by === exports.handoffGeneratedBy;
+        }
+        catch {
+            return false;
+        }
+    });
+    return `Project Librarian handoff cleared: ${exports.handoffPath}=${handoffResult}, ${exports.handoffStatePath}=${stateResult}`;
+}
+function sectionText(markdown, heading) {
+    const pattern = new RegExp(`^## ${heading}\\n\\n([\\s\\S]*?)(?=\\n## |\\n$)`, "m");
+    return markdown.match(pattern)?.[1]?.trim() ?? "";
+}
+function compactPromotionContent(markdown) {
+    const sections = [
+        ["Goal", sectionText(markdown, "Goal")],
+        ["Current State", sectionText(markdown, "Current State")],
+        ["Blocked", sectionText(markdown, "Blocked")],
+        ["Next Actions", sectionText(markdown, "Next Actions")],
+        ["Recent Decisions", sectionText(markdown, "Recent Decisions")],
+        ["Open Questions", sectionText(markdown, "Open Questions")],
+        ["Verification Evidence", sectionText(markdown, "Verification Evidence")],
+    ].filter(([, text]) => text && text !== "- none" && text !== "- [ ] none");
+    const body = sections.map(([title, text]) => `### ${title}\n${text}`).join("\n\n");
+    return capText([
+        "Promoted from generated local session handoff. Review before canonicalizing into project truth.",
+        "",
+        body || "No structured handoff facts were available.",
+    ].join("\n"), 1600);
+}
+function promoteHandoffToInbox() {
+    const status = getHandoffStatus();
+    if (!status.exists)
+        throw new Error("cannot promote handoff: no generated handoff found");
+    if (!status.safeToInject)
+        throw new Error(`cannot promote handoff: ${status.reason}`);
+    if (!(0, workspace_2.exists)("wiki/index.md"))
+        throw new Error("cannot promote handoff: initialize Project Librarian wiki before writing wiki/inbox");
+    const markdown = readFileNoSymlink(exports.handoffPath);
+    if (!markdown.includes(exports.handoffSentinel))
+        throw new Error(`cannot promote handoff: missing generated sentinel in ${exports.handoffPath}`);
+    const firstGoal = sectionText(markdown, "Goal").split(/\r?\n/).find((line) => line.replace(/^[-\s[\]x]+/i, "").trim()) || "Session handoff";
+    const title = `Session handoff: ${firstGoal.replace(/^[-\s[\]x]+/i, "").trim() || "untitled"}`;
+    const inboxStatus = (0, modes_1.appendProjectCandidate)({
+        category: "session-handoff",
+        content: compactPromotionContent(markdown),
+        title,
+    });
+    const indexStatus = (0, workspace_2.upsertMarkedSection)("wiki/index.md", "<!-- PROJECT-WIKI-INBOX:START -->", "<!-- PROJECT-WIKI-INBOX:END -->", templates_1.inboxIndexBlock);
+    return `Project Librarian handoff promoted to wiki inbox: wiki/inbox/project-candidates.md=${inboxStatus}, wiki/index.md inbox router=${indexStatus}`;
+}
+function enableHandoffInjection(now = new Date()) {
+    const updatedAt = now.toISOString();
+    const state = {
+        content_hash: "",
+        full_injection_enabled: true,
+        generated: true,
+        generated_by: exports.handoffGeneratedBy,
+        path: exports.handoffInjectionStatePath,
+        schema: exports.handoffSchema,
+        size_bytes: 0,
+        updated_at: updatedAt,
+    };
+    const content = `${JSON.stringify(state, null, 2)}\n`;
+    state.size_bytes = Buffer.byteLength(content, "utf8");
+    writeFileNoFollow(exports.handoffInjectionStatePath, `${JSON.stringify(state, null, 2)}\n`);
+    return `Project Librarian handoff full injection enabled: ${exports.handoffInjectionStatePath}`;
+}
+function disableHandoffInjection() {
+    const result = removeGeneratedFile(exports.handoffInjectionStatePath, (text) => {
+        try {
+            const state = JSON.parse(text);
+            return state.generated === true && state.generated_by === exports.handoffGeneratedBy;
+        }
+        catch {
+            return false;
+        }
+    });
+    return `Project Librarian handoff full injection disabled: ${exports.handoffInjectionStatePath}=${result}`;
+}
+function getHandoffInjectionStatus() {
+    const state = readInjectionState();
+    const enabled = state.generated === true && state.generated_by === exports.handoffGeneratedBy && state.full_injection_enabled === true;
+    const handoff = getHandoffStatus();
+    const safeToInject = enabled && handoff.exists && !handoff.stale && handoff.reason === "ok";
+    return {
+        enabled,
+        handoffPath: exports.handoffPath,
+        maxInjectedChars: maxInjectedHandoffChars,
+        path: exports.handoffInjectionStatePath,
+        reason: !enabled ? "full injection is not enabled" : safeToInject ? "ok" : handoff.reason,
+        safeToInject,
+        updatedAt: state.updated_at || "",
+    };
+}
+function runHandoffSaveMode() {
+    const result = saveHandoffFromCli();
+    console.log(`Project Librarian handoff ${result.status}: ${result.handoffPath}`);
+    console.log(`State: ${result.statePath}`);
+    console.log(`Size: ${result.sizeBytes} bytes`);
+    console.log("Resume: project-librarian --handoff-show");
+}
+function runHandoffShowMode() {
+    process.stdout.write(showHandoff());
+}
+function runHandoffStatusMode() {
+    console.log(JSON.stringify(getHandoffStatus(), null, 2));
+}
+function runHandoffClearMode() {
+    console.log(clearHandoff());
+}
+function runHandoffPromoteInboxMode() {
+    console.log(promoteHandoffToInbox());
+}
+function runHandoffInjectionEnableMode() {
+    console.log(enableHandoffInjection());
+}
+function runHandoffInjectionDisableMode() {
+    console.log(disableHandoffInjection());
+}
+function runHandoffInjectionStatusMode() {
+    console.log(JSON.stringify(getHandoffInjectionStatus(), null, 2));
+}

package/dist/templates.js

@@ -86,6 +86,7 @@ During conversation:
 - Classify new project-planning content with \`wiki/meta/document-taxonomy.md\` before writing or consolidating it.
 - Do not store non-project LLM memory, assistant preferences, collaboration reminders, or workflow instructions in project wiki canonical or decision docs.
 - Follow \`wiki/AGENTS.md\` for detailed rules when editing files under \`wiki/\`.
+- Treat broad maintenance/improvement automation requests that do not name a concrete command (for example "improve this project", "start improvement automation", or "개선 자동화 시작해") as analyze-first project work, not as a plain bootstrap/update. Inspect repo, wiki, CI, test, release, dependency, and code-structure evidence; produce a ranked backlog with evidence and verification paths; persist the plan in \`wiki/plans/\` when project-planning content changes; then execute safe high-priority items with tests.
 - Let \`.githooks/prepare-commit-msg\` append wiki trailers automatically for staged wiki, hook, AGENTS, or project-librarian files.
 - ${exports.wikiTrustContract}
 - ${exports.codeEvidenceTrustContract}
@@ -724,6 +725,7 @@ Canonical: [[meta/operating-model]], [[meta/decision-policy]], [[meta/document-t
 | ${workspace_1.today} | Commit automation writes the \`Wiki-scope\` trailer. | Reviewers should see whether a commit touched startup, canonical docs, decisions, or wiki operations. | Leave wiki impact implicit in the diff. | Trailer format becomes too noisy. | [[meta/operating-model]] |
 | ${workspace_1.today} | Migration may mark rows \`needs-human-review\`. | Ambiguous, risky, or high-impact legacy content should not be closed automatically. | Force every migrated row into adopted/rejected/resolved. | Human review queues become too large. | [[meta/operating-model]] |
 | ${workspace_1.today} | Capture stores candidates in \`wiki/inbox/\`. | Useful ideas are not lost, but unreviewed content does not become canonical truth. | Save all conversation content directly into canonical docs. | Inbox content is frequently abandoned. | [[meta/operating-model]] |
+| ${workspace_1.today} | Session handoff state lives under \`.project-wiki/session/\`. | Last-session operational memory helps resume work, but it is generated local reference data rather than reviewed project truth. | Store rolling execution memory in \`wiki/startup.md\` or canonical pages. | Handoff data needs to become durable project planning truth. | [[meta/operating-model]] |
 `,
     "wiki/meta/document-taxonomy.md": exports.documentTaxonomy,
     "wiki/decisions/decision-pack-template.md": `${(0, exports.metadata)("project-decision-template", "short", "wiki/meta/decision-policy.md", "decision pack format changes", "template")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-librarian",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",
@@ -49,6 +49,7 @@
     "benchmark:guidance": "npm run build && node benchmarks/tools/guidance-probe-runner.js",
     "benchmark:guidance:dry-run": "npm run build && node benchmarks/tools/guidance-probe-runner.js --dry-run --markdown",
     "benchmark:injection-sentinel": "node benchmarks/tools/injection-sentinel.js",
+    "benchmark:handoff-resume:preview": "node benchmarks/tools/session-handoff-resume-preview.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",
@@ -56,6 +57,7 @@
     "benchmark:release:diagnose": "npm run benchmark:llm -- --sanitized-pack --runs 1 --warmup-runs 0 --model gpt-5.5 --out benchmarks/reports/llm/diagnostic-current.json --markdown benchmarks/reports/llm/diagnostic-current.md",
     "benchmark:release": "npm run benchmark:llm -- --sanitized-pack --full-matrix --runs 3 --warmup-runs 1 --min-runs-for-claim 3 --require-clean --require-claimable --model gpt-5.5 --out benchmarks/reports/llm/current.json --markdown benchmarks/reports/llm/current.md",
     "build": "tsc && chmod +x dist/init-project-wiki.js",
+    "check:dist": "node benchmarks/tools/release-readiness.js --only-dist-parity",
     "perf:code-efficiency": "node benchmarks/tools/code-performance-efficiency.js --full",
     "release:check": "node benchmarks/tools/release-readiness.js",
     "typecheck": "tsc --noEmit",