Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

27.8 KB
Raw Blame
/**
 * The lessons folder (daemons/LEARNING.md, "Store"): a git-backed folder OUTSIDE any repo, by default
 * `~/.harness/lessons/`, shared by every daemon you pair with (a new daemon keeps the lessons).
 *
 *   pending/<id>/SKILL.md | NOTE.md   proposed, waiting for your key (not committed)
 *   skills/<name>/SKILL.md           approved skills: the folder the Store runtime publishes (publish.ts)
 *   notes/<id>/NOTE.md               approved project notes (written into that project's AGENTS.md block)
 *   archive/<name>/SKILL.md          skills the curator put away, unused for 90 days (restore brings one back)
 *   lesson.json                      beside each: the record the daemon reads back
 *   journal.jsonl, state.json        what happened, and what not to propose again (not committed)
 *   usage.json, export.json          when each lesson was last used; what was exported where (not committed)
 *
 * SKILL.md is an Agent Skills file (agentskills.io): `name` (the folder's name), `description`, and a
 * `metadata.harness` map — learnedBy (the daemon), from (provenance), approved (the date), evidence.
 *
 * ONE commit per approval, per revert, per archive and per restore (and an empty one when a lesson goes stale), made with git in this folder and nowhere else, with no
 * global or system git config (no hooks, no signing, a fixed author: never the person's name or email).
 * A revert is `git revert` of the lesson's own commit. Without git the same moves happen with a plain
 * journal, and every answer says so.
 */
import { execFileSync } from 'node:child_process'
import { randomBytes } from 'node:crypto'
import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { redactDeep, refusal } from '../../shared/guard.js'
import { contentHash, type Lesson, type Provenance, type Signal, type SignalKind } from './types.js'

export type LessonStatus = 'pending' | 'approved' | 'reverted' | 'skipped' | 'archived'
export type LessonSource = 'template' | 'model' | 'borrowed'

export interface LessonRecord {
  id: string
  kind: 'skill' | 'note'
  /** A skill's name (its folder); a note's is `note-<id>`. */
  name: string
  description: string
  body: string
  lines?: string[]
  hash: string
  signal: { kind: SignalKind; key: string }
  /** The project, hashed. A note belongs to it; a skill made in it is listed only in its sessions. */
  project: string | null
  projectName: string | null
  learnedBy: string
  from: Provenance[]
  evidence: string[]
  source: LessonSource
  /** Where a borrowed lesson came from, in words: `borrowed from hermes`. */
  provenance?: string | null
  reason?: string
  created: number
  status: LessonStatus
  /** The day it was approved (YYYY-MM-DD). */
  approved?: string | null
  approvedBy?: string | null
  commit?: string | null
}

export type StoreResult<T = Record<string, unknown>> = ({ ok: true } & T) | { ok: false; error: string; detail?: string }

export interface LessonStoreOptions {
  root: string
  now: () => number
  newId?: () => string
  /** The git command; null means no git (a plain journal). Default `git`, if it runs. */
  git?: string | null
  env?: NodeJS.ProcessEnv
}

export const NO_GIT_NOTE = 'git is not installed: lessons are kept with a plain journal, not commits'
const SKIPPED_MAX = 2_000
const IGNORED = ['pending/', 'reverted/', 'state.json', 'journal.jsonl', 'usage.json', 'export.json', '*.tmp']

interface StoreState { v: 1; skipped: string[]; proposed: Record<string, number>; lastProposedAt: number | null; curatedAt: number | null }

export class LessonStore {
  readonly root: string
  private readonly now: () => number
  private readonly newId: () => string
  private readonly gitCommand: string | null
  private readonly env: NodeJS.ProcessEnv
  private gitWorks: boolean | null = null

  constructor(opts: LessonStoreOptions) {
    this.root = opts.root
    this.now = opts.now
    this.newId = opts.newId ?? (() => randomBytes(4).toString('hex'))
    this.gitCommand = opts.git === undefined ? 'git' : opts.git
    this.env = opts.env ?? process.env
  }

