@crazx/dsh-todo-completion-guard 0.1.0-rc.7.zw.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/guard/todo-completion-guard/README.md
+README.md: a6454bb40f47754e7b7c445fcd0c038db729f93f
+README.zh.md: 722d973787bef71d420748473b5fd175290a32b7

package/README.md

@@ -0,0 +1,35 @@
+# @deepseek-ai/dsh-todo-completion-guard
+
+English | [中文](README.zh.md)
+
+An advisory turn-end guard, not a model-facing tool: it never appears in the tool list, never vetoes a turn, and adds exactly one behavior — when an otherwise completed turn is about to close while its standing todo list still has unfinished items, it steers one plugin-notice into the same turn telling the model to finish and check off the items, rewrite the list around a deliberate drop, or state explicitly why the list stays open. Whether to comply stays entirely with the model; the guard advises once per turn and never loops. Decision record: [the todo-completion-guard Agent Note](../../../.agents/notes/implemented/feature/2026-08-19-todo-completion-guard.md).
+
+## When it fires
+
+The guard listens on `agent/turn-stopping`, the boundary the loop broadcasts just before closing an otherwise completed turn (the same seam the Claude Code Stop hook rides). A steered message makes the loop observe pending input and run another step of the same turn.
+
+At that boundary it inspects the current turn's events:
+
+- **Standing list** — the latest `todo/write` after the current turn's own `turn/start`, matching the todo projection's clearing rule. A list written in an earlier turn is already cleared by that rule and is never nagged about; a turn that writes no list is invisible to the guard.
+- **Unfinished means not `completed`** — both `pending` and `in_progress` count. A forgotten `pending` item is exactly the residue this guard exists for.
+- **Exempt: wall-bounded turns.** If any step of the turn finished on `max-tokens` (a sticky turn outcome), the guard stays quiet — forcing another step would most likely hit the same output ceiling again and burn the request for nothing.
+- **Once per agent per turn.** A steered turn that still ends with an open list is allowed to end: the reminder names the exits (complete, rewrite with a one-line reason, or declare the deferral), and a model that chooses to keep the list open heard the reminder once. This is the guard's own loop cap; the loop itself has none.
+
+## The reminder
+
+One `notice`-form context message, source `{kind: 'plugin', plugin: 'todo-completion-guard'}`, steered into the turn and appended as a logged `user/message` — model-visible, source-attributed, and reconstructable from the session log with no new session event. It lists every unfinished item with its status, then names the three exits. The decision — finish, rewrite, or keep with an explicit statement — stays with the model: a legitimately deferred list (work continuing next turn, waiting for the user) is delayed by nothing and blocked by nothing.
+
+## Composition
+
+```yaml
+- id: todo-completion-guard
+  name: '@deepseek-ai/dsh-todo-completion-guard'
+```
+
+No configuration: every knob this guard would expose (reminder text, per-turn cap, exemptions) is a correctness property of the advisory contract, not a deployment choice. It is a consumer of the `todo/write` event vocabulary; mounting it without `tool-todo` in the composition is inert (no turn ever writes the event).
+
+## Known Limitations and Deferred Work
+
+- **Advisory only** — a model that acknowledges the reminder and still leaves the list open ends the turn after one nudge; escalating to forced continuation is rejected (that is a `TODO(stop-loop-guard)` policy for the loop, not this guard).
+- **In-memory throttle** — the once-per-turn state is a `WeakMap` over the live agent; a session resumed from persistence gets a fresh budget, which only matters for a turn that spans a process restart.
+- **Subagent lists are invisible by design** — the guard reads each agent's own session log; a child's unfinished list never steers the parent (the parent's own list reflects delegated work as it sees it).

package/README.zh.md

@@ -0,0 +1,35 @@
+# @deepseek-ai/dsh-todo-completion-guard
+
+[English](README.md) | 中文
+
+一个仅提供建议的回合结束守卫，而非面向模型的工具：它不会出现在工具列表中，不会否决任何回合，只增加一种行为——当一个本可完成的回合即将结束、而其当前有效 todo 清单仍有未完成项时，它会向**同一回合**注入一条 plugin-notice，要求模型完成并勾掉这些项、围绕明确放弃重写清单，或显式说明清单为何保持开放。是否遵从完全由模型决定；守卫每回合只提醒一次，绝不循环。决策记录见 [todo-completion-guard Agent Note](../../../.agents/notes/implemented/feature/2026-08-19-todo-completion-guard.md)。
+
+## 触发时机
+
+守卫监听 `agent/turn-stopping`——loop 在关闭一个本可完成的回合前广播的边界（与 Claude Code Stop hook 同一条缝）。被注入的消息会让 loop 观察到待处理输入，并在同一回合里再跑一个 step。
+
+在这个边界上，它检查当前回合的事件：
+
+- **当前有效清单**——当前回合自己的 `turn/start` 之后的最近一次 `todo/write`，与 todo 投影的清空规则一致。更早回合写的清单已被该规则清空，绝不追讨；没写过清单的回合对守卫不可见。
+- **未完成 = 非 `completed`**——`pending` 和 `in_progress` 都算。被遗忘的 `pending` 项正是这个守卫要清理的残羹。
+- **豁免：撞墙回合。** 若回合中任何 step 以 `max-tokens` 收尾（粘性回合结局），守卫保持沉默——强制续 step 大概率再次撞上同一输出上限，白白烧掉请求。
+- **每 agent 每回合一次。** 被提醒后仍以开放清单收尾的回合允许结束：提醒列出了全部出口（完成、附一行理由重写、或显式声明延后），选择保留清单的模型已经听过一次。这是守卫自带的循环上限；loop 本身没有。
+
+## 提醒内容
+
+一条 `notice` 形态的上下文消息，source 为 `{kind: 'plugin', plugin: 'todo-completion-guard'}`，注入回合并作为落日志的 `user/message` 追加——模型可见、来源可归属、可从会话日志重建，无需新的会话事件。它列出每个未完成项及其状态，然后给出三个出口。决定——完成、重写、还是保留并显式声明——留给模型：合法延后的清单（工作延续到下一回合、等待用户）既不被延迟也不被阻塞。
+
+## 组合
+
+```yaml
+- id: todo-completion-guard
+  name: '@deepseek-ai/dsh-todo-completion-guard'
+```
+
+无配置：这个守卫可能暴露的每个旋钮（提醒文案、每回合上限、豁免规则）都是 advisory 契约的正确性属性，而非部署选择。它是 `todo/write` 事件词汇的消费者；组合中未挂载 `tool-todo` 时它天然无害（任何回合都不会写该事件）。
+
+## 已知限制与延后工作
+
+- **仅建议**——确认收到提醒却仍保留开放清单的模型，在提醒一次后即可结束回合；升级为强制延续已被拒绝（那是 loop 层的 `TODO(stop-loop-guard)` 策略，不属于本守卫）。
+- **内存态限流**——每回合一次的状态是挂在活跃 agent 上的 `WeakMap`；从持久化恢复的会话获得全新预算，这只影响横跨进程重启的回合。
+- **子代理清单设计上不可见**——守卫读每个 agent 自己的会话日志；子代理的未完成清单绝不会驱动父代理（父代理自己的清单按它所见反映委派工作）。

package/lib/index.js

@@ -0,0 +1,72 @@
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+//#region lib/types/index.js
+/**
+* Advisory turn-end todo guard: at `agent/turn-stopping` it inspects the
+* current turn's standing todo list and steers one notice when items remain
+* unfinished. Whether to finish, rewrite, or legitimately defer stays with the
+* model. Configuration-free; semantics live in the package README; rationale
+* lives in the todo-completion-guard Agent Note.
+* @module @deepseek-ai/dsh-todo-completion-guard
+*/
+const name = "todo-completion-guard";
+/**
+* The `{kind:'plugin'}` source stamped on the guard's reminder — the label is
+* load-bearing (an unlabeled context would render as a user prompt in derived
+* history).
+*/
+const PLUGIN_NAME = "todo-completion-guard";
+/**
+* The current turn's standing plan: the latest `todo/write` after the turn's
+* own `turn/start` (matching the todo projection's clearing rule), or `null`
+* when the turn wrote no list. `wallBounded` records that some step of the
+* turn finished on `max-tokens` — the sticky turn outcome — where forcing
+* another step would most likely hit the same output ceiling again.
+* @param events - the agent's whole session log; only the current turn's tail is read.
+* @returns the standing list and the wall-bounded flag.
+*/
+function inspectTurn(events) {
+	const turnStart = events.findLastIndex((event) => event.type === "turn/start");
+	const scope = events.slice(turnStart + 1);
+	return {
+		todos: scope.findLast((event) => event.type === "todo/write")?.data.todos ?? null,
+		wallBounded: scope.some((event) => event.type === "assistant/chunk" && event.data.chunk.type === "finish" && event.data.chunk.reason.kind === "max-tokens")
+	};
+}
+/**
+* Build the one-page reminder naming every unfinished item with its status.
+* @param open - standing items whose status is not `completed`, in list order.
+* @returns the frozen plugin-notice user message ready to steer.
+*/
+function reminder(open) {
+	const lines = open.map((item) => `- [${item.status}] ${item.content}`).join("\n");
+	return createUserMessage({
+		content: [{
+			type: "text",
+			text: `The todo list still has ${open.length} unfinished item(s) while this turn is about to end:\n${lines}\nBefore finishing the reply: complete the remaining item(s) and mark them completed with todo_write; or, if items are genuinely dropped or deferred, rewrite the list to reflect that and say why in one line. If the work legitimately continues in a later turn or you are blocked waiting for the user, state that explicitly in the reply and the list may stay as is.`
+		}],
+		source: {
+			kind: "plugin",
+			plugin: PLUGIN_NAME,
+			form: "notice",
+			summary: `todos: ${open.length} unfinished`
+		}
+	});
+}
+/**
+* Install the guard's listener.
+* @param ctx - plugin context; the listener is scoped to it and disposed with it.
+*/
+function apply(ctx) {
+	const lastReminded = /* @__PURE__ */ new WeakMap();
+	ctx.on("agent/turn-stopping", ({ agent, turn }) => {
+		if (lastReminded.get(agent) === turn) return;
+		const { todos, wallBounded } = inspectTurn(agent.session.events);
+		if (todos === null || wallBounded) return;
+		const open = todos.filter((item) => item.status !== "completed");
+		if (open.length === 0) return;
+		lastReminded.set(agent, turn);
+		agent.steer(reminder(open));
+	});
+}
+//#endregion
+export { apply, name };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-todo-completion-guard`.
+* @module @deepseek-ai/dsh-todo-completion-guard/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-todo-completion-guard";
+/** Cordis companion plugin name. */
+const name = "todo-completion-guard-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the reminded-turn state is private to one turn-stopping
+* listener, and the steered notices it produces are already source-attributed
+* `user/message` events in the session log — no package-owned event or snapshot
+* exists for an independent companion to observe.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Advisory turn-end todo guard: at `agent/turn-stopping` it inspects the
+ * current turn's standing todo list and steers one notice when items remain
+ * unfinished. Whether to finish, rewrite, or legitimately defer stays with the
+ * model. Configuration-free; semantics live in the package README; rationale
+ * lives in the todo-completion-guard Agent Note.
+ * @module @deepseek-ai/dsh-todo-completion-guard
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "todo-completion-guard";
+/**
+ * Install the guard's listener.
+ * @param ctx - plugin context; the listener is scoped to it and disposed with it.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-todo-completion-guard`.
+ * @module @deepseek-ai/dsh-todo-completion-guard/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "todo-completion-guard-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@crazx/dsh-todo-completion-guard",
+  "description": "Turn-end todo guard plugin: one advisory steer when a turn closes on an unfinished todo list",
+  "version": "0.1.0-rc.7.zw.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aka-danielZhang/deepseek-harness.git",
+    "directory": "packages/guard/todo-completion-guard"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^0.1.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-todo": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^0.1.0-rc.7"
+  }
+}