@nurix/etna 0.15.7 → 0.16.0

package/data/harnesses/code/hooks/session-reflect.js

@@ -0,0 +1,283 @@
+// plugins/code/hooks/session-reflect.js — SessionEnd hook: reflect the session into durable lessons (headless haiku pass) appended to the actor's memory inbox.
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync, spawn } = require("child_process");
+const { redact } = require("./lib/redact.js");
+
+// A session below all three thresholds carries no lesson worth a model call.
+const MIN_TURNS = 8;
+const MAX_MESSAGE_CHARS = 1500;
+const MAX_DIGEST_CHARS = 80000;
+const MAX_LESSONS = 6;
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Run a git command in projectDir; returns trimmed stdout or fallback on any error.
+function git(projectDir, args, fallback) {
+  try {
+    return execFileSync("git", ["-C", projectDir, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || fallback;
+  } catch (e) {
+    return fallback;
+  }
+}
+
+// Slug a raw actor name into kebab-case ASCII.
+function slugActor(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Determine the actor: git user.name (slugged) → $USER → "agent".
+function resolveActor(projectDir) {
+  const fromGit = slugActor(git(projectDir, ["config", "user.name"], ""));
+  if (fromGit) return fromGit;
+  const fromEnv = slugActor(process.env.USER || "");
+  if (fromEnv) return fromEnv;
+  return "agent";
+}
+
+// Truncate a single line to n chars with an ellipsis marker.
+function clip(text, n) {
+  const clean = String(text || "").replace(/\s+/g, " ").trim();
+  return clean.length > n ? clean.slice(0, n) + "…" : clean;
+}
+
+// Extract plain text from a message whose content is a string or content-block array.
+function extractText(msg) {
+  if (!msg || !msg.content) return "";
+  if (typeof msg.content === "string") return msg.content;
+  if (Array.isArray(msg.content)) {
+    return msg.content
+      .filter((b) => b && b.type === "text" && typeof b.text === "string")
+      .map((b) => b.text)
+      .join(" ");
+  }
+  return "";
+}
+
+// Strip harness-injected wrappers so only what the user actually typed survives.
+function stripInjected(text) {
+  return String(text || "")
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, "")
+    .replace(/<(local-command-caveat|local-command-stdout|local-command-stderr|command-name|command-message|command-args|command-contents)>[\s\S]*?<\/\1>/g, "")
+    .trim();
+}
+
+// Scan an assistant message's tool_use blocks for edited files and git commits.
+function collectToolUse(msg, summary) {
+  if (!msg || !Array.isArray(msg.content)) return;
+  for (const block of msg.content) {
+    if (!block || block.type !== "tool_use") continue;
+    const name = block.name || "";
+    const input = block.input || {};
+    if (/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(name) && input.file_path) {
+      summary.files.add(input.file_path);
+    }
+    if (name === "Bash" && typeof input.command === "string" && /\bgit\s+commit\b/.test(input.command)) {
+      summary.sawCommit = true;
+    }
+  }
+}
+
+// Walk the JSONL transcript once: turn/edit/commit counts plus a USER/ASSISTANT text digest.
+function digestTranscript(transcriptPath) {
+  const out = { turns: 0, files: new Set(), sawCommit: false, lines: [] };
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return out;
+  for (const line of fs.readFileSync(transcriptPath, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch (e) {
+      continue;
+    }
+    if (row.isSidechain) continue;
+    const msg = row && row.message ? row.message : row;
+    const role = (msg && msg.role) || row.type;
+    if (role === "user") {
+      const text = stripInjected(extractText(msg));
+      if (!text || text.startsWith("Caveat: The messages below")) continue;
+      out.lines.push("USER: " + clip(text, MAX_MESSAGE_CHARS));
+    } else if (role === "assistant") {
+      out.turns += 1;
+      collectToolUse(msg, out);
+      const text = extractText(msg);
+      if (text) out.lines.push("ASSISTANT: " + clip(text, MAX_MESSAGE_CHARS));
+    }
+  }
+  return out;
+}
+
+// Compute the per-actor inbox file path.
+function inboxPath(projectDir, actor) {
+  const dir = path.join(projectDir, "docs", "memory", "inbox");
+  return { dir, file: path.join(dir, `${actor}.md`) };
+}
+
+// True when this session already wrote an inbox entry (SessionEnd re-fires on resume).
+function alreadyReflected(file, sessionId) {
+  try {
+    return Boolean(sessionId) && fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(`session ${sessionId}`);
+  } catch (e) {
+    return false;
+  }
+}
+
+// Build the inbox file header block.
+function inboxHeader(actor) {
+  return `# Memory inbox — ${actor}\nSession lessons awaiting distillation — appended by the session-reflect hook, consumed by \`distiller facts\`.\n`;
+}
+
+// The full output contract sits AFTER the transcript — with it only up front, the model
+// continues the conversation in the transcript instead of reflecting on it.
+const PROMPT_HEADER = [
+  "You are a memory reflector. Below is the transcript of a FINISHED coding session,",
+  "delimited by <transcript> tags. Do not reply to it or continue it — you will be asked",
+  "to extract durable lessons from it after the closing tag.",
+  "",
+  "<transcript>",
+  "",
+].join("\n");
+
+const PROMPT_FOOTER = [
+  "",
+  "</transcript>",
+  "",
+  "The session above is over. Extract ONLY durable lessons a future session in this",
+  "repository would benefit from knowing:",
+  "- corrections or preferences the user stated",
+  "- failures whose root cause was found, with the fix",
+  "- decisions made, with their rationale",
+  "- discovered constraints or non-obvious facts about the project or its tooling",
+  "Rules:",
+  "- Most sessions contain none. If nothing qualifies, output exactly: NONE",
+  `- Otherwise output at most ${MAX_LESSONS} bullets and nothing else — no preamble, no headers.`,
+  '- Each bullet starts with "- [project]" (true of this repo or its tooling) or "- [user]" (true of this user).',
+  "- Each bullet is one complete, self-contained sentence with names and identifiers spelled out.",
+  "- Routine work (commits made, files edited, tasks completed) is NOT a lesson. Never include secrets.",
+].join("\n");
+
+// Hook mode: stash the payload and hand off to a detached worker so session exit is never delayed.
+function hook() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+  if (!payload.transcript_path) return;
+
+  const stash = {
+    projectDir: resolveProjectDir(payload),
+    transcriptPath: payload.transcript_path,
+    sessionId: payload.session_id || "",
+  };
+  const stashFile = path.join(os.tmpdir(), `etna-reflect-${stash.sessionId || process.pid}.json`);
+  fs.writeFileSync(stashFile, JSON.stringify(stash), "utf8");
+  spawn(process.execPath, [__filename, "--worker", stashFile], { detached: true, stdio: "ignore" }).unref();
+}
+
+// Worker mode: filter, digest, run the reflection model, append surviving lessons to the inbox.
+function worker(stashFile) {
+  let stash;
+  try {
+    stash = JSON.parse(fs.readFileSync(stashFile, "utf8"));
+  } finally {
+    try {
+      fs.rmSync(stashFile, { force: true });
+    } catch (e) {
+      // Stale stash files are harmless.
+    }
+  }
+
+  const { projectDir, transcriptPath, sessionId } = stash;
+  const digest = digestTranscript(transcriptPath);
+  if (digest.turns < MIN_TURNS && digest.files.size === 0 && !digest.sawCommit) return;
+
+  const actor = resolveActor(projectDir);
+  const { dir, file } = inboxPath(projectDir, actor);
+  if (alreadyReflected(file, sessionId)) return;
+
+  let text = redact(digest.lines.join("\n"));
+  if (text.length > MAX_DIGEST_CHARS) {
+    text = text.slice(0, 8000) + "\n[... middle of session elided ...]\n" + text.slice(-(MAX_DIGEST_CHARS - 8000));
+  }
+
+  const output = execFileSync("claude", ["-p", "--model", "haiku"], {
+    input: PROMPT_HEADER + text + PROMPT_FOOTER,
+    encoding: "utf8",
+    cwd: os.tmpdir(),
+    env: Object.assign({}, process.env, { ETNA_REFLECT: "1" }),
+    timeout: 240000,
+    maxBuffer: 4 * 1024 * 1024,
+    stdio: ["pipe", "pipe", "ignore"],
+  });
+
+  const lessons = output
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => /^- \[(project|user)\]\s+\S/.test(l))
+    .slice(0, MAX_LESSONS)
+    .map((l) => redact(l));
+  if (!lessons.length) return;
+
+  const repo = path.basename(projectDir);
+  const branch = git(projectDir, ["rev-parse", "--abbrev-ref", "HEAD"], "-");
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  const stamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+
+  fs.mkdirSync(dir, { recursive: true });
+  if (alreadyReflected(file, sessionId)) return;
+  const exists = fs.existsSync(file);
+  const block =
+    (exists ? "\n" : inboxHeader(actor) + "\n") +
+    `## ${stamp} · session ${sessionId || "unknown"} · ${repo}@${branch}\n` +
+    lessons.join("\n") +
+    "\n";
+  fs.appendFileSync(file, block, "utf8");
+}
+
+function main() {
+  if (process.env.ETNA_REFLECT) return;
+  const workerIdx = process.argv.indexOf("--worker");
+  if (workerIdx !== -1) {
+    worker(process.argv[workerIdx + 1]);
+  } else {
+    hook();
+  }
+}
+
+try {
+  main();
+} catch (e) {
+  try {
+    process.stderr.write(`session-reflect hook: ${e && e.message ? e.message : e}\n`);
+  } catch (e2) {
+    // Nothing more we can do.
+  }
+} finally {
+  process.exit(0);
+}

package/data/harnesses/code/skills/distiller/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: distiller
-description: The one place the raw event ledger is distilled into colder, higher-signal knowledge. One skill, two modes — `facts` (ledger → atomic provenance-linked fact-cards in `docs/memory/facts/`) and `docs` (fact-cards → proposed, human-approved doc deltas). Both modes read one shared algorithm spec, `references/method.md` (surprisal filter, EDU fact-cards, reconciliation, bi-temporal supersession — all stolen, all cited), so they can never drift apart. NEVER edits the ledger (append-only audit substrate); NEVER auto-runs (invoked by the user, or by accepting the maintenance agent's threshold proposal). Triggers on "distill the ledger", "distill facts", "run the distiller", "distill into fact-cards", "facts from the ledger", "distill docs", "draft doc deltas", "distiller docs", "/distiller".
+description: The one place captured session lessons are distilled into colder, higher-signal knowledge. One skill, two modes — `facts` (memory inbox → atomic provenance-linked fact-cards in `docs/memory/facts/`) and `docs` (fact-cards → proposed, human-approved doc deltas). Both modes read one shared algorithm spec, `references/method.md` (surprisal filter, EDU fact-cards, reconciliation, bi-temporal supersession — all stolen, all cited), so they can never drift apart. Consumes the inbox entries it digests (the inbox is a queue, not an audit log — git history and commit/session provenance are the audit trail); NEVER auto-runs (invoked by the user, or by accepting the maintenance agent's threshold proposal). Triggers on "distill the inbox", "distill facts", "run the distiller", "distill into fact-cards", "facts from the inbox", "distill docs", "draft doc deltas", "distiller docs", "/distiller".
 ---
 
 # Distiller Skill
 
-The one place a repo's **raw event ledger** is distilled into colder,
-higher-signal knowledge. The ledger (`docs/memory/ledger/`) is a high-volume,
-append-only stream of what happened; the distiller turns the *surprising* part of
-it into atomic, self-contained, provenance-linked **fact-cards**
-(`docs/memory/facts/`). Volume falls, signal rises — one hop down the
-distillation gradient.
+The one place a repo's **captured session lessons** are distilled into colder,
+higher-signal knowledge. The memory inbox (`docs/memory/inbox/{actor}.md`) is a
+per-actor queue of lessons the `session-reflect` hook extracted at session end;
+the distiller reconciles the *surprising* part of it into atomic, self-contained,
+provenance-linked **fact-cards** (`docs/memory/facts/`) and consumes the entries
+it digests. Volume falls, signal rises — one hop down the distillation gradient.
 
 The methods this skill runs are **stolen, not invented** — surprisal-based
 retention (Nemori), non-lossy EDU fact-cards (EMem), per-fact ADD/UPDATE/
@@ -19,8 +19,8 @@ Graphiti). They live in exactly one place:
 
 > **Read [`references/method.md`](references/method.md) first, in every mode.**
 > It carries the four mechanisms verbatim-grade (with their arXiv ids — provenance
-> matters here of all places), the fact-card format, and the high-water-mark
-> protocol. This SKILL.md only orchestrates those mechanisms over the ledger.
+> matters here of all places), the fact-card format, and the inbox-consumption
+> protocol. This SKILL.md only orchestrates those mechanisms over the inbox.
 
 The reason the two modes are one skill: **both read one algorithm root.** Two
 components would mean two copies of the surprisal/reconciliation/supersession
@@ -32,7 +32,7 @@ model that drift apart. One skill, one spec, zero drift.
 
 | You want to… | Mode | Ships |
 |---|---|---|
-| Distill new ledger entries into fact-cards | **`facts`** | now |
+| Distill new inbox entries into fact-cards | **`facts`** | now |
 | Distill fact-cards into proposed doc deltas | **`docs`** | now — procedure in [`references/docs-mode.md`](references/docs-mode.md) |
 
 Both modes read [`references/method.md`](references/method.md); each mode's
@@ -43,57 +43,55 @@ procedure that sequences it lives in its own section below.
 Runs **in the main session** — no standing sub-agents, no daemon, no cron, no
 watch. The harness **proposes**, the user **disposes**: this skill runs only when
 the user asks, when the **Completion flow** invokes it (the kit `CLAUDE.md`
-Completion step distils the just-finished plan's trail — `facts` if the ledger
-advanced past the high-water mark, then `docs` which still drafts for approval),
-or when the user accepts the `maintenance` agent's threshold proposal (≥20
-undigested ledger entries). It never schedules itself, never runs on a hook,
-never gates anything.
+Completion step distils the just-finished plan's trail — `facts` if the inbox
+holds entries, then `docs` which still drafts for approval), or when the user
+accepts the `maintenance` agent's threshold proposal (≥5 undigested inbox
+entries). It never schedules itself, never runs on a hook, never gates anything.
 
 ---
 
