feat: add lifecycle-aware compact re-entry for llmdoc

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "llmdoc",
       "source": "./",
-      "description": "llmdoc workflow for Claude Code: init, commit-watermark update detection, update modes, temporary investigation cache, and use"
+      "description": "llmdoc workflow for Claude Code: bounded cold-start context, routed docs, init, commit-watermark updates, and use"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "llmdoc",
-  "description": "llmdoc Claude Code plugin with init, commit-watermark update detection, update modes, temporary investigation cache, and use",
-  "version": "2.2.0",
+  "description": "llmdoc plugin with bounded cold-start context, routed docs, init, commit-watermark updates, and use",
+  "version": "2.3.0",
   "author": {
     "name": "DJJ & Danniel"
   }

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "llmdoc",
-  "version": "2.2.0",
-  "description": "Doc-driven workflow with startup docs, commit-watermark update detection, update modes, temporary investigation cache, and reusable skills for Codex.",
+  "version": "2.3.0",
+  "description": "Doc-driven workflow with bounded cold-start context, compact re-entry, commit-watermark updates, and reusable skills for Codex.",
   "author": {
     "name": "DJJ & Danniel",
     "email": "shuaiqijianaho@qq.com",
@@ -13,10 +13,15 @@
   "interface": {
     "displayName": "llmdoc",
     "shortDescription": "Doc-driven coding workflow",
-    "longDescription": "Use startup docs, guides, commit-watermark update detection, update modes, temporary investigation cache, and focused reflections to improve coding quality and reduce repeated work.",
+    "longDescription": "Load a bounded startup package once, resume compacted tasks without replaying llmdoc, and use routed docs, commit-watermark updates, temporary investigation cache, and focused reflections.",
     "developerName": "TokenRoll",
     "category": "Productivity",
     "capabilities": ["Read", "Write"],
-    "websiteURL": "https://github.com/TokenRollAI/llmdoc"
+    "websiteURL": "https://github.com/TokenRollAI/llmdoc",
+    "defaultPrompt": [
+      "Load llmdoc and help me implement this task.",
+      "Initialize llmdoc for this repository.",
+      "Update llmdoc after my recent changes."
+    ]
   }
 }

.codex/agents/llmdoc-recorder.toml

@@ -11,6 +11,9 @@ Load the llmdoc skill first.
 Your responsibilities:
 - Maintain stable llmdoc documents.
 - Keep llmdoc/index.md and llmdoc/startup.md distinct.
+- Keep index.md + startup.md + must/ under 24 KiB by default.
+- In monoliths, keep the root index as an L0 router and route leaf docs through subsystem indexes.
+- Treat the startup pack as cold-start-only; context compaction resumes from LLMDOC_STATE.
 - Keep temporary investigation artifacts out of stable docs.
 - Read relevant guides and reflections before updating stable docs.
 - Split documents aggressively rather than growing one large file.

AGENTS.example.md

@@ -2,6 +2,8 @@
 
 Before broad source-code exploration, planning, or documentation work, load the `llmdoc` skill.
 
+Load it once on cold start. After context compaction, continue from `LLMDOC_STATE` and do not replay the skill or startup pack unless the state is stale or insufficient.
+
 The main assistant should align with the user before non-trivial plans or edits.
 
 Use available `llmdoc` subagents when they fit the task. Prefer `investigator` for context exploration, current-state research, unfamiliar subsystems, and reusable scratch reports; use `recorder` for stable doc updates, `worker` for scoped implementation, and `reflector` for process lessons.

CLAUDE.example.md

@@ -3,6 +3,8 @@ Always answer in 简体中文
 </system-reminder>
 Load the `llmdoc` skill before broad code exploration, planning, document updates, or non-trivial code edits.
 
+Load it once on cold start. After context compaction, continue from `LLMDOC_STATE` and do not replay the skill or startup pack unless the state is stale or insufficient.
+
 The main assistant should align with the user before non-trivial plans or edits.
 
 Use available `llmdoc` subagents when they fit the task. Prefer `investigator` for context exploration, current-state research, unfamiliar subsystems, and reusable scratch reports; use `recorder` for stable doc updates, `worker` for scoped implementation, and `reflector` for process lessons.

