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

criteria:
  - name: calls_content_functions
    kind: judge
    check: "The skill calls at least one of the exported functions from 'state/lib/content.ts' based on the skill's input."
  - name: handles_required_inputs
    kind: deterministic
    check: "The skill execution does not error when 'getContentAtoms_input', 'listDrafts_input', and 'createDraft_input' are provided with valid string values."
  - name: log_entry_created
    kind: deterministic
    check: "A new row is appended to 'state/log/pending-eval.ndjson' for each skill execution."
  - name: matches_snapshot_output
    kind: judge
    check: "The output of the skill matches a pre-established snapshot for similar inputs, indicating consistent behavior."

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

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

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

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-content/api.ts -- Content production orchestrator for all snappy-* skills.
 *
 * Re-exports from knowledge + provides helpers for querying the content engine DB
 * (content_atoms on rb-content-engine.fly.dev).
 *
 * Usage:
 *   npx tsx api.ts atoms draft        # list draft content atoms
 *   npx tsx api.ts atoms approved     # list approved content atoms
 *   npx tsx api.ts atoms archived     # list archived content atoms
 *
 * Or import as module:
 *   import { listContacts, getContentAtoms } from "./content.ts";
 */

import { env } from "./env.ts";
import { readdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import {
  checkTone,
  requireCitations,
  checkFlow,
} from "./positioning.ts";
import { realpathSync } from "fs";
import {
  schedulePost,
  patchDraft,
  getDraft,
  deleteDraft,
  listScheduled,
} from "./linkedin.ts";

// --- Re-exports from child skills ---

export { listContacts } from "./knowledge.ts";

// --- Content Engine DB ---

const CONTENT_ENGINE = "https://rb-content-engine.fly.dev/sql";

/**
 * Query the content engine DB for content atoms by status.
 * Returns rows from content_atoms table.
 */
export async function getContentAtoms(status = "draft") {
  const res = await fetch(CONTENT_ENGINE, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: "SELECT id, type, draft, speaker, topic, tags, frequency, status, times_used, created_at FROM content_atoms WHERE status = $1 ORDER BY created_at DESC LIMIT 50",
      params: [status],
    }),
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`Content engine query failed (${res.status}): ${text}`);
  }
  return res.json();
}

// --- Content PID loop ---
// Mirrors the classroom loop: disk frontmatter is source of truth, pass-log
// is the append-only decision trace, Typefully is the publishing target.
// See data/README.md for the schema and invariants.

const THIS_DIR = dirname(fileURLToPath(import.meta.url));
const DRAFTS_DIR = join(THIS_DIR, "data", "drafts");
const PASS_LOG = join(THIS_DIR, "data", "pass-log.md");

export type DraftStatus = "drafted" | "scheduled" | "shipped" | "retired";

export type DraftFrontmatter = {
  slug: string;
  topic: string;
  status: DraftStatus;
  typefully_id: number;
  publish_at: string;
  iteration: number;
  last_tick_at: string;
  last_gate_check: "" | "pass" | "fail";
  last_gate_cite: "" | "pass" | "fail";
  last_gate_flow: "" | "pass" | "fail";
  flow_profile: string;
  media_id: string;
  cite_mode: "verbatim" | "practitioner";
  first_comment: string;
};

export type Draft = {
  path: string;
  fm: DraftFrontmatter;
  body: string;
};

