elanous 0.2.6 → 0.2.8

package/scripts/release-loop/ops-upgrade-node.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env bun
+import { homedir } from 'node:os';
+import { errorResult, finishNode, lastResult, nodeOutput, readGraphContext, runCommand, type CommandResult, type CommandRunner } from './node-verdict.js';
+
+interface HostResult { host: string; ok: boolean; before: string; after: string; error?: string; skipped?: string; hooks?: string }
+
+function firstLine(text: string): string { return text.trim().split(/\r?\n/)[0]?.trim() ?? ''; }
+
+function reason(result: CommandResult): string {
+  const data = lastResult(result);
+  const message = [data?.error, data?.reason, data?.message, result.stderr, result.stdout].find((part) => typeof part === 'string' && part.trim());
+  const line = firstLine(String(message ?? `명령 실패 (rc=${result.status})`));
+  return /\b404\b/.test(line) ? `공급원에 판 없음 (404): ${line}` : line;
+}
+
+function quote(value: string): string { return `'${value.replaceAll("'", "'\\''")}'`; }
+
+export function runOpsUpgrade(run: CommandRunner = runCommand) {
+  const context = readGraphContext();
+  const hosts = context.input.opsHosts;
+  if (hosts === undefined || (Array.isArray(hosts) && hosts.length === 0)) {
+    return { outcome: 'ok' as const, verdict: 'pass' as const, summary: '운영 대상 없음 — 건너뜀', hosts: [] as HostResult[] };
+  }
+  if (!Array.isArray(hosts) || !hosts.every((host) => typeof host === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(host))) throw new Error('input.opsHosts must be an array of host names');
+  if (context.outputs.verify?.outcome !== 'ok') throw new Error('verify must pass before ops upgrade');
+  const version = context.input.version;
+  if (nodeOutput(context, 'publish', 'tag') !== `v${version}`) throw new Error('published tag/version mismatch');
+  const internalDist = context.input.internalDist;
+  if (internalDist !== undefined && (typeof internalDist !== 'string' || !internalDist.trim())) throw new Error('input.internalDist must be a path string');
+  const feedPath = typeof internalDist === 'string' && internalDist.startsWith('~/') ? `${homedir()}/${internalDist.slice(2)}` : internalDist;
+  let feedError = '';
+  if (typeof feedPath === 'string') {
+    try {
+      const feed = run('bun', ['scripts/publish-internal-dist.ts', '--checkout', process.cwd(), '--out', feedPath]);
+      const data = lastResult(feed);
+      if (feed.status !== 0 || data?.ok !== true || data.version !== version) feedError = `내부 피드 발행 실패: ${feed.status === 0 && data?.ok === true ? `판 불일치 (${String(data.version)})` : reason(feed)}`;
+    } catch (error) { feedError = `내부 피드 발행 실패: ${firstLine(String(error))}`; }
+  }
+  const results: HostResult[] = [];
+  for (const host of hosts as string[]) {
+    if (host !== 'local' && feedError) {
+      results.push({ host, ok: false, before: '', after: '', skipped: '내부 피드 발행 실패', error: feedError });
+      continue;
+    }
+    const command = (args: string[]): CommandResult => host === 'local'
+      ? run('elanous', args)
+      // The installer's own bin dir comes first — a --no-modify-path install (the bot VM) has elanous only there.
+      : run('ssh', [host, `PATH="$HOME/.local/share/elanous/bin:$HOME/.local/bin:$HOME/.bun/bin:$PATH"; export PATH; elanous ${args.map(quote).join(' ')}`]);
+    let before = '';
+    let after = '';
+    try {
+      const previous = command(['--version']);
+      if (previous.status === 0) before = firstLine(previous.stdout);
+      const updated = command(['update', '--version', version, '--json', ...(context.input.opsRestart === true ? ['--restart'] : [])]);
+      const updateResult = lastResult(updated);
+      if (updated.status !== 0 || updateResult?.exitCode !== 0 || updateResult.installedVersion !== version) {
+        const error = updated.status === 0 && updateResult?.exitCode === 0
+          ? `설치판 불일치 (기대 ${version}, 실제 ${String(updateResult.installedVersion)})` : reason(updated);
+        results.push({ host, ok: false, before, after, error });
+        continue;
+      }
+      const current = command(['--version']);
+      if (current.status !== 0) {
+        results.push({ host, ok: false, before, after, error: reason(current) });
+        continue;
+      }
+      after = firstLine(current.stdout);
+      if (after.split(/\s+/)[0] !== version) {
+        results.push({ host, ok: false, before, after, error: `올렸는데 판이 그대로 (기대 ${version}, 실제 ${after || '없음'})` });
+        continue;
+      }
+      // The webhook receiver (`elanous hooks serve`, a user systemd unit on the bot VM) keeps the old code until it
+      // restarts. try-restart touches it only where it runs; elsewhere the unit is absent and nothing happens.
+      let hooks: string | undefined;
+      if (host !== 'local' && context.input.opsRestart === true) {
+        const restarted = run('ssh', [host, 'systemctl --user try-restart elanous-hooks.service 2>/dev/null && systemctl --user is-active elanous-hooks.service 2>/dev/null || echo absent']);
+        hooks = firstLine(restarted.stdout) || 'absent';
+      }
+      results.push({ host, ok: true, before, after, ...(hooks ? { hooks } : {}) });
+    } catch (error) {
+      results.push({ host, ok: false, before, after, error: firstLine(String(error)) });
+    }
+  }
+  const failures = results.filter((result) => !result.ok);
+  return { outcome: failures.length || feedError ? 'fail' as const : 'ok' as const,
+    verdict: failures.length || feedError ? 'fail' as const : 'pass' as const,
+    summary: failures.length ? `운영 판올림 실패: ${failures.map(({ host, error }) => `${host}: ${error}`).join('; ')}${feedError && !failures.some((item) => item.skipped) ? `; ${feedError}` : ''}`
+      : feedError || `운영 판올림 ${version} · ${results.length}대 확인`, hosts: results };
+}
+
+if (import.meta.main) {
+  let version = '';
+  try { version = readGraphContext().input.version; process.exitCode = finishNode('ops-upgrade', version, runOpsUpgrade()); }
+  catch (error) { process.exitCode = finishNode('ops-upgrade', version, errorResult(error)); }
+}

