elanous 0.2.13 → 0.2.15

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/docs-cli-check.ts

@@ -2,7 +2,7 @@
 // 공개 문서에 적힌 `elanous …` 명령·하위 명령·플래그가 «실제 CLI» 에 있나 — 문서가 실제와 어긋나는 1순위 원인을 잡는다.
 //   bun scripts/docs-cli-check.ts [--json] [files…]      (기본 = release/public/내부 문서 `*` ⊕ README.md)
 // 🩸 계기(2026-09-25 🅢 RFC 피드백 ③): README·install.md 가 거짓이 된 원인이 전부 «설치기·doctor 가 바뀌었는데 문서가 모름»이었다.
-// 자 = `bun bin/elanous.mjs <cmd> [<sub>] --help` 산출(원천) — 문서의 코드 블록과 인라인 코드에서 `elanous ` 로 시작하는 것만 본다.
+// 자 = `bun bin/elanous.mjs <cmd> [<sub>] [<subsub>] --help` 산출(원천) — 문서의 코드 블록과 인라인 코드에서 `elanous ` 로 시작하는 것만 본다.
 // ⛔ 못 본 것은 «없다»로 적지 않는다: `--help` 가 실패하면 그 명령은 `unmeasured` 로 따로 센다.
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
@@ -10,7 +10,7 @@ import { spawnSync } from 'node:child_process';
 
 const REPO = resolve(import.meta.dir, '..');
 
-export interface DocCommand { file: string; line: number; text: string; cmd: string; sub?: string; flags: string[] }
+export interface DocCommand { file: string; line: number; text: string; cmd: string; sub?: string; subsub?: string; flags: string[] }
 export interface Finding { kind: 'unknown-command' | 'unknown-subcommand' | 'unknown-flag' | 'unmeasured'; ref: DocCommand; detail: string }
 
 /** 코드 블록(``` … ```) 줄과 인라인 코드(`elanous …`)에서 elanous 호출을 뽑는다. 자리표(`<x>`)·셸 변수는 인자로 보고 넘긴다. */
