@cstart/coldstart 2.2.13 → 2.2.15

package/hooks/capture-payload.mjs

@@ -16,8 +16,7 @@
  *              (the coordinator only sees the final message — #61).
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 // The spec shapes are NOT written here any more. They come from the one table
 // the write guide, the MCP tool description and `kb repair` also render from —
@@ -25,25 +24,36 @@ import { join } from "node:path";
 import { shapesBlock } from "./note-shape.mjs";
 
 /**
- * Session worklist manifest — the DENOMINATOR for capture coverage.
+ * Durable capture worklist — the checklist the agent can re-Read at any point.
  *
- * The checklist can only ASK the agent to walk the whole worklist (rule 3a);
- * nothing downstream could tell it that it wrote 8 notes for 30 worked files,
- * because `kb write` sees one spec at a time and never saw the worklist. So the
- * worklist is dropped here, at the one point every host passes through, and
- * `kb write --session <sid>` reads it back to print "N of M".
+ * The old design dropped the worklist in tmpdir (keyed by session id) and let
+ * `kb write --session` print a running "N of M". Two failures: the manifest was
+ * scratch that no agent ever read directly, and the whole capture PAYLOAD (this
+ * checklist + the write contract) was delivered one-shot and lost to compaction
+ * — the agent had to re-derive the note shape from memory 80 tool-calls later.
  *
- * CONTRACT TWIN: src/kb/session-worklist.ts — same filename, same shape. Keyed
- * by session id in tmpdir like the pending-capture file (elicit-core.pendingPath);
- * never in the repo, so it cannot be committed and needs no ignore rule.
- * Best-effort: capture must never fail because this could not be written.
+ * So the pair now lives in the repo notebook, keyed by root, and holds BOTH:
+ *   .worklist.json  structured scope (the coverage source of truth)
+ *   .worklist.md    the full rendered payload — worklist + write contract
+ * The agent re-Reads the .md whenever this scrolls away; `kb write` credits and
+ * trims/clears the pair (src/kb/durable-worklist.ts) so a stale snapshot never
+ * lingers, and the next capture fire regenerates it against live freshness.
+ *
+ * CONTRACT TWIN: src/kb/durable-worklist.ts — keep the paths and the .json shape
+ * (ts, sid, files:[{path,tier,needsNote}], wrote:[]) in step. Both gitignored
+ * (src/kb/store.ts initSkeleton). One active worklist per repo (concurrent
+ * sessions last-write-wins, an accepted edge). Best-effort: capture must never
+ * fail because these could not be written.
  */
-export function worklistManifestPath(sid) {
-  return join(tmpdir(), `coldstart-kb-worklist-${sid}.json`);
+export function worklistJsonPath(root) {
+  return join(root, ".coldstart", "notebook", ".worklist.json");
+}
+export function worklistMdPath(root) {
+  return join(root, ".coldstart", "notebook", ".worklist.md");
 }
 
-function recordWorklistManifest(sid, entries) {
-  if (!sid || !entries?.length) return;
+function writeDurableWorklist(root, sid, entries, mdBody) {
+  if (!root || !entries?.length) return;
   try {
     // needsNote: no note yet, or the note it has is stale. A file whose note is
     // already fresh is NOT an outstanding item — counting it would make full
@@ -53,7 +63,9 @@ function recordWorklistManifest(sid, entries) {
       tier: e.tier,
       needsNote: !e.notes?.length || e.notes.some((n) => n.state === "changed" || n.state === "missing"),
     }));
-    writeFileSync(worklistManifestPath(sid), JSON.stringify({ ts: Date.now(), files, wrote: [] }));
+    mkdirSync(join(root, ".coldstart", "notebook"), { recursive: true });
+    writeFileSync(worklistJsonPath(root), JSON.stringify({ ts: Date.now(), sid, files, wrote: [] }));
+    writeFileSync(worklistMdPath(root), mdBody);
   } catch { /* best-effort */ }
 }
 
@@ -101,8 +113,15 @@ function worklistLines(entries) {
   return lines.join("\n");
 }
 
-export function buildCapturePayload({ root, cli, sid, entries, envelope }) {
-  recordWorklistManifest(sid, entries);
+export function buildCapturePayload(args) {
+  const payload = renderCapturePayload(args);
+  // Persist the WHOLE payload durably so the agent can re-Read it later, and the
+  // structured scope for `kb write` coverage. Best-effort; never blocks capture.
+  writeDurableWorklist(args.root, args.sid, args.entries, payload);
+  return payload;
+}
+
+function renderCapturePayload({ root, cli, sid, entries, envelope }) {
   const opening = envelope === "block"
     ? "Handle capture now, then stop."
     : envelope === "manual"
@@ -150,9 +169,10 @@ changed and what you had to understand to change it, and that is precisely the k
 cold agent lacks. The default for an edited file is a note. Walk the worklist top to bottom \
 and decide each one explicitly; do not stop at the first two or three. If you end up writing \
 notes for well under half the [edited] files, you have under-captured — say which files you \
-skipped and why, so the decision is visible instead of silent. Each \`kb write\` prints the \
-running count ("N of M worklist files noted") and lists what is still unwritten — read that \
-line back before you finish; it is the only place your own coverage is visible to you.
+skipped and why, so the decision is visible instead of silent. This whole checklist (worklist \
++ the write contract below) is saved at \`.coldstart/notebook/.worklist.md\` — re-Read that file \
+any time this session if this scrolls out of context. Your \`kb write\` call ends with a coverage \
+line naming any worked file still without a note; read it back before you finish.
 
 WORKLIST — files you actually read this session, most-worked first:
 
@@ -210,7 +230,11 @@ missing fact is a NEW flow, even in the same subsystem, even across the same fil
 an unrelated fact into a nearby flow buries it: nobody searching for your fact will find that \
 title.
 
-WRITE — one Bash block total: specs as heredocs, writes chained with &&.
+WRITE — ONE call: put EVERY note as an object in a JSON array and write the array \
+in a single \`kb write\`. Order flows before the file notes that reference them. Malformed \
+notes are reported together (a bad note never silences a good one), and the call ends with \
+the coverage line. Forming an array is fewer tokens than chaining, not more — same JSON, \
+without the per-note heredoc and && glue.
 ${shapesBlock({ compact: true })}
   "identityAliases" and "symbols" are what make a note FINDABLE and both go missing by \
 default: a note without identityAliases is reachable only by its exact title, and agents \
@@ -227,14 +251,18 @@ however carefully you described it. Never write a flow using the file-note shape
 with several of its symbols. file-hub is ONLY for grab-bag files that have no single purpose \
 (models.py, utils, helpers) — there, knowledge lives per symbol. Touching many symbols does \
 not make a file a hub; having no one purpose does.
-  Update = the same spec plus "id":"<id from the worklist>".
-  node ${cli} kb write /tmp/spec1.json --root ${root} --session ${sid} --force
-  Flow/lesson shapes: run \`node ${cli} kb write --root ${root}\` with no spec — it prints the full guide.
+  Update = the same spec plus "id":"<id from the worklist>". Retract a note you \
+found wrong: {"op":"retract","id":"<id>","target":{"kind":"note"}} (as one array element).
+  cat > /tmp/notes.json <<'JSON'
+  [ {…note 1…}, {…note 2…} ]
+JSON
+  node ${cli} kb write /tmp/notes.json --root ${root} --session ${sid} --force
+  Full shapes: run \`node ${cli} kb write --root ${root}\` with no spec — it prints the guide.
 
 FLOW DECISION — record what you decided about FLOWS (created a new one, folded into an \
-existing one, or none) so the flow gate can be measured. Ride it on your LAST kb write — it \
+existing one, or none) so the flow gate can be measured. Ride it on the SAME batch write — it \
 is a flag, not a second command:
-  node ${cli} kb write /tmp/specN.json --root ${root} --session ${sid} --force \\
+  node ${cli} kb write /tmp/notes.json --root ${root} --session ${sid} --force \\
     --decision <none|new|update> [--id <flow id>] --why "<one clause>"
 Only when you wrote NO notes at all is there no write to carry it, and then run it alone:
   node ${cli} kb flow-decision --decision none --why "<one clause>" --root ${root} --session ${sid}${tail}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cstart/coldstart",
-  "version": "2.2.13",
+  "version": "2.2.15",
   "mcpName": "io.github.AkashGoenka/coldstart",
   "publishConfig": {
     "access": "public"

package/dist/kb/session-worklist.d.ts

@@ -1,10 +0,0 @@
-/** Paths this spec puts a note on. Flow steps do NOT count: a flow verifies
- *  files, it does not give any of them the file note rule 5 asks for. */
-export declare function specPaths(spec: unknown): string[];
-/**
- * Record this write against the session worklist and return the coverage line
- * to print, or null when there is no manifest to compare against (no --session,
- * a manual `kb write` outside capture, a session that never armed).
- */
-export declare function noteCoverage(sid: string | undefined, spec: unknown): string | null;
-//# sourceMappingURL=session-worklist.d.ts.map

package/dist/kb/session-worklist.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"session-worklist.d.ts","sourceRoot":"","sources":["../../src/kb/session-worklist.ts"],"names":[],"mappings":"AA8CA;yEACyE;AACzE,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAIjD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CA8BlF"}

package/dist/kb/session-worklist.js

@@ -1,92 +0,0 @@
-/**
- * Capture coverage — telling the writing agent how much of its worklist it noted.
- *
- * The gap this closes: the capture checklist hands the agent a worklist of every
- * file it worked on, but `kb write` only ever sees ONE spec, so nothing could
- * report "you wrote 8 notes for 30 worked files". The agent's own count is the
- * one thing it cannot check — it is mid-heredoc, and under-capture is silent by
- * construction. So the hook drops the worklist in tmpdir when it builds the
- * capture prompt, and every `kb write --session <sid>` prints the running ratio.
- *
- * CONTRACT TWIN: hooks/capture-payload.mjs (worklistManifestPath) writes this
- * file; keep the name and shape in step. Everything here is best-effort — a
- * missing, stale or malformed manifest prints nothing and never fails a write.
- *
- * Local only. The manifest lives in tmpdir, never in the repo: it is scratch
- * state for one session, not a record, and nothing about it is transmitted.
- */
-import { readFileSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-/** Manifests older than this are a resumed/unrelated session — ignore them. */
-const MAX_AGE_MS = 24 * 60 * 60 * 1000;
-/** Below this share of outstanding files, name the skips. */
-const LOW_COVERAGE = 0.5;
-const LIST_MAX = 6;
-function manifestPath(sid) {
-    return join(tmpdir(), `coldstart-kb-worklist-${sid}.json`);
-}
-function load(sid) {
-    try {
-        const m = JSON.parse(readFileSync(manifestPath(sid), 'utf8'));
-        if (!Array.isArray(m?.files) || !m.files.length)
-            return null;
-        if (typeof m.ts === 'number' && Date.now() - m.ts > MAX_AGE_MS)
-            return null;
-        m.wrote = Array.isArray(m.wrote) ? m.wrote : [];
-        return m;
-    }
-    catch {
-        return null;
-    }
-}
-/** Paths this spec puts a note on. Flow steps do NOT count: a flow verifies
- *  files, it does not give any of them the file note rule 5 asks for. */
-export function specPaths(spec) {
-    const s = spec;
-    if (!s || typeof s.path !== 'string')
-        return [];
-    return s.type === 'file-single' || s.type === 'file-hub' ? [s.path] : [];
-}
-/**
- * Record this write against the session worklist and return the coverage line
- * to print, or null when there is no manifest to compare against (no --session,
- * a manual `kb write` outside capture, a session that never armed).
- */
-export function noteCoverage(sid, spec) {
-    if (!sid)
-        return null;
-    const m = load(sid);
-    if (!m)
-        return null;
-    for (const p of specPaths(spec))
-        if (!m.wrote.includes(p))
-            m.wrote.push(p);
-    try {
-        writeFileSync(manifestPath(sid), JSON.stringify(m));
-    }
-    catch { /* best-effort */ }
-    const outstanding = m.files.filter((f) => f.needsNote);
-    if (!outstanding.length)
-        return null;
-    const wrote = new Set(m.wrote);
-    const done = outstanding.filter((f) => wrote.has(f.path));
-    const left = outstanding.filter((f) => !wrote.has(f.path));
-    const already = m.files.length - outstanding.length;
-    const lines = [
-        `capture coverage: ${done.length} of ${outstanding.length} worklist files noted` +
-            (already ? ` (${already} more already had a fresh note)` : ''),
-    ];
-    if (left.length) {
-        const shown = left.slice(0, LIST_MAX).map((f) => `${f.path} [${f.tier}]`).join(', ');
-        lines.push(`  not noted yet: ${shown}${left.length > LIST_MAX ? `, +${left.length - LIST_MAX} more` : ''}`);
-    }
-    // The nudge fires only on the low end, and asks for a REASON rather than more
-    // notes: a deliberate skip is a fine answer, an invisible one is not. Chained
-    // writes each print this, so the last line of the block carries the real tally.
-    if (left.length && done.length / outstanding.length < LOW_COVERAGE) {
-        lines.push('  if those need no note, say which and why in your reply — an unexplained skip reads as a forgotten one.');
-    }
-    return lines.join('\n');
-}
-//# sourceMappingURL=session-worklist.js.map

package/dist/kb/session-worklist.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"session-worklist.js","sourceRoot":"","sources":["../../src/kb/session-worklist.ts"],"names":[],"mappings":"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"}