package/scripts/release-loop/publish-node.ts

@@ -17,6 +17,22 @@ export function publicNotes(markdown: string, pages: { pages: Array<{ id: string
   });
 }
 
+/** Polls each release asset until it answers 200 (following redirects). Returns the names still missing. */
+export function waitForAssets(run: CommandRunner, repo: string, tag: string, names: readonly string[], waitSeconds: unknown = 600,
+  sleep: (ms: number) => void = (ms) => Bun.sleepSync(ms)): string[] {
+  if (!repo || names.length === 0) return [];
+  const limit = typeof waitSeconds === 'number' && Number.isFinite(waitSeconds) && waitSeconds >= 0 ? Math.min(waitSeconds, 1800) : 600;
+  let pending = [...names];
+  for (let waited = 0; ; waited += 15) {
+    pending = pending.filter((name) => {
+      const probe = run('curl', ['-sIL', '-o', '/dev/null', '-w', '%{http_code}', '-m', '20', `https://github.com/${repo}/releases/download/${tag}/${name}`]);
+      return probe.stdout.trim() !== '200';
+    });
+    if (pending.length === 0 || waited >= limit) return pending;
+    sleep(15_000);
+  }
+}
+
 export function runPublish(run: CommandRunner = runCommand) {
   const context = readGraphContext();
   const version = context.input.version;
@@ -50,7 +66,13 @@ export function runPublish(run: CommandRunner = runCommand) {
     const result = lastResult(published);
     if (published.status === 1) return { outcome: 'fail' as const, verdict: 'fail' as const, summary: `release publish failed: ${result?.error ?? published.stderr.trim()}` };
     if (published.status !== 0 || result?.ok !== true || result.published !== true || result.tag !== `v${version}`) throw new Error(`release publish incomplete or tag mismatch: ${result?.error ?? published.stderr.trim()}`);
-    return { outcome: 'ok' as const, verdict: 'pass' as const, summary: `published v${version}`, tag: `v${version}` };
+    // REL3 — «published» only once every asset downloads. 10-01: the run went on to verify before GitHub served the
+    // assets (release created 13:16Z, assets 13:20Z, run ended 13:15Z) and verify failed on a missing installer.
+    const repo = typeof result.publicRepo === 'string' ? result.publicRepo : '';
+    const names = Array.isArray(result.assets) ? (result.assets as unknown[]).filter((a): a is string => typeof a === 'string').map((a) => a.split('/').at(-1)!) : [];
+    const pending = waitForAssets(run, repo, `v${version}`, names, context.input.assetWaitSeconds);
+    if (pending.length) return { outcome: 'fail' as const, verdict: 'fail' as const, summary: `published v${version} but assets not downloadable yet: ${pending.join(', ')}`, tag: `v${version}` };
+    return { outcome: 'ok' as const, verdict: 'pass' as const, summary: `published v${version} · ${names.length} assets downloadable`, tag: `v${version}` };
   } finally { rmSync(dir, { recursive: true, force: true }); }
 }
 

