elanous 0.2.13 → 0.2.15

package/scripts/expose-rubric-suggest.ts

@@ -0,0 +1,169 @@
+#!/usr/bin/env bun
+/** Machine-measured suggestions only; MK judges and merges the exposure ledger. */
+import { readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+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 { BRAND_RULES_UNMEASURED, checkBrand } from './brand/check.js';
+import { checkCommands, extractElanousCommands, type HelpRunner } from './docs-cli-check.js';
+import { scanLeaks } from './public-export.js';
+
+const DOCS = 'release/public/docs';
+const LEDGER = 'release/public/expose-rubric.yaml';
+const KEYS = ['reproducible', 'confidential', 'brand'] as const;
+type Criterion = { status: 'pass' | 'fail' | 'n/a'; reason: string };
+type Suggestion = { path: string; criteria: Record<(typeof KEYS)[number], Criterion> };
+
+function unmeasured(error: unknown): Criterion {
+  const detail = error instanceof Error ? error.message : String(error);
+  return { status: 'n/a', reason: `측정 불가: ${detail.split(/\r?\n/)[0] || '알 수 없는 오류'}` };
+}
+
+function measure(run: () => Criterion): Criterion {
+  try { return run(); } catch (error) { return unmeasured(error); }
+}
+
+/** 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, 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 이어야 합니다');
+  type HelpResult = ReturnType<HelpRunner> & { failure?: string };
+  let helpRuns = 0;
+  const rootHelp: (args: string[]) => HelpResult = help ?? ((args) => {
+    helpRuns++;
+    const result = spawnSync('bun', ['bin/elanous.mjs', '--test', ...args, '--help'], {
+      cwd: resolve(import.meta.dir, '..'), encoding: 'utf8', timeout: 60_000, env: { ...process.env, NO_COLOR: '1' },
+    });
+    const error = result.error as NodeJS.ErrnoException | undefined;
+    return {
+      ok: result.status === 0 && !error,
+      out: `${result.stdout ?? ''}\n${result.stderr ?? ''}`,
+      failure: error?.code === 'ETIMEDOUT' ? 'timeout'
+        : error ? error.message
+        : result.status !== 0 ? `exit ${result.status ?? 'unknown'}` : undefined,
+    };
+  });
+  const helpCache = new Map<string, { ok: true; out: string } | { ok: false; reason: string }>();
+  let helpFailures = 0;
+  const checkedHelp: HelpRunner = (args) => {
+    const key = args.join(' ');
+    let cached = helpCache.get(key);
+    if (!cached) {
+      const runOnce = (): { ok: true; out: string } | { ok: false; reason: string } => {
+        try {
+          const result = rootHelp(args);
+          if (result.ok && result.out.trim()) return { ok: true, out: result.out };
+          helpFailures++;
+          return { ok: false, reason: result.failure ?? (result.out.trim() ? '실행 실패' : '빈 출력') };
+        } catch (error) {
+          helpFailures++;
+          return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+      };
+      cached = runOnce();
+      if (!cached.ok) cached = runOnce();
+      helpCache.set(key, cached);
+    }
+    if (!cached.ok) throw new Error(`elanous ${key ? `${key} ` : ''}--help 실패(${cached.reason.split(/\r?\n/)[0] || '알 수 없는 오류'})`);
+    return cached;
+  };
+  const results = paths.sort().map((path): Suggestion => {
+    const absolute = join(root, path);
+    let text: string;
+    try { text = readFileSync(absolute, 'utf8'); }
+    catch (error) {
+      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 명령 없음' };
+      const findings = checkCommands(refs, checkedHelp);
+      const unable = findings.find((finding) => finding.kind === 'unmeasured');
+      if (unable) return unmeasured(unable.detail);
+      const missing = [...new Set(findings.map((finding) => finding.detail))].slice(0, 3);
+      return missing.length
+        ? { status: 'fail', reason: `없는 명령: ${missing.join(', ')}` }
+        : { status: 'pass', reason: `명령 ${refs.length}개 모두 --help 에 있음` };
+    });
+    const confidential = measure(() => {
+      const hits = scanLeaks(root, [path], undefined, new Map([[path, text]]));
+      const markers = [...new Set(hits.map((hit) => hit.marker))].slice(0, 3);
+      return markers.length
+        ? { status: 'fail', reason: `누출 표식: ${markers.join(', ')}` }
+        : { status: 'pass', reason: '누출 표식 없음' };
+    });
+    // 브랜드 규칙이 없으면 브랜드만 «측정 불가» — 따로 잰 재현성·누출 결과는 덮어쓰지 않는다.
+    return { path, criteria: { reproducible, confidential, brand } };
+  });
+  const statuses = results.flatMap((item) => KEYS.map((key) => item.criteria[key].status));
+  debug.log('expose.rubric', 'suggested', {
+    docs: results.length, pass: statuses.filter((status) => status === 'pass').length,
+    fail: statuses.filter((status) => status === 'fail').length,
+    unmeasured: statuses.filter((status) => status === 'n/a').length,
+    helpRuns, helpFailures,
+  });
+  return results;
+}
+
+export function run(argv: readonly string[], root = process.cwd(), help?: HelpRunner): number {
+  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, rulesPath);
+  if (out) {
+    const target = resolve(root, out);
+    const ledger = resolve(root, LEDGER);
+    if (target === ledger || realpathOrSelf(target) === realpathOrSelf(ledger) || sameFile(target, ledger)) throw new Error('원장 파일은 덮어쓸 수 없습니다');
+    writeFileSync(target, stringify({ entries: results }));
+  }
+  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})` : 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)`);
+  }
+  return 0;
+}
+
+function realpathOrSelf(path: string): string {
+  try { return realpathSync(path); } catch { return path; }
+}
+
+function sameFile(target: string, ledger: string): boolean {
+  const a = statSync(target, { throwIfNoEntry: false });
+  const b = statSync(ledger, { throwIfNoEntry: false });
+  return !!a && !!b && a.dev === b.dev && a.ino === b.ino;
+}
+
+if (import.meta.main) {
+  try { process.exitCode = run(process.argv.slice(2)); }
+  catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 2; }
+}

package/scripts/heal/run-role.ts

@@ -5,6 +5,7 @@ import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { debug } from '../../src/debug/log.js';
+import { readFailureInbox } from '../../src/self-implement/heal-intake.js';
 import {
   fillMissingGateFacts,
   markDeletedUnverified,
@@ -101,6 +102,7 @@ export interface HealRoleDeps {
   loadLedger?: (runId: string) => RunLedgerEntry[] | null;
   ledgerDir?: string;
   search?: (query: string) => unknown;
+  stateRoot?: string;
 }
 
 function gitHeadExists(worktree: string, path: string): PathExists {
@@ -243,6 +245,18 @@ export function roleResult(role: string, ctx: GraphContext, deps: HealRoleDeps =
   const signature = failureOf(ctx);
   switch (role) {
     case 'observe-ledger': {
+      const selector = asRecord(input.failureEvent);
+      if (selector) {
+        if (typeof selector.source !== 'string' || typeof selector.ref !== 'string' || !selector.source || !selector.ref) {
+          return withAddedFacts({ outcome: 'fail', reason: 'invalid-failure-event-selector' }, []);
+        }
+        const since = typeof input.since === 'string' ? input.since : undefined;
+        const event = readFailureInbox({ since }, deps.stateRoot)
+          .filter(row => row.source === selector.source && row.ref === selector.ref)
+          .sort((a, b) => Date.parse(b.at) - Date.parse(a.at)).at(0);
+        if (!event) return withAddedFacts({ outcome: 'empty', reason: 'inbox-event-not-found' }, []);
+        return withAddedFacts({ outcome: 'ok', entries: [{ errorText: event.summary }], event }, ['errorText']);
+      }
       if (!asRecord(input.failure) && Object.keys(failure).length === 0) return withAddedFacts({ outcome: 'empty' }, []);
       const worktree = typeof input.worktree === 'string' ? input.worktree : '';
       const paths = signature.unverified ?? [];

package/scripts/hq/standby-verify.ts

@@ -10,6 +10,7 @@ import type { Manifest, Tier } from './standby-snapshot.js';
 export interface TierVerification {
   tier: Tier;
   generation: string | null;
+  manifestSha256: string | null;
   ageMin: number | null;
   host: string | null;
   entries: number | null;
@@ -27,7 +28,7 @@ export interface StandbyVerification {
   reasons: string[];
 }
 
-export interface VerifyOptions { root: string; tiers: Tier[]; marker?: string; maxAgeMin?: number | Partial<Record<Tier, number>>; now?: Date }
+export interface VerifyOptions { root: string; tiers: Tier[]; generations?: Partial<Record<Tier, string>>; marker?: string; maxAgeMin?: number | Partial<Record<Tier, number>>; now?: Date }
 
 function errorCode(error: unknown): unknown {
   return typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
@@ -46,8 +47,8 @@ async function hashFile(path: string): Promise<string> {
   return hash.digest('hex');
 }
 
-async function verifyTier(root: string, tier: Tier, maxAgeMin: number | undefined, now: Date): Promise<TierVerification> {
-  const result: TierVerification = { tier, generation: null, ageMin: null, host: null, entries: null, checked: 0, mismatches: 0, missing: 0, unreadable: false, reasons: [] };
+async function verifyTier(root: string, tier: Tier, maxAgeMin: number | undefined, now: Date, pinnedGeneration?: string): Promise<TierVerification> {
+  const result: TierVerification = { tier, generation: null, manifestSha256: null, ageMin: null, host: null, entries: null, checked: 0, mismatches: 0, missing: 0, unreadable: false, reasons: [] };
   const base = join(root, tier);
   try {
     await stat(base);
@@ -58,7 +59,7 @@ async function verifyTier(root: string, tier: Tier, maxAgeMin: number | undefine
   }
   let target: string;
   try {
-    target = await readlink(join(base, 'latest'));
+    target = pinnedGeneration ?? await readlink(join(base, 'latest'));
   } catch (error) {
     if (errorCode(error) === 'ENOENT' || errorCode(error) === 'EINVAL') result.reasons.push(`${tier}:latest missing`);
     else {
@@ -76,10 +77,13 @@ async function verifyTier(root: string, tier: Tier, maxAgeMin: number | undefine
   let manifest: Manifest;
   let sums: string;
   try {
-    [manifest, sums] = await Promise.all([
-      readFile(join(dir, 'MANIFEST.json'), 'utf8').then(text => JSON.parse(text) as Manifest),
+    const [manifestBytes, sumsText] = await Promise.all([
+      readFile(join(dir, 'MANIFEST.json')),
       readFile(join(dir, 'SHA256SUMS'), 'utf8'),
     ]);
+    manifest = JSON.parse(manifestBytes.toString('utf8')) as Manifest;
+    sums = sumsText;
+    result.manifestSha256 = createHash('sha256').update(manifestBytes).digest('hex');
   } catch (error) {
     if (error instanceof SyntaxError) result.reasons.push(`${tier}:invalid manifest`);
     else {
@@ -128,7 +132,7 @@ async function verifyTier(root: string, tier: Tier, maxAgeMin: number | undefine
 
 export async function verifyStandby(opts: VerifyOptions): Promise<StandbyVerification> {
   const tiers = await Promise.all(opts.tiers.map(tier => verifyTier(opts.root, tier,
-    typeof opts.maxAgeMin === 'number' ? opts.maxAgeMin : opts.maxAgeMin?.[tier], opts.now ?? new Date())));
+    typeof opts.maxAgeMin === 'number' ? opts.maxAgeMin : opts.maxAgeMin?.[tier], opts.now ?? new Date(), opts.generations?.[tier])));
   const reasons = tiers.flatMap(tier => tier.reasons);
   let marker: StandbyVerification['marker'];
   if (opts.marker !== undefined) {

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

@@ -0,0 +1,112 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+import { LessonLedger, type LessonRow, type LessonStatus } from '../../src/lessons/lesson-ledger.js';
+
+const statuses: LessonStatus[] = ['candidate', 'open', 'enforced', 'promoted'];
+
+function args(argv: string[]): { stateDir?: string; out?: string; json: boolean } {
+  const options: { stateDir?: string; out?: string; json: boolean } = { json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') options.json = true;
+    else if (arg === '--state-dir' || arg === '--out') {
+      const value = argv[++i];
+      if (!value || value.startsWith('--')) throw new Error(`missing value for ${arg}`);
+      if (arg === '--state-dir') options.stateDir = value;
+      else options.out = value;
+    } else throw new Error(`unknown option: ${arg}`);
+  }
+  return options;
+}
+
+function inlineText(value: string): string {
+  return value.replace(/\s+/g, ' ').trim()
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/([\\`*_{}\[\]()~!|])/g, '\\$1')
+    .replace(/([a-z][a-z\d+.-]*:)(\/\/)|\b(www\.)(?=\S)|(@)(?=\S)/gi,
+      (_match, scheme: string | undefined, slashes: string | undefined, www: string | undefined, at: string | undefined) =>
+        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(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) : '반증 없음 — 승격 불가'}`);
+    if (kind === 'enforced' || kind === 'promoted') lines.push(`- 강제 자리: ${inlineText(row.enforced_by)}`);
+    lines.push('');
+  }
+  return lines;
+}
+
+export function generateHandbookPage(options: { stateDir?: string; out?: string } = {}): {
+  total: number; byStatus: Record<LessonStatus, number>; unenforced: number; out: string;
+} | { skipped: 'empty-ledger' } {
+  const ledger = new LessonLedger({ stateDir: options.stateDir });
+  const rows = ledger.list();
+  if (!rows.length) return { skipped: 'empty-ledger' };
+  const out = options.out ?? join(dirname(ledger.path), 'handbook-lessons.md');
+  const byStatus: Record<LessonStatus, number> = { candidate: 0, open: 0, enforced: 0, promoted: 0 };
+  for (const row of rows) byStatus[row.status]++;
+  const unenforcedRows = rows.filter(row => row.status === 'open' && !row.enforced_by.trim());
+  const unenforced = unenforcedRows.length;
+  const lines = [
+    '# 교훈', '',
+    `생성 시각: ${new Intl.DateTimeFormat('ko-KR', { timeZone: 'Asia/Seoul', dateStyle: 'long', timeStyle: 'long' }).format(new Date())} (KST)`,
+    `총 ${rows.length} · ${statuses.map(status => `${status} ${byStatus[status]}`).join(' · ')} · 강제 자리 없음 ${unenforced}`,
+    '',
+    ...section('승격 후보', rows.filter(row => row.status === 'candidate'), ledger, 'candidate'),
+    ...section('강제 자리 없음', unenforcedRows, ledger, 'open'),
+    ...section('강제됨', rows.filter(row => row.status === 'enforced'), ledger, 'enforced'),
+    ...section('규칙으로 승격됨', rows.filter(row => row.status === 'promoted'), ledger, 'promoted'),
+  ];
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, `${lines.join('\n')}\n`, 'utf8');
+  debug.log('lessons.handbook', 'rendered', { total: rows.length, byStatus, unenforced, out });
+  return { total: rows.length, byStatus, unenforced, out };
+}
+
+if (import.meta.main) {
+  try {
+    const options = args(process.argv.slice(2));
+    const result = generateHandbookPage(options);
+    console.log(options.json ? JSON.stringify(result) : 'skipped' in result ? `skipped: ${result.skipped}` : `rendered: ${result.out}`);
+  } catch (error) {
+    console.error(`handbook-page: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}

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);
+}