elanous 0.2.14 → 0.2.15

package/scripts/ci-typecheck-changed.ts

@@ -53,6 +53,9 @@ export type ChangedTsFiles = {
   files: Set<string>;
   base: string;
   baseSource: string;
+  head?: string;
+  diffFiles?: Set<string>;
+  warnings?: string[];
   failures?: { command: string; why: string }[];
 };
 
@@ -78,23 +81,41 @@ export function changedTsFiles(run = sh, env: NodeJS.ProcessEnv = process.env):
     }
   }
 
-  const files = new Set<string>();
-  const add = (out: string) => {
-    for (const line of out.split('\n')) {
-      const file = line.trim().replace(/^\.\//, '');
-      if (/\.tsx?$/.test(file) && existsSync(file)) files.add(file);
-    }
-  };
   const failures: { command: string; why: string }[] = [];
-  const addCommand = (command: string) => {
-    try { add(run(command)); } catch (cause) {
+  // Revision reads are observational: an unreadable HEAD/base must not turn into a collection failure.
+  const quietRevision = (command: string): string => { try { return run(command).trim(); } catch { return ''; } };
+  const head = quietRevision('git rev-parse HEAD') || undefined;
+  const warnings: string[] = [];
+  if (head && quietRevision(`git rev-parse ${base}`) === head) {
+    const main = quietRevision('git rev-parse origin/main');
+    const merged = main && main !== head ? quietRevision('git merge-base HEAD origin/main') : '';
+    if (merged && merged !== head) {
+      warnings.push(`base=${base} 가 HEAD 와 같은 커밋 — origin/main (${main})과 달라 merge-base 로 재계산`);
+      base = merged;
+      baseSource = 'recomputed merge-base(origin/main)';
+    } else if (main && main !== head) {
+      failures.push({ command: `git rev-parse ${base}`, why: `base 가 HEAD(${head}) 와 같아 변경을 셀 수 없다 — TSC_BASE_REF 로 base 를 주라 (못 셌음 ≠ 0)` });
+    }
+  }
+
+  const files = new Set<string>();
+  const diffFiles = new Set<string>();
+  const commands = [`git diff --name-only ${base}...HEAD`, 'git diff --name-only HEAD', 'git ls-files --others --exclude-standard'];
+  for (const command of commands) {
+    try {
+      for (const line of run(command).split('\n')) {
+        const file = line.trim().replace(/^\.\//, '');
+        if (!file) continue;
+        const ts = /\.tsx?$/.test(file);
+        // A deleted .ts is not a compile candidate, so it must not count as «should have been collected».
+        if (!ts || existsSync(file)) diffFiles.add(file);
+        if (ts && existsSync(file)) files.add(file);
+      }
+    } catch (cause) {
       failures.push({ command, why: cause instanceof Error ? cause.message : String(cause) });
     }
-  };
-  addCommand(`git diff --name-only ${base}...HEAD`);
-  addCommand('git diff --name-only HEAD');
-  addCommand('git ls-files --others --exclude-standard');
-  return { files, base, baseSource, failures };
+  }
+  return { files, base, baseSource, head, diffFiles, warnings, failures };
 }
 
 type RequiredExportField = { typeName: string; fieldName: string };
@@ -850,10 +871,13 @@ export function runGate(io: Partial<GateIo> = {}): void {
     ? { additions: [] }
     : exportedLiteralUnionMembersInChanges(changed, base));
   const changedResult = getChanged();
-  const { files: changed, base, baseSource, failures = [] } = changedResult instanceof Set
-    ? { files: changedResult, base: 'injected test seam', baseSource: 'injected test seam', failures: [] }
+  const { files: changed, base, baseSource, head, diffFiles, warnings = [], failures = [] } = changedResult instanceof Set
+    ? { files: changedResult, base: 'injected test seam', baseSource: 'injected test seam', head: 'injected test seam', diffFiles: new Set<string>(), warnings: [], failures: [] }
     : changedResult;
-  log(`[tsc-gate] base=${base} (${baseSource}); 변경 .ts ${changed.size}개 관측.`);
+  for (const message of warnings) warn(`[tsc-gate] ⚠ ${message}`);
+  const diffCount = diffFiles?.size;
+  const diffTsCount = diffFiles && [...diffFiles].filter((file) => /\.tsx?$/.test(file)).length;
+  log(`[tsc-gate] base=${base} (${baseSource}); 변경 .ts ${changed.size}개 관측. (head=${head ?? 'unknown'} · 전체 diff 파일 ${diffCount ?? 'unknown'}개 · diff .ts ${diffTsCount ?? 'unknown'}개)`);
   if (failures.length > 0) {
     error('[tsc-gate] ⛔ 변경 파일 수집 실패:');
     for (const { command, why } of failures) error(`  ${command}: ${why}`);
@@ -861,7 +885,15 @@ export function runGate(io: Partial<GateIo> = {}): void {
     exit(1);
     return;
   }
-  if (changed.size === 0) { log('[tsc-gate] 변경된 .ts 파일 없음 — 위 base 기준 0개이며 tsc 실행 없이 통과.'); return; }
+  if (changed.size === 0) {
+    if (!(changedResult instanceof Set) && (!head || diffCount === undefined || diffTsCount === undefined || diffTsCount > 0)) {
+      error(`[tsc-gate] FAIL — 변경 파일 수집 불일치: 전체 diff 파일 ${diffCount ?? 'unknown'}개 · diff .ts ${diffTsCount ?? 'unknown'}개 · 수집 .ts 0개 (못 셌음 ≠ 0).`);
+      exit(1);
+      return;
+    }
+    log(`[tsc-gate] PASS — 변경된 .ts 파일 없음 · base=${base} · head=${head} · 전체 diff 파일 ${diffCount}개 · diff .ts ${diffTsCount}개 · 수집 .ts 0개; tsc 실행 없이 통과.`);
+    return;
+  }
   const fieldCheck = requiredExportFields(changed, base);
   const requiredFields = Array.isArray(fieldCheck) ? fieldCheck : fieldCheck.fields;
   if (!Array.isArray(fieldCheck) && fieldCheck.failure) {

package/scripts/docs/generate-graph-anatomy.ts

@@ -0,0 +1,315 @@
+#!/usr/bin/env bun
+/**
+ * DOC-GEN① — 그래프 아나토미를 코드에서 생성한다.
+ *
+ * 원천은 둘뿐이다.
+ *   노드 종류 = src/graph-kinds/registry.ts (HARNESS_CORE_KINDS · WORKFLOW_CORE_KINDS · listNodeKinds)
+ *   그래프     = graphs/ YAML 을 src/self-implement/graph-yaml.ts 의 loadGraphTemplates · edgeMapOf 가 읽는다
+ *
+ * renderGraphAnatomy 는 순수하다 — 파일을 쓰지 않고 process.cwd() 를 읽지 않는다.
+ * 뿌리·커밋·시각은 인자로만 받는다. main 만 내부 문서 `graph-anatomy` 에 쓴다.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { listNodeKinds, type GraphKind, type NodeKindEntry } from '../../src/graph-kinds/registry.js';
+import {
+  edgeMapOf,
+  loadGraphTemplates,
+  parseGraphTemplateYaml,
+  type GraphLoadResult,
+  type GraphParseIssue,
+  type GraphTemplateSpec,
+} from '../../src/self-implement/graph-yaml.js';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+/** drafts/ · overlays/ 는 스캔에서 뺀다(실측 10-05). 그 이름인 디렉터리와 그 아래는 안 읽는다. */
+const EXCLUDED_DIR_NAMES = new Set(['drafts', 'overlays']);
+
+export interface RenderGraphAnatomyInput {
+  readonly graphsRoot: string;
+  readonly commit: string;
+  readonly generatedAt: string;
+}
+
+export interface ScannedGraphDir {
+  /** graphsRoot 기준 상대 경로. 뿌리 자신은 '.' */
+  readonly dir: string;
+  readonly result: GraphLoadResult;
+}
+
+function cell(value: string): string {
+  return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+
+function edgeCountOf(template: GraphTemplateSpec): number {
+  return Object.values(edgeMapOf(template)).reduce((sum, targets) => sum + targets.length, 0);
+}
+
+function edgeLinesOf(template: GraphTemplateSpec): string[] {
+  const lines: string[] = [];
+  for (const edge of template.edges) {
+    if (edge.to !== undefined) lines.push(`${edge.from} → ${edge.to}`);
+    for (const [key, target] of Object.entries(edge.map ?? {})) lines.push(`${edge.from} → ${target} (${key})`);
+    for (const fallback of edge.fallback ?? []) lines.push(`${edge.from} → ${fallback.node} (fallback)`);
+  }
+  return lines;
+}
+
+/**
+ * A directory with recipes.yaml holds workflow graphs run by `elanous graph run` (src/graph-runner/runner.ts), not
+ * harness templates. The runner gives a recipe-less node (done · failed) `recipe: 'none'` before the shared parser
+ * (runner.ts «command-less node … represented internally as `none`»); read those graphs the same way, and do not
+ * read recipes.yaml itself as a graph.
+ */
+function isRunnerDir(abs: string): boolean { return existsSync(join(abs, 'recipes.yaml')); }
+
+function parseLikeRunner(source: string, label: string): ReturnType<typeof parseGraphTemplateYaml> {
+  let raw: unknown;
+  try { raw = parseYaml(source); } catch { return parseGraphTemplateYaml(source, label); }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return parseGraphTemplateYaml(source, label);
+  const document = raw as Record<string, unknown>;
+  if (Array.isArray(document.nodes)) {
+    document.nodes = document.nodes.map((node: unknown) => node && typeof node === 'object' && !Array.isArray(node) && !('recipe' in node)
+      ? { ...node, recipe: 'none' } : node);
+  }
+  return parseGraphTemplateYaml(stringifyYaml(document), label);
+}
+
+function graphFileNames(abs: string): string[] {
+  const runner = isRunnerDir(abs);
+  return readdirSync(abs).filter((name) => (name.endsWith('.yaml') || name.endsWith('.yml')) && !(runner && name === 'recipes.yaml')).sort();
+}
+
+/** loadGraphTemplates for harness dirs; the runner's reading for workflow-graph dirs (same result shape). */
+function loadDir(abs: string): GraphLoadResult {
+  if (!isRunnerDir(abs)) return loadGraphTemplates(abs);
+  const errors: GraphParseIssue[] = [];
+  const warnings: GraphParseIssue[] = [];
+  const templates: Record<string, GraphTemplateSpec> = {};
+  let files: string[];
+  try { files = graphFileNames(abs); }
+  catch (error) { return { templates, errors: [{ path: abs, message: `그래프 디렉토리를 못 읽었다: ${String(error)}` }], warnings, scannedFiles: 0 }; }
+  for (const file of files) {
+    let source: string;
+    try { source = readFileSync(join(abs, file), 'utf8'); }
+    catch (error) { errors.push({ path: file, message: `읽기 실패: ${String(error)}` }); continue; }
+    const result = parseLikeRunner(source, file);
+    errors.push(...result.errors);
+    warnings.push(...result.warnings);
+    if (!result.template) continue;
+    if (templates[result.template.graphId]) { errors.push({ path: file, message: `graph_id '${result.template.graphId}' 가 중복이다` }); continue; }
+    templates[result.template.graphId] = result.template;
+  }
+  return { templates, errors, warnings, scannedFiles: files.length };
+}
+
+/** 뿌리와 하위 디렉터리를 돈다. drafts/ · overlays/ 와 그 아래는 제외. 디렉터리마다 loadGraphTemplates 를 그대로 부른다. */
+export function scanGraphDirs(graphsRoot: string): ScannedGraphDir[] {
+  const scanned: ScannedGraphDir[] = [];
+  const visit = (dir: string): void => {
+    scanned.push({ dir: relative(graphsRoot, dir) || '.', result: loadDir(dir) });
+    let names: string[];
+    try {
+      names = readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !EXCLUDED_DIR_NAMES.has(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+    } catch {
+      return;
+    }
+    for (const name of names) visit(join(dir, name));
+  };
+  visit(graphsRoot);
+  return scanned;
+}
+
+/**
+ * loadGraphTemplates 는 파일명을 템플릿에 안 남긴다.
+ * 같은 디렉터리 yaml 을 parseGraphTemplateYaml 로 한 번씩 읽어 graph_id → 상대 경로를 붙인다.
+ * 파싱에 실패한 파일은 표에 안 들어가므로 맵에도 안 넣는다.
+ */
+/** 그 디렉터리에서 loadGraphTemplates 가 센 yaml 이름. 못 읽으면 빈 목록. */
+function yamlNames(graphsRoot: string, dir: string): readonly string[] {
+  const abs = dir === '.' ? graphsRoot : join(graphsRoot, dir);
+  try {
+    return graphFileNames(abs);
+  } catch {
+    return [];
+  }
+}
+
+function graphIdPaths(graphsRoot: string, dir: string): ReadonlyMap<string, string> {
+  const abs = dir === '.' ? graphsRoot : join(graphsRoot, dir);
+  const prefix = dir === '.' ? '' : `${dir}/`;
+  const paths = new Map<string, string>();
+  let names: string[];
+  try {
+    names = graphFileNames(abs);
+  } catch {
+    return paths;
+  }
+  for (const name of names) {
+    let source: string;
+    try { source = readFileSync(join(abs, name), 'utf8'); }
+    catch { continue; }
+    const parsed = isRunnerDir(abs) ? parseLikeRunner(source, name) : parseGraphTemplateYaml(source, name);
+    if (!parsed.template) continue;
+    const rel = `${prefix}${name}`;
+    const prev = paths.get(parsed.template.graphId);
+    paths.set(parsed.template.graphId, prev === undefined ? rel : `${prev}, ${rel}`);
+  }
+  return paths;
+}
+
+function kindRows(entries: readonly NodeKindEntry[]): string[] {
+  return [...entries]
+    .sort((a, b) => (a.graph < b.graph ? -1 : a.graph > b.graph ? 1 : a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0))
+    .map((entry) => `| ${cell(entry.graph)} | ${cell(entry.kind)} | ${entry.core ? 'core' : 'plugin'} |`);
+}
+
+function issueLines(label: string, issues: readonly GraphParseIssue[]): string[] {
+  if (issues.length === 0) return [`- ${label}: 0`];
+  return [`- ${label}: ${issues.length}`, ...issues.map((issue) => `  - ${cell(issue.path)} — ${issue.message}`)];
+}
+
+/**
+ * 마크다운 한 장. 파일을 쓰지 않는다. graphsRoot · commit · generatedAt 만 읽는다.
+ */
+export function renderGraphAnatomy(input: RenderGraphAnatomyInput): string {
+  const scanned = scanGraphDirs(input.graphsRoot);
+  const templates: { dir: string; fileLabel: string; template: GraphTemplateSpec }[] = [];
+  for (const { dir, result } of scanned) {
+    for (const template of Object.values(result.templates)) {
+      templates.push({ dir, fileLabel: dir === '.' ? `${template.graphId}` : `${dir}/${template.graphId}`, template });
+    }
+  }
+  templates.sort((a, b) => (a.template.graphId < b.template.graphId ? -1 : a.template.graphId > b.template.graphId ? 1 : a.dir < b.dir ? -1 : 1));
+
+  const scannedFiles = scanned.reduce((sum, entry) => sum + entry.result.scannedFiles, 0);
+  const missingDirs = scanned.filter((entry) =>
+    entry.result.scannedFiles === 0
+    && entry.result.errors.some((issue) => issue.message.startsWith('그래프 디렉토리를 못 읽었다')),
+  );
+
+  const lines: string[] = [
+    '# Graph anatomy',
+    '',
+    '> 이 문서는 생성물이다 — 손으로 고치지 마라',
+    '',
+    `- generatedAt: ${input.generatedAt}`,
+    `- commit: ${input.commit}`,
+    `- graphsRoot: (인자)`,
+    `- scannedFiles: ${scannedFiles}`,
+    `- scannedDirs: ${scanned.length}`,
+    `- templates: ${templates.length}`,
+    '',
+    '## 표 1 노드 종류',
+    '',
+    '원천: `src/graph-kinds/registry.ts` — `HARNESS_CORE_KINDS` · `WORKFLOW_CORE_KINDS` · `listNodeKinds()`.',
+    '',
+    '| graph | kind | core/plugin |',
+    '| --- | --- | --- |',
+    ...kindRows(listNodeKinds()),
+    '',
+    '## 표 2 그래프',
+    '',
+    '원천: `loadGraphTemplates(dir)` ⊕ `edgeMapOf(template)`. 간선 수는 edgeMapOf 합(to · map · fallback, 중복 목적지는 한 번). `drafts/` · `overlays/` 는 제외.',
+    '',
+    '| 파일 경로 | graph_id | 노드 수 | 간선 수 | entryNode | terminalNodes |',
+    '| --- | --- | --- | --- | --- | --- |',
+  ];
+
+  if (templates.length === 0) {
+    lines.push('| (없음) | — | 0 | 0 | — | — |');
+  }
+  const pathCache = new Map<string, ReadonlyMap<string, string>>();
+  for (const { dir, template } of templates) {
+    let paths = pathCache.get(dir);
+    if (paths === undefined) {
+      paths = graphIdPaths(input.graphsRoot, dir);
+      pathCache.set(dir, paths);
+    }
+    const where = paths.get(template.graphId) ?? (dir === '.' ? `${template.graphId}.yaml` : `${dir}/`);
+    lines.push(`| ${cell(where)} | ${cell(template.graphId)} | ${template.nodes.length} | ${edgeCountOf(template)} | ${cell(template.entryNode)} | ${cell(template.terminalNodes.join(', '))} |`);
+  }
+
+  lines.push('', '## 그래프별 노드 · 간선', '');
+  if (templates.length === 0) lines.push('(읽힌 그래프 없음)', '');
+  for (const { dir, template } of templates) {
+    const where = dir === '.' ? '(graphs root)' : dir;
+    lines.push(`### ${template.graphId}`, '', `- path: ${where}`, '', '#### 노드', '', '| nodeId | kind |', '| --- | --- |');
+    for (const node of template.nodes) lines.push(`| ${cell(node.nodeId)} | ${cell(node.kind)} |`);
+    lines.push('', '#### 간선', '');
+    const edges = edgeLinesOf(template);
+    if (edges.length === 0) lines.push('(간선 없음)');
+    else for (const edge of edges) lines.push(`- ${edge}`);
+    lines.push('');
+  }
+
+  lines.push('## 스캔한 파일', '');
+  lines.push('loadGraphTemplates 가 센 yaml. 파싱에 실패한 파일은 표 2에 없고 여기와 오류 절에만 있다.', '');
+  lines.push('| 디렉터리 | 파일 |', '| --- | --- |');
+  for (const { dir } of scanned) {
+    const names = yamlNames(input.graphsRoot, dir);
+    const prefix = dir === '.' ? '' : `${dir}/`;
+    if (names.length === 0) {
+      lines.push(`| ${cell(dir === '.' ? '(graphs root)' : dir)} | (yaml 0) |`);
+      continue;
+    }
+    for (const name of names) lines.push(`| ${cell(dir === '.' ? '(graphs root)' : dir)} | ${cell(`${prefix}${name}`)} |`);
+  }
+  lines.push('', '## 로드 오류 · 경고 · scannedFiles', '');
+  lines.push(`scannedFiles 합: ${scannedFiles}`, '');
+  if (missingDirs.length > 0) {
+    lines.push('디렉토리 없음 (0개 읽음과 구분):', '');
+    for (const entry of missingDirs) {
+      for (const issue of entry.result.errors) lines.push(`- ${cell(issue.path)} — ${issue.message}`);
+    }
+    lines.push('');
+  }
+  for (const { dir, result } of scanned) {
+    const label = dir === '.' ? '(graphs root)' : dir;
+    const unreadable = result.scannedFiles === 0 && result.errors.some((issue) => issue.message.startsWith('그래프 디렉토리를 못 읽었다'));
+    lines.push(`### ${label}`, '');
+    lines.push(`- scannedFiles: ${result.scannedFiles}${unreadable ? ' (디렉토리 없음)' : result.scannedFiles === 0 ? ' (0개 읽음)' : ''}`);
+    lines.push(...issueLines('errors', result.errors));
+    lines.push(...issueLines('warnings', result.warnings));
+    lines.push('');
+  }
+
+  const axes: GraphKind[] = ['harness', 'workflow'];
+  lines.push('## 축별 종류 수', '');
+  for (const axis of axes) lines.push(`- ${axis}: ${listNodeKinds(axis).length}`);
+  lines.push('');
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`;
+}
+
+function repoRootFromHere(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+function readCommit(repoRoot: string): string {
+  return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' }).trim();
+}
+
+export function defaultOutputPath(repoRoot: string): string {
+  return join(repoRoot, 'docs', 'generated', 'graph-anatomy.md');
+}
+
+function main(): void {
+  const repoRoot = repoRootFromHere();
+  const graphsRoot = join(repoRoot, 'graphs');
+  const generatedAt = new Date().toISOString();
+  const commit = readCommit(repoRoot);
+  const markdown = renderGraphAnatomy({ graphsRoot, commit, generatedAt });
+  const out = defaultOutputPath(repoRoot);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, markdown);
+  process.stdout.write(`${out}\n`);
+}
+
+if (import.meta.main) main();

package/scripts/expose-rubric-suggest.ts

@@ -5,7 +5,7 @@ import { spawnSync } from 'node:child_process';
 import { join, relative, resolve, sep } from 'node:path';
 import { stringify } from 'yaml';
 import { debug } from '../src/debug/log.js';
-import { checkBrand } from './brand/check.js';
+import { BRAND_RULES_UNMEASURED, checkBrand } from './brand/check.js';
 import { checkCommands, extractElanousCommands, type HelpRunner } from './docs-cli-check.js';
 import { scanLeaks } from './public-export.js';
 
@@ -25,7 +25,7 @@ function measure(run: () => Criterion): Criterion {
 }
 
 /** Files are repository-relative paths (or absolute paths within root); the ledger is never read or written. */
-export function suggestExposeRubric(root: string, files?: readonly string[], help?: HelpRunner): Suggestion[] {
+export function suggestExposeRubric(root: string, files?: readonly string[], help?: HelpRunner, rulesPath?: string): Suggestion[] {
   const names = files ?? readdirSync(join(root, DOCS)).filter((name) => name.endsWith('.md')).map((name) => `${DOCS}/${name}`);
   const paths = [...new Set(names.map((name) => relative(root, resolve(root, name)).split(sep).join('/')))];
   if (paths.some((path) => !/^release\/public\/docs\/[^/]+\.md$/.test(path))) throw new Error('문서 경로는 release/public/docs/*.md 이어야 합니다');
@@ -77,6 +77,15 @@ export function suggestExposeRubric(root: string, files?: readonly string[], hel
       const failed = unmeasured(error);
       return { path, criteria: { reproducible: failed, confidential: failed, brand: failed } };
     }
+    const brand = measure(() => {
+      const result = checkBrand('public-docs', [absolute], rulesPath);
+      if (result.missing) return { status: 'n/a', reason: result.message ?? BRAND_RULES_UNMEASURED };
+      if (result.files !== 1 || result.rules === 0) return unmeasured('브랜드 규칙 없음 또는 파일 검사 실패');
+      const ids = [...new Set(result.findings.map((finding) => finding.id))].slice(0, 3);
+      return ids.length
+        ? { status: 'fail', reason: `브랜드 규칙: ${ids.join(', ')}` }
+        : { status: 'pass', reason: '브랜드 규칙 위반 없음' };
+    });
     const reproducible = measure(() => {
       const refs = extractElanousCommands(path, text);
       if (!refs.length) return { status: 'n/a', reason: '문서에 elanous 명령 없음' };
@@ -95,14 +104,7 @@ export function suggestExposeRubric(root: string, files?: readonly string[], hel
         ? { status: 'fail', reason: `누출 표식: ${markers.join(', ')}` }
         : { status: 'pass', reason: '누출 표식 없음' };
     });
-    const brand = measure(() => {
-      const result = checkBrand('public-docs', [absolute]);
-      if (result.missing || result.files !== 1 || result.rules === 0) return unmeasured('브랜드 규칙 없음 또는 파일 검사 실패');
-      const ids = [...new Set(result.findings.map((finding) => finding.id))].slice(0, 3);
-      return ids.length
-        ? { status: 'fail', reason: `브랜드 규칙: ${ids.join(', ')}` }
-        : { status: 'pass', reason: '브랜드 규칙 위반 없음' };
-    });
+    // 브랜드 규칙이 없으면 브랜드만 «측정 불가» — 따로 잰 재현성·누출 결과는 덮어쓰지 않는다.
     return { path, criteria: { reproducible, confidential, brand } };
   });
   const statuses = results.flatMap((item) => KEYS.map((key) => item.criteria[key].status));
@@ -119,19 +121,23 @@ export function run(argv: readonly string[], root = process.cwd(), help?: HelpRu
   const json = argv.includes('--json');
   let files: string[] | undefined;
   let out: string | undefined;
+  let rulesPath: string | undefined;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]!;
     if (arg === '--json') continue;
     if (arg === '--yaml-patch') {
       out = argv[++i];
       if (!out || out.startsWith('--')) throw new Error('--yaml-patch 에 출력 경로가 필요합니다');
+    } else if (arg === '--rules') {
+      rulesPath = argv[++i];
+      if (!rulesPath || rulesPath.startsWith('--')) throw new Error('--rules 에 규칙 경로가 필요합니다');
     } else if (arg === '--files') {
       files = [];
       while (argv[i + 1] && !argv[i + 1]!.startsWith('--')) files.push(argv[++i]!);
       if (!files.length) throw new Error('--files 에 문서 경로가 필요합니다');
     } else throw new Error(`알 수 없는 옵션: ${arg}`);
   }
-  const results = suggestExposeRubric(root, files, help);
+  const results = suggestExposeRubric(root, files, help, rulesPath);
   if (out) {
     const target = resolve(root, out);
     const ledger = resolve(root, LEDGER);
@@ -140,7 +146,7 @@ export function run(argv: readonly string[], root = process.cwd(), help?: HelpRu
   }
   if (json) console.log(JSON.stringify(results));
   else {
-    for (const { path, criteria } of results) console.log(`${path} · ${KEYS.map((key) => `${key} ${criteria[key].status}${criteria[key].status === 'fail' ? `(${criteria[key].reason.split(': ').slice(1).join(': ') || criteria[key].reason})` : ''}`).join(' · ')}`);
+    for (const { path, criteria } of results) console.log(`${path} · ${KEYS.map((key) => `${key} ${criteria[key].status}${criteria[key].status === 'fail' ? `(${criteria[key].reason.split(': ').slice(1).join(': ') || criteria[key].reason})` : criteria[key].reason === BRAND_RULES_UNMEASURED ? `(${criteria[key].reason})` : ''}`).join(' · ')}`);
     const statuses = results.flatMap((item) => KEYS.map((key) => item.criteria[key].status));
     console.log(`합계 문서 ${results.length} · pass ${statuses.filter((status) => status === 'pass').length} · fail ${statuses.filter((status) => status === 'fail').length} · n/a ${statuses.filter((status) => status === 'n/a').length} · maturity/value/evidence/support 사람 판정 (MK)`);
   }

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) : '반증 없음 — 승격 불가'}`);