README.md

@@ -13,6 +13,8 @@ The default setup is simple:
 - `CLAUDE.md` and `AGENTS.md` only need one short rule: step one is loading the `llmdoc` skill
 - the core skill entry is short, while detailed rationale, protocols, and templates are split under `skills/llmdoc/references/`
 - the core skill defines proactive guide/reflection reading and proactive user discussion before non-trivial edits
+- the startup package is loaded once on cold start; Codex compaction resumes through a compact `LLMDOC_STATE` instead of replaying llmdoc
+- monoliths keep a bounded root router and use subsystem indexes instead of loading a repository-wide leaf catalog
 - the workflow restores the good pattern of proactively asking whether to run `/llmdoc:update` at the end of non-trivial tasks
 - `/llmdoc:update` supports lightweight and heavier modes, so immediate post-task doc updates do not always require a full multi-agent pipeline
 - helper Codex skills provide command-like entrypoints without pretending Codex has custom slash commands for this plugin
@@ -36,7 +38,7 @@ This refactor keeps the public interface small and moves the rest into one reusa
 - Claude Code plugin support: `.claude-plugin/`
 - Codex CLI plugin support: `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`
 - Codex CLI subagents: `.codex/agents/*.toml`
-- Codex CLI hooks: `SessionStart`, `Stop` templates included
+- Codex CLI hooks: lifecycle-aware `SessionStart` bundled; `Stop` and compact-prompt templates included
 
 ## Workflow
 
@@ -92,13 +94,25 @@ The command:
 
 In normal use, the main assistant should proactively ask whether to run `/llmdoc:update` when the task produced durable knowledge or a useful reflection.
 
+## Context Lifecycle
+
+`llmdoc` distinguishes a cold start from compact re-entry:
+
+- `startup` and `clear` load the core skill, root index, startup list, and MUST pack once
+- `resume` reuses a valid `LLMDOC_STATE`, otherwise it performs one cold start
+- `compact` continues the same task without reloading the skill, startup pack, lessons, or already-loaded task docs
+
+The bundled Codex `SessionStart` hook fingerprints the startup pack and reports its byte size. Re-entry refreshes only the smallest relevant document set when the fingerprint changed, a relevant document changed, the task entered a new subsystem, or the compact state is insufficient.
+
+The default startup budget is 24 KiB for `index.md` + `startup.md` + `must/`. This is a deterministic proxy, not an exact model-token count. In a monolith, keep `llmdoc/index.md` as an L0 router, add subsystem indexes beside their docs, and load only the active subsystem route.
+
 ## llmdoc Layout
 
 ```text
 llmdoc/
 ├── index.md
 ├── startup.md
-├── must/                 # Small startup context package
+├── must/                 # Small cold-start context package
 ├── overview/             # Project and feature identity
 ├── architecture/         # Retrieval maps, invariants, ownership
 ├── guides/               # One workflow per document
@@ -112,8 +126,8 @@ llmdoc/
 └── investigations/       # Temporary scratch investigation reports
 ```
 
-`llmdoc/index.md` is the global doc map.
-`llmdoc/startup.md` is only the startup reading order.
+`llmdoc/index.md` is the bounded global router.
+`llmdoc/startup.md` is only the cold-start reading order.
 They should link to each other, but they should not repeat the same content.
 
 `.llmdoc-tmp/` is a local temporary context cache. Investigator reports can persist across nearby sessions and help avoid repeated research, but they are ignored by git, not indexed, and not a source of truth. Promote only durable conclusions into tracked `llmdoc/` docs.
@@ -178,11 +192,13 @@ This repository contains two separate Codex integration surfaces:
   - [`skills/llmdoc/`](skills/llmdoc/)
   - [`skills/llmdoc-init/`](skills/llmdoc-init/)
   - [`skills/llmdoc-update/`](skills/llmdoc-update/)
+  - [`hooks/hooks.json`](hooks/hooks.json) for the bundled lifecycle-aware `SessionStart` hook
   - [`.agents/plugins/marketplace.json`](.agents/plugins/marketplace.json) as a repo-scoped local marketplace example
 - Repo-local Codex workflow files for this repository:
   - [`.codex/config.toml`](.codex/config.toml)
   - [`.codex/agents/`](.codex/agents)
   - [`skills/llmdoc/templates/codex-hooks.json`](skills/llmdoc/templates/codex-hooks.json)
