dsh-checklists 0.5.0 → 0.6.0

package/README.md

@@ -50,7 +50,7 @@ From a local build or tarball:
 npm install
 npm run build
 npm pack
-dsh plugin --profile dev add ./dsh-checklists-0.4.0.tgz
+dsh plugin --profile dev add ./dsh-checklists-0.6.0.tgz
 dsh --profile dev --dump-config        # the tool-checklist row should appear
 ```
 
@@ -68,6 +68,7 @@ Override the defaults on the plugin's entry in the profile's `cordis.patch.yml`:
     maxDigestLines: 12      # lines of the injected digest
     maxItemsPerList: 200    # per-list item cap
     pruneDays: 14           # prune untouched sessions after N days (0 = never)
+    nudge: steer            # steer | observe | off — see "Turn-end gate"
     # storageRoot: "D:/data/dsh-checklists"
     # templates:
     #   my-flow: ["Step 1", "  Sub-step", "Step 2"]
@@ -113,8 +114,42 @@ the agent's edit.
 |---|---|---|
 | `/dsh-checklist/state` | GET | One session's state (read-only, `no-store`) |
 | `/dsh-checklist/item` | POST | Edit an item's text, with a conflict guard |
+| `/dsh-checklist/nudge` | GET | Recent turn-end gate decisions |
 | `/dsh-checklist/client-probe` | GET | Client load diagnostics |
 
+## Turn-end gate
+
+A checklist only helps while it is true. The gate closes the most common gap:
+a turn does real work, forgets to mark it, and the list is stale by the time you
+look at it.
+
+When a turn is about to close, the plugin checks exactly three things:
+
+1. Did the turn run a tool that changes the workspace (`bash`, `edit`, `write`, …)?
+2. Did it skip every checklist write?
+3. Is anything still marked `doing`?
+
+If all three hold, the agent gets one short steering message before the turn ends:
+
+> Before you finish: N checklist item(s) are still marked "doing". If you
+> completed any of them this turn, update them with checklist_check and say what
+> proves it. If not, leave them as they are — do not mark work you did not do.
+
+It never guesses **what** was completed — only that the bookkeeping was skipped.
+At most one nudge per turn, and none when the turn was pure conversation or the
+checklist already changed.
+
+Inspect recent decisions at `GET /dsh-checklist/nudge`:
+
+```jsonc
+{ "mode": "steer", "entries": [
+  { "source": "turn-stopping", "nudge": true, "steered": true,
+    "reason": "1 item(s) still doing after workspace changes", "doing": 1 }
+] }
+```
+
+`nudge: observe` records without interrupting; `nudge: off` disables the gate.
+
 ## Language
 
 The panel follows the harness locale: **Spanish** when `locale` starts with `es`,

package/lib/index.js

@@ -10,6 +10,7 @@
  * The agent is the only writer. There is no client write path: the session
  * document is the single source of truth.
  */
+import { randomUUID } from 'node:crypto';
 import { renderDigest } from './digest.js';
 import { decideNudge, isChecklistWrite, MUTATING_TOOLS, NUDGE_ROUTE } from './gate.js';
 import { countState } from './model.js';
@@ -19,6 +20,26 @@ import { ChecklistStore } from './store.js';
 import { registerChecklistTools } from './tools.js';
 export const name = 'dsh-checklist';
 export const inject = ['tools'];
+/**
+ * Build the steering message.
+ *
+ * Model-facing, so English. It states the observation, asks for evidence, and
+ * explicitly allows leaving an item untouched — a gate that demanded progress
+ * would push the model into marking work it never did.
+ */
+function buildSteerMessage(doing) {
+    return {
+        id: randomUUID(),
+        role: 'user',
+        content: [{
+                type: 'text',
+                text: `Before you finish: ${doing} checklist item(s) are still marked "doing". `
+                    + 'If you completed any of them this turn, update them with checklist_check and say what '
+                    + 'proves it. If not, leave them as they are — do not mark work you did not do.',
+            }],
+        source: { kind: 'user' },
+    };
+}
 /**
  * Resolve which session this prompt assembly belongs to.
  *
@@ -46,18 +67,20 @@ export function apply(ctx, config = {}) {
     if (config.pruneDays !== 0) {
         void store.prune(config.pruneDays ?? 14).catch(() => undefined);
     }
-    // --- Turn-end gate (observation mode) ------------------------------------
-    // Watches one turn's tool activity and decides, as the turn closes, whether
-    // the checklist was left stale. This release only records the decision — the
-    // event is not exercised yet — so enabling `steer` is a one-line follow-up
-    // once the log shows it fires when it should.
+    // --- Turn-end gate --------------------------------------------------------
+    // Watches one turn's tool activity and, as the turn closes, decides whether
+    // the checklist was left stale. In `steer` mode the agent gets a message
+    // before the turn is allowed to end; `observe` only records the decision.
+    const nudgeMode = config.nudge ?? 'steer';
     const activity = new Map();
     const gateLog = [];
     const events = ctx;
-    ctx.effect(() => events.on('tools/result', (payload) => {
-        const event = payload;
-        const toolName = event.exec?.name;
-        const agentId = event.exec?.agent?.id;
+    ctx.effect(() => events.on('tools/result', (exec) => {
+        // `tools/result` is emitted as (execution, result); the execution carries
+        // the tool name and the calling agent.
+        const call = exec;
+        const toolName = call?.name;
+        const agentId = call?.agent?.id;
         if (typeof toolName !== 'string' || typeof agentId !== 'string')
             return;
         const current = activity.get(agentId) ?? { mutated: false, checklistWrite: false };
@@ -67,11 +90,8 @@ export function apply(ctx, config = {}) {
             current.checklistWrite = true;
         activity.set(agentId, current);
     }));
-    ctx.effect(() => events.on('agent/turn-stopping', (payload) => {
-        const event = payload;
-        const agentId = event.agent?.id;
-        if (typeof agentId !== 'string')
-            return;
+    const evaluate = (agent, source) => {
+        const agentId = agent.id;
         const current = activity.get(agentId) ?? { mutated: false, checklistWrite: false };
         activity.set(agentId, { mutated: false, checklistWrite: false });
         const doc = store.peek(agentId);
@@ -80,17 +100,55 @@ export function apply(ctx, config = {}) {
             for (const list of doc.lists)
                 doing += countState(list.items, 'doing');
         const decision = decideNudge(current, doing);
-        if (!decision.nudge && process.env.DSH_CHECKLIST_DEBUG !== '1')
-            return;
+        let steered = false;
+        let reason = decision.reason;
+        if (decision.nudge && nudgeMode === 'steer') {
+            try {
+                agent.steer?.(buildSteerMessage(doing));
+                steered = true;
+            }
+            catch (error) {
+                reason = `${reason}; steer failed: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        // Log every decision: an empty log must mean "the event never fired",
+        // never "the answer was no".
         gateLog.push({
             at: new Date().toISOString(),
             sessionId: agentId,
+            source,
+            mode: nudgeMode,
             nudge: decision.nudge,
-            reason: decision.reason,
+            steered,
+            reason,
             doing,
         });
         if (gateLog.length > 20)
             gateLog.shift();