-## Mode: `facts` (ledger → fact-cards)
+## Mode: `facts` (inbox → fact-cards)
 
-Distill ledger entries newer than the high-water mark into fact-cards. The
-algorithm is in [`references/method.md`](references/method.md) — follow it; this
-section is the procedure that sequences it.
+Distill the inbox's undigested entries into fact-cards. The algorithm is in
+[`references/method.md`](references/method.md) — follow it; this section is the
+procedure that sequences it.
 
-1. **Read the high-water mark.** Read `docs/memory/facts/.digest-state.md`
-   (the frontmatter records the last-digested file + entry timestamp **per
-   actor**). Absent ⇒ start of history — digest everything. Then collect ledger
-   entries from `docs/memory/ledger/YYYY-MM-DD--{actor}.md` that are **newer**
-   than the per-actor mark. This is what makes the run idempotent — an immediate
-   second run finds nothing new and is a clean NOOP.
+1. **Collect the inbox.** Read every entry block
+   (`## <timestamp> · session <id> · <repo>@<branch>`) across
+   `docs/memory/inbox/*.md`. The inbox is a consume-on-digest queue — what is
+   present is exactly what is undigested, so there is no separate high-water
+   mark. An immediate second run finds an empty inbox and is a clean NOOP.
 
-   **Thin or empty ledger ⇒ not a NOOP — distill the decision record.** A
-   commit-less project, or one whose ledger holds only mechanical entries the
-   surprisal filter would drop (a transient exit-1, a bare echo), is **not** a
-   project with nothing to distill. Architecture decisions and reversals are
+   **Thin or empty inbox ⇒ not a NOOP — distill the decision record.** A
+   project whose sessions produced no reflected lessons is **not** a project
+   with nothing to distill. Architecture decisions and reversals are
    high-surprisal by nature — they exist precisely because they were *not*
-   predictable. So when the ledger is thin/empty, also ingest, as surprisal
+   predictable. So when the inbox is thin/empty, also ingest, as surprisal
    sources for steps 2–5:
    - `docs/architecture/adr/**` — each accepted ADR is a surprising decision
      (its `Decision` + **Options Considered** — the rejected-alternatives section
      in the `documentation` §10 ADR template — carry the prediction error).
    - `docs/memory/brainstorm.md` — owner pronouncements, reversals, and
-     discovered constraints recorded outside the ledger.
-   Provenance points at the ADR file / brainstorm section, not a ledger
-   `#HH:MM`. These sources sit outside the high-water mark (which tracks ledger
-   entries only) — reconciliation (step 4) is what keeps a re-run idempotent.
+     discovered constraints recorded outside the inbox.
+   Provenance points at the ADR file / brainstorm section, not a session id.
+   These sources are **never consumed** — reconciliation (step 4) is what keeps
+   a re-run over them idempotent.
 
 2. **Surprisal filter → survivors** (method §1). Present the LLM with (a) a
-   summary of the *current* fact-set, (b) the new undigested entries. Keep only
+   summary of the *current* fact-set, (b) the undigested entries. Keep only
    what is **surprising** relative to (a). Predictable ⇒ dropped — no importance
-   scores, no templates, prediction error is the only retention signal. (First
-   run, empty fact-set: "predictable" = mechanical routine — a bare commit echo,
-   a transient exit-1 with no lesson; keep decisions, reversals, discovered
-   constraints, and failures with a cause worth remembering.)
+   scores, no templates, prediction error is the only retention signal. Inbox
+   entries arrive semi-distilled (the reflection hook already dropped routine
+   work), so the filter's job here is narrower: drop what the existing fact-set
+   already predicts. (First run, empty fact-set: keep decisions, reversals,
+   discovered constraints, and failures with a cause worth remembering.)
 
 3. **Decompose survivors → EDU candidates** (method §2). Each survivor becomes
    **one** atomic, self-contained statement — entity names normalized, minimal
-   context baked into the sentence — with `provenance` pointing back at the
-   ledger entries/commits it derives from. Decomposition, **not** summarization:
+   context baked into the sentence — with `provenance` pointing at the session
+   ids and commits its inbox entry names. Decomposition, **not** summarization:
    one survivor may yield several cards; no information is destroyed; everything
-   stays auditable back to raw.
+   stays auditable back to its session and commits.
 
 4. **Reconcile each candidate against existing cards** (method §3). Query the
    existing facts for semantic neighbors, then decide
@@ -132,35 +130,39 @@ section is the procedure that sequences it.
      See method.md §4 "Self-contained reversal."
    - **NOOP** → the fact is already known; write nothing.
 
-6. **Update the high-water mark LAST.** Only after every card is written, update
-   `docs/memory/facts/.digest-state.md` to the newest entry timestamp processed
-   per actor. Last, so a crash mid-run re-digests rather than silently skips.
+6. **Consume the digested entries LAST.** Only after every card is written,
+   delete exactly the entry blocks this run digested from
+   `docs/memory/inbox/*.md` (keep each file's header; never touch undigested
+   blocks). Last, so a crash mid-run leaves the entries in place and the re-run
+   re-digests them — reconciliation NOOPs the already-written cards. This
+   consumption is the only bookkeeping; there is no `.digest-state.md`.
 
 7. **If qmd present, refresh the lens** (skip silently if `command -v qmd`
    finds nothing):
    - `qmd collection add docs/memory/facts --name {repo}-facts` — register the
      collection. Re-adding an existing name exits non-zero with "already exists";
      **treat that as success.** Never register `docs/memory` as a whole — that
-     would sweep the raw ledger into the index.
+     would sweep the raw inbox queue into the index.
    - `qmd context add qmd://{repo}-facts/ "Distilled recent decisions/observations, provenance-linked"`
      — upserts, safe to re-run.
    - `qmd update` — **re-scan the collection for the cards you just wrote.** In
      qmd 2.5.3 `collection add` on an already-registered name does NOT re-index
      new files; `qmd update` is what picks them up. Skipping this leaves the new
-     cards invisible to retrieval (and to distill②).
+     cards invisible to retrieval (to the `prompt-recall` hook, and to distill②).
    - `qmd embed -c {repo}-facts` — regenerate vectors for the new/changed cards.
      Always scope with `-c`; a bare `qmd embed` re-embeds every repo on the
-     machine.
+     machine. The `prompt-recall` hook's vector fallback only sees embedded
+     cards, so skipping this hides new cards from prompt-time recall.
 
 8. **Report** (in chat). Cards added / updated / superseded / NOOP'd, the
-   high-water mark advance per actor, and — if reconciliation fell back to
+   entries consumed per actor, and — if reconciliation fell back to
    filename/grep (qmd absent, **or** `{repo}-facts` registered but holding no
    cards yet — the first-run-on-a-scaffolded-facts-dir case) — the one advisory
    line saying so. Fire this advisory whenever semantic retrieval was effectively
    unavailable, even if the collection appeared in `qmd collection list`: a
    registered-but-empty collection is not semantic retrieval. A run that finds
    nothing surprising is **valid**: say
-   "no surprising entries since the mark," don't pad.
+   "no surprising entries in the inbox," don't pad.
 
 ---
 
@@ -179,14 +181,14 @@ It NEVER writes a doc on its own — it **drafts and presents**; the human dispo
 
 - **One algorithm root.** Every mode reads `references/method.md`. Extend the
   spec there — never inline a divergent copy of the four methods in a mode.
-- **Never edit the ledger.** `docs/memory/ledger/` is the append-only audit
-  substrate. The distiller is **read-only** on it — no deletes, no rewrites, no
-  reordering, not even archiving. It writes only under `docs/memory/facts/`.
-- **Idempotent via the mark.** The high-water mark is the only thing standing
-  between this skill and reprocessing. Read it first, advance it last; a second
-  run with no new entries is a NOOP.
+- **Consume, never rewrite.** `docs/memory/inbox/` is a queue owned by the
+  `session-reflect` capture hook. The distiller deletes exactly the entry blocks
+  it digested this run — no edits, no reordering, no touching undigested blocks.
+  Beyond that consumption it writes only under `docs/memory/facts/`.
+- **Idempotent via consumption.** What is in the inbox is what is undigested.
+  Consume last; a second run finds an empty inbox and is a NOOP.
 - **Cards are atomic and provenance-linked.** One self-contained statement per
-  card; every card resolves back to the ledger entries/commits it came from.
+  card; every card resolves back to the session ids and commits it came from.
   Decompose — never lossily summarize.
 - **Supersede ≠ delete.** Bi-temporal only: set `invalid_from:` +
   `superseded_by:` on the old card and leave the file in place. Nothing is ever
@@ -208,9 +210,9 @@ It NEVER writes a doc on its own — it **drafts and presents**; the human dispo
 
 ## Output locations
 
-- `facts` writes fact-cards to `docs/memory/facts/{kebab-slug}.md` and the
-  high-water mark to `docs/memory/facts/.digest-state.md`; the report goes to
-  chat. It reads `docs/memory/ledger/` but never writes there.
+- `facts` reads `docs/memory/inbox/`, writes fact-cards to
+  `docs/memory/facts/{kebab-slug}.md`, and deletes the consumed entry blocks
+  from the inbox; the report goes to chat.
 - `docs` presents doc deltas in chat and, **only on approval**, writes the accepted
   prose into the target doc under `docs/` (+ a new `docs/history/changelog/` entry if
   drafted) and appends `digested_into:` to each consumed card in `docs/memory/facts/`.

package/data/harnesses/code/skills/distiller/references/docs-mode.md

@@ -8,7 +8,7 @@ from `docs/memory/facts/` (warm, distilled cards) into proposed edits to `docs/`
 human-owned SSoT). It NEVER writes a doc on its own — it **drafts and presents**; the human
 disposes (P7).
 
-> `facts` mode = ledger → cards. `docs` mode = cards → *presented* doc deltas. One component,
+> `facts` mode = inbox → cards. `docs` mode = cards → *presented* doc deltas. One component,
 > two modes, one algorithm root. distill② is the greenfield hop no surveyed tool has built
 > (prior art stops at index/retrieval); the discipline below is what keeps it from corrupting
 > documentation.
@@ -23,14 +23,14 @@ mechanically check every claim:
 
 > **Two-way traceability.** Every drafted delta *line* names the fact-card(s) it decomposes
 > from (forward: delta → card). Every consumed card names the doc(s) it was digested into
-> (backward: card → delta). Every card already names the ledger entries/commits it came from
-> (`provenance`, from `facts` mode). The chain **doc-line → card → ledger entry → commit**
+> (backward: card → delta). Every card already names the sessions/commits it came from
+> (`provenance`, from `facts` mode). The chain **doc-line → card → session/commit**
 > must resolve end to end with no orphan link. A delta line with no card, or a card marked
 > digested into a doc that does not contain its content, is a **defect**: the run fails its
 > acceptance check, the line is not presented.
 
 This mode introduces **no prose that is not a decomposition of a card** — decomposition-with-
-citation, exactly as `facts` mode decomposes ledger entries into cards. If the agent cannot
+citation, exactly as `facts` mode decomposes inbox entries into cards. If the agent cannot
 cite a card for a sentence, that sentence is not written.
 
 ---
@@ -90,7 +90,7 @@ independently.
 > Each step names the failure mode(s) it closes. Ordering is load-bearing: the pillar check
 > precedes drafting (a belief-changing card never reaches the draft); the digestion mark is
 > written **last** (a crash re-presents rather than silently swallows — the mirror of `facts`
-> mode's "advance the high-water mark last").
+> mode's "consume the digested entries last").
 
 ### 0. Read the roots
 
@@ -173,20 +173,20 @@ The output of this step is a **single presented delta document** (in chat, not w
 disk):
 
 ```
-TARGET: docs/features/memory-ledger.md
+TARGET: docs/features/memory-capture.md
 
 ── PROPOSED DELTA ────────────────────────────────────────
 § Current Behavior  (EXTEND)
   + The qmd retrieval lens is organized into per-subtree collections, with the
-    raw ledger excluded from indexing by construction.   [from: fact-qmd-optional-retrieval-lens]
+    memory inbox excluded from indexing by construction.   [from: fact-qmd-optional-retrieval-lens]
 
 § Changelog entry  (new — docs/history/changelog/2026-06-04-...md)
   ### Modified
   - capture-hook merge is now idempotent across re-install   [from: fact-etna-hook-merge-idempotent]
 
 ── QUESTIONS (D7 phrasing — answer before accept) ────────
-  Q1. docs/features/memory-ledger.md §Current Behavior says the index spans all of
-      docs/memory; fact-qmd-optional-retrieval-lens says the raw ledger is excluded.
+  Q1. docs/features/memory-capture.md §Current Behavior says the index spans all of
+      docs/memory; fact-qmd-optional-retrieval-lens says the memory inbox is excluded.
       Confirm the doc is stale before I revise it — I will not overwrite it silently.
 
 ── PILLAR-CONFLICT ESCAPE (NOT a doc edit) ───────────────
@@ -238,7 +238,7 @@ Append the declined delta to `docs/history/backlog.md` at the finding's own P0
 (same scale as code work), deduped:
 
 ```
-- **[P2]** distiller-docs proposed updating docs/features/memory-ledger.md §Current Behavior from fact-qmd-optional-retrieval-lens (declined) — discovered by distiller docs
+- **[P2]** distiller-docs proposed updating docs/features/memory-capture.md §Current Behavior from fact-qmd-optional-retrieval-lens (declined) — discovered by distiller docs
 ```
 
 Dedupe by (target doc § section, contributing card-ids): if an identical pending item exists,
@@ -266,11 +266,11 @@ broad capture, conservative gating.
 
 **(a) Structural intersection (exact, always evaluated).** True when ANY of:
 
-1. **Provenance match (STRONG signal).** A path in the card's `provenance` matches a glob in
-   the target's `owns`/`touches`. A `provenance` entry may be a `ledger/...#HH:MM` reference
-   (the entry names files) or a `commit <sha>`. Resolve a commit's changed files with
-   `git show --name-only <sha>` when the commit is local; a changed file under the doc's globs
-   is a match. This is strong because the card derives from a commit that edited code the doc
+1. **Provenance match (STRONG signal).** A `commit <sha>` entry in the card's `provenance`
+   resolves to changed files (`git show --name-only <sha>` when the commit is local); a changed
+   file under the target's `owns`/`touches` globs is a match. (`session <id>` entries carry no
+   paths and do not participate; an ADR/brainstorm path matches the globs directly.) This is
+   strong because the card derives from a commit that edited code the doc
    owns.
 2. **Entity match (SUPPORTING signal).** A normalized name in the card's `entities` equals
    (case-insensitively, after kebab/camel normalization) a module/feature stem in an `owns`
@@ -338,10 +338,10 @@ valid_from: 2026-06-04
 invalid_from: null
 superseded_by: null
 digested_into:                                  # ← added by docs mode, on accept, never on draft
-  - docs/features/memory-ledger.md
+  - docs/features/memory-capture.md
   - docs/history/changelog/2026-06-04-qmd-lens.md
-entities: [qmd, retrieval-lens, per-subtree-collections, ledger]
-provenance: [ledger/2026-06-04--joyjeet-sarkar.md#00:31, commit d262e18]
+entities: [qmd, retrieval-lens, per-subtree-collections, inbox]
+provenance: [session e3c4a623, commit d262e18]
 ---
 ```
 
@@ -434,12 +434,12 @@ does not re-teach (the procedure lives in this file). Verbatim:
 > On Completion, after flipping the spec to `Active`, consult `distiller docs` for the just-completed feature's doc — it drafts any pending fact-card deltas for your approval (presented, never auto-written).
 
 **(b) Maintenance threshold — ONE line in `agents/maintenance.md` Step 7**, sibling to the
-existing ledger-distillation threshold (the `facts` analogue: ≥20 undigested *ledger entries*
+existing inbox-distillation threshold (the `facts` analogue: ≥5 undigested *inbox entries*
 proposes a `facts` run). Verbatim:
 
 > **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by Resolution 1's structural intersection (exact, qmd-independent). If **≥10** map to **one** doc, add one line to the report **proposing** a `distiller docs --doc <path>` run on that doc — propose only, never auto-run, no cron. Declined/ignored ⇒ the count keeps growing and the proposal reappears next pass; that recurrence is the dedupe, so never backlog the proposal itself.
 
-`N = 10` default (vs the ledger threshold's 20 — one hop colder, a lower bar). "Touch" uses the
+`N = 10` default (vs the inbox threshold's 5 — inbox entries are rare and rich; cards accrue per doc). "Touch" uses the
 **structural** retriever only (deterministic, no qmd dependency in the maintenance loop).
 Per-doc count, not repo-wide: the proposal names the one doc, so the run is already scoped. This
 lands as a proposal emitter only — maintenance does not run the distiller (P19: distinct axis).
@@ -519,7 +519,7 @@ resulting doc edit re-enter normally.
    nothing.
 8. **Idempotent via the digestion mark.** An immediate re-run on the same doc finds its touching
    cards already `digested_into:` that doc and is a clean NOOP — the digestion mark is to `docs`
-   mode what the high-water mark is to `facts` mode (F3).
+   mode what inbox consumption is to `facts` mode (F3).
 9. **Trigger budget.** Exactly one line added to `CLAUDE.md` Completion; exactly one line added to
    maintenance Step 7. No procedure inlined into either (P10).
 10. **Not autonomous.** No cron/daemon/hook; invoked by the Completion step, by accepting