elanous 0.2.17 → 0.2.19

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

@@ -0,0 +1,106 @@
+// GATE-PARTIAL (0.2.19 · 10-07): a re-gate after `release cut-branch --append` runs only the test files that can have
+// changed — not the whole 24-shard sweep again (0.2.18: two timeout fixes on top of an 84-minute gate meant another full
+// gate). The plan is opt-in (`release resume --from gate --partial`) and fail-closed: any non-test source change, a prior
+// gate record for another commit, or a missing record means «full gate», never a guess.
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+
+export interface PartialPlan {
+  version: string;
+  /** Commit the previous (full) gate measured — its recorded failures are carried for every file not re-run. */
+  priorCommit: string;
+  /** The commit this plan is for — a gate on any other commit ignores it. */
+  forCommit: string;
+  /** Test files re-run: changed test files ⊕ files of the prior failures. */
+  files: string[];
+  priorFailures: string[];
+  priorErrors: string[];
+}
+
+export const partialPlanPath = (root: string, version: string) => join(root, 'release', version, 'gate-partial.json');
+/** The same test-file set the gate sweep runs (`git ls-files` filtered by this suffix). */
+const TEST_FILE = /^(?:[\w.-]+\/)*[\w.-]+\.test\.(?:tsx?|jsx?|mts|cts)$/;
+/** Changes that cannot alter a test result on their own: Markdown that is not test input. A fixture (any file under a
+ *  test/, fixtures, __fixtures__ or __snapshots__ path), JSON or script is not inert — the gate runs in full. */
+const INERT_MD = /\.md$/;
+const TEST_INPUT = /(?:^|\/)(?:test|tests|fixtures|__fixtures__|__snapshots__|__mocks__)\//;
+const isInert = (file: string) => INERT_MD.test(file) && !TEST_INPUT.test(file);
+
+/** The test file of a failure id (`<file> > <case>`). One rule for the gate and the partial plan: ids come only from the
+ *  gate's output parsers, which accept `dir/….test.ts(x)` — anything else (a root file, `..`, no case) is unsafe. */
+export function testFileOfId(id: string): string {
+  const file = id.split(' > ', 1)[0]!;
+  if (!id.includes(' > ') || !/^(?:[\w.-]+\/)+[\w.-]+\.test\.tsx?$/.test(file) || file.split('/').includes('..')) throw new Error(`unsafe test path: ${file}`);
+  return file;
+}
+
+/** Decide whether a partial re-gate is safe for `changedFiles` (prior → for). Never guesses: any doubt is a full gate. */
+export function planPartialRegate(input: { version: string; priorCommit: string; forCommit: string; changedFiles: readonly string[];
+  priorFailures: readonly string[]; priorErrors: readonly string[] }):
+  { ok: true; plan: PartialPlan } | { ok: false; reason: string } {
+  if (!/^[0-9a-f]{40}$/i.test(input.priorCommit) || !/^[0-9a-f]{40}$/i.test(input.forCommit)) return { ok: false, reason: 'commit is not a full sha' };
+  if (input.priorCommit === input.forCommit) return { ok: false, reason: 'no new commit since the prior gate' };
+  const source = input.changedFiles.filter((file) => !TEST_FILE.test(file) && !isInert(file));
+  if (source.length) return { ok: false, reason: `non-test change → full gate: ${source.slice(0, 5).join(', ')}${source.length > 5 ? ` (+${source.length - 5})` : ''}` };
+  let failureFiles: string[];
+  try { failureFiles = [...input.priorFailures, ...input.priorErrors].map(testFileOfId); }
+  catch (error) { return { ok: false, reason: String(error instanceof Error ? error.message : error) }; }
+  const files = [...new Set([...input.changedFiles.filter((file) => TEST_FILE.test(file)), ...failureFiles])].sort();
+  if (!files.length) return { ok: false, reason: 'nothing to re-run' };
+  return { ok: true, plan: { version: input.version, priorCommit: input.priorCommit, forCommit: input.forCommit, files,
+    priorFailures: [...input.priorFailures], priorErrors: [...input.priorErrors] } };
+}
+
+export function writePartialPlan(root: string, plan: PartialPlan): string {
+  const path = partialPlanPath(root, plan.version);
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(plan, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temp, path);
+  return path;
+}
+
+export function clearPartialPlan(root: string, version: string): void {
+  const path = partialPlanPath(root, version);
+  if (existsSync(path)) rmSync(path);
+}
+
+/** The plan for exactly this commit, or null. A malformed plan is an error (never silently a full or partial gate). */
+export function readPartialPlan(roots: readonly string[], version: string, commit: string): PartialPlan | null {
+  for (const root of roots) {
+    const path = partialPlanPath(root, version);
+    if (!existsSync(path)) continue;
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<PartialPlan>;
+    if (raw.version !== version || typeof raw.priorCommit !== 'string' || !/^[0-9a-f]{40}$/i.test(raw.priorCommit)
+      || typeof raw.forCommit !== 'string' || !/^[0-9a-f]{40}$/i.test(raw.forCommit) || raw.priorCommit === raw.forCommit
+      || !Array.isArray(raw.files) || raw.files.length === 0 || !raw.files.every((file) => typeof file === 'string' && TEST_FILE.test(file) && !file.split('/').includes('..'))
+      || !Array.isArray(raw.priorFailures) || !Array.isArray(raw.priorErrors)) throw new Error(`invalid gate partial plan: ${path}`);
+    // Every prior failure's file is re-run (planPartialRegate guarantees it) — a plan that would carry a failure it did
+    // not re-run is malformed, not «partial».
+    const rerun = new Set(raw.files);
+    let failureFiles: string[];
+    try { failureFiles = [...raw.priorFailures, ...raw.priorErrors].map((id) => testFileOfId(String(id))); }
+    catch { throw new Error(`invalid gate partial plan: ${path}`); }
+    if (failureFiles.some((file) => !rerun.has(file))) throw new Error(`invalid gate partial plan (prior failure not re-run): ${path}`);
+    if (raw.forCommit !== commit) continue;
+    return raw as PartialPlan;
+  }
+  return null;
+}
+
+/** Cut failures after a partial re-run: prior results for files not re-run ⊕ this run's results for the re-run files. */
+export function mergePartialFailures(plan: PartialPlan, measured: { failures: string[]; errors: string[] }): { failures: string[]; errors: string[] } {
+  const rerun = new Set(plan.files);
+  const keep = (ids: readonly string[]) => ids.filter((id) => !rerun.has(testFileOfId(id)));
+  return { failures: [...keep(plan.priorFailures), ...measured.failures], errors: [...keep(plan.priorErrors), ...measured.errors] };
+}
+
+/** Files changed between two commits — both sides of a rename (`--no-renames`), so moving a source file into a test or
+ *  Markdown name still shows the source path that disappeared. */
+export function changedFilesBetween(repo: string, from: string, to: string): string[] {
+  // git-spawn-allow: read-only diff of two release commits.
+  const result = spawnSync('git', ['diff', '--name-only', '--no-renames', `${from}..${to}`], { cwd: repo, encoding: 'utf8' });
+  if (result.status !== 0 || result.error) throw new Error(`git diff failed: ${(result.stderr || result.error || 'no output').toString().trim()}`);
+  return result.stdout.split(/\r?\n/).filter(Boolean);
+}

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

