dsh-todo-ledger 0.0.0-stage → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.1] - 2026-10-24
+
+A follow-up on the floating window: its surface now matches the host's own floating panels, and the
+status colours are the ones the panel has always used.
+
+### Fixed
+
+- **The window surface no longer reads as a lighter grey than everything around it.** It used
+  `--dsw-alias-bg-overlay`, which resolves to a mid grey in the dark theme. It now takes the raised
+  layer the host's own floating panels use: `--dsw-alias-bg-layer-1`, a `--dsw-alias-border-l2`
+  border, a 14px radius and the same two-layer shadow.
+
+### Changed
+
+- **Status colours are the previous palette again** — blue in progress, slate to do, violet awaiting
+  review, red blocked. Only the accept action and error text use the host state tokens.
+- Count chips and task rows stay on `--dsw-alias-bg-layer-2` with a `--dsw-alias-border-l1` border,
+  and section titles, slugs and the footer use `--dsw-alias-label-secondary`.
+
+### Added
+
+- A storefront icon (`assets/icon-180.png`, rendered from `assets/icon.svg`) and `screenshots.json`
+  declaring the sidebar and floating-window captures.
+- Install-from-npm instructions in both READMEs, plus the npm version badge.
+
+## [0.3.0] - 2026-10-24
+
+The release that gives the ledger a window of its own, and keeps every view on the session you are
+actually looking at.
+
+### Added
+
+- **Floating ledger window.** A `Todo` control under the composer opens a frame-wide window with the
+  same sections and sign-off action as the sidebar panel. Drag its header to move it, drag the
+  bottom-right grip to resize it (240×180 minimum, clamped to the viewport), and the box is restored
+  the next time it opens. Only the task list scrolls, so the counts row and the footer stay put however
+  long the queue gets.
+- **Collapsible status groups.** Click a group header to fold it. Clicking a status count expands that
+  group and aligns its header to the top of the list, which keeps a long queue navigable without
+  dragging the chat page behind the window.
+- **The window follows the session in front.** Switching sessions re-targets an open floating window
+  to the new session's workspace instead of leaving it on the session that opened it.
+
+### Changed
+
+- The floating window starts at its status counts: the duplicate plugin name and in-body collapse from
+  the previous iteration are gone, because its own header already names the panel.
+- The composer control reads as a plain dock item (`Todo`, the book icon, dock font and hover
+  treatment) rather than a filled chip.
+
+### Fixed
+
+- The sidebar panel kept showing the previous ledger after switching to a session in another
+  workspace: the tab registration froze the session injected when it was created. It now reads the
+  session the slot dispatches, keeps one resource and one request per session, and re-reads when the
+  window comes back into focus.
+
+## [0.2.0] - 2026-10-24
+
+The release that turns the ledger from a prompt-only capability into something you can watch and
+sign off without leaving the conversation.
+
+### Added
+
+- **Sidebar ledger panel.** A read-only tab in the right sidebar shows the ledger of the current
+  session's working directory: `doing`, `todo`, `review` and `blocked` sections with counts, a
+  colour per state, and a fixed order so the shape of the queue reads at a glance. It opens from the
+  sidebar guide capsule and polls only while visible.
+- **Sign a review task off from the panel.** Each task under `review` carries an accept action; it
+  archives through the same path as `todo_complete` and records the click as both evidence and
+  sign-off (`accepted from the ledger panel at <ISO timestamp>`). Only `review` tasks can be accepted
+  this way; other states are refused with an inline error.
+- **Host routes for the panel:** `GET /todo-ledger/projection?sessionId=…` returns the ledger
+  projection, and `GET /todo-ledger/complete?slug=…&sessionId=…` performs the single side-effecting
+  call. Both are registered as `prefix` routes and dispatched as `GET`, which is what the host's
+  plugin route layer supports.
+- **Dependencies between tasks.** `todo_add` now accepts `depends_on` and `blocker_cause`; a task
+  whose predecessors are not yet finished is created as `blocked` with the dependency recorded, and
+  is created directly as `todo` when they already are. Unknown, dropped, self-referential and
+  circular predecessors are rejected.
+- **Automatic unblocking on formal completion.** Completing a predecessor through `todo_complete` (or
+  the panel) promotes its dependents to `todo` once *all* predecessors are formally completed. A
+  `review` state, a dropped archive, or a manual blocker never unblocks anything, and hand-edited
+  state cannot fake it.
+
+### Changed
+
+- The prompt section's hand-edit ban now names the three tool-owned surfaces explicitly — the status
+  lines in `todo.md`, the `tasks.md` index, and a task file's frontmatter — and points at
+  `todo_doctor` when they disagree, instead of the earlier catch-all wording.
+- `README.md` and `README_zh.md` gained a sidebar panel section covering the opt-in entry point,
+  section ordering, visible-only polling, what acceptance records, and the restart/refresh boundary.
+
+### Fixed
+
+- Registering the ledger no longer takes the session down when one of its parts fails; the feature
+  degrades instead, and the failing file and line are named.
+- The prompt section no longer breaks session startup when a ledger file contains a `{{`-like
+  literal (such as another plugin's macro shell); such braces are rendered inert.
+- Agent-written ledger content that would corrupt the state machine is flagged for rewrite instead
+  of being written silently.
+- The accept call no longer fails with `HTTP 405`: the client sends `GET` with query parameters, and
+  the handler acts on whichever carrier holds the slug.
+
+## [0.1.0]
+
+First release: the resident prompt section, the eleven `todo_*` tools, the ledger file format
+(`_todo/` preferred, legacy `todo/` supported), and the `context/` retention files.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,259 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-todo-ledger
+
+[![release](https://img.shields.io/github/v/release/haruri03/dsh-todo-ledger?sort=semver)](https://github.com/haruri03/dsh-todo-ledger/releases) [![npm](https://img.shields.io/npm/v/dsh-todo-ledger)](https://www.npmjs.com/package/dsh-todo-ledger) [![license](https://img.shields.io/github/license/haruri03/dsh-todo-ledger)](LICENSE)
+
+[English](README.md) | [中文](README_zh.md)
+
+Repository: https://github.com/haruri03/dsh-todo-ledger
+
+A host-level DSH plugin that turns the todo ledger workflow into a resident prompt section,
+a set of native tools, and context stored inside the repository's `_todo/` directory.
+
+It addresses the failure mode where rules live in a skill or `AGENTS.md`, the model forgets to
+read them, and the task list has to be rewritten every turn:
+
+| Before | This plugin |
+|---|---|
+| Rules live in `AGENTS.md` / a skill and stop working when the model does not read them | A host-level `systemPrompt.section` is present every step of every session, with no load step to forget |
+| The system `todo_write` list is overwritten each turn and progress is lost | Authoritative state lives in the repository's `_todo/` files and survives sessions and compaction |
+| Context exists only in conversation history and disappears after compaction | `todo_checkpoint` / `todo_note` write conclusions and next steps into `_todo/context/`, and a snapshot is injected on every prompt assembly |
+| The model has to assemble shell commands itself | 11 native tools with schema validation and readable errors |
+
+The file format is fully compatible with an external todo CLI: the plugin and the original CLI can
+both write the same repository and both can run `doctor` on it.
+
+## Install (manual)
+
+Choose one:
+
+**Human**: copy this directory to `$HOME/.dsh/profiles/<profile>/node_modules/dsh-todo-ledger`,
+then append this row to the profile's `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: todo-ledger
+      name: './lib/index.js'
+```
+
+**Agent**: run `plugin_manager install_bundle --target "<path-to-plugin>"`.
+
+### Install from Git
+
+When the repository root is the package (it contains `package.json` and `dsh.bundle`), install it
+directly from its Git URL:
+
+```powershell
+plugin_manager install_bundle --target "git+https://github.com/haruri03/dsh-todo-ledger.git"
+```
+
+The same operation is available to humans through the Web plugin page ("Add plugin") or the CLI:
+
+```powershell
+dsh plugin --profile <profile> add "git+https://github.com/haruri03/dsh-todo-ledger.git"
+```
+
+### Install from npm
+
+The package is published as `dsh-todo-ledger`, so the npm name alone installs it:
+
+```powershell
+plugin_manager install_bundle --target "dsh-todo-ledger"
+```
+
+```powershell
+dsh plugin --profile <profile> add dsh-todo-ledger
+```
+
+Tarball URLs are accepted too. To update, remove and reinstall, or wait for an upstream release.
+
+After installation, every new session carries a `[todo-ledger · cross-session tasks and context]`
+prompt section, and the tool list gains:
+
+`todo_list / todo_add / todo_show / todo_status / todo_complete / todo_archive / todo_note / todo_checkpoint / todo_snapshot / todo_doctor / todo_init`
+
+No restart is required.
+
+## Layout
+
+Inside the repository root (the directory that contains `_todo/`; a repository that already keeps `todo/` keeps working, the plugin accepts either name):
+
+```
+_todo/
+├── todo.md              queue: `- [status] slug`
+├── tasks.md             index: `- [status] **slug** — title → [details](tasks/slug.md)`
+├── tasks/<slug>.md      details: goal / subtasks / acceptance / progress / blockers / files
+├── archived/<slug>.md   completed + ## Delivery record (includes the sign-off quote)
+├── AGENTS.md            directory notes generated by todo_init
+└── context/             added by this plugin
+    ├── now.md           current goal / next step / key files (overwritten by todo_checkpoint)
+    └── log.md           append-only log (automatic tool trace + todo_note)
+```
+
+States are `todo` / `doing` / `blocked` / `review`; there is no `done`. `review` means work is
+finished and waiting for the owner's sign-off. Closing a task requires both `evidence` and
+`signoff` (the owner's own words); neither may be omitted. This is a hard rule of the todo ledger
+workflow.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `todo_list` | List tasks and states (optionally filtered); call it before starting work |
+| `todo_show` | Show one task's details |
+| `todo_add` | Create a task (unique kebab-case slug) |
+| `todo_status` | Change state and sync the task frontmatter, index, and queue |
+| `todo_complete` | Close and archive a task; requires `evidence` + `signoff` |
+| `todo_archive` | Abandon a task; additionally requires `reason` |
+| `todo_note` | Append to `context/log.md`; with `slug`, insert at the end of that task's `## Progress` section (the placeholder is removed on first write); with `state`, advance the state machine in the same call |
+| `todo_checkpoint` | Overwrite `context/now.md`: current goal / next step / key files |
+| `todo_snapshot` | Read-only: return the snapshot that would be injected into the prompt (check whether the ledger is stale) |
+| `todo_doctor` | Two-way consistency check; returns errors and warnings |
+| `todo_init` | Create the `_todo/` skeleton (only when the user asks) |
+
+Every tool accepts an optional `root`, so it can operate on repositories outside the workspace:
+
+`todo_doctor { root: "<repo-root>" }`.
+
+## Sidebar panel
+
+<img src="assets/sidebar-panel.png" width="420" alt="The sidebar ledger panel: in progress, to do, awaiting review with an Accept button, and blocked">
+
+The plugin also serves a sidebar panel for the ledger of the current session working directory:
+browsing is read-only, and the panel's only action is accepting a review task. It is opt-in: nothing is injected into the layout until a user opens the panel from the
+right sidebar's guide capsule (named after the plugin); it then renders as a sidebar tab.
+
+- Four sections — `doing`, `todo`, `review`, `blocked` — with a count each, plus a per-state colour
+  so the shape of the ledger reads at a glance.
+- Ordering is fixed: `doing` first, then `todo`, `review`, `blocked`; an empty section still shows.
+- The panel reads; it does not write task content. Polling runs only while the panel is visible
+  (every 5 s), so a closed or backgrounded tab costs nothing.
+- When a session has no ledger above its working directory, or the ledger files disagree, the panel
+  says so instead of guessing. Run `todo_doctor` to repair the latter.
+
+Each row under `review` carries an **accept** action. Accepting a review task from the panel archives
+it through the same path as `todo_complete`, recording the panel click as both the evidence and the
+sign-off (`accepted from the ledger panel at <ISO timestamp>`). Only `review` tasks can be accepted
+this way; any other state is refused with an inline error rather than an alarm.
+
+### Floating panel
+
+A book launcher below the composer opens a movable, resizable Todo Ledger floating panel. Drag
+its header to move it and drag the bottom-right grip to resize it. It is an additional way to view
+the ledger; the original right-sidebar panel remains available. The floating panel's labels follow
+the host locale, and its body starts directly with the status counts because the window header
+already names it. Every surface, border and state colour comes from the host theme tokens, so the
+window follows the active theme — light, dark or a custom one — instead of carrying its own palette.
+
+<img src="assets/floating-panel.png" width="360" alt="The floating ledger window: the same four sections, with the header used to drag it and the bottom-right grip used to resize it">
+
+Each status group is collapsible: click a group header to fold it. Clicking a status count expands
+that group and scrolls its header to the top of the list, which is how a long queue stays
+navigable. Only the task list scrolls; the counts row and the footer stay put.
+
+The panel is bound to the session it is shown in: switching to a session in another workspace
+re-reads that workspace's ledger instead of keeping the previous one, and returning focus to the
+window re-reads it again. The floating panel follows the session in front, so it re-targets when
+the session changes instead of staying on the one that opened it.
+
+The viewport-clamped box (position plus size) is saved in browser local storage and restored when
+the panel opens again. Visibility and ledger content are not saved there: opening the panel reads
+the current ledger rather than restoring a previous view.
+
+The panel talks to two host routes, both read-only in intent and dispatched as `GET`:
+
+| Route | Purpose |
+|---|---|
+| `/todo-ledger/projection?sessionId=<id>` | Ledger projection for that session's working directory |
+| `/todo-ledger/complete?slug=<slug>&sessionId=<id>` | Accept one `review` task; the only side-effecting call |
+
+A host restart is required after installing or updating the host-side code; the panel itself is plain
+client JavaScript shipped by the package, so it needs no build step and appears after a page refresh.
+
+## Dependencies
+
+Tasks can wait for other tasks. Pass `depends_on` (a list of slugs) to `todo_add`, and the task is
+created `blocked` with `blocker_cause: dependency` until every predecessor is **formally completed**.
+If the predecessors are already completed, the task is created as `todo` straight away.
+
+```mermaid
+graph LR
+  spec["Design the API contract<br/>todo"] --> impl["Implement the endpoint<br/>blocked"]
+  spec --> form["Wire the form to it<br/>blocked"]
+  impl --> notes["Draft the release notes<br/>blocked"]
+  form --> notes
+  legacy["Migrate the legacy config loader<br/>blocked, manual"]
+```
+
+Completing `spec` promotes `impl` and `form` to `todo` in the same call. `notes` stays blocked until
+both of its predecessors are completed — one is not enough. `legacy` has no predecessor: its
+`blocker_cause: manual` means nothing unblocks it automatically.
+
+- **Completion only.** A predecessor in `review` does not count; neither does an archived task that
+  was dropped instead of completed. Only `todo_complete` — or the panel's accept — unblocks.
+- **Validated at creation.** Unknown, already-dropped, self-referential and circular predecessors are
+  rejected, as is a `dependency` blocker with no predecessor.
+- **Repairable.** `todo_doctor` reports dependency fields that disagree with the archives.
+
+## How context survives
+
+1. On each system-prompt assembly the plugin finds the nearest `_todo/` above the session working
+   directory and injects:
+   - **Ledger last written: N ago** (the newest mtime among `context/log.md`, `tasks.md`, and `now.md`);
+   - **Session staleness**: how many tool calls happened since the last `todo_*` write and how many
+     of them were writes; 3 or more writes adds a ⚠ telling the agent to update the ledger first;
+   - **Task totals** (four states), **review items** (with `(Nd)` days waiting) and **blocked** slugs;
+   - **Progress of doing tasks**: the last real line of the task's `## Progress` section (≤80 chars);
+     the whole line is omitted when there is no progress; a state unchanged for 2+ days is marked
+     `state Nd unchanged`; template placeholders are filtered out;
+   - The body of `context/now.md` and the last 6 log entries.
+2. At every turn end (`agent/turn-stopping`) the plugin counts write-class operations per **turn
+   boundary**. At 3 or more it appends a factual log entry (tool calls / writes / state changes)
+   without inventing semantics. If the turn only wrote notes and never advanced a state, the entry
+   says the state machine did not advance. It deliberately does **not** measure from the last
+   `todo_*` write, because a final `todo_note` would reset the counter and hide a turn that edited
+   many files but left a single note.
+3. `todo_checkpoint` records conclusions, not long excerpts; `todo_note` records small findings;
+   writes append a trace automatically.
+4. After compaction, a new session, or a DSH restart, the next prompt still carries the snapshot,
+   so work can continue.
+5. Without a `_todo/` directory the plugin only injects the rules and mentions `todo_init`; it never
+   creates the directory on its own.
+
+> The unsolved half: the semantic summary is still written by the model. The plugin turns "the
+> ledger is stale" into a visible fact and a ⚠ instead of inventing conclusions for the model.
+
+## Configuration
+
+This row in `cordis.patch.yml` can be adjusted:
+
+```yaml
+- id: todo-ledger
+  name: './lib/index.js'
+  config:
+    root: "<repo-root>"                # optional: pin the repository root
+    sectionOrder: 180                  # prompt section order, default 180
+    maxSnapshotChars: 4000             # snapshot size limit, default 4000
+```
+
+Without `root`, the plugin searches upward from the session working directory for
+`_todo/tasks.md`; if that fails it uses the `TODO_ROOT` environment variable.
+
+## Verification
+
+```powershell
+node test/smoke.mjs
+```
+
+Coverage: prompt section registration and snapshot rendering, the schemas of all 11 tools, the full
+init → add → status → note → checkpoint → doctor → complete/archive flow, and rejection of a close
+without `signoff`. When `TODO_CLI` points at an external `todo.js`, the test also verifies
+`list`/`doctor` interoperability.
+
+## Uninstall
+
+```powershell
+plugin_manager remove_bundle --target dsh-todo-ledger
+```
+
+The plugin removes only its own registrations; the `_todo/` directory (including `context/`) is left
+untouched.

package/README_zh.md

@@ -0,0 +1,224 @@
+# dsh-todo-ledger
+
+[![release](https://img.shields.io/github/v/release/haruri03/dsh-todo-ledger?sort=semver)](https://github.com/haruri03/dsh-todo-ledger/releases) [![npm](https://img.shields.io/npm/v/dsh-todo-ledger)](https://www.npmjs.com/package/dsh-todo-ledger) [![license](https://img.shields.io/github/license/haruri03/dsh-todo-ledger)](LICENSE)
+
+[English](README.md) | [中文](README_zh.md)
+
+仓库：https://github.com/haruri03/dsh-todo-ledger
+
+把 **todo 账本工作流**做成 DSH 宿主级插件：
+**常驻提示段** + **原生工具** + **待办目录里的上下文留存**。
+
+它解决的是「靠 skill / AGENTS.md 提醒，模型容易忘、要在每轮重写清单」的问题：
+
+| 旧做法 | 这个插件 |
+|---|---|
+| 规则写在 AGENTS.md / skill 里，模型不读就失效 | 宿主级 `systemPrompt.section`，每个会话每步都在，不依赖模型记得加载 |
+| 用系统 `todo_write` 每轮覆盖式重写，进度丢失 | 权威状态落在仓库 `_todo/` 文件里，跨会话、跨压缩都在 |
+| 上下文只存在于对话历史，压缩后丢失 | `todo_checkpoint` / `todo_note` 把结论和下一步写进 `_todo/context/`，每次组装自动注入快照 |
+| 模型要自己拼 shell 命令 | 11 个原生工具，schema 校验、错误可读 |
+
+文件格式与外部 todo CLI **完全一致**，同一个仓库插件和原版 CLI 都能写、都能 `doctor`。
+
+## 安装（手动）
+
+任选其一：
+
+**人类**：把本目录复制到 `$HOME/.dsh/profiles/<profile>/node_modules/dsh-todo-ledger`，再在 profile 的 `cordis.patch.yml` 追加：
+
+```yaml
+- insert:
+    - id: todo-ledger
+      name: './lib/index.js'
+```
+
+**Agent**：让 agent 运行 `plugin_manager install_bundle --target "<path-to-plugin>"`。
+
+### 从 Git 自动安装
+
+仓库根就是包（含 `package.json` 与 `dsh.bundle`）时，可以直接用 Git 地址安装：
+
+```powershell
+plugin_manager install_bundle --target "git+https://github.com/haruri03/dsh-todo-ledger.git"
+```
+
+等价的人类操作：Web 插件页「添加插件」粘贴同一地址，或命令行：
+
+```powershell
+dsh plugin --profile <profile> add "git+https://github.com/haruri03/dsh-todo-ledger.git"
+```
+
+### 从 npm 安装
+
+包已发布为 `dsh-todo-ledger`，直接写包名即可：
+
+```powershell
+plugin_manager install_bundle --target "dsh-todo-ledger"
+```
+
+```powershell
+dsh plugin --profile <profile> add dsh-todo-ledger
+```
+
+也支持 tarball URL。更新时先卸载再安装，或等待上游发版。
+
+装好后新会话的系统提示里会出现「【todo-ledger · 跨会话任务与上下文】」段；工具列表里多出
+`todo_list / todo_add / todo_show / todo_status / todo_complete / todo_archive / todo_note / todo_checkpoint / todo_snapshot / todo_doctor / todo_init`。
+无需重启。
+
+## 目录与文件格式
+
+在仓库根（含 `_todo/` 的目录）下；已经用 `todo/` 的旧仓库继续可用，两个名字只认其一：
+
+```
+_todo/
+├── todo.md              队列：`- [status] slug`
+├── tasks.md             目录：`- [status] **slug** — 标题 → [详情](tasks/slug.md)`
+├── tasks/<slug>.md      详情：目标 / 子项 / 验收 / 进度 / 阻塞 / 相关文件
+├── archived/<slug>.md   结案 + ## 交付记录（含签收原话）
+├── AGENTS.md            todo_init 生成的目录说明
+└── context/             ← 本插件新增
+    ├── now.md           当前目标 / 下一步 / 关键文件（todo_checkpoint 覆盖写）
+    └── log.md           追加式流水（工具操作自动留痕 + todo_note）
+```
+
+状态只有 `todo` / `doing` / `blocked` / `review`；没有 `done`。`review` = 做完等负责人签收。
+结案必须带 `evidence` 与 `signoff`（负责人原话），缺一不可——这是 todo 账本工作流的硬规则。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `todo_list` | 列出任务与状态（可按状态筛），开工先调 |
+| `todo_show` | 看某任务详情 |
+| `todo_add` | 新建任务（slug kebab-case，唯一） |
+| `todo_status` | 改状态，同步详情 frontmatter / 索引 / 队列 |
+| `todo_complete` | 结案归档，必须 `evidence` + `signoff` |
+| `todo_archive` | 放弃归档，另需 `reason` |
+| `todo_note` | 往 `context/log.md` 追加流水；带 `slug` 时**插入该任务「## 进度」节末尾**（首次写入清掉模板占位句）；带 `state` 时**顺手推进状态机**（治“只 note 不改状态”） |
+| `todo_checkpoint` | 覆盖写 `context/now.md`：当前目标 / 下一步 / 关键文件 |
+| `todo_snapshot` | 只读：返回当前会注入提示词的那份快照（用来确认账本是不是又旧了） |
+| `todo_doctor` | 双向一致性校验，返回 errors / warns |
+| `todo_init` | 建 `_todo/` 骨架（只在用户要求时） |
+
+所有工具都接受可选 `root`，方便对工作区之外的仓库操作，例如：
+`todo_doctor { root: "<repo-root>" }`。
+
+## 侧栏面板
+
+<img src="assets/sidebar-panel.png" width="420" alt="侧栏里的账本面板：进行中、待办、待复核（带「通过」按钮）、阻塞四区">
+
+插件还会为当前会话工作目录的账本提供一个侧栏面板：浏览是只读的，面板上唯一的动作是「通过」一个待复核任务。
+它是按需打开的：在右侧栏的引导胶囊（以插件名命名）点开之前，布局里不会多出任何东西；点开后作为一个侧栏标签页渲染。
+
+- 四个分区 `doing` / `todo` / `review` / `blocked`，各带计数，并按状态配色，扫一眼就能看出账本形状。
+- 顺序固定：`doing` 在最前，然后 `todo`、`review`、`blocked`；空分区保留占位而不是消失。
+- 面板只读，不写任务内容。轮询只在面板可见时进行（每 5 秒一次），关掉或切到后台就不耗资源。
+- 会话工作目录之上没有账本、或账本文件互相矛盾时，面板直接说明，不去猜。后者跑一次 `todo_doctor` 修。
+
+`review` 分区里每条都带一个**通过**动作。从面板通过一个待复核任务，走的是与 `todo_complete` 相同的归档路径，
+把这次点击同时记为验收证据和签收（`accepted from the ledger panel at <ISO 时间戳>`）。只有 `review` 态的任务
+可以这样通过，其他状态会被拒绝并在面板内联报错，而不是抛异常。
+
+### 浮动面板
+
+输入框下方的书本入口可打开可移动、可缩放的 Todo Ledger 浮动面板：拖动标题栏移动窗口，拖动右下角
+握把调整大小。这是查看账本的另一种方式，原有右侧栏面板仍可使用；浮动面板的文案跟随宿主语言，
+面板正文直接从状态计数开始，因为窗口标题栏已经写了名称。所有背景、边框与状态颜色都取自宿主
+主题 token，所以窗口会跟随当前主题（亮色、暗色或自定义主题），不自带一套配色。
+
+<img src="assets/floating-panel.png" width="360" alt="浮动面板：同样四区，标题栏可拖动移动窗口，右下角握把可缩放">
+
+浏览器本地存储保存浮动面板经视口边界限制后的窗口框（位置与尺寸），并在再次打开时恢复。
+显示状态和账本内容不会保存在本地存储中：打开面板时读取当前账本，而不是恢复上次的内容。
+
+每个状态分组可以折叠：点击分组标题即可收起。点击状态计数会展开该分组，并把它的标题滚到列表
+顶部——长队列下这就是导航方式。只有任务列表滚动，计数行与页脚保持不动。
+
+面板绑定到它所显示的那个会话：切到别的会话、哪怕换了工作区，也会重新读取那个工作区的账本，
+而不是继续显示上一个；把焦点切回窗口时也会再读一次。悬浮窗跟着当前最前面的会话走，切会话
+时它会一起换目标，而不是停在被打开时那个会话上。
+
+面板对接两条宿主路由，都是 `GET` 派发：
+
+| 路由 | 作用 |
+|---|---|
+| `/todo-ledger/projection?sessionId=<id>` | 返回该会话工作目录的账本投影 |
+| `/todo-ledger/complete?slug=<slug>&sessionId=<id>` | 通过一个 `review` 任务；唯一有副作用的调用 |
+
+安装或更新宿主侧代码后需要重启宿主；面板本身是包里自带的纯客户端 JavaScript，没有构建步骤，刷新页面即可出现。
+
+## 依赖
+
+任务可以等别的任务。给 `todo_add` 传 `depends_on`（slug 列表），这个任务就会以 `blocked` +
+`blocker_cause: dependency` 建出来，直到所有前驱都被**正式完成**；如果前驱当时已经完成，它直接就是 `todo`。
+
+```mermaid
+graph LR
+  spec["设计 API 契约<br/>todo"] --> impl["实现接口<br/>blocked"]
+  spec --> form["接上表单<br/>blocked"]
+  impl --> notes["写发布说明<br/>blocked"]
+  form --> notes
+  legacy["迁移旧配置加载器<br/>blocked, manual"]
+```
+
+完成 `spec` 会在同一次调用里把 `impl` 和 `form` 提升为 `todo`；`notes` 要等两个前驱都完成——只完成一个不够。
+`legacy` 没有前驱，它的 `blocker_cause: manual` 意味着任何签收都不会自动解除它。
+
+- **只认正式完成**：前驱处于 `review` 不算，被丢弃（dropped）的归档也不算；只有 `todo_complete`——或面板上的「通过」——才解锁。
+- **创建时就校验**：未知、已被丢弃、自引用、成环的前驱都会被拒绝；`dependency` 却没有前驱同样被拒。
+- **可修**：`todo_doctor` 会报出与归档不一致的依赖字段。
+
+## 上下文是怎么留下来的
+
+1. 每次组装系统提示时，插件读会话工作目录，向上找 `_todo/`，注入：
+   - **账本最后写入：X 前**（`context/log.md` / `tasks.md` / `now.md` 的最大 mtime）；
+   - **本会话记账陈旧度**：最近一次 `todo_*` 写入之后又发生多少次工具调用、其中多少是写入类；
+     写入类 ≥3 时打 ⚠ 要求先补账；
+   - **任务总计**（四态计数）+ **待签收 review**（带 `(Nd)` 挂了几天）+ **阻塞 blocked** 的 slug；
+   - **doing 任务的进度**：取该任务「## 进度」节**最后一条**真实内容（≤80 字），
+     没有进度就整行省略（不打印「（无进度）」这类空标记）；状态 ≥2 天没变会标「状态 Nd 未变」；
+     模板占位句一律过滤。
+   - `context/now.md` 正文与最近 6 条流水。
+2. 每轮结束（`agent/turn-stopping`）按 **turn 边界**统计本轮写入类操作：≥3 次就自动往
+   `context/log.md` 补一条事实流水（工具次数 / 写入类次数 / 状态推进次数），不编语义。
+   本轮只有 note 没有状态推进时，会明确写「状态机没推进」。**刻意不以「最后一次 todo 写入」
+   为起点**——否则收尾一条 `todo_note` 会把计数清零，掩盖「本轮猛改一堆文件、只留一句 note」。
+3. `todo_checkpoint` 写结论（不是大段原文）；`todo_note` 记零碎发现；写操作自动追加流水。
+4. 会话被压缩、换新会话、重启 DSH 之后，下一个回合的提示里仍然带着这份快照 → 接着干。
+5. 没有 `_todo/` 时只注入规则并提示可以用 `todo_init`，不会擅自建目录。
+
+> 还没解决的那一半：语义摘要仍要模型自己写。插件能做的是把「账本旧了」变成提示里的
+> 事实和 ⚠，而不是替模型编造结论。
+
+## 配置
+
+`cordis.patch.yml` 里这一行可以改：
+
+```yaml
+- id: todo-ledger
+  name: './lib/index.js'
+  config:
+    root: "<repo-root>"                # 可选：固定仓库根
+    sectionOrder: 180                  # 提示段排序，默认 180
+    maxSnapshotChars: 4000             # 快照上限，默认 4000
+```
+
+不填 `root` 时按「会话工作目录向上找 `_todo/tasks.md`」；再没有就用 `TODO_ROOT` 环境变量。
+
+## 验证
+
+```powershell
+node test/smoke.mjs
+```
+
+覆盖：提示段注册与快照渲染、11 个工具 schema、init→add→status→note→checkpoint→doctor→complete/archive
+全流程、缺 `signoff` 拒绝结案。设置 `TODO_CLI` 时额外验证与外部 `todo.js` 的 `list`/`doctor` 互通。
+
+## 卸载
+
+```powershell
+plugin_manager remove_bundle --target dsh-todo-ledger
+```
+
+插件只删自己的注册；`_todo/` 目录（含 context/）不会被删。

package/assets/icon.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="180" height="180" viewBox="0 0 180 180">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#211f2b"/>
+      <stop offset="1" stop-color="#121118"/>
+    </linearGradient>
+  </defs>
+  <rect x="8" y="8" width="164" height="164" rx="36" fill="url(#bg)"/>
+  <rect x="8.75" y="8.75" width="162.5" height="162.5" rx="35.25" fill="none" stroke="#3a3747" stroke-width="1.5"/>
+  <g transform="translate(38,34) scale(4.3333)" fill="none" stroke="#f9fafb" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M12 6c-2.4-1.5-5.3-1.8-9-1v13c3.7-.8 6.6-.5 9 1 2.4-1.5 5.3-1.8 9-1V5c-3.7-.8-6.6-.5-9 1Z"/>
+    <path d="M12 6v13"/>
+  </g>
+  <g fill="#a78bfa">
+    <circle cx="70" cy="141" r="3.4"/>
+    <circle cx="90" cy="141" r="3.4"/>
+    <circle cx="110" cy="141" r="3.4"/>
+  </g>
+</svg>