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

criteria:
  - name: journal_entry_format
    kind: deterministic
    check: "The appended line in state/memory/YYYY-MM-DD.md must start with a UTC timestamp followed by the journal entry."
  - name: journal_single_line_entry
    kind: deterministic
    check: "Each journal invocation must append exactly one line to state/memory/YYYY-MM-DD.md, as verified by line count difference."
  - name: journal_entry_relevance
    kind: judge
    check: "The journal entry should provide relevant narrative context not captured by mechanical logs, explaining a decision, surprise, or feedback."
  - name: journal_timestamp_is_utc
    kind: deterministic
    check: "The timestamp prepended to the journal entry in state/memory/YYYY-MM-DD.md must be in UTC, not local time."

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

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

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * state/lib/journal.ts — append a line to today's daily note, with
 * governance: audit log, rate limit, dedup, caller provenance.
 *
 * The through-line-of-intelligence layer ported from OpenClaw:
 *   memory/YYYY-MM-DD.md = raw daily journal (this lib)
 *   observations.md      = distilled claims (distill.ts)
 *   log/journal.ndjson   = audit trail (every call, visible in /memory UI)
 *
 * Write triggers are EXPLICITLY agent-initiated. No stop hook, no daemon,
 * no timer. The only two ways a row lands:
 *
 *   (1) A skill calls `journal(line, { caller })` in the current turn.
 *   (2) A human runs `npx tsx state/lib/journal.ts "line"` from a shell.
 *
 * If either feels out of control, the /memory screen shows every write
 * with its caller, and the rate limit refuses excess writes with a clear
 * error. SNAPPY_JOURNAL_MAX_PER_DAY overrides the 200/day default.
 *
 * CLI:
 *   npx tsx state/lib/journal.ts "User rejected the draft"
 */
import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync, 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 AUDIT_LOG = resolve(REPO, "state", "log", "journal.ndjson");

const DEFAULT_RATE_LIMIT_PER_DAY = 200;
const DEDUP_WINDOW_MS = 5 * 60 * 1000;

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

function nowUTC(): string {
  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
}

function ensureDay(date: string): string {
  if (!existsSync(MEMORY_DIR)) mkdirSync(MEMORY_DIR, { recursive: true });
  const path = resolve(MEMORY_DIR, `${date}.md`);
  if (!existsSync(path)) {
    writeFileSync(path, `# ${date}\n\n`, "utf8");
  }
  return path;
}

interface AuditRow {
  ts: string;
  caller: string;
  line: string;
  path: string;
  session_id?: string;
}

function readAudit(): AuditRow[] {
  if (!existsSync(AUDIT_LOG)) return [];
  const body = readFileSync(AUDIT_LOG, "utf8");
  const rows: AuditRow[] = [];
  for (const line of body.split(/\r?\n/)) {
    if (!line.trim()) continue;
    try { rows.push(JSON.parse(line) as AuditRow); } catch { /* skip */ }
  }
  return rows;
}

function countToday(audit: AuditRow[], date: string): number {
  return audit.filter(r => (r.ts || "").startsWith(date)).length;
}

function rateLimit(): number {
  const env = Number(process.env.SNAPPY_JOURNAL_MAX_PER_DAY);
  return Number.isFinite(env) && env > 0 ? env : DEFAULT_RATE_LIMIT_PER_DAY;
}

function recentlyWritten(audit: AuditRow[], line: string, now: number): boolean {
  for (let i = audit.length - 1; i >= 0; i--) {
    const r = audit[i];
    if (!r.ts) continue;
    const ts = Date.parse(r.ts);
    if (!Number.isFinite(ts)) continue;
    if (now - ts > DEDUP_WINDOW_MS) return false;
    if (r.line === line) return true;
  }
  return false;
}

export interface JournalOptions {
  date?: string;
  ts?: string;
  caller?: string;
  session_id?: string;
  force?: boolean;
}

export interface JournalResult {
  path: string;
  line: string;
  skipped?: "dedup" | "rate-limit";
  reason?: string;
}

export function journal(line: string, opts: JournalOptions = {}): JournalResult {
  const date = opts.date ?? todayUTC();
  const ts = opts.ts ?? nowUTC();
  const caller = (opts.caller ?? process.env.SNAPPY_JOURNAL_CALLER ?? "unknown").slice(0, 40);
  const session_id = opts.session_id ?? process.env.CLAUDE_SESSION_ID ?? process.env.SNAPPY_SESSION_ID;
  const trimmed = line.replace(/\s+/g, " ").trim();
  if (!trimmed) throw new Error("journal(): empty line");
  const path = ensureDay(date);
  const audit = readAudit();
  if (!opts.force) {
    const todayCount = countToday(audit, date);
    const limit = rateLimit();
    if (todayCount >= limit) {
      return { path, line: "", skipped: "rate-limit", reason: `rate limit ${limit}/day reached` };
    }
    if (recentlyWritten(audit, trimmed, Date.parse(ts))) {
      return { path, line: "", skipped: "dedup", reason: "same line written in last 5 min" };
    }
  }
  const row = `- \`${ts}\` ${trimmed}\n`;
  appendFileSync(path, row, "utf8");
  const auditRow: AuditRow = { ts, caller, line: trimmed, path, session_id };
  if (!existsSync(dirname(AUDIT_LOG))) mkdirSync(dirname(AUDIT_LOG), { recursive: true });
  appendFileSync(AUDIT_LOG, JSON.stringify(auditRow) + "\n", "utf8");
  return { path, line: row };
}

export function readDay(date: string): string {
  const path = resolve(MEMORY_DIR, `${date}.md`);
  return existsSync(path) ? readFileSync(path, "utf8") : "";
}

export function listDays(): string[] {
  if (!existsSync(MEMORY_DIR)) return [];
  return readdirSync(MEMORY_DIR)
    .filter((f: string) => /^\d{4}-\d{2}-\d{2}\.md$/.test(f))
    .map((f: string) => f.slice(0, 10))
    .sort();
}

/**
 * parseDay(date) -> structured entries for the UI.
 * Reads state/memory/YYYY-MM-DD.md and matches audit rows for caller/session.
 */
export interface DayEntry {
  ts: string;
  text: string;
  caller?: string;
  session_id?: string;
}
export function parseDay(date: string): DayEntry[] {
  const path = resolve(MEMORY_DIR, `${date}.md`);
  if (!existsSync(path)) return [];
  const body = readFileSync(path, "utf8");
  const audit = readAudit();
  const auditByTs = new Map<string, AuditRow>();
  for (const r of audit) if (r.ts) auditByTs.set(r.ts, r);
  const out: DayEntry[] = [];
  for (const line of body.split(/\r?\n/)) {
    const m = line.match(/^- `([^`]+)` (.+)$/);
    if (!m) continue;
    const ts = m[1];
    const text = m[2];
    const a = auditByTs.get(ts);
    out.push({ ts, text, caller: a?.caller, session_id: a?.session_id });
  }
  return out;
}

/**
 * governanceState() -> what the /memory UI shows in the Controls panel.
 * Tells the operator exactly what can write, and how much has been written.
 */
export interface GovernanceState {
  rate_limit_per_day: number;
  today_count: number;
  today_date: string;
  dedup_window_ms: number;
  allowed_callers: string[];
  audit_log_path: string;
  memory_dir: string;
  last_10_audit: AuditRow[];
}
export function governanceState(): GovernanceState {
  const audit = readAudit();
  const date = todayUTC();
  return {
    rate_limit_per_day: rateLimit(),
    today_count: countToday(audit, date),
    today_date: date,
    dedup_window_ms: DEDUP_WINDOW_MS,
    allowed_callers: [
      "cli              : npx tsx state/lib/journal.ts \"line\"",
      "skill            : any skill importing journal()",
      "http             : POST /journal on head-screen (dev UI only)",
    ],
    audit_log_path: AUDIT_LOG.replace(REPO + "/", ""),
    memory_dir: MEMORY_DIR.replace(REPO + "/", ""),
    last_10_audit: audit.slice(-10).reverse(),
  };
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const line = process.argv.slice(2).join(" ").trim();
  if (!line) {
    console.error("usage: journal <line>");
    process.exit(2);
  }
  const r = journal(line, { caller: "cli" });
  if (r.skipped) {
    process.stderr.write(`skipped (${r.skipped}): ${r.reason}\n`);
    process.exit(1);
  }
  process.stdout.write(`ok: ${r.path}\n${r.line}`);

  // eval row: shape check. Actor = the journal() append.
  // Auditor = re-parse today's day file, confirm the just-written line is present.
  const { append, newRunId } = await import("./log.ts");
  const today = todayUTC();
  const entries = parseDay(today);
  const found = entries.some((e) => e.text === line.replace(/\s+/g, " ").trim());
  const run_id = newRunId();
  append("evals", {
    skill: "journal",
    run_id,
    mode: "shape",
    score: found ? 1 : 0,
    entries_today: entries.length,
    actor_session_id: `journal-cli-${run_id}`,
    auditor_session_id: `journal-shape-${Date.now()}`,
    writer_id: "state/lib/journal.ts",
    notes: found ? "shape-ok: appended line parsed back" : "shape-fail: append missing on re-parse",
  });
}

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

no recent runs logged - the eval contract is declared but nothing has been graded yet