feat: 基于 commit 水位线的 /llmdoc:update（多批变更检测）

.claude-plugin/marketplace.json

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

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "llmdoc",
-  "description": "llmdoc Claude Code plugin with init, update modes, temporary investigation cache, and use",
-  "version": "2.1.0",
+  "description": "llmdoc Claude Code plugin with init, commit-watermark update detection, update modes, temporary investigation cache, and use",
+  "version": "2.2.0",
   "author": {
     "name": "DJJ & Danniel"
   }

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "llmdoc",
-  "version": "2.1.0",
-  "description": "Doc-driven workflow with startup docs, update modes, temporary investigation cache, and reusable skills for Codex.",
+  "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.",
   "author": {
     "name": "DJJ & Danniel",
     "email": "shuaiqijianaho@qq.com",
@@ -13,7 +13,7 @@
   "interface": {
     "displayName": "llmdoc",
     "shortDescription": "Doc-driven coding workflow",
-    "longDescription": "Use startup docs, guides, update modes, temporary investigation cache, and focused reflections to improve coding quality and reduce repeated work.",
+    "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.",
     "developerName": "TokenRoll",
     "category": "Productivity",
     "capabilities": ["Read", "Write"],

.codex/agents/llmdoc-investigator.toml

@@ -18,6 +18,8 @@ Then follow this protocol:
 - Prefer file-level and symbol-level references.
 - Only add line numbers when needed to prove subtle or disputed behavior.
 - If asked to write findings to disk, write temporary scratch reports under .llmdoc-tmp/investigations/.
+- When invoked for /llmdoc:update, work from the precomputed net-diff path list (git diff --name-status -M -C) instead of re-deriving the change set; consult per-commit history only to explain intent, never as doc content.
+- In file reports, record the resolved commit range and watermark in the metadata (Range:, Watermark:) so a report is reused only when the current range is a subset of the report's range.
 - Do not silently redesign the system. Return evidence, findings, gaps, and recommended next reads.
 """
 nickname_candidates = ["Scout", "Trace", "Atlas"]

.codex/agents/llmdoc-recorder.toml

@@ -18,5 +18,10 @@ Your responsibilities:
 - Promote only recurring, stable lessons into must/, guides/, or reference/.
 - Do not paste large code blocks.
 - Prefer file-level and symbol-level references.
+- You are the sole writer of llmdoc/index.md and llmdoc/state/sync.md (the commit watermark) for a run.
+- Reason from the NET diff and read committed-batch content at the BATCH TIP (git show <tip>:<path>), never from HEAD or disk, except the uncommitted working-tree set. Never document an intermediate state absent at the tip.
+- Advance watermark-commit only as the terminal step of a complete, successful update that consumed a committed range; rewrite only watermark-commit, watermark-subject, and updated-at/by.
+- NEVER advance on a --working-tree-only run, a failed/partial run, a HEAD-behind-watermark run, or while a git operation is in progress or HEAD is detached.
+- Do not index .llmdoc-tmp/, and keep llmdoc/state/sync.md out of llmdoc/index.md, startup.md, and MUST; it is machine-managed state, not knowledge.
 """
 nickname_candidates = ["Ledger", "Archive", "Quill"]

.codex/agents/llmdoc-reflector.toml

@@ -14,6 +14,7 @@ Your responsibilities:
 - Write concise reflections to llmdoc/memory/reflections/.
 - Capture what went wrong, why it happened, what docs or signals were missing, and what may deserve promotion.
 - Do not rewrite stable architecture docs here.
+- You may read per-commit history (git log, git show, git log --first-parent to cut side-branch noise) over the synced range to capture WHY a change happened and spot reversals or rework; on a merge-base-recovered baseline, ignore commits older than the previous watermark. Per-commit history explains why; it never decides which stable docs change.
 - Leave compact, reusable learning artifacts.
 """
 nickname_candidates = ["Echo", "Pulse", "North"]

.codex/agents/llmdoc-worker.toml

@@ -17,5 +17,6 @@ Operate with these rules:
 - If you enter a new subsystem or hit a failure, re-read relevant docs before expanding code search.
 - Use guides and reflections proactively to improve quality.
 - Hand off mistakes, surprises, missing docs, and workflow gaps for reflection.
+- Never edit llmdoc/index.md or llmdoc/state/sync.md; recorder is their sole writer.
 """
 nickname_candidates = ["Forge", "Brick", "Delta"]

README.md

@@ -70,21 +70,25 @@ In Codex, use the helper skill `llmdoc-update` for the equivalent workflow.
 
 The command keeps tracked `llmdoc/` docs consistent with the current repository. Stable docs should stay compact: either smaller than the source they describe or useful because they explain architecture, implementation intent, boundaries, and stable contracts.
 
-The command selects the lightest mode that can keep docs correct:
+Change detection is **commit-based**. A tracked watermark, `llmdoc/state/sync.md`, records the last source commit already reflected in `llmdoc/`. By default the command diffs `watermark..HEAD` (the net change across every commit since the last sync) and advances the watermark on success. Uncommitted working-tree changes are folded in as an additional input but never move the watermark.
 
-- `fast`: default for immediate post-implementation updates when the coordinating assistant has fresh context
-- `analysis`: one focused evidence pass for stale context, current-state research, or unclear impact
-- `full`: separate investigation, reflection, and recording when risk or process learning justifies the extra independence
+It can ingest multiple commit batches in one run — `--range A..B` (repeatable), `--commits SHA,…`, `--since REF`, `--from SHA`, `--working-tree-only` — and degrades gracefully on non-git projects, shallow clones, a first run with no watermark, and rebased/orphaned watermarks.
+
+The command selects the lightest mode that can keep docs correct, keyed on range size × authorship × risk:
+
+- `fast`: a small, self-authored range with nameable impacted docs
+- `analysis`: a larger range, any non-self-authored commit, or a recovered/first-run baseline — one focused evidence pass
+- `full`: large or high-risk ranges, multi-batch backfill, or history-rewrite recovery — separate investigation, reflection, and recording
 
 The command:
 
-1. Rebuilds context from llmdoc and the current working tree
+1. Reads the watermark and computes the commit range (plus any batch flags and the working tree)
 2. Proactively reads relevant guides and reflections
-3. Chooses an update mode
+3. Chooses an update mode from range size, authorship, and risk
 4. Investigates impacted concepts only when the selected mode requires it
 5. Writes a reflection under `llmdoc/memory/reflections/` only when there is a workflow lesson or missing-doc signal
 6. Updates stable docs and reconciles `llmdoc/memory/doc-gaps.md`
-7. Synchronizes `llmdoc/index.md`
+7. Synchronizes `llmdoc/index.md` and advances the watermark on success
 
 In normal use, the main assistant should proactively ask whether to run `/llmdoc:update` when the task produced durable knowledge or a useful reflection.
 

README.zh-CN.md

@@ -70,21 +70,25 @@
 
 这个命令会让 tracked `llmdoc/` 文档和当前仓库保持一致。稳定文档应该保持紧凑：要么比它描述的源码更小，要么能解释源码搜索无法快速提供的架构、实现意图、边界和稳定契约。
 
-这个命令会选择能保证文档正确的最轻模式：
+变更检测是**基于 commit** 的。一个被 git 跟踪的水位线 `llmdoc/state/sync.md` 记录 `llmdoc/` 已反映到的最后一个 source commit。默认对 `水位线..HEAD` 做 diff（自上次同步以来所有提交的净变更），成功后推进水位线。未提交的工作树变更作为附加输入纳入，但永不移动水位线。
 
-- `fast`：默认模式，适合主 assistant 刚完成实现、上下文仍然新鲜的情况
-- `analysis`：适合上下文变旧、需要调研当前现状、或影响范围不清时的一次聚焦证据 pass
-- `full`：适合风险较高、事实有争议、或确实需要独立反思与复核的情况
+它可以在一次运行里吞掉多批 commit —— `--range A..B`（可重复）、`--commits SHA,…`、`--since REF`、`--from SHA`、`--working-tree-only` —— 并在非 git 项目、shallow clone、首次运行无水位线、rebase/孤儿水位线等情况下优雅降级。
+
+这个命令会选择能保证文档正确的最轻模式，触发器是 范围大小 × 作者归属 × 风险：
+
+- `fast`：小范围、自己作者、受影响文档可点名
+- `analysis`：较大范围、含任一他人提交、或恢复/首次运行的 baseline —— 一次聚焦证据 pass
+- `full`：大范围或高风险、多批回填、或历史重写恢复 —— 独立的调研、反思与记录
 
 这个命令会：
 
-1. 基于 llmdoc 和当前 working tree 重建上下文
+1. 读水位线并计算 commit 范围（外加任何批次 flag 与工作树）
 2. 主动阅读相关 guides 和 reflection
-3. 选择 update mode
+3. 基于范围大小、作者归属、风险选择 update mode
 4. 只在所选模式需要时调研受影响的概念
 5. 只有出现工作流教训或缺失文档信号时，才在 `llmdoc/memory/reflections/` 下写 reflection
 6. 更新稳定文档，并清账 `llmdoc/memory/doc-gaps.md`
-7. 同步 `llmdoc/index.md`
+7. 同步 `llmdoc/index.md`，并在成功后推进水位线
 
 在日常使用里，如果任务产生了值得长期保留的知识或反思，主 assistant 应该主动询问是否现在运行 `/llmdoc:update`。
 

agents/investigator.md

@@ -28,7 +28,8 @@ Key practices:
 - **Objective:** Report facts and evidence, not design opinions.
 - **Split by sink:** `sink=chat` is for direct answers. `sink=file` is for temporary scratch artifacts, usually under `.llmdoc-tmp/investigations/`.
 - **Temporary means temporary:** `.llmdoc-tmp/` may persist across sessions, but it is ignored by git, not indexed by `llmdoc/index.md`, and can be deleted at any time.
-- **Make reuse safe:** File reports should record date, git revision when available, evidence scope, unresolved gaps, and whether the report is safe to reuse.
+- **Make reuse safe:** File reports should record date, git revision when available, the resolved commit range and watermark when the task is an update, evidence scope, unresolved gaps, and whether the report is safe to reuse. A report is reusable only if the current resolved range is a subset of the report's range.
+- **Update input:** When invoked for `/llmdoc:update`, work from the precomputed net-diff path list (`git diff --name-status -M -C`) instead of re-deriving the change set. Consult per-commit history only to explain intent, never as doc content.
 - **No long code pastes:** The reader can open source files directly.
 
 <InputFormat>
@@ -73,6 +74,8 @@ Write a markdown file using the same section layout as `<OutputFormat_Chat>`, pl
 
 - Date:
 - Git Revision:
+- Range:
+- Watermark:
 - Evidence Scope:
 - Reuse Conditions:
 

agents/recorder.md

@@ -28,9 +28,17 @@ Consistency rules:
 - Correct or remove stable-doc claims that no longer match the current code.
 - Do not preserve stale facts just because they were previously documented.
 - Do not add volatile counts, line totals, or incidental implementation inventory unless they are part of a stable contract.
-- Do not index `.llmdoc-tmp/`.
+- Do not index `.llmdoc-tmp/`, and do not index `llmdoc/state/sync.md` as knowledge.
 - Reconcile `memory/doc-gaps.md` during non-trivial updates: close resolved gaps, mark stale gaps, and add only actionable gaps with closure criteria.
 
+Commit watermark ownership (`llmdoc/state/sync.md`):
+
+- You are the sole writer of `llmdoc/index.md` and `llmdoc/state/sync.md` for a run.
+- Reason from the NET diff and read committed-batch content at the BATCH TIP (`git show <tip>:<path>`), never from HEAD or disk — except the uncommitted working-tree set, which is read from disk. Never document an intermediate state absent at the tip.
+- Advance `watermark-commit` only as the terminal step of a complete, successful update that consumed a committed range; rewrite only `watermark-commit`, `watermark-subject`, and `updated-at/by`.
+- NEVER advance on a `--working-tree-only` run, a failed/partial run, a HEAD-behind-watermark run, or while a git operation is in progress or HEAD is detached.
+- Keep `llmdoc/state/sync.md` out of `llmdoc/index.md`, `startup.md`, and the MUST pack; it is machine-managed state, not knowledge.
+
 llmdoc categories:
 
 - `/must/`: Tiny startup documents that should be read on every run. Only recurring, cross-task, stable knowledge belongs here.

agents/reflector.md

@@ -23,6 +23,7 @@ Reflection rules:
 - Record what went wrong, why it went wrong, and how to avoid it next time.
 - Keep each reflection focused on one task.
 - Do not rewrite stable architecture docs here.
+- You may read per-commit history (`git log`, `git show`, `git log --first-parent` to cut side-branch noise) over the synced range to capture WHY a change happened and spot reversals or rework. On a merge-base-recovered baseline, ignore commits older than the previous watermark. Per-commit history explains why; it never decides which stable docs change.
 
 <ReflectionFormat>
 # [Task Reflection]

agents/worker.md

@@ -25,6 +25,7 @@ Key practices:
 - Add line numbers only when necessary to justify a non-obvious behavior.
 - Do not pause to discuss with the user. Coordination belongs to the calling assistant.
 - Do not write reflection files yourself. Hand off facts for `reflector`.
+- Never edit `llmdoc/index.md` or `llmdoc/state/sync.md`; `recorder` is their sole writer.
 
 <InputFormat>
 - **Objective**: What needs to be accomplished.

commands/init.md

@@ -30,7 +30,9 @@ Why:
      - `llmdoc/reference/`
      - `llmdoc/memory/reflections/`
      - `llmdoc/memory/decisions/`
+     - `llmdoc/state/sync.md`
      - `.llmdoc-tmp/investigations/`
+   - Seed the commit watermark in `llmdoc/state/sync.md` (template in `skills/llmdoc/references/templates.md`): set `watermark-commit` to `$(git rev-parse HEAD)`, so the first `/llmdoc:update` has a valid anchor. Skip this in a non-git project. `llmdoc/state/sync.md` is machine-managed state, not knowledge: never index it or add it to `startup.md`/`must/`.
 
 3. Run investigation.
    - Use `investigator` for evidence gathering.