  get skillsDir(): string { return join(this.root, 'skills') }
  /** Whether the folder exists yet: nothing is ever made before the first lesson. */
  get exists(): boolean { return existsSync(this.root) }

  /** Git is here and runs. Asked once. */
  get git(): boolean {
    if (this.gitWorks === null) {
      if (!this.gitCommand) this.gitWorks = false
      else {
        try { execFileSync(this.gitCommand, ['--version'], { stdio: 'pipe', env: this.gitEnv() }); this.gitWorks = true } catch { this.gitWorks = false }
      }
    }
    return this.gitWorks
  }

  // ── reading ─────────────────────────────────────────────────────────────────────────────────────────

  pending(): LessonRecord[] {
    return this.readDir('pending').sort(byCreated)
  }

  approved(): LessonRecord[] {
    const commits = new Map<string, string | null>()
    for (const entry of this.journal()) if (entry.op === 'approved') commits.set(entry.id, entry.record?.commit ?? null)
    return [...this.readDir('skills'), ...this.readDir('notes')]
      .map((r) => ({ ...r, commit: commits.get(r.id) ?? null }))
      .sort(byCreated)
  }

  /** Skills the curator put away (archive/). `restore` brings one back. */
  archived(): LessonRecord[] {
    return this.readDir('archive').sort(byCreated)
  }

  /** Every lesson: pending, approved, archived, and the ones reverted or skipped (from the journal). */
  list(): LessonRecord[] {
    const live = [...this.pending(), ...this.approved(), ...this.archived()]
    const seen = new Set(live.map((r) => r.id))
    const gone = new Map<string, LessonRecord>()
    for (const entry of this.journal()) {
      if ((entry.op === 'reverted' || entry.op === 'skipped') && entry.record && !seen.has(entry.id)) gone.set(entry.id, { ...entry.record, status: entry.op })
      if ((entry.op === 'approved' || entry.op === 'added') && gone.has(entry.id)) gone.delete(entry.id)
    }
    return [...live, ...gone.values()]
  }

  get(id: string): LessonRecord | null {
    if (!/^[a-f0-9]{4,32}$/.test(id)) return null
    return this.list().find((r) => r.id === id) ?? null
  }

  /** The file an agent reads: SKILL.md for a skill, NOTE.md for a note. */
  text(record: LessonRecord): string {
    return record.kind === 'skill' ? renderSkill(record) : renderNote(record)
  }

  // ── adding ──────────────────────────────────────────────────────────────────────────────────────────

  /**
   * A distilled lesson, pending your key. Refused when you skipped or reverted it (or its signal) before,
   * or when the same lesson is already here.
   */
  add(input: { lesson: Lesson; signal: Signal; learnedBy: string; source: LessonSource; provenance?: string | null }): StoreResult<{ record: LessonRecord }> {
    const { lesson, signal } = input
    const hash = contentHash(lesson.kind === 'skill' ? ['skill', lesson.name, lesson.body] : ['note', signal.project, lesson.lines])
    const state = this.state()
    if (state.skipped.includes(hash) || state.skipped.includes(signal.key)) return { ok: false, error: 'SKIPPED' }
    const known = [...this.pending(), ...this.approved(), ...this.archived()]
    if (known.some((r) => r.hash === hash || (r.status === 'pending' && r.signal.key === signal.key))) return { ok: false, error: 'KNOWN' }
    const id = this.newId()
    const record: LessonRecord = {
      id, kind: lesson.kind,
      name: lesson.kind === 'skill' ? lesson.name : `note-${id}`,
      description: lesson.kind === 'skill' ? lesson.description : lesson.lines[0]!,
      body: lesson.kind === 'skill' ? lesson.body : lesson.lines.map((line) => `- ${line}`).join('\n'),
      ...(lesson.kind === 'note' ? { lines: lesson.lines } : {}),
      hash, signal: { kind: signal.kind, key: signal.key }, project: signal.project, projectName: signal.projectName,
      learnedBy: input.learnedBy, from: signal.from.slice(0, 8), evidence: signal.evidence.slice(0, 8), source: input.source,
      ...(input.provenance ? { provenance: input.provenance } : {}),
      ...(signal.reason ? { reason: signal.reason } : {}),
      created: this.now(), status: 'pending', approved: null,
    }
    // The guard once more, over the file an agent would read — front matter, provenance and evidence too.
    const why = refusal(this.text(record))
    if (why) return { ok: false, error: 'REFUSED', detail: why }
    this.ensure()
    this.writeLesson(join(this.root, 'pending', id), record)
    this.log({ op: 'added', id, kind: record.kind, name: record.name })
    return { ok: true, record }
  }

