elanous 0.2.35 → 0.2.37

package/scripts/measure-nl-routing-corpus.ts

@@ -74,6 +74,194 @@ export function resolveCorpusRunSafety(
   return { observeOnly, bypassed, exposedMutatingTools };
 }
 
+// ── NL-UTTERANCE-PATTERNS v5 — 경로·복합 처리 채점 입구 ─────────────────────
+//
+// 칸의 판정선은 수가 아니라 «판정선»이다: 가림 예시 누출 0 · 패턴 ≥12 · v5 채점 문항 ≥25.
+// 패턴은 발화 어휘 신호(경로 지정 / 복합 요청)이고, 문항은 그 패턴이 실제로 발화하는지
+// 스스로 증명한다(선언 패턴이 프롬프트에서 안 잡히면 mismatch 로 판정 실패).
+// ⛔ 가림 예시(masking examples)는 «채점되지 않는» 홀드아웃 발화다 — 문항·패턴에 새면 판정선이 무너진다.
+
+export interface NlRoutingToolExpectation {
+  readonly tool: string;
+  readonly minCount?: number;
+}
+
+export interface NlUtterancePattern {
+  readonly id: string;
+  readonly handles: 'path' | 'compound';
+  readonly signal: RegExp;
+}
+
+export const NL_UTTERANCE_PATTERNS: readonly NlUtterancePattern[] = [
+  { id: 'path-single-read', handles: 'path', signal: /(?:읽어\s*줘|열어\s*줘)/u },
+  { id: 'path-relative', handles: 'path', signal: /(?:상대\s*경로|\.\/)/u },
+  { id: 'path-absolute', handles: 'path', signal: /(?:절대\s*경로|\/tmp\/|\/home\/)/u },
+  { id: 'path-home-config', handles: 'path', signal: /(?:~\/\.elanous|홈\s*디렉터리)/u },
+  { id: 'path-directory-scope', handles: 'path', signal: /(?:디렉터리\s*안에서|그\s*폴더\s*안)/u },
+  { id: 'path-symbol-search', handles: 'path', signal: /어디서\s*쓰/u },
+  { id: 'path-file-glob', handles: 'path', signal: /(?:목록|어떤\s*파일들)/u },
+  { id: 'path-nested-file', handles: 'path', signal: /하위\s*디렉터리[\s\S]*파일/u },
+  { id: 'compound-read-then-grep', handles: 'compound', signal: /읽고\s*나서[\s\S]*찾/u },
+  { id: 'compound-grep-then-read', handles: 'compound', signal: /찾아서\s*그\s*파일/u },
+  { id: 'compound-glob-then-read', handles: 'compound', signal: /목록[\s\S]*첫\s*파일/u },
+  { id: 'compound-two-file-compare', handles: 'compound', signal: /두\s*파일[\s\S]*비교/u },
+  { id: 'compound-three-way', handles: 'compound', signal: /읽고[\s\S]*찾고[\s\S]*목록/u },
+  { id: 'compound-search-then-confirm', handles: 'compound', signal: /검색해서[\s\S]*전부\s*확인/u },
+];
+
+export interface NlRoutingV5Question {
+  readonly id: string;
+  readonly pattern: string;
+  readonly prompt: string;
+  readonly expects: readonly NlRoutingToolExpectation[];
+}
+
+const single = (tool: string): readonly NlRoutingToolExpectation[] => [{ tool }];
+
+export const NL_ROUTING_V5_QUESTIONS: readonly NlRoutingV5Question[] = [
+  { id: 'v5-01', pattern: 'path-single-read', prompt: 'src/domains/surface-events.ts 파일 읽어 줘', expects: single('Read') },
+  { id: 'v5-02', pattern: 'path-single-read', prompt: 'scripts/measure-nl-routing-corpus.ts 읽어 줘', expects: single('Read') },
+  { id: 'v5-03', pattern: 'path-relative', prompt: 'src/cli/self-utterances-cli.ts 상대 경로로 열어 줘', expects: single('Read') },
+  { id: 'v5-04', pattern: 'path-relative', prompt: './scripts/lib/nl-routing-screening.ts 상대 경로 파일 보여줘', expects: single('Read') },
+  { id: 'v5-05', pattern: 'path-absolute', prompt: '/home/ubuntu/.elanous/logs 절대 경로 확인해 줘', expects: single('Read') },
+  { id: 'v5-06', pattern: 'path-absolute', prompt: '/tmp/nl-routing/corpus.json 절대 경로 읽어 줘', expects: single('Read') },
+  { id: 'v5-07', pattern: 'path-home-config', prompt: '~/.elanous 아래 설정 파일 읽어 줘', expects: single('Read') },
+  { id: 'v5-08', pattern: 'path-home-config', prompt: '홈 디렉터리의 elanous 설정 읽어 줘', expects: single('Read') },
+  { id: 'v5-09', pattern: 'path-directory-scope', prompt: 'src/domains 디렉터리 안에서 발화 origin 찾아 줘', expects: single('Grep') },
+  { id: 'v5-10', pattern: 'path-directory-scope', prompt: '그 폴더 안에서 querySurfaceUtterances 를 검색해 줘', expects: single('Grep') },
+  { id: 'v5-11', pattern: 'path-symbol-search', prompt: 'recordInboundTurn 이 어디서 쓰이는지 알려 줘', expects: single('Grep') },
+  { id: 'v5-12', pattern: 'path-symbol-search', prompt: 'classifyTier 어디서 쓰는지 찾아 줘', expects: single('Grep') },
+  { id: 'v5-13', pattern: 'path-file-glob', prompt: 'scripts 아래 측정 스크립트 목록 뽑아 줘', expects: single('Glob') },
+  { id: 'v5-14', pattern: 'path-file-glob', prompt: '어떤 파일들 *.test.ts 이 있는지 보여 줘', expects: single('Glob') },
+  { id: 'v5-15', pattern: 'path-nested-file', prompt: 'src/domains 하위 디렉터리의 파일 하나 읽어 줘', expects: single('Read') },
+  { id: 'v5-16', pattern: 'path-nested-file', prompt: 'scripts/lib 하위 디렉터리 파일 읽어 줘', expects: single('Read') },
+  { id: 'v5-17', pattern: 'compound-read-then-grep', prompt: 'src/domains/surface-events.ts 읽고 나서 호출부 찾아 줘', expects: [{ tool: 'Read' }, { tool: 'Grep' }] },
+  { id: 'v5-18', pattern: 'compound-read-then-grep', prompt: 'docs/goal-context README 읽고 나서 참조 찾아 줘', expects: [{ tool: 'Read' }, { tool: 'Grep' }] },
+  { id: 'v5-19', pattern: 'compound-grep-then-read', prompt: 'recordInboundTurn 찾아서 그 파일 읽어 줘', expects: [{ tool: 'Grep' }, { tool: 'Read' }] },
+  { id: 'v5-20', pattern: 'compound-grep-then-read', prompt: 'querySurfaceUtterances 찾아서 그 파일 열어 줘', expects: [{ tool: 'Grep' }, { tool: 'Read' }] },
+  { id: 'v5-21', pattern: 'compound-glob-then-read', prompt: 'src/domains 목록 뽑고 첫 파일 읽어 줘', expects: [{ tool: 'Glob' }, { tool: 'Read' }] },
+  { id: 'v5-22', pattern: 'compound-glob-then-read', prompt: 'scripts/lib 목록 보고 첫 파일 읽어 줘', expects: [{ tool: 'Glob' }, { tool: 'Read' }] },
+  { id: 'v5-23', pattern: 'compound-two-file-compare', prompt: 'surface-events.ts 와 provenance.ts 두 파일 비교해 줘', expects: [{ tool: 'Read', minCount: 2 }] },
+  { id: 'v5-24', pattern: 'compound-two-file-compare', prompt: 'measure-nl-routing-corpus.ts 와 nl-routing-measurement.ts 두 파일 비교해 줘', expects: [{ tool: 'Read', minCount: 2 }] },
+  { id: 'v5-25', pattern: 'compound-three-way', prompt: 'surface-events.ts 읽고 지난 기록 찾고 폴더 목록도 뽑아 줘', expects: [{ tool: 'Read' }, { tool: 'Grep' }, { tool: 'Glob' }] },
+  { id: 'v5-26', pattern: 'compound-three-way', prompt: 'self-utterances-cli.ts 읽고 origin 찾고 scripts 목록도 뽑아 줘', expects: [{ tool: 'Read' }, { tool: 'Grep' }, { tool: 'Glob' }] },
+  { id: 'v5-27', pattern: 'compound-search-then-confirm', prompt: 'origin 표기를 검색해서 관련 파일 전부 확인해 줘', expects: [{ tool: 'Grep' }, { tool: 'Read' }] },
+  { id: 'v5-28', pattern: 'compound-search-then-confirm', prompt: 'v5 문항을 검색해서 전부 확인해 줘', expects: [{ tool: 'Grep' }, { tool: 'Read' }] },
+];
+
+/** 채점에 쓰이지 않는 홀드아웃 발화 — 문항·패턴에 «한 글자도» 새면 안 된다. */
+export const NL_ROUTING_MASKING_EXAMPLES: readonly string[] = [
+  '이 저장소에서 라우팅 규칙이 어디에 적혀 있는지 알려 줘',
+  '방금 만든 스크립트랑 예전 스크립트를 나란히 놓고 틀린 곳만 짚어 줘',
+  '설정 폴더 아래 있는 재정의 항목만 훑어 줘',
+  '테스트가 실제로 도는 파일과 그렇지 않은 파일을 갈라 줘',
+  '복합 요청: 먼저 근거를 모으고 그다음에 요약을 만들어 줘',
+  '이 변경이 어떤 진입점을 타는지 확인해 줘',
+  '오늘 새로 생긴 산출물만 모아서 보여 줘',
+  '지난 실행에서 실패한 문항을 다시 재 보고 싶어',
+];
+
+export const NL_ROUTING_V5_THRESHOLDS = { maskingLeaks: 0, patterns: 12, scored: 25 } as const;
+
+function normalizeUtterance(text: string): string {
+  return text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+}
+
+/** 발화에서 발화하는 패턴 id 목록(패턴 정의가 장식이 아님을 문항 단위로 확인하는 자). */
+export function matchNlUtterancePatterns(prompt: string): string[] {
+  return NL_UTTERANCE_PATTERNS.filter((pattern) => pattern.signal.test(prompt)).map((pattern) => pattern.id);
+}
+
+/** 가림 예시 누출 검사 — 문항 프롬프트·패턴 id 어디에도 홀드아웃 발화가 겹치면 누출이다. */
+export function maskingExampleLeaks(): string[] {
+  const prompts = NL_ROUTING_V5_QUESTIONS.map((question) => ({ id: question.id, text: normalizeUtterance(question.prompt) }));
+  const patternIds = NL_UTTERANCE_PATTERNS.map((pattern) => normalizeUtterance(pattern.id));
+  const leaks: string[] = [];
+  NL_ROUTING_MASKING_EXAMPLES.forEach((example, index) => {
+    const normalized = normalizeUtterance(example);
+    if (!normalized) return;
+    const hit = prompts.find((prompt) => prompt.text.includes(normalized) || normalized.includes(prompt.text));
+    if (hit) { leaks.push(`example${index + 1}:${hit.id}`); return; }
+    if (patternIds.some((id) => id.includes(normalized))) leaks.push(`example${index + 1}:pattern`);
+  });
+  return leaks;
+}
+
+export interface NlRoutingV5Score {
+  readonly questions: number;
+  readonly pathQuestions: number;
+  readonly compoundQuestions: number;
+  readonly patterns: number;
+  readonly pathPatterns: number;
+  readonly compoundPatterns: number;
+  readonly scored: number;
+  readonly passed: number;
+  readonly failed: readonly string[];
+  readonly failedRuns: number;
+  readonly maskingLeaks: readonly string[];
+  readonly patternMismatches: readonly string[];
+  readonly thresholdsMet: boolean;
+  readonly verdict: 'pass' | 'fail';
+}
+
+function expectationsMet(expects: readonly NlRoutingToolExpectation[], breakdown: Record<string, number>): boolean {
+  return expects.every((expectation) => (breakdown[expectation.tool] ?? 0) >= (expectation.minCount ?? 1));
+}
+
+/** v5 28문항을 «생산 runEvalPrompt seam» 으로 그대로 돌려 경로·복합 처리를 채점한다. */
+export async function scoreNlRoutingV5(opts: {
+  runPrompt: typeof runEvalPrompt;
+  surface: EvalPromptToolSurface;
+  cwd: string;
+  maxTurns?: number;
+}): Promise<NlRoutingV5Score> {
+  const maxTurns = opts.maxTurns ?? 6;
+  const matched = new Set<string>();
+  const failed: string[] = [];
+  const patternMismatches: string[] = [];
+  let scored = 0;
+  let passed = 0;
+  let failedRuns = 0;
+  for (const question of NL_ROUTING_V5_QUESTIONS) {
+    if (!matchNlUtterancePatterns(question.prompt).includes(question.pattern)) {
+      patternMismatches.push(question.id);
+    }
+    try {
+      const result = await opts.runPrompt({ prompt: question.prompt, maxTurns, tools: opts.surface, silent: true, cwd: opts.cwd });
+      scored += 1;
+      if (expectationsMet(question.expects, result.toolBreakdown)) {
+        passed += 1;
+        matched.add(question.pattern);
+      } else failed.push(question.id);
+    } catch {
+      failedRuns += 1;
+    }
+  }
+  const matchedPatterns = NL_UTTERANCE_PATTERNS.filter((pattern) => matched.has(pattern.id));
+  const leaks = maskingExampleLeaks();
+  const thresholdsMet = scored >= NL_ROUTING_V5_THRESHOLDS.scored
+    && passed >= NL_ROUTING_V5_THRESHOLDS.scored
+    && matchedPatterns.length >= NL_ROUTING_V5_THRESHOLDS.patterns
+    && leaks.length <= NL_ROUTING_V5_THRESHOLDS.maskingLeaks
+    && patternMismatches.length === 0;
+  return {
+    questions: NL_ROUTING_V5_QUESTIONS.length,
+    pathQuestions: NL_ROUTING_V5_QUESTIONS.filter((question) => NL_UTTERANCE_PATTERNS.find((pattern) => pattern.id === question.pattern)?.handles === 'path').length,
+    compoundQuestions: NL_ROUTING_V5_QUESTIONS.filter((question) => NL_UTTERANCE_PATTERNS.find((pattern) => pattern.id === question.pattern)?.handles === 'compound').length,
+    patterns: matchedPatterns.length,
+    pathPatterns: matchedPatterns.filter((pattern) => pattern.handles === 'path').length,
+    compoundPatterns: matchedPatterns.filter((pattern) => pattern.handles === 'compound').length,
+    scored,
+    passed,
+    failed,
+    failedRuns,
+    maskingLeaks: leaks,
+    patternMismatches,
+    thresholdsMet,
+    verdict: thresholdsMet ? 'pass' : 'fail',
+  };
+}
+
 function formatMachineLoad(load: MachineLoad): string {
   return `부하 ${load.loadAverage.map((value) => value.toFixed(2)).join('/')}, ${load.coreCount}코어`;
 }
