dsh-checklists 0.4.0 → 0.5.0

package/lib/gate.js

@@ -0,0 +1,55 @@
+/**
+ * Turn-end gate: decides whether a turn is closing with the checklist stale.
+ *
+ * Kept pure on purpose — the host event wiring lives in `index.ts`, so the rule
+ * itself is testable without a running harness and can be reasoned about by
+ * reading one function.
+ *
+ * The gate never guesses *what* was completed. It only notices the shape of the
+ * problem: real work happened, the checklist was not touched, and something is
+ * still marked as in progress.
+ */
+/** Observation endpoint for the gate's last decisions. */
+export const NUDGE_ROUTE = '/dsh-checklist/nudge';
+/**
+ * Tools whose result can change the workspace. `run_code` is included because
+ * the PTC transport can reach any tool behind it.
+ */
+export const MUTATING_TOOLS = new Set([
+    'bash',
+    'pwsh',
+    'write',
+    'edit',
+    'str_replace_editor',
+    'apply_patch',
+    'run_code',
+]);
+/** Tools that already keep a checklist current. */
+const CHECKLIST_WRITES = new Set([
+    'checklist_create',
+    'checklist_add',
+    'checklist_check',
+    'checklist_edit',
+    'checklist_remove_item',
+    'checklist_delete',
+    'checklist_rename',
+]);
+export function isChecklistWrite(name) {
+    return CHECKLIST_WRITES.has(name);
+}
+/**
+ * Decide whether the closing turn should be challenged.
+ *
+ * @param activity - what the turn did.
+ * @param doingCount - items currently in `doing` across the session.
+ * @returns the decision and a short human-readable reason, logged either way.
+ */
+export function decideNudge(activity, doingCount) {
+    if (!activity.mutated)
+        return { nudge: false, reason: 'no mutating tool calls' };
+    if (activity.checklistWrite)
+        return { nudge: false, reason: 'checklist already updated' };
+    if (doingCount === 0)
+        return { nudge: false, reason: 'nothing in progress' };
+    return { nudge: true, reason: `${doingCount} item(s) still doing after workspace changes` };
+}

package/lib/index.js

@@ -11,6 +11,8 @@
  * document is the single source of truth.
  */
 import { renderDigest } from './digest.js';
+import { decideNudge, isChecklistWrite, MUTATING_TOOLS, NUDGE_ROUTE } from './gate.js';
+import { countState } from './model.js';
 import { serveProbe, PROBE_ROUTE } from './probe.js';
 import { serveItemUpdate, serveState, ITEM_ROUTE, STATE_ROUTE } from './route.js';
 import { ChecklistStore } from './store.js';
@@ -44,6 +46,52 @@ 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.
+    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;
+        if (typeof toolName !== 'string' || typeof agentId !== 'string')
+            return;
+        const current = activity.get(agentId) ?? { mutated: false, checklistWrite: false };
+        if (MUTATING_TOOLS.has(toolName))
+            current.mutated = true;
+        if (isChecklistWrite(toolName))
+            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 current = activity.get(agentId) ?? { mutated: false, checklistWrite: false };
+        activity.set(agentId, { mutated: false, checklistWrite: false });
+        const doc = store.peek(agentId);
+        let doing = 0;
+        if (doc)
+            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;
+        gateLog.push({
+            at: new Date().toISOString(),
+            sessionId: agentId,
+            nudge: decision.nudge,
+            reason: decision.reason,
+            doing,
+        });
+        if (gateLog.length > 20)
+            gateLog.shift();
+    }));
     let loggedScope = false;
     ctx.inject(['systemPrompt'], (promptCtx) => {
         promptCtx.systemPrompt.context({
@@ -93,5 +141,19 @@ export function apply(ctx, config = {}) {
                 serveProbe(req, res);
             },
         }), 'dsh-checklist: client probe route');
+        // What the turn-end gate decided, for verification before it steers.
+        webCtx.effect(() => webCtx.webServer.register({
+            kind: 'exact',
+            path: NUDGE_ROUTE,
+            handler: (req, res) => {
+                const body = Buffer.from(`${JSON.stringify({ mode: 'observe', entries: gateLog }, null, 2)}\n`, 'utf8');
+                res.writeHead(200, {
+                    'content-type': 'application/json; charset=utf-8',
+                    'content-length': String(body.byteLength),
+                    'cache-control': 'no-store',
+                });
+                res.end(body);
+            },
+        }), 'dsh-checklist: nudge log route');
     });
 }

package/lib/model.js

@@ -9,12 +9,25 @@ export const ITEM_STATES = ['todo', 'doing', 'done', 'blocked'];
 export function emptyDoc(sessionId) {
     return { version: 1, sessionId, lists: [] };
 }
