shadok-ai 0.12.1 → 0.12.3

package/context/ledger-reflex.md

@@ -9,11 +9,15 @@ open, a PR being unmerged, a task undone, a campaign live — **verify it first*
   `git log`), never assume "not merged".
 - **Everything else** (infra, marketing, site, ops, tasks): the `shadok-ledger`
   skill — `node ~/.claude/skills/shadok-ledger/ledger.mjs check "<topic>"`.
+  Ask in plain language; it ranks by word overlap, so you need not guess the
+  exact wording a sibling used.
 
 Then let it steer you:
 - a record says **resolved / done** → do NOT re-raise or re-act; report it handled;
 - **nothing recorded is UNKNOWN, not "not done"** → ask the human or hedge
   ("de mémoire, à faire — dis-moi si c'est déjà réglé"), don't assert;
+- rows printed under **"related rows — they may NOT answer your question"** are
+  leads, not an answer: you are still in the UNKNOWN case above;
 - a **stale** record (days old) → confirm before acting.
 
 **You are also pushed the changes.** Ahead of each turn you are given — a user

package/context/ledger-skill/SKILL.md

@@ -20,13 +20,23 @@ system of record**: infra changes, marketing actions, site activity, ops, tasks.
 Run `check` and let it steer you:
 
 ```
-node ~/.claude/skills/shadok-ledger/ledger.mjs check "<topic or entity>"
+node ~/.claude/skills/shadok-ledger/ledger.mjs check "<topic, in your own words>"
 ```
 
+**Ask in plain language — don't try to guess how a sibling worded the row.** The
+search ranks rows by word overlap, so `check "claude launcher stub spawn
+failure"` finds `claude-launcher-stub-breaks-spawns`. Describing the topic in a
+few words beats one lucky keyword; extra words that turn out to be absent cost
+you nothing.
+
 - a row says **resolved / done** → do NOT re-raise or re-act; report it as handled.
 - **nothing recorded** → treat as **UNKNOWN**, not as "not done": ask the human
   or hedge ("from memory, still to do — tell me if it is already handled"),
   don't assert.
+- **related rows — they may NOT answer your question** → exactly what it says:
+  the search found no row that answers you, only rows sharing some words. You
+  are still in the UNKNOWN case above. Read them as leads (they may point at the
+  right topic under another name), never as a status to assert.
 - a **stale** row (many days old) → hedge and confirm before acting.
 
 This fires on status-dependent claims (a bug being open, a PR unmerged, a task

package/context/ledger-skill/ledger-core.mjs

@@ -67,21 +67,118 @@ export function upsertEntry(entries, patch, now, newId) {
   return [...entries.filter((e) => normEntity(e.entity) !== key), row];
 }
 
+/* --------------------------------------------------------------------- *
+ * Recall: answering a QUESTION, not demanding the exact wording.
+ *
+ * `check` used to match the whole query as a SUBSTRING of the id, entity or
+ * note — so it answered only when the caller already knew how a sibling had
+ * phrased the row, which is exactly when they did not need to ask. Measured on
+ * the live 64-row table against fifteen queries agents really typed: ZERO
+ * returned anything, while the matching row sat there in plain sight
+ * ("claude launcher stub spawn failure" vs `claude-launcher-stub-breaks-spawns`).
+ * Each got "(nothing recorded — treat as UNKNOWN)", which the reflex reads as
+ * "there is nothing here" — the very silo the ledger exists to close.
+ *
+ * So: word overlap weighted by IDF, computed over the table itself.
+ * Design and the tuning sweep: docs/superpowers/specs/2026-09-09-ledger-recall.md
+ * --------------------------------------------------------------------- */
+
+/** A hit in the entity is worth more than one in the details — but the details
+ *  are still evidence, so this BOOSTS rather than caps: a query fully covered by
+ *  a note must still be able to be a strong match. */
+const FIELD_WEIGHT = { entity: 1, note: 0.7, source: 0.7 };
+/** A word the table has never seen is DISCOUNTED, not ignored. Ignoring it
+ *  outright let a query whose subject is absent score a perfect match on the
+ *  filler words it happened to share with a note; counting it in full threw away
+ *  long real queries whose subject IS recorded under other words. */
+const UNKNOWN_TERM_PENALTY = 0.2;
+/** Two tiers, because "nothing recorded is UNKNOWN" is load-bearing: a search
+ *  that always returns SOMETHING would quietly erase that third state. */
+const STRONG = 0.55;
+const WEAK = 0.25;
+
+/** Words, not substrings: lowercased, split on non-alphanumerics, 1-char tokens
+ *  dropped, a trailing plural stripped — which is what lets "spawn failure"
+ *  reach "…-breaks-spawns". */
+export function tokenize(s) {
+  return String(s ?? "")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length > 1)
+    .map((w) => (w.length > 3 && w.endsWith("s") && !w.endsWith("ss") ? w.slice(0, -1) : w));
+}
+
+/** Document frequency per term over the whole table — the corpus the scoring is
+ *  relative to, so it self-tunes and needs no domain vocabulary. */
+function docFreq(entries) {
+  const df = new Map();
+  for (const e of entries) {
+    const seen = new Set([...tokenize(e.entity), ...tokenize(e.note), ...tokenize(e.source)]);
+    for (const t of seen) df.set(t, (df.get(t) ?? 0) + 1);
+  }
+  return df;
+}
+
 /**
- * Rows whose id, entity OR note contains the query (case-insensitive), most-
- * recent first. An empty query returns the whole table (for `list`).
+ * Rows matching `query`, split into `strong` (this is your answer) and `weak`
+ * (this merely shares words with your question), each ranked best-first and
+ * capped. An empty query returns the whole table in `strong`, recent-first.
+ *
+ * The caller MUST keep the two apart: a weak row is a lead, never a status to
+ * assert on.
  */
