SKILL.md- the skill, written out in plain English

criteria:
  - name: output_file_exists
    kind: deterministic
    check: "A file named 'state/observations.md' exists after skill execution."
  - name: parseable_and_sourced
    kind: deterministic
    check: "Parsing 'state/observations.md' via 'parseObservations()' results in an array where every observation has 'observations.length >= 0' and 'claim.sources.length >= 1'."
  - name: eval_log_entry
    kind: deterministic
    check: "A new entry with 'skill: \"distill\"' exists in 'state/log/evals.ndjson' after skill execution, with a valid shape check result."
  - name: observation_relevance
    kind: judge
    check: "Observations recorded in 'state/observations.md' are relevant to human-scale memory and do not re-introduce friction/breakage clusters."

AGENTS.md- what the AI loads when this skill comes up

echo "[$(date -u +%FT%TZ)] distill: <what was missing>" >> state/log/loader-feedback.log

echo "[$(date -u +%FT%TZ)] distill: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * state/lib/distill.ts — scan state/memory/ journal,
 * write state/observations.md with claims that carry their source.
 *
 * The curated side of the OpenClaw-style memory split:
 *   memory/YYYY-MM-DD.md = raw daily (written by journal)
 *   observations.md      = distilled claims (written here)
 *
 * Every observation carries:
 *   - id              — stable slug so the UI can key on it
 *   - claim           — one-sentence statement
 *   - confidence      — low|medium|high (heuristic)
 *   - sources[]       — file paths (+ optional line) the claim derives from
 *   - generated_at    — ISO timestamp
 *
 * Usage:
 *   npx tsx state/lib/distill.ts              # scan last 14 days
 *   npx tsx state/lib/distill.ts --days 30    # widen window
 *
 * SCOPE (2026-04-23 cut): memory is human-scale only. We distill the journal.
 * Breakage rows + low-score eval rows are automation fuel for `pid-regen` +
 * other lints; they are NOT memory. Surfacing them here was double-shouting
 * work the PID loop already drains. If you want to know what broke, read
 * `state/log/breakage-report.ndjson` and the recent eval rows; if you want
 * to know what the operator thought, read the journal / this file.
 */
import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";

const HERE = dirname(fileURLToPath(import.meta.url));
const REPO = resolve(HERE, "..", "..");
const MEMORY_DIR = resolve(REPO, "state", "memory");
const OUT = resolve(REPO, "state", "observations.md");
const SNAPSHOT_DIR = resolve(REPO, "state", "observations");

export type ObservationStatus = "new" | "drifted" | "stable" | "resolved";

export interface Observation {
  id: string;
  claim: string;
  confidence: "low" | "medium" | "high";
  sources: string[];
  generated_at: string;
  kind: "journal-pattern";
  status?: ObservationStatus;
  prior_claim?: string;
}

interface JournalRow {
  date: string;
  ts: string;
  text: string;
  source: string;
}

const VERB_PATTERNS: Array<{ verb: string; re: RegExp }> = [
  { verb: "rejected", re: /\brejected\b/i },
  { verb: "approved", re: /\bapproved\b/i },
  { verb: "edited",   re: /\bedited\b/i },
  { verb: "decided",  re: /\bdecided|decision\b/i },
  { verb: "surprised",re: /\b(surprised|unexpected|surprise)\b/i },
  { verb: "corrected",re: /\bcorrected|correction\b/i },
];

function slugify(s: string): string {
  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
}

function daysBack(date: Date, n: number): Date {
  const d = new Date(date);
  d.setUTCDate(d.getUTCDate() - n);
  return d;
}

function isoDate(d: Date): string {
  return d.toISOString().slice(0, 10);
}