@@ -24,15 +24,17 @@ export function extractElanousCommands(file: string, text: string): DocCommand[]
     for (const m of raw.matchAll(/`(elanous [^`]+)`/g)) candidates.push(m[1]!);
     for (const c of candidates) {
       for (const seg of c.split(/&&|\|\||;|\|/)) {
-        const m = /(?:^|\s)elanous\s+(.+)$/.exec(seg.trim());
+        const m = /^(?:(?:\$\s+|>\s+|sudo\s+|[A-Za-z_][A-Za-z0-9_]*=\S+\s+))*elanous\s+(.+)$/.exec(seg.trim());
         if (!m) continue;
         const tokens = m[1]!.trim().split(/\s+/).filter(Boolean);
         const cmd = tokens[0];
         if (!cmd || !/^[a-z][a-z0-9:-]*$/.test(cmd)) continue;
         const second = tokens[1];
         const sub = second && /^[a-z][a-z0-9-]*$/.test(second) ? second : undefined;
+        const third = tokens[2];
+        const subsub = sub && third && /^[a-z][a-z0-9-]*$/.test(third) ? third : undefined;
         const flags = tokens.filter((t) => /^--[a-z]/.test(t)).map((t) => t.replace(/[=,.)].*$/, ''));
-        out.push({ file, line: i + 1, text: seg.trim(), cmd, ...(sub ? { sub } : {}), flags });
+        out.push({ file, line: i + 1, text: seg.trim(), cmd, ...(sub ? { sub } : {}), ...(subsub ? { subsub } : {}), flags });
       }
     }
   });
@@ -63,13 +65,28 @@ export function checkCommands(refs: readonly DocCommand[], help: HelpRunner = de
     const cmdHelp = get([ref.cmd]);
     if (!cmdHelp.ok) { findings.push({ kind: 'unmeasured', ref, detail: `elanous ${ref.cmd} --help 실패` }); continue; }
     let flagsHelp = cmdHelp.out;
+    let flagsPath = `elanous ${ref.cmd}`;
     if (ref.sub && /\nCommands:\n/.test(cmdHelp.out)) {
       if (!listed(cmdHelp.out, ref.sub)) { findings.push({ kind: 'unknown-subcommand', ref, detail: `elanous ${ref.cmd} ${ref.sub}` }); continue; }
+      flagsPath = `elanous ${ref.cmd} ${ref.sub}`;
       const subHelp = get([ref.cmd, ref.sub]);
-      if (subHelp.ok) flagsHelp = subHelp.out;
+      if (!subHelp.ok) {
+        findings.push({ kind: 'unmeasured', ref, detail: `${flagsPath} --help 실패` });
+        continue;
+      }
+      flagsHelp = subHelp.out;
+      if (ref.subsub && listed(subHelp.out, ref.subsub)) {
+        flagsPath += ` ${ref.subsub}`;
+        const subsubHelp = get([ref.cmd, ref.sub, ref.subsub]);
+        if (!subsubHelp.ok) {
+          findings.push({ kind: 'unmeasured', ref, detail: `${flagsPath} --help 실패` });
+          continue;
+        }
+        flagsHelp = subsubHelp.out;
+      }
     }
     for (const f of ref.flags) {
-      if (!new RegExp(`(^|[\\s,])${f}(\\b|[\\s,=<\\[])`, 'm').test(flagsHelp)) findings.push({ kind: 'unknown-flag', ref, detail: `${f} (elanous ${ref.cmd}${ref.sub ? ` ${ref.sub}` : ''})` });
+      if (!new RegExp(`(^|[\\s,])${f}(\\b|[\\s,=<\\[])`, 'm').test(flagsHelp)) findings.push({ kind: 'unknown-flag', ref, detail: `${f} (${flagsPath})` });
     }
   }
   return findings;

package/scripts/expose-rubric-check.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env bun
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { parse } from 'yaml';
+import { debug } from '../src/debug/log.js';
+
+const DOCS = 'release/public/docs';
+const LEDGER = 'release/public/expose-rubric.yaml';
+const CRITERIA = ['maturity', 'value', 'reproducible', 'evidence', 'confidential', 'brand', 'support'] as const;
+type Criterion = { status: 'pass' | 'fail' | 'n/a'; reason: string };
+type Entry = {
+  path: string;
+  verdict: 'public' | 'beta' | 'internal';
+  criteria: Record<(typeof CRITERIA)[number], Criterion>;
+  judge: string;
+  techReview?: string;
+  at: string;
+};
+type RubricResult = { docs: number; missing: string[]; orphan: string[]; failing: Array<{ path: string; criteria: string[]; verdict?: 'beta' }>; internal: string[]; unreviewed: string[]; unjudged: string[] };
+
+function validEntry(value: unknown): value is Entry {
+  if (!value || typeof value !== 'object') return false;
+  const entry = value as Partial<Entry>;
+  if (typeof entry.path !== 'string' || !/^release\/public\/docs\/[^/]+\.md$/.test(entry.path)
+    || !['public', 'beta', 'internal'].includes(entry.verdict ?? '')
+    // The exposure judge is the CMO seat (EXPOSE-RUBRIC); any other non-empty name is not a judgement.
+    || entry.judge !== 'MK'
+    || (entry.techReview !== undefined && (typeof entry.techReview !== 'string' || !entry.techReview.trim()))
+    || typeof entry.at !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(entry.at)
+    || !Number.isFinite(Date.parse(entry.at)) || !entry.criteria || typeof entry.criteria !== 'object') return false;
+  const criteria = entry.criteria as Record<string, unknown>;
+  if (Object.keys(criteria).length !== CRITERIA.length) return false;
+  return CRITERIA.every((key) => {
+    const item = criteria[key] as Partial<Criterion> | undefined;
+    return item && ['pass', 'fail', 'n/a'].includes(item.status ?? '')
+      && typeof item.reason === 'string' && !!item.reason.trim() && !item.reason.includes('\n');
+  });
+}
+
+function selectedPath(input: string, root: string): string | undefined {
+  const path = relative(root, resolve(root, input)).split(sep).join('/');
+  return /^release\/public\/docs\/[^/]+\.md$/.test(path) ? path : undefined;
+}
+
+export function checkExposeRubric(root: string, files?: readonly string[]): RubricResult {
+  const data = parse(readFileSync(join(root, LEDGER), 'utf8')) as unknown;
+  if (!data || typeof data !== 'object' || !('entries' in data) || !Array.isArray(data.entries)) throw new Error(`invalid ledger: ${LEDGER}`);
+  const entries = new Map<string, Entry>();
+  for (const value of data.entries as unknown[]) {
+    if (!validEntry(value) || entries.has(value.path)) throw new Error(`invalid or duplicate ledger entry: ${JSON.stringify(value)}`);
+    entries.set(value.path, value);
+  }
+  const scope = files === undefined ? undefined : new Set(files.map((file) => selectedPath(file, root)).filter((path): path is string => path !== undefined));
+  const docs = readdirSync(join(root, DOCS)).filter((name) => name.endsWith('.md'))
+    .map((name) => `${DOCS}/${name}`).filter((path) => !scope || scope.has(path)).sort();
+  const missing = docs.filter((path) => !entries.has(path));
+  const orphan: string[] = [];
+  const failing: RubricResult['failing'] = [];
+  const internal: string[] = [];
+  const unreviewed: string[] = [];
+  const unjudged: string[] = [];
+  for (const entry of entries.values()) {
+    if (scope && !scope.has(entry.path)) continue;
+    if (!existsSync(join(root, entry.path))) {
+      orphan.push(entry.path);
+      continue;
+    }
+    if (entry.verdict === 'internal') internal.push(entry.path);
+    if (entry.verdict === 'public' || entry.verdict === 'beta') {
+      const failed = entry.verdict === 'public'
+        ? CRITERIA.filter((key) => entry.criteria[key].status === 'fail')
+        : (entry.criteria.confidential.status === 'fail' ? ['confidential'] : []);
+      if (failed.length) failing.push({ path: entry.path, criteria: failed, ...(entry.verdict === 'beta' ? { verdict: 'beta' as const } : {}) });
+      if (entry.verdict === 'public' && entry.techReview !== 'TC') unreviewed.push(entry.path);
+      // An outward verdict with no criterion actually passed is a placeholder, not a judgement (all n/a = never checked).
+      if (!CRITERIA.some((key) => entry.criteria[key].status === 'pass')) unjudged.push(entry.path);
+    }
+  }
+  orphan.sort();
+  failing.sort((a, b) => a.path.localeCompare(b.path));
+  internal.sort();
+  unreviewed.sort();
+  unjudged.sort();
+  const result = { docs: docs.length, missing, orphan, failing, internal, unreviewed, unjudged };
+  debug.log('expose.rubric', 'checked', { docs: result.docs, missing: missing.length, orphan: orphan.length, failing: failing.length, unjudged: unjudged.length });
+  return result;
+}
+
+if (import.meta.main) {
+  try {
+    const args = process.argv.slice(2);
+    if (args.includes('--help')) {
+      console.log('Usage: bun scripts/expose-rubric-check.ts [--strict] [--json] [--files <path...>]');
+    } else {
+      const options = new Set(['--strict', '--json', '--files']);
+      const index = args.indexOf('--files');
+      const beforeFiles = args.slice(0, index < 0 ? args.length : index);
+      const files = index < 0 ? undefined : args.slice(index + 1);
+      if (beforeFiles.some((arg) => !options.has(arg) || arg === '--files')
+        || (files && (!files.length || files.some((file) => file.startsWith('--'))))) throw new Error('invalid arguments: use --files <path...> last');
+      const result = checkExposeRubric(process.cwd(), files);
+      if (args.includes('--json')) console.log(JSON.stringify(result));
+      else {
+        for (const path of result.missing) console.error(`경고: 원장 없음: ${path}`);
+        for (const path of result.orphan) console.error(`경고: 파일 없음: ${path}`);
+        for (const item of result.failing) console.error(`경고: ${item.verdict ?? 'public'} 인데 fail (${item.criteria.join(', ')}): ${item.path}`);
+        for (const path of result.internal) console.error(`경고: internal 인데 공개 경로: ${path}`);
+        for (const path of result.unreviewed) console.error(`경고: public 기술 정확성 TC 미검토: ${path}`);
+        for (const path of result.unjudged) console.error(`경고: 미판정(일곱 기준 중 pass 0): ${path}`);
+        console.error(`expose-rubric — docs=${result.docs} missing=${result.missing.length} orphan=${result.orphan.length} failing=${result.failing.length} internal=${result.internal.length} unreviewed=${result.unreviewed.length} unjudged=${result.unjudged.length}`);
+      }
+      if (args.includes('--strict') && (result.missing.length || result.orphan.length || result.failing.length || result.internal.length || result.unjudged.length)) process.exitCode = 1;
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+  }
+}