-/** Mint the next `<prefix>N` identifier that is not already in `used`. */
+/**
+ * Mint the next `<prefix>N` identifier.
+ *
+ * Numbers start after the highest one already in `used`, so a removed item's id
+ * is not handed to the next arrival: a freed `i3` stays dead instead of
+ * silently aliasing a different item. The high-water mark is not persisted, so
+ * removing the newest item and adding another can still reuse that id — fully
+ * closing the hole needs a stored counter, which means a schema change.
+ */
 export function mintId(prefix, used) {
-    let n = 1;
-    while (used.has(`${prefix}${n}`))
-        n += 1;
-    return `${prefix}${n}`;
+    let highest = 0;
+    for (const id of used) {
+        if (!id.startsWith(prefix))
+            continue;
+        const suffix = Number(id.slice(prefix.length));
+        if (Number.isInteger(suffix) && suffix > highest)
+            highest = suffix;
+    }
+    return `${prefix}${highest + 1}`;
 }
 /**
  * Build an item tree from plain lines.
@@ -80,6 +93,16 @@ export function countItems(items) {
     }
     return { total, done };
 }
+/** Count items in one state across a tree. */
+export function countState(items, state) {
+    let total = 0;
+    for (const item of items) {
+        if (item.state === state)
+            total += 1;
+        total += countState(item.children, state);
+    }
+    return total;
+}
 /**
  * Resolve one model-supplied reference against the session's checklists.
  *
@@ -89,14 +112,17 @@ export function countItems(items) {
  *
  * @param lists - the session's checklists.
  * @param ref - a model-supplied item id, text, or prefix.
- * @param listId - optional checklist id to search within.
+ * @param listId - optional checklist id **or exact title** to search within.
  * @returns the hit, the ambiguity, or a miss.
  */
 export function resolveRef(lists, ref, listId) {
     const needles = ref.trim().toLowerCase();
     if (needles.length === 0)
         return { kind: 'miss' };
-    const scoped = listId ? lists.filter((list) => list.id === listId) : lists;
+    // Accept a title here as well as an id: every other tool does, and a model
+    // that just created "Release 2.3" will pass that back, not "l1".
+    const scope = listId ? findList(lists, listId) : undefined;
+    const scoped = listId ? (scope ? [scope] : []) : lists;
     const entries = [];
     for (const list of scoped) {
         for (const { item } of flatten(list.items))

package/lib/types/gate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Turn-end gate: decides whether a turn is closing with the checklist stale.
+ *
+ * Kept pure on purpose — the host event wiring lives in `index.ts`, so the rule
+ * itself is testable without a running harness and can be reasoned about by
+ * reading one function.
+ *
+ * The gate never guesses *what* was completed. It only notices the shape of the
+ * problem: real work happened, the checklist was not touched, and something is
+ * still marked as in progress.
+ */
+export interface TurnActivity {
+    /** The turn ran a tool that can change the workspace. */
+    mutated: boolean;
+    /** The turn already wrote to a checklist. */
+    checklistWrite: boolean;
+}
+/** Observation endpoint for the gate's last decisions. */
+export declare const NUDGE_ROUTE = "/dsh-checklist/nudge";
+export interface NudgeDecision {
+    nudge: boolean;
+    reason: string;
+}
+/**
+ * Tools whose result can change the workspace. `run_code` is included because
+ * the PTC transport can reach any tool behind it.
+ */
+export declare const MUTATING_TOOLS: ReadonlySet<string>;
+export declare function isChecklistWrite(name: string): boolean;
+/**
+ * Decide whether the closing turn should be challenged.
+ *
+ * @param activity - what the turn did.
+ * @param doingCount - items currently in `doing` across the session.
+ * @returns the decision and a short human-readable reason, logged either way.
+ */
+export declare function decideNudge(activity: TurnActivity, doingCount: number): NudgeDecision;

package/lib/types/model.d.ts

@@ -25,7 +25,15 @@ export interface SessionDoc {
     lists: Checklist[];
 }
 export declare function emptyDoc(sessionId: string): SessionDoc;
-/** Mint the next `<prefix>N` identifier that is not already in `used`. */
+/**
+ * Mint the next `<prefix>N` identifier.
+ *
+ * Numbers start after the highest one already in `used`, so a removed item's id
+ * is not handed to the next arrival: a freed `i3` stays dead instead of
+ * silently aliasing a different item. The high-water mark is not persisted, so
+ * removing the newest item and adding another can still reuse that id — fully
+ * closing the hole needs a stored counter, which means a schema change.
+ */
 export declare function mintId(prefix: string, used: ReadonlySet<string>): string;
 /**
  * Build an item tree from plain lines.
@@ -53,6 +61,8 @@ export interface ItemCounts {
     done: number;
 }
 export declare function countItems(items: readonly ChecklistItem[]): ItemCounts;
+/** Count items in one state across a tree. */
+export declare function countState(items: readonly ChecklistItem[], state: ItemState): number;
 export interface RefHit {
     list: Checklist;
     item: ChecklistItem;
@@ -75,7 +85,7 @@ export type RefResult = {
  *
  * @param lists - the session's checklists.
  * @param ref - a model-supplied item id, text, or prefix.
- * @param listId - optional checklist id to search within.
+ * @param listId - optional checklist id **or exact title** to search within.
  * @returns the hit, the ambiguity, or a miss.
  */
 export declare function resolveRef(lists: readonly Checklist[], ref: string, listId?: string): RefResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-checklists",
-  "version": "0.4.0",
+  "version": "0.5.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",