  // ── your key ────────────────────────────────────────────────────────────────────────────────────────

  /** Pending → skills/<name> or notes/<id>, one commit. `by`: a key, or the CLI. */
  approve(id: string, by: string): StoreResult<{ record: LessonRecord; commit: string | null; note?: string }> {
    const record = this.pending().find((r) => r.id === id)
    if (!record) return this.missing(id, 'pending')
    this.ensure()
    const date = new Date(this.now()).toISOString().slice(0, 10)
    let name = record.name
    if (record.kind === 'skill') {
      // Two lessons, one name: the second gets a number. The folder and `name` always agree (agentskills.io).
      for (let n = 2; existsSync(join(this.root, 'skills', name)); n++) name = `${record.name.slice(0, 60)}-${n}`
    }
    const approved: LessonRecord = { ...record, name, status: 'approved', approved: date, approvedBy: by }
    const rel = record.kind === 'skill' ? join('skills', name) : join('notes', id)
    this.writeLesson(join(this.root, rel), approved)
    rmSync(join(this.root, 'pending', id), { recursive: true, force: true })
    let commit: string | null = null
    if (this.git) {
      try {
        this.run(['add', '--', rel])
        this.run(['commit', '-q', '-m', `learn: ${name}\n\nLesson-Id: ${id}\nLearned-By: ${record.learnedBy}\nApproved-By: ${by}`, '--', rel])
        commit = this.run(['rev-parse', 'HEAD']).trim()
      } catch (err) {
        // Put it back as it was: nothing half-approved.
        try { this.run(['reset', '-q', '--', rel]) } catch { /* nothing staged */ }
        rmSync(join(this.root, rel), { recursive: true, force: true })
        this.writeLesson(join(this.root, 'pending', id), record)
        return { ok: false, error: 'COMMIT_FAILED', detail: gitError(err) }
      }
    }
    const final: LessonRecord = { ...approved, commit }
    this.log({ op: 'approved', id, kind: record.kind, name, commit, record: final })
    return { ok: true, record: final, commit, ...(this.git ? {} : { note: NO_GIT_NOTE }) }
  }

  /** Pending → gone, and never proposed again (its lesson and its signal are remembered as skipped). */
  skip(id: string): StoreResult<{ record: LessonRecord }> {
    const record = this.pending().find((r) => r.id === id)
    if (!record) return this.missing(id, 'pending')
    rmSync(join(this.root, 'pending', id), { recursive: true, force: true })
    this.remember(record)
    const skipped: LessonRecord = { ...record, status: 'skipped' }
    this.log({ op: 'skipped', id, kind: record.kind, name: record.name, record: skipped })
    return { ok: true, record: skipped }
  }