package/scripts/release-loop/release-readiness.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { releaseLedgerRoot } from '../../src/instance/resolve.js';
+import { checklistGate, type ChecklistGate } from '../../src/release-loop/checklist.js';
+
+export type ReleaseReadiness =
+  | { ready: false; reason: 'already-published'; details: string }
+  | { ready: false; reason: 'already-running'; details: string }
+  | { ready: false; reason: 'checklist-blocked'; details: ChecklistGate }
+  | { ready: true; reason: 'ready'; details: ChecklistGate };
+
+export interface ReleaseReadinessDeps {
+  ledgerRoot?: string;
+  checklist?: typeof checklistGate;
+  isPidAlive?: (pid: number) => boolean;
+}
+
+function readIfPresent(path: string): string | undefined {
+  try { return readFileSync(path, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false;
+    if ((error as NodeJS.ErrnoException).code === 'EPERM') return true;
+    throw error;
+  }
+}
+
+/** Read-only preflight; callers own acquiring and releasing run.lock around the graph. */
+export function releaseReadiness(version: string, deps: ReleaseReadinessDeps = {}): ReleaseReadiness {
+  if (!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(version)) throw new Error(`release version must be x.y.z: ${version}`);
+  const dir = join(deps.ledgerRoot ?? releaseLedgerRoot(), 'release', version);
+  const record = readIfPresent(join(dir, 'release.json'));
+  if (record) {
+    const data = JSON.parse(record) as { publishedAt?: unknown };
+    if (typeof data.publishedAt === 'string' && data.publishedAt.trim()) {
+      return { ready: false, reason: 'already-published', details: data.publishedAt };
+    }
+  }
+  const lock = readIfPresent(join(dir, 'run.lock'));
+  if (lock) {
+    let pid: unknown;
+    try { pid = (JSON.parse(lock) as { pid?: unknown } | null)?.pid; }
+    catch { pid = undefined; }
+    if (typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0 && (deps.isPidAlive ?? isPidAlive)(pid)) {
+      return { ready: false, reason: 'already-running', details: String(pid) };
+    }
+  }
+  const gate = (deps.checklist ?? checklistGate)(version);
+  if (!gate.ok) return { ready: false, reason: 'checklist-blocked', details: gate };
+  return { ready: true, reason: 'ready', details: gate };
+}

package/scripts/release-loop/shard-plan.ts

@@ -26,6 +26,23 @@ export function readFileDurations(dir: string): Map<string, number> {
   return durations;
 }
 
+/** Per-file peak memory (MB) from a TSV with `file` and `rss_mb` columns (TD1 whole-gate measurement); missing → empty. */
+export function readFileMemory(path: string): Map<string, number> {
+  const memory = new Map<string, number>();
+  let lines: string[];
+  try { lines = readFileSync(path, 'utf8').split(/\r?\n/); } catch { return memory; }
+  const header = lines[0]?.split('\t') ?? [];
+  const fileAt = header.indexOf('file');
+  const rssAt = header.indexOf('rss_mb');
+  if (fileAt < 0 || rssAt < 0) return memory;
+  for (const line of lines.slice(1)) {
+    const cells = line.split('\t');
+    const mb = Number(cells[rssAt]);
+    if (cells[fileAt] && cells[rssAt] !== '' && Number.isFinite(mb) && mb >= 0) memory.set(cells[fileAt]!, mb);
+  }
+  return memory;
+}
+
 /** Longest processing time first; tie-breaks use lexical paths, then the least populated lightest shard. */
 export function planShards(files: string[], durations: Map<string, number>, count: number): Array<{ files: string[]; plannedSeconds: number }> {
   if (!Number.isSafeInteger(count) || count < 1) throw new Error('invalid shard count');

package/scripts/release-loop/unattended-release.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getElanousConfigDirOverride } from '../../src/elanous-config-dir.js';
+import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
+import { userConfigPath } from '../../src/user-config.js';
+import { checklistGate } from '../../src/release-loop/checklist.js';
+import { runGraph, type GraphRunState } from '../../src/graph-runner/runner.js';
+
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
+
+export interface ReleaseLoopConfig {
+  gatePodPool?: string;
+  gatePodBunCache?: string;
+  gatePodShards?: number;
+  gatePodShardTimeoutSeconds?: number;
+  gateRemote?: string;
+  gateRemoteMirror?: string;
+  opsHosts?: string[];
+  internalDist?: string;
+  opsRestart?: boolean;
+}
+
+export interface ReleaseRunInput extends ReleaseLoopConfig {
+  version: string;
+  previousVersion: string;
+  gatePodPool: string;
+}
+
+export interface UnattendedReleaseDeps {
+  ledgerRoot?: string;
+  config?: ReleaseLoopConfig;
+  configPath?: string;
+  graph?: (path: string, options: { input: ReleaseRunInput }) => Promise<GraphRunState>;
+  checklist?: typeof checklistGate;
+}
+
+function compareVersions(a: string, b: string): number {
+  const aa = a.split('.').map(BigInt), bb = b.split('.').map(BigInt);
+  for (let i = 0; i < 3; i++) {
+    if (aa[i]! < bb[i]!) return -1;
+    if (aa[i]! > bb[i]!) return 1;
+  }
+  return 0;
+}
+
+/** Only completed publications in the release ledger count as a prior release. */
+export function latestPublishedPreviousVersion(version: string, ledgerRoot = releaseLedgerRoot()): string {
+  if (!VERSION.test(version)) throw new Error(`release version must be x.y.z: ${version}`);
+  const dir = join(ledgerRoot, 'release');
+  const versions = existsSync(dir) ? readdirSync(dir) : [];
+  const published = versions.filter((candidate) => {
+    if (!VERSION.test(candidate) || compareVersions(candidate, version) >= 0) return false;
+    try {
+      const record = JSON.parse(readFileSync(join(dir, candidate, 'release.json'), 'utf8')) as { version?: unknown; publishedAt?: unknown };
+      return record.version === candidate && typeof record.publishedAt === 'string' && record.publishedAt.trim().length > 0;
+    } catch { return false; }
+  });
+  const previous = published.sort((a, b) => compareVersions(b, a))[0];
+  if (!previous) throw new Error(`no published previous release before ${version} in ${dir}`);
+  return previous;
+}
+
+export function releaseLoopConfig(configPath = getElanousConfigDirOverride() ? join(effectiveInstanceRoot(), 'config.json') : userConfigPath()): ReleaseLoopConfig {
+  if (!existsSync(configPath)) return {};
+  const raw = JSON.parse(readFileSync(configPath, 'utf8')) as { release?: { loop?: ReleaseLoopConfig } };
+  return raw.release?.loop ?? {};
+}
+
+export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDeps = {}): ReleaseRunInput {
+  const config = deps.config ?? releaseLoopConfig(deps.configPath);
+  const pool = config.gatePodPool;
+  if (typeof pool !== 'string' || !pool.trim()) throw new Error('release.loop.gatePodPool is required before graph execution');
+  const previousVersion = latestPublishedPreviousVersion(version, deps.ledgerRoot);
+  return {
+    ...config,
+    version, previousVersion,
+    gatePodPool: pool.trim(),
+  };
+}
+
+/** Fail closed at the entry boundary, before any graph node can change a release. */
+export async function runUnattendedRelease(
+  opts: { version: string; dryRun?: boolean },
+  deps: UnattendedReleaseDeps = {},
+): Promise<{ input: ReleaseRunInput; dryRun: boolean; state?: GraphRunState }> {
+  const input = buildReleaseRunInput(opts.version, deps);
+  if (opts.dryRun) return { input, dryRun: true };
+  const gate = (deps.checklist ?? checklistGate)(opts.version);
+  if (!gate.ok) throw new Error(`release checklist blocked: ${[...gate.red, ...gate.undecided, ...gate.blocked].join(', ')}`);
+  const state = await (deps.graph ?? runGraph)(GRAPH, { input });
+  return { input, dryRun: false, state };
+}

