elanous 0.2.14 → 0.2.16

package/scripts/goals/goal-census.ts

@@ -0,0 +1,343 @@
+#!/usr/bin/env bun
+/**
+ * GOAL-LIFE① — docs/goals 전수 분류(이관 전 측정).
+ *
+ * GitHub API·gh 를 부르지 않는다. git 이력과 파일 시스템만 읽고,
+ * docs/goals 아래 어떤 파일도 쓰지 않는다.
+ *
+ *   bun scripts/goals/goal-census.ts [--json] [--out <path>]
+ */
+import { spawnSync } from 'node:child_process';
+import { readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+
+export type GoalKind = 'GOAL' | 'ASK' | 'other';
+export type GoalClass = 'landed' | 'untracked' | 'tracked-no-pr';
+
+export interface GoalCensusEntry {
+  readonly path: string;
+  readonly classification: GoalClass;
+  readonly kind: GoalKind;
+  readonly bytes: number;
+  /** 추가 날짜 YYYY-MM-DD (KST). 미추적이면 파일 mtime. */
+  readonly addedDateKst: string;
+  readonly prNumber?: number;
+  readonly addCommit?: string;
+}
+
+export interface GoalCensusSummary {
+  readonly total: number;
+  readonly byClass: Record<GoalClass, number>;
+  readonly byKind: Record<GoalKind, number>;
+  readonly matrix: Record<GoalClass, Record<GoalKind, number>>;
+  readonly bytes: number;
+  readonly bytesByClass: Record<GoalClass, number>;
+  /** 월별 추가 수 — YYYY-MM (KST). */
+  readonly addedByMonth: Record<string, number>;
+}
+
+export interface GoalCensus {
+  readonly entries: readonly GoalCensusEntry[];
+  readonly summary: GoalCensusSummary;
+}
+
+export interface AddedCommit {
+  readonly hash: string;
+  readonly subject: string;
+  /** git %aI — ISO 8601 with offset. */
+  readonly authoredAt: string;
+}
+
+export interface CensusGoalsInput {
+  readonly repoRoot: string;
+  /** 경로(repo 상대, posix) → 그 파일을 처음 추가한 커밋. 없으면 미추적. */
+  readonly gitLog: (repoRoot: string) => ReadonlyMap<string, AddedCommit>;
+  /** repo 상대 미추적 경로. */
+  readonly listUntracked: (repoRoot: string) => readonly string[];
+  /** 테스트·대체 루트. 기본 docs/goals. */
+  readonly goalsDir?: string;
+}
+
+const CLASSES: readonly GoalClass[] = ['landed', 'untracked', 'tracked-no-pr'];
+const KINDS: readonly GoalKind[] = ['GOAL', 'ASK', 'other'];
+
+const PR_AT_END = /\(#(\d+)\)\s*$/;
+
+export function classifyKind(relPath: string): GoalKind {
+  const base = relPath.split('/').pop() ?? relPath;
+  if (base.startsWith('GOAL')) return 'GOAL';
+  if (base.startsWith('ASK')) return 'ASK';
+  return 'other';
+}
+
+export function prNumberFromSubject(subject: string): number | undefined {
+  const m = subject.match(PR_AT_END);
+  return m ? Number(m[1]) : undefined;
+}
+
+/** UTC ISO(또는 offset 포함) → KST YYYY-MM-DD. */
+export function kstDate(iso: string): string {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return iso.slice(0, 10);
+  const kst = new Date(t + 9 * 60 * 60 * 1000);
+  const y = kst.getUTCFullYear();
+  const m = String(kst.getUTCMonth() + 1).padStart(2, '0');
+  const d = String(kst.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+function emptyMatrix(): Record<GoalClass, Record<GoalKind, number>> {
+  const matrix = {} as Record<GoalClass, Record<GoalKind, number>>;
+  for (const c of CLASSES) {
+    matrix[c] = { GOAL: 0, ASK: 0, other: 0 };
+  }
+  return matrix;
+}
+
+function measureEntry(repoRoot: string, rel: string): { bytes: number; mtimeIso: string; files: string[] } {
+  const abs = resolve(repoRoot, rel);
+  const root = resolve(repoRoot);
+  try {
+    const st = statSync(abs);
+    if (!st.isDirectory()) return { bytes: st.size, mtimeIso: st.mtime.toISOString(), files: [rel] };
+    const files: string[] = [];
+    walkFiles(abs, root, files);
+    let bytes = 0;
+    for (const f of files) {
+      try { bytes += statSync(resolve(repoRoot, f)).size; } catch { /* skip missing */ }
+    }
+    return { bytes, mtimeIso: st.mtime.toISOString(), files };
+  } catch {
+    return { bytes: 0, mtimeIso: new Date(0).toISOString(), files: [] };
+  }
+}
+
+function earliestAddition(added: ReadonlyMap<string, AddedCommit>, prefix: string): AddedCommit | undefined {
+  let best: AddedCommit | undefined;
+  for (const [p, c] of added) {
+    if (!p.startsWith(prefix)) continue;
+    if (!best || c.authoredAt < best.authoredAt) best = c;
+  }
+  return best;
+}
+
+function walkFiles(dir: string, root: string, out: string[]): void {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name === '.git') continue;
+    const abs = join(dir, name);
+    let st;
+    try {
+      st = statSync(abs);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) walkFiles(abs, root, out);
+    else if (st.isFile()) out.push(relative(root, abs).split('\\').join('/'));
+  }
+}
+
+/**
+ * `ls docs/goals` 와 같은 최상위 이름(파일·디렉터리 각 1).
+ * 디렉터리의 크기·착지 근거는 그 아래 파일을 모아 정한다.
+ */
+export function listGoalFiles(repoRoot: string, goalsDir = 'docs/goals'): string[] {
+  const abs = resolve(repoRoot, goalsDir);
+  let names: string[];
+  try {
+    names = readdirSync(abs);
+  } catch {
+    return [];
+  }
+  return names.filter((n) => n !== '.' && n !== '..').map((n) => `${goalsDir}/${n}`).sort();
+}
+
+export function summarize(entries: readonly GoalCensusEntry[]): GoalCensusSummary {
+  const byClass = { landed: 0, untracked: 0, 'tracked-no-pr': 0 } as Record<GoalClass, number>;
+  const byKind = { GOAL: 0, ASK: 0, other: 0 } as Record<GoalKind, number>;
+  const matrix = emptyMatrix();
+  const bytesByClass = { landed: 0, untracked: 0, 'tracked-no-pr': 0 } as Record<GoalClass, number>;
+  const addedByMonth: Record<string, number> = {};
+  let bytes = 0;
+  for (const e of entries) {
+    byClass[e.classification] += 1;
+    byKind[e.kind] += 1;
+    matrix[e.classification][e.kind] += 1;
+    bytesByClass[e.classification] += e.bytes;
+    bytes += e.bytes;
+    const month = e.addedDateKst.slice(0, 7);
+    addedByMonth[month] = (addedByMonth[month] ?? 0) + 1;
+  }
+  return { total: entries.length, byClass, byKind, matrix, bytes, bytesByClass, addedByMonth };
+}
+
+export function censusGoals(input: CensusGoalsInput): GoalCensus {
+  const goalsDir = input.goalsDir ?? 'docs/goals';
+  const prefix = goalsDir.endsWith('/') ? goalsDir : `${goalsDir}/`;
+  const files = listGoalFiles(input.repoRoot, goalsDir);
+  const added = input.gitLog(input.repoRoot);
+  const untracked = new Set(input.listUntracked(input.repoRoot).map((p) => p.split('\\').join('/')));
+
+  const entries: GoalCensusEntry[] = [];
+  for (const path of files) {
+    if (!path.startsWith(prefix)) continue;
+    const kind = classifyKind(path);
+    const measured = measureEntry(input.repoRoot, path);
+    const { bytes, mtimeIso } = measured;
+    const commit = added.get(path) ?? earliestAddition(added, `${path}/`);
+    const nestedUntracked = measured.files.length > 0
+      && measured.files.every((f) => untracked.has(f) || !added.has(f));
+    if (!commit || untracked.has(path) || nestedUntracked) {
+      entries.push({
+        path,
+        classification: 'untracked',
+        kind,
+        bytes,
+        addedDateKst: kstDate(mtimeIso),
+      });
+      continue;
+    }
+    const prNumber = prNumberFromSubject(commit.subject);
+    if (prNumber !== undefined) {
+      entries.push({
+        path,
+        classification: 'landed',
+        kind,
+        bytes,
+        addedDateKst: kstDate(commit.authoredAt),
+        prNumber,
+        addCommit: commit.hash,
+      });
+    } else {
+      entries.push({
+        path,
+        classification: 'tracked-no-pr',
+        kind,
+        bytes,
+        addedDateKst: kstDate(commit.authoredAt),
+        addCommit: commit.hash,
+      });
+    }
+  }
+  return { entries, summary: summarize(entries) };
+}
+
+/**
+ * 파일을 처음 추가한 커밋만. `git log --diff-filter=A` 한 번.
+ * 최신→과거 순이므로 같은 경로가 다시 나오면 나중 값(최초 추가)이 이긴다.
+ */
+export function gitLogAdditions(repoRoot: string, goalsDir = 'docs/goals'): Map<string, AddedCommit> {
+  const r = spawnSync(
+    'git',
+    [
+      '-C', repoRoot,
+      'log',
+      '--diff-filter=A',
+      '--name-only',
+      '--format=@@%H%x09%s%x09%aI',
+      '--',
+      goalsDir,
+    ],
+    { encoding: 'utf8', maxBuffer: 512 * 1024 * 1024 },
+  );
+  if (r.status !== 0) {
+    throw new Error(`git log failed: ${(r.stderr || '').trim()}`);
+  }
+  const out = new Map<string, AddedCommit>();
+  let current: AddedCommit | undefined;
+  for (const line of r.stdout.split('\n')) {
+    if (!line) continue;
+    if (line.startsWith('@@')) {
+      const body = line.slice(2);
+      const tab = body.indexOf('\t');
+      const tab2 = body.lastIndexOf('\t');
+      if (tab > 0 && tab2 > tab) {
+        current = {
+          hash: body.slice(0, tab),
+          subject: body.slice(tab + 1, tab2),
+          authoredAt: body.slice(tab2 + 1),
+        };
+      }
+      continue;
+    }
+    if (current) out.set(line, current);
+  }
+  return out;
+}
+
+/** 작업 트리의 미추적 파일. `git ls-files --others --exclude-standard`. */
+export function gitListUntracked(repoRoot: string, goalsDir = 'docs/goals'): string[] {
+  const r = spawnSync(
+    'git',
+    ['-C', repoRoot, 'ls-files', '--others', '--exclude-standard', '--', goalsDir],
+    { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
+  );
+  if (r.status !== 0) {
+    throw new Error(`git ls-files failed: ${(r.stderr || '').trim()}`);
+  }
+  return r.stdout.split('\n').filter((p) => p.length > 0);
+}
+
+export function formatSummary(census: GoalCensus): string {
+  const { summary } = census;
+  const lines: string[] = [];
+  lines.push(`total ${summary.total}  bytes ${summary.bytes}`);
+  lines.push('class × kind');
+  const header = ['class', ...KINDS, 'bytes'].join('\t');
+  lines.push(header);
+  for (const c of CLASSES) {
+    const row = [
+      c,
+      ...KINDS.map((k) => String(summary.matrix[c][k])),
+      String(summary.bytesByClass[c]),
+    ];
+    lines.push(row.join('\t'));
+  }
+  lines.push('added by month (KST)');
+  const months = Object.keys(summary.addedByMonth).sort();
+  for (const month of months) lines.push(`${month}\t${summary.addedByMonth[month]}`);
+  return lines.join('\n') + '\n';
+}
+
+function parseArgs(argv: readonly string[]): { json: boolean; out?: string } {
+  let json = false;
+  let out: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') json = true;
+    else if (a === '--out') {
+      out = argv[i + 1];
+      i += 1;
+    } else if (a.startsWith('--out=')) out = a.slice('--out='.length);
+  }
+  return { json, out };
+}
+
+function main(argv: readonly string[]): void {
+  const repoRoot = resolve(import.meta.dir, '../..');
+  const args = parseArgs(argv);
+  const census = censusGoals({
+    repoRoot,
+    gitLog: (root) => gitLogAdditions(root),
+    listUntracked: (root) => gitListUntracked(root),
+  });
+  const { summary } = census;
+  debug.log('goals.census', 'scanned', {
+    total: summary.total,
+    landed: summary.byClass.landed,
+    untracked: summary.byClass.untracked,
+    trackedNoPr: summary.byClass['tracked-no-pr'],
+    bytes: summary.bytes,
+  });
+  const body = args.json ? JSON.stringify(census, null, 2) + '\n' : formatSummary(census);
+  if (args.out) writeFileSync(args.out, body);
+  process.stdout.write(body);
+}
+
+if (import.meta.main) main(process.argv.slice(2));

package/scripts/lecture-note/node.ts

@@ -5,6 +5,7 @@ import { dirname, extname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { debug } from '../../src/debug/log.js';
+import { runOcr } from '../../skills/omni-digest/src/ocr.js';
 import { streamLLM } from '../../src/llm.js';
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
@@ -19,6 +20,7 @@ export interface Counts { inputs: number; diagrams: number; rendered: number; ht
 export interface StageResult extends Counts { outcome: 'ok' | 'skipped' }
 export interface StageOptions {
   llm?: (prompt: string) => Promise<string>;
+  ocr?: (filePath: string) => Promise<string>;
   toolsPath?: string;
   referenceRoot?: string;
 }
@@ -62,9 +64,9 @@ function binary(name: string, path = process.env.PATH ?? ''): string | undefined
   return undefined;
 }
 
-function run(bin: string, args: string[], dir: string, timeout: number): ReturnType<typeof spawnSync> {
+function run(bin: string, args: string[], dir: string, timeout: number, cacheDir = dir): ReturnType<typeof spawnSync> {
   return spawnSync(bin, args, { cwd: dir, encoding: 'utf8', timeout, maxBuffer: 20 * 1024 * 1024,
-    env: { ...process.env, HOME: dir, XDG_CACHE_HOME: dir, XDG_CONFIG_HOME: dir, UV_CACHE_DIR: dir, PYTHONDONTWRITEBYTECODE: '1' } });
+    env: { ...process.env, HOME: dir, XDG_CACHE_HOME: dir, XDG_CONFIG_HOME: dir, UV_CACHE_DIR: cacheDir, PYTHONDONTWRITEBYTECODE: '1' } });
 }
 
 function readInputs(dir: string): Input[] {
@@ -83,7 +85,7 @@ function counts(dir: string): Counts {
   return { inputs, diagrams, rendered, html: existsSync(join(dir, 'notes.html')) ? 'yes' : 'no', pdf: existsSync(join(dir, 'notes.pdf')) ? 'yes' : 'skipped' };
 }
 
-export function collect(folder: string, options: StageOptions = {}): StageResult {
+export async function collect(folder: string, options: StageOptions = {}): Promise<StageResult> {
   const dir = outputDir(folder);
   const files: Input[] = [];
   const pdfText = binary('pdftotext', options.toolsPath);
@@ -94,11 +96,22 @@ export function collect(folder: string, options: StageOptions = {}): StageResult
     const kind = kinds[extname(entry.name).toLowerCase()];
     if (!entry.isFile() || !kind) continue;
     const at = join(base, entry.name);
-    const text = kind === 'markdown' ? readFileSync(at, 'utf8') : kind === 'image' ? '이미지 — 시각 자료 (텍스트 추출 없음)' :
-      pdfText ? (() => {
-        const result = run(pdfText, ['-layout', at, '-'], dir, 60000);
-        return result.status === 0 ? String(result.stdout) : 'PDF 텍스트 없음 — pdftotext 추출 실패';
-      })() : 'PDF 텍스트 없음 — pdftotext 없음';
+    let text: string;
+    if (kind === 'markdown') text = readFileSync(at, 'utf8');
+    else if (kind === 'image') {
+      try {
+        const extracted = await (options.ocr ?? runOcr)(at);
+        if (!extracted.trim()) throw new Error('Upstage/OCR.space 폴백 결과가 비었다');
+        text = extracted;
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        text = `이미지 텍스트 못 읽음 · ${reason}`;
+        debug.log('lecture-note.collect', 'ocr-failed', { name: prefix + entry.name, reason });
+      }
+    } else if (pdfText) {
+      const result = run(pdfText, ['-layout', at, '-'], dir, 60000);
+      text = result.status === 0 ? String(result.stdout) : 'PDF 텍스트 없음 — pdftotext 추출 실패';
+    } else text = 'PDF 텍스트 없음 — pdftotext 없음';
     files.push({ name: prefix + entry.name, kind, text });
   }
   writeFileSync(artifact(dir, 'inputs.json'), JSON.stringify(files, null, 2) + '\n');
@@ -131,19 +144,26 @@ export function render(folder: string, options: StageOptions = {}): StageResult
   const renderer = join(options.referenceRoot ?? ownRoot, 'diagram-master/references/engines/mermaid/render_mermaid.py');
   const uv = binary('uv', options.toolsPath);
   let unavailable = 0;
+  let failed = 0;
   for (const [i, match] of [...notes.matchAll(mermaid)].entries()) {
     const png = artifact(dir, `diagram-${i + 1}.png`);
     if (existsSync(png)) rmSync(png);
     if (!uv || !existsSync(renderer)) { unavailable++; continue; }
     const mmd = artifact(dir, `diagram-${i + 1}.mmd`);
     writeFileSync(mmd, match[1]!);
-    const result = run(uv, ['run', 'python', renderer, mmd, '--output', png], dir, 120000);
+    const cacheDir = join(process.env.ELANOUS_STATE_DIR ?? join(homedir(), '.elanous'), 'lecture-note', 'uv-cache');
+    const result = run(uv, ['run', 'python', renderer, mmd, '--output', png], dir, 120000, cacheDir);
     if (result.status !== 0 || !existsSync(png)) {
       if (existsSync(png)) rmSync(png);
-      throw new Error(`Mermaid 렌더 실패 (diagram-${i + 1}, exit=${result.status}): ${result.error?.message ?? result.stderr ?? result.stdout ?? 'PNG 없음'}`);
+      failed++;
+      const detail = String(result.stderr ?? '').split(/\r?\n/)[0]?.trim() || result.error?.message ||
+        String(result.stdout ?? '').split(/\r?\n/)[0]?.trim() || 'PNG 없음';
+      const reason = `Mermaid 렌더 실패 (diagram-${i + 1}, exit=${result.status}): ${detail}`;
+      debug.log('lecture-note.render', 'diagram-failed', { name: `diagram-${i + 1}`, reason });
     }
   }
   if (unavailable) console.log(`렌더러 없음: ${unavailable}`);
+  if (failed) console.log(`못 그림: ${failed}`);
   return { ...counts(dir), outcome: 'ok' };
 }
 
@@ -216,7 +236,7 @@ export function pdf(folder: string, options: StageOptions = {}): StageResult {
 }
 
 export async function runStage(stage: Stage, folder: string, options: StageOptions = {}): Promise<StageResult> {
-  const result = stage === 'collect' ? collect(folder, options) : stage === 'draft' ? await draft(folder, options) :
+  const result = stage === 'collect' ? await collect(folder, options) : stage === 'draft' ? await draft(folder, options) :
     stage === 'render' ? render(folder, options) : stage === 'html' ? html(folder, options) : pdf(folder, options);
   debug.log('lecture.note', stage, { inputs: result.inputs, diagrams: result.diagrams, rendered: result.rendered, pdf: result.pdf });
   return result;

package/scripts/lessons/handbook-page.ts

@@ -29,14 +29,41 @@ function inlineText(value: string): string {
         www ? 'w\u200bww.' : `${scheme ?? at}\u200b${slashes ?? ''}`);
 }
 
+function displayId(id: string): string {
+  return id.replace(/(-(?:\d{4}-\d{2}-\d{2}|undated))-[a-f\d]{64}$/i, '$1');
+}
+
+function summaryText(value: string): string {
+  // 원장 적재 때 줄바꿈이 사라져 «| a | b | |---|---| | 1 | 2 |» 처럼 한 줄로 뭉개진 표는 행 경계 «| |»에서 다시 줄로 편다.
+  const lines = value.split(/\r?\n/)
+    .flatMap(line => /\|\s*:?-{3,}:?\s*\|/.test(line) && /\|\s+\|/.test(line) ? line.replace(/\|\s+\|/g, '|\n|').split('\n') : [line])
+    .map(line => line.trim()).filter(Boolean);
+  const cells = (line: string) => line.replace(/^\||\|$/g, '').split('|').map(cell => cell.trim());
+  const findTable = () => lines.findIndex((line, index) => {
+    if (!line.includes('|') || !lines[index + 1]) return false;
+    const separator = cells(lines[index + 1]);
+    return separator.length > 1 && separator.every(cell => /^:?-{3,}:?$/.test(cell));
+  });
+  // 표가 여럿이면 모두 «첫 데이터 행 한 줄»로 접는다 — 뒤 표의 구분선·이스케이프가 남지 않게.
+  for (let tableAt = findTable(); tableAt >= 0; tableAt = findTable()) {
+    const row = lines[tableAt + 2]?.includes('|') ? lines[tableAt + 2] : lines[tableAt];
+    const summary = cells(row).join(' · ');
+    let after = tableAt + 2;
+    while (after < lines.length && lines[after].includes('|')) after++;
+    lines.splice(tableAt, after - tableAt, summary);
+  }
+  const text = lines.join(' ').replace(/\*\*|__/g, '').replace(/\s+/g, ' ').trim();
+  return inlineText(text.length > 200 ? `${text.slice(0, 200)}…` : text);
+}
+
 function section(title: string, rows: LessonRow[], ledger: LessonLedger, kind: LessonStatus): string[] {
   const lines = [`## ${title}`, ''];
   if (!rows.length) return [...lines, '없음', ''];
   for (const row of rows) {
     const last = ledger.get(row.id).occurrences.at(-1);
-    lines.push(`### ${inlineText(row.id)} — ${inlineText(row.incident)}`,
-      `- 원인: ${inlineText(row.cause)}`,
-      `- 처방: ${inlineText(row.remedy)}`,
+    lines.push(`### ${inlineText(displayId(row.id))} — ${inlineText(row.incident)}`,
+      `- 원인: ${summaryText(row.cause)}`,
+      `- 처방: ${summaryText(row.remedy)}`,
       `- 재발: ${row.occurrence_count}회`,
       `- 마지막 발생: ${inlineText(last?.at ?? '없음')} · 출처: ${inlineText(last?.source ?? '없음')}`);
     if (kind === 'candidate') lines.push(`- 반증: ${row.disproof?.trim() ? inlineText(row.disproof) : '반증 없음 — 승격 불가'}`);

package/scripts/marketing/generate-ax-brief.ts

@@ -0,0 +1,140 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { FEATURE_MATURITY } from '../../src/maturity/feature-maturity.js';
+import type { ChecklistItem } from '../../src/release-loop/checklist.js';
+import type { ReleaseSchedule } from '../../src/release-loop/release-schedule.js';
+import type { MergedRunLedgerQuery } from '../../src/self-implement/run-ledger.js';
+import { generateFeatureMap } from './generate-feature-map.js';
+
+const MAP = resolve(import.meta.dir, '../../docs/marketing/MAP-value-props-to-features.md');
+const AUTONOMY = new Set(['ORCH1', 'ORCH2', 'LOOP-LIVE1', 'AUTOQ-LOOP', 'AUTHOR-PAR', 'RUN-HELPER', 'FINISH-RATE']);
+const ROADMAP = /^(?:ENT-|KPACK|GRID)/;
+
+export interface AxBriefSources {
+  featureMap: () => string;
+  checklist: (version: string) => readonly ChecklistItem[];
+  schedules: () => readonly ReleaseSchedule[];
+  merges: () => Pick<MergedRunLedgerQuery, 'entries' | 'ledgerDirectoryMissing' | 'unreadableLedgerCount' | 'excludedLedgerCount'>;
+  now?: () => Date;
+}
+
+type Source<T> = { ok: true; value: T } | { ok: false; reason: string };
+
+function readSource<T>(read: () => T): Source<T> {
+  try { return { ok: true, value: read() }; }
+  catch (error) { return { ok: false, reason: error instanceof Error ? error.message : String(error) }; }
+}
+
+function cell(text: string): string {
+  return text.replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ').trim();
+}
+
+function reason(source: Source<unknown>): string {
+  return source.ok ? '' : `못 읽음 · 사유: ${cell(source.reason)}`;
+}
+
+function versionNumbers(version: string): number[] | null {
+  return /^\d+\.\d+\.\d+$/.test(version) ? version.split('.').map(Number) : null;
+}
+
+function after03(version: string): boolean {
+  const parts = versionNumbers(version);
+  return !!parts && (parts[0]! > 0 || parts[1]! >= 3);
+}
+
+function compareVersions(left: string, right: string): number {
+  const a = versionNumbers(left)!, b = versionNumbers(right)!;
+  return a[0]! - b[0]! || a[1]! - b[1]! || a[2]! - b[2]!;
+}
+
+function firstLine(evidence: string | undefined): string {
+  return evidence?.split(/\r?\n/, 1)[0]?.trim() || '근거 없음';
+}
+
+/** Read-only report: failures in one ledger do not turn other sections into claims of success. */
+export function generateAxBrief(version: string, sources: AxBriefSources): string {
+  const now = (sources.now ?? (() => new Date()))().toISOString();
+  const feature = readSource(sources.featureMap);
+  const current = readSource(() => sources.checklist(version));
+  const schedules = readSource(sources.schedules);
+  const merges = readSource(sources.merges);
+  const mergeCount = merges.ok && !merges.value.ledgerDirectoryMissing
+    ? new Set(merges.value.entries.filter((entry) => entry.merged).map((entry) => entry.prNumber)).size : null;
+  const mergeValue = merges.ok && !merges.value.ledgerDirectoryMissing && merges.value.unreadableLedgerCount > 0
+    ? `못 읽음 · 사유: 원장 ${merges.value.unreadableLedgerCount}건 판독 실패 · 확인된 병합 ${mergeCount}건 (집계 불완전)`
+    : mergeCount ?? (merges.ok ? '못 읽음 · 사유: 원장 디렉터리 없음' : reason(merges));
+  const mergeCaveat = merges.ok && !merges.value.ledgerDirectoryMissing && (merges.value.unreadableLedgerCount || merges.value.excludedLedgerCount)
+    ? ` · 미반영 원장: 못 읽음 ${merges.value.unreadableLedgerCount}건 · 중복 병합 제외 ${merges.value.excludedLedgerCount}건` : '';
+  const featureRows = feature.ok ? feature.value.split(/\r?\n/).filter((line) => /^\| .* \| (?:된다|베타) \|/.test(line)) : [];
+  const autonomous = current.ok ? current.value.filter((item) => AUTONOMY.has(item.id)) : [];
+  const roadmap = schedules.ok ? schedules.value.filter((schedule) => after03(schedule.version)).sort((a, b) => compareVersions(a.version, b.version)) : [];
+  const roadmapSources = roadmap.map((schedule) => ({ version: schedule.version, result: schedule.version === version ? current : readSource(() => sources.checklist(schedule.version)) }));
+  const roadmapFailures = roadmapSources.filter(({ result }) => !result.ok).map(({ version: v, result }) => `${v}: ${reason(result)}`);
+  const roadmapRows = roadmapSources.flatMap(({ version: v, result }) => result.ok
+    ? result.value.filter((item) => ROADMAP.test(item.id)).map((item) => `| ${cell(v)} | ${cell(item.id)} | ${cell(item.title)} |`)
+    : []);
+  const owners = [...new Set(autonomous.map((item) => item.owner).filter((owner): owner is string => !!owner))];
+  return [
+    '# AX-BRIEF — 내부·파트너용 AX 브리핑',
+    '',
+    '> 공개 문서가 아닙니다. 내부 수치·자리 이름을 포함하며 외부 공개 판정으로 쓰지 않습니다.',
+    `> 생성: ${cell(version)} · ${now} · 원천: FEATURE-MAP 생성 출력, 릴리스 체크리스트, 릴리스 일정(release schedules), self-implement run-ledger`,
+    '',
+    '## 1. 지금 되는 것',
+    '',
+    feature.ok ? '| 기능 | 성숙도 | 칸 id | 근거 PR |' : reason(feature),
+    ...(feature.ok ? ['|---|---|---|---|', ...featureRows] : []),
+    '',
+    '## 2. 자율 단계표',
+    '',
+    current.ok ? '| 칸 | 판 | 상태 | 근거 첫 줄 |' : reason(current),
+    ...(current.ok ? ['|---|---|---|---|', ...autonomous.map((item) => `| ${cell(item.id)} | ${cell(version)} | ${cell(item.status)} | ${cell(firstLine(item.evidence))} |`)] : []),
+    ...(current.ok ? [`자리 이름: ${owners.length ? owners.map(cell).join(' · ') : '원장에 없음'}`] : []),
+    '',
+    `실제 병합 수 (self-implement run-ledger 전체 기록 · 중복 PR 제외 · 외부/수동 병합 제외): ${mergeValue}${mergeCaveat}`,
+    '',
+    '## 3. 로드맵 계단',
+    '',
+    '> 계획 · 바뀔 수 있습니다',
+    schedules.ok ? '| 판 | 칸 | 제목 |' : reason(schedules),
+    ...(schedules.ok ? ['|---|---|---|', ...roadmapRows, ...roadmapFailures.map((failure) => `못 읽음 · 사유: ${cell(failure)}`)] : []),
+    '',
+    '## 4. 도입 경로 (파일럿 기준 · 한 자리부터)',
+    '',
+    '1. **설치 한 줄 → 웹 앱 첫 화면** — 쓰던 구독을 그대로 알아본다.',
+    '2. **한 자리(예: 마케팅 또는 기술)만** — L1(한 줄 → 병합)을 그 팀 저장소에서. 측정: 발사 대비 병합 · 사람 수확 비율.',
+    '3. **결정 카드** — 비가역·공개만 사람에게. 나머지는 자리에 위임 범위를 적는다.',
+    '4. **자리 넷 ⊕ 그림자 루프** — L2 를 «기록만»으로 일주일 대조한 뒤 live.',
+    '5. **지식 팩** — 사내 문서·절차를 팩으로(로드맵 §3 · 유료 판매는 결정 뒤).',
+    '',
+  ].join('\n');
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const option = (name: string) => {
+    const index = args.indexOf(name);
+    if (index < 0) return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${name} 값이 필요하다`);
+    args.splice(index, 2);
+    return value;
+  };
+  const version = option('--version');
+  const out = option('--out');
+  if (!version || args.length) throw new Error('Usage: bun scripts/marketing/generate-ax-brief.ts --version <v> [--out <file>]');
+  const { listChecklist } = await import('../../src/release-loop/checklist.js');
+  const { listSchedules } = await import('../../src/release-loop/release-schedule.js');
+  const { queryMergedRunLedgers } = await import('../../src/self-implement/run-ledger.js');
+  const { releaseLedgerRoot } = await import('../../src/instance/resolve.js');
+  const root = releaseLedgerRoot();
+  const checklist = (v: string) => listChecklist(v, root).items;
+  const body = generateAxBrief(version, {
+    featureMap: () => generateFeatureMap({ map: readFileSync(MAP, 'utf8'), items: checklist(version), registry: FEATURE_MATURITY, version }),
+    checklist,
+    schedules: () => listSchedules(root),
+    merges: () => queryMergedRunLedgers(),
+  });
+  if (out) writeFileSync(out, body);
+  else process.stdout.write(body);
+}