  /** Approved → `git revert` of its commit (or, without git, moved to reverted/). Never proposed again. */
  revert(id: string): StoreResult<{ record: LessonRecord; commit: string | null; note?: string }> {
    const record = this.approved().find((r) => r.id === id)
    if (!record) return this.missing(id, 'approved')
    const rel = record.kind === 'skill' ? join('skills', record.name) : join('notes', id)
    let commit: string | null = null
    const learned = this.git ? this.commitOf(id) : null
    if (learned) {
      try {
        this.run(['revert', '--no-commit', learned])
        this.run(['commit', '-q', '-m', `unlearn: ${record.name}\n\nThis reverts commit ${learned}.\nLesson-Id: ${id}`])
        commit = this.run(['rev-parse', 'HEAD']).trim()
      } catch (err) {
        try { this.run(['revert', '--abort']) } catch { try { this.run(['reset', '-q', '--merge']) } catch { /* nothing to abort */ } }
        return { ok: false, error: 'REVERT_FAILED', detail: gitError(err) }
      }
      // A revert of a commit that also held other paths (a hand edit) leaves them; this lesson's folder goes.
      rmSync(join(this.root, rel), { recursive: true, force: true })
    } else {
      mkdirSync(join(this.root, 'reverted'), { recursive: true, mode: 0o700 })
      renameSync(join(this.root, rel), join(this.root, 'reverted', `${id}-${record.name}`))
    }
    this.remember(record)
    const reverted: LessonRecord = { ...record, status: 'reverted' }
    this.log({ op: 'reverted', id, kind: record.kind, name: record.name, commit, record: reverted })
    return { ok: true, record: reverted, commit, ...(this.git ? {} : { note: NO_GIT_NOTE }) }
  }

  // ── the curator (curate.ts) ─────────────────────────────────────────────────────────────────────────

  /**
   * An approved skill → archive/, out of every session's index, one commit (`archive: <name>`). A note is
   * never archived: it lives in its project's AGENTS.md, where the person sees it.
   */
  archive(id: string, why = 'unused for 90 days'): StoreResult<{ record: LessonRecord; commit: string | null; note?: string }> {
    const record = this.approved().find((r) => r.id === id)
    if (!record) return this.missing(id, 'approved')
    if (record.kind !== 'skill') return { ok: false, error: 'NOT_A_SKILL', detail: 'only skills are archived; a note stays in its project\'s AGENTS.md' }
    const from = join('skills', record.name)
    const to = existsSync(join(this.root, 'archive', record.name)) ? join('archive', `${record.name}-${id}`) : join('archive', record.name)
    mkdirSync(join(this.root, 'archive'), { recursive: true, mode: 0o700 })
    renameSync(join(this.root, from), join(this.root, to))
    const moved = this.commitMove(from, to, `archive: ${record.name}\n\n${why}.\nLesson-Id: ${id}`)
    if (!moved.ok) { renameSync(join(this.root, to), join(this.root, from)); return moved }
    const archived: LessonRecord = { ...record, status: 'archived' }
    this.log({ op: 'archived', id, kind: record.kind, name: record.name, commit: moved.commit, why, record: archived })
    return { ok: true, record: archived, commit: moved.commit, ...(this.git ? {} : { note: NO_GIT_NOTE }) }
  }

  /** An archived skill back into skills/, one commit (`restore: <name>`). Refused when its name is taken. */
  restore(id: string): StoreResult<{ record: LessonRecord; commit: string | null; note?: string }> {
    const folder = this.folderOf('archive', id)
    const record = folder ? this.archived().find((r) => r.id === id) : null
    if (!folder || !record) return this.missing(id, 'archived')
    const to = join('skills', record.name)
    if (existsSync(join(this.root, to))) return { ok: false, error: 'NAME_TAKEN', detail: `another skill is called ${record.name}; revert it first` }
    const from = join('archive', folder)
    mkdirSync(join(this.root, 'skills'), { recursive: true, mode: 0o700 })
    renameSync(join(this.root, from), join(this.root, to))
    const moved = this.commitMove(from, to, `restore: ${record.name}\n\nLesson-Id: ${id}`)
    if (!moved.ok) { renameSync(join(this.root, to), join(this.root, from)); return moved }
    const restored: LessonRecord = { ...record, status: 'approved' }
    this.log({ op: 'restored', id, kind: record.kind, name: record.name, commit: moved.commit, record: restored })
    return { ok: true, record: restored, commit: moved.commit, ...(this.git ? {} : { note: NO_GIT_NOTE }) }
  }