+    };
+    ctx.effect(() => events.on('agent/turn-stopping', (payload) => {
+        if (nudgeMode === 'off')
+            return;
+        const event = payload;
+        if (typeof event.agent?.id === 'string')
+            evaluate(event.agent, 'turn-stopping');
+    }));
+    // Fallback close signal. It evaluates only when `turn-stopping` left activity
+    // unconsumed, so it never duplicates a decision — but it still catches the
+    // turn if the primary event is ever missing.
+    ctx.effect(() => events.on('agent/status', (payload) => {
+        if (nudgeMode === 'off')
+            return;
+        const event = payload;
+        if (event.status !== 'idle')
+            return;
+        const agent = event.agent;
+        if (!agent || typeof agent.id !== 'string')
+            return;
+        const current = activity.get(agent.id);
+        if (!current || (!current.mutated && !current.checklistWrite))
+            return;
+        evaluate(agent, 'status');
     }));
     let loggedScope = false;
     ctx.inject(['systemPrompt'], (promptCtx) => {
@@ -146,7 +204,7 @@ export function apply(ctx, config = {}) {
             kind: 'exact',
             path: NUDGE_ROUTE,
             handler: (req, res) => {
-                const body = Buffer.from(`${JSON.stringify({ mode: 'observe', entries: gateLog }, null, 2)}\n`, 'utf8');
+                const body = Buffer.from(`${JSON.stringify({ mode: nudgeMode, entries: gateLog }, null, 2)}\n`, 'utf8');
                 res.writeHead(200, {
                     'content-type': 'application/json; charset=utf-8',
                     'content-length': String(body.byteLength),

package/lib/types/index.d.ts

@@ -24,5 +24,12 @@ export interface Config {
     pruneDays?: number;
     /** Extra templates merged over the built-in ones. */
     templates?: Record<string, string[]>;
+    /**
+     * What the turn-end gate does when it finds a stale checklist.
+     * - `steer` (default): put a message in front of the agent before the turn ends.
+     * - `observe`: record the decision, never interrupt.
+     * - `off`: do not evaluate at all.
+     */
+    nudge?: 'steer' | 'observe' | 'off';
 }
 export declare function apply(ctx: Context, config?: Config): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-checklists",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Session-scoped checklists for DeepSeek Harness: the agent tracks work as a tree, the model always sees a compact digest, and a read-only sidebar tab mirrors it.",
   "type": "module",
   "main": "lib/index.js",