@@ -0,0 +1,120 @@
+// F5 GATE-TIMING-REPORT — 게이트 한 판의 «시간 비용»을 보이게 한다(GATE-SPEED 의 자).
+// 입력 = 게이트 로그 디렉토리(`<ledger>/release/<version>/gate-logs/cut`)의 `pod-*.json`.
+//   첫 판 샤드 = `pod-<n>.json` · 재시도 = 그 밖의 모든 `pod-*.json`(`-c<k>`·`-c<k>-file-<m>`·`-retry` …).
+// ⛔ 측정이 없으면 `measured:false` 로 표시한다 — 0 을 «잰 값»처럼 내지 않는다.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { releaseLedgerRoot } from '../../src/instance/resolve.js';
+
+export interface ShardTiming { name: string; min: number; files: number; plannedMin: number | null }
+
+export interface GateTimingReport {
+  dir: string;
+  /** 읽은 pod-*.json 중 durationMs 를 가진 것이 하나라도 있었나. false 면 아래 수는 «측정 없음». */
+  measured: boolean;
+  /** JSON 파싱 실패·durationMs 부재로 건너뛴 파일 이름. */
+  unreadable: string[];
+  firstPass: { shards: number; sumMin: number; medianMin: number; maxMin: number; failedShards: string[] };
+  retries: { runs: number; sumMin: number; medianMin: number };
+  /** 재시도 합 / (첫 판 합 + 재시도 합). 측정이 없으면 null. */
+  retryShare: number | null;
+  slowestShards: ShardTiming[];
+}
+
+const FIRST_PASS = /^pod-\d+\.json$/;
+const POD_JSON = /^pod-.+\.json$/;
+
+const round1 = (n: number) => Math.round(n * 10) / 10;
+
+function median(xs: number[]): number {
+  if (xs.length === 0) return 0;
+  const s = [...xs].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
+}
+
+interface PodRecord { durationMs?: unknown; rc?: unknown; files?: unknown; plannedSeconds?: unknown; jobFailed?: unknown }
+
+export function gateTiming(dir: string): GateTimingReport {
+  const names = existsSync(dir) && statSync(dir).isDirectory()
+    ? readdirSync(dir).filter((n) => POD_JSON.test(n)).sort((a, b) => a.localeCompare(b, 'en', { numeric: true }))
+    : [];
+  const first: Array<ShardTiming & { failed: boolean }> = [];
+  const retryMin: number[] = [];
+  const unreadable: string[] = [];
+  for (const name of names) {
+    let rec: PodRecord;
+    try { rec = JSON.parse(readFileSync(join(dir, name), 'utf8')) as PodRecord; } catch { unreadable.push(name); continue; }
+    if (!rec || typeof rec !== 'object' || typeof rec.durationMs !== 'number' || !Number.isFinite(rec.durationMs)) { unreadable.push(name); continue; }
+    const min = rec.durationMs / 60_000;
+    if (FIRST_PASS.test(name)) {
+      first.push({
+        name: name.replace(/\.json$/, ''),
+        min,
+        files: Array.isArray(rec.files) ? rec.files.length : 0,
+        plannedMin: typeof rec.plannedSeconds === 'number' ? rec.plannedSeconds / 60 : null,
+        failed: rec.jobFailed === true || (typeof rec.rc === 'number' && rec.rc !== 0),
+      });
+    } else {
+      retryMin.push(min);
+    }
+  }
+  const firstMins = first.map((s) => s.min);
+  const firstSum = firstMins.reduce((a, b) => a + b, 0);
+  const retrySum = retryMin.reduce((a, b) => a + b, 0);
+  const total = firstSum + retrySum;
+  const measured = first.length + retryMin.length > 0;
+  return {
+    dir,
+    measured,
+    unreadable,
+    firstPass: {
+      shards: first.length,
+      sumMin: round1(firstSum),
+      medianMin: round1(median(firstMins)),
+      maxMin: round1(firstMins.length ? Math.max(...firstMins) : 0),
+      failedShards: first.filter((s) => s.failed).map((s) => s.name),
+    },
+    retries: { runs: retryMin.length, sumMin: round1(retrySum), medianMin: round1(median(retryMin)) },
+    retryShare: measured && total > 0 ? Math.round((retrySum / total) * 1000) / 1000 : null,
+    slowestShards: [...first].sort((a, b) => b.min - a.min).slice(0, 5)
+      .map(({ name, min, files, plannedMin }) => ({ name, min: round1(min), files, plannedMin: plannedMin === null ? null : round1(plannedMin) })),
+  };
+}
+
+/** `<version>` 이면 원장 루트(`releaseLedgerRoot()`)의 `release/<version>/gate-logs/cut`, 경로처럼 보이면 그대로. */
+export function resolveGateLogDir(arg: string, ledgerRoot: string = releaseLedgerRoot()): string {
+  if (arg.includes('/') || arg.startsWith('.') || existsSync(arg)) return arg;
+  return join(ledgerRoot, 'release', arg, 'gate-logs', 'cut');
+}
+
+export function formatGateTiming(r: GateTimingReport): string {
+  if (!r.measured) {
+    return [`게이트 시간 — 측정 없음 (${r.dir})`, '  pod-*.json 에 durationMs 가 하나도 없다 · 0 은 «잰 값»이 아니다',
+      ...(r.unreadable.length ? [`  읽지 못한 파일 ${r.unreadable.length}개`] : [])].join('\n');
+  }
+  const f = r.firstPass;
+  const lines = [
+    `게이트 시간 (${r.dir})`,
+    `  첫 판   샤드 ${f.shards}개 · 합 ${f.sumMin}분 · 중앙 ${f.medianMin}분 · 최대 ${f.maxMin}분 · 실패 샤드 ${f.failedShards.length}개${f.failedShards.length ? ` (${f.failedShards.join(', ')})` : ''}`,
+    `  재시도  ${r.retries.runs}회 · 합 ${r.retries.sumMin}분 · 중앙 ${r.retries.medianMin}분`,
+    `  재시도 비중 ${r.retryShare === null ? '측정 없음' : `${round1(r.retryShare * 100)}%`} (재시도 합 / 전체 합)`,
+    '  느린 샤드 상위 5:',
+    ...r.slowestShards.map((s) => `    ${s.name}  ${s.min}분 · 파일 ${s.files}개 · 계획 ${s.plannedMin === null ? '—' : `${s.plannedMin}분`}`),
+  ];
+  if (r.unreadable.length) lines.push(`  ⚠ 읽지 못한 파일 ${r.unreadable.length}개: ${r.unreadable.slice(0, 5).join(', ')}${r.unreadable.length > 5 ? ' …' : ''}`);
+  return lines.join('\n');
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const target = args.find((a) => !a.startsWith('--'));
+  if (!target) {
+    console.error('사용법: bun scripts/release-loop/gate-timing.ts <version|dir> [--json]');
+    process.exit(2);
+  }
+  const report = gateTiming(resolveGateLogDir(target));
+  console.log(json ? JSON.stringify(report, null, 2) : formatGateTiming(report));
+  if (!report.measured) process.exit(1);
+}

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { spawnSync } from 'node:child_process';
+import { isReleaseVersion } from './release-version.js';
 import { readFileSync } from 'node:fs';
 import { debug } from '../../src/debug/log.js';
 