  /**
   * A lesson unused for 30 days: an empty commit (`stale: <name>`) and a journal entry. Nothing in its folder
   * changes, so its `learn:` commit still reverts cleanly.
   */
  markStale(id: string, why = 'unused for 30 days'): StoreResult<{ record: LessonRecord; commit: string | null }> {
    const record = this.approved().find((r) => r.id === id)
    if (!record) return this.missing(id, 'approved')
    let commit: string | null = null
    if (this.git && existsSync(join(this.root, '.git'))) {
      try {
        this.run(['commit', '-q', '--allow-empty', '-m', `stale: ${record.name}\n\n${why}.\nLesson-Id: ${id}`])
        commit = this.run(['rev-parse', 'HEAD']).trim()
      } catch (err) { return { ok: false, error: 'COMMIT_FAILED', detail: gitError(err) } }
    }
    this.log({ op: 'stale', id, kind: record.kind, name: record.name, commit, why })
    return { ok: true, record, commit }
  }

  curatedAt(): number | null { return this.state().curatedAt }

  markCurated(at: number): void {
    const state = this.state()
    state.curatedAt = at
    this.saveState(state)
  }

  // ── proposals ───────────────────────────────────────────────────────────────────────────────────────

  lastProposedAt(): number | null { return this.state().lastProposedAt }
  proposedAt(id: string): number | null { return this.state().proposed[id] ?? null }

  markProposed(id: string, at: number): void {
    const state = this.state()
    state.proposed[id] = at
    state.lastProposedAt = at
    const pending = new Set(this.pending().map((r) => r.id))
    for (const key of Object.keys(state.proposed)) if (!pending.has(key)) delete state.proposed[key]
    this.saveState(state)
  }

  // ── internals ───────────────────────────────────────────────────────────────────────────────────────

  /** One commit for a folder that moved: the new path added, the old one gone from the index. */
  private commitMove(from: string, to: string, message: string): StoreResult<{ commit: string | null }> {
    if (!this.git || !existsSync(join(this.root, '.git'))) return { ok: true, commit: null }
    try {
      this.run(['add', '-A', '--', to])
      this.run(['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', from])
      this.run(['commit', '-q', '-m', message])
      return { ok: true, commit: this.run(['rev-parse', 'HEAD']).trim() }
    } catch (err) {
      try { this.run(['reset', '-q', 'HEAD', '--', from, to]) } catch { /* nothing staged */ }
      return { ok: false, error: 'COMMIT_FAILED', detail: gitError(err) }
    }
  }

  /** The folder a lesson is kept in under `dir`, by its lesson.json. */
  private folderOf(dir: 'archive', id: string): string | null {
    let names: string[]
    try { names = readdirSync(join(this.root, dir)) } catch { return null }
    for (const name of names) {
      try {
        const record = JSON.parse(readFileSync(join(this.root, dir, name, 'lesson.json'), 'utf8')) as { id?: unknown }
        if (record?.id === id) return name
      } catch { /* not a lesson */ }
    }
    return null
  }

  /** The commit that approved this lesson: its `Lesson-Id` trailer, found by git itself. */
  private commitOf(id: string): string | null {
    try {
      const lines = this.run(['log', '-F', `--grep=Lesson-Id: ${id}`, '--format=%H%x09%s']).split('\n')
      return lines.map((line) => line.split('\t')).find(([, subject]) => subject?.startsWith('learn: '))?.[0] ?? null
    } catch { return null }
  }

  private missing(id: string, want: LessonStatus): StoreResult<never> {
    const record = this.get(id)
    if (!record) return { ok: false, error: 'NOT_FOUND', detail: `no lesson ${id}` }
    return { ok: false, error: `NOT_${want.toUpperCase()}`, detail: `lesson ${id} is ${record.status}` }
  }

  private remember(record: LessonRecord): void {
    const state = this.state()
    state.skipped = [...state.skipped.filter((h) => h !== record.hash && h !== record.signal.key), record.hash, record.signal.key].slice(-SKIPPED_MAX)
    delete state.proposed[record.id]
    this.saveState(state)
  }

