elanous 0.2.13 → 0.2.14

package/scripts/expose-rubric-check.ts

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

package/scripts/expose-rubric-suggest.ts

@@ -0,0 +1,163 @@
+#!/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 { 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): 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 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: '누출 표식 없음' };
+    });
+    const brand = measure(() => {
+      const result = checkBrand('public-docs', [absolute]);
+      if (result.missing || result.files !== 1 || result.rules === 0) return unmeasured('브랜드 규칙 없음 또는 파일 검사 실패');
+      const ids = [...new Set(result.findings.map((finding) => finding.id))].slice(0, 3);
+      return ids.length
+        ? { status: 'fail', reason: `브랜드 규칙: ${ids.join(', ')}` }
+        : { status: 'pass', reason: '브랜드 규칙 위반 없음' };
+    });
+    return { path, criteria: { reproducible, confidential, brand } };
+  });
+  const statuses = results.flatMap((item) => KEYS.map((key) => item.criteria[key].status));
+  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;
+  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 === '--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);
+  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})` : ''}`).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/lessons/handbook-page.ts

@@ -0,0 +1,85 @@
+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 section(title: string, rows: LessonRow[], ledger: LessonLedger, kind: LessonStatus): string[] {
+  const lines = [`## ${title}`, ''];
+  if (!rows.length) return [...lines, '없음', ''];
+  for (const row of rows) {
+    const last = ledger.get(row.id).occurrences.at(-1);
+    lines.push(`### ${inlineText(row.id)} — ${inlineText(row.incident)}`,
+      `- 원인: ${inlineText(row.cause)}`,
+      `- 처방: ${inlineText(row.remedy)}`,
+      `- 재발: ${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/release-loop/gate-node.ts

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { debug } from '../../src/debug/log.js';
+import { landingFreezeMessage, readLandingFreeze } from '../../src/release-loop/landing-freeze.js';
 import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
 import { getElanousConfigDirOverride } from '../../src/elanous-config-dir.js';
 import { diffFailures, junitFailures, parseFailures } from './gate-diff';
@@ -32,6 +33,7 @@ export interface GateRunner {
 }
 export interface GateOptions {
   commit: string;
+  forceFreeze?: boolean;
   version: string;
   baselineVersion?: string;
   baselineCommit?: string;
@@ -537,6 +539,12 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
   const start = Date.now();
   const explicitConfig = getElanousConfigDirOverride();
   const root = explicitConfig ? effectiveInstanceRoot() : (opts.instanceRoot ?? effectiveInstanceRoot());
+  // The freeze is read from the same root the gate runs in (a config-dir override must not move it elsewhere).
+  const frozen = readLandingFreeze(root);
+  if (frozen) {
+    debug.log('release.run', opts.forceFreeze ? 'freeze-forced' : 'frozen', { version: opts.version, reason: frozen.reason, until: frozen.until, node: 'gate' });
+    if (!opts.forceFreeze) throw new Error(landingFreezeMessage(frozen));
+  }
   const ledger = explicitConfig ? root : (opts.ledgerRoot ?? releaseLedgerRoot());
   const roots = [...new Set([ledger, root])];
   const cachedBaseline = (version: string, commit: string) => {
@@ -766,6 +774,7 @@ export function parseOptions(args: string[], env: NodeJS.ProcessEnv): GateOption
     commit: typeof fromGraph.commit === 'string' ? fromGraph.commit : '',
     version: typeof fromGraph.version === 'string' ? fromGraph.version : '',
     baselineVersion: typeof fromGraph.previousVersion === 'string' ? fromGraph.previousVersion : undefined,
+    forceFreeze: fromGraph.forceFreeze === true,
     baselineCommit: typeof fromGraph.previousCommit === 'string' ? fromGraph.previousCommit : undefined,
     remote: typeof fromGraph.gateRemote === 'string' ? fromGraph.gateRemote : undefined,
     remoteMirror: typeof fromGraph.gateRemoteMirror === 'string' ? fromGraph.gateRemoteMirror : undefined,

package/scripts/release-loop/publish-node.ts

@@ -3,6 +3,8 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { WARNING_ONLY } from './auto-approve-node.js';
+import { beginLandingMerge, landingFreezeMessage } from '../../src/release-loop/landing-freeze.js';
+import { debug } from '../../src/debug/log.js';
 import { errorResult, finishNode, lastResult, nodeOutput, readGraphContext, runCommand, type CommandRunner } from './node-verdict.js';
 
 export function publicNotes(markdown: string, pages: { pages: Array<{ id: string; slug?: string; source?: string }> }): string {
@@ -64,7 +66,18 @@ export function runPublish(run: CommandRunner = runCommand) {
   try {
     const file = join(dir, 'notes.md');
     writeFileSync(file, body);
-    const published = run('bun', ['bin/elanous.mjs', 'release', 'publish', '--dir', out, '--notes-file', file, '--yes', '--json']);
+    // Same in-flight marker as merges: `freeze on` waits for a publication that already passed this check.
+    // Unlike a merge, a frozen publication is not queued: it fails, and the release run is run again after `freeze off`.
+    const landing = beginLandingMerge();
+    const frozen = landing.frozen;
+    if (frozen) {
+      landing.end(); // already released by beginLandingMerge when frozen; kept explicit so no path leaves a marker
+      debug.log('release.run', context.input.forceFreeze === true ? 'freeze-forced' : 'frozen', { version, reason: frozen.reason, until: frozen.until, node: 'publish' });
+      if (context.input.forceFreeze !== true) return { outcome: 'fail' as const, verdict: 'fail' as const, summary: `publish blocked: ${landingFreezeMessage(frozen)}` };
+    }
+    let published: ReturnType<typeof run>;
+    try { published = run('bun', ['bin/elanous.mjs', 'release', 'publish', '--dir', out, '--notes-file', file, '--yes', '--json']); }
+    finally { landing.end(); }
     if (published.stderr) process.stderr.write(published.stderr);
     const result = lastResult(published);
     if (published.status === 1) return { outcome: 'fail' as const, verdict: 'fail' as const, summary: `release publish failed: ${result?.error ?? published.stderr.trim()}` };

package/scripts/release-loop/unattended-release.ts

@@ -4,6 +4,8 @@ import { getElanousConfigDirOverride } from '../../src/elanous-config-dir.js';
 import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
 import { userConfigPath } from '../../src/user-config.js';
 import { checklistGate } from '../../src/release-loop/checklist.js';
+import { isLandingFreezeRefusal, readLandingFreeze, LandingFrozenError } from '../../src/release-loop/landing-freeze.js';
+import { debug } from '../../src/debug/log.js';
 import { runGraph, type GraphRunState } from '../../src/graph-runner/runner.js';
 
 const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
@@ -26,6 +28,7 @@ export interface ReleaseRunInput extends ReleaseLoopConfig {
   previousVersion: string;
   cutCommit?: string;
   gatePodPool: string;
+  forceFreeze?: boolean;
 }
 
 export interface UnattendedReleaseDeps {
@@ -34,6 +37,7 @@ export interface UnattendedReleaseDeps {
   configPath?: string;
   graph?: (path: string, options: { input: ReleaseRunInput }) => Promise<GraphRunState>;
   checklist?: typeof checklistGate;
+  freezeRoot?: string;
 }
 
 function compareVersions(a: string, b: string): number {
@@ -83,13 +87,31 @@ export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDep
 
 /** Fail closed at the entry boundary, before any graph node can change a release. */
 export async function runUnattendedRelease(
-  opts: { version: string; dryRun?: boolean; cutCommit?: string },
+  opts: { version: string; dryRun?: boolean; cutCommit?: string; forceFreeze?: boolean },
   deps: UnattendedReleaseDeps = {},
 ): Promise<{ input: ReleaseRunInput; dryRun: boolean; state?: GraphRunState }> {
+  if (!opts.dryRun) {
+    const frozen = readLandingFreeze(deps.freezeRoot);
+    if (frozen) {
+      debug.log('release.run', opts.forceFreeze ? 'freeze-forced' : 'frozen', { version: opts.version, reason: frozen.reason, until: frozen.until });
+      if (!opts.forceFreeze) throw new LandingFrozenError(frozen);
+    }
+  }
   const input = buildReleaseRunInput(opts.version, deps, opts.cutCommit);
+  if (opts.forceFreeze) input.forceFreeze = true;
   if (opts.dryRun) return { input, dryRun: true };
   const gate = (deps.checklist ?? checklistGate)(opts.version);
   if (!gate.ok) throw new Error(`release checklist blocked: ${[...gate.red, ...gate.undecided, ...gate.blocked].join(', ')}`);
+  const beforeGraph = readLandingFreeze(deps.freezeRoot);
+  if (beforeGraph && !opts.forceFreeze) throw new LandingFrozenError(beforeGraph);
   const state = await (deps.graph ?? runGraph)(GRAPH, { input });
+  // A freeze switched on while the graph ran stops gate or publish inside it. Only a failed gate/publish node whose own
+  // record is the freeze refusal is reported as the freeze; any other failure keeps its own reason.
+  if (state.status === 'failed' && !opts.forceFreeze) {
+    const refused = (state.nodes ?? []).find((node) => (node.nodeId === 'gate' || node.nodeId === 'publish') && !node.ok
+      && isLandingFreezeRefusal(`${typeof node.output === 'string' ? node.output : JSON.stringify(node.output ?? '')} ${node.error ?? ''}`));
+    const during = refused ? readLandingFreeze(deps.freezeRoot) : null;
+    if (refused) throw new LandingFrozenError(during ?? { reason: 'frozen during the run', startedAt: new Date().toISOString(), until: null, by: 'release-run' });
+  }
   return { input, dryRun: false, state };
 }