-export function findEntries(entries, query) {
+export function searchEntries(entries, query, opts = {}) {
+  const strongAt = opts.strong ?? STRONG;
+  const weakAt = opts.weak ?? WEAK;
+  const byRecency = (a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0);
   const q = normEntity(query);
-  const rows = q
-    ? entries.filter(
-        (e) =>
-          String(e.id ?? "").toLowerCase().includes(q) ||
-          normEntity(e.entity).includes(q) ||
-          normEntity(e.note ?? "").includes(q),
-      )
-    : entries.slice();
-  return rows.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+  if (!q) return { strong: entries.slice().sort(byRecency), weak: [] };
+
+  // An id is a durable handle an agent quotes from the pushed block: it must
+  // resolve whatever the corpus thinks of it as a word. Before the term guard,
+  // which would drop it as a term the table has never seen.
+  const byId = resolveId(entries, q);
+  if (byId) return { strong: [byId], weak: [] };
+
+  const df = docFreq(entries);
+  const N = entries.length || 1;
+  const idf = (t) => Math.log(1 + N / (1 + (df.get(t) ?? 0)));
+  // A term in most of the table cannot discriminate. Derived, never listed:
+  // "to" is a stopword in one table and "ledger" in none of ours, and no
+  // hand-written list would have known that.
+  const terms = [...new Set(tokenize(query))].filter((t) => !((df.get(t) ?? 0) >= 4 && df.get(t) > 0.4 * N));
+  const known = terms.filter((t) => df.get(t));
+  if (!known.length) return { strong: [], weak: [] };
+  const denom =
+    known.reduce((a, t) => a + idf(t), 0) +
+    UNKNOWN_TERM_PENALTY * terms.filter((t) => !df.get(t)).reduce((a, t) => a + idf(t), 0);
+
+  const scored = entries
+    .map((e) => {
+      // A verbatim substring is the old behaviour and still wins outright, so
+      // what `check` used to answer it still answers, identically.
+      if (String(e.id ?? "").toLowerCase() === q || `${e.entity} ${e.note ?? ""}`.toLowerCase().includes(q))
+        return { e, score: 1 };
+      const F = { entity: tokenize(e.entity), note: tokenize(e.note), source: tokenize(e.source) };
+      let matched = 0;
+      for (const t of known) {
+        const w = F.entity.includes(t)
+          ? FIELD_WEIGHT.entity
+          : F.note.includes(t)
+            ? FIELD_WEIGHT.note
+            : F.source.includes(t)
+              ? FIELD_WEIGHT.source
+              : 0;
+        matched += idf(t) * w;
+      }
+      return { e, score: denom ? matched / denom : 0 };
+    })
+    .sort((a, b) => b.score - a.score || byRecency(a.e, b.e));
+
+  return {
+    strong: scored.filter((x) => x.score >= strongAt).slice(0, 5).map((x) => x.e),
+    weak: scored.filter((x) => x.score < strongAt && x.score >= weakAt).slice(0, 3).map((x) => x.e),
+  };
 }
 
 /** Whole days since a row was last touched — the freshness the reflex hedges on. */

package/context/ledger-skill/ledger.mjs

@@ -10,7 +10,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
-import { upsertEntry, findEntries, ageDays, resolveId, normEntity } from "./ledger-core.mjs";
+import { upsertEntry, searchEntries, ageDays, resolveId, normEntity } from "./ledger-core.mjs";
 
 const FILE =
   (process.env.SHADOK_LEDGER_FILE || "").trim() ||
@@ -68,12 +68,21 @@ if (cmd === "check") {
     console.error('usage: ledger check "<topic or entity>"');
     process.exit(2);
   }
-  const hits = findEntries(load(), q);
-  if (hits.length === 0) {
+  // Two tiers, and the difference is the whole point: `strong` answers the
+  // question, `weak` merely shares words with it. Collapsing them would make a
+  // loosely-related row read as a status — the opposite of what this gates.
+  const { strong, weak } = searchEntries(load(), q);
+  if (strong.length) {
+    console.log(strong.map((e) => fmt(e, now)).join("\n"));
+  } else {
     // Nothing recorded is NOT "not done" — it's UNKNOWN. Tell the agent to hedge.
+    // This line comes FIRST and unchanged even when there are leads below it:
+    // the reflex keys on it, and a lead must not quietly become an answer.
     console.log(`(nothing recorded for "${q}" — treat as UNKNOWN: ask or hedge, do not assert)`);
-  } else {
-    console.log(hits.map((e) => fmt(e, now)).join("\n"));
+    if (weak.length) {
+      console.log(`\nrelated rows — they may NOT answer your question, do not assert on them:`);
+      console.log(weak.map((e) => fmt(e, now)).join("\n"));
+    }
   }
 } else if (cmd === "record") {
   const f = parseFlags(rest);
@@ -105,7 +114,7 @@ if (cmd === "check") {
   const row = byId ? resolveId(rows, f.id) : rows.find((r) => normEntity(r.entity) === normEntity(f.entity));
   console.log(`recorded: ${row.entity} — ${row.status} [${row.id}]`);
 } else if (cmd === "list") {
-  const rows = findEntries(load(), "");
+  const rows = searchEntries(load(), "").strong;
   console.log(rows.length ? rows.map((e) => fmt(e, now)).join("\n") : "(ledger empty)");
 } else {
   console.error("usage: ledger <check|record|list> …");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadok-ai",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "main": "dist/session.js",
   "scripts": {
     "test": "node --import tsx --test test/*.ts context/*/test/*.test.mjs",

package/public/index.html

@@ -879,13 +879,15 @@
     overflow-x: auto;
   }
   .bubble.md pre code { background: none; padding: 0; }
+  /* The horizontal scroll for a wide table lives on this wrapper (added in JS
+     after sanitising), NOT on the <table>: `display:block` on a table breaks its
+     own layout — thead and tbody stop sharing column widths, so the header row
+     detaches and misaligns from the body. */
+  .bubble.md .md-table-wrap { overflow-x: auto; max-width: 100%; margin: 8px 0; }
   .bubble.md table {
     border-collapse: collapse;
-    margin: 8px 0;
     font-size: 13px;
-    display: block;
-    overflow-x: auto;
-    max-width: 100%;
+    width: auto;
   }
   .bubble.md th, .bubble.md td {
     border: 1px solid var(--line);
@@ -4077,6 +4079,17 @@
     if (role === "claude" && (extraClass === "hist" || extraClass === "live") && window.marked && window.DOMPurify) {
       bubble.classList.add("md");
       bubble.innerHTML = DOMPurify.sanitize(marked.parse(text));
+      // A wide table must be able to scroll sideways WITHOUT `display:block` on
+      // the <table> itself — that turns the thead and tbody into separate stacked
+      // blocks that size their columns independently, so the header detaches from
+      // the body and the columns no longer line up (a real, reported render bug).
+      // The scroll belongs on a wrapper; the table stays a real table.
+      for (const t of bubble.querySelectorAll("table")) {
+        const wrap = document.createElement("div");
+        wrap.className = "md-table-wrap";
+        t.replaceWith(wrap);
+        wrap.appendChild(t);
+      }
     } else {
       bubble.textContent = text;
     }