elanous 0.2.13 → 0.2.15

package/src/cli/decisions-cli.ts

@@ -1,12 +1,16 @@
 import { Option, type Command } from 'commander';
 import { hqCliWriteAllowed, type HqDeps } from '../hq/hq.js';
 import { fileLeaseStore } from '../hq/lease.js';
+import { isIsolatedLedgerWriteRoot } from '../hq/ledger-write-target.js';
+import { debug } from '../debug/log.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
 import { join } from 'node:path';
 import { getElanousConfigDirOverride } from '../elanous-config-dir.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { getUserConfig } from '../user-config.js';
 import { projectDecisionsToLinear } from '../decisions/decision-linear-projection.js';
-import { DecisionLedger, importDecisionMarkdown, type DecisionCategory, type DecisionLedgerOptions, type DecisionOption, type DecisionTrack, type DecisionEntry } from '../decisions/decision-ledger.js';
+import { DecisionLedger, importDecisionMarkdown, type DecisionCategory, type DecisionLedgerOptions, type DecisionOption, type DecisionTrack, type DecisionEntry, type Seat, type SeatDecisionRecord } from '../decisions/decision-ledger.js';
+import { formatProactMeter, readProactMeter } from '../decisions/proact-meter.js';
 
 const repeat = (value: string, values: string[]) => [...values, value];
 function date(raw?: string): string | undefined {
@@ -52,13 +56,24 @@ export function formatDecisionDetail(e: DecisionEntry): string {
     ...(e.refs?.length ? [`참조: ${e.refs.join(' · ')}`] : [])].join('\n');
 }
 
+export function formatSeatDecisionRow(e: SeatDecisionRecord): string {
+  return `${e.id} · 결정: ${e.decidedAt ? kst(e.decidedAt) : '시각 미상'} · 기록: ${e.recordedAt ? kst(e.recordedAt) : '시각 미상'} · ${e.seat} 결정 · 사후 보고 · ${e.title} → ${e.decision} · 위임: ${e.delegation}${e.refs?.length ? ` · 참조: ${e.refs.join(' · ')}` : ''}`;
+}
+
 export function registerDecisionsCommands(program: Command, config: DecisionLedgerOptions = {}, out: Pick<Console, 'log'> = console, hqDeps: HqDeps = {}): void {
   const noXcheck = new Option('--no-xcheck <이유>', '교차 확인 생략 이유');
   // This flag takes a reason, not Commander's negated boolean default.
   noXcheck.negate = false;
   const root = program.command('decisions').description('대표 결정 원장 · 로컬 전용').option('--hq-override', '본부 임대 거부를 관측하며 수동 우회');
-  const mayWrite = (command: string, override?: boolean) => hqCliWriteAllowed(`decisions ${command}`, Boolean(override || root.opts().hqOverride),
-    (getElanousConfigDirOverride() || config.stateDir) && !hqDeps.store && !getUserConfig().hq?.arbiter ? { ...hqDeps, store: fileLeaseStore(join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'lease.json')), seenPath: join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'seen-generation'), localPath: join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'local.json') } : hqDeps);
+  const mayWrite = (command: string, override?: boolean) => {
+    const ledgerRoot = config.stateDir ?? elanousStateRoot();
+    if (command !== 'linear-sync' && isIsolatedLedgerWriteRoot(ledgerRoot)) {
+      try { debug.log('hq.fence', 'skipped-isolated', { root: ledgerRoot, command: `decisions ${command}` }); } catch { /* observation is fail-soft */ }
+      return true;
+    }
+    return hqCliWriteAllowed(`decisions ${command}`, Boolean(override || root.opts().hqOverride),
+      (getElanousConfigDirOverride() || config.stateDir) && !hqDeps.store && !getUserConfig().hq?.arbiter ? { ...hqDeps, store: fileLeaseStore(join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'lease.json')), seenPath: join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'seen-generation'), localPath: join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'local.json') } : hqDeps);
+  };
   const emit = (value: unknown, json?: boolean, text?: string) => out.log(json ? JSON.stringify(value) : text ?? JSON.stringify(value));
   const fail = (action: () => void) => { try { action(); } catch (e) { throw new Error(`decisions: ${e instanceof Error ? e.message : String(e)}`); } };
   root.command('linear-sync').description('열린 결정을 COO Linear 프로젝트에 투영하고 닫힌 결정을 동기화한다')