+  - [`skills/llmdoc/templates/compact-prompt.md`](skills/llmdoc/templates/compact-prompt.md)
 
 #### Option 1: Install from GitHub (recommended)
 
@@ -198,7 +214,8 @@ Then:
 2. Run `/plugins` in Codex.
 3. Find `llmdoc` in the plugin list, select it to open the detail page.
 4. Install the plugin.
-5. Start a new thread in any repository and either:
+5. Review and trust the bundled lifecycle hook in `/hooks`.
+6. Start a new thread in any repository and either:
    - ask Codex to load the `llmdoc` skill first for normal work
    - choose `llmdoc-init` when you want the `/llmdoc:init` workflow
    - choose `llmdoc-update` when you want the `/llmdoc:update` workflow
@@ -219,7 +236,9 @@ Use this when you are working inside this repository — contributing to `llmdoc
    - choose `llmdoc-init` when you want the `/llmdoc:init` workflow
    - choose `llmdoc-update` when you want the `/llmdoc:update` workflow
    - or type `@` and choose the plugin or one of its bundled skills explicitly
-8. If you want hooks, copy [`skills/llmdoc/templates/codex-hooks.json`](skills/llmdoc/templates/codex-hooks.json) to `.codex/hooks.json` and adjust the script paths for your machine.
+8. Review and trust the bundled hook in `/hooks`. If you prefer repo-local hooks instead of the installed plugin hook, copy [`skills/llmdoc/templates/codex-hooks.json`](skills/llmdoc/templates/codex-hooks.json) to `.codex/hooks.json` and adjust the script paths for your machine; do not enable both copies.
+
+The compact-prompt template is optional because configuring `compact_prompt` or `experimental_compact_prompt_file` overrides Codex's built-in compaction prompt. Use it only when you want a stronger `LLMDOC_STATE` shape and are prepared to review it as Codex evolves.
 
 When you open this repository itself, Codex can also use the project-scoped agents under [`.codex/agents/`](.codex/agents) and the agent limits from [`.codex/config.toml`](.codex/config.toml).
 
@@ -229,6 +248,7 @@ The reusable skill lives at [`skills/llmdoc/SKILL.md`](skills/llmdoc/SKILL.md).
 The Codex helper entry skills live at [`skills/llmdoc-init/SKILL.md`](skills/llmdoc-init/SKILL.md) and [`skills/llmdoc-update/SKILL.md`](skills/llmdoc-update/SKILL.md).
 Detailed references live under [`skills/llmdoc/references/`](skills/llmdoc/references/).
 Codex hook templates live under [`skills/llmdoc/templates/`](skills/llmdoc/templates/).
+The plugin-bundled Codex hook lives at [`hooks/hooks.json`](hooks/hooks.json).
 
 ## Codex Subagents
 

README.zh-CN.md

@@ -13,6 +13,8 @@
 - `CLAUDE.md` 和 `AGENTS.md` 里只保留一条短规则：step one 是加载 `llmdoc` skill
 - core skill 入口保持简短，详细的方法论、协议和模板拆到 `skills/llmdoc/references/`
 - core skill 还定义了主动阅读 guides/reflection，以及在非简单改动前主动和用户沟通
+- startup package 只在冷启动读取一次；Codex compact 后通过精简的 `LLMDOC_STATE` 恢复，而不是重放 llmdoc
+- 巨石仓库使用有固定预算的根路由和子系统索引，不加载覆盖全仓库的叶子文档清单
 - 整套工作流还恢复了一个好模式：在非简单任务结束时，主动询问是否运行 `/llmdoc:update`
 - `/llmdoc:update` 支持轻量和重型模式，所以刚完成实现后的文档更新不必每次都跑完整多 agent 流水线
 - Codex helper skills 提供了接近 command 的入口，但不会误导用户以为 Codex 已经支持这个插件的自定义 slash command
@@ -36,7 +38,7 @@
 - Claude Code plugin 支持：`.claude-plugin/`
 - Codex CLI plugin 支持：已提供 `.codex-plugin/plugin.json` 和 `.agents/plugins/marketplace.json`
 - Codex CLI subagents 支持：已提供 `.codex/agents/*.toml`
-- Codex CLI hooks：已提供 `SessionStart`、`Stop` 模板
+- Codex CLI hooks：插件内置生命周期感知的 `SessionStart`；另提供 `Stop` 与 compact-prompt 模板
 
 ## 工作流
 
@@ -92,13 +94,25 @@
 
 在日常使用里，如果任务产生了值得长期保留的知识或反思，主 assistant 应该主动询问是否现在运行 `/llmdoc:update`。
 
+## Context 生命周期
+
+`llmdoc` 区分冷启动和 compact 热恢复：
+
+- `startup`、`clear`：只加载一次 core skill、根 index、startup 列表和 MUST pack
+- `resume`：优先复用有效的 `LLMDOC_STATE`，没有有效状态时才执行一次冷启动
+- `compact`：继续同一任务，不重新加载 skill、startup pack、lessons 或已经加载的任务文档
+
+插件内置的 Codex `SessionStart` hook 会计算 startup pack 指纹和字节数。只有指纹变化、相关文档被修改、任务进入新子系统或 compact 状态不足时，才读取最小的相关文档集合。
+
+`index.md` + `startup.md` + `must/` 的默认预算是 24 KiB；这是确定性的近似约束，不是精确 token 数。巨石仓库应让 `llmdoc/index.md` 只做 L0 路由，在相关文档旁建立子系统索引，并且只加载当前子系统的路由。
+
 ## llmdoc 结构
 
 ```text
 llmdoc/
 ├── index.md
 ├── startup.md
-├── must/                 # 每次运行都应读取的小型启动上下文
+├── must/                 # 冷启动时读取一次的小型上下文
 ├── overview/             # 项目和特性的身份与边界
 ├── architecture/         # 检索地图、不变量、所有权边界
 ├── guides/               # 一篇文档只讲一个工作流
@@ -112,8 +126,8 @@ llmdoc/
 └── investigations/       # 临时调查草稿
 ```
 
-`llmdoc/index.md` 是全局文档地图。
-`llmdoc/startup.md` 只负责启动阅读顺序。
+`llmdoc/index.md` 是有固定预算的全局路由。
+`llmdoc/startup.md` 只负责冷启动阅读顺序。
 两者可以互相链接，但不应该重复同一批内容。
 
 `.llmdoc-tmp/` 是本地临时 context cache。investigator 报告可以跨相邻会话保留，帮助减少重复调研，但它被 git 忽略、不会进入 index，也不是 source of truth。只有稳定、可复用的结论才应该提升到 tracked `llmdoc/` 文档里。
@@ -178,11 +192,13 @@ codex
   - [`skills/llmdoc/`](skills/llmdoc/)
   - [`skills/llmdoc-init/`](skills/llmdoc-init/)
   - [`skills/llmdoc-update/`](skills/llmdoc-update/)
+  - [`hooks/hooks.json`](hooks/hooks.json)，插件内置的生命周期感知 `SessionStart` hook
   - [`.agents/plugins/marketplace.json`](.agents/plugins/marketplace.json)，作为 repo 级本地 marketplace 示例
 - 这个仓库自己的 repo-local Codex 工作流文件：
   - [`.codex/config.toml`](.codex/config.toml)
   - [`.codex/agents/`](.codex/agents)
   - [`skills/llmdoc/templates/codex-hooks.json`](skills/llmdoc/templates/codex-hooks.json)
+  - [`skills/llmdoc/templates/compact-prompt.md`](skills/llmdoc/templates/compact-prompt.md)
 
 #### 方式一：从 GitHub 安装（推荐）
 
@@ -198,7 +214,8 @@ codex plugin marketplace add TokenRollAI/llmdoc
 2. 在 Codex 中执行 `/plugins`
 3. 在插件列表中找到 `llmdoc`，选中进入详情页
 4. 安装插件
-5. 在任意仓库里新开一个对话，然后按你的目标选择入口：
+5. 在 `/hooks` 中检查并信任插件内置的生命周期 hook
+6. 在任意仓库里新开一个对话，然后按你的目标选择入口：
    - 正常工作时，让 Codex 先加载 `llmdoc` skill
    - 要执行 `/llmdoc:init` 等价流程时，选择 `llmdoc-init`
    - 要执行 `/llmdoc:update` 等价流程时，选择 `llmdoc-update`
@@ -219,7 +236,9 @@ codex plugin marketplace add TokenRollAI/llmdoc
    - 要执行 `/llmdoc:init` 等价流程时，选择 `llmdoc-init`
    - 要执行 `/llmdoc:update` 等价流程时，选择 `llmdoc-update`
    - 或者输入 `@`，再显式选择这个插件或它打包进来的 skill
-8. 如果你需要 hooks，把 [`skills/llmdoc/templates/codex-hooks.json`](skills/llmdoc/templates/codex-hooks.json) 复制到 `.codex/hooks.json`，再按你的机器路径调整脚本路径
+8. 在 `/hooks` 中检查并信任插件内置 hook。如果你更希望使用 repo-local hook，可以把 [`skills/llmdoc/templates/codex-hooks.json`](skills/llmdoc/templates/codex-hooks.json) 复制到 `.codex/hooks.json`，再按机器路径调整脚本；不要同时启用两份
+
+compact-prompt 模板是可选增强，因为配置 `compact_prompt` 或 `experimental_compact_prompt_file` 会覆盖 Codex 内置 compaction prompt。只有在需要更强的 `LLMDOC_STATE` 结构保证，并愿意随 Codex 演进持续检查模板时才启用。
 
 当你打开的就是这个仓库时，Codex 还会同时使用 [`.codex/agents/`](.codex/agents) 里的 project-scoped agents，以及 [`.codex/config.toml`](.codex/config.toml) 里的 agent 限制配置。
 
@@ -229,6 +248,7 @@ codex plugin marketplace add TokenRollAI/llmdoc
 Codex helper 入口 skills 位于 [`skills/llmdoc-init/SKILL.md`](skills/llmdoc-init/SKILL.md) 和 [`skills/llmdoc-update/SKILL.md`](skills/llmdoc-update/SKILL.md)。
 详细参考文档位于 [`skills/llmdoc/references/`](skills/llmdoc/references/)。
 Codex CLI hooks 模板位于 [`skills/llmdoc/templates/`](skills/llmdoc/templates/)。
+插件内置的 Codex hook 位于 [`hooks/hooks.json`](hooks/hooks.json)。
 
 ## Codex Subagents
 

agents/recorder.md

@@ -41,7 +41,7 @@ Commit watermark ownership (`llmdoc/state/sync.md`):
 
 llmdoc categories:
 
-- `/must/`: Tiny startup documents that should be read on every run. Only recurring, cross-task, stable knowledge belongs here.
+- `/must/`: Tiny startup documents read once on cold start. Only recurring, cross-task, stable knowledge belongs here.
 - `/overview/`: Identity, boundaries, and role of the project or a large feature.
 - `/architecture/`: Retrieval maps, ownership boundaries, flows, and invariants.
 - `/guides/`: One workflow per document.
@@ -60,6 +60,8 @@ Index rules:
 
 - `llmdoc/index.md` is the global map of the documentation system.
 - `llmdoc/startup.md` is only the startup reading order for must-read docs.
+- Keep `index.md` + `startup.md` + `must/` under 24 KiB by default.
+- In a monolith, keep the root index as an L0 router and point it at subsystem indexes instead of listing every leaf document.
 - Do not duplicate the global category catalog inside `startup.md`.
 - Do not duplicate the detailed startup reading order inside `llmdoc/index.md`.
 
@@ -72,6 +74,7 @@ Split rules:
 - If a document grows large only because it is preserving one coherent execution model, invariant set, or contract cluster, keep it intact until a clean split is obvious.
 - If a document exceeds roughly 120 lines, covers more than one workflow, or mixes stable facts with transient notes, split it when doing so improves retrieval without discarding essential reasoning flow.
 - Do not promote content into `/must/` unless it is stable, short, and useful on nearly every task.
+- After context compaction, preserve and use `LLMDOC_STATE`; do not replay the startup pack merely because compaction occurred.
 
 Reference policy: