@nurix/etna 0.18.15 → 0.18.16

package/data/harnesses/mobile/hooks/session-reflect.mjs

@@ -1,285 +0,0 @@
-// plugins/code/hooks/session-reflect.mjs — SessionEnd hook: reflect the session into durable lessons (headless haiku pass) appended to the actor's memory inbox.
-
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { execFileSync, spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { redact } from "./lib/redact.mjs";
-
-// ESM has no __filename; derive it from this module's URL for the detached worker re-spawn.
-const __filename = fileURLToPath(import.meta.url);
-
-// 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/mobile/skills/distiller/SKILL.md

@@ -1,90 +0,0 @@
----
-name: 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 **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/ SUPERSEDE/NOOP reconciliation (Mem0), and bi-temporal supersession (Zep/ 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 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 model that drift apart. One skill, one spec, zero drift.
-
----
-
-## Picking a mode
-
-| You want to… | Mode | Ships |
-| --- | --- | --- |
-| 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 procedure that sequences it lives in its own section below.
-
-## Execution model — pure skill, never autonomous
-
-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 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` (inbox → fact-cards)
-
-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. **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 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 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/brainstorm/{topic}/` — the kept Brainstorming-Mode design records (`pillars/decisions.md`, `rejected.md`, etc.): the reasoning, reversals, and roads-not-taken behind each design call, retained as committed provenance. The richest surprisal source the harness produces. (Where a repo keeps no brainstorm record in `docs/` — e.g. an older transient-workspace harness — fall back to `docs/memory/brainstorm.md`, the owner pronouncements recorded outside the inbox.) Provenance points at the ADR file / brainstorm pillar, 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 undigested entries. Keep only what is **surprising** relative to (a). Predictable ⇒ dropped — no importance 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 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 its session and commits.
-
-4. **Reconcile each candidate against existing cards** (method §3). Query the existing facts for semantic neighbors, then decide **ADD / UPDATE / SUPERSEDE / NOOP** for each. Gate on the **facts collection holding cards**, not on the binary and not on the collection merely being registered — a present qmd whose `{repo}-facts` collection is _registered but empty_ (the common first run: the `maintenance` agent's baseline mode registers + embeds `{repo}-facts` over a freshly-scaffolded `docs/memory/facts/` that has zero cards) returns nothing useful, exactly like an unregistered collection.
-   - **Cards present** — `command -v qmd` succeeds **and** `docs/memory/facts/` holds at least one card (`docs/memory/facts/*.md` is non-empty): query scoped to the collection — `qmd query --format json -c {repo}-facts "<the candidate statement>"`. `{repo}` = the repo's directory name. Scope with `-c` always. (If the query returns nothing on a non-empty card set, the collection is registered-but- unbuilt — treat that as the fallback trigger below, not as "no neighbors.")
-   - **No cards to query** (qmd absent, **or** `docs/memory/facts/*.md` empty — the common first-run case where the facts dir was scaffolded but never distilled into): fall back to filename/grep similarity over `docs/memory/facts/*.md` (slug overlap + entity-name grep), and **note in the report** that reconciliation ran without semantic retrieval. Step 7 builds/refreshes the collection at the end of the run, so the _next_ run — with cards now present — reconciles semantically.
-
-5. **Write the results** (method §4 — bi-temporal, never delete).
-   - **ADD** → write a new card `docs/memory/facts/{kebab-slug}.md` in the format.
-   - **UPDATE** → refine the existing card's statement in place; extend its `provenance`.
-   - **SUPERSEDE** → on the **old** card set `invalid_from:` (today) and `superseded_by:` (the new fact-id); write the **new** card with `valid_from:` today. The old file stays in place — history stays queryable, nothing vanishes.
-   - **Self-contained reversal** (one input states X-then-reversed-to-Y, no old card exists yet) → emit **two** cards in one pass: a born-invalid historical card for X (`invalid_from` + `superseded_by` → Y) and a live card for Y. See method.md §4 "Self-contained reversal."
-   - **NOOP** → the fact is already known; write nothing.
-
-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 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 (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. 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 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 in the inbox," don't pad.
-
----
-
-## Mode: `docs` (fact-cards → proposed doc deltas)
-
-Distill fact-cards into proposed edits to `docs/` (the cold, human-owned SSoT) — the next hop down the gradient from `facts`. The full procedure (input selection, delta drafting, digestion marking, the pillar escape valve, trigger wiring) is in [`references/docs-mode.md`](references/docs-mode.md) — follow it; reuses `method.md`'s surprisal / EDU / reconciliation / bi-temporal vocabulary unchanged. It NEVER writes a doc on its own — it **drafts and presents**; the human disposes.
-
----
-
-## Rules
-
-- **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.
-- **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 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 removed from `docs/memory/facts/`.
-- **Findings are questions, not verdicts.** When a candidate appears to contradict an existing card, phrase it as a question (is X now superseded by Y?) — never assert staleness or falsity.
-- **Never auto-runs.** Invoked by the user, by the Completion flow (kit `CLAUDE.md`), or by accepting the maintenance proposal. No cron, no daemon, no hook self-trigger — a workflow step the agent runs is not a self-trigger.
-- **qmd is strictly optional.** Guard every qmd call on `command -v qmd`; absent ⇒ silent skip. Reconciliation additionally needs the `{repo}-facts` collection to hold **cards** — not merely to be registered. "Unbuilt" here means **no cards** (`docs/memory/facts/*.md` empty), not "unregistered": the `maintenance` agent's baseline mode registers + embeds `{repo}-facts` over an empty scaffolded facts dir, so on a qmd-equipped, freshly-baselined repo the collection _appears in_ `qmd collection list` yet indexes zero cards. Binary present but collection cardless (first run) falls back to filename/grep too, same as qmd being absent.
-
-## Output locations
-
-- `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/`. See [`references/docs-mode.md`](references/docs-mode.md).