@@ -105,6 +120,32 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
       if (entry.crossCheckSkipped === 'missing') console.error('교차 확인 없음 — --xcheck SEAT:메모 또는 --no-xcheck 이유');
       emit(entry, o.json, `올림: ${formatDecisionRow(entry)}`);
     }));
+  root.command('record-seat').description('위임 범위에서 이미 내린 자리 결정을 사후 보고로 원장에 기록 (대표 카드 아님)')
+    .requiredOption('--seat <OP|MK|TC|UX>').requiredOption('--title <text>')
+    .requiredOption('--decision <text>').requiredOption('--delegation <scope>')
+    .option('--at <UTC>', '알고 있는 결정 시각 (UTC ISO; 생략 시 결정 시각 미상)')
+    .option('--ref <source>', '조율 글 등의 출처 (반복)', repeat, [] as string[])
+    .option('--json').option('--hq-override')
+    .action((o: { seat: Seat; title: string; decision: string; delegation: string; at?: string; ref: string[]; json?: boolean; hqOverride?: boolean }) => fail(() => {
+      if (!mayWrite('record-seat', o.hqOverride)) return;
+      const entry = new DecisionLedger(config).recordSeatDecision({ seat: o.seat, title: o.title, decision: o.decision,
+        delegation: o.delegation, ...(o.at ? { decidedAt: o.at } : {}), ...(o.ref.length ? { refs: o.ref } : {}) });
+      emit(entry, o.json, formatSeatDecisionRow(entry));
+    }));
+  root.command('seat-report').description('밤사이 자리들의 사후 결정을 한 번에 조회 (기본 최근 24시간)')
+    .option('--since <date>', '조회 시작 UTC ISO 또는 Nd', '1d').option('--seat <OP|MK|TC|UX>').option('--json')
+    .action((o: { since: string; seat?: Seat; json?: boolean }) => fail(() => {
+      const rows = new DecisionLedger(config).seatReport({ since: date(o.since), seat: o.seat });
+      emit(rows, o.json, rows.length ? rows.map(formatSeatDecisionRow).join('\n') : '자리 결정 0건');
+    }));
+  root.command('proact').description('선제성 기준선 — 지난 7일, 먼저 낸 수·채택 수·물어서야 드러난 수')
+    .option('--days <n>', 'KST 일수 (기본 7)', '7').option('--json')
+    .action((o: { days: string; json?: boolean }) => fail(() => {
+      const days = Number(o.days);
+      if (!Number.isInteger(days) || days < 1) throw new Error('invalid days');
+      const meter = readProactMeter({ ...(config.stateDir ? { stateDir: config.stateDir, instanceRoot: config.stateDir } : {}), ...(config.now ? { now: config.now() } : {}), days });
+      emit(meter, o.json, formatProactMeter(meter));
+    }));
   root.command('list').description('결정 목록 (기본 열린 것)')
     .option('--status <open|decided|all>', '기본 open', 'open').option('--since <date>').option('--version <version>')
     .option('--decided-by <human|auto>').option('--category <category>').option('--json')

package/src/cli/docs-cli.ts

@@ -6,6 +6,7 @@
 // 양쪽에서 잡는다. 임베딩 다운 시 키워드 단독으로 강등(fail-soft).
 
 import type { Command } from 'commander';
+import { registerRfcStatusCommand } from './rfc-status.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { relative, resolve } from 'node:path';
 import { knowledgeDbPath, openKnowledgeDb, hybridQueryKnowledge } from '../domains/knowledge.js';