@@ -110,7 +298,7 @@ export async function main(
   const unknownArgs = process.argv.slice(2);
   if (unknownArgs.length) {
     throw new Error(`이 러너는 인자를 받지 않는다 — 모르는 인자 ${unknownArgs.join(' ')}. `
-      + '설정은 환경변수다: CORPUS_CWD=<툴 작업 디렉토리> · CORPUS_PATH=<코퍼스 JSON 경로> · CORPUS_OUT=<원자료 JSON 경로> · CORPUS_TIERS · CORPUS_IDS · CORPUS_REPEATS · CORPUS_BUDGETS · CORPUS_CONCURRENCY');
+      + '설정은 환경변수다: CORPUS_CWD=<툴 작업 디렉토리> · CORPUS_PATH=<코퍼스 JSON 경로> · CORPUS_OUT=<원자료 JSON 경로> · CORPUS_TIERS · CORPUS_IDS · CORPUS_REPEATS · CORPUS_BUDGETS · CORPUS_CONCURRENCY · CORPUS_V5=1 (v5 28문항 경로·복합 처리 채점)');
   }
   const corpusCwd = resolveCorpusCwdFromEnv();
   const requestedSurface = process.env.CORPUS_SURFACE;
@@ -209,13 +397,30 @@ export async function main(
     console.log(`  실패 분류 — ①미발사 ${noFire} · ②툴 오선택 ${wrong} · ③거부툴 선택 ${rejected} (측정 가능 실행 ${measurableRecords.length})\n`);
   }
 