  /** The folder, its .gitignore and its repository, made on the first write — never before. */
  private ensure(): void {
    mkdirSync(this.root, { recursive: true, mode: 0o700 })
    const ignore = join(this.root, '.gitignore')
    if (!existsSync(ignore)) writeFileSync(ignore, `${IGNORED.join('\n')}\n`, { mode: 0o600 })
    else this.ignoreMore(ignore)
    if (!this.git || existsSync(join(this.root, '.git'))) return
    this.run(['init', '-q'])
    this.run(['add', '--', '.gitignore'])
    this.run(['commit', '-q', '-m', 'lessons: start\n\nLessons your daemons learned, one commit per approval and per revert.'])
  }

  /** A folder made by an older version: the files it did not know to ignore, added in one commit. */
  private ignoreMore(ignore: string): void {
    let text: string
    try { text = readFileSync(ignore, 'utf8') } catch { return }
    const lines = text.split('\n').map((line) => line.trim())
    const missing = IGNORED.filter((rule) => !lines.includes(rule))
    if (!missing.length) return
    writeFileSync(ignore, `${text}${text.endsWith('\n') || !text ? '' : '\n'}${missing.join('\n')}\n`, { mode: 0o600 })
    if (!this.git || !existsSync(join(this.root, '.git'))) return
    try {
      this.run(['add', '--', '.gitignore'])
      this.run(['commit', '-q', '-m', 'lessons: ignore usage and export records', '--', '.gitignore'])
    } catch {
      // Put it back, so the next write tries again: left staged, it would ride along in the next commit.
      try { this.run(['reset', '-q', '--', '.gitignore']) } catch { /* nothing staged */ }
      writeFileSync(ignore, text, { mode: 0o600 })
    }
  }

  private gitEnv(): NodeJS.ProcessEnv {
    const env: NodeJS.ProcessEnv = {}
    for (const [key, value] of Object.entries(this.env)) if (!key.startsWith('GIT_')) env[key] = value
    return {
      ...env,
      GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0',
      GIT_AUTHOR_NAME: 'Harness', GIT_AUTHOR_EMAIL: '[email protected]',
      GIT_COMMITTER_NAME: 'Harness', GIT_COMMITTER_EMAIL: '[email protected]',
    }
  }