@@ -17,7 +18,7 @@ export function readGraphContext(env: NodeJS.ProcessEnv = process.env): GraphCon
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid graph context');
   const context = value as Record<string, unknown>;
   const input = context.input as Record<string, unknown> | undefined;
-  if (!input || typeof input.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(input.version)
+  if (!input || typeof input.version !== 'string' || !isReleaseVersion(input.version)
     || typeof input.previousVersion !== 'string' || !/^\d+\.\d+\.\d+$/.test(input.previousVersion)) throw new Error('version and previousVersion required');
   return { input: input as GraphContext['input'], outputs: context.outputs && typeof context.outputs === 'object' ? context.outputs as GraphContext['outputs'] : {} };
 }

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

@@ -7,6 +7,7 @@ import { debug } from '../../src/debug/log.js';
 import { sendOutbound } from '../../src/domains/outbound-alert.js';
 import { effectiveInstanceRoot, prodInstanceRoot } from '../../src/instance/resolve.js';
 import { emitNodeResult, readGraphContext, type GraphContext } from './node-verdict.js';
+import { prereleaseKind } from './release-version.js';
 
 type Result = { outcome: 'ok' | 'fail'; verdict: 'pass' | 'fail'; summary: string; npm?: 'published' | 'already-published' | 'staged-not-visible'; humanAction?: 'npm-support' };
 type Exec = (command: string, args: string[], env?: NodeJS.ProcessEnv) => { status: number | null; stdout: string; stderr: string };
