elanous 0.2.12 → 0.2.14

package/src/claims/claims-ledger.ts

@@ -0,0 +1,232 @@
+import { Database } from 'bun:sqlite';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+
+export type ClaimStatus = 'draft' | 'verified' | 'public' | 'stale' | 'retracted';
+
+export class ClaimsInputError extends Error {
+  override name = 'ClaimsInputError';
+}
+
+const claimsTable = (name: 'claims' | 'claims_new') => `CREATE TABLE ${name} (
+  id TEXT PRIMARY KEY, claim TEXT NOT NULL, audience TEXT NOT NULL,
+  status TEXT NOT NULL CHECK(status IN ('draft','verified','public','stale','retracted')),
+  owner TEXT NOT NULL, contrast TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL)`;
+export interface ClaimRow {
+  id: string;
+  claim: string;
+  audience: string;
+  status: ClaimStatus;
+  owner: string;
+  contrast: string | null;
+  created_at: string;
+  updated_at: string;
+}
+export interface ClaimEvidence { claim_id: string; value: string; command: string; source: string | null; measured_at: string; valid_until: string }
+export interface ClaimLink { claim_id: string; cell: string; version: string | null }
+export interface ClaimHistory { claim_id: string; at: string; by: string; event: 'add' | 'verify' | 'publish' | 'link' | 'stale' | 'retract'; detail: string }
+export interface ClaimDetail extends ClaimRow { evidence: ClaimEvidence[]; links: ClaimLink[]; history: ClaimHistory[] }
+export interface ClaimsLedgerOptions { stateDir?: string; now?: () => Date }
+
+function required(value: string, field: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new ClaimsInputError(`${field} is required`);
+  return value.trim();
+}
+function iso(value: string, field: string): string {
+  if (typeof value !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(value)) throw new ClaimsInputError(`invalid ${field}: ${value}`);
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime())) throw new ClaimsInputError(`invalid ${field}: ${value}`);
+  return date.toISOString();
+}
+
+export class ClaimsLedger {
+  readonly path: string;
+  private readonly now: () => Date;
+
+  constructor(options: ClaimsLedgerOptions = {}) {
+    this.path = join(options.stateDir ?? elanousStateRoot(), 'claims', 'claims.sqlite');
+    this.now = options.now ?? (() => new Date());
+  }
+
+  private open(): Database {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const db = new Database(this.path, { create: true, strict: true });
+    try {
+      chmodSync(this.path, 0o600);
+      db.exec('PRAGMA busy_timeout = 10000');
+      db.exec('PRAGMA journal_mode = WAL');
+      db.exec('PRAGMA foreign_keys = ON');
+      db.exec(`${claimsTable('claims').replace('CREATE TABLE', 'CREATE TABLE IF NOT EXISTS')};
+        CREATE TABLE IF NOT EXISTS evidence (
+          claim_id TEXT NOT NULL REFERENCES claims(id), value TEXT NOT NULL, command TEXT NOT NULL,
+          source TEXT, measured_at TEXT NOT NULL, valid_until TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS links (
+          claim_id TEXT NOT NULL REFERENCES claims(id), cell TEXT NOT NULL, version TEXT);
+        CREATE TABLE IF NOT EXISTS history (
+          claim_id TEXT NOT NULL REFERENCES claims(id), at TEXT NOT NULL, by TEXT NOT NULL,
+          event TEXT NOT NULL, detail TEXT NOT NULL);`);
+      const schema = (db.query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'claims'").get() as { sql: string }).sql;
+      if (!schema.includes("'retracted'")) {
+        db.exec('PRAGMA foreign_keys = OFF');
+        try {
+          db.exec('BEGIN IMMEDIATE');
+          try {
+            // Another opener may have migrated while this connection waited for the write lock.
+            const current = (db.query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'claims'").get() as { sql: string }).sql;
+            if (!current.includes("'retracted'")) {
+              db.exec(claimsTable('claims_new'));
+              db.exec('INSERT INTO claims_new SELECT * FROM claims');
+              db.exec('DROP TABLE claims');
+              db.exec('ALTER TABLE claims_new RENAME TO claims');
+              if ((db.query('PRAGMA foreign_key_check').all() as unknown[]).length) throw new Error('claims migration foreign key check failed');
+            }
+            db.exec('COMMIT');
+          } catch (error) { db.exec('ROLLBACK'); throw error; }
+        } finally { db.exec('PRAGMA foreign_keys = ON'); }
+      }
+      return db;
+    } catch (error) { db.close(); throw error; }
+  }
+
+  private using<T>(work: (db: Database) => T): T {
+    const db = this.open();
+    try { return work(db); } finally { db.close(); }
+  }
+
+  private transaction<T>(db: Database, work: () => T): T {
+    db.exec('BEGIN IMMEDIATE');
+    try { const result = work(); db.exec('COMMIT'); return result; }
+    catch (error) { db.exec('ROLLBACK'); throw error; }
+  }
+
+  private row(db: Database, id: string): ClaimRow {
+    const row = db.query('SELECT * FROM claims WHERE id = ?').get(id) as ClaimRow | null;
+    if (!row) throw new ClaimsInputError(`claim not found: ${id}`);
+    return row;
+  }
+
+  private latest(db: Database, id: string): ClaimEvidence | null {
+    return db.query('SELECT claim_id, value, command, source, measured_at, valid_until FROM evidence WHERE claim_id = ? ORDER BY measured_at DESC, rowid DESC LIMIT 1').get(id) as ClaimEvidence | null;
+  }
+
+  private record(db: Database, id: string, at: string, by: string, event: ClaimHistory['event'], detail: string): void {
+    db.query('INSERT INTO history (claim_id, at, by, event, detail) VALUES (?, ?, ?, ?, ?)').run(id, at, by, event, detail);
+  }
+
+  private refresh(db: Database, row: ClaimRow, at: string): ClaimRow {
+    if (row.status === 'stale' || row.status === 'draft' || row.status === 'retracted') return row;
+    const evidence = this.latest(db, row.id);
+    if (!evidence || evidence.valid_until > at) return row;
+    db.query("UPDATE claims SET status = 'stale', updated_at = ? WHERE id = ?").run(at, row.id);
+    this.record(db, row.id, at, 'system', 'stale', `evidence expired: ${evidence.valid_until}`);
+    debug.log('claims.ledger', 'stale', { id: row.id, status: 'stale' });
+    return { ...row, status: 'stale', updated_at: at };
+  }
+
+  add(input: { id: string; claim: string; audience: string; owner: string; contrast?: string }): ClaimRow {
+    const id = required(input.id, 'id');
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(id)) throw new ClaimsInputError('invalid claim id');
+    const claim = required(input.claim, 'claim');
+    const audience = required(input.audience, 'audience').split(',').map(part => required(part, 'audience')).join(',');
+    const owner = required(input.owner, 'owner');
+    const contrast = input.contrast === undefined ? null : required(input.contrast, 'contrast');
+    return this.using(db => this.transaction(db, () => {
+      if (db.query('SELECT 1 FROM claims WHERE id = ?').get(id)) throw new ClaimsInputError(`claim already exists: ${id}`);
+      const at = this.now().toISOString();
+      db.query('INSERT INTO claims (id, claim, audience, status, owner, contrast, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)')
+        .run(id, claim, audience, 'draft', owner, contrast, at, at);
+      this.record(db, id, at, owner, 'add', claim);
+      debug.log('claims.ledger', 'add', { id, status: 'draft' });
+      return this.row(db, id);
+    }));
+  }
+
+  verify(id: string, input: { value: string; command: string; source?: string; measuredAt: string; validUntil: string; by: string }): ClaimRow {
+    const value = required(input.value, 'value');
+    const command = required(input.command, 'command');
+    const by = required(input.by, 'by');
+    const measuredAt = iso(input.measuredAt, 'measuredAt');
+    const validUntil = iso(input.validUntil, 'validUntil');
+    if (validUntil <= measuredAt) throw new ClaimsInputError('validUntil must be after measuredAt');
+    const source = input.source === undefined ? null : required(input.source, 'source');
+    return this.using(db => this.transaction(db, () => {
+      if (this.row(db, id).status === 'retracted') throw new ClaimsInputError(`claim retracted: ${id}`);
+      const at = this.now().toISOString();
+      db.query('INSERT INTO evidence (claim_id, value, command, source, measured_at, valid_until) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(id, value, command, source, measuredAt, validUntil);
+      db.query("UPDATE claims SET status = 'verified', updated_at = ? WHERE id = ?").run(at, id);
+      this.record(db, id, at, by, 'verify', value);
+      debug.log('claims.ledger', 'verify', { id, status: 'verified' });
+      return this.row(db, id);
+    }));
+  }
+
+  publish(id: string, by: string): ClaimRow {
+    const actor = required(by, 'by');
+    return this.using(db => {
+      const published = this.transaction(db, () => {
+        const at = this.now().toISOString();
+        const row = this.refresh(db, this.row(db, id), at);
+        const evidence = this.latest(db, id);
+        if (row.status !== 'verified' || !evidence || evidence.valid_until <= at) return null;
+        db.query("UPDATE claims SET status = 'public', updated_at = ? WHERE id = ?").run(at, id);
+        this.record(db, id, at, actor, 'publish', evidence.value);
+        return this.row(db, id);
+      });
+      if (!published) throw new ClaimsInputError(`claim requires verified, valid evidence: ${id}`);
+      debug.log('claims.ledger', 'publish', { id, status: 'public' });
+      return published;
+    });
+  }
+
+  link(id: string, input: { cell: string; version?: string }): ClaimRow {
+    const cell = required(input.cell, 'cell');
+    const version = input.version === undefined ? null : required(input.version, 'version');
+    return this.using(db => this.transaction(db, () => {
+      const row = this.row(db, id);
+      const at = this.now().toISOString();
+      db.query('INSERT INTO links (claim_id, cell, version) VALUES (?, ?, ?)').run(id, cell, version);
+      db.query('UPDATE claims SET updated_at = ? WHERE id = ?').run(at, id);
+      this.record(db, id, at, 'system', 'link', version ? `${cell} (${version})` : cell);
+      debug.log('claims.ledger', 'link', { id, status: row.status });
+      return this.row(db, id);
+    }));
+  }
+
+  retract(id: string, input: { reason: string; by: string }): ClaimRow {
+    const reason = required(input.reason, 'reason');
+    const by = required(input.by, 'by');
+    return this.using(db => this.transaction(db, () => {
+      if (this.row(db, id).status === 'retracted') throw new ClaimsInputError(`claim already retracted: ${id}`);
+      const at = this.now().toISOString();
+      db.query("UPDATE claims SET status = 'retracted', updated_at = ? WHERE id = ?").run(at, id);
+      this.record(db, id, at, by, 'retract', reason);
+      debug.log('claims.ledger', 'retract', { id, status: 'retracted' });
+      return this.row(db, id);
+    }));
+  }
+
+  list(filters: { status?: ClaimStatus; audience?: string } = {}): ClaimRow[] {
+    if (filters.status && !['draft', 'verified', 'public', 'stale', 'retracted'].includes(filters.status)) throw new ClaimsInputError('invalid status');
+    return this.using(db => this.transaction(db, () => {
+      const at = this.now().toISOString();
+      return (db.query('SELECT * FROM claims ORDER BY created_at, id').all() as ClaimRow[])
+        .map(row => this.refresh(db, row, at))
+        .filter(row => (!filters.status || row.status === filters.status)
+          && (!filters.audience || row.audience.split(',').includes(filters.audience)));
+    }));
+  }
+
+  get(id: string): ClaimDetail {
+    return this.using(db => this.transaction(db, () => {
+      const row = this.refresh(db, this.row(db, id), this.now().toISOString());
+      return { ...row,
+        evidence: db.query('SELECT claim_id, value, command, source, measured_at, valid_until FROM evidence WHERE claim_id = ? ORDER BY measured_at, rowid').all(id) as ClaimEvidence[],
+        links: db.query('SELECT claim_id, cell, version FROM links WHERE claim_id = ? ORDER BY rowid').all(id) as ClaimLink[],
+        history: db.query('SELECT claim_id, at, by, event, detail FROM history WHERE claim_id = ? ORDER BY rowid').all(id) as ClaimHistory[],
+      };
+    }));
+  }
+}

package/src/claims/claims-render.ts

@@ -0,0 +1,157 @@
+import { Database } from 'bun:sqlite';
+import { appendFileSync, existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { checkBrand } from '../../scripts/brand/check.js';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import type { ClaimsLedger, ClaimEvidence } from './claims-ledger.js';
+
+export type ClaimSurface = 'deck' | 'site' | 'notice';
+export interface RenderedClaims {
+  markdown: string;
+  included: string[];
+  excluded: Array<{ id: string; reason: 'stale' | 'not-public' | 'retracted' | 'expired' | 'brand' | 'ambiguous-value' }>;
+}
+
+const headings: Record<ClaimSurface, string> = {
+  deck: '## 왜 엘라누스인가',
+  site: '## 엘라누스가 하는 일',
+  notice: '### 이번 판에서 확인된 것',
+};
+const scopes: Record<ClaimSurface, 'deck' | 'site' | 'release-notes'> = {
+  deck: 'deck', site: 'site', notice: 'release-notes',
+};
+
+function latest(evidence: ClaimEvidence[]): ClaimEvidence | undefined {
+  return evidence.reduce<ClaimEvidence | undefined>((best, item) =>
+    !best || item.measured_at >= best.measured_at ? item : best, undefined);
+}
+
+function commentValue(value: string): string {
+  return value.replace(/<!--|-->|\r|\n/g, ' ').replace(/\s+/g, ' ');
+}
+
+function firstSentence(claim: string): string {
+  const sentence = claim.split(/\r?\n|(?<=[.!?。！？])\s+/u)[0];
+  return sentence?.trim() ?? '';
+}
+
+/**
+ * The big number to show is the one measured value that carries a unit (420만+ 줄 · 37% · 12배 …).
+ * Dates, times and bare numbers are not values; the first unit-bearing number wins, none is ambiguous — exclude
+ * rather than publish the wrong one (review round 3: «측정일 2026-10-03, 결과 420만+ 줄» used to print 2026).
+ */
+export function representativeNumber(value: string): string | undefined {
+  const withoutDates = value.replace(/\b\d{4}-\d{2}-\d{2}(?:[T ][\d:.]+Z?)?\b/g, ' ').replace(/\b\d{1,2}:\d{2}(?::\d{2})?\b/g, ' ');
+  const matches = [...withoutDates.matchAll(/\d[\d,.]*\s*(?:만\+?\s*줄|만\+|만|억|%|배|명|건|줄|개월|lines?\b|PRs?\b|x\b)\+?/gi)].map(match => match[0].trim());
+  return matches[0];
+}
+
+export function renderClaims(ledger: ClaimsLedger, options: { surface: ClaimSurface; audience?: string }): RenderedClaims {
+  const { surface, audience } = options;
+  if (!(surface in headings)) throw new Error(`invalid claims surface: ${surface}`);
+  const excluded: RenderedClaims['excluded'] = [];
+  const candidates: Array<{ id: string; line: string }> = [];
+  for (const row of ledger.list()) {
+    if (audience && !row.audience.split(',').includes(audience)) continue;
+    if (row.status !== 'public') {
+      excluded.push({ id: row.id, reason: row.status === 'stale' ? 'stale' : row.status === 'retracted' ? 'retracted' : 'not-public' });
+      continue;
+    }
+    const detail = ledger.get(row.id);
+    if (detail.status !== 'public') {
+      excluded.push({ id: row.id, reason: 'stale' });
+      continue;
+    }
+    const evidence = latest(detail.evidence);
+    if (!evidence) {
+      excluded.push({ id: row.id, reason: 'expired' });
+      continue;
+    }
+    const claim = firstSentence(row.claim);
+    const number = representativeNumber(evidence.value);
+    if (!number) {
+      excluded.push({ id: row.id, reason: 'ambiguous-value' });
+      continue;
+    }
+    if (!claim) {
+      excluded.push({ id: row.id, reason: 'brand' });
+      continue;
+    }
+    candidates.push({ id: row.id, line: `- ${claim} — ${number} <!-- claim:${row.id} measured:${evidence.measured_at} cmd:${commentValue(evidence.command)}${evidence.source ? ` source:${commentValue(evidence.source)}` : ''} --> <!-- src:${commentValue(evidence.source ?? evidence.command)} -->` });
+  }
+
+  const temp = mkdtempSync(join(tmpdir(), 'claims-render-'));
+  const file = join(temp, 'claims.md');
+  try {
+    const probe = (items: typeof candidates): Set<string> => {
+      writeFileSync(file, [headings[surface], '', ...items.map(item => item.line)].join('\n').trimEnd() + '\n');
+      const result = checkBrand(scopes[surface], [file]);
+      if (result.missing) throw new Error('brand rules missing');
+      const bad = new Set<string>();
+      for (const finding of result.findings) {
+        const owner = items[finding.line - 3];
+        if (!owner) throw new Error('brand finding outside claim lines');
+        bad.add(owner.id);
+      }
+      return bad;
+    };
+    let remaining = candidates;
+    while (remaining.length) {
+      const bad = probe(remaining);
+      if (!bad.size) break;
+      const next = remaining.filter(item => {
+        if (!bad.has(item.id)) return true;
+        excluded.push({ id: item.id, reason: 'brand' });
+        return false;
+      });
+      remaining = next;
+    }
+    const included = remaining.map(item => item.id);
+    const markdown = [headings[surface], '', ...remaining.map(item => item.line)].join('\n').trimEnd() + '\n';
+    debug.log('claims.render', 'rendered', { surface, included, excluded });
+    return { markdown, included, excluded };
+  } finally { rmSync(temp, { recursive: true, force: true }); }
+}
+
+export function queueStaleRechecks(ledger: ClaimsLedger, options: { root?: string; now?: Date } = {}): number {
+  const stale = ledger.list({ status: 'stale' });
+  if (!stale.length) {
+    debug.log('claims.recheck', 'queued', { count: 0 });
+    return 0;
+  }
+  const now = options.now ?? new Date();
+  const parts = new Intl.DateTimeFormat('en-US', { timeZone: 'Asia/Seoul', year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(now);
+  const part = (type: string) => parts.find(p => p.type === type)!.value;
+  const day = `${part('year')}-${part('month')}-${part('day')}`;
+  const path = join(options.root ?? effectiveInstanceRoot(), 'seat-requests', 'requests.jsonl');
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = new Database(`${path}.loop-checker.lock.sqlite`);
+  try {
+    lock.exec('PRAGMA busy_timeout = 10000');
+    lock.exec('BEGIN EXCLUSIVE');
+    try {
+      const existing = new Set<string>();
+      if (existsSync(path)) for (const line of readFileSync(path, 'utf8').split('\n')) {
+        if (line.trim()) {
+          const row = JSON.parse(line) as { key?: string };
+          if (row.key) existing.add(row.key);
+        }
+      }
+      let count = 0;
+      for (const claim of stale) {
+        const key = `claims-recheck:${claim.id}:${day}`;
+        if (existing.has(key)) continue;
+        const command = latest(ledger.get(claim.id).evidence)?.command ?? '없음';
+        appendFileSync(path, JSON.stringify({ key, seat: claim.owner, text: `${claim.id} 근거 낡음 — 재측: ${command}`,
+          source: 'claims', status: 'queued', queuedAt: now.toISOString() }) + '\n');
+        existing.add(key);
+        count++;
+      }
+      lock.exec('COMMIT');
+      debug.log('claims.recheck', 'queued', { count });
+      return count;
+    } catch (error) { lock.exec('ROLLBACK'); throw error; }
+  } finally { lock.close(); }
+}

package/src/cli/claims-cli.ts

@@ -0,0 +1,94 @@
+import type { Command } from 'commander';
+import { ClaimsInputError, ClaimsLedger, type ClaimsLedgerOptions, type ClaimRow, type ClaimDetail } from '../claims/claims-ledger.js';
+import { renderClaims, queueStaleRechecks, type ClaimSurface } from '../claims/claims-render.js';
+
+function actor(explicit?: string): string {
+  const by = explicit?.trim() || process.env.AI_AGENT?.trim();
+  if (!by) throw new ClaimsInputError('--by or AI_AGENT is required');
+  return by;
+}
+
+function validUntil(raw: string, now: Date): string {
+  const days = /^\+(\d+)d$/.exec(raw);
+  const parsed = days ? new Date(now.getTime() + Number(days[1]) * 86400000) : new Date(raw);
+  if (!Number.isFinite(parsed.getTime()) || (!days && !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(raw))) throw new ClaimsInputError(`invalid --valid-until: ${raw}`);
+  return parsed.toISOString();
+}
+
+function handle<Args extends unknown[]>(command: string, action: (...args: Args) => void): (...args: Args) => void {
+  return (...args) => {
+    try { action(...args); }
+    catch (error) {
+      if (!(error instanceof ClaimsInputError)) throw error;
+      const message = error.message.replace(/\r/g, '\\r').replace(/\n/g, '\\n')
+        .replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+      process.stderr.write(`claims ${command}: ${message}\n`);
+      process.exitCode = 1;
+    }
+  };
+}
+
+function format(row: ClaimRow): string {
+  return `${row.id} · ${row.status} · ${row.claim} · ${row.audience} · ${row.owner}`;
+}
+function detail(row: ClaimDetail): string {
+  return [format(row), ...(row.contrast ? [`대비: ${row.contrast}`] : []),
+    '근거:', ...row.evidence.map(e => `  ${e.value} · ${e.command} · 측정 ${e.measured_at} · 유효 ${e.valid_until}${e.source ? ` · ${e.source}` : ''}`),
+    '연결:', ...row.links.map(l => `  ${l.cell}${l.version ? ` · ${l.version}` : ''}`),
+    '이력:', ...row.history.map(h => `  ${h.at} · ${h.event} · ${h.by} · ${h.detail}`)].join('\n');
+}
+
+export function registerClaimsCommands(program: Command, options: ClaimsLedgerOptions & { instanceRoot?: string } = {}, out: Pick<Console, 'log'> = console): void {
+  const root = program.command('claims').description('소구점 · 실측 근거 원장');
+  const ledger = () => new ClaimsLedger(options);
+  const emit = (value: unknown, json: boolean | undefined, text: string) => out.log(json ? JSON.stringify(value) : text);
+  root.command('add <id>').requiredOption('--claim <text>').requiredOption('--audience <list>').requiredOption('--owner <seat>')
+    .option('--contrast <text>').action(handle('add', (id: string, o: { claim: string; audience: string; owner: string; contrast?: string }) => {
+      const row = ledger().add({ id, claim: o.claim, audience: o.audience, owner: o.owner, ...(o.contrast ? { contrast: o.contrast } : {}) });
+      emit(row, false, format(row));
+    }));
+  root.command('verify <id>').requiredOption('--value <value>').requiredOption('--command <command>')
+    .requiredOption('--valid-until <ISO|+Nd>').option('--source <url>').option('--by <name>')
+    .action(handle('verify', (id: string, o: { value: string; command: string; validUntil: string; source?: string; by?: string }) => {
+      const by = actor(o.by);
+      const now = options.now?.() ?? new Date();
+      const row = ledger().verify(id, { value: o.value, command: o.command, measuredAt: now.toISOString(), validUntil: validUntil(o.validUntil, now), by, ...(o.source ? { source: o.source } : {}) });
+      emit(row, false, format(row));
+    }));
+  root.command('publish <id>').option('--by <name>').action(handle('publish', (id: string, o: { by?: string }) => {
+    const row = ledger().publish(id, actor(o.by));
+    emit(row, false, format(row));
+  }));
+  root.command('link <id>').requiredOption('--cell <cell>').option('--version <version>')
+    .action(handle('link', (id: string, o: { cell: string; version?: string }) => {
+      const row = ledger().link(id, { cell: o.cell, ...(o.version ? { version: o.version } : {}) });
+      emit(row, false, format(row));
+    }));
+  root.command('retract <id>').requiredOption('--reason <text>').option('--by <name>')
+    .action(handle('retract', (id: string, o: { reason: string; by?: string }) => {
+      const row = ledger().retract(id, { reason: o.reason, by: actor(o.by) });
+      emit(row, false, format(row));
+    }));
+  root.command('list').option('--status <status>').option('--audience <audience>').option('--json')
+    .action(handle('list', (o: { status?: ClaimRow['status']; audience?: string; json?: boolean }) => {
+      const rows = ledger().list({ status: o.status, audience: o.audience });
+      emit(rows, o.json, rows.length ? rows.map(format).join('\n') : '소구점 0건');
+    }));
+  root.command('show <id>').option('--json').action(handle('show', (id: string, o: { json?: boolean }) => {
+    const row = ledger().get(id);
+    emit(row, o.json, detail(row));
+  }));
+  root.command('render').requiredOption('--surface <surface>', 'deck | site | notice')
+    .option('--audience <audience>').option('--json')
+    .action(handle('render', (o: { surface: ClaimSurface; audience?: string; json?: boolean }) => {
+      const result = renderClaims(ledger(), { surface: o.surface, ...(o.audience ? { audience: o.audience } : {}) });
+      // Review follow-up: rendering is where stale claims surface — queue their re-measurement in the same act.
+      const rechecks = result.excluded.some(item => item.reason === 'stale')
+        ? queueStaleRechecks(ledger(), { root: options.instanceRoot, now: options.now?.() }) : 0;
+      emit({ ...result, rechecks }, o.json, rechecks ? `${result.markdown}\n<!-- 재측 요청 ${rechecks}건 -->` : result.markdown);
+    }));
+  root.command('recheck').option('--json').action(handle('recheck', (o: { json?: boolean }) => {
+    const count = queueStaleRechecks(ledger(), { root: options.instanceRoot, now: options.now?.() });
+    emit({ count }, o.json, `재측 요청 ${count}건`);
+  }));
+}