elanous 0.2.36 → 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

@@ -22,6 +22,7 @@ interface DocsResult {
   branch?: string;
   worktree?: string;
   translationFallbacks?: number;
+  artifactOwner?: { runId: string; attempt: number; localBackup?: string; remoteBackup?: string; remoteHead?: string };
 }
 
 type TranslationRunner = (line: string) => string;
@@ -495,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.
@@ -541,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'], {
@@ -597,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) {

package/scripts/release-loop/gate-closure.ts

@@ -5,6 +5,7 @@
 //
 // Read from the tip commit's git objects, never from the working tree (the resume can run from any checkout).
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { dirname, join, normalize } from 'node:path/posix';
 import ts from 'typescript';
 import { sourceCandidates } from '../../src/self-implement/importer-test-index.js';
@@ -230,6 +231,53 @@ export function testsReachingChanged(tree: ClosureTree, changed: readonly string
     opaqueFiles: [...opaque].filter(([file]) => !preloadClosure.has(file)).map(([file, why]) => `${file}: ${why}`).sort() };
 }
 
+// TRAIN-REACH-GROUPING — two PRs whose reach sets share a test ride the same release train (their gates
+// cannot be reused independently); disjoint reach sets stay separate trains. Pure and deterministic: the
+// ledger is derived from content alone — no file, clock, or network effects.
+
+/** One PR's reach set for train grouping — the `tests` of a `testsReachingChanged` verdict (`ok: true`). */
+export interface TrainReach {
+  /** The PR that owns this reach set (number or url). */
+  readonly pr: string;
+  /** 도달 시험 집합 — tests reaching the PR's changed files. */
+  readonly tests: readonly string[];
+}
+
+/** 묶음 원장 — train grouping ledger returned by `defineTrainGrouping`. */
+export interface TrainGrouping {
+  /** Train id per PR — both PRs share one id when their reach sets intersect. */
+  readonly trainIds: ReadonlyMap<string, string>;
+  /** The tests both reach sets share (sorted, deduped) — empty when they stay separate trains. */
+  readonly intersection: readonly string[];
+  /** True when the reach sets intersect and the two PRs ride the same train. */
+  readonly sameTrain: boolean;
+}
+
+/** Train id derived from content — same parts give the same id; a sha256 slice keeps the ledger readable. */
+const trainIdOf = (parts: readonly string[]): string =>
+  `train-${createHash('sha256').update(parts.join('\u0000')).digest('hex').slice(0, 12)}`;
+
+/** Bundle two PRs' reach sets into trains: intersecting reach sets get one shared train id, disjoint reach
+ * sets keep separate per-PR ids. Deterministic and side-effect free — same inputs, same ledger. */
+export function defineTrainGrouping(left: TrainReach, right: TrainReach): TrainGrouping {
+  const reachOf = (reach: TrainReach): string[] => [...new Set(reach.tests)].sort();
+  const leftTests = reachOf(left);
+  const rightTests = reachOf(right);
+  const rightSet = new Set(rightTests);
+  const shared = leftTests.filter((test) => rightSet.has(test));
+  const trainIds = new Map<string, string>();
+  if (shared.length > 0) {
+    const sharedId = trainIdOf(shared);
+    trainIds.set(left.pr, sharedId);
+    trainIds.set(right.pr, sharedId);
+  } else {
+    // Disjoint reach sets: mix the PR key into each id so even two empty reach sets stay separate trains.
+    trainIds.set(left.pr, trainIdOf([left.pr, ...leftTests]));
+    trainIds.set(right.pr, trainIdOf([right.pr, ...rightTests]));
+  }
+  return { trainIds, intersection: shared, sameTrain: shared.length > 0 };
+}
+
 /** `[test].preload` of a bunfig.toml text (repo-relative). Null when the file has a preload we cannot parse. */
 export function bunfigPreload(text: string | undefined): string[] | null {
   if (text === undefined) return [];

package/scripts/release-loop/gate-diff.ts

@@ -12,7 +12,8 @@ export function parseFailures(output: string): string[] {
     const line = raw.trim();
     const header = /^(?:\.\/)?((?:[\w.-]+\/)+[\w.-]+\.test\.tsx?):(?:\s|$)/.exec(line);
     if (header) { file = header[1]; continue; }
-    const failed = /^\(fail\)[ \t]+(.+?)(?:[ \t]+\[[\d.]+(?:ms|s)\])?[ \t]*$/.exec(raw);
+    // Line-start only: a title/body `(fail)` is not a reporter row. Trailing CR is still a real Bun fail row.
+    const failed = /^\(fail\)[ \t]+(.+?)(?:[ \t]+\[[\d.]+(?:ms|s)\])?[ \t]*\r?$/.exec(raw);
     if (failed && file) failures.add(`${file} > ${failed[1]!.trim()}`);
   }
   return [...failures].sort();

package/scripts/release-loop/known-issues-node.ts

@@ -22,7 +22,7 @@ const INTRO = 'The following issues are known in this release.';
 const resolved = /\b(?:fixed|resolved|no longer|has been addressed|is addressed|was addressed)\b/i;
 const unsafe = /[^\x20-\x7e]|#\d+|\/Users\/|\.test\.ts\b|\[(?:TC|MK|OP|UX|S|T|F|O)\]|\b(?:TC|MK|OP|UX)\s+track\b|\b(?:PR|pull request)\s*\d+\b|\b(?:scripts|src|test)\/\S+|\bfile:\/\/|(?<![\w:/])\/(?!\/)[\w.-]+(?:\/[\w.-]+)*|\b[A-Z]:\\(?:[^\s\\]+\\)*[^\s\\]+|\b(?:RFC|HANDOFF|MANUAL)-/i;
 
-type Issue = { id: string; title?: string; evidence?: string; note?: string };
+type Issue = { id: string; title?: string; evidence?: string; knownIssue?: string; note?: string };
 
 // Accepted regressions with the same public note describe one issue, even if several gates recorded it.
 function issueGroup(issue: Issue, checklistIssues: ReadonlySet<Issue>): string {
@@ -62,9 +62,9 @@ function generatedBullets(raw: string, sourceIds: string[]): string[] {
 }
 
 function coversIssue(bullet: string, issue: Issue, others: Issue[]): boolean {
-  const source = issue.title ?? issue.note ?? '';
+  const source = issue.knownIssue ?? issue.note ?? '';
   const words = source.toLowerCase().match(/[a-z]{5,}/g) ?? [];
-  const otherWords = new Set(others.flatMap((other) => ((other.title ?? other.note ?? '').toLowerCase().match(/[a-z]{5,}/g) ?? []).map((word) => word.slice(0, 5))));
+  const otherWords = new Set(others.flatMap((other) => ((other.knownIssue ?? other.note ?? '').toLowerCase().match(/[a-z]{5,}/g) ?? []).map((word) => word.slice(0, 5))));
   const publicWords = new Set((bullet.toLowerCase().match(/[a-z]{5,}/g) ?? []).map((word) => word.slice(0, 5)));
   const distinctive = [...new Set(words.map((word) => word.slice(0, 5)))].filter((word) => !otherWords.has(word));
   const negative = /\b(?:not|never|no|cannot|can't|doesn't|don't|won't|fails? to|isn't|aren't)\b/i;
@@ -130,7 +130,9 @@ export function runKnownIssues(context: GraphContext = readGraphContext(), run:
   if (context.outputs.docs?.branch !== `release-docs/${version}`) throw new Error('docs branch/version mismatch');
   const notes = join(worktree, 'release/public/docs/releases', `${version}.md`);
   if (!existsSync(notes)) throw new Error(`release notes missing: ${notes}`);
-  const checklist = issues(context.outputs['checklist-gate']?.knownIssues, 'checklist');
+  // A checklist title is an internal task label, not public issue copy. Missing dedicated copy
+  // means no public note row is generated for that checklist item.
+  const checklist = issues(context.outputs['checklist-gate']?.knownIssues, 'checklist').filter((issue) => typeof issue.knownIssue === 'string' && issue.knownIssue.trim()).map((issue) => ({ ...issue, title: issue.knownIssue!.trim() }));
   const accepted = issues(context.input.acceptedRegressions, 'accepted');
   const approved0233Batch = version === '0.2.33' && accepted.length === APPROVED_0233_INPUT.length
     && new Set(accepted.map((issue) => issue.id)).size === accepted.length