@@ -47,8 +48,11 @@ function metadata(value: unknown): { name?: string; version?: string } {
 export async function runNpmPublish(context: GraphContext = readGraphContext(), deps: NpmPublishDeps = {}): Promise<Result> {
   const version = context.input.version;
   let token = '';
+  // RELEASE-REHEARSAL-RC: a prerelease goes to `next` so `npm i elanous` never resolves to a rehearsal build.
+  let distTag = 'latest';
   try {
     if (context.outputs.publish?.outcome !== 'ok') throw new Error('publish must succeed before npm publish');
+    distTag = prereleaseKind(version) === null ? 'latest' : 'next';
     const stateDir = deps.stateDir ?? effectiveInstanceRoot();
     // REL3 — the archive prepare actually built (its output) wins over this process's universe: a resumed run can
     // resolve another universe (10-01 0.2.7: prepared in the pilot test universe, resumed in production).
@@ -67,14 +71,14 @@ export async function runNpmPublish(context: GraphContext = readGraphContext(),
       const [manifest, tags] = await Promise.all([readRegistry(`${PACKAGE_URL}/${version}`), readRegistry(PACKAGE_URL)]);
       if (manifest.status !== 200 && manifest.status !== 404) throw new Error(`npm registry version lookup failed (${manifest.status})`);
       if (tags.status !== 200) throw new Error(`npm registry tags lookup failed (${tags.status})`);
-      const latest = tags.body && typeof tags.body === 'object' && 'dist-tags' in tags.body
-        ? (tags.body as { 'dist-tags'?: { latest?: unknown } })['dist-tags']?.latest : undefined;
+      const tagged = tags.body && typeof tags.body === 'object' && 'dist-tags' in tags.body
+        ? (tags.body as { 'dist-tags'?: Record<string, unknown> })['dist-tags']?.[distTag] : undefined;
       if (manifest.status === 200 && (metadata(manifest.body).name !== 'elanous' || metadata(manifest.body).version !== version))
         throw new Error('npm registry version metadata mismatch');
-      return { visible: manifest.status === 200, tagged: manifest.status === 200 && latest === version };
+      return { visible: manifest.status === 200, tagged: manifest.status === 200 && tagged === version };
     };
     const before = await inspect();
-    if (before.tagged) return { outcome: 'ok', verdict: 'pass', npm: 'already-published', summary: `npm ${version} already published with latest tag` };
+    if (before.tagged) return { outcome: 'ok', verdict: 'pass', npm: 'already-published', summary: `npm ${version} already published with ${distTag} tag` };
     if (!before.visible) {
       // The npm token is a machine secret (like the GitHub App key): input → this universe → the production root.
       const tokenFile = context.input.npmTokenFile ?? [join(stateDir, 'secrets', 'npm-token'), join(deps.productionRoot ?? prodInstanceRoot(), 'secrets', 'npm-token')].find((p) => existsSync(p)) ?? join(stateDir, 'secrets', 'npm-token');
@@ -86,7 +90,7 @@ export async function runNpmPublish(context: GraphContext = readGraphContext(),
       try {
         const npmrc = join(dir, 'npmrc');
         writeFileSync(npmrc, `//registry.npmjs.org/:_authToken=${token}\n`, { mode: 0o600, flag: 'wx' });
-        published = run('npm', ['publish', candidate, '--ignore-scripts', '--tag', 'latest', '--access', 'public'], { ...process.env, NPM_CONFIG_USERCONFIG: npmrc });
+        published = run('npm', ['publish', candidate, '--ignore-scripts', '--tag', distTag, '--access', 'public'], { ...process.env, NPM_CONFIG_USERCONFIG: npmrc });
       } finally { rmSync(dir, { recursive: true, force: true }); }
       const output = `${published.stdout}\n${published.stderr}`;
       const staged = published.status !== 0 && /\bE409\b/i.test(output) && /previously staged/i.test(output);
@@ -96,10 +100,10 @@ export async function runNpmPublish(context: GraphContext = readGraphContext(),
     let last = before;
     for (let i = 0; i <= polls; i++) {
       last = await inspect();
-      if (last.tagged) return { outcome: 'ok', verdict: 'pass', npm: before.visible ? 'already-published' : 'published', summary: `npm ${version} visible with latest tag` };
+      if (last.tagged) return { outcome: 'ok', verdict: 'pass', npm: before.visible ? 'already-published' : 'published', summary: `npm ${version} visible with ${distTag} tag` };
       if (i < polls) await wait(Math.min(30_000, waitMinutes * 60_000 - i * 30_000));
     }
-    if (last.visible) throw new Error(`npm ${version} visible but dist-tags.latest did not reach ${version} within ${waitMinutes} minutes`);
+    if (last.visible) throw new Error(`npm ${version} visible but dist-tags.${distTag} did not reach ${version} within ${waitMinutes} minutes`);
     try { (deps.log ?? ((v, minutes) => debug.log('release-loop.npm', 'staged-not-visible', { version: v, waitedMinutes: minutes })))(version, waitMinutes); } catch { /* observation must not mask npm's staged state */ }
     try { (deps.alert ?? sendOutbound)(`npm ${version} 가 스테이징에 멈춤 — 계정 소유자 확인 필요`, 'alert'); } catch { /* alert failure must not block docs */ }
     return { outcome: 'ok', verdict: 'pass', npm: 'staged-not-visible', humanAction: 'npm-support', summary: 'npm 스테이징 — 레지스트리에 아직 없음' };

package/scripts/release-loop/ops-upgrade-node.ts

@@ -4,6 +4,7 @@ import { homedir, tmpdir } from 'node:os';
 import { join, isAbsolute } from 'node:path';
 import { debug } from '../../src/debug/log.js';
 import { errorResult, finishNode, lastResult, nodeOutput, readGraphContext, runCommand, type CommandResult, type CommandRunner } from './node-verdict.js';
+import { prereleaseKind } from './release-version.js';
 
 interface HostResult { host: string; ok: boolean; before: string; after: string; error?: string; skipped?: string; hooks?: string; restart?: 'no-service' }
 /** Where the internal feed is packed from: a checkout of the release tag, never the run's working tree. */
@@ -199,6 +200,12 @@ export function runOpsUpgrade(run: CommandRunner = runCommand, deps: OpsUpgradeD
 
 if (import.meta.main) {
   let version = '';
-  try { version = readGraphContext().input.version; process.exitCode = finishNode('ops-upgrade', version, runOpsUpgrade()); }
+  try {
+    version = readGraphContext().input.version;
+    // RELEASE-REHEARSAL-RC: a prerelease never lands docs on main or upgrades the operating hosts.
+    process.exitCode = finishNode('ops-upgrade', version, prereleaseKind(version) !== null
+      ? { outcome: 'ok', verdict: 'pass', summary: `ops-upgrade skipped — ${version} is a prerelease`, skipped: 'prerelease' }
+      : runOpsUpgrade());
+  }
   catch (error) { process.exitCode = finishNode('ops-upgrade', version, errorResult(error)); }
 }

package/scripts/release-loop/preflight.ts

@@ -0,0 +1,246 @@
+// `elanous release preflight` — 컷 30분 전 사전 점검(RELEASE-PREFLIGHT · 10-06).
+//
+// 🩸 계기(10-06 실측): 0.2.17 릴리스 런이 첫 노드(checklist-gate)에서 멎었다 — «발행 뒤» 칸(POSTPUB-VERIFY)이 그 판에
+//    남아 있었고 게이트가 그것을 미완으로 셌다. 컷이 올 때까지 아무도 몰랐다. 새 규칙 = 착지 마감 = 컷 − 30분, 그 30분에 이 점검.
+// ⛔ 읽기 전용 — 칸을 옮기지도, 동결을 바꾸지도, push 하지도 않는다. 옮길 것은 «명령»으로 제안만 한다.
+// ⛔ 게이트 규칙을 다시 쓰지 않는다 — checklist-gate 노드 · release run 진입 검사 · 예약 시작 준비 검사(releaseReadiness, #24557)가
+//    함께 쓰는 단 하나의 판정 cutChecklistGate 를 그대로 부르고, 예약 시작 경로는 releaseReadiness 를 CLI 와 같은 인자로 부른다.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { cutChecklistGate, listChecklist, type ChecklistItem } from '../../src/release-loop/checklist.js';
+import { getSchedule, formatKst, type ReleaseSchedule } from '../../src/release-loop/release-schedule.js';
+import { readLandingFreeze, landingFreezeMessage, type LandingFreeze } from '../../src/release-loop/landing-freeze.js';
+import { effectiveInstanceRoot } from '../../src/instance/resolve.js';
+import { debug } from '../../src/debug/log.js';
+import { releaseReadiness } from './release-readiness.js';
+import { latestPublishedPreviousVersion, runUnattendedRelease, type UnattendedReleaseDeps } from './unattended-release.js';
+
+export type PreflightLevel = 'ok' | 'warn' | 'block';
+export type PreflightCheck = 'checklist' | 'postpub' | 'run-input' | 'freeze' | 'schedule';
+export interface PreflightFinding { level: PreflightLevel; check: PreflightCheck; id?: string; message: string; suggestion?: string }
+export interface GateMeasure { version: string; runId: string; gateSeconds: number; toPublishSeconds?: number }
+const compareStable = (a: string, b: string) => { const x = a.split('.').map(Number), y = b.split('.').map(Number); return x[0]! - y[0]! || x[1]! - y[1]! || x[2]! - y[2]!; };
+export interface PreflightResult {
+  version: string;
+  next: string;
+  verdict: PreflightLevel;
+  blockers: number;
+  warnings: number;
+  findings: PreflightFinding[];
+  schedule: { cutAt: string; landBy: string | null; publishAt: string | null; publishAtSource: 'option' | 'cadence' | null } | null;
+  /** The immediately previous release (by version order) whose gate is compared. */
+  previousVersion: string | null;
+  gateMeasure: GateMeasure | null;
+  /** When the previous release has no record: the newest measured older release, labelled with its version. */
+  fallbackGateMeasure: GateMeasure | null;
+}
+
+export interface PreflightDeps {
+  now?: Date;
+  /** Planned publish time (ISO). Without it, the October cadence (07:00 · 18:00 KST) after the cut is assumed. */
+  publishAt?: string;
+  runInput?: (version: string) => Promise<{ input: unknown }>;
+  freeze?: () => LandingFreeze | null;
+  schedule?: (version: string) => ReleaseSchedule | null;
+  graphRunsRoot?: string;
+  releaseRunDeps?: UnattendedReleaseDeps;
+  /** The immediately previous release; default = the run input's previousVersion (release ledger). */
+  previousVersion?: string;
+}
+
+const POSTPUB_ID = /^POSTPUB-/i;
+// Only a title that «starts» with the marker: a pre-publish cell often mentions «발행 뒤» in its body (a slot, a plan).
+const POSTPUB_TITLE = /^[«"'(]?\s*(발행\s*(뒤|후)|post-?publish)/i;
+const STABLE = /^\d+\.\d+\.\d+$/;
+
+export function isPostPublishCell(item: Pick<ChecklistItem, 'id' | 'title'> & { kind?: string }): boolean {
+  return POSTPUB_ID.test(item.id) || POSTPUB_TITLE.test(item.title) || (item as { kind?: string }).kind === 'postpub';
+}
+
+export function nextPatch(version: string): string {
+  const [major, minor, patch] = version.split('.').map(Number);
+  return `${major}.${minor}.${patch! + 1}`;
+}
+
+const kstHour = (ms: number) => Number(new Intl.DateTimeFormat('en-GB', { timeZone: 'Asia/Seoul', hour: '2-digit', hourCycle: 'h23' }).format(new Date(ms)));
+
+/** October cadence: the first 07:00 or 18:00 KST strictly after the cut (a cut at 07:00 publishes at 18:00). */
+export function cadencePublishAt(cutAt: string): string {
+  const cut = Date.parse(cutAt);
+  const startOfHour = Math.floor(cut / 3_600_000) * 3_600_000 + 3_600_000;
+  for (let t = startOfHour; t < cut + 48 * 3_600_000; t += 3_600_000) {
+    const h = kstHour(t);
+    if (h === 7 || h === 18) return new Date(t).toISOString();
+  }
+  return new Date(cut).toISOString();
+}
+
+/**
+ * A release's measured gate: the newest finished release-loop run of «that» version (`{ version }`) or, with
+ * `{ below }`, the most recently measured run of any version under it. Node timings are not stored in the run state, so the gate time is the start of the gate node's context file to
+ * the start of the next node's (contexts/<n>.json is written when node n starts). Null when nothing was measured.
+ */
+export function releaseGateMeasure(which: { version: string } | { below: string }, root = join(effectiveInstanceRoot(), 'graph-runs', 'release-loop')): GateMeasure | null {
+  if (!existsSync(root)) return null;
+  const runs: Array<{ runId: string; version: string; startedAt: string; path: string[]; file: string }> = [];
+  for (const file of readdirSync(root)) {
+    if (!file.endsWith('.json') || file.includes('.decision')) continue;
+    try {
+      const state = JSON.parse(readFileSync(join(root, file), 'utf8')) as { runId?: string; status?: string; startedAt?: string; path?: string[]; input?: { version?: string } };
+      const v = state.input?.version;
+      if (state.status !== 'done' || typeof v !== 'string' || !STABLE.test(v) || !Array.isArray(state.path) || typeof state.startedAt !== 'string') continue;
+      if ('version' in which ? v !== which.version : compareStable(v, which.below) >= 0) continue;
+      runs.push({ runId: state.runId ?? file.slice(0, -5), version: v, startedAt: state.startedAt, path: state.path, file });
+    } catch { /* an unreadable run is skipped — the measure is best-effort */ }
+  }
+  // `{ version }`: the newest run of that release. `{ below }` (only a labelled reference when the previous release has
+  // no record): the most recently measured run, not the highest version.
+  runs.sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt));
+  for (const run of runs) {
+    const contexts = join(root, `${run.file}.contexts`);
+    const index = run.path.indexOf('gate');
+    if (index < 0 || !existsSync(contexts)) continue;
+    const at = (i: number): number | null => {
+      const path = join(contexts, `${i + 1}.json`);
+      try {
+        const ctx = JSON.parse(readFileSync(path, 'utf8')) as { nodeId?: string };
+        return ctx.nodeId === run.path[i] ? statSync(path).mtimeMs : null;
+      } catch { return null; }
+    };
+    const gateStart = at(index), gateEnd = at(index + 1);
+    if (gateStart === null || gateEnd === null || gateEnd < gateStart) continue;
+    const publishIndex = run.path.indexOf('publish');
+    const publishStart = publishIndex >= 0 ? at(publishIndex) : null;
+    return {
+      version: run.version, runId: run.runId, gateSeconds: Math.round((gateEnd - gateStart) / 1000),
+      ...(publishStart !== null ? { toPublishSeconds: Math.round((publishStart - Date.parse(run.startedAt)) / 1000) } : {}),
+    };
+  }
+  return null;
+}
+
+const minutes = (seconds: number) => `${Math.round(seconds / 60)}분`;
+const short = (title: string) => (title.length > 60 ? `${title.slice(0, 60)}…` : title);
+
+export async function releasePreflight(version: string, deps: PreflightDeps = {}): Promise<PreflightResult> {
+  if (!STABLE.test(version)) throw new Error(`release preflight takes a stable version x.y.z: ${version}`);
+  const now = deps.now ?? new Date();
+  const next = nextPatch(version);
+  const findings: PreflightFinding[] = [];
+  const moveHint = (id: string) => `elanous release checklist move ${id} --from ${version} --to ${next} --reason "발행 뒤 칸 — 다음 판에서 확인"`;
+
+  // 1·2. Checklist gate simulation «at the cut» (the node and the run entry both judge after land-by) ⊕ post-publish cells.
+  const schedule = (deps.schedule ?? ((v: string) => getSchedule(v, deps.releaseRunDeps?.ledgerRoot)))(version);
+  // Always the stored cut (before or after it): the preflight simulates «the cut», not the moment it is run.
+  const judgeAt = schedule ? new Date(Date.parse(schedule.cutAt)) : now;
+  const data = listChecklist(version);
+  const { autoMoved, ...gate } = cutChecklistGate(version, schedule?.landBy, judgeAt);
+  const p0 = data.items.filter((item) => item.status === 'yellow' && item.priority === 'P0').map((item) => item.id);
+  const byId = new Map(data.items.map((item) => [item.id, item]));
+  const blockReason = new Map<string, string>();
+  for (const id of gate.red) blockReason.set(id, '빨강');
+  for (const id of gate.undecided) blockReason.set(id, '노랑 · 처분 없음(판정 없음)');
+  for (const id of gate.blocked) blockReason.set(id, p0.includes(id) ? 'P0 노랑' : '노랑 · 처분 block');
+  // The scheduled start (`release run --if-ready` · `auto-start`) first asks releaseReadiness — the same call the CLI
+  // makes, judged at the cut. It shares cutChecklistGate (#24557); an injected deps.checklist may still differ, so any
+  // cell it refuses that the cut judgement did not is reported too (report, don't re-rule).
+  try {
+    const readiness = releaseReadiness(version, { ledgerRoot: deps.releaseRunDeps?.ledgerRoot, checklist: deps.releaseRunDeps?.checklist, now: () => judgeAt });
+    if (readiness.reason === 'checklist-blocked') {
+      for (const id of [...readiness.details.red, ...readiness.details.undecided, ...readiness.details.blocked]) {
+        if (!blockReason.has(id)) blockReason.set(id, '예약 시작(release run --if-ready · auto-start)의 준비 검사(releaseReadiness)가 런을 거부한다');
+      }
+    } else if (readiness.reason === 'already-published' || readiness.reason === 'already-running') {
+      // Both refuse the scheduled start — a running release (live run.lock) or a published one.
+      findings.push({ level: 'block', check: 'run-input', message: `준비 검사(releaseReadiness)가 예약 시작을 거부한다: ${readiness.reason} (${readiness.details})` });
+    }
+  } catch (error) {
+    findings.push({ level: 'block', check: 'run-input', message: `준비 검사(releaseReadiness) 오류 — ${error instanceof Error ? error.message : String(error)}` });
+  }
+  for (const [id, reason] of blockReason) {
+    const item = byId.get(id);
+    const postpub = item ? isPostPublishCell(item) : false;
+    findings.push({
+      level: 'block', check: postpub ? 'postpub' : 'checklist', id,
+      message: `${id} — ${reason}${postpub ? ' · 발행 뒤 칸이 이 판에 남아 있다' : ''}${item ? ` · «${short(item.title)}»` : ''}`,
+      ...(postpub ? { suggestion: moveHint(id) } : {}),
+    });
+  }
+  for (const item of data.items) {
+    if (blockReason.has(item.id) || !isPostPublishCell(item)) continue;
+    findings.push({ level: 'warn', check: 'postpub', id: item.id, message: `${item.id} — 발행 뒤 칸이 이 판에 남아 있다(지금은 막지 않음 · 상태 ${item.status} · 처분 ${item.disposition ?? '-'})`, suggestion: moveHint(item.id) });
+  }
+  for (const id of autoMoved) {
+    if (!blockReason.has(id)) findings.push({ level: 'warn', check: 'checklist', id, message: `${id} — 처분 없는 노랑 · 컷(착지 마감 뒤)에서 노드가 ${next} 로 자동 이월한다` });
+  }
+  for (const p of gate.parity ?? []) findings.push({ level: 'warn', check: 'checklist', id: p.id, message: `${p.id} — 화면 짝 경고: ${p.why}` });
+  if (!blockReason.size) findings.push({ level: 'ok', check: 'checklist', message: `체크리스트 게이트 모의 통과 — ${data.items.length}칸 · 이월 ${gate.moved.length} · 알려진 문제 ${gate.knownIssues.length}` });
+
+  // 3. The same input check `release run --dry-run` makes.
+  let runPrevious: string | undefined;
+  try {
+    const result = await (deps.runInput ?? ((v: string) => runUnattendedRelease({ version: v, dryRun: true }, deps.releaseRunDeps ?? {})))(version);
+    const input = result.input as { previousVersion?: string; gatePodPool?: string };
+    runPrevious = input.previousVersion;
+    findings.push({ level: 'ok', check: 'run-input', message: `release run --dry-run 입력 OK — 직전 판 ${input.previousVersion ?? '-'} · 게이트 풀 ${input.gatePodPool ?? '-'}` });
+  } catch (error) {
+    findings.push({ level: 'block', check: 'run-input', message: `release run --dry-run 입력 오류 — ${error instanceof Error ? error.message : String(error)}` });
+  }
+
+  // 4. Landing freeze (emergency switch since RELEASE-BRANCH): when on, `release run` refuses.
+  try {
+    const frozen = (deps.freeze ?? (() => readLandingFreeze(deps.releaseRunDeps?.freezeRoot)))();
+    if (frozen) findings.push({ level: 'block', check: 'freeze', message: `${landingFreezeMessage(frozen)} — release run 이 거부한다`, suggestion: 'elanous freeze off (또는 의도한 강행이면 release run --force-freeze)' });
+    else findings.push({ level: 'ok', check: 'freeze', message: '착지 동결 꺼짐' });
+  } catch (error) {
+    findings.push({ level: 'block', check: 'freeze', message: `동결 상태를 못 읽었다 — ${error instanceof Error ? error.message : String(error)}` });
+  }
+
+  // 5. Schedule sanity: land-by = cut − 30 min · cut→publish window vs the previous measured gate.
+  let scheduleOut: PreflightResult['schedule'] = null;
+  let gateMeasure: GateMeasure | null = null;
+  let fallbackGateMeasure: GateMeasure | null = null;
+  let previousVersion: string | null = deps.previousVersion ?? runPrevious ?? null;
+  if (!previousVersion) { try { previousVersion = latestPublishedPreviousVersion(version, deps.releaseRunDeps?.ledgerRoot); } catch { previousVersion = null; } }
+  if (!schedule) {
+    findings.push({ level: 'warn', check: 'schedule', message: `판 일정 없음 — elanous release schedule set --version ${version} --cut-at <iso> --land-by <iso>` });
+  } else {
+    const cut = Date.parse(schedule.cutAt);
+    const publishAt = deps.publishAt ? new Date(deps.publishAt).toISOString() : cadencePublishAt(schedule.cutAt);
+    scheduleOut = { cutAt: schedule.cutAt, landBy: schedule.landBy, publishAt, publishAtSource: deps.publishAt ? 'option' : 'cadence' };
+    if (!schedule.landBy) findings.push({ level: 'warn', check: 'schedule', message: `착지 마감 없음 — 컷 ${formatKst(schedule.cutAt)} · 규칙은 컷 − 30분` });
+    else if (cut - Date.parse(schedule.landBy) < 30 * 60_000) findings.push({ level: 'warn', check: 'schedule', message: `착지 마감 ${formatKst(schedule.landBy)} 이 컷 − 30분보다 늦다(컷 ${formatKst(schedule.cutAt)})` });
+    else findings.push({ level: 'ok', check: 'schedule', message: `일정 — 착지 마감 ${formatKst(schedule.landBy)} · 컷 ${formatKst(schedule.cutAt)}` });
+    gateMeasure = previousVersion ? releaseGateMeasure({ version: previousVersion }, deps.graphRunsRoot) : null;
+    if (!gateMeasure) fallbackGateMeasure = releaseGateMeasure({ below: version }, deps.graphRunsRoot);
+    const windowSeconds = Math.round((Date.parse(publishAt) - cut) / 1000);
+    const publishLabel = `발행 ${formatKst(publishAt)}${deps.publishAt ? '' : '(기본: 판 주기 07·18시 · --publish-at 로 바꾼다)'}`;
+    if (!gateMeasure) {
+      const fallback = fallbackGateMeasure ? ` · 참고: 가장 최근 실측은 ${fallbackGateMeasure.version} 게이트 ${minutes(fallbackGateMeasure.gateSeconds)}(직전 판 아님)` : ' · 게이트 실측 없음';
+      findings.push({ level: 'warn', check: 'schedule', message: `직전 판${previousVersion ? `(${previousVersion})` : ''} 실측 없음 — 컷→${publishLabel} 창 ${minutes(windowSeconds)}${fallback}` });
+    }
+    else {
+      const measured = `직전 실측 ${gateMeasure.version} 게이트 ${minutes(gateMeasure.gateSeconds)}${gateMeasure.toPublishSeconds !== undefined ? ` · 런 시작→발행 노드 ${minutes(gateMeasure.toPublishSeconds)}` : ''}`;
+      const need = Math.max(gateMeasure.gateSeconds, gateMeasure.toPublishSeconds ?? 0);
+      findings.push(windowSeconds < need
+        ? { level: 'warn', check: 'schedule', message: `컷→${publishLabel} 창 ${minutes(windowSeconds)} < ${measured} — 발행이 늦어진다` }
+        : { level: 'ok', check: 'schedule', message: `컷→${publishLabel} 창 ${minutes(windowSeconds)} ≥ ${measured}` });
+    }
+  }
+
+  const blockers = findings.filter((f) => f.level === 'block').length;
+  const warnings = findings.filter((f) => f.level === 'warn').length;
+  debug.log('release.preflight', 'checked', { version, blockers, warnings });
+  return { version, next, verdict: blockers ? 'block' : warnings ? 'warn' : 'ok', blockers, warnings, findings, schedule: scheduleOut, previousVersion, gateMeasure, fallbackGateMeasure };
+}
+
+const ICON: Record<PreflightLevel, string> = { ok: '✅', warn: '⚠️', block: '⛔' };
+
+export function formatPreflight(result: PreflightResult): string[] {
+  const order: PreflightLevel[] = ['block', 'warn', 'ok'];
+  const lines = [...result.findings].sort((a, b) => order.indexOf(a.level) - order.indexOf(b.level))
+    .flatMap((f) => [`${ICON[f.level]} ${f.message}`, ...(f.suggestion ? [`    → ${f.suggestion}`] : [])]);
+  const verdict = result.verdict === 'block' ? `⛔ 판정: 막힘 — ⛔${result.blockers} ⚠️${result.warnings} · 컷 전에 고친다`
+    : result.verdict === 'warn' ? `⚠️ 판정: 통과(경고 ${result.warnings})` : '✅ 판정: 통과';
+  return [`release preflight ${result.version} (다음 판 ${result.next})`, ...lines, verdict];
+}

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

@@ -5,6 +5,7 @@ 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 { prereleaseKind } from './release-version.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 {
@@ -20,6 +21,12 @@ export function publicNotes(markdown: string, pages: { pages: Array<{ id: string
   });
 }
 
+/** RELEASE-REHEARSAL-RC: prerelease notes open with a label, so nobody mistakes a rehearsal for the stable release. */
+export function labelPrerelease(version: string, body: string): string {
+  if (prereleaseKind(version) === null) return body;
+  return `> **Pre-release** — ${version} is a pre-release, not the latest version. Install it with \`npm i -g elanous@next\`; \`latest\` stays on the current stable release.\n\n${body}`;
+}
+
 /** Polls each release asset until it answers 200 (following redirects). Returns the names still missing. */
 export function waitForAssets(run: CommandRunner, repo: string, tag: string, names: readonly string[], waitSeconds: unknown = 600,
   sleep: (ms: number) => void = (ms) => Bun.sleepSync(ms)): string[] {
@@ -61,7 +68,7 @@ export function runPublish(run: CommandRunner = runCommand, prodFreezeRoot?: str
   const registry = run('git', ['show', `${branch}:website/pages.json`]);
   if (doc.status !== 0 || registry.status !== 0) throw new Error(`docs branch missing notes or pages: ${branch}`);
   if (!doc.stdout.startsWith(`# ${version}\n`)) throw new Error('release notes version mismatch');
-  const body = publicNotes(doc.stdout, JSON.parse(registry.stdout));
+  const body = labelPrerelease(version, publicNotes(doc.stdout, JSON.parse(registry.stdout)));
   const dir = mkdtempSync(join(tmpdir(), 'release-publish-notes-'));
   try {
     const file = join(dir, 'notes.md');