  private run(args: string[]): string {
    return execFileSync(this.gitCommand!, ['-c', 'core.hooksPath=/dev/null', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', ...args],
      { cwd: this.root, env: this.gitEnv(), stdio: 'pipe', encoding: 'utf8' })
  }

  private readDir(folder: 'pending' | 'skills' | 'notes' | 'archive'): LessonRecord[] {
    const dir = join(this.root, folder)
    let names: string[]
    try { names = readdirSync(dir) } catch { return [] }
    const records: LessonRecord[] = []
    for (const name of names) {
      try {
        const record = JSON.parse(readFileSync(join(dir, name, 'lesson.json'), 'utf8')) as LessonRecord
        if (typeof record?.id !== 'string' || (record.kind !== 'skill' && record.kind !== 'note') || typeof record.name !== 'string') continue
        records.push({ ...record, status: folder === 'pending' ? 'pending' : folder === 'archive' ? 'archived' : 'approved' })
      } catch { /* not a lesson, or a hand-made folder */ }
    }
    return records
  }

  private writeLesson(dir: string, raw: LessonRecord): void {
    const record = redactDeep(raw)
    mkdirSync(dir, { recursive: true, mode: 0o700 })
    writeFileSync(join(dir, record.kind === 'skill' ? 'SKILL.md' : 'NOTE.md'), this.text(record), { mode: 0o600 })
    // The record as kept: where it is says its status, and git (or the journal) says its commit.
    const { status: _status, commit: _commit, ...kept } = record
    writeFileSync(join(dir, 'lesson.json'), `${JSON.stringify(kept, null, 2)}\n`, { mode: 0o600 })
  }

  private journal(): Array<{ at: number; op: string; id: string; record?: LessonRecord }> {
    let text: string
    try { text = readFileSync(join(this.root, 'journal.jsonl'), 'utf8') } catch { return [] }
    const entries: Array<{ at: number; op: string; id: string; record?: LessonRecord }> = []
    for (const line of text.split('\n')) {
      if (!line.trim()) continue
      try { entries.push(JSON.parse(line)) } catch { /* a torn line */ }
    }
    return entries
  }

  private log(entry: Record<string, unknown>): void {
    const file = join(this.root, 'journal.jsonl')
    const fresh = !existsSync(file)
    appendFileSync(file, `${JSON.stringify(redactDeep({ at: this.now(), ...entry, ...(this.git ? {} : { git: false }) }))}\n`, { mode: 0o600 })
    if (fresh) chmodSync(file, 0o600)
  }

  private state(): StoreState {
    try {
      const parsed = JSON.parse(readFileSync(join(this.root, 'state.json'), 'utf8')) as Partial<StoreState>
      return {
        v: 1,
        skipped: Array.isArray(parsed.skipped) ? parsed.skipped.filter((h): h is string => typeof h === 'string') : [],
        proposed: parsed.proposed && typeof parsed.proposed === 'object' ? parsed.proposed : {},
        lastProposedAt: typeof parsed.lastProposedAt === 'number' ? parsed.lastProposedAt : null,
        curatedAt: typeof parsed.curatedAt === 'number' ? parsed.curatedAt : null,
      }
    } catch { return { v: 1, skipped: [], proposed: {}, lastProposedAt: null, curatedAt: null } }
  }

  private saveState(state: StoreState): void {
    mkdirSync(this.root, { recursive: true, mode: 0o700 })
    const file = join(this.root, 'state.json')
    writeFileSync(`${file}.tmp`, JSON.stringify(state), { mode: 0o600 })
    renameSync(`${file}.tmp`, file)
  }
}

function byCreated(a: LessonRecord, b: LessonRecord): number {
  return a.created - b.created || a.id.localeCompare(b.id)
}

function gitError(err: unknown): string {
  const e = err as { stderr?: unknown; message?: unknown }
  const text = typeof e?.stderr === 'string' && e.stderr.trim() ? e.stderr : typeof e?.message === 'string' ? e.message : String(err)
  return text.trim().split('\n').slice(-2).join(' ').slice(0, 200)
}

// ── the files an agent reads ──────────────────────────────────────────────────────────────────────────

/** A YAML scalar that is always read back as the same string: JSON's quoting is valid YAML. */
const q = (value: unknown): string => JSON.stringify(value ?? null)

function frontmatter(record: LessonRecord): string {
  return [
    '---',
    `name: ${record.name}`,
    `description: ${q(record.description)}`,
    'metadata:',
    '  harness:',
    `    id: ${q(record.id)}`,
    `    kind: ${q(record.kind)}`,
    `    learnedBy: ${q(record.learnedBy)}`,
    `    signal: ${q(record.signal.kind)}`,
    `    project: ${q(record.project)}`,
    `    source: ${q(record.source)}`,
    ...(record.provenance ? [`    provenance: ${q(record.provenance)}`] : []),
    `    approved: ${q(record.approved ?? null)}`,
    '    from:',
    ...(record.from.length ? record.from.map((f) => `      - ${JSON.stringify({ engine: f.engine, machine: f.machine, session: f.session, turn: f.turn, project: f.project })}`) : ['      []']),
    '    evidence:',
    ...(record.evidence.length ? record.evidence.map((line) => `      - ${q(line)}`) : ['      []']),
    '---',
  ].join('\n').replace(/:\n {6}\[\]/g, ': []')
}

export function renderSkill(record: LessonRecord): string {
  return `${frontmatter(record)}\n${record.body.trim()}\n`
}

export function renderNote(record: LessonRecord): string {
  return `${frontmatter(record)}\n${(record.lines ?? [record.description]).map((line) => `- ${line}`).join('\n')}\n`
}