elanous 0.2.16 → 0.2.18

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

@@ -0,0 +1,115 @@
+// RELEASE-BRANCH (10-06): resume a failed release run after `release cut-branch --append --pick` moved release/<v>.
+// The saved version-release output is re-pointed at the new branch tip (fast-forward only, state backed up first), so
+// every later node reads the repaired commit without anyone hand-editing the run state.
+import { spawnSync } from 'node:child_process';
+import { constants, copyFileSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+import { effectiveInstanceRoot } from '../../src/instance/resolve.js';
+import { lastJsonObject, runGraph, type GraphRunState } from '../../src/graph-runner/runner.js';
+import { isReleaseVersion } from './release-version.js';
+
+const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
+
+export interface ResumeReleaseDeps {
+  root?: string;
+  repo?: string;
+  /** Runs git and returns stdout (throws on failure). */
+  git?: (args: string[]) => string;
+  /** `git merge-base --is-ancestor a b`. */
+  isAncestor?: (ancestor: string, descendant: string) => boolean;
+  graph?: typeof runGraph;
+  /** The release graph (tests point it at a probe graph with the same graph id). */
+  graphPath?: string;
+  /** Node command runner for the resumed graph (tests record each node's context instead of running it). */
+  runBash?: NonNullable<NonNullable<Parameters<typeof runGraph>[1]>['deps']>['runBash'];
+  now?: () => Date;
+}
+
+export interface TipRefresh { version: string; branch: string; from: string; to: string; changed: boolean; statePath: string; backup?: string }
+
+function gitRunner(repo: string) {
+  return (args: string[]): string => {
+    // git-spawn-allow: read-only fetch / ls-remote / rev-parse against release/<v>; nothing is pushed or checked out.
+    const result = spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
+    if (result.status !== 0 || result.error) throw new Error(`git ${args[0]} failed: ${(result.stderr || result.error || 'no output').toString().trim()}`);
+    return result.stdout.trim();
+  };
+}
+
+function ancestorRunner(repo: string) {
+  return (ancestor: string, descendant: string): boolean => {
+    const result = spawnSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], { cwd: repo });
+    if (result.status !== 0 && result.status !== 1) throw new Error(`git merge-base failed: ${result.error || result.stderr || 'unknown'}`);
+    return result.status === 0;
+  };
+}
+
+function safeRunId(runId: string): string {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) || runId === '.' || runId === '..') throw new Error(`invalid run id: ${runId}`);
+  return runId;
+}
+
+/** Point the saved version-release output at the current release/<v> tip (fast-forward of the recorded commit only). */
+export function refreshReleaseBranchTip(runId: string, deps: ResumeReleaseDeps = {}, from?: string): TipRefresh {
+  const root = deps.root ?? effectiveInstanceRoot();
+  const statePath = join(root, 'graph-runs', 'release-loop', `${safeRunId(runId)}.json`);
+  const state = JSON.parse(readFileSync(statePath, 'utf8')) as GraphRunState;
+  if (state.graphId !== 'release-loop' || state.runId !== runId) throw new Error(`run identity mismatch: ${statePath}`);
+  if (state.status !== 'failed') throw new Error(`release run ${runId} is ${state.status} — only a failed run is resumed`);
+  const restartAt = from === undefined ? -1 : state.path.indexOf(from);
+  if (from !== undefined && (restartAt < 0 || state.path.lastIndexOf(from) !== restartAt)) throw new Error(`--from ${from} is not a node on the saved path of ${runId}`);
+  const index = state.nodes.findIndex((node) => node.nodeId === 'version-release');
+  const record = index >= 0 ? state.nodes[index]! : undefined;
+  const output = record ? lastJsonObject(record.output) : undefined;
+  if (!record?.ok || !output) throw new Error(`release run ${runId} has no successful version-release record`);
+  const version = typeof output.version === 'string' ? output.version : '';
+  const recorded = typeof output.commit === 'string' ? output.commit : '';
+  if (!isReleaseVersion(version) || !/^[0-9a-f]{40}$/i.test(recorded)) throw new Error(`release run ${runId} version-release output is not a release commit`);
+  const branch = `release/${version}`;
+  // Only a run that cut release/<v> itself is re-pointed — a main-cut or --cut-commit run has no branch of its own.
+  const input = (state.input ?? {}) as { branchCut?: unknown; version?: unknown };
+  if (input.branchCut !== true || input.version !== version || output.branch !== branch) {
+    throw new Error(`release run ${runId} was not cut as ${branch} (input.branchCut/version or version-release branch differ) — refusing to resume`);
+  }
+  const git = deps.git ?? gitRunner(deps.repo ?? process.cwd());
+  const advertised = git(['ls-remote', '--heads', 'origin', `refs/heads/${branch}`]).split(/\s+/)[0] ?? '';
+  if (!/^[0-9a-f]{40}$/i.test(advertised)) throw new Error(`${branch} is not on origin — this run was not cut as a release branch`);
+  git(['fetch', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`]);
+  const to = git(['rev-parse', '--verify', `refs/remotes/origin/${branch}^{commit}`]);
+  if (to !== advertised) throw new Error(`${branch} moved while it was read (${advertised} → ${to})`);
+  if (to === recorded) {
+    debug.log('release-loop.resume', 'tip-unchanged', { runId, version, commit: to });
+    return { version, branch, from: recorded, to, changed: false, statePath };
+  }
+  // A repair only appends (`cut-branch --append`): anything but a fast-forward is a different release.
+  if (!(deps.isAncestor ?? ancestorRunner(deps.repo ?? process.cwd()))(recorded, to)) {
+    throw new Error(`${branch} tip ${to} does not descend from the recorded release commit ${recorded} — refusing to resume`);
+  }
+  // A new tip invalidates everything built from the old one (gate verdict, prepared archive, …): restart no later
+  // than the first node that consumed the commit, so each of them runs again on the new tip.
+  const firstConsumer = state.path.indexOf('gate');
+  if (restartAt >= 0 && firstConsumer >= 0 && restartAt > firstConsumer) {
+    throw new Error(`${branch} moved (${recorded.slice(0, 12)} → ${to.slice(0, 12)}): resume at gate or earlier — later nodes were built from the old tip`);
+  }
+  const stamp = (deps.now?.() ?? new Date()).toISOString().replace(/[:.]/g, '-');
+  const backup = `${statePath}.before-tip-${stamp}-${process.pid}-${to.slice(0, 12)}.bak`;
+  // Exclusive: a retry never overwrites an earlier backup.
+  copyFileSync(statePath, backup, constants.COPYFILE_EXCL);
+  const refreshed = { ...output, commit: to, refreshedFrom: recorded };
+  const text = typeof record.output === 'string' ? record.output.replace(/\s*$/, '') : '';
+  state.nodes[index] = { ...record, output: `${text}\n${JSON.stringify(refreshed)}\n` };
+  const temporary = `${statePath}.${process.pid}.tip.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`);
+  renameSync(temporary, statePath);
+  debug.log('release-loop.resume', 'tip-refreshed', { runId, version, branch, from: recorded, to, backup });
+  return { version, branch, from: recorded, to, changed: true, statePath, backup };
+}
+
+/** Refresh the branch tip, then restart the failed run at `from` with the saved graph snapshot. */
+export async function resumeReleaseRun(opts: { runId: string; from: string }, deps: ResumeReleaseDeps = {}): Promise<{ tip: TipRefresh; state: GraphRunState }> {
+  if (opts.from === 'version-release') throw new Error('--from version-release would cut again — resume at a later node');
+  const tip = refreshReleaseBranchTip(opts.runId, deps, opts.from);
+  const state = await (deps.graph ?? runGraph)(deps.graphPath ?? GRAPH, { resumeRunId: opts.runId, fromNodeId: opts.from, ...(deps.root || deps.runBash ? { deps: { ...(deps.root ? { root: deps.root } : {}), ...(deps.runBash ? { runBash: deps.runBash } : {}) } } : {}) });
+  return { tip, state };
+}

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

@@ -1,12 +1,15 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { getElanousConfigDirOverride } from '../../src/elanous-config-dir.js';
 import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
 import { userConfigPath } from '../../src/user-config.js';
-import { checklistGate } from '../../src/release-loop/checklist.js';
+import { cutChecklistGate } from '../../src/release-loop/checklist.js';
+import { getSchedule } from '../../src/release-loop/release-schedule.js';
 import { isLandingFreezeRefusal, readLandingFreeze, LandingFrozenError } from '../../src/release-loop/landing-freeze.js';
 import { debug } from '../../src/debug/log.js';
 import { runGraph, type GraphRunState } from '../../src/graph-runner/runner.js';
+import { baseVersion, isStableVersion, nextPrereleaseVersion, type PrereleaseKind } from './release-version.js';
 
 const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
@@ -29,6 +32,8 @@ export interface ReleaseRunInput extends ReleaseLoopConfig {
   cutCommit?: string;
   gatePodPool: string;
   forceFreeze?: boolean;
+  /** RELEASE-BRANCH: version-release cuts release/<v> from main HEAD and bumps only the branch. */
+  branchCut?: boolean;
 }
 
 export interface UnattendedReleaseDeps {
@@ -36,8 +41,25 @@ export interface UnattendedReleaseDeps {
   config?: ReleaseLoopConfig;
   configPath?: string;
   graph?: (path: string, options: { input: ReleaseRunInput }) => Promise<GraphRunState>;
-  checklist?: typeof checklistGate;
+  checklist?: (version: string) => Pick<ReturnType<typeof cutChecklistGate>, 'ok' | 'red' | 'undecided' | 'blocked'>;
   freezeRoot?: string;
+  /** Names already taken for prerelease numbering (remote release branches and tags). */
+  releaseRefs?: (base: string, kind: PrereleaseKind) => string[];
+}
+
+/** Remote `release/<base>-<kind>.*` branches and `v<base>-<kind>.*` tags — read-only. */
+export function remoteReleaseRefs(base: string, kind: PrereleaseKind, repo = process.cwd()): string[] {
+  // git-spawn-allow: read-only ls-remote to number a prerelease.
+  const result = spawnSync('git', ['ls-remote', 'origin', `refs/heads/release/${base}-${kind}.*`, `refs/tags/v${base}-${kind}.*`], { cwd: repo, encoding: 'utf8' });
+  if (result.status !== 0 || result.error) throw new Error(`git ls-remote failed: ${(result.stderr || result.error || 'no output').toString().trim()}`);
+  return result.stdout.split('\n').map((line) => line.split(/\s+/)[1] ?? '').filter(Boolean);
+}
+
+/** `0.2.18` + `rc` → the next free `0.2.18-rc.<n>`; a stable run keeps its version. */
+export function resolveRunVersion(version: string, prerelease: PrereleaseKind | undefined, deps: UnattendedReleaseDeps = {}): string {
+  if (!prerelease) return version;
+  if (!isStableVersion(version)) throw new Error(`--prerelease takes the base version x.y.z: ${version}`);
+  return nextPrereleaseVersion(version, prerelease, (deps.releaseRefs ?? remoteReleaseRefs)(version, prerelease));
 }
 
 function compareVersions(a: string, b: string): number {
@@ -76,7 +98,7 @@ export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDep
   const config = deps.config ?? releaseLoopConfig(deps.configPath);
   const pool = config.gatePodPool;
   if (typeof pool !== 'string' || !pool.trim()) throw new Error('release.loop.gatePodPool is required before graph execution');
-  const previousVersion = latestPublishedPreviousVersion(version, deps.ledgerRoot);
+  const previousVersion = latestPublishedPreviousVersion(baseVersion(version), deps.ledgerRoot);
   return {
     ...config,
     version, previousVersion,
@@ -87,9 +109,14 @@ export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDep
 
 /** Fail closed at the entry boundary, before any graph node can change a release. */
 export async function runUnattendedRelease(
-  opts: { version: string; dryRun?: boolean; cutCommit?: string; forceFreeze?: boolean },
+  opts: { version: string; dryRun?: boolean; cutCommit?: string; forceFreeze?: boolean; mainCut?: boolean; prerelease?: PrereleaseKind },
   deps: UnattendedReleaseDeps = {},
 ): Promise<{ input: ReleaseRunInput; dryRun: boolean; state?: GraphRunState }> {
+  // RELEASE-BRANCH (10-06): the default cut is a release branch, so main keeps landing and the run no longer needs a
+  // landing freeze. A freeze stays the emergency switch: when one is on, it still stops the run (`--force-freeze` overrides).
+  // `--cut-commit` (an already-cut branch) and `--main-cut` keep the old main-bump path.
+  const branchCut = opts.cutCommit === undefined && !opts.mainCut;
+  if (opts.prerelease && !branchCut) throw new Error('--prerelease needs the release-branch cut (no --cut-commit / --main-cut): a rehearsal must never bump main');
   if (!opts.dryRun) {
     const frozen = readLandingFreeze(deps.freezeRoot);
     if (frozen) {
@@ -97,11 +124,20 @@ export async function runUnattendedRelease(
       if (!opts.forceFreeze) throw new LandingFrozenError(frozen);
     }
   }
-  const input = buildReleaseRunInput(opts.version, deps, opts.cutCommit);
+  const version = resolveRunVersion(opts.version, opts.prerelease, deps);
+  const input = buildReleaseRunInput(version, deps, opts.cutCommit);
   if (opts.forceFreeze) input.forceFreeze = true;
+  if (branchCut) input.branchCut = true;
+  debug.log('release.run', 'input', { version, requested: opts.version, branchCut, prerelease: opts.prerelease ?? null, dryRun: opts.dryRun === true });
   if (opts.dryRun) return { input, dryRun: true };
-  const gate = (deps.checklist ?? checklistGate)(opts.version);
-  if (!gate.ok) throw new Error(`release checklist blocked: ${[...gate.red, ...gate.undecided, ...gate.blocked].join(', ')}`);
+  if (opts.prerelease) {
+    // A rehearsal neither judges nor carries the stable version's checklist cells.
+    debug.log('release.run', 'checklist-skipped', { version, reason: 'prerelease' });
+  } else {
+    // Same judgement as the checklist-gate node: past the landing deadline non-P0 yellows carry; P0 yellows block.
+    const gate = (deps.checklist ?? ((v: string) => cutChecklistGate(v, getSchedule(v)?.landBy)))(version);
+    if (!gate.ok) throw new Error(`release checklist blocked: ${[...gate.red, ...gate.undecided, ...gate.blocked].join(', ')}`);
+  }
   const beforeGraph = readLandingFreeze(deps.freezeRoot);
   if (beforeGraph && !opts.forceFreeze) throw new LandingFrozenError(beforeGraph);
   const state = await (deps.graph ?? runGraph)(GRAPH, { input });

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

@@ -5,12 +5,17 @@ import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { emitNodeResult } from './node-verdict.js';
 import { debug } from '../../src/debug/log.js';
+import { effectiveInstanceRoot, prodInstanceRoot } from '../../src/instance/resolve.js';
+import { landingFreezeMessage, readLandingFreeze, type LandingFreeze } from '../../src/release-loop/landing-freeze.js';
+import { baseVersion, isReleaseVersion, isStableVersion, prereleaseKind } from './release-version.js';
 
 type Kind = 'release' | 'dev-bump';
-type Output = { outcome: 'ok' | 'error'; kind: Kind | null; version: string | null; commit: string | null; pr: number | null; files?: string[]; worktree?: string; error?: string };
+type Output = { outcome: 'ok' | 'error'; kind: Kind | null; version: string | null; commit: string | null; pr: number | null; files?: string[]; worktree?: string; error?: string;
+  /** RELEASE-BRANCH: the release branch the cut lives on and the main commit it was cut from. */
+  branch?: string; base?: string; existing?: boolean; skipped?: string };
 
 export function nextDevVersion(version: string): string {
-  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(version);
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(isReleaseVersion(version) ? baseVersion(version) : version);
   if (!match) throw new Error(`invalid release version: ${version}`);
   return `${match[1]}.${match[2]}.${BigInt(match[3]!) + 1n}-dev.0`;
 }
@@ -64,9 +69,136 @@ function shippedNextMdLines(repo: string, cut: string | undefined): { lines: Set
   return { lines: new Set(shown.stdout.split('\n').map((line) => line.trim()).filter((line) => line.startsWith('- '))) };
 }
 
-function landing(repo: string, kind: Kind, releaseVersion: string, cut?: string, cutCommit?: string): Output {
+/** Rewrite the version in package.json, server.json, the ACP agent card and the bun.lock root; returns the files touched. */
+function writeVersionBump(worktree: string, current: string, target: string): string[] {
+  const path = join(worktree, 'package.json');
+  const text = readFileSync(path, 'utf8');
+  const old = `"version": "${current}"`;
+  if (!text.includes(old)) throw new Error(`package.json version field not found: ${current}`);
+  writeFileSync(path, text.replace(old, `"version": "${target}"`));
+  const files = ['package.json'];
+  const serverPath = join(worktree, 'server.json');
+  if (existsSync(serverPath)) {
+    const server = JSON.parse(readFileSync(serverPath, 'utf8')) as { version: string; packages: Array<{ version: string }> };
+    server.version = target;
+    server.packages[0]!.version = target;
+    writeFileSync(serverPath, `${JSON.stringify(server, null, 2)}\n`);
+    files.push('server.json');
+  }
+  const agentPath = join(worktree, 'integrations', 'acp-registry', 'elanous', 'agent.json');
+  if (existsSync(agentPath)) {
+    const agent = JSON.parse(readFileSync(agentPath, 'utf8')) as { version: string; distribution: { npx: { package: string } } };
+    agent.version = target;
+    agent.distribution.npx.package = `elanous@${target}`;
+    writeFileSync(agentPath, `${JSON.stringify(agent, null, 2)}\n`);
+    files.push('agent.json');
+  }
+  const lockPath = join(worktree, 'bun.lock');
+  const lock = readFileSync(lockPath, 'utf8');
+  const root = /"workspaces"\s*:\s*\{\s*""\s*:\s*\{([\s\S]*?)(?=\s*"(?:dependencies|devDependencies|optionalDependencies)"\s*:)/.exec(lock);
+  if (!root) throw new Error('bun.lock root workspace not found');
+  const lockedVersion = /"version"\s*:\s*"([^"]+)"/.exec(root[1]!);
+  if (lockedVersion) {
+    if (lockedVersion[1] !== current) throw new Error(`bun.lock root version ${lockedVersion[1]} is not ${current}`);
+    writeFileSync(lockPath, lock.replace(root[0], root[0].replace(lockedVersion[0], `"version": "${target}"`)));
+  }
+  return files;
+}
+
+export interface BranchCutDeps {
+  /** Runs `bun install --frozen-lockfile` in the bump worktree (the lock must accept the new version). */
+  install?: (worktree: string) => void;
+  /** The landing freeze in force (production root first, like a merge). */
+  freeze?: () => LandingFreeze | null;
+  /** `--force-freeze`: cut while a freeze is on (recorded). */
+  forceFreeze?: boolean;
+}
+
+function currentFreeze(): LandingFreeze | null {
+  const prod = prodInstanceRoot();
+  const root = effectiveInstanceRoot();
+  return readLandingFreeze(prod) ?? (root === prod ? null : readLandingFreeze(root));
+}
+
+/**
+ * RELEASE-BRANCH (대표 10-06 20:0x «0.2.18부터 브랜치 방식»): the release commit lives on `release/<v>`, never on main.
+ * An existing branch is reused as is (a resumed run, or a branch a repair appended to) — its tip is the release commit.
+ * Otherwise the branch is cut from origin/main and the version bump is committed on it; main keeps its -dev.N version
+ * until the post-publish dev bump.
+ */
+export function cutReleaseBranchForRun(repo: string, version: string, deps: BranchCutDeps = {}): Output {
+  if (!isReleaseVersion(version)) throw new Error(`invalid release version: ${version}`);
+  // The run does not need a freeze, but one that is on is the emergency stop: neither a new nor a reused cut passes it.
+  const frozen = (deps.freeze ?? currentFreeze)();
+  if (frozen) {
+    debug.log('release.run', deps.forceFreeze ? 'freeze-forced' : 'frozen', { version, reason: frozen.reason, until: frozen.until, node: 'version-release' });
+    if (!deps.forceFreeze) throw new Error(landingFreezeMessage(frozen));
+  }
+  fetchMain(repo);
+  const branch = `release/${version}`;
+  const advertised = git(repo, 'ls-remote', '--heads', 'origin', `refs/heads/${branch}`).split(/\s+/)[0] ?? '';
+  if (advertised) {
+    // A prerelease number is used once: an existing rc branch is another run's cut, never this run's.
+    if (prereleaseKind(version) !== null) throw new Error(`${branch} already exists — ${version} was cut by another run; run again for the next free number`);
+    if (!/^[0-9a-f]{40}$/i.test(advertised)) throw new Error(`${branch} remote tip is not a commit SHA`);
+    git(repo, 'fetch', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`);
+    const tip = git(repo, 'rev-parse', '--verify', `refs/remotes/origin/${branch}^{commit}`);
+    if (tip !== advertised) throw new Error(`${branch} moved while it was read (${advertised} → ${tip})`);
+    const current = versionAt(repo, tip);
+    if (current !== version) throw new Error(`${branch} tip ${tip} package.json version ${current} is not ${version}`);
+    // The branch must be a cut of this release line: its fork point on main still carries <base>-dev.N (or <v>).
+    const fork = git(repo, 'merge-base', 'origin/main', tip);
+    const forkVersion = versionAt(repo, fork);
+    const stableLine = baseVersion(version);
+    if (forkVersion !== version && !new RegExp(`^${stableLine.replaceAll('.', '\\.')}-dev\\.(0|[1-9][0-9]*)$`).test(forkVersion)) {
+      throw new Error(`${branch} forks from main at ${fork} (version ${forkVersion}) — not a cut of ${stableLine}-dev.N`);
+    }
+    debug.log('release-loop.cut', 'chosen', { version, source: 'release-branch', commit: tip, branch, existing: true });
+    return { outcome: 'ok', kind: 'release', version, commit: tip, pr: null, branch, existing: true };
+  }
+  const base = git(repo, 'rev-parse', 'origin/main');
+  const current = versionAt(repo, base);
+  const stable = baseVersion(version);
+  const devOfStable = new RegExp(`^${stable.replaceAll('.', '\\.')}-dev\\.(0|[1-9][0-9]*)$`);
+  if (current !== version && !devOfStable.test(current)) throw new Error(`origin/main version ${current} is not ${stable}-dev.N (release ${version})`);
+  const temp = mkdtempSync(join(tmpdir(), 'release-branch-cut-'));
+  const worktree = join(temp, 'tree');
+  let added = false;
+  try {
+    git(repo, 'worktree', 'add', '--detach', worktree, base);
+    added = true;
+    const files = current === version ? [] : writeVersionBump(worktree, current, version);
+    if (files.length) {
+      (deps.install ?? ((tree: string) => { run('bun', ['install', '--frozen-lockfile'], tree); }))(worktree);
+      git(worktree, 'add', '-A');
+      git(worktree, 'commit', '-m', `release: ${version}`, '-m', `Cut from main ${base}.`);
+    }
+    const commit = git(worktree, 'rev-parse', 'HEAD');
+    // Create-only: an empty lease refuses to overwrite a branch someone else made meanwhile.
+    const push = git(repo, 'push', '--porcelain', `--force-with-lease=refs/heads/${branch}:`, 'origin', `${commit}:refs/heads/${branch}`);
+    const created = push.split('\n').some((line) => {
+      const [flag, ref, summary] = line.split('\t');
+      return flag === '*' && !!ref?.endsWith(`:refs/heads/${branch}`) && summary === '[new branch]';
+    });
+    if (!created) throw new Error(`${branch} was not created (push: ${push.replace(/\s+/g, ' ').trim() || 'no output'})`);
+    debug.log('release-loop.cut', 'chosen', { version, source: 'release-branch', commit, branch, base, existing: false });
+    return { outcome: 'ok', kind: 'release', version, commit, pr: null, branch, base, files };
+  } finally {
+    try { if (added) git(repo, 'worktree', 'remove', '--force', worktree); }
+    finally { rmSync(temp, { recursive: true, force: true }); }
+  }
+}
+
+function landing(repo: string, kind: Kind, releaseVersion: string, cut?: string, cutCommit?: string, forceFreeze = false, branchCut = false): Output {
+  if (kind === 'release' && branchCut && cutCommit === undefined) return cutReleaseBranchForRun(repo, releaseVersion, { forceFreeze });
+  if (kind === 'dev-bump' && prereleaseKind(releaseVersion) !== null) {
+    // A prerelease (rehearsal) never moves main: the next stable release still owns this -dev line.
+    debug.log('release-loop.version-dev-bump', 'skipped', { version: releaseVersion, reason: 'prerelease' });
+    return { outcome: 'ok', kind, version: releaseVersion, commit: null, pr: null, skipped: 'prerelease' };
+  }
   const target = kind === 'release' ? releaseVersion : nextDevVersion(releaseVersion);
-  const source = kind === 'release' ? `${releaseVersion}-dev.N` : releaseVersion;
+  // With the release on its branch, main still carries <v>-dev.N when the dev bump runs.
+  const source = kind === 'release' ? `${releaseVersion}-dev.N` : branchCut ? `${releaseVersion}-dev.N` : releaseVersion;
   fetchMain(repo);
   if (kind === 'release' && cutCommit !== undefined) {
     if (!/^[0-9a-f]{7,40}$/i.test(cutCommit)) throw new Error(`invalid cut commit SHA: ${cutCommit}`);
@@ -107,7 +239,8 @@ function landing(repo: string, kind: Kind, releaseVersion: string, cut?: string,
       return { outcome: 'ok', kind, version: current, commit: before, pr: null };
     }
   }
-  if (kind === 'release' ? !new RegExp(`^${releaseVersion.replaceAll('.', '\\.')}\\-dev\\.(0|[1-9][0-9]*)$`).test(current) : current !== source) {
+  const devOfRelease = new RegExp(`^${releaseVersion.replaceAll('.', '\\.')}\\-dev\\.(0|[1-9][0-9]*)$`);
+  if (kind === 'release' || branchCut ? !devOfRelease.test(current) && !(kind === 'dev-bump' && current === releaseVersion) : current !== source) {
     throw new Error(`origin/main version ${current} is not ${source} (target ${target})`);
   }
 
@@ -115,37 +248,7 @@ function landing(repo: string, kind: Kind, releaseVersion: string, cut?: string,
   const worktree = join(temp, 'tree');
   try {
     git(repo, 'worktree', 'add', '-b', `release-version-${kind}-${Date.now()}-${process.pid}`, worktree, 'origin/main');
-    const path = join(worktree, 'package.json');
-    const text = readFileSync(path, 'utf8');
-    const old = `"version": "${current}"`;
-    if (!text.includes(old)) throw new Error(`package.json version field not found: ${current}`);
-    writeFileSync(path, text.replace(old, `"version": "${target}"`));
-    const files = ['package.json'];
-    const serverPath = join(worktree, 'server.json');
-    if (existsSync(serverPath)) {
-      const server = JSON.parse(readFileSync(serverPath, 'utf8')) as { version: string; packages: Array<{ version: string }> };
-      server.version = target;
-      server.packages[0]!.version = target;
-      writeFileSync(serverPath, `${JSON.stringify(server, null, 2)}\n`);
-      files.push('server.json');
-    }
-    const agentPath = join(worktree, 'integrations', 'acp-registry', 'elanous', 'agent.json');
-    if (existsSync(agentPath)) {
-      const agent = JSON.parse(readFileSync(agentPath, 'utf8')) as { version: string; distribution: { npx: { package: string } } };
-      agent.version = target;
-      agent.distribution.npx.package = `elanous@${target}`;
-      writeFileSync(agentPath, `${JSON.stringify(agent, null, 2)}\n`);
-      files.push('agent.json');
-    }
-    const lockPath = join(worktree, 'bun.lock');
-    const lock = readFileSync(lockPath, 'utf8');
-    const root = /"workspaces"\s*:\s*\{\s*""\s*:\s*\{([\s\S]*?)(?=\s*"(?:dependencies|devDependencies|optionalDependencies)"\s*:)/.exec(lock);
-    if (!root) throw new Error('bun.lock root workspace not found');
-    const lockedVersion = /"version"\s*:\s*"([^"]+)"/.exec(root[1]!);
-    if (lockedVersion) {
-      if (lockedVersion[1] !== current) throw new Error(`bun.lock root version ${lockedVersion[1]} is not ${current}`);
-      writeFileSync(lockPath, lock.replace(root[0], root[0].replace(lockedVersion[0], `"version": "${target}"`)));
-    }
+    const files = writeVersionBump(worktree, current, target);
     run('bun', ['install', '--frozen-lockfile'], worktree);
     if (kind === 'dev-bump') {
       const nextPath = join(worktree, 'release', 'next.md');
@@ -183,7 +286,8 @@ function landing(repo: string, kind: Kind, releaseVersion: string, cut?: string,
       }
     }
     const title = kind === 'release' ? `release: ${target}` : `version: ${target}`;
-    const land = spawnSync('bun', ['bin/elanous.mjs', 'pr', 'land', '--commit-message', title, '--title', title, '--body', `Set package.json version to ${target}.`], {
+    const land = spawnSync('bun', ['bin/elanous.mjs', 'pr', 'land', '--commit-message', title, '--title', title, '--body', `Set package.json version to ${target}.`,
+      ...(forceFreeze ? ['--force-freeze', `release run version bump ${target}`] : [])], {
       cwd: worktree, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024,
     });
     const transcript = `${land.stdout ?? ''}\n${land.stderr ?? ''}`;
@@ -206,11 +310,13 @@ function landing(repo: string, kind: Kind, releaseVersion: string, cut?: string,
   }
 }
 
-function main(args: string[] = process.argv.slice(2), repo = process.cwd()): Output {
+export function main(args: string[] = process.argv.slice(2), repo = process.cwd()): Output {
   let kind: Kind | null = null;
   let version: string | null = null;
   let cut: string | undefined;
   let cutCommit: string | undefined;
+  let forceFreeze = false;
+  let branchCut = false;
   try {
     if (args[0] !== 'release' && args[0] !== 'dev-bump') throw new Error('usage: version-node.ts <release|dev-bump> [--version <v>] [--cut <sha>] [--cut-commit <sha>] --json');
     kind = args[0];
@@ -224,8 +330,10 @@ function main(args: string[] = process.argv.slice(2), repo = process.cwd()): Out
     if (process.env.ELANOUS_GRAPH_CONTEXT) {
       const location = process.env.ELANOUS_GRAPH_CONTEXT;
       const context = JSON.parse(location.trimStart().startsWith('{') ? location : readFileSync(location, 'utf8')) as {
-        input?: { version?: unknown; cutCommit?: unknown }; outputs?: Record<string, { commit?: unknown } | undefined> };
+        input?: { version?: unknown; cutCommit?: unknown; forceFreeze?: unknown; branchCut?: unknown }; outputs?: Record<string, { commit?: unknown } | undefined> };
       if (!version && typeof context.input?.version === 'string') version = context.input.version;
+      forceFreeze = context.input?.forceFreeze === true;
+      branchCut = context.input?.branchCut === true;
       if (kind === 'release' && cutCommit === undefined && context.input?.cutCommit !== undefined) {
         if (typeof context.input.cutCommit !== 'string') throw new Error('cutCommit must be a commit SHA');
         cutCommit = context.input.cutCommit;
@@ -237,11 +345,11 @@ function main(args: string[] = process.argv.slice(2), repo = process.cwd()): Out
     if (!version) throw new Error('version required (--version or ELANOUS_GRAPH_CONTEXT.input.version)');
     nextDevVersion(version);
     if (kind === 'dev-bump' && cutCommit !== undefined) throw new Error('--cut-commit is only valid for release');
-    return landing(resolve(repo), kind, version, cut, cutCommit);
+    return landing(resolve(repo), kind, version, cut, cutCommit, forceFreeze, branchCut);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const worktree = /\[worktree: ([^\]]+)\]$/.exec(message)?.[1];
-    const outputVersion = kind === 'dev-bump' && version && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version)
+    const outputVersion = kind === 'dev-bump' && version && isStableVersion(version)
       ? nextDevVersion(version) : version;
     return { outcome: 'error', kind, version: outputVersion,
       commit: null, pr: null, ...(worktree ? { worktree } : {}), error: message };

package/scripts/release-story/draft.ts

@@ -86,18 +86,25 @@ function manualTexts(dir: string): string[] {
   return texts;
 }
 
-function linkedClaims(stateDir: string, version: string, ids: Set<string>): { sentences: string[]; error?: string } {
+type StoryClaim = { id: string; sentence: string; command: string | null; firstPublicCandidate: boolean };
+
+function linkedClaims(stateDir: string, version: string, ids: Set<string>): { claims: StoryClaim[]; error?: string } {
   const ledger = new ClaimsLedger({ stateDir });
   try {
-    if (!existsSync(stateDir)) return { sentences: [], error: '상태 경로 없음' };
-    if (!statSync(stateDir).isDirectory()) return { sentences: [], error: '상태 경로가 폴더가 아님' };
-    if (!existsSync(ledger.path)) return { sentences: [], error: '원장 없음' };
-    const sentences = [...ledger.list({ status: 'verified' }), ...ledger.list({ status: 'public' })]
-      .filter((row) => ledger.get(row.id).links.some((link) => link.version === version && ids.has(link.cell)))
-      .map((row) => row.claim);
-    return { sentences };
+    if (!existsSync(stateDir)) return { claims: [], error: '상태 경로 없음' };
+    if (!statSync(stateDir).isDirectory()) return { claims: [], error: '상태 경로가 폴더가 아님' };
+    if (!existsSync(ledger.path)) return { claims: [], error: '원장 없음' };
+    const claims = [...ledger.list({ status: 'verified' }), ...ledger.list({ status: 'public' })]
+      .map((row): StoryClaim | null => {
+        const detail = ledger.get(row.id);
+        if (!detail.links.some((link) => link.version === version && ids.has(link.cell))) return null;
+        return { id: row.id, sentence: row.claim, command: detail.evidence.at(-1)?.command ?? null,
+          firstPublicCandidate: !detail.history.some((entry) => entry.event === 'publish')
+            && !detail.links.some((link) => link.version !== version && link.version !== null) };
+      }).filter((claim): claim is StoryClaim => claim !== null);
+    return { claims };
   } catch (error) {
-    return { sentences: [], error: error instanceof Error ? error.message : String(error) };
+    return { claims: [], error: error instanceof Error ? error.message : String(error) };
   }
 }
 
@@ -117,15 +124,34 @@ export function draftReleaseStory(options: DraftOptions): DraftResult {
   const candidates = green.filter((item) => !mentions.some((text) => text.includes(item.id)));
   const evidence = linkedClaims(options.stateDir ?? effectiveInstanceRoot(), version, new Set(publicCells.map((item) => item.id)));
   const changes = [...userLines, ...publicCells.map((item) => firstPhrase(item.title))];
+  const numeric = evidence.claims.find((claim) => claim.firstPublicCandidate && /\d/.test(claim.sentence) && claim.command);
+  const kindPattern = /\bnew\b|새로운|신규|새 종류/i;
+  const kindFromNext = userLines.find((line) => kindPattern.test(line));
+  const kindFromCell = publicCells.map((item) => firstPhrase(item.title)).find((line) => kindPattern.test(line));
+  const kindFromClaim = evidence.claims.find((claim) => kindPattern.test(claim.sentence));
+  const newKind = kindFromNext ? { text: kindFromNext, source: 'release/next.md', command: null }
+    : kindFromCell ? { text: kindFromCell, source: 'green 칸', command: null }
+    : kindFromClaim ? { text: kindFromClaim.sentence, source: `소구점 ${kindFromClaim.id}`, command: kindFromClaim.command } : null;
+  const card = numeric ? { kind: '첫 공개 숫자 후보', text: numeric.sentence, source: `소구점 ${numeric.id}`, command: numeric.command }
+    : newKind ? { kind: '새 종류 후보', ...newKind } : null;
   const announcement = [
-    `# ${version} 판 공지 초안`, '', '## 무엇이 달라졌나',
+    `# ${version} 판 공지 초안`, '', '## 대표 카드 · CMO 확인 전',
+    ...(card ? [`- ${card.kind}: ${card.text}`, `- 출처: ${card.source}`, `- 재측정: ${card.command ?? '확인 명령 없음 — 게시 전 확인'}`]
+      : ['- 후보 없음 — CMO가 이번 판의 대표 문장을 고른다']),
+    '- 첫 공개 여부·새 종류 여부는 앞 판의 공개 문장과 대조한 뒤 CMO가 확정한다.',
+    '', '## 무엇이 달라졌나',
     ...(changes.length ? changes.map((line) => `- ${line}`) : ['- 사용자 쪽 변경 없음']),
     '', '## 근거',
-    ...(evidence.error ? [`근거: 소구점 원장 못 읽음(${evidence.error})`] : evidence.sentences.length ? evidence.sentences.map((claim) => `- ${claim}`) : ['근거: 연결된 소구점 없음']),
+    ...(evidence.error ? [`근거: 소구점 원장 못 읽음(${evidence.error})`] : evidence.claims.length ? evidence.claims.map((claim) => `- ${claim.sentence}`) : ['근거: 연결된 소구점 없음']),
+    '', '## CMO 게시 판단 · 초안은 게시가 아니다',
+    '- 착지·출처: release/next.md와 green 칸의 공개 상태, 연결된 검증 소구점을 대조한다. 근거가 없거나 원장을 못 읽었으면 보류한다.',
+    '- 사실·톤: 숫자는 근거 명령으로 재측정하고 첫 공개·새 종류는 앞 판 공개 문장과 대조한다. 브랜드 규칙과 금지 표현을 확인한다.',
+    '- 채널·결정: 공지·사이트·매뉴얼 문장의 대상과 영어 원문을 대조하고 CMO가 게시/수정/보류와 이유를 기록한다. 실제 바깥 게시는 역할 파일의 사람 결정 관문을 따른다.',
     '',
   ].join('\n');
   const siteChanges = [...userLines, ...publicCells.map((item) => firstPhrase(item.title)).filter((title) => !/[가-힣]/.test(title))];
-  const siteNews = [`# What's new in ${version}`, '', ...siteChanges.slice(0, 3).map((line) => `- ${line}`), '', `Release: ${version}`, ''].join('\n');
+  const siteCard = card && !/[가-힣]/.test(card.text) ? [`## Lead card candidate (CMO review required)`, card.text, ''] : [];
+  const siteNews = [`# What's new in ${version}`, '', ...siteCard, ...siteChanges.slice(0, 3).map((line) => `- ${line}`), '', `Release: ${version}`, ''].join('\n');
   const manual = [`# ${version} 매뉴얼 갱신 후보`, '', ...candidates.map((item: ChecklistItem) => `- ${item.id} · ${firstPhrase(item.title)} · 매뉴얼 언급 없음`), ''].join('\n');
   const outDir = options.outDir ?? join(effectiveInstanceRoot(), 'release', version, 'story');
   mkdirSync(outDir, { recursive: true });
@@ -150,7 +176,7 @@ export function draftReleaseStory(options: DraftOptions): DraftResult {
     files.push(file);
   }
   const result: DraftResult = { version, status: 'drafted', userLines: userLines.length, internalDropped, greenCells: green.length,
-    claims: evidence.sentences.length, manualCandidates: candidates.length, brandFindings, ...(brandUnmeasured ? { brandUnmeasured } : {}), files };
+    claims: evidence.claims.length, manualCandidates: candidates.length, brandFindings, ...(brandUnmeasured ? { brandUnmeasured } : {}), files };
   debug.log('release.story', 'drafted', { version, userLines: result.userLines, internalDropped, greenCells: result.greenCells,
     claims: result.claims, manualCandidates: result.manualCandidates, brandFindings, ...(brandUnmeasured ? { brandUnmeasured } : {}) });
   return result;
@@ -161,7 +187,9 @@ export function runReleaseStory(context: GraphContext = readGraphContext(), draf
   try {
     if (context.outputs.publish?.outcome !== 'ok' || context.outputs.verify?.outcome !== 'ok')
       throw new Error('published release and verification required');
-    const result = draft({ version });
+    // 판 노트 원천은 기본이 저장소의 release/next.md — 시험·재현은 env 로 다른 파일을 준다(실제 next.md 는 판마다 비워진다).
+    const nextPath = process.env.ELANOUS_RELEASE_NEXT_PATH?.trim();
+    const result = draft({ version, ...(nextPath ? { nextPath } : {}) });
     if (result.status === 'drafted') {
       const root = effectiveInstanceRoot();
       const requestsPath = join(root, 'seat-requests', 'requests.jsonl');