@@ -280,6 +281,7 @@ export async function runDocsStale(
 export function registerDocsCommands(program: Command): void {
   const docsCmd = program.command('docs')
     .description('문서 지식 검색/관리 — knowledge.db 벡터+BM25 하이브리드 (DocOps)');
+  registerRfcStatusCommand(docsCmd);
   docsCmd.command('search <query>')
     .description('하이브리드 검색(RRF) — 의미(임베딩)+키워드(FTS5) 융합. 임베딩 다운 시 키워드 단독')
     .option('--limit <n>', '최대 결과 (기본 8·최대 20)')

package/src/cli/doctor-cli.ts

@@ -39,6 +39,7 @@ import { formatDoctorLocalLlm, probeDoctorLocalLlm, type DoctorLocalLlm } from '
 import type { LlmInventory } from '../llm/local-manager/types.js';
 import { buildDoctorBundle } from './doctor-bundle.js';
 import { uploadDoctorBundle } from './doctor-bundle-upload.js';
+import { checkNodeModules, formatNodeModulesCheck, nodeModulesTrees } from './doctor-node-modules.js';
 
 function defaultCheckPythonEnv(): { status: 'ok' | 'fixable' | 'manual'; evidence: string; remedy?: string } {
   const c = checkPythonEnv(false);
@@ -1216,9 +1217,30 @@ export function registerDoctorCommand(program: Command, deps: DoctorCliDeps = {}
   const out = deps.out ?? { log: (value: string) => console.log(value) };
   const err = deps.err ?? { error: (value: string) => console.error(value) };
   const setExitCode = deps.setExitCode ?? ((code: number) => { process.exitCode = code; });
-  program.command('doctor')
+  const doctor = program.command('doctor')
     .description('Reports whether credentials resolve and where each resolution comes from')
+    .option('--json', 'structured output');
+  doctor.command('node-modules')
+    .description('Check installed top-level packages against bun.lock (read-only)')
+    .option('--dir <tree>', 'tree to check', process.cwd())
+    .option('--all', 'also check nested package.json trees')
     .option('--json', 'structured output')
+    .action((opts: { dir: string; all?: boolean; json?: boolean }, command: Command) => {
+      const json = opts.json || command.parent?.opts().json === true;
+      let dirs: string[];
+      try { dirs = opts.all ? nodeModulesTrees(opts.dir) : [resolve(opts.dir)]; }
+      catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        if (json) out.log(JSON.stringify({ status: 'unreadable', reason }));
+        else out.log(`unreadable: ${reason}`);
+        setExitCode(1);
+        return;
+      }
+      const checks = dirs.map(checkNodeModules);
+      out.log(json ? JSON.stringify(opts.all ? checks : checks[0], null, 2) : checks.map(formatNodeModulesCheck).join('\n'));
+      if (checks.some((check) => check.status !== 'ok')) setExitCode(1);
+    });
+  doctor
     .option('--credentials', 'show per-credential details in human-readable output')
     .option('--bundle', 'write a redacted diagnostics archive for support')
     .option('--upload', 'send the bundle to diagnostics.uploadUrl after consent (requires --bundle)')

package/src/cli/doctor-node-modules.ts

@@ -0,0 +1,147 @@
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { debug } from '../debug/log.js';
+
+export interface NodeModulesCheck {
+  dir: string;
+  status: 'ok' | 'issues' | 'unreadable';
+  missing: string[];
+  mismatch: { name: string; expected: string; actual: string }[];
+  borrowed: { target: string; tree: string } | null;
+  reason?: string;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function loadJson(path: string): unknown {
+  return JSON.parse(readFileSync(path, 'utf8')) as unknown;
+}
+
+function dependencyNames(pkg: Record<string, unknown>): string[] {
+  if (!record(pkg.dependencies ?? {}) || !record(pkg.devDependencies ?? {})) throw new Error('invalid package.json dependencies');
+  return [...new Set([...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})])].sort();
+}
+
+interface LockContext { lockRoot: string; workspace: Record<string, unknown>; packages: Record<string, unknown>; scope: string | null }
+
+/** Own bun.lock first; otherwise the nearest ancestor bun.lock whose workspaces list this folder (root-lock Bun workspaces). */
+function findLock(root: string, packageName: string | null): LockContext {
+  let current = root;
+  for (;;) {
+    let text: string | null = null;
+    try { text = readFileSync(join(current, 'bun.lock'), 'utf8'); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    if (text !== null) {
+      const lock = Bun.JSONC.parse(text) as unknown;
+      if (!record(lock) || !record(lock.packages) || !record(lock.workspaces)) throw new Error('invalid bun.lock');
+      const key = relative(current, root).split(sep).join('/');
+      const workspace = lock.workspaces[key];
+      if (record(workspace)) return { lockRoot: current, workspace, packages: lock.packages, scope: key === '' ? null : (packageName ?? key) };
+      if (key === '') throw new Error('invalid bun.lock');
+      throw new Error(`bun.lock at ${current} does not list workspace ${key}`);
+    }
+    const parent = dirname(current);
+    if (parent === current) throw new Error('no bun.lock in this folder or any parent workspace root');
+    current = parent;
+  }
+}
+
+function lockedVersion(packages: Record<string, unknown>, name: string, scope: string | null = null): string {
+  // Bun keys a workspace-specific resolution as «<workspace>/<dep>» when it differs from the hoisted one.
+  const scoped = scope ? packages[`${scope}/${name}`] : undefined;
+  const entry = Array.isArray(scoped) ? scoped : packages[name];
+  if (!Array.isArray(entry) || typeof entry[0] !== 'string' || !entry[0].startsWith(`${name}@`) || entry[0].length <= name.length + 1) {
+    throw new Error(`bun.lock has no resolved version for ${name}`);
+  }
+  return entry[0].slice(name.length + 1);
+}
+
+export function checkNodeModules(dir: string): NodeModulesCheck {
+  const root = resolve(dir);
+  const result: NodeModulesCheck = { dir: root, status: 'ok', missing: [], mismatch: [], borrowed: null };
+  try {
+    const pkg = loadJson(join(root, 'package.json'));
+    if (!record(pkg)) throw new Error('invalid package.json');
+    const names = dependencyNames(pkg);
+    const lock = findLock(root, typeof pkg.name === 'string' ? pkg.name : null);
+    const declared = dependencyNames(lock.workspace);
+    for (const name of names) {
+      if (!declared.includes(name)) throw new Error(`bun.lock does not declare ${name}`);
+    }
+    const versions = new Map(names.map((name) => [name, lockedVersion(lock.packages, name, lock.scope)]));
+    // A workspace without its own node_modules resolves hoisted packages from the lock root.
+    const own = join(root, 'node_modules');
+    const modules = lock.lockRoot !== root && !lstatSync(own, { throwIfNoEntry: false }) ? join(lock.lockRoot, 'node_modules') : own;
+    try {
+      const entry = lstatSync(modules);
+      if (entry.isSymbolicLink()) {
+        const target = realpathSync(modules);
+        if (!lstatSync(target).isDirectory()) throw new Error('node_modules symlink target is not a directory');
+        result.borrowed = { target, tree: dirname(target) };
+      } else if (!entry.isDirectory()) {
+        throw new Error('node_modules is not a directory');
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      // A dangling symlink has a different cause from an absent node_modules directory.
+      if (lstatSync(modules, { throwIfNoEntry: false })?.isSymbolicLink()) throw new Error('node_modules symlink target is missing');
+      result.missing.push(...names);
+      if (names.length) result.status = 'issues';
+      return result;
+    }
+    for (const name of names) {
+      let installed: unknown;
+      const candidates = [...new Set([modules, join(lock.lockRoot, 'node_modules')])];
+      for (const base of candidates) {
+        try {
+          installed = loadJson(join(base, name, 'package.json'));
+          break;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+        }
+      }
+      if (installed === undefined) {
+        result.missing.push(name);
+        continue;
+      }
+      if (!record(installed) || typeof installed.version !== 'string') throw new Error(`invalid node_modules/${name}/package.json`);
+      const expected = versions.get(name)!;
+      if (installed.version !== expected) result.mismatch.push({ name, expected, actual: installed.version });
+    }
+    if (result.missing.length || result.mismatch.length) result.status = 'issues';
+  } catch (error) {
+    result.status = 'unreadable';
+    result.reason = error instanceof Error ? error.message : String(error);
+  } finally {
+    debug.log('doctor.node-modules', 'checked', { dir: root, missing: result.missing, mismatch: result.mismatch, borrowed: result.borrowed });
+  }
+  return result;
+}
+
+export function nodeModulesTrees(dir: string): string[] {
+  const root = resolve(dir);
+  const found = [root];
+  const skip = new Set(['node_modules', '.git', '.next', 'dist', 'build', 'out', '.elanous-test']);
+  function visit(current: string): void {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      if (!entry.isDirectory() || skip.has(entry.name) || entry.name.startsWith('.')) continue;
+      const child = join(current, entry.name);
+      const children = readdirSync(child);
+      if (children.includes('package.json')) found.push(child);
+      visit(child);
+    }
+  }
+  visit(root);
+  return found;
+}
+
+export function formatNodeModulesCheck(result: NodeModulesCheck): string {
+  const lines = [`${result.dir}: ${result.status === 'ok' ? '정상' : result.status === 'unreadable' ? '못 읽음' : '결손'}`];
+  if (result.borrowed) lines.push(`  빌린 트리: ${result.borrowed.tree} (node_modules → ${result.borrowed.target})`);
+  if (result.missing.length) lines.push(`  빠짐 ${result.missing.length}: ${result.missing.join(', ')}`);
+  if (result.mismatch.length) lines.push(`  버전 다름 ${result.mismatch.length}: ${result.mismatch.map(({ name, expected, actual }) => `${name} (${actual} != ${expected})`).join(', ')}`);
+  if (result.reason) lines.push(`  이유: ${result.reason}`);
+  return lines.join('\n');
+}

package/src/cli/flow-cli.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import { flowCard, flowTick } from '../flow/cards.js';
+
+export function registerFlowCommands(program: Command): void {
+  const flow = program.command('flow').description('Wish 카드 → 칸 → 릴리스 판');
+  flow.command('tick').description('새 Wish 카드 한 장 처리 (크론용)')
+    .action(async () => { const result = await flowTick(); console.log(result ? result.text : '새 카드 없음'); });
+  flow.command('plan <cardId>').description('카드 분할·배치 미리보기 (쓰기 없음)')
+    .requiredOption('--dry-run', '판·결정·카드 원장에 쓰지 않는다')
+    .action(async (cardId: string) => { console.log(JSON.stringify(await flowCard(cardId, {}, true))); });
+}

package/src/cli/freeze-cli.ts

@@ -0,0 +1,45 @@
+import type { Command } from 'commander';
+import { debug } from '../debug/log.js';
+import { CliUserError } from './cli-user-error.js';
+import { awaitLandingMergesDrained, disableLandingFreeze, enableLandingFreeze, readLandingFreeze, landingFreezeMessage } from '../release-loop/landing-freeze.js';
+import { pendingFrozenMerges, sweepFrozenMerges } from '../self-implement/frozen-merges.js';
+
+export function registerFreezeCommands(program: Command): void {
+  const freeze = program.command('freeze').description('착지 동결 상태 on/off/status');
+  freeze.command('on').option('--reason <text>', '동결 이유').option('--until <timestamp>', '끝 시각(타임존 포함 ISO)')
+    .option('--wait-seconds <n>', '이미 동결 검사를 지난 병합이 끝나기를 기다릴 최대 초', '600')
+    .action(async (opts: { reason?: string; until?: string; waitSeconds: string }) => {
+      const waitSeconds = Number(opts.waitSeconds);
+      if (!/^\d+$/.test(opts.waitSeconds.trim()) || !Number.isSafeInteger(waitSeconds) || waitSeconds > 86_400) {
+        throw new CliUserError(`잘못된 --wait-seconds: ${opts.waitSeconds}`, '0 이상 86400 이하의 정수 초');
+      }
+      const state = enableLandingFreeze(opts);
+      debug.log('harness.merge', 'freeze-on', state);
+      const drained = await awaitLandingMergesDrained(undefined, { timeoutMs: waitSeconds * 1000 });
+      debug.log('harness.merge', 'freeze-drain', drained);
+      console.log(landingFreezeMessage(state));
+      if (!drained.drained) {
+        console.error(`⚠ 동결 전에 시작한 병합 ${drained.pending}건이 아직 진행 중 — 끝나면 더 이상 병합이 시작되지 않는다`);
+        process.exitCode = 2;
+      }
+    });
+  freeze.command('off').description('동결을 풀고 보류된 병합을 바로 이어 한다').action(async () => {
+    disableLandingFreeze();
+    debug.log('harness.merge', 'freeze-off', {});
+    console.log('동결 해제');
+    await resume();
+  });
+  freeze.command('resume').description('동결이 풀렸으면 보류된 병합을 지금 이어 한다').action(async () => { await resume(); });
+  freeze.command('status').option('--json', '상태 JSON').action((opts: { json?: boolean }) => {
+    const state = readLandingFreeze();
+    const pending = pendingFrozenMerges();
+    if (opts.json) console.log(JSON.stringify({ frozen: state !== null, freeze: state, pendingMerges: pending }));
+    else console.log(`${state ? landingFreezeMessage(state) : '동결 없음'} · 보류 병합 ${pending}건`);
+  });
+}
+
+async function resume(): Promise<void> {
+  const result = await sweepFrozenMerges();
+  debug.log('harness.merge', 'freeze-resume', result);
+  console.log(`보류 병합 이어 하기: 병합 ${result.merged}건 · 남음 ${result.pending}건`);
+}

package/src/cli/intake-cli.ts

@@ -21,6 +21,13 @@ export interface IntakeToTasksCliDeps {
   llm?: (input: IntakeTaskInput) => Promise<string>;
 }
 
+export interface IntakeDigestCliDeps {
+  root?: string;
+  annotateLens?: (root: string, day: string) => Promise<unknown>;
+  buildDigest?: typeof import('../intake-plane/digest.js').buildIntakeDigest;
+  sendTelegram?: (text: string) => Promise<boolean>;
+}
+
 export function intakeToTasksMessages(content: string) {
   return [
     { role: 'system' as const, content: 'Interpret the supplied goal line or idea note into up to three actionable tasks. Respond only with JSON: {"tasks":[{"type":"implement|research|document|operate","title":"...","description":"...","priority":"low|medium|high","acceptanceCriteria":["..."]}],"questions":["..."]}. Each task needs a verifiable acceptance criterion; put unresolved requests in questions instead. Do not invent facts. Limit each title to 80 characters and description to 4000 characters.' },
@@ -76,6 +83,44 @@ export async function runIntakeToTasksCli(
   return runIntakeToTasks(deps.root, opts, { llm, post });
 }
 
+/** `--telegram` 다이제스트. 렌즈는 digest 를 만들기 전에 돈다. 렌즈 실패는 보고를 막지 않는다. */
+export async function runIntakeDigestCli(
+  opts: { day?: string; json?: boolean; telegram?: boolean; vault?: string; note?: string },
+  deps: IntakeDigestCliDeps = {},
+): Promise<{ sent?: boolean; empty?: boolean }> {
+  const { buildIntakeDigest, renderDigestMarkdown, renderDigestTelegram } = await import('../intake-plane/digest.js');
+  const { effectiveInstanceRoot } = await import('../instance/resolve.js');
+  const root = deps.root ?? effectiveInstanceRoot();
+  const day = opts.day ?? new Date(Date.now() + 9 * 3600_000).toISOString().slice(0, 10);
+  if (opts.telegram) {
+    const annotate = deps.annotateLens ?? (async (lensRoot, lensDay) => {
+      const { annotateIntakeLens } = await import('../intake-plane/lens.js');
+      return annotateIntakeLens(lensRoot, lensDay);
+    });
+    try { await annotate(root, day); }
+    catch (error) { debug.log('intake.lens', 'annotate-failed', { day, reason: error instanceof Error ? error.message : String(error) }); }
+  }
+  const d = (deps.buildDigest ?? buildIntakeDigest)(root, day);
+  if (opts.telegram) {
+    if (!d.absorbed.length) { console.log(`텔레그램: ${day} 흡수 0 — 보내지 않음`); return { empty: true }; }
+    const text = renderDigestTelegram(d, { ...(opts.vault ? { vaultRoot: opts.vault } : {}), ...(opts.note ? { notePath: opts.note } : {}) });
+    const sent = deps.sendTelegram
+      ? await deps.sendTelegram(text)
+      : await (async () => {
+        const { sendTelegramReport } = await import('../telegram-report.js');
+        const { getUserConfig } = await import('../user-config.js');
+        return sendTelegramReport(getUserConfig(), text, { markdown: true, kind: 'intake' });
+      })();
+    debug.log('intake.digest', 'telegram', { day, absorbed: d.absorbed.length, goals: d.goals.length, sent });
+    console.log(sent ? `텔레그램 보고 채널로 보냈다 (${day} · 흡수 ${d.absorbed.length} · 골 후보 ${d.goals.length})` : '텔레그램 보고 채널 설정이 없다(telegram.reportChannel) — 보내지 않음');
+    if (!sent) process.exitCode = 3;
+    return { sent };
+  }
+  if (opts.json) { await writeStdoutFully(JSON.stringify(d, null, 2)); return {}; }
+  await writeStdoutFully(renderDigestMarkdown(d));
+  return {};
+}
+
 export function resolveIntakeCheckRoot(
   cwd: string,
   git: typeof runGitCommand = runGitCommand,
@@ -283,23 +328,7 @@ export function registerIntakeCommands(program: Command): void {
     .option('--vault <root>', '옵시디언 볼트 뿌리 — 텔레그램 판에 노트 열기 주소를 싣는다')
     .option('--note <path>', '열기 주소가 가리킬 노트(그날 트렌드 노트)')
     .action(async (opts: { day?: string; json?: boolean; telegram?: boolean; vault?: string; note?: string }) => {
-      const { buildIntakeDigest, renderDigestMarkdown, renderDigestTelegram } = await import('../intake-plane/digest.js');
-      const { effectiveInstanceRoot } = await import('../instance/resolve.js');
-      const day = opts.day ?? new Date(Date.now() + 9 * 3600_000).toISOString().slice(0, 10);
-      const d = buildIntakeDigest(effectiveInstanceRoot(), day);
-      if (opts.telegram) {
-        if (!d.absorbed.length) { console.log(`텔레그램: ${day} 흡수 0 — 보내지 않음`); return; }
-        const { sendTelegramReport } = await import('../telegram-report.js');
-        const { getUserConfig } = await import('../user-config.js');
-        const text = renderDigestTelegram(d, { ...(opts.vault ? { vaultRoot: opts.vault } : {}), ...(opts.note ? { notePath: opts.note } : {}) });
-        const sent = await sendTelegramReport(getUserConfig(), text, { markdown: true, kind: 'intake' });
-        debug.log('intake.digest', 'telegram', { day, absorbed: d.absorbed.length, goals: d.goals.length, sent });
-        console.log(sent ? `텔레그램 보고 채널로 보냈다 (${day} · 흡수 ${d.absorbed.length} · 골 후보 ${d.goals.length})` : '텔레그램 보고 채널 설정이 없다(telegram.reportChannel) — 보내지 않음');
-        if (!sent) process.exitCode = 3;
-        return;
-      }
-      if (opts.json) { await writeStdoutFully(JSON.stringify(d, null, 2)); return; }
-      await writeStdoutFully(renderDigestMarkdown(d));
+      await runIntakeDigestCli(opts);
     });
 
   intakeCmd

package/src/cli/lesson-cli.ts

@@ -0,0 +1,108 @@
+import type { Command } from 'commander';
+import { resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+import { importLessons, scanLessonDocs } from '../lessons/lesson-import.js';
+import { LessonInputError, LessonLedger, type LessonLedgerOptions, type LessonRow, type LessonDetail } from '../lessons/lesson-ledger.js';
+
+function actor(explicit?: string): string {
+  const by = explicit?.trim() || process.env.AI_AGENT?.trim();
+  if (!by) throw new LessonInputError('--by or AI_AGENT is required');
+  return by;
+}
+
+function reportError(command: string, message: string): void {
+  const escaped = message.replace(/\r/g, '\\r').replace(/\n/g, '\\n')
+    .replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+  process.stderr.write(`lesson ${command}: ${escaped}\n`);
+  process.exitCode = 1;
+}
+
+function handle<Args extends unknown[]>(command: string, action: (...args: Args) => void): (...args: Args) => void {
+  return (...args) => {
+    try { action(...args); }
+    catch (error) {
+      if (!(error instanceof LessonInputError)) throw error;
+      reportError(command, error.message);
+    }
+  };
+}
+
+function format(row: LessonRow): string {
+  return `${row.id} · ${row.status} · ${row.occurrence_count}회 · ${row.incident} · ${row.owner}`;
+}
+
+function detail(row: LessonDetail): string {
+  return [format(row), `원인: ${row.cause}`, `처방: ${row.remedy}`, `강제: ${row.enforced_by || '없음'}`,
+    ...(row.disproof ? [`반증: ${row.disproof}`] : []),
+    '발생:', ...row.occurrences.map(o => `  ${o.at} · ${o.source}${o.note ? ` · ${o.note}` : ''}`),
+    '이력:', ...row.history.map(h => `  ${h.at} · ${h.event} · ${h.by} · ${h.detail}`)].join('\n');
+}
+
+export function registerLessonCommands(program: Command, options: LessonLedgerOptions = {}, out: Pick<Console, 'log'> = console): void {
+  const root = program.command('lesson').description('사고 · 원인 · 처방 · 재발 교훈 원장');
+  const ledger = () => new LessonLedger(options);
+  const emit = (value: unknown, json: boolean | undefined, text: string) => out.log(json ? JSON.stringify(value) : text);
+  root.command('import').description('INCIDENT·FINDING 문서 교훈 미리 보기 (기본값); --apply 로 적재')
+    .option('--apply', '원장에 적재').option('--json', 'JSON 출력').option('--by <name>', '기록자 (기본 AI_AGENT)')
+    .action(handle('import', (o: { apply?: boolean; json?: boolean; by?: string }) => {
+      const by = actor(o.by);
+      const scan = scanLessonDocs(resolve(process.cwd()));
+      const imported = importLessons(ledger(), scan.items, { apply: !!o.apply, by });
+      const result = { files: scan.files, items: imported.items, skipped: [...scan.skipped, ...imported.skipped],
+        emptyCause: imported.items.filter(item => !item.cause).length,
+        emptyRemedy: imported.items.filter(item => !item.remedy).length, written: imported.written };
+      if (o.apply) debug.log('lessons.import', 'applied', { files: result.files, items: result.items.length,
+        skipped: result.skipped.length, written: result.written });
+      emit(result, o.json, `파일 ${result.files} · 넣을 교훈 ${result.items.length} · 건너뜀 ${result.skipped.length} · 빈 원인 ${result.emptyCause} · 빈 처방 ${result.emptyRemedy} · 기록 ${result.written}`);
+    }));
+  root.command('page').description('교훈 원장에서 핸드북 페이지 생성')
+    .option('--out <file>', '출력 파일').option('--json', 'JSON 출력')
+    .action(async (o: { out?: string; json?: boolean }) => {
+      try {
+        const { generateHandbookPage } = await import('../../scripts/lessons/handbook-page.js');
+        const result = generateHandbookPage({ stateDir: options.stateDir, out: o.out });
+        emit(result, o.json, 'skipped' in result
+          ? '교훈 페이지: 건너뜀(원장 비어 있음)'
+          : `교훈 페이지: ${result.out} · 총 ${result.total} · 강제 자리 없음 ${result.unenforced}`);
+      } catch (error) {
+        reportError('page', error instanceof Error ? error.message : String(error));
+      }
+    });
+  root.command('add <id>').requiredOption('--incident <text>').requiredOption('--cause <text>')
+    .requiredOption('--remedy <text>').requiredOption('--owner <name>').requiredOption('--source <path>')
+    .option('--enforced-by <paths>').option('--disproof <command>').option('--by <name>')
+    .action(handle('add', (id: string, o: { incident: string; cause: string; remedy: string; owner: string; source: string; enforcedBy?: string; disproof?: string; by?: string }) => {
+      const by = actor(o.by);
+      const row = ledger().add({ id, incident: o.incident, cause: o.cause, remedy: o.remedy, owner: o.owner,
+        source: o.source, by, ...(o.enforcedBy !== undefined ? { enforcedBy: o.enforcedBy } : {}),
+        ...(o.disproof !== undefined ? { disproof: o.disproof } : {}) });
+      emit(row, false, format(row));
+    }));
+  root.command('recur <id>').requiredOption('--source <path>').option('--note <text>').option('--by <name>')
+    .action(handle('recur', (id: string, o: { source: string; note?: string; by?: string }) => {
+      const row = ledger().recur(id, { source: o.source, note: o.note ?? '', by: actor(o.by) });
+      emit(row, false, format(row));
+    }));
+  root.command('enforce <id>').requiredOption('--enforced-by <paths>').option('--by <name>')
+    .action(handle('enforce', (id: string, o: { enforcedBy: string; by?: string }) => {
+      const row = ledger().enforce(id, { enforcedBy: o.enforcedBy, by: actor(o.by) });
+      emit(row, false, format(row));
+    }));
+  root.command('promote <id>').requiredOption('--rule <path>').option('--by <name>')
+    .action(handle('promote', (id: string, o: { rule: string; by?: string }) => {
+      const row = ledger().promote(id, { rulePath: o.rule, by: actor(o.by) });
+      emit(row, false, format(row));
+    }));
+  root.command('find <query>').option('--json').action(handle('find', (query: string, o: { json?: boolean }) => {
+    const rows = ledger().find(query);
+    emit(rows, o.json, rows.length ? rows.map(format).join('\n') : '교훈 0건');
+  }));
+  root.command('show <id>').option('--json').action(handle('show', (id: string, o: { json?: boolean }) => {
+    const row = ledger().get(id);
+    emit(row, o.json, detail(row));
+  }));
+  root.command('candidates').option('--json').action(handle('candidates', (o: { json?: boolean }) => {
+    const rows = ledger().candidates();
+    emit(rows, o.json, rows.length ? rows.map(format).join('\n') : '승격 후보 0건');
+  }));
+}