elanous 0.2.14 → 0.2.16

package/scripts/ci-public-export-import-gate.ts

@@ -0,0 +1,154 @@
+/**
+ * Public export import guard — a file the public export includes must not statically import
+ * a module the export excludes. 0.2.15 shipped that break: src/decisions/proact-meter.ts
+ * imported src/directives/directive-index (exclude `src/directives/directive-index*`) and the
+ * export-check PWA build failed.
+ *
+ *   bun scripts/ci-public-export-import-gate.ts --changed-files a b …   # exit 1 on a hit · 0 when clean
+ *
+ * Only string-literal specifiers are resolved. Non-literal specifiers (createRequire with a
+ * concatenated string, and the like) are counted as unseen — this check cannot see them.
+ * The public PWA build itself stays on the release export-check run; it is not run here.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, posix, resolve } from 'node:path';
+type ExportSelectors = {
+  loadExportConfig: (root: string, file?: string) => { readonly include: readonly string[]; readonly exclude: readonly string[]; readonly replace: Readonly<Record<string, string>> };
+  selectExportFiles: (tracked: readonly string[], config: { readonly include: readonly string[]; readonly exclude: readonly string[]; readonly replace: Readonly<Record<string, string>> }) => string[];
+};
+
+/**
+ * scripts/public-export.ts `loadExportConfig` (line 123) and `selectExportFiles` (line 140).
+ * Imported on call, not at load: that module imports typescript, and a tree that has not
+ * installed it must still be able to load this gate and report why it could not measure.
+ */
+async function exportSelectors(): Promise<ExportSelectors> {
+  return import('./public-export.js');
+}
+
+export interface ExportImportHit {
+  readonly file: string;
+  readonly line: number;
+  readonly target: string;
+}
+
+export interface ExportImportCheck {
+  readonly measured: boolean;
+  readonly hits: readonly ExportImportHit[];
+  readonly unseen: number;
+  readonly detail?: string;
+}
+
+const CODE_FILE = /\.(?:[cm]?[jt]sx?)$/;
+const FROM_CLAUSE = /\b(?:import|export)\s+(?:type\s+)?(?:[^'"\n;]*?\s+from\s+)?(['"])([^'"\n]+)\1/g;
+const DYNAMIC_IMPORT = /\bimport\s*\(\s*(['"])([^'"\n]+)\1/g;
+const NON_LITERAL_IMPORT = /\b(?:import|require|createRequire)\s*\(\s*(?!['"`])/g;
+
+function trackedFiles(root: string): string[] | undefined {
+  const run = spawnSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf-8', timeout: 60_000, maxBuffer: 64 * 1024 * 1024 });
+  if (run.status !== 0) return undefined;
+  return String(run.stdout).split('\0').filter(Boolean);
+}
+
+/** Specifier resolved against the importer's directory, then mapped onto a repo-relative path. */
+function resolveSpecifier(importer: string, specifier: string): string | undefined {
+  if (!specifier.startsWith('.')) return undefined;
+  const raw = posix.normalize(posix.join(posix.dirname(importer), specifier));
+  return raw.startsWith('../') ? undefined : raw;
+}
+
+function candidatePaths(resolved: string): string[] {
+  const ext = posix.extname(resolved);
+  const bases = ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs'
+    ? [resolved.slice(0, -ext.length) + '.ts', resolved.slice(0, -ext.length) + '.tsx', resolved]
+    : [resolved];
+  const out: string[] = [];
+  for (const base of bases) {
+    out.push(base);
+    if (!posix.extname(base)) {
+      out.push(`${base}.ts`, `${base}.tsx`, `${base}.js`, `${base}.mjs`);
+      out.push(posix.join(base, 'index.ts'), posix.join(base, 'index.tsx'), posix.join(base, 'index.js'));
+    }
+  }
+  return out;
+}
+
+function lineOf(text: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text[i] === '\n') line++;
+  return line;
+}
+
+/**
+ * Changed files that the public manifest includes, scanned for a literal import of a tracked
+ * module that the same manifest leaves out. `unseen` counts non-literal import/require calls.
+ */
+export async function exportImportCheck(changedFiles: readonly string[], root: string): Promise<ExportImportCheck> {
+  const tracked = trackedFiles(root);
+  if (!tracked) return { measured: false, hits: [], unseen: 0, detail: 'git ls-files 실패' };
+  let included: Set<string>;
+  try {
+    const { loadExportConfig, selectExportFiles } = await exportSelectors();
+    included = new Set(selectExportFiles(tracked, loadExportConfig(root)));
+  } catch (error) {
+    return { measured: false, hits: [], unseen: 0, detail: error instanceof Error ? error.message : '매니페스트를 못 읽었다' };
+  }
+  const trackedSet = new Set(tracked);
+  const hits: ExportImportHit[] = [];
+  let unseen = 0;
+  for (const file of changedFiles) {
+    if (!included.has(file) || !CODE_FILE.test(file)) continue;
+    const abs = join(root, file);
+    if (!existsSync(abs)) continue;
+    let text: string;
+    try { text = readFileSync(abs, 'utf8'); } catch { continue; }
+    const seen = new Set<string>();
+    const consider = (index: number, specifier: string) => {
+      const resolvedSpec = resolveSpecifier(file, specifier);
+      if (!resolvedSpec) return;
+      const target = candidatePaths(resolvedSpec).find((candidate) => trackedSet.has(candidate));
+      if (!target || included.has(target)) return;
+      const key = `${index}\0${target}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      hits.push({ file, line: lineOf(text, index), target });
+    };
+    for (const pattern of [FROM_CLAUSE, DYNAMIC_IMPORT]) {
+      pattern.lastIndex = 0;
+      for (const match of text.matchAll(pattern)) consider(match.index ?? 0, match[2] ?? '');
+    }
+    NON_LITERAL_IMPORT.lastIndex = 0;
+    unseen += [...text.matchAll(NON_LITERAL_IMPORT)].length;
+  }
+  return { measured: true, hits, unseen };
+}
+
+/** Gate form: 1 on a hit, 0 when clean. An unmeasured check blocks only when a changed file is included. */
+export async function runPublicExportImportGate(io: { args: readonly string[]; cwd: string; log: (line: string) => void; error: (line: string) => void }): Promise<number> {
+  const at = io.args.indexOf('--changed-files');
+  const files = at >= 0 ? io.args.slice(at + 1).filter((arg) => !arg.startsWith('--')) : [];
+  if (files.length === 0) return 0;
+  let result: ExportImportCheck;
+  try { result = await exportImportCheck(files, io.cwd); }
+  catch { result = { measured: false, hits: [], unseen: 0, detail: '검사 실행 실패' }; }
+  if (!result.measured) {
+    let publicFiles = files;
+    try {
+      const { loadExportConfig, selectExportFiles } = await exportSelectors();
+      publicFiles = selectExportFiles(files, loadExportConfig(io.cwd));
+    } catch { publicFiles = files; }
+    if (publicFiles.length === 0) { io.log('⚠ public-export-import: 못 쟀다 — 공개 대상 변경 없음'); return 0; }
+    io.error(`✗ public-export-import: 못 쟀다 — 막는다(${result.detail ?? '?'})`);
+    return 1;
+  }
+  if (result.unseen > 0) io.log(`⚠ public-export-import: 비리터럴 지정자 ${result.unseen}곳은 못 봄`);
+  if (result.hits.length === 0) return 0;
+  io.error(`✗ public-export-import: 공개 파일이 공개 내보내기에서 제외된 모듈을 import 한다 (${result.hits.length}곳) — 공개본 빌드가 여기서 깨진다:`);
+  for (const hit of result.hits) io.error(`   ${hit.file}:${hit.line} → ${hit.target}`);
+  return 1;
+}
+
+if (import.meta.main) {
+  process.exit(await runPublicExportImportGate({ args: process.argv.slice(2), cwd: resolve(import.meta.dir, '..'), log: console.log, error: console.error }));
+}

package/scripts/ci-test-interference-gate.ts

@@ -2,6 +2,7 @@
 import {
   detectTestInterference,
   formatIsolatedFailureSummary,
+  runBunTest,
   type InterferenceReport,
   type TestRunner,
 } from './detect-test-interference.js';
@@ -11,6 +12,8 @@ const TEST_FILE = /\.test\.tsx?$/;
 
 export type TestInterferenceGateIo = {
   args?: readonly string[];
+  /** Landing tree. `bun test` of the changed files runs here, not in process.cwd(). */
+  cwd?: string;
   log?: (message: string) => void;
   detect?: (files: readonly string[], runner?: TestRunner) => Promise<InterferenceReport>;
   runner?: TestRunner;
@@ -36,6 +39,7 @@ export function selectedTestFiles(files: readonly string[]): string[] {
 export async function runTestInterferenceGate(io: TestInterferenceGateIo = {}): Promise<number> {
   const args = io.args ?? process.argv.slice(2);
   const log = io.log ?? console.log;
+  const cwd = io.cwd ?? process.cwd();
   const changed = parseChangedFiles(args);
   const tests = selectedTestFiles(changed ?? []);
   if (tests.length < 2) {
@@ -48,7 +52,7 @@ export async function runTestInterferenceGate(io: TestInterferenceGateIo = {}):
   const capNotice = omitted > 0 ? ` · 상한 ${MAX_INSPECTED_TEST_FILES}개 적용, ${omitted}개 미검사.` : '';
   let report: InterferenceReport;
   try {
-    report = await (io.detect ?? detectTestInterference)(inspected, io.runner);
+    report = await (io.detect ?? detectTestInterference)(inspected, io.runner ?? ((files) => runBunTest(files, undefined, cwd)));
   } catch {
     log(`[test-interference-gate] 경고: 측정 불가 — 판정기 실행 실패, 간섭 없음으로 처리하지 않음.${capNotice}`);
     return 0;

package/scripts/ci-typecheck-changed.ts

@@ -15,9 +15,18 @@ import {
 import { debug } from '../src/debug/log.js';
 import { tscEnv } from '../src/typecheck-ratchet.js';
 
+/** Inherited GIT_DIR / GIT_WORK_TREE would make `--cwd <other tree>` still read the launcher's repo. */
+function gitEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env = { ...base };
+  delete env.GIT_DIR;
+  delete env.GIT_WORK_TREE;
+  delete env.GIT_COMMON_DIR;
+  return env;
+}
+
 /** git 조회용 — 명령 실패는 호출자가 빈 출력과 구분할 수 있게 전파한다. */
-function sh(cmd: string): string {
-  return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+function sh(cmd: string, cwd = process.cwd()): string {
+  return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], cwd, env: gitEnv() });
 }
 
 export type TscRun = { out: string; ran: boolean; why?: string };
@@ -53,16 +62,21 @@ export type ChangedTsFiles = {
   files: Set<string>;
   base: string;
   baseSource: string;
+  head?: string;
+  diffFiles?: Set<string>;
+  warnings?: string[];
   failures?: { command: string; why: string }[];
 };
 
-/** 선택한 base와 파일 수를 함께 보존한다. 0개도 base 기준 관측값이다. */
-export function changedTsFiles(run = sh, env: NodeJS.ProcessEnv = process.env): ChangedTsFiles {
+/** 선택한 base와 파일 수를 함께 보존한다. 0개도 base 기준 관측값이다.
+ *  `cwd` 는 착지 트리다 — `pr land --cwd` 가 프로세스 cwd 가 아니라 그 트리를 재게 한다. */
+export function changedTsFiles(run: (cmd: string) => string = sh, env: NodeJS.ProcessEnv = process.env, cwd = process.cwd(), baseRef?: string): ChangedTsFiles {
   let base: string;
   let baseSource: string;
-  if (env.TSC_BASE_REF) {
-    base = env.TSC_BASE_REF;
-    baseSource = 'TSC_BASE_REF';
+  const pinned = baseRef ?? env.TSC_BASE_REF;
+  if (pinned) {
+    base = pinned;
+    baseSource = baseRef ? 'baseRef' : 'TSC_BASE_REF';
   } else if (env.GITHUB_BASE_REF) {
     base = `origin/${env.GITHUB_BASE_REF}`;
     baseSource = 'GITHUB_BASE_REF';
@@ -78,23 +92,43 @@ 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».
+        // existsSync is bound to the landing tree — process.cwd() would count the launcher's files.
+        const present = existsSync(join(cwd, file));
+        if (!ts || present) diffFiles.add(file);
+        if (ts && present) 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 };
@@ -745,7 +779,7 @@ export function readMergeBaseDiagnostics(base: string, command: string, cwd = pr
   const workspace = mkdtempSync(join(tmpdir(), 'ci-typecheck-baseline-'));
   const worktree = join(workspace, 'base');
   try {
-    execFileSync('git', ['worktree', 'add', '--detach', worktree, base], { cwd, stdio: 'pipe' });
+    execFileSync('git', ['worktree', 'add', '--detach', worktree, base], { cwd, stdio: 'pipe', env: gitEnv() });
     const modules = join(cwd, 'node_modules');
     if (!existsSync(modules)) return { unavailable: `기준 worktree 의존성을 재사용할 수 없다(${modules} 없음)` };
     symlinkSync(modules, join(worktree, 'node_modules'));
@@ -759,7 +793,7 @@ export function readMergeBaseDiagnostics(base: string, command: string, cwd = pr
   } catch (error) {
     return { unavailable: error instanceof Error ? error.message : String(error) };
   } finally {
-    try { execFileSync('git', ['worktree', 'remove', '--force', worktree], { cwd, stdio: 'pipe' }); }
+    try { execFileSync('git', ['worktree', 'remove', '--force', worktree], { cwd, stdio: 'pipe', env: gitEnv() }); }
     catch { /* acquisition failure is rendered by the caller */ }
     rmSync(workspace, { recursive: true, force: true });
   }
@@ -771,6 +805,10 @@ export type GateIo = {
   literalUnionMembers?: (changed: ReadonlySet<string>, base: string) => LiteralUnionMember[] | LiteralUnionMemberCheck;
   readBaselineDiagnostics?: (base: string, command: string) => BaselineDiagnostics;
   runTscCmd: (cmd: string) => TscRun;
+  /** Landing tree. Git, existsSync, tsc, and the test baseline are measured here — not in process.cwd(). */
+  cwd?: string;
+  /** Explicit base revision. Same rule as TSC_BASE_REF, without reading the process environment. */
+  baseRef?: string;
   log: (message: string) => void;
   warn: (message: string) => void;
   error: (message: string) => void;
@@ -840,8 +878,10 @@ function inspectTscResult(tsc: TscRun, changed: ReadonlySet<string>, baseline: R
 }
 
 export function runGate(io: Partial<GateIo> = {}): void {
-  const { changedTsFiles: getChanged = changedTsFiles, runTscCmd = (cmd: string) => runTsc(cmd), log = (message: string) => console.log(message), warn = (message: string) => console.warn(message), error = (message: string) => console.error(message), exit = ((code: number) => process.exit(code)) as GateIo['exit'] } = io;
-  const readBaselineDiagnostics = io.readBaselineDiagnostics ?? ((base: string, command: string) => readMergeBaseDiagnostics(base, command));
+  const cwd = io.cwd ?? process.cwd();
+  const defaultChanged = () => changedTsFiles((cmd) => sh(cmd, cwd), process.env, cwd, io.baseRef);
+  const { changedTsFiles: getChanged = defaultChanged, runTscCmd = (cmd: string) => runTsc(cmd, ((command, options) => execSync(command, { ...options, cwd, env: gitEnv() })) as typeof execSync), log = (message: string) => console.log(message), warn = (message: string) => console.warn(message), error = (message: string) => console.error(message), exit = ((code: number) => process.exit(code)) as GateIo['exit'] } = io;
+  const readBaselineDiagnostics = io.readBaselineDiagnostics ?? ((base: string, command: string) => readMergeBaseDiagnostics(base, command, cwd));
   // Set 주입은 기존 테스트 심이며 기준 revision이 없다. 실제 ChangedTsFiles 경로만 Git 관측을 요구한다.
   const requiredExportFields = io.requiredExportFields ?? ((changed: ReadonlySet<string>, base: string) => base === 'injected test seam'
     ? { fields: [], removedSymbols: [], parameterIncreases: [] }
@@ -850,10 +890,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 +904,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) {
@@ -934,8 +985,8 @@ export function runGate(io: Partial<GateIo> = {}): void {
   }, { level: 'info' });
   log(`[tsc-gate] root 설정 범위 ${rootScope.size}개 관측 (apps/pwa/** 제외).`);
   if (runsPwa) log(`[tsc-gate] PWA 설정 범위 ${pwaScope.size}개 관측.`);
-  const tscBin = existsSync('node_modules/.bin/tsc') ? 'node_modules/.bin/tsc' : 'npx tsc';
-  const baseline = readTestTypecheckBaseline(process.cwd());
+  const tscBin = existsSync(join(cwd, 'node_modules/.bin/tsc')) ? 'node_modules/.bin/tsc' : 'npx tsc';
+  const baseline = readTestTypecheckBaseline(cwd);
   const rootCommand = `${tscBin} --noEmit -p ${TYPECHECK_GATE_CONFIG}`;
   const pwaCommand = `${tscBin} --noEmit -p apps/pwa/tsconfig.json`;
   const pwaEnvCommand = `${tscBin} --noEmit -p tsconfig.pwa-env.json`;

package/scripts/docs/doc-rot.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env bun
+// DOC-ROT① — 내부 매뉴얼(내부 문서 `*`)의 명령·저장소 경로를 실제와 대조한다.
+//   bun scripts/docs/doc-rot.ts [--json] [files…]      (기본 = 내부 문서 `*`)
+// 명령 판정은 scripts/docs-cli-check.ts 의 checkCommands 만 쓴다(같은 판정을 다시 짜지 않는다).
+// 경로 판정은 인라인 코드 안의 src/ · scripts/ · docs/ · graphs/ · test/ 가 repoRoot 에 있는지다.
+// ⛔ --help 를 못 잰 명령은 unmeasured 로 따로 센다 — «없다»로 세지 않는다.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, relative, resolve } from 'node:path';
+import {
+  checkCommands,
+  extractElanousCommands,
+  type Finding,
+  type HelpRunner,
+} from '../docs-cli-check.js';
+
+const REPO = resolve(import.meta.dir, '../..');
+const PATH_ROOTS = ['src/', 'scripts/', 'docs/', 'graphs/', 'test/'] as const;
+const PASSTHROUGH_COMMANDS = new Set(['gh', 'git']);
+
+export interface MissingPath { line: number; path: string }
+export interface DocRotFinding extends Omit<Finding, 'kind'> {
+  kind: Finding['kind'] | 'passthrough' | 'globalFlag' | 'intentional';
+}
+export interface DocRotFile {
+  file: string;
+  commands: DocRotFinding[];
+  missingPaths: MissingPath[];
+}
+export interface DocRotTotals {
+  files: number;
+  staleFiles: number;
+  missingPaths: number;
+  badCommands: number;
+  unmeasured: number;
+  passthrough: number;
+  globalFlag: number;
+  intentional: number;
+}
+export interface DocRotReport {
+  files: DocRotFile[];
+  totals: DocRotTotals;
+}
+
+export interface ScanDocRotInput {
+  files: readonly string[];
+  repoRoot: string;
+  help?: HelpRunner;
+  read?: (file: string) => string;
+}
+
+/** 인라인 코드에서 저장소 경로를 뽑는다. 줄번호 꼬리(`:12`)는 떼고, glob(`*`)은 건너뛴다. */
+export function extractRepoPaths(text: string): MissingPath[] {
+  const out: MissingPath[] = [];
+  const seen = new Set<string>();
+  for (const m of text.matchAll(/`([^`\n]+)`/g)) {
+    const raw = m[1]!;
+    if (raw.includes('*')) continue;
+    if (!PATH_ROOTS.some((root) => raw.startsWith(root))) continue;
+    const path = raw.replace(/:\d+$/, '');
+    if (!PATH_ROOTS.some((root) => path.startsWith(root)) || path.endsWith('/')) continue;
+    const line = text.slice(0, m.index ?? 0).split('\n').length;
+    const key = `${line}\0${path}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ line, path });
+  }
+  return out;
+}
+
+/** 파일마다 명령 findings(checkCommands 재사용)와 없는 경로를 센다. */
+export function scanDocRot(input: ScanDocRotInput): DocRotReport {
+  const read = input.read ?? ((file: string) => readFileSync(file, 'utf8'));
+  const texts = input.files.map((file) => ({ file, text: read(file) }));
+  const help: HelpRunner = input.help ?? ((args) => {
+    const result = spawnSync('bun', ['bin/elanous.mjs', '--test', ...args, '--help'], {
+      cwd: input.repoRoot, encoding: 'utf8', timeout: 60_000, env: { ...process.env, NO_COLOR: '1' },
+    });
+    return { ok: result.status === 0, out: `${result.stdout ?? ''}\n${result.stderr ?? ''}` };
+  });
+  let commandRoot: ReturnType<HelpRunner> | undefined;
+  const cachedHelp: HelpRunner = (args) => {
+    if (args.length === 0) return commandRoot ??= help(args);
+    return help(args);
+  };
+  const checked = texts.map(({ file, text }) => {
+    const label = relative(input.repoRoot, file) || file;
+    return { file: label, text, commands: checkCommands(extractElanousCommands(label, text), cachedHelp) };
+  });
+  const hasUnknownFlag = checked.some(({ commands }) => commands.some((finding) => finding.kind === 'unknown-flag'));
+  // A separate lookup measures root Options; a failure must not mean "no global flags".
+  const rootOptionsHelp = hasUnknownFlag ? help([]) : commandRoot;
+  const rootOptions = rootOptionsHelp?.ok ? (rootOptionsHelp.out.split(/\nOptions:\s*\n/)[1] ?? '').split(/\n\S[^\n]*:\s*\n/)[0]! : '';
+  const globalFlags = new Set([...rootOptions.matchAll(/^\s+(?:-\w,\s*)?(--[a-z][a-z0-9-]*)\b/gm)].map((match) => match[1]!));
+  const files: DocRotFile[] = checked.map(({ file, text, commands }) => {
+    const lines = text.split('\n');
+    const classified: DocRotFinding[] = commands.map((finding) => {
+      if (finding.kind !== 'unmeasured' && (lines[finding.ref.line - 1] ?? '').includes('⛔')) return { ...finding, kind: 'intentional' };
+      if (finding.kind !== 'unknown-flag') return finding;
+      if (PASSTHROUGH_COMMANDS.has(finding.ref.cmd)) return { ...finding, kind: 'passthrough' };
+      if (!rootOptionsHelp?.ok) return { ...finding, kind: 'unmeasured' };
+      const flag = /^--[a-z][a-z0-9-]*/.exec(finding.detail)?.[0];
+      if (flag && globalFlags.has(flag)) return { ...finding, kind: 'globalFlag' };
+      return finding;
+    });
+    const missingPaths = extractRepoPaths(text).filter((entry) => !existsSync(join(input.repoRoot, entry.path)));
+    return { file, commands: classified, missingPaths };
+  });
+  const isBad = (finding: DocRotFinding) => finding.kind === 'unknown-command' || finding.kind === 'unknown-subcommand' || finding.kind === 'unknown-flag';
+  const count = (kind: DocRotFinding['kind']) => files.reduce((sum, file) => sum + file.commands.filter((finding) => finding.kind === kind).length, 0);
+  const totals: DocRotTotals = {
+    files: files.length,
+    staleFiles: files.filter((file) => file.missingPaths.length > 0 || file.commands.some(isBad)).length,
+    missingPaths: files.reduce((sum, file) => sum + file.missingPaths.length, 0),
+    badCommands: files.reduce((sum, file) => sum + file.commands.filter(isBad).length, 0),
+    unmeasured: count('unmeasured'),
+    passthrough: count('passthrough'),
+    globalFlag: count('globalFlag'),
+    intentional: count('intentional'),
+  };
+  return { files, totals };
+}
+
+export function defaultManualFiles(repoRoot: string = REPO): string[] {
+  return readdirSync(join(repoRoot, 'docs', 'manual'))
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => join(repoRoot, 'docs', 'manual', name));
+}
+
+function renderTable(report: DocRotReport): string {
+  const lines = [
+    `doc-rot — 매뉴얼 ${report.totals.files} · 낡은 파일 ${report.totals.staleFiles} · 없는 경로 ${report.totals.missingPaths} · 깨진 명령 ${report.totals.badCommands} · 못 잰 명령 ${report.totals.unmeasured} · 통과 래퍼 ${report.totals.passthrough} · 전역 옵션 ${report.totals.globalFlag} · 의도적 예시 ${report.totals.intentional}`,
+  ];
+  for (const file of report.files) {
+    for (const finding of file.commands) lines.push(`  ${finding.kind}  ${file.file}:${finding.ref.line}  ${finding.detail}`);
+    for (const missing of file.missingPaths) lines.push(`  missing-path  ${file.file}:${missing.line}  ${missing.path}`);
+  }
+  return lines.join('\n');
+}
+
+if (import.meta.main) {
+  try {
+    const { registerStandaloneLogSink } = await import('../../src/domains/standalone-log-sink.js');
+    await registerStandaloneLogSink('doc-rot');
+  } catch { /* fail-open — 관측 배선 실패가 측정을 막지 않는다 */ }
+  const { debug } = await import('../../src/debug/log.js');
+  const json = process.argv.includes('--json');
+  const args = process.argv.slice(2).filter((arg) => arg !== '--json');
+  const files = args.length ? args.map((arg) => resolve(arg)) : defaultManualFiles();
+  const report = scanDocRot({ files, repoRoot: REPO });
+  debug.log('docs.rot', 'scanned', {
+    files: report.totals.files,
+    staleFiles: report.totals.staleFiles,
+    missingPaths: report.totals.missingPaths,
+    badCommands: report.totals.badCommands,
+    unmeasured: report.totals.unmeasured,
+    passthrough: report.totals.passthrough,
+    globalFlag: report.totals.globalFlag,
+    intentional: report.totals.intentional,
+  });
+  console.log(json ? JSON.stringify(report) : renderTable(report));
+  process.exit(report.totals.badCommands + report.totals.missingPaths > 0 ? 1 : 0);
+}