+  // ★ v5 28문항 경로·복합 처리 채점 — 같은 러너·같은 runEvalPrompt seam 으로 채점한다
+  //   (다른 자로 재면 판정선과 비교 불가 · 형태 F3). 임계 미달은 «조용한 0» 이 아니라 거부다.
+  let v5: NlRoutingV5Score | undefined;
+  if (process.env.CORPUS_V5 === '1') {
+    v5 = await scoreNlRoutingV5({ runPrompt, surface, cwd: corpusCwd, maxTurns: budgets[0] });
+    console.log(`[v5] patterns ${v5.patterns} (path ${v5.pathPatterns} · compound ${v5.compoundPatterns}) · 문항 ${v5.questions} (path ${v5.pathQuestions} · compound ${v5.compoundQuestions}) · 채점 ${v5.scored} · 통과 ${v5.passed} · 실패 ${v5.failed.length ? v5.failed.join(',') : '(없음)'} · 실행 실패 ${v5.failedRuns} · masking-leak ${v5.maskingLeaks.length} ${v5.maskingLeaks.length ? v5.maskingLeaks.join(',') : '(없음)'} · pattern-mismatch ${v5.patternMismatches.length ? v5.patternMismatches.join(',') : '(없음)'} · 판정 ${v5.verdict}`);
+    if (!v5.thresholdsMet) {
+      throw new Error(
+        `NL routing v5 entrance stopped: 채점 문항 ${v5.scored} < ${NL_ROUTING_V5_THRESHOLDS.scored}`
+        + ` 또는 올바른 라우팅 ${v5.passed} < ${NL_ROUTING_V5_THRESHOLDS.scored}`
+        + ` 또는 패턴 ${v5.patterns} < ${NL_ROUTING_V5_THRESHOLDS.patterns}`
+        + ` 또는 가림 예시 누출 ${v5.maskingLeaks.length} > ${NL_ROUTING_V5_THRESHOLDS.maskingLeaks}`
+        + ` 또는 패턴 미발화 ${v5.patternMismatches.length}.`,
+      );
+    }
+  }
+
   const errored = jobs.length - records.length;
   if (errored > 0) console.log(`⚠️ 실행 실패 ${errored}건은 측정 가능 표본의 누락 실행이며 관측된 k/n 분모에서 제외했다.`);
   const out = process.env.CORPUS_OUT;
   // ⛔⭐ 최상위 `machineLoad` 는 **런 시작 스냅샷**이고 이름은 그대로 둔다(기존 원자료가 그 뜻으로 쓰였다).
   //    레코드의 실제 부하는 `records[].loadAtStart`·`loadAtEnd` 다(`MEAS-T15` · 타입 주석에 표로 있다).
   //    ⛔ 별칭 필드를 나란히 두지 않는다 — 소비자 없는 중복은 **죽은 공개 필드**다(리뷰 must-fix 수용).