package/scripts/storyboard/storyboard.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env bun
+// 스토리보드 정본(storyboards/<kind>/<id>.yaml) — 검사 ⊕ MD 뽑기 (대표 10-01 23:0x · OP 형식 결정 = YAML 정본 ⊕ 스키마 ⊕ 생성 MD).
+//   bun scripts/storyboard/storyboard.ts lint [파일…]     스키마 필수 칸 · 시간 겹침 · 화면 문구 출처 · 승인본 규칙
+//   bun scripts/storyboard/storyboard.ts render [파일…]   내부 문서 `STORYBOARD-<id>-v<version>` 를 다시 쓴다(손으로 안 고친다)
+// 인자가 없으면 storyboards/ 아래 전부. lint 는 오류가 있으면 rc 1, 경고만이면 rc 0.
+import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { parse } from 'yaml';
+
+const ROOT = resolve(import.meta.dir, '../..');
+const DIR = join(ROOT, 'storyboards');
+
+type Text = { text: string; source: string; ref?: string };
+type Shot = {
+  id: string; t: [number, number]; stage: string; layer?: string; persona?: string; purpose: string; subject?: string; action?: string;
+  camera?: { move?: string; lens_mm?: number; angle?: string; framing?: string }; lighting?: string; color?: string;
+  transition_in?: { type: string; intent: string }; on_screen_text?: Text[]; audio?: { vo?: string; sfx?: string; bgm?: string };
+  generation?: { tool: string; model?: string; prompt?: string; asset?: string }; real_or_staged: string; state: string; notes?: string;
+};
+/** kind: site — a site's page structure, menu and copy draft, planned like a storyboard (SITE2 · 10-02). */
+type Section = { id: string; title: string; purpose: string; change: string; copy?: Text[]; notes?: string };
+type Site = { domain: string; role: string; preview?: string; branch?: string; nav: Array<{ label: string; href: string }>; pages: Array<{ path: string; sections: Section[] }> };
+export type Storyboard = {
+  id: string; kind: string; title: string; version: number; status: string; approved?: { by: string; at: string; note?: string } | null;
+  supersedes?: string; owner: string; directive?: string; format: { aspects: string[]; duration_s: number; fps?: number; loop?: boolean; surface?: string };
+  scqa?: { s?: string; c?: string; q?: string; a?: string }; principles?: string[]; layers?: Record<string, string>; shots: Shot[]; sites?: Site[];
+  references?: string[]; open_questions?: string[];
+};
+
+const KINDS = ['teaser', 'site-hero', 'event-demo', 'persona-scene', 'explainer', 'ad', 'site'];
+const CHANGES = ['keep', 'move', 'new', 'replace', 'remove'];
+const STAGES = ['hook', 'buildup', 'climax', 'transition', 'end', 'loop'];
+const SOURCES = ['real-ui', 'real-cli', 'real-output', 'copy', 'example'];
+
+export function lint(sb: Storyboard, file = ''): { errors: string[]; warnings: string[] } {
+  const errors: string[] = [], warnings: string[] = [];
+  const need = (cond: unknown, msg: string) => { if (!cond) errors.push(msg); };
+  need(/^[a-z0-9][a-z0-9-]{2,80}$/.test(sb.id ?? ''), 'id: 소문자·숫자·하이픈 3~80자');
+  need(KINDS.includes(sb.kind), `kind: ${KINDS.join('|')}`);
+  need(Number.isInteger(sb.version) && sb.version >= 1, 'version: 1 이상 정수');
+  need(['draft', 'approved', 'superseded'].includes(sb.status), 'status: draft|approved|superseded');
+  need(sb.owner, 'owner 필요');
+  if (sb.status === 'approved') need(sb.approved?.by && sb.approved?.at, '승인본은 approved.by·at 필요');
+  if (file && sb.kind && !file.includes(`/${sb.kind}/`)) errors.push(`파일 위치가 kind(${sb.kind}) 폴더가 아니다`);
+  if (sb.kind === 'site') return lintSite(sb, errors, warnings);
+  need(sb.format?.aspects?.length && sb.format.duration_s > 0, 'format.aspects ⊕ duration_s 필요');
+  if (!Array.isArray(sb.shots) || !sb.shots.length) { errors.push('shots 가 비었다'); return { errors, warnings }; }
+  const ids = new Set<string>();
+  sb.shots.forEach((s, i) => {
+    const at = `shots[${i}](${s.id ?? '?'})`;
+    need(s.id && !ids.has(s.id), `${at}: id 없음·중복`); ids.add(s.id);
+    need(Array.isArray(s.t) && s.t.length === 2 && s.t[0] < s.t[1], `${at}: t = [시작, 끝] 이고 시작 < 끝`);
+    need(STAGES.includes(s.stage), `${at}: stage ${STAGES.join('|')}`);
+    need(s.purpose, `${at}: purpose(이 비트의 한 가지) 필요`);
+    need(['real', 'staged', 'composite'].includes(s.real_or_staged), `${at}: real_or_staged 필요`);
+    need(['planned', 'shot', 'approved'].includes(s.state), `${at}: state planned|shot|approved`);
+    if (s.transition_in && !s.transition_in.intent) errors.push(`${at}: 전환에는 의도 한 줄(«그냥 컷»은 설계가 아니다)`);
+    for (const txt of s.on_screen_text ?? []) {
+      need(SOURCES.includes(txt.source), `${at}: 화면 문구 «${txt.text}» 의 source 가 ${SOURCES.join('|')} 가 아니다`);
+      if (txt.source?.startsWith('real-') && !txt.ref) warnings.push(`${at}: 실제 문면 «${txt.text}» 에 ref(출처) 가 없다`);
+      if (/\d/.test(txt.text) && txt.source === 'copy') warnings.push(`${at}: 마케팅 문구에 숫자 «${txt.text}» — 실측 근거나 «example» 로`);
+    }
+    if (s.generation?.tool === 'higgsfield' && !s.generation.prompt) warnings.push(`${at}: 힉스필드 샷에 prompt 가 없다`);
+    if (s.real_or_staged !== 'real' && !/연출/.test(JSON.stringify(sb))) warnings.push(`${at}: 연출 샷이 있는데 문서 어디에도 «연출 장면» 표기가 없다`);
+  });
+  const end = Math.max(...sb.shots.map((s) => s.t?.[1] ?? 0));
+  if (sb.format?.duration_s && Math.abs(end - sb.format.duration_s) > 0.5) warnings.push(`마지막 샷 끝(${end}s) ≠ format.duration_s(${sb.format.duration_s}s)`);
+  return { errors, warnings };
+}
+
+/** A site plan has pages instead of shots: every section says why it is there and what changes; copy names its source. */
+function lintSite(sb: Storyboard, errors: string[], warnings: string[]): { errors: string[]; warnings: string[] } {
+  if (!Array.isArray(sb.sites) || !sb.sites.length) { errors.push('site 종류는 sites 가 필요하다'); return { errors, warnings }; }
+  for (const site of sb.sites) {
+    const at = `sites(${site.domain ?? '?'})`;
+    if (!site.domain || !site.role) errors.push(`${at}: domain ⊕ role(이 사이트가 맡는 것) 필요`);
+    if (!site.nav?.length) errors.push(`${at}: nav(메뉴) 필요`);
+    if (!site.pages?.length) errors.push(`${at}: pages 필요`);
+    if (!site.preview) warnings.push(`${at}: preview(미리보기 주소) 없음`);
+    const ids = new Set<string>();
+    for (const page of site.pages ?? []) for (const sec of page.sections ?? []) {
+      const where = `${at}${page.path} #${sec.id ?? '?'}`;
+      if (!sec.id || ids.has(`${page.path}#${sec.id}`)) errors.push(`${where}: id 없음·중복`);
+      ids.add(`${page.path}#${sec.id}`);
+      if (!sec.purpose) errors.push(`${where}: purpose(이 칸이 하는 한 가지) 필요`);
+      if (!CHANGES.includes(sec.change)) errors.push(`${where}: change ${CHANGES.join('|')}`);
+      for (const txt of sec.copy ?? []) {
+        if (!SOURCES.includes(txt.source)) errors.push(`${where}: 문구 «${txt.text}» 의 source 가 ${SOURCES.join('|')} 가 아니다`);
+        if (/\d/.test(txt.text) && txt.source === 'copy' && !txt.ref) warnings.push(`${where}: 마케팅 문구에 숫자 «${txt.text}» — ref(실측 근거) 를 단다`);
+      }
+    }
+  }
+  return { errors, warnings };
+}
+
+function renderSites(sb: Storyboard): string[] {
+  return (sb.sites ?? []).flatMap((site) => [
+    `## ${site.domain} — ${site.role}`, '',
+    ...(site.preview ? [`- 미리보기: ${site.preview}${site.branch ? ` (가지 \`${site.branch}\`)` : ''}`] : []),
+    `- 메뉴: ${site.nav.map((n) => `${n.label}(${n.href})`).join(' · ')}`, '',
+    ...site.pages.flatMap((page) => [
+      `### ${page.path}`, '', '| # | 칸 | 제목 | 목적 | 바뀜 | 문구(출처) | 메모 |', '|---|---|---|---|---|---|---|',
+      ...page.sections.map((sec, i) => `| ${i + 1} | ${md(sec.id)} | ${md(sec.title)} | ${md(sec.purpose)} | ${sec.change} | ${md((sec.copy ?? []).map((x) => `«${x.text}»(${x.source}${x.ref ? ` · ${x.ref}` : ''})`).join(' / '))} | ${md(sec.notes)} |`),
+      '',
+    ]),
+  ]);
+}
+
+const md = (v: unknown) => String(v ?? '').replace(/\|/g, '\\|').replace(/\n+/g, ' ');
+export function render(sb: Storyboard, file: string): string {
+  const head = [
+    `# STORYBOARD — ${sb.title} (v${sb.version} · ${sb.status}${sb.approved ? ` · 승인 ${sb.approved.by} ${sb.approved.at}` : ''})`,
+    '',
+    `> ⛔ 자동 생성 — 손으로 고치지 않는다. 정본 = \`${file}\` · 다시 뽑기 = \`bun scripts/storyboard/storyboard.ts render ${file}\`.`,
+    `> 종류 ${sb.kind} · 소유 ${sb.owner}${sb.format ? ` · ${sb.format.aspects.join(' · ')} · ${sb.format.duration_s}초${sb.format.loop ? ' · 반복' : ''}${sb.format.surface ? ` · ${sb.format.surface}` : ''}` : ''}${sb.supersedes ? ` · 앞 판 ${sb.supersedes}` : ''}`,
+    ...(sb.directive ? [`> 지시: ${sb.directive}`] : []),
+    '',
+  ];
+  const scqa = sb.scqa ? ['## SCQA', ...(['s', 'c', 'q', 'a'] as const).filter((k) => sb.scqa?.[k]).map((k) => `- **${k.toUpperCase()}** — ${sb.scqa![k]}`), ''] : [];
+  const pr = sb.principles?.length ? ['## 원칙', ...sb.principles.map((p, i) => `${i + 1}. ${p}`), ''] : [];
+  const layers = sb.layers ? ['## 층', ...Object.entries(sb.layers).map(([k, v]) => `- **${k}** — ${v}`), ''] : [];
+  const table = sb.kind === 'site' ? renderSites(sb) : [
+    '## 샷 구조표',
+    '| # | 초 | 단계 | 층·인물 | 목적 | 화면(피사체·행동) | 카메라 | 빛·색 | 전환(의도) | 화면 문구(출처) | 소리 | 만들기 | 실물/연출 · 상태 |',
+    '|---|---|---|---|---|---|---|---|---|---|---|---|---|',
+    ...sb.shots.map((s) => `| ${md(s.id)} | ${s.t[0]}–${s.t[1]} | ${s.stage} | ${md([s.layer, s.persona].filter(Boolean).join(' · '))} | ${md(s.purpose)} | ${md([s.subject, s.action].filter(Boolean).join(' — '))} | ${md(s.camera ? [s.camera.move, s.camera.lens_mm ? `${s.camera.lens_mm}mm` : '', s.camera.angle, s.camera.framing].filter(Boolean).join(' · ') : '')} | ${md([s.lighting, s.color].filter(Boolean).join(' · '))} | ${md(s.transition_in ? `${s.transition_in.type} — ${s.transition_in.intent}` : '')} | ${md((s.on_screen_text ?? []).map((x) => `«${x.text}»(${x.source}${x.ref ? ` · ${x.ref}` : ''})`).join(' / '))} | ${md(s.audio ? [s.audio.vo && `VO ${s.audio.vo}`, s.audio.sfx && `SFX ${s.audio.sfx}`, s.audio.bgm && `BGM ${s.audio.bgm}`].filter(Boolean).join(' · ') : '')} | ${md(s.generation ? [s.generation.tool, s.generation.model].filter(Boolean).join(' · ') : '')} | ${s.real_or_staged} · ${s.state} |`),
+    '',
+  ];
+  const shots = sb.shots ?? [];
+  const prompts = shots.filter((s) => s.generation?.prompt);
+  const pblock = prompts.length ? ['## 생성 프롬프트', ...prompts.flatMap((s) => [`### ${s.id} · ${s.generation!.tool}${s.generation!.model ? ` · ${s.generation!.model}` : ''}`, '```', s.generation!.prompt!.trim(), '```', ...(s.generation!.asset ? [`결과: \`${s.generation!.asset}\``] : []), ''])] : [];
+  const notes = shots.filter((s) => s.notes).map((s) => `- ${s.id}: ${s.notes}`);
+  const tail = [
+    ...(notes.length ? ['## 샷 메모', ...notes, ''] : []),
+    ...(sb.open_questions?.length ? ['## 열린 물음', ...sb.open_questions.map((q) => `- ${q}`), ''] : []),
+    ...(sb.references?.length ? ['## 참고', ...sb.references.map((r) => `- ${r}`), ''] : []),
+  ];
+  return [...head, ...scqa, ...pr, ...layers, ...table, ...pblock, ...tail].join('\n');
+}
+
+function files(args: string[]): string[] {
+  if (args.length) return args.map((a) => resolve(a));
+  const out: string[] = [];
+  const walk = (d: string) => { for (const f of readdirSync(d)) { const p = join(d, f); if (statSync(p).isDirectory()) walk(p); else if (/\.ya?ml$/.test(f) && !f.startsWith('_')) out.push(p); } };
+  walk(DIR);
+  return out.sort();
+}
+
+if (import.meta.main) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (cmd !== 'lint' && cmd !== 'render') { console.error('usage: storyboard.ts lint|render [files…]'); process.exit(2); }
+  let bad = 0;
+  for (const f of files(rest)) {
+    const rel = relative(ROOT, f);
+    const sb = parse(readFileSync(f, 'utf8')) as Storyboard;
+    const { errors, warnings } = lint(sb, rel);
+    for (const e of errors) console.log(`✗ ${rel}: ${e}`);
+    for (const w of warnings) console.log(`⚠ ${rel}: ${w}`);
+    if (errors.length) { bad++; continue; }
+    if (cmd === 'render') {
+      const out = join(ROOT, 'docs', 'marketing', `STORYBOARD-${sb.id}-v${sb.version}.md`);
+      writeFileSync(out, render(sb, rel) + '\n');
+      console.log(`✓ ${rel} → ${relative(ROOT, out)}`);
+    } else console.log(`✓ ${rel} · v${sb.version} · ${sb.status} · ${sb.kind === 'site' ? `사이트 ${sb.sites?.length ?? 0}` : `샷 ${sb.shots.length}`}`);
+  }
+  process.exit(bad ? 1 : 0);
+}