function readJournalWindow(windowDays: number): JournalRow[] {
  if (!existsSync(MEMORY_DIR)) return [];
  const today = new Date();
  const from = daysBack(today, windowDays - 1);
  const rows: JournalRow[] = [];
  const files = readdirSync(MEMORY_DIR)
    .filter(f => /^\d{4}-\d{2}-\d{2}\.md$/.test(f))
    .sort();
  for (const f of files) {
    const date = f.slice(0, 10);
    const d = new Date(date + "T00:00:00Z");
    if (d < from) continue;
    const body = readFileSync(resolve(MEMORY_DIR, f), "utf8");
    const lines = body.split(/\r?\n/);
    for (const line of lines) {
      const m = line.match(/^- `([^`]+)` (.+)$/);
      if (!m) continue;
      rows.push({ date, ts: m[1], text: m[2], source: `state/memory/${f}` });
    }
  }
  return rows;
}

function groupJournalByVerb(rows: JournalRow[]): Observation[] {
  const out: Observation[] = [];
  for (const { verb, re } of VERB_PATTERNS) {
    const hits = rows.filter(r => re.test(r.text));
    if (hits.length < 2) continue;
    const sources = [...new Set(hits.map(h => h.source))];
    out.push({
      id: `journal-verb-${verb}`,
      kind: "journal-pattern",
      claim: `${hits.length} journal entries in window use "${verb}" — recurring theme.`,
      confidence: hits.length >= 4 ? "high" : hits.length >= 3 ? "medium" : "low",
      sources,
      generated_at: new Date().toISOString(),
    });
  }
  return out;
}

function render(obs: Observation[], windowDays: number): string {
  const lines: string[] = [];
  lines.push(`# observations.md`);
  lines.push("");
  lines.push(`Generated: ${new Date().toISOString()}`);
  lines.push(`Window: last ${windowDays} days`);
  lines.push(`Count: ${obs.length}`);
  const byStatus = obs.reduce<Record<string, number>>((m, o) => { const s = o.status || "new"; m[s] = (m[s] || 0) + 1; return m; }, {});
  lines.push(`Status: new=${byStatus.new||0} drifted=${byStatus.drifted||0} stable=${byStatus.stable||0} resolved=${byStatus.resolved||0}`);
  lines.push("");
  lines.push(`> Curated claims with provenance. Written by \`state/lib/distill.ts\`.`);
  lines.push(`> Raw journal: \`state/memory/YYYY-MM-DD.md\`. Do not hand-edit this file — rerun distill.`);
  lines.push(`> Snapshots: \`state/observations/YYYY-MM-DD.md\` (one per run, source of the delta).`);
  lines.push("");
  if (obs.length === 0) {
    lines.push(`_No observations — journal is thin or the window is too tight. Use the \`journal\` skill to log rejections, decisions, surprises._`);
    lines.push("");
    return lines.join("\n");
  }
  for (const o of obs) {
    lines.push(`## ${o.id}`);
    lines.push("");
    lines.push(`- **claim:** ${o.claim}`);
    lines.push(`- **kind:** ${o.kind}`);
    lines.push(`- **confidence:** ${o.confidence}`);
    lines.push(`- **status:** ${o.status || "new"}`);
    if (o.prior_claim && o.status === "drifted") {
      lines.push(`- **prior_claim:** ${o.prior_claim}`);
    }
    lines.push(`- **generated_at:** ${o.generated_at}`);
    lines.push(`- **sources:**`);
    for (const s of o.sources) lines.push(`  - \`${s}\``);
    lines.push("");
  }
  return lines.join("\n");
}

function readPriorSnapshot(): Map<string, Observation> {
  const map = new Map<string, Observation>();
  if (!existsSync(SNAPSHOT_DIR)) return map;
  const files = readdirSync(SNAPSHOT_DIR)
    .filter(f => /^\d{4}-\d{2}-\d{2}\.md$/.test(f))
    .sort();
  if (files.length === 0) return map;
  const latest = resolve(SNAPSHOT_DIR, files[files.length - 1]);
  const body = readFileSync(latest, "utf8");
  const blocks = body.split(/^## /m).slice(1);
  for (const block of blocks) {
    const [header, ...rest] = block.split(/\r?\n/);
    const id = header.trim();
    const body = rest.join("\n");
    const claim = (body.match(/- \*\*claim:\*\* (.+)/)?.[1] ?? "").trim();
    const confidence = (body.match(/- \*\*confidence:\*\* (low|medium|high)/)?.[1] ?? "low") as "low"|"medium"|"high";
    const kind = (body.match(/- \*\*kind:\*\* ([\w-]+)/)?.[1] ?? "journal-pattern") as Observation["kind"];
    map.set(id, { id, claim, confidence, kind, sources: [], generated_at: "" });
  }
  return map;
}

function annotateStatus(current: Observation[], prior: Map<string, Observation>): Observation[] {
  const out: Observation[] = [];
  const currentIds = new Set(current.map(o => o.id));
  for (const o of current) {
    const p = prior.get(o.id);
    if (!p) {
      out.push({ ...o, status: "new" });
    } else if (p.claim !== o.claim) {
      out.push({ ...o, status: "drifted", prior_claim: p.claim });
    } else {
      out.push({ ...o, status: "stable" });
    }
  }
  // carry forward disappeared as "resolved" so the operator sees them fade
  for (const [id, p] of prior.entries()) {
    if (currentIds.has(id)) continue;
    out.push({
      id,
      claim: p.claim,
      confidence: p.confidence,
      kind: p.kind,
      sources: [],
      generated_at: new Date().toISOString(),
      status: "resolved",
      prior_claim: p.claim,
    });
  }
  return out;
}

function writeSnapshot(obs: Observation[], windowDays: number): string {
  if (!existsSync(SNAPSHOT_DIR)) mkdirSync(SNAPSHOT_DIR, { recursive: true });
  const date = new Date().toISOString().slice(0, 10);
  const path = resolve(SNAPSHOT_DIR, `${date}.md`);
  writeFileSync(path, render(obs, windowDays), "utf8");
  return path;
}

export function distill(windowDays = 14): { observations: Observation[]; path: string; snapshot: string } {
  const journalRows = readJournalWindow(windowDays);
  const fresh: Observation[] = [
    ...groupJournalByVerb(journalRows),
  ];
  const prior = readPriorSnapshot();
  const annotated = annotateStatus(fresh, prior);
  // Sort: new + drifted first (most interesting), then stable, then resolved. Within each, confidence descending.
  const statusRank: Record<string, number> = { new: 0, drifted: 1, stable: 2, resolved: 3 };
  const confRank: Record<string, number> = { high: 0, medium: 1, low: 2 };
  annotated.sort((a, b) => {
    const s = statusRank[a.status || "new"] - statusRank[b.status || "new"];
    if (s !== 0) return s;
    return confRank[a.confidence] - confRank[b.confidence];
  });
  if (!existsSync(dirname(OUT))) mkdirSync(dirname(OUT), { recursive: true });
  writeFileSync(OUT, render(annotated, windowDays), "utf8");
  const snapshot = writeSnapshot(annotated, windowDays);
  return { observations: annotated, path: OUT, snapshot };
}

/**
 * Parse observations.md back into structured Observation records.
 * The UI endpoint uses this so the fake-ASK risk is gone: what the UI shows
 * is what the file says.
 */
export function parseObservations(): Observation[] {
  if (!existsSync(OUT)) return [];
  const body = readFileSync(OUT, "utf8");
  const blocks = body.split(/^## /m).slice(1);
  const out: Observation[] = [];
  for (const block of blocks) {
    const [header, ...rest] = block.split(/\r?\n/);
    const id = header.trim();
    const body = rest.join("\n");
    const claim = (body.match(/- \*\*claim:\*\* (.+)/)?.[1] ?? "").trim();
    const kindRaw = (body.match(/- \*\*kind:\*\* (.+)/)?.[1] ?? "journal-pattern").trim();
    const confidence = (body.match(/- \*\*confidence:\*\* (low|medium|high)/)?.[1] ?? "low") as "low"|"medium"|"high";
    const generated_at = (body.match(/- \*\*generated_at:\*\* (.+)/)?.[1] ?? "").trim();
    const statusRaw = (body.match(/- \*\*status:\*\* (new|drifted|stable|resolved)/)?.[1] ?? "") as ObservationStatus | "";
    const prior_claim = (body.match(/- \*\*prior_claim:\*\* (.+)/)?.[1] ?? "").trim();
    const sources: string[] = [];
    const srcBlock = body.split(/- \*\*sources:\*\*/)[1] ?? "";
    for (const line of srcBlock.split(/\r?\n/)) {
      const m = line.match(/^\s*-\s*`([^`]+)`\s*$/);
      if (m) sources.push(m[1]);
    }
    const kind = "journal-pattern" as Observation["kind"];
    void kindRaw;
    const rec: Observation = { id, claim, kind, confidence, sources, generated_at };
    if (statusRaw) rec.status = statusRaw;
    if (prior_claim) rec.prior_claim = prior_claim;
    out.push(rec);
  }
  return out;
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const idx = process.argv.indexOf("--days");
  const windowDays = idx >= 0 ? Math.max(1, parseInt(process.argv[idx + 1], 10) || 14) : 14;
  const { observations, path } = distill(windowDays);
  process.stdout.write(`ok: ${path}\ncount: ${observations.length}\nwindow_days: ${windowDays}\n`);

  // eval row: shape check. Actor = the distill() run that wrote the file.
  // Auditor = re-read + parse, confirm every observation has ≥1 source.
  const { append, newRunId } = await import("./log.ts");
  const reread = parseObservations();
  const sourceless = reread.filter((o) => !o.sources || o.sources.length === 0);
  const run_id = newRunId();
  append("evals", {
    skill: "distill",
    run_id,
    mode: "shape",
    score: sourceless.length === 0 ? 1 : 0,
    count: reread.length,
    sourceless: sourceless.length,
    window_days: windowDays,
    actor_session_id: `distill-cli-${run_id}`,
    auditor_session_id: `distill-shape-${Date.now()}`,
    writer_id: "state/lib/distill.ts",
    notes: sourceless.length === 0 ? "shape-ok" : `${sourceless.length} observations missing sources`,
  });
}

scripts- helper scripts it can run

prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs