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

criteria:
  - name: shape_matches_parser
    kind: deterministic
    check: "summarizeRange() returns { progressList: { steps: [...] } } where each step has id, label, status in {done|running|pending|error}, optional note — exactly the shape parseProgressListArgs in web/src/tool-args.ts accepts."
  - name: dispatcher_intent_match
    kind: deterministic
    check: "Trigger phrases route to a ProgressList TOOL_CALL emission, not text fallback."
  - name: classification_correct
    kind: judge
    check: "Status per skill matches the rule: error if any score=0 in window, running if last_ts within 5min, done otherwise."

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

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

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * state/lib/agent-recap.ts -- read state/log/evals.ndjson and produce a
 * ProgressList payload for the snappy-chat generative UI.
 *
 * Closes the catalog→cockpit drift gap surfaced by the dogfood loop: the
 * intent "what did the agents do today" used to fall back to plain text
 * because no producer skill emitted the right TOOL_CALL shape. This lib
 * groups eval rows by skill, derives a status per skill (running if a row
 * landed in the last 5 minutes, error if any score = 0, done otherwise),
 * and shapes them into the ProgressList contract that
 * web/src/tool-args.ts:parseProgressListArgs accepts.
 *
 *   import { summarizeToday, summarizeRange } from "../lib/agent-recap.ts";
 *   const { progressList } = await summarizeToday();
 *
 * Pure read. Never writes. Scope-only by snappy-os convention.
 */

import { existsSync, readFileSync } from "fs";
import { dirname, join } from "path";
import { fileURLToPath } from "url";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, "..", "..");
const EVALS_PATH = join(ROOT, "state", "log", "evals.ndjson");

const RUNNING_WINDOW_MS = 5 * 60 * 1000;

export type ProgressListStatus = "done" | "running" | "pending" | "error";

export interface ProgressListStep {
  id: string;
  label: string;
  status: ProgressListStatus;
  note?: string;
}

export interface ProgressListPayload {
  steps: ProgressListStep[];
  currentStepId?: string;
}

export interface SummarizeRangeOpts {
  /** ISO timestamp lower bound (inclusive). Default = today 00:00 UTC. */
  since?: string;
  /** ISO timestamp upper bound (exclusive). Default = now. */
  until?: string;
  /** "now" override for tests — ms since epoch. */
  nowMs?: number;
  /** Override evals.ndjson path (mostly for tests). */
  evalsPath?: string;
}

interface EvalRow {
  ts?: string;
  skill?: string;
  score?: number;
  primary_issue?: string | null;
}

function parseRow(line: string): EvalRow | null {
  if (!line) return null;
  try {
    const o = JSON.parse(line);
    if (!o || typeof o !== "object") return null;
    return o as EvalRow;
  } catch {
    return null;
  }
}

function startOfTodayUtcMs(nowMs: number): number {
  const d = new Date(nowMs);
  return Date.UTC(
    d.getUTCFullYear(),
    d.getUTCMonth(),
    d.getUTCDate(),
    0, 0, 0, 0,
  );
}

function classifyStatus(args: {
  hasZero: boolean;
  hasRecent: boolean;
}): ProgressListStatus {
  if (args.hasZero) return "error";
  if (args.hasRecent) return "running";
  return "done";
}

/**
 * Read evals.ndjson and return a ProgressList payload covering one row per
 * skill that ran in [since, until). Steps are sorted alphabetically by
 * skill so the UI is stable across runs.
 */
export async function summarizeRange(
  opts: SummarizeRangeOpts = {},
): Promise<{ progressList: ProgressListPayload }> {
  const nowMs = opts.nowMs ?? Date.now();
  const sinceMs = opts.since
    ? Date.parse(opts.since)
    : startOfTodayUtcMs(nowMs);
  const untilMs = opts.until ? Date.parse(opts.until) : nowMs;
  const path = opts.evalsPath ?? EVALS_PATH;

  if (!existsSync(path)) {
    return { progressList: { steps: [] } };
  }

  const lines = readFileSync(path, "utf8").split(/\r?\n/);

  type Bucket = {
    runs: number;
    sumScore: number;
    countScored: number;
    minScore: number;
    maxTs: number;
  };
  const bySkill = new Map<string, Bucket>();

  for (const line of lines) {
    const row = parseRow(line);
    if (!row) continue;
    if (typeof row.skill !== "string" || row.skill.length === 0) continue;
    if (typeof row.ts !== "string") continue;
    const tsMs = Date.parse(row.ts);
    if (!Number.isFinite(tsMs)) continue;
    if (tsMs < sinceMs || tsMs >= untilMs) continue;

    const cur = bySkill.get(row.skill) ?? {
      runs: 0,
      sumScore: 0,
      countScored: 0,
      minScore: Number.POSITIVE_INFINITY,
      maxTs: 0,
    };
    cur.runs += 1;
    if (typeof row.score === "number" && Number.isFinite(row.score)) {
      cur.sumScore += row.score;
      cur.countScored += 1;
      if (row.score < cur.minScore) cur.minScore = row.score;
    }
    if (tsMs > cur.maxTs) cur.maxTs = tsMs;
    bySkill.set(row.skill, cur);
  }

  const slugs = [...bySkill.keys()].sort((a, b) => a.localeCompare(b));
  const steps: ProgressListStep[] = slugs.map((slug, i) => {
    const b = bySkill.get(slug)!;
    const hasRecent = nowMs - b.maxTs <= RUNNING_WINDOW_MS;
    const hasZero =
      b.countScored > 0 && b.minScore !== Number.POSITIVE_INFINITY && b.minScore <= 0;
    const status = classifyStatus({ hasZero, hasRecent });
    const meanScore =
      b.countScored > 0 ? b.sumScore / b.countScored : null;
    const noteParts: string[] = [`${b.runs} run${b.runs === 1 ? "" : "s"}`];
    if (meanScore !== null) noteParts.push(`mean ${meanScore.toFixed(2)}`);
    return {
      id: `recap-${i + 1}`,
      label: slug,
      status,
      note: noteParts.join(" · "),
    };
  });

  // Surface "currently active" — the most recent running step, if any.
  const runningStep = steps.find(s => s.status === "running");
  const payload: ProgressListPayload = { steps };
  if (runningStep) payload.currentStepId = runningStep.id;
  return { progressList: payload };
}

/** Convenience wrapper — today (UTC) up to now. */
export async function summarizeToday(): Promise<{ progressList: ProgressListPayload }> {
  return summarizeRange({});
}

/**
 * Same scan as summarizeRange, but emits a PhaseDisclosure payload via the
 * phase-trace builder. One disclosure row per skill; the collapsed summary
 * is the run-count + mean score, the expanded body lists individual run
 * timestamps + their primary issues. Used by the chat dispatcher to answer
 * "what is X doing right now" / "trace the agent run" intents.
 */
export async function summarizeRangeAsPhases(
  opts: SummarizeRangeOpts = {},
): Promise<{ phaseDisclosure: { phases: Array<{ label: string; summary: string; body?: string; status?: ProgressListStatus }>; title?: string } }> {
  const { startTrace } = await import("./phase-trace.ts");
  const nowMs = opts.nowMs ?? Date.now();
  const sinceMs = opts.since
    ? Date.parse(opts.since)
    : startOfTodayUtcMs(nowMs);
  const untilMs = opts.until ? Date.parse(opts.until) : nowMs;
  const path = opts.evalsPath ?? EVALS_PATH;

  const trace = startTrace("Agent activity today");

  if (!existsSync(path)) {
    return trace.emit();
  }

  const lines = readFileSync(path, "utf8").split(/\r?\n/);

  type Bucket = {
    runs: number;
    sumScore: number;
    countScored: number;
    minScore: number;
    maxTs: number;
    issues: Array<{ ts: string; score?: number; issue?: string | null }>;
  };
  const bySkill = new Map<string, Bucket>();

  for (const line of lines) {
    const row = parseRow(line);
    if (!row) continue;
    if (typeof row.skill !== "string" || row.skill.length === 0) continue;
    if (typeof row.ts !== "string") continue;
    const tsMs = Date.parse(row.ts);
    if (!Number.isFinite(tsMs)) continue;
    if (tsMs < sinceMs || tsMs >= untilMs) continue;

    const cur = bySkill.get(row.skill) ?? {
      runs: 0, sumScore: 0, countScored: 0,
      minScore: Number.POSITIVE_INFINITY, maxTs: 0, issues: []
    };
    cur.runs += 1;
    if (typeof row.score === "number" && Number.isFinite(row.score)) {
      cur.sumScore += row.score;
      cur.countScored += 1;
      if (row.score < cur.minScore) cur.minScore = row.score;
    }
    if (tsMs > cur.maxTs) cur.maxTs = tsMs;
    cur.issues.push({ ts: row.ts, score: row.score, issue: row.primary_issue ?? null });
    bySkill.set(row.skill, cur);
  }

  const slugs = [...bySkill.keys()].sort((a, b) => a.localeCompare(b));
  for (const slug of slugs) {
    const b = bySkill.get(slug)!;
    const hasRecent = nowMs - b.maxTs <= RUNNING_WINDOW_MS;
    const hasZero =
      b.countScored > 0 && b.minScore !== Number.POSITIVE_INFINITY && b.minScore <= 0;
    const status: ProgressListStatus = classifyStatus({ hasZero, hasRecent });
    const meanScore = b.countScored > 0 ? b.sumScore / b.countScored : null;
    const summary = meanScore !== null
      ? `${b.runs} run${b.runs === 1 ? "" : "s"} · mean ${meanScore.toFixed(2)}`
      : `${b.runs} run${b.runs === 1 ? "" : "s"}`;
    const lastN = b.issues.slice(-5).reverse();
    const bodyLines = lastN.map(r => {
      const score = typeof r.score === "number" ? r.score.toFixed(2) : "—";
      const issue = r.issue ? ` ${r.issue}` : "";
      return `${r.ts} · score ${score}${issue}`;
    });
    trace.phase(slug, { summary, status }).body(bodyLines.join("\n"));
  }

  return trace.emit();
}

/** Convenience: today's activity as a PhaseDisclosure payload. */
export async function summarizeTodayAsPhases() {
  return summarizeRangeAsPhases({});
}

// CLI smoke-test path: `npx tsx state/lib/agent-recap.ts`
const isMain = (() => {
  try {
    const argv1 = process.argv[1];
    if (!argv1) return false;
    return import.meta.url === new URL(`file://${argv1}`).href
      || import.meta.url.endsWith(argv1);
  } catch { return false; }
})();
if (isMain) {
  summarizeToday().then(out => {
    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
  }).catch(err => {
    console.error(`agent-recap: ${err}`);
    process.exit(1);
  });
}

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 6 runs