Status: Planning
Current stage: Spec review
Next stage: Split implementation tickets
背景
llmdoc 的初心，是为当前工程提供一套可持久化、可检索、可同步的外置上下文，让 Assistant 不必在每次会话中重新理解整个代码仓库。
经过多次迭代，当前实现逐渐出现了一些结构性问题：
- Command、Skill、Agent、Reference 和 Hook 中重复维护相同业务 Prompt；
- Prompt 总量持续增长，职责边界不够清晰；
startup.md、must/、memory/ 等固定加载结构容易侵占上下文；- 文档可以持续增加，但缺少完整的收敛和瘦身机制；
- 文档与源码主要通过全局 commit watermark 同步，难以精确判断单份文档的有效性；
- Claude 与 Codex 的封装存在重复维护和行为漂移风险；
- 单次任务 Reflection 与跨案例可复用经验混在一起，容易污染成熟知识。
V3 将进行一次彻底重构，而不是继续在现有 Prompt 和目录上做增量修补。
目标
V3 要建立一套以 Domain 为核心、由结构化 Runtime 支撑、可渐进读取并能持续收敛的工程知识系统：
- 保持 llmdoc“工程持久化外置上下文”的单一产品定位；
- 大幅减少重复 Prompt 和普通任务的上下文占用；
- 使用一套 canonical source 构建 Claude/Codex 两个平台原生插件；
- 让文档与代码建立可验证的精确关联；
- 支持轻量定向更新与重度调查更新；
- 在知识持续增长后主动建议并执行无损瘦身；
- 对正式知识写入提供事务、并发检测和失败恢复；
- Compact 后在状态仍有效时继续任务，不重新加载已有 llmdoc 上下文。
最终产品形态
用户命令
核心命令只保留：
init：为没有 llmdoc 的项目首次建立工程知识；update：根据 llmdoc 历史有效版本与当前代码差异同步知识；prune：合并、压缩和清理持续膨胀的成熟知识。
另提供一个完全隔离、只允许显式调用的低频命令：
upgrade：迁移旧 major schema，不进入普通开发上下文。
内部 Agent
investigator：调查代码、配置和变更，形成临时调研证据；reflector：收集对话案例和用户反馈，形成临时 Reflection candidate；recorder：正式 llmdoc/ 与 meta.json 的唯一知识写入者。
通用代码 Worker 不再属于 llmdoc。
生成的文档结构
llmdoc/
├── meta.json
└── <domain-id>/
├── domain.md
├── architecture/
├── guides/
├── reference/
├── decisions/
└── reflections/
V3 将移除：
- 根
index.md；
startup.md；must/；overview/；memory/；domains/ + project/ 双层范围划分。
每份 Markdown 使用 YAML Front matter 保存文档 ID、description、kind、Domain、文档关系和代码关联；正文只保存成熟工程知识。
目录图与文档图由 Runtime 从文件树和 Front matter 实时构建，不在 meta.json 中保存重复副本。
核心行为
渐进读取
文件树
→ 批量 Domain metadata
→ 批量文档 metadata
→ 少量正文与关联源码
Assistant 决定发散方向，Runtime 负责批量读取、预算、分页和关系图。
Update
Update 基于 meta.json 中的历史 source fingerprints、当前代码状态和 Front matter code relations 计算影响闭包：
light：影响明确，Runtime delta 直接交给 Recorder；deep：存在未映射代码、跨 Domain 影响、结构变化或证据冲突，先由 Investigator 调查。
Reflector 不再因为 Update 规模较大而自动运行。
局部 Update 可以更新目标文档，但不能推进表示全仓已经同步的 repository baseline。
Prune
Update 完成后，Runtime 将当前规模与最近一次成功 Init/Prune 的 convergence baseline 比较。命中 Growth Gate 时，主 Assistant 询问用户是否自动 Prune。
Prune 必须证明：
- 文档规模实际下降；
- 唯一约束、SOP、决策和因果没有丢失；
- code relation 覆盖不下降；
- 文档图没有悬空关系。
Prune 不是归档，也不会通过把文档移出正常读取路径来制造“变小”。
Reflection
未经验证的案例只保存在：
Reflector 先通过简短 description 进行相似性匹配。默认积累到三个经正文确认的相似案例后，才判断是否形成可复用模式。
成熟 Reflection 只能通过用户确认的 Update，由 Recorder 写入正式 Domain。
正式写入
所有 Init、Update、Prune 和 Reflection Promote 使用统一事务：
snapshot
→ stage
→ validate
→ concurrency check
→ commit
→ independent review
Markdown 与 meta.json 作为一个逻辑事务更新。失败或并发修改不得留下半完成状态。
仓库重构方向
src/ 核心逻辑、Prompt、Runtime、Schema、Hook 和 Adapter 的唯一手工维护源
upgrade/ 与核心上下文物理隔离的迁移子系统
tooling/ 构建、生成、校验和发布工具
tests/ Unit、Contract、Integration、Parity、Fixture 和 Snapshot
plugins/ 从 canonical source 生成并提交的 Claude/Codex 可安装插件
dist/ 发布压缩包，不提交 Git
Claude 与 Codex 使用各自原生安装文件树，但必须暴露等价的命令、Agent 角色、权限、Runtime contract 和 SOP。
非目标
本次重构不会把以下通用开发能力加入 llmdoc：
- Grill-me / Ask-User-Question；
- Just-Do-it / 通用执行循环；
- 通用 Plan、Ticket 或 Definition of Done 系统；
- 通用代码 Worker；
- 项目管理或 Code Review 能力。
这些能力属于宿主 Assistant 或独立 Skills。
实施阶段
本 Issue 只追踪 V3 里程碑状态。每个阶段会拆分成独立子 Issue，并在实现前定义逐步骤验收标准。
里程碑验收标准
交付流程
本里程碑按以下顺序推进：
grill-with-docs
→ to-spec
→ to-tickets
→ implement
→ code-review
每个实现 Ticket 必须在编码前定义每一步的验收流程、标准和证据。实现完成后，Code Review 将分别检查仓库规范、Spec 符合度和 Ticket DoD。
当前状态
后续所有 V3 子 Issue、Pull Request 和重要决策都应回链到本 Issue。
背景
llmdoc 的初心，是为当前工程提供一套可持久化、可检索、可同步的外置上下文，让 Assistant 不必在每次会话中重新理解整个代码仓库。
经过多次迭代，当前实现逐渐出现了一些结构性问题：
startup.md、must/、memory/等固定加载结构容易侵占上下文；V3 将进行一次彻底重构，而不是继续在现有 Prompt 和目录上做增量修补。
目标
V3 要建立一套以 Domain 为核心、由结构化 Runtime 支撑、可渐进读取并能持续收敛的工程知识系统：
最终产品形态
用户命令
核心命令只保留：
init：为没有 llmdoc 的项目首次建立工程知识；update：根据 llmdoc 历史有效版本与当前代码差异同步知识；prune：合并、压缩和清理持续膨胀的成熟知识。另提供一个完全隔离、只允许显式调用的低频命令：
upgrade：迁移旧 major schema，不进入普通开发上下文。内部 Agent
investigator：调查代码、配置和变更，形成临时调研证据；reflector：收集对话案例和用户反馈，形成临时 Reflection candidate；recorder：正式llmdoc/与meta.json的唯一知识写入者。通用代码 Worker 不再属于 llmdoc。
生成的文档结构
V3 将移除：
index.md；startup.md；must/；overview/；memory/；domains/ + project/双层范围划分。每份 Markdown 使用 YAML Front matter 保存文档 ID、description、kind、Domain、文档关系和代码关联；正文只保存成熟工程知识。
目录图与文档图由 Runtime 从文件树和 Front matter 实时构建，不在
meta.json中保存重复副本。核心行为
渐进读取
Assistant 决定发散方向，Runtime 负责批量读取、预算、分页和关系图。
Update
Update 基于
meta.json中的历史 source fingerprints、当前代码状态和 Front matter code relations 计算影响闭包：light：影响明确，Runtime delta 直接交给 Recorder；deep：存在未映射代码、跨 Domain 影响、结构变化或证据冲突，先由 Investigator 调查。Reflector 不再因为 Update 规模较大而自动运行。
局部 Update 可以更新目标文档，但不能推进表示全仓已经同步的 repository baseline。
Prune
Update 完成后，Runtime 将当前规模与最近一次成功 Init/Prune 的 convergence baseline 比较。命中 Growth Gate 时，主 Assistant 询问用户是否自动 Prune。
Prune 必须证明：
Prune 不是归档，也不会通过把文档移出正常读取路径来制造“变小”。
Reflection
未经验证的案例只保存在：
Reflector 先通过简短 description 进行相似性匹配。默认积累到三个经正文确认的相似案例后，才判断是否形成可复用模式。
成熟 Reflection 只能通过用户确认的 Update，由 Recorder 写入正式 Domain。
正式写入
所有 Init、Update、Prune 和 Reflection Promote 使用统一事务：
Markdown 与
meta.json作为一个逻辑事务更新。失败或并发修改不得留下半完成状态。仓库重构方向
Claude 与 Codex 使用各自原生安装文件树，但必须暴露等价的命令、Agent 角色、权限、Runtime contract 和 SOP。
非目标
本次重构不会把以下通用开发能力加入 llmdoc：
这些能力属于宿主 Assistant 或独立 Skills。
实施阶段
本 Issue 只追踪 V3 里程碑状态。每个阶段会拆分成独立子 Issue，并在实现前定义逐步骤验收标准。
src/、构建系统和生成边界meta.json、fingerprint、delta 和事务 Runtime里程碑验收标准
init/update/prune，Upgrade 保持隔离且只能显式调用meta.json的唯一知识写入者meta.json不保存目录 catalog、当前文档图或会话状态交付流程
本里程碑按以下顺序推进：
每个实现 Ticket 必须在编码前定义每一步的验收流程、标准和证据。实现完成后，Code Review 将分别检查仓库规范、Spec 符合度和 Ticket DoD。
当前状态
后续所有 V3 子 Issue、Pull Request 和重要决策都应回链到本 Issue。