package/scripts/test-diet/lib.ts

@@ -0,0 +1,88 @@
+// TD2 — a daily look at the test suite, one cost-weighted slice at a time (shadow: it measures and drafts, it
+// never deletes or moves a test). Design: 내부 문서 `TD1-v2-gate-content-review-2026-10-01`.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DEFAULT_COST_SECS = 10;
+export const SLOW_SECS = 60;
+export const HEAVY_MB = 2048;
+
+export interface Measurement { file: string; secs: number; rssMb: number | null; rc: number | null; pass: number | null; fail: number | null; reason?: string }
+export type Verdict = 'keep' | 'failing' | 'review';
+export interface Judged extends Measurement { caught90: number; flags: string[]; verdict: Verdict }
+export interface LedgerLine { at: string; range: string; start: number; end: number; next: number; total: number; commit: string; budgetSecs: number; results: Judged[] }
+
+/** `file\tsecs\t…` (TD1 whole-gate TSV) → seconds per file. */
+export function costTable(tsv: string): Map<string, number> {
+  const costs = new Map<string, number>();
+  for (const line of tsv.split('\n').slice(1)) {
+    const [file, secs] = line.split('\t');
+    const n = Number(secs);
+    if (file && Number.isFinite(n) && n > 0) costs.set(file, n);
+  }
+  return costs;
+}
+
+/** Next slice from the cursor until the known cost reaches the budget (at least one file; wraps at the end). */
+export function pickRange(files: readonly string[], start: number, costs: ReadonlyMap<string, number>, budgetSecs: number): { start: number; end: number; next: number; files: string[]; estimatedSecs: number } {
+  if (files.length === 0) return { start: 0, end: -1, next: 0, files: [], estimatedSecs: 0 };
+  const from = ((start % files.length) + files.length) % files.length;
+  const picked: string[] = [];
+  let spent = 0;
+  let i = from;
+  while (picked.length < files.length) {
+    const file = files[i]!;
+    const cost = costs.get(file) ?? DEFAULT_COST_SECS;
+    if (picked.length > 0 && spent + cost > budgetSecs) break;
+    picked.push(file);
+    spent += cost;
+    i = (i + 1) % files.length;
+  }
+  return { start: from, end: (from + picked.length - 1) % files.length, next: i, files: picked, estimatedSecs: spent };
+}
+
+/** Mechanical verdict: failing, or slow/heavy with nothing caught in 90 days → review (a draft card, never an action). */
+export function judge(m: Measurement, caught90: number): Judged {
+  const flags: string[] = [];
+  if (m.secs >= SLOW_SECS) flags.push('slow');
+  if (m.rssMb !== null && m.rssMb >= HEAVY_MB) flags.push('heavy');
+  const verdict: Verdict = m.rc !== 0 ? 'failing' : flags.length > 0 && caught90 === 0 ? 'review' : 'keep';
+  return { ...m, caught90, flags, verdict };
+}
+
+export function ledgerPath(root: string): string { return join(root, 'test-diet', 'ledger.jsonl'); }
+
+export function lastLedgerLine(root: string): LedgerLine | null {
+  const path = ledgerPath(root);
+  if (!existsSync(path)) return null;
+  const lines = readFileSync(path, 'utf8').trim().split('\n').filter(Boolean);
+  try { return lines.length ? JSON.parse(lines.at(-1)!) as LedgerLine : null; } catch { return null; }
+}
+
+export function appendLedger(root: string, line: LedgerLine): void {
+  mkdirSync(join(root, 'test-diet'), { recursive: true });
+  appendFileSync(ledgerPath(root), `${JSON.stringify(line)}\n`);
+}
+
+/** Draft approval card — written as a file for a person to read; nothing is acted on. */
+export function writeCardDraft(root: string, line: LedgerLine): string | null {
+  const items = line.results.filter((r) => r.verdict !== 'keep');
+  if (items.length === 0) return null;
+  const dir = join(root, 'test-diet', 'cards');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${line.at.slice(0, 10)}-${line.range.replace(/[^0-9a-z~#-]/gi, '')}.md`);
+  const rows = items.map((r) => `| \`${r.file}\` | ${r.verdict} | ${r.secs}s | ${r.rssMb ?? '?'} MB | ${r.caught90} | ${r.flags.join(', ') || '—'} | ${(r.reason ?? '').replace(/\|/g, '/')} |`);
+  writeFileSync(path, [
+    `# 시험 리뷰 초안 — ${line.range} (${line.at.slice(0, 10)})`,
+    '',
+    '> 초안이다. 아무것도 지우거나 옮기지 않았다. 사람이 읽고 정한다.',
+    '',
+    '| 파일 | 판정 | 단독 시간 | 피크 메모리 | 90일 fix 커밋 | 표지 | 실패 사유(첫 줄) |',
+    '|---|---|---|---|---|---|---|',
+    ...rows,
+    '',
+    `원장: ${line.results.length}개 중 ${items.length}개 · 측정 판 ${line.commit}`,
+    '',
+  ].join('\n'));
+  return path;
+}