-  if (out) writeFileSync(out, JSON.stringify({ surface, repeats, budgets, machineLoad: load, observeOnly: safety.observeOnly, unsafeBypass: safety.bypassed, exposedMutatingTools: safety.exposedMutatingTools, surfaceToolNames, unmeasurableIds, records }, null, 2));
+  if (out) writeFileSync(out, JSON.stringify({ surface, repeats, budgets, machineLoad: load, observeOnly: safety.observeOnly, unsafeBypass: safety.bypassed, exposedMutatingTools: safety.exposedMutatingTools, surfaceToolNames, unmeasurableIds, ...(v5 ? { v5 } : {}), records }, null, 2));
 }
 
 if (import.meta.main) await main();

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

@@ -1,9 +1,10 @@
 #!/usr/bin/env bun
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn, spawnSync, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from 'node:child_process';
 import { isAbsolute, basename, dirname, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { debug } from '../../src/debug/log.js';
 import { effectiveInstanceRoot } from '../../src/instance/resolve.js';
 import type { ReleaseManifest } from '../../src/release-loop/manifest.js';
@@ -20,6 +21,185 @@ interface DocsResult {
   error?: string;
   branch?: string;
   worktree?: string;
+  translationFallbacks?: number;
+  artifactOwner?: { runId: string; attempt: number; localBackup?: string; remoteBackup?: string; remoteHead?: string };
+}
+
+type TranslationRunner = (line: string) => string;
+type AskSpawn = (command: string, args: string[], options: SpawnSyncOptionsWithStringEncoding) => SpawnSyncReturns<string>;
+
+const HANGUL = /[\uac00-\ud7a3]/;
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+function splitMarkdownPrefix(raw: string): { prefix: string; text: string } {
+  let cursor = /^[\t ]*/.exec(raw)![0].length;
+  let sawHeading = false;
+  while (cursor < raw.length) {
+    const rest = raw.slice(cursor);
+    const token = /^>[\t ]*/.exec(rest)
+      ?? /^(?:[-+*]|\d+[.)])[\t ]+/.exec(rest)
+      ?? (!sawHeading ? /^#{1,6}[\t ]+/.exec(rest) : null);
+    if (!token) break;
+    if (token[0][0] === '#') sawHeading = true;
+    cursor += token[0].length;
+  }
+  return { prefix: raw.slice(0, cursor), text: raw.slice(cursor) };
+}
+
+function markdownFenceLine(raw: string, closing = false): { marker: string; quoteDepth: number; listDepth: number } | undefined {
+  let cursor = 0;
+  const columns = (start: number): { end: number; width: number } => {
+    let end = start;
+    let width = 0;
+    while (raw[end] === ' ' || raw[end] === '\t') {
+      width = raw[end] === '\t' ? width + (4 - (width % 4)) : width + 1;
+      end++;
+    }
+    return { end, width };
+  };
+  const initialIndent = columns(cursor);
+  if (initialIndent.width > 3) return undefined;
+  cursor = initialIndent.end;
+  let quoteDepth = 0;
+  let listDepth = 0;
+  while (cursor < raw.length) {
+    const before = columns(cursor);
+    if (before.width > 3) break;
+    const tokenStart = before.end;
+    if (raw[tokenStart] === '>') {
+      cursor = tokenStart + 1;
+      if (raw[cursor] === ' ') cursor++;
+      quoteDepth++;
+      continue;
+    }
+    const list = /^(?:[-+*]|\d+[.)])[\t ]+/.exec(raw.slice(tokenStart));
+    if (list) {
+      cursor = tokenStart + list[0].length;
+      listDepth++;
+      continue;
+    }
+    break;
+  }
+  const contentIndent = columns(cursor);
+  if (contentIndent.width > 3) return undefined;
+  cursor = contentIndent.end;
+  const marker = /^(?:`{3,}|~{3,})/.exec(raw.slice(cursor))?.[0];
+  if (!marker) return undefined;
+  const tail = raw.slice(cursor + marker.length);
+  if (closing && !/^[\t ]*$/.test(tail)) return undefined;
+  return { marker, quoteDepth, listDepth };
+}
+
+/**
+ * The CLI that answers the translation boundary. `ELANOUS_RELEASE_ASK_BIN` lets a fake-bin stand in at
+ * this child-process boundary (offline runs, tests) without touching the model or the operator's config.
+ */
+function askCliPath(env: NodeJS.ProcessEnv): string {
+  return env.ELANOUS_RELEASE_ASK_BIN?.trim() || join(REPO_ROOT, 'bin/elanous.mjs');
+}
+
+/** Translate one public note sentence without sending private manifest fields to the model. */
+function askBareForEnglish(line: string, askSpawn: AskSpawn = spawnSync, env: NodeJS.ProcessEnv = process.env): string {
+  const prompt = [
+    'Translate the following public release-note sentence into concise English.',
+    'Return only the translated sentence. Preserve product names, code, Markdown links, and meaning.',
+    'Do not add facts, headings, quotes, or commentary.',
+    '',
+    line,
+  ].join('\n');
+  const result = askSpawn(process.execPath, [askCliPath(env), 'ask', '--bare', '--json', prompt], {
+    // Pin the approved translation model for this child only; do not mutate the operator's config.
+    cwd: process.cwd(), env: { ...process.env, ELANOUS_LLM_PROVIDER: 'openrouter', ELANOUS_LLM_MODEL: 'z-ai/glm-5.3' },
+    encoding: 'utf8', timeout: 60_000, maxBuffer: 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) throw new Error(`ask --bare failed: ${result.error?.message ?? result.stderr ?? result.stdout}`);
+  const payload = JSON.parse(result.stdout.trim().split('\n').at(-1) ?? 'null') as { reply?: unknown; error?: unknown };
+  if (typeof payload.reply !== 'string') throw new Error(typeof payload.error === 'string' ? payload.error : 'ask --bare returned no reply');
+  return payload.reply;
+}
+
+function translatePublicText(text: string, runner: TranslationRunner, failures: string[], cache: Map<string, string>): string {
+  let fence: { marker: string; quoteDepth: number; listDepth: number } | undefined;
+  let inHtmlComment = false;
+  const translatePlain = (raw: string): string => {
+    const { prefix, text: untrimmed } = splitMarkdownPrefix(raw);
+    const source = untrimmed.trim();
+    if (!HANGUL.test(source)) return raw;
+    let translated = cache.get(source);
+    if (translated === undefined) {
+      try {
+        const candidate = runner(source).trim();
+        const alphanumeric = [...candidate].filter((character) => /[\p{L}\p{N}]/u.test(character));
+        if (!candidate || HANGUL.test(candidate) || alphanumeric.length === 0 || /[^\x00-\x7f]/.test(candidate)) {
+          throw new Error('translation is empty or contains non-Latin writing');
+        }
+        translated = candidate;
+        cache.set(source, candidate);
+      } catch (error) {
+        failures.push(error instanceof Error ? error.message : String(error));
+        translated = source;
+        cache.set(source, source);
+        debug.log('release-loop.docs', 'public-note-translation-fallback', { reason: failures.at(-1) });
+        return raw;
+      }
+    }
+    const trailingWhitespace = /\s*$/.exec(untrimmed)?.[0] ?? '';
+    return `${prefix}${translated}${trailingWhitespace}`;
+  };
+  return text.split(/(\r?\n)/).map((raw, index) => {
+    if (index % 2 === 1) return raw;
+    const failuresBeforeLine = failures.length;
+    const finishLine = (value: string): string => failures.length > failuresBeforeLine ? raw : value;
+    const fenceLine = inHtmlComment ? undefined : markdownFenceLine(raw);
+    if (fence) {
+      const closingFence = !inHtmlComment ? markdownFenceLine(raw, true) : undefined;
+      if (closingFence && closingFence.quoteDepth === fence.quoteDepth && closingFence.listDepth <= fence.listDepth
+        && closingFence.marker[0] === fence.marker[0] && closingFence.marker.length >= fence.marker.length) fence = undefined;
+      return raw;
+    }
+    if (fenceLine) { fence = fenceLine; return raw; }
+    let output = '';
+    let cursor = 0;
+    let plainStart = 0;
+    while (cursor < raw.length) {
+      if (inHtmlComment) {
+        const end = raw.indexOf('-->', cursor);
+        if (end < 0) return finishLine(output + raw.slice(cursor));
+        output += raw.slice(cursor, end + 3);
+        cursor = end + 3;
+        plainStart = cursor;
+        inHtmlComment = false;
+        continue;
+      }
+      if (raw[cursor] === '`') {
+        let delimiterLength = 1;
+        while (raw[cursor + delimiterLength] === '`') delimiterLength++;
+        let end = raw.indexOf('`'.repeat(delimiterLength), cursor + delimiterLength);
+        while (end >= 0) {
+          let endLength = 1;
+          while (raw[end + endLength] === '`') endLength++;
+          if (endLength === delimiterLength) break;
+          end = raw.indexOf('`'.repeat(delimiterLength), end + endLength);
+        }
+        output += translatePlain(raw.slice(plainStart, cursor));
+        if (end < 0) return finishLine(output + raw.slice(cursor));
+        output += raw.slice(cursor, end + delimiterLength);
+        cursor = end + delimiterLength;
+        plainStart = cursor;
+        continue;
+      }
+      if (raw.startsWith('<!--', cursor)) {
+        output += translatePlain(raw.slice(plainStart, cursor)) + '<!--';
+        cursor += 4;
+        plainStart = cursor;
+        inHtmlComment = true;
+        continue;
+      }
+      cursor++;
+    }
+    output += translatePlain(raw.slice(plainStart));
+    return finishLine(output);
+  }).join('');
 }
 
 function* markdownFiles(directory: string): Generator<string> {
@@ -53,7 +233,7 @@ function graphInput(env: NodeJS.ProcessEnv): Record<string, unknown> {
 /** Apply the cutoff manifest to the public documentation checkout. */
 export function runDocs(
   args: string[], base = process.cwd(), env: NodeJS.ProcessEnv = process.env,
-  deps: { stateRoot?: string; writeTemp?: (path: string, text: string) => void } = {},
+  deps: { stateRoot?: string; writeTemp?: (path: string, text: string) => void; translateLine?: TranslationRunner; askSpawn?: AskSpawn } = {},
 ): DocsResult {
   let version: string | null = null;
   try {
@@ -87,17 +267,33 @@ export function runDocs(
     if (!Array.isArray(registry.pages)) throw new Error(`invalid pages registry: ${pages}`);
     const count = registry.pages.filter((page) => page.id === id).length;
     if (count > 1) throw new Error(`duplicate pages entry: ${id}`);
-    const renderedNotes = renderReleaseNotes(manifest, version);
+    const translationFailures: string[] = [];
+    const translateLine = deps.translateLine ?? ((line) => askBareForEnglish(line, deps.askSpawn, env));
+    const translationCache = new Map<string, string>();
+    const publicEntries = new Set(['feat', 'fix', 'security']);
+    const notesManifest: ReleaseManifest = {
+      ...manifest,
+      in: manifest.in.map((entry) => entry.line && publicEntries.has(entry.kind ?? '')
+        ? { ...entry, line: translatePublicText(entry.line, translateLine, translationFailures, translationCache) }
+        : entry),
+    };
+    const renderedNotes = renderReleaseNotes(notesManifest, version);
+    const existingNotes = existsSync(notes) ? readFileSync(notes, 'utf8') : null;
+    const translatedExistingNotes = existingNotes === null
+      ? null
+      : translatePublicText(existingNotes, translateLine, translationFailures, translationCache);
     // A PR may land its own line (or the headline) in this version's notes before the loop runs.
     // Fold it in rather than refusing (which stalled the release) or overwriting (which lost it).
     let notesText: string | null = null;
-    if (count === 0 && existsSync(notes)) {
-      const existing = readFileSync(notes, 'utf8');
-      if (existing !== renderedNotes) {
-        const fold = foldPreLandedNotes(existing, renderedNotes);
+    if (count === 0 && translatedExistingNotes !== null) {
+      if (existingNotes !== renderedNotes) {
+        const fold = foldPreLandedNotes(translatedExistingNotes, renderedNotes);
         notesText = fold.text;
         debug.log('release-loop.docs', 'pre-landed-lines-folded', { version, count: fold.folded });
       }
+    } else if (count > 0 && existingNotes !== null && translatedExistingNotes !== existingNotes) {
+      // A resumed docs node may find its own earlier Korean output already registered.
+      notesText = translatedExistingNotes;
     }
     if (count === 0) {
       const first = registry.pages.findIndex((page) => page.id.startsWith('releases/'));
@@ -120,7 +316,8 @@ export function runDocs(
     else if (!existsSync(notes)) atomicWrite(notes, renderedNotes, writeTemp);
     for (const [path, text] of changed) atomicWrite(path, text, writeTemp);
     if (count === 0) atomicWrite(pages, JSON.stringify(registry, null, 2) + '\n', writeTemp);
-    return { outcome: 'ok', version, notes, flipped: changed.map(([path]) => path), pages };
+    return { outcome: 'ok', version, notes, flipped: changed.map(([path]) => path), pages,
+      ...(translationFailures.length ? { translationFallbacks: translationFailures.length } : {}) };
   } catch (error) {
     return { outcome: 'error', version, error: error instanceof Error ? error.message : String(error) };
   }
@@ -299,6 +496,11 @@ export function joinTui(context: GraphContext, env: NodeJS.ProcessEnv, repo: str
 export function graphDocs(context: GraphContext, env: NodeJS.ProcessEnv, repo: string, run: Runner = commandRunner,
   stateRoot = effectiveInstanceRoot()): DocsResult {
   const version = context.input.version;
+  if (context.runId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(context.runId))
+      return { outcome: 'error', version, error: 'invalid release runId' };
+    return graphDocsOwned(context, env, repo, run, stateRoot);
+  }
   let tree: string | undefined;
   // Before ANY check (and so also on every failure path): only the first docs attempt may consume a staged cache,
   // and only when the worker won the claim; otherwise this attempt claims the slot so a late worker cannot publish.
@@ -345,6 +547,137 @@ export function graphDocs(context: GraphContext, env: NodeJS.ProcessEnv, repo: s
   }
 }
 
+type DocsOwner = NonNullable<DocsResult['artifactOwner']>;
+type DocsReceipt = { owner: DocsOwner; branch: string; worktree: string; outcome: 'staged' | 'pushed'; result?: DocsResult; head?: string };
+
+/** The resume count is part of the artifact key; the first run has attempt zero. */
+function docsAttempt(stateRoot: string, version: string, runId: string): number {
+  const path = join(stateRoot, 'release', version, 'resume-attempts', `${runId}.json`);
+  if (!existsSync(path)) return 0;
+  const value = JSON.parse(readFileSync(path, 'utf8')) as { version?: unknown; runId?: unknown; attempts?: unknown };
+  if (value.version !== version || value.runId !== runId || !Array.isArray(value.attempts)
+    || value.attempts.some((at) => typeof at !== 'string' || !Number.isFinite(Date.parse(at))))
+    throw new Error(`invalid release resume attempts ledger: ${path}`);
+  return value.attempts.length;
+}
+
+function docsReceipt(path: string): DocsReceipt | null {
+  if (!existsSync(path)) return null;
+  const value = JSON.parse(readFileSync(path, 'utf8')) as DocsReceipt;
+  if (!value || typeof value !== 'object' || !value.owner || typeof value.owner.runId !== 'string'
+    || !Number.isSafeInteger(value.owner.attempt) || typeof value.worktree !== 'string'
+    || typeof value.branch !== 'string' || !['staged', 'pushed'].includes(value.outcome))
+    throw new Error(`invalid docs ownership receipt: ${path}`);
+  return value;
+}
+
+function remoteBranchHead(run: Runner, repo: string, branch: string): string | null {
+  const line = run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], repo).trim();
+  if (!line) return null;
+  const match = /^([0-9a-f]{40})\s+refs\/heads\/[^\s]+$/i.exec(line);
+  if (!match) throw new Error(`invalid remote docs branch response: ${line}`);
+  return match[1]!;
+}
+
+function graphDocsOwned(context: GraphContext, env: NodeJS.ProcessEnv, repo: string, run: Runner, stateRoot: string): DocsResult {
+  const version = context.input.version;
+  const runId = context.runId!;
+  let tree: string | undefined;
+  let owner: DocsOwner | undefined;
+  let mayConsume = false;
+  let cacheDir: string | undefined;
+  try {
+    cacheDir = runCacheDir(env);
+    mkdirSync(cacheDir, { recursive: true });
+    const closed = join(cacheDir, 'docs-closed');
+    const firstAttempt = !existsSync(closed);
+    writeFileSync(closed, `${new Date().toISOString()}\n`);
+    const docsWon = claimPrefetch(cacheDir, 'docs');
+    mayConsume = firstAttempt && !docsWon && readFileSync(join(cacheDir, 'claim'), 'utf8') === 'worker';
+  } catch { /* standalone graph: no prefetch slot */ }
+  try {
+    for (const node of ['gate', 'prepare', 'upgrade', 'tui']) if (context.outputs[node]?.outcome !== 'ok') throw new Error(`${node} did not pass`);
+    const attempt = docsAttempt(stateRoot, version, runId);
+    const branch = `release-docs/${version}`;
+    const receiptPath = join(stateRoot, 'release', version, 'docs-branch-owner.json');
+    const previous = docsReceipt(receiptPath);
+    const sameOwner = previous?.owner.runId === runId && previous.owner.attempt === attempt && previous.branch === branch;
+    let cached: DocsCache | null = null;
+    if (mayConsume && cacheDir) { try { cached = loadCache(cacheDir, cutFor(context, stateRoot)); } catch { cached = null; } }
+    run('git', ['fetch', 'origin', 'main'], repo);
+    const main = run('git', ['rev-parse', '--verify', 'origin/main^{commit}'], repo);
+    if (!SHA.test(main)) throw new Error('invalid origin/main commit');
+    let local = '';
+    try { local = run('git', ['show-ref', '--verify', '--hash', `refs/heads/${branch}`], repo).trim(); }
+    catch { /* No local branch is the normal first-run case. */ }
+    const remote = remoteBranchHead(run, repo, branch);
+    owner = { runId, attempt };
+    if (sameOwner && local && existsSync(previous!.worktree)) {
+      tree = previous!.worktree;
+      if (run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], tree) !== branch) throw new Error('docs owner worktree changed branch');
+      if (previous!.outcome === 'pushed' && previous!.head === local && remote === local && previous!.result?.outcome === 'ok')
+        return { ...previous!.result, artifactOwner: previous!.owner };
+      if (remote && run('git', ['merge-base', remote, local], repo) !== remote)
+        throw new Error(`same-run docs remote diverged: ${branch}`);
+    } else {
+      const suffix = `${runId}-${attempt}-${randomUUID()}`;
+      if (local) {
+        const localBackup = `release-docs-backup/${version}/${suffix}`;
+        run('git', ['branch', '-m', branch, localBackup], repo);
+        owner.localBackup = localBackup;
+      }
+      if (remote) {
+        const remoteBackup = `release-docs-backup/${version}/${suffix}`;
+        run('git', ['fetch', 'origin', `refs/heads/${branch}`], repo);
+        if (run('git', ['rev-parse', '--verify', 'FETCH_HEAD^{commit}'], repo) !== remote)
+          throw new Error(`remote docs branch changed while backing up: ${branch}`);
+        const changed = run('git', ['diff', '--name-only', `${main}...${remote}`], repo).split('\n').filter(Boolean);
+        if (changed.some((path) => !path.startsWith('release/public/docs/') && path !== 'website/pages.json'))
+          throw new Error(`foreign docs branch changes outside public docs: ${changed.join(', ')}`);
+        run('git', ['push', 'origin', `${remote}:refs/heads/${remoteBackup}`], repo);
+        if (remoteBranchHead(run, repo, remoteBackup) !== remote) throw new Error('remote docs backup not verified');
+        owner.remoteBackup = remoteBackup;
+        owner.remoteHead = remote;
+      }
+      const useCache = !remote && cached?.main === main && SHA.test(main);
+      if (useCache) {
+        tree = cached!.tree;
+        run('git', ['-C', tree, 'switch', '-c', branch], repo);
+        rmSync(cacheFile(cacheDir!, cached!), { force: true });
+      } else {
+        const root = mkdtempSync(join(tmpdir(), 'release-docs-'));
+        tree = join(root, 'tree');
+        run('git', ['worktree', 'add', '-b', branch, tree, main], repo);
+      }
+      // A foreign ref is incorporated by a normal merge, keeping the original branch fast-forwardable.
+      // Restore the docs inputs from main before generating this run's notes: old output is history, not input.
+      if (remote) {
+        run('git', ['merge', '--no-ff', '--no-edit', remote], tree);
+        run('git', ['restore', '--source', main, '--staged', '--worktree', '--', 'release/public/docs', 'website/pages.json'], tree);
+      }
+      const receipt: DocsReceipt = { owner, branch, worktree: tree, outcome: 'staged' };
+      mkdirSync(dirname(receiptPath), { recursive: true });
+      publish(receiptPath, receipt);
+      if (!useCache) run('bun', ['install', '--frozen-lockfile'], tree);
+    }
+    const result = cached?.tree === tree && cached.main === main ? cached.docs
+      : runDocs(['--version', version, '--base', tree, '--json'], repo, env, { stateRoot });
+    if (result.outcome !== 'ok') throw new Error(result.error ?? 'docs generation failed');
+    run('git', ['add', 'release/public/docs', 'website/pages.json'], tree);
+    const changes = run('git', ['diff', '--cached', '--name-only'], tree).trim();
+    if (changes) run('git', ['commit', '-m', `docs: release ${version}`], tree);
+    // No force: a concurrent remote update fails and leaves both branch and backup intact.
+    run('git', ['push', '-u', 'origin', branch], tree);
+    const head = run('git', ['rev-parse', '--verify', 'HEAD'], tree);
+    const output: DocsResult = { ...result, branch, worktree: tree, artifactOwner: owner };
+    publish(receiptPath, { owner, branch, worktree: tree, outcome: 'pushed', head, result: output } satisfies DocsReceipt);
+    return output;
+  } catch (error) {
+    return { outcome: 'error', version, error: error instanceof Error ? error.message : String(error),
+      ...(tree ? { worktree: tree } : {}), ...(owner ? { artifactOwner: owner } : {}) };
+  }
+}
+
 /** Detached prefetch worker; an asynchronous spawn failure is logged as a cache miss and never escapes the node. */
 export function startPrefetchWorker(version: string, commit: string,
   spawnWorker: () => ReturnType<typeof spawn> = () => spawn(process.execPath, [resolve(import.meta.filename), '--prefetch-worker'], {
@@ -401,6 +734,9 @@ if (import.meta.main) {
       result = { ...joinTui(context, process.env, process.cwd()), version: context.input.version } as typeof result;
     } else if (node === 'docs') {
       result = graphDocs(readGraphContext(), process.env, process.cwd(), commandRunner);
+    } else if (node === 'notes-repair') {
+      const { runNotesRepair } = await import('./notes-repair.js');
+      result = await runNotesRepair(readGraphContext()) as typeof result;
     } else if (node === null) result = runDocs(process.argv.slice(2));
     else throw new Error(`unknown release docs node: ${node}`);
   } catch (error) {