function parseFm(raw: string): { fm: DraftFrontmatter; body: string } {
  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
  if (!match) throw new Error("missing frontmatter block");
  const fm: Record<string, unknown> = {};
  for (const line of match[1].split("\n")) {
    const kv = line.match(/^(\w+):\s*(.*)$/);
    if (!kv) continue;
    let v: unknown = kv[2].trim().replace(/^["']|["']$/g, "");
    if (v === "true") v = true;
    else if (v === "false") v = false;
    else if (typeof v === "string" && /^-?\d+$/.test(v)) v = Number(v);
    fm[kv[1]] = v;
  }
  return { fm: fm as DraftFrontmatter, body: match[2] };
}

function serializeFm(fm: DraftFrontmatter, body: string): string {
  const order: (keyof DraftFrontmatter)[] = [
    "slug", "topic", "status", "typefully_id", "publish_at",
    "iteration", "last_tick_at", "last_gate_check", "last_gate_cite",
    "last_gate_flow", "flow_profile", "media_id", "cite_mode", "first_comment",
  ];
  const lines = order.map((k) => {
    const v = fm[k];
    if (typeof v === "string") return `${k}: "${v}"`;
    return `${k}: ${v}`;
  });
  return `---\n${lines.join("\n")}\n---\n${body.startsWith("\n") ? body : "\n" + body}`;
}

export function listDrafts(): Draft[] {
  let files: string[];
  try {
    files = readdirSync(DRAFTS_DIR).filter((f) => f.endsWith(".md"));
  } catch {
    return [];
  }
  return files.map((f) => {
    const path = join(DRAFTS_DIR, f);
    const raw = readFileSync(path, "utf8");
    const { fm, body } = parseFm(raw);
    return { path, fm, body };
  });
}

function writeDraft(d: Draft): void {
  writeFileSync(d.path, serializeFm(d.fm, d.body));
}

export function createDraft(
  slug: string,
  topic: string,
  body: string,
  opts: { flowProfile?: string; citeMode?: "verbatim" | "practitioner" } = {},
): Draft {
  const fm: DraftFrontmatter = {
    slug,
    topic,
    status: "drafted",
    typefully_id: 0,
    publish_at: "",
    iteration: 0,
    last_tick_at: "",
    last_gate_check: "",
    last_gate_cite: "",
    last_gate_flow: "",
    flow_profile: opts.flowProfile || "balanced",
    media_id: "",
    cite_mode: opts.citeMode || "verbatim",
    first_comment: "",
  };
  const path = join(DRAFTS_DIR, `${slug}.md`);
  const d: Draft = { path, fm, body };
  writeDraft(d);
  return d;
}

function logPass(entry: string): void {
  appendFileSync(PASS_LOG, "\n" + entry + "\n");
}

/** Read-only status view over the drafts directory. */
export function status() {
  const drafts = listDrafts();
  const buckets: Record<DraftStatus, Draft[]> = {
    drafted: [],
    scheduled: [],
    shipped: [],
    retired: [],
  };
  for (const d of drafts) {
    const s = d.fm.status;
    if (buckets[s]) buckets[s].push(d);
  }
  return {
    total: drafts.length,
    drafted: buckets.drafted.map((d) => ({ slug: d.fm.slug, topic: d.fm.topic, iteration: d.fm.iteration })),
    scheduled: buckets.scheduled.map((d) => ({ slug: d.fm.slug, topic: d.fm.topic, publish_at: d.fm.publish_at, typefully_id: d.fm.typefully_id, iteration: d.fm.iteration })),
    shipped: buckets.shipped.map((d) => ({ slug: d.fm.slug, topic: d.fm.topic, publish_at: d.fm.publish_at })),
    retired: buckets.retired.map((d) => ({ slug: d.fm.slug, topic: d.fm.topic })),
  };
}

function runGates(body: string, profile: string, citeMode: string = "verbatim") {
  const tone = checkTone(body);
  const cite = citeMode === "practitioner"
    ? { pass: true, reasons: [] as string[] }
    : requireCitations(body);
  const flow = checkFlow(body, { profile });
  return {
    check: tone.pass ? "pass" : "fail",
    cite: cite.pass ? "pass" : "fail",
    flow: flow.pass ? "pass" : "fail",
    reasons: [
      ...tone.violations.map((r) => `check: ${r}`),
      ...cite.reasons.map((r) => `cite: ${r}`),
      ...flow.violations.map((r) => `flow: ${r}`),
    ],
  } as const;
}

/**
 * Single PID tick for one draft. Idempotent. Returns a decision record.
 *
 * Rules:
 * - drafted + all gates pass → schedule to Typefully at `when`, write back id+publish_at.
 * - scheduled + text changed → patch Typefully in place (bumps iteration).
 * - scheduled + gates fail on current body → log gap, do not publish.
 * - shipped/retired → no-op.
 * - If `dryRun`, runs gates and decides but makes no remote or disk writes.
 */
export async function tickDraft(
  slug: string,
  opts: { when?: string; dryRun?: boolean } = {},
) {
  const drafts = listDrafts();
  const d = drafts.find((x) => x.fm.slug === slug);
  if (!d) throw new Error(`draft not found: ${slug}`);

  const now = new Date().toISOString();
  const profile = d.fm.flow_profile || "balanced";
  const citeMode = d.fm.cite_mode || "verbatim";
  const gates = runGates(d.body, profile, citeMode);

  const decision: {
    slug: string;
    action: "schedule" | "patch" | "noop" | "gap";
    gates: typeof gates;
    typefully_id?: number;
    publish_at?: string;
    note: string;
  } = { slug, action: "noop", gates, note: "" };

  if (d.fm.status === "shipped" || d.fm.status === "retired") {
    decision.note = `status=${d.fm.status}; nothing to do`;
    return decision;
  }

  if (gates.check !== "pass" || gates.cite !== "pass" || gates.flow !== "pass") {
    decision.action = "gap";
    decision.note = `gates failed: ${gates.reasons.join(" | ")}`;
    if (!opts.dryRun) {
      d.fm.last_tick_at = now;
      d.fm.last_gate_check = gates.check;
      d.fm.last_gate_cite = gates.cite;
      d.fm.last_gate_flow = gates.flow;
      writeDraft(d);
      logPass(tickEntry(d, decision));
    }
    return decision;
  }

  if (d.fm.status === "drafted") {
    const when = opts.when
      || d.fm.publish_at
      || new Date(Date.now() + 3 * 24 * 3600 * 1000).toISOString().replace(/\.\d+Z$/, "Z");
    decision.action = "schedule";
    decision.publish_at = when;
    decision.note = `schedule new draft at ${when}`;
    if (!opts.dryRun) {
      const mediaIds = d.fm.media_id ? [d.fm.media_id] : undefined;
      const firstComment = d.fm.first_comment || undefined;
      const created = (await schedulePost(stripCiteMarkup(d.body), when, true, mediaIds, firstComment)) as { id: number };
      d.fm.status = "scheduled";
      d.fm.typefully_id = created.id;
      d.fm.publish_at = when;
      d.fm.iteration += 1;
      d.fm.last_tick_at = now;
      d.fm.last_gate_check = "pass";
      d.fm.last_gate_cite = "pass";
      d.fm.last_gate_flow = "pass";
      decision.typefully_id = created.id;
      writeDraft(d);
      logPass(tickEntry(d, decision));
    }
    return decision;
  }

  // status === "scheduled"
  const remote = (await getDraft(d.fm.typefully_id)) as any;
  const remoteText: string = remote?.platforms?.linkedin?.posts?.[0]?.text ?? "";
  const desiredText = stripCiteMarkup(d.body);
  if (remoteText === desiredText) {
    decision.note = "scheduled text matches local; no patch needed";
    if (!opts.dryRun) {
      d.fm.last_tick_at = now;
      writeDraft(d);
      logPass(tickEntry(d, decision));
    }
    return decision;
  }

  decision.action = "patch";
  decision.typefully_id = d.fm.typefully_id;
  decision.note = `patching remote draft ${d.fm.typefully_id} in place`;
  if (!opts.dryRun) {
    const patchFirstComment = d.fm.first_comment || undefined;
    await patchDraft(d.fm.typefully_id, { text: desiredText, firstComment: patchFirstComment });
    d.fm.iteration += 1;
    d.fm.last_tick_at = now;
    writeDraft(d);
    logPass(tickEntry(d, decision));
  }
  return decision;
}

function stripCiteMarkup(body: string): string {
  return body
    .replace(/\[source:[^\]]*\]/g, "")
    .replace(/<\/?connective>/gi, "")
    .replace(/[ \t]+\n/g, "\n")
    .replace(/[ \t]{2,}/g, " ")
    .trim();
}

function tickEntry(d: Draft, decision: { action: string; note: string; gates: { check: string; cite: string; flow: string } }): string {
  const now = new Date().toISOString();
  return [
    `## ${now.slice(0, 10)} content-loop`,
    `- **Tick kind**: ${decision.action}`,
    `- **Draft**: ${d.fm.slug} (typefully_id=${d.fm.typefully_id || "none"})`,
    `- **Gates**: check ${decision.gates.check}, cite ${decision.gates.cite}, flow/${d.fm.flow_profile} ${decision.gates.flow}`,
    `- **Decision**: ${decision.note}`,
  ].join("\n");
}

// --- Metrics (Step 7a) ---

const STAGED_ACTIONS_LOG = `${process.env.HOME}/.claude/logs/staged-actions.ndjson`;

type StagedRun = { ts: string; name: string; action: string };

function readStagedRunsContent(): StagedRun[] {
  try {
    const lines = readFileSync(STAGED_ACTIONS_LOG, "utf-8").split("\n");
    const out: StagedRun[] = [];
    for (const line of lines) {
      if (!line.trim()) continue;
      try {
        const j = JSON.parse(line);
        if (typeof j?.name === "string" && typeof j?.ts === "string") {
          out.push({ ts: j.ts, name: j.name, action: j.action || "" });
        }
      } catch { /* skip malformed */ }
    }
    return out;
  } catch { return []; }
}

function withinLastDays(tsIso: string, days: number): boolean {
  const t = new Date(tsIso).getTime();
  if (isNaN(t)) return false;
  return t >= Date.now() - days * 86400_000;
}

export function computeContentMetric(name: string): number | null {
  const runs = readStagedRunsContent().filter((r) => withinLastDays(r.ts, 7));
  switch (name) {
    case "polish-per-week":
    case "content_polish_runs_per_week":
      return runs.filter((r) => r.name === "content-polish").length;
    case "polish-apply-rate":
    case "content_polish_apply_rate": {
      const polish = runs.filter((r) => r.name === "content-polish");
      if (!polish.length) return null;
      const delivered = polish.filter((r) => r.action === "delivered").length;
      return delivered / polish.length;
    }
    case "atoms-per-week":
    case "content_mine_atoms_per_week":
      return runs.filter((r) => r.name === "content-mine").length;
    default:
      return null;
  }
}

// --- CLI ---

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "metrics": {
        const [name, ...rest] = args;
        if (!name) {
          console.error("Usage: api.ts metrics <name> [--json]");
          console.error("Names: polish-per-week, polish-apply-rate, atoms-per-week");
          process.exit(1);
        }
        const value = computeContentMetric(name);
        if (rest.includes("--json")) console.log(JSON.stringify({ value }));
        else console.log(value == null ? "null" : String(value));
        break;
      }
      case "atoms": {
        const status = args[0] || "draft";
        const data = await getContentAtoms(status);
        if (Array.isArray(data) && data.length) {
          for (const atom of data) {
            console.log(`[${atom.id}] ${atom.type || "untyped"} -- ${atom.topic || "(no topic)"} (${atom.status})`);
            if (atom.draft) console.log(`  ${atom.draft.slice(0, 120)}...`);
          }
        } else {
          console.log(JSON.stringify(data, null, 2));
        }
        break;
      }
      case "status": {
        const s = status();
        console.log(`[loop-status] total=${s.total}`);
        console.log(`  drafted:   ${s.drafted.length}`);
        for (const d of s.drafted) console.log(`    - ${d.slug} (iter=${d.iteration}) — ${d.topic}`);
        console.log(`  scheduled: ${s.scheduled.length}`);
        for (const d of s.scheduled) console.log(`    - ${d.slug} (iter=${d.iteration}) id=${d.typefully_id} at=${d.publish_at} — ${d.topic}`);
        console.log(`  shipped:   ${s.shipped.length}`);
        for (const d of s.shipped) console.log(`    - ${d.slug} at=${d.publish_at} — ${d.topic}`);
        console.log(`  retired:   ${s.retired.length}`);
        for (const d of s.retired) console.log(`    - ${d.slug} — ${d.topic}`);
        break;
      }
      case "tick": {
        let slug: string | undefined;
        let when: string | undefined;
        let dryRun = false;
        for (let i = 0; i < args.length; i++) {
          if (args[i] === "--when") { when = args[++i]; }
          else if (args[i] === "--dry-run") { dryRun = true; }
          else if (!slug) { slug = args[i]; }
        }
        if (!slug) { console.error("Usage: api.ts tick <slug> [--when ISO8601Z] [--dry-run]"); process.exit(1); }
        const decision = await tickDraft(slug, { when, dryRun });
        console.log(JSON.stringify(decision, null, 2));
        break;
      }
      case "tick-all": {
        const dryRun = args.includes("--dry-run");
        const results = [];
        for (const d of listDrafts()) {
          if (d.fm.status === "shipped" || d.fm.status === "retired") continue;
          results.push(await tickDraft(d.fm.slug, { dryRun }));
        }
        console.log(JSON.stringify(results, null, 2));
        break;
      }
      case "draft-new": {
        let slug: string | undefined;
        let topic = "";
        let bodyFile: string | undefined;
        let profile = "balanced";
        let citeMode: "verbatim" | "practitioner" | undefined;
        for (let i = 0; i < args.length; i++) {
          if (args[i] === "--topic") { topic = args[++i]; }
          else if (args[i] === "--body-file") { bodyFile = args[++i]; }
          else if (args[i] === "--profile") { profile = args[++i]; }
          else if (args[i] === "--cite-mode") { citeMode = args[++i] as "verbatim" | "practitioner"; }
          else if (!slug) { slug = args[i]; }
        }
        if (!slug || !bodyFile) { console.error("Usage: api.ts draft-new <slug> --body-file <path> --topic <topic> [--profile balanced] [--cite-mode verbatim|practitioner]"); process.exit(1); }
        const body = readFileSync(bodyFile, "utf8");
        const d = createDraft(slug, topic, body, { flowProfile: profile, citeMode });
        console.log(JSON.stringify({ slug: d.fm.slug, path: d.path, status: d.fm.status }));
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts <atoms|status|tick|tick-all|draft-new> [...args]");
    }
  })();
}

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