elanous 0.2.15 → 0.2.17

package/scripts/release-loop/cut-branch.ts

@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { debug } from '../../src/debug/log.js';
 
-export interface CutBranchOptions { version: string; base: string; pick: string[]; dryRun?: boolean; repoRoot?: string; log?: (line: string) => void }
+export interface CutBranchOptions { version: string; base: string; pick: string[]; append?: boolean; dryRun?: boolean; repoRoot?: string; log?: (line: string) => void }
 
 // git-spawn-allow: release branch operations happen only in an isolated temporary worktree; main is never checked out or changed.
 function git(repo: string, args: string[]): string {
@@ -23,8 +23,8 @@ export function cutReleaseBranch(opts: CutBranchOptions): { branch: string; comm
   const repo = resolve(opts.repoRoot ?? process.cwd());
   const branch = `release/${opts.version}`;
   const log = opts.log ?? console.log;
-  const report = (event: 'created' | 'refused' | 'conflict', reason?: string, commit?: string) =>
-    debug.log('release-loop.cut-branch', event, { version: opts.version, branch, ...(commit ? { commit } : {}), ...(reason ? { reason } : {}) });
+  const report = (event: 'created' | 'refused' | 'conflict' | 'appended', reason?: string, commit?: string, extra?: Record<string, string | string[]>) =>
+    debug.log('release-loop.cut-branch', event, { version: opts.version, branch, ...(commit ? { commit } : {}), ...(reason ? { reason } : {}), ...extra });
   try {
     if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(opts.version)) throw new Error(`invalid release version: ${opts.version}`);
     if (!opts.pick.length) throw new Error('at least one --pick commit is required');
@@ -37,18 +37,31 @@ export function cutReleaseBranch(opts: CutBranchOptions): { branch: string; comm
     for (const sha of picks) if (ancestor(repo, sha, base)) throw new Error(`pick ${sha} is already in base ${base}`);
     if (new Set(picks).size !== picks.length) throw new Error('duplicate --pick commit');
     for (const sha of picks) if (git(repo, ['rev-list', '--parents', '-n', '1', sha]).split(' ').length !== 2) throw new Error(`pick ${sha} must have exactly one parent`);
-    if (git(repo, ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`])) throw new Error(`${branch} already exists on origin`);
+    const remoteLine = git(repo, ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`]);
+    if (remoteLine && !opts.append) throw new Error(`${branch} already exists on origin — use --append to fast-forward more picks onto it`);
+    if (!remoteLine && opts.append) throw new Error(`${branch} does not exist on origin — omit --append to create it`);
     if (spawnSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: repo }).status === 0) throw new Error(`${branch} already exists locally`);
-    const pkg = JSON.parse(git(repo, ['show', `${base}:package.json`])) as { version?: unknown };
-    if (pkg.version !== opts.version) throw new Error(`base package.json version ${pkg.version} is not ${opts.version}`);
-    log(`${branch}: ${base} + ${picks.join(' + ')}${opts.dryRun ? ' (dry-run)' : ''}`);
+    let remoteTip: string | undefined;
+    if (opts.append) {
+      const advertised = remoteLine.split(/\s+/)[0] ?? '';
+      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}`]);
+      remoteTip = git(repo, ['rev-parse', '--verify', `refs/remotes/origin/${branch}^{commit}`]);
+      if (advertised !== remoteTip) throw new Error(`${branch} remote tip moved — fast-forward refused (no force push)`);
+      for (const sha of picks) if (ancestor(repo, sha, remoteTip)) throw new Error(`pick ${sha} is already in ${branch}`);
+    }
+    const versionAt = remoteTip ?? base;
+    const pkg = JSON.parse(git(repo, ['show', `${versionAt}:package.json`])) as { version?: unknown };
+    if (pkg.version !== opts.version) throw new Error(`${opts.append ? 'release branch' : 'base'} package.json version ${pkg.version} is not ${opts.version}`);
+    const start = remoteTip ?? base;
+    log(`${branch}: ${start} + ${picks.join(' + ')}${opts.append ? ' (append)' : ''}${opts.dryRun ? ' (dry-run)' : ''}`);
     if (opts.dryRun) return { branch, commit: null, dryRun: true };
     const temp = mkdtempSync(join(tmpdir(), 'release-cut-branch-'));
     const tree = join(temp, 'tree');
     let added = false;
     let commit: string | undefined;
     try {
-      git(repo, ['worktree', 'add', '--detach', tree, base]);
+      git(repo, ['worktree', 'add', '--detach', tree, start]);
       added = true;
       for (const sha of picks) {
         try { git(tree, ['cherry-pick', sha]); }
@@ -68,13 +81,30 @@ export function cutReleaseBranch(opts: CutBranchOptions): { branch: string; comm
       } finally { rmSync(temp, { recursive: true, force: true }); }
     }
     if (!commit) throw new Error('cherry-pick produced no commit');
-    const push = git(repo, ['push', '--porcelain', `--force-with-lease=refs/heads/${branch}:`, 'origin', `${commit}:refs/heads/${branch}`]);
-    const newBranch = push.split('\n').some((line) => {
+    const lease = opts.append ? remoteTip! : '';
+    let push: string;
+    try {
+      push = git(repo, ['push', '--porcelain', `--force-with-lease=refs/heads/${branch}:${lease}`, 'origin', `${commit}:refs/heads/${branch}`]);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (opts.append && /stale info|rejected|non-fast-forward|failed to push/i.test(message)) {
+        throw new Error(`${branch} remote tip moved — fast-forward refused (no force push)`);
+      }
+      throw error;
+    }
+    const landed = push.split('\n').some((line) => {
       const [flag, ref, summary] = line.split('\t');
-      return flag === '*' && ref?.endsWith(`:refs/heads/${branch}`) && summary === '[new branch]';
+      if (flag !== ' ' && flag !== '*') return false;
+      if (!ref?.endsWith(`:refs/heads/${branch}`)) return false;
+      if (!opts.append) return flag === '*' && summary === '[new branch]';
+      const range = summary?.match(/^([0-9a-f]+)\.\.([0-9a-f]+)$/i);
+      return flag === ' ' && !!range && remoteTip!.startsWith(range[1]!) && commit.startsWith(range[2]!);
     });
-    if (!newBranch) throw new Error(`${branch} already exists on origin (push did not create a new branch)`);
-    report('created', undefined, commit);
+    if (!landed) throw new Error(opts.append
+      ? `${branch} remote tip moved — fast-forward refused (no force push)`
+      : `${branch} already exists on origin (push did not create a new branch)`);
+    if (opts.append) report('appended', undefined, commit, { from: remoteTip!, to: commit, picks });
+    else report('created', undefined, commit);
     log(`${branch} → ${commit}`);
     return { branch, commit, dryRun: false };
   } catch (error) {

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

@@ -1,10 +1,14 @@
 #!/usr/bin/env bun
-import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
+import { listChecklist } from '../../src/release-loop/checklist.js';
+import type { ReleaseManifest } from '../../src/release-loop/manifest.js';
+import { recordDocsFollow, type DocsFollowItem } from './release-docs.js';
 import { dirname, join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { errorResult, finishNode, nodeOutput, readGraphContext, runCommand, type CommandRunner } from './node-verdict.js';
 
-export function runDocsLand(run: CommandRunner = runCommand) {
+export function runDocsLand(run: CommandRunner = runCommand, stateRoot = effectiveInstanceRoot(), ledgerRoot = releaseLedgerRoot()) {
   const context = readGraphContext();
   const version = context.input.version;
   if (context.outputs.publish?.outcome !== 'ok') throw new Error('publish must succeed before docs land');
@@ -14,6 +18,37 @@ export function runDocsLand(run: CommandRunner = runCommand) {
   const worktree = nodeOutput(context, 'docs', 'worktree');
   const scratch = dirname(worktree);
   if (dirname(scratch) !== tmpdir() || !/^release-docs-[A-Za-z0-9]+$/.test(scratch.split('/').at(-1) ?? '') || worktree !== join(scratch, 'tree')) throw new Error('invalid docs worktree');
+  const recordFollow = (deployed: boolean) => {
+    const releaseDir = join(stateRoot, 'release', version);
+    const manifest: ReleaseManifest = JSON.parse(readFileSync(join(releaseDir, 'manifest.json'), 'utf8'));
+    if (manifest.version !== version || !Array.isArray(manifest.in)) throw new Error('docs-follow manifest/version mismatch');
+    // MK attestations are independent of generated notes; missing proof is unmeasured.
+    const evidencePath = join(releaseDir, 'docs-follow-evidence.json');
+    // 증거 파일이 깨졌으면 «증거 없음»으로 센다 — 보고서·MK 대기열은 그래도 남긴다(미측정으로).
+    let raw: unknown = { items: [] };
+    try { if (existsSync(evidencePath)) raw = JSON.parse(readFileSync(evidencePath, 'utf8')); }
+    catch (error) { process.stderr.write(`docs-follow evidence unreadable — counted as no evidence: ${String(error)}\n`); }
+    const valid = !!raw && typeof raw === 'object' && 'items' in raw && Array.isArray((raw as { items: unknown }).items);
+    if (!valid) process.stderr.write('docs-follow evidence malformed — counted as no evidence\n');
+    // 항목도 하나씩 본다 — 객체이고 문자열 id 가 있는 것만 증거로 센다(나머지는 «증거 없음»).
+    const evidence: { items: unknown[] } = { items: valid ? (raw as { items: unknown[] }).items
+      .filter((item) => !!item && typeof item === 'object' && typeof (item as { id?: unknown }).id === 'string') : [] };
+    const checklist = listChecklist(version, ledgerRoot);
+    const attestations = new Map((evidence.items as DocsFollowItem[]).map((item) => [item.id, item]));
+    const items = checklist.items.map((item) => ({ ...attestations.get(item.id), id: item.id, status: item.status,
+      ...(deployed ? {} : { docs: undefined }) }));
+    const publicationFile = join(ledgerRoot, 'release', version, 'release.json');
+    const publication: unknown = existsSync(publicationFile) ? JSON.parse(readFileSync(publicationFile, 'utf8')) : null;
+    const publishedAt = publication && typeof publication === 'object' && 'publishedAt' in publication
+      && typeof publication.publishedAt === 'string' ? publication.publishedAt : undefined;
+    const follow = recordDocsFollow(stateRoot, manifest, items, new Date(), publishedAt);
+    return { pending: follow.pending.length, unassessed: follow.unassessed.length, ratio: follow.ratio, verdict: follow.verdict };
+  };
+  // The deployment error is authoritative even if the follow-up ledger cannot be written.
+  const recordFailure = () => {
+    try { return recordFollow(false); }
+    catch (error) { process.stderr.write(`docs-follow recording failed: ${String(error)}\n`); return undefined; }
+  };
   // 재시도 멱등: 노트가 이미 main 에 있으면(앞 판에서 머지됐고 배포만 실패) 착지를 건너뛰고 배포부터.
   const before = run('git', ['fetch', 'origin', 'main']);
   if (before.status !== 0) throw new Error(`docs landing fetch failed: ${before.stderr}`);
@@ -22,16 +57,20 @@ export function runDocsLand(run: CommandRunner = runCommand) {
     if (!existsSync(worktree)) throw new Error(`docs worktree missing and notes not on main: ${worktree}`);
     const land = run('bun', ['bin/elanous.mjs', 'pr', 'land', '--cwd', worktree]);
     if (land.stderr) process.stderr.write(land.stderr);
-    if (land.status === 1) return { outcome: 'fail' as const, verdict: 'fail' as const, summary: `docs land failed: ${land.stderr || land.stdout}` };
+    if (land.status === 1) return { outcome: 'fail' as const, verdict: 'fail' as const, summary: `docs land failed: ${land.stderr || land.stdout}`, docsFollow: recordFailure() };
     if (land.status !== 0 || !land.stdout.includes('✓ merge:')) throw new Error(`docs land incomplete (rc=${land.status}): ${land.stderr || land.stdout}`);
   }
+  // 착지(병합)는 이미 끝났다 — 이 뒤의 모든 실패는 후속 기록을 시도하고 원래 오류를 그대로 던진다.
   const fetch = run('git', ['fetch', 'origin', 'main']);
-  if (fetch.status !== 0) throw new Error(`docs landing fetch failed: ${fetch.stderr}`);
+  if (fetch.status !== 0) { recordFailure(); throw new Error(`docs landing fetch failed: ${fetch.stderr}`); }
   const merged = run('git', ['rev-parse', 'origin/main']);
-  if (merged.status !== 0 || !/^[0-9a-f]{40}\s*$/i.test(merged.stdout)) throw new Error(`merged main commit unavailable: ${merged.stderr}`);
-  const deployDir = mkdtempSync(join(tmpdir(), 'release-docs-deploy-'));
+  if (merged.status !== 0 || !/^[0-9a-f]{40}\s*$/i.test(merged.stdout)) { recordFailure(); throw new Error(`merged main commit unavailable: ${merged.stderr}`); }
+  let deployDir: string;
+  try { deployDir = mkdtempSync(join(tmpdir(), 'release-docs-deploy-')); }
+  catch (error) { recordFailure(); throw error; }
   const deployTree = join(deployDir, 'tree');
   let added = false;
+  let deployed = false;
   try {
     const add = run('git', ['worktree', 'add', '--detach', deployTree, merged.stdout.trim()]);
     if (add.status !== 0) throw new Error(`docs deploy worktree failed: ${add.stderr}`);
@@ -40,21 +79,41 @@ export function runDocsLand(run: CommandRunner = runCommand) {
     if (install.status !== 0) throw new Error(`docs deploy install failed: ${install.stderr}`);
     const deploy = run('bun', ['website/scripts/deploy-pages.ts', '--remote', 'node-b', '--yes'], deployTree);
     if (deploy.stderr) process.stderr.write(deploy.stderr);
-    if (deploy.status === 1) return { outcome: 'fail' as const, verdict: 'fail' as const, summary: `docs deploy failed: ${deploy.stderr || deploy.stdout}` };
+    if (deploy.status === 1) return { outcome: 'fail' as const, verdict: 'fail' as const,
+      summary: `docs deploy failed: ${deploy.stderr || deploy.stdout}`, docsFollow: recordFailure() };
     if (deploy.status !== 0) throw new Error(`docs deploy incomplete (rc=${deploy.status}): ${deploy.stderr || deploy.stdout}`);
+    deployed = true;
     if (existsSync(worktree)) {
       const remove = run('git', ['worktree', 'remove', '--force', worktree]);
       if (remove.status !== 0) throw new Error(`docs worktree cleanup failed: ${remove.stderr}`);
     }
     rmSync(scratch, { recursive: true, force: true });
-    return { outcome: 'ok' as const, verdict: 'pass' as const, summary: `docs landed and deployed v${version}` };
+    // 배포 성공 — 후속 기록 실패(manifest 없음 등)는 결과를 «실패»로 바꾸지 않는다. 알리고 넘어간다.
+    let follow: ReturnType<typeof recordFollow> | undefined;
+    try { follow = recordFollow(true); }
+    catch (error) { process.stderr.write(`docs-follow recording failed after deploy: ${String(error)}\n`); }
+    return { outcome: 'ok' as const, verdict: 'pass' as const,
+      summary: `docs landed and deployed v${version}${follow ? ` · docs-follow pending=${follow.pending} unassessed=${follow.unassessed}` : ' · docs-follow not recorded'}`,
+      docsFollow: follow };
+  } catch (error) {
+    if (!deployed) recordFailure();
+    else {
+      // 배포는 됐는데 정리에서 실패 — 보고서·MK 대기열은 «배포됨»으로 남기고 원래 오류를 보존한다.
+      try { recordFollow(true); }
+      catch (recordError) { process.stderr.write(`docs-follow recording failed: ${String(recordError)}\n`); }
+    }
+    throw error;
   } finally {
     try {
       if (added) {
         const remove = run('git', ['worktree', 'remove', '--force', deployTree]);
-        if (remove.status !== 0) throw new Error(`docs deploy cleanup failed: ${remove.stderr}`);
+        // 배포 임시 트리 정리 실패는 앞선 결과(반환·원래 오류)를 덮지 않는다 — 알리고 넘어간다.
+        if (remove.status !== 0) process.stderr.write(`docs deploy cleanup failed (kept the original result): ${remove.stderr}\n`);
       }
-    } finally { rmSync(deployDir, { recursive: true, force: true }); }
+    } finally {
+      try { rmSync(deployDir, { recursive: true, force: true }); }
+      catch (error) { process.stderr.write(`docs deploy temp cleanup failed (kept the original result): ${String(error)}\n`); }
+    }
   }
 }
 

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

@@ -242,8 +242,10 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
       // GNU timeout signals its own process group: -s KILL would kill timeout too (ssh 255), so TERM first then KILL after 10s (124 / 137).
       // No coreutils timeout on the remote → run unlimited there and rely on the local ssh deadline.
       const limitPrefix = limitMs ? `$(command -v timeout >/dev/null 2>&1 && echo 'timeout -k 10 ${Math.ceil(limitMs / 1000)}') ` : '';
+      // Start in /tmp, not the caller checkout. macOS resolves that symlink to /private/tmp before the child sees it;
+      // the remote command still `cd`s to the quoted path, so either spelling is the same directory.
       const run = spawnSync('ssh', [remote, `PATH=$HOME/.bun/bin:/opt/homebrew/bin:$PATH; export PATH; cd ${quote(cwd)} && ${limitPrefix}${[cmd, ...args].map(quote).join(' ')}`],
-        { encoding: 'utf8', maxBuffer: 128 * 1024 * 1024, ...(limitMs ? { timeout: limitMs + 60_000, killSignal: 'SIGKILL' as const } : {}) });
+        { cwd: '/tmp', encoding: 'utf8', maxBuffer: 128 * 1024 * 1024, ...(limitMs ? { timeout: limitMs + 60_000, killSignal: 'SIGKILL' as const } : {}) });
       const timedOut = !!limitMs && (run.status === 124 || run.status === 137 || (run.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT');
       return { rc: run.status ?? 2, output: `${run.stdout ?? ''}\n${run.stderr ?? ''}${run.error ? `\n${run.error}` : ''}`, ...(timedOut ? { timedOut } : {}) };
     }

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

@@ -36,7 +36,7 @@ export function waitForAssets(run: CommandRunner, repo: string, tag: string, nam
   }
 }
 
-export function runPublish(run: CommandRunner = runCommand) {
+export function runPublish(run: CommandRunner = runCommand, prodFreezeRoot?: string) {
   const context = readGraphContext();
   const version = context.input.version;
   // A measured automatic decision or the existing human approval must authorize publication.
@@ -68,7 +68,7 @@ export function runPublish(run: CommandRunner = runCommand) {
     writeFileSync(file, body);
     // Same in-flight marker as merges: `freeze on` waits for a publication that already passed this check.
     // Unlike a merge, a frozen publication is not queued: it fails, and the release run is run again after `freeze off`.
-    const landing = beginLandingMerge();
+    const landing = beginLandingMerge(undefined, undefined, prodFreezeRoot);
     const frozen = landing.frozen;
     if (frozen) {
       landing.end(); // already released by beginLandingMerge when frozen; kept explicit so no path leaves a marker

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

@@ -1,6 +1,140 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { appendSeatRequestRows, listSeatRequests, withSeatRequestLedgerLock } from '../../src/seat-dispatch/seat-request-ledger.js';
 import { debug } from '../../src/debug/log.js';
 import type { ReleaseManifest } from '../../src/release-loop/manifest.js';
 
+type DocsFollowEvidence = { location: string; verifiedAt: string; publishedAt: string };
+type DocsFollowExposure = {
+  verdict: 'public' | 'beta' | 'internal';
+  judge: 'MK';
+  rubric: string;
+  verifiedAt: string;
+};
+export type DocsFollowItem = {
+  id: string;
+  status: string;
+  sha?: string;
+  exposure?: DocsFollowExposure;
+  docs?: DocsFollowEvidence;
+  homepage?: { elanous: DocsFollowEvidence; elanvital: DocsFollowEvidence };
+  readme?: DocsFollowEvidence;
+};
+type DocsFollowCoverage = {
+  id: string;
+  sha: string | null;
+  docs: boolean;
+  homepage: boolean;
+  readme: boolean;
+  missing: Array<'docs' | 'homepage' | 'readme'>;
+};
+type DocsFollowReport = {
+  coverage: DocsFollowCoverage[];
+  pending: DocsFollowCoverage[];
+  unassessed: string[];
+  ratio: number | null;
+  verdict: 'pass' | 'fail' | 'unmeasured';
+};
+
+/** An attestation is not coverage unless it points to a measured, timestamped surface. */
+function evidenced(value: DocsFollowEvidence | undefined, measuredAt?: string): boolean {
+  const at = value?.verifiedAt ? Date.parse(value.verifiedAt) : NaN;
+  const published = value?.publishedAt ? Date.parse(value.publishedAt) : NaN;
+  return !!value?.location?.trim() && Number.isFinite(at) && Number.isFinite(published)
+    && /(?:Z|[+-]\d\d:\d\d)$/.test(value.verifiedAt)
+    && /(?:Z|[+-]\d\d:\d\d)$/.test(value.publishedAt)
+    && published <= at && (measuredAt === undefined || at <= Date.parse(measuredAt));
+}
+
+/** Unknown exposure/landing never becomes a published claim; it remains visible as an unassessed item. */
+export function calculateDocsFollow(manifest: ReleaseManifest, items: readonly DocsFollowItem[], publishedAt?: string, measuredAt?: string): DocsFollowReport {
+  const landed = new Set(manifest.in.map((entry) => entry.sha).filter(Boolean));
+  const green = items.filter((item) => item.status === 'green');
+  const ids = new Set<string>();
+  for (const item of items) {
+    if (!item.id?.trim() || ids.has(item.id)) throw new Error('invalid or duplicate docs-follow item');
+    ids.add(item.id);
+  }
+  const judged = (item: DocsFollowItem) => item.exposure?.judge === 'MK'
+    && !!item.exposure.rubric?.trim() && evidenced({ location: item.exposure.rubric, verifiedAt: item.exposure.verifiedAt,
+      publishedAt: item.exposure.verifiedAt }, measuredAt)
+    && ['public', 'beta', 'internal'].includes(item.exposure.verdict);
+  const unassessed = green.filter((item) => !judged(item) || !item.sha || !landed.has(item.sha))
+    .map((item) => item.id);
+  const supplied = new Set(items.map((item) => item.sha));
+  for (const entry of manifest.in) {
+    if (entry.sha && (entry.kind === 'feat' || entry.kind === 'fix' || entry.kind === 'security') && entry.line && !supplied.has(entry.sha)) {
+      unassessed.push(`landing:${entry.sha}`);
+    }
+  }
+  const visible = green.filter((item) => judged(item) && (item.exposure?.verdict === 'public' || item.exposure?.verdict === 'beta') && item.sha && landed.has(item.sha));
+  const coverage: DocsFollowCoverage[] = visible.map((item) => {
+    const docs = evidenced(item.docs, measuredAt);
+    const homepage = evidenced(item.homepage?.elanous, measuredAt) && evidenced(item.homepage?.elanvital, measuredAt);
+    const readme = evidenced(item.readme, measuredAt);
+    return { id: item.id, sha: item.sha!, docs, homepage, readme,
+      missing: ([['docs', docs], ['homepage', homepage], ['readme', readme]] as const)
+        .filter(([, present]) => !present).map(([surface]) => surface) };
+  });
+  const pending = coverage.filter((item) => !item.docs || !item.homepage);
+  const covered = coverage.filter((item) => item.docs && item.homepage && item.readme).length;
+  const start = publishedAt ? Date.parse(publishedAt) : NaN;
+  const end = measuredAt ? Date.parse(measuredAt) : NaN;
+  const deadline = start + 24 * 60 * 60 * 1000;
+  const validWindow = Number.isFinite(start) && Number.isFinite(end) && end >= start
+    && /(?:Z|[+-]\d\d:\d\d)$/.test(publishedAt ?? '')
+    && /(?:Z|[+-]\d\d:\d\d)$/.test(measuredAt ?? '');
+  const atDeadline = validWindow && end > deadline
+    ? calculateDocsFollow(manifest, items, publishedAt, new Date(deadline).toISOString()) : null;
+  const timely = atDeadline ?? { coverage, pending, unassessed,
+    ratio: coverage.length && !unassessed.length ? covered / coverage.length : null };
+  const pass = validWindow && timely.coverage.length > 0 && !timely.unassessed.length
+    && timely.ratio !== null && timely.ratio >= 0.8 && !timely.pending.length;
+  // Missing proof may still establish timely coverage; only a verified late publication rules it out.
+  const lateProof = (proof: DocsFollowEvidence | undefined) => evidenced(proof, measuredAt)
+    && Date.parse(proof!.publishedAt) > deadline;
+  const impossible = validWindow && end > deadline && !pass && !timely.unassessed.length
+    && visible.length > 0 && (
+      visible.some((item) => lateProof(item.docs) || lateProof(item.homepage?.elanous) || lateProof(item.homepage?.elanvital))
+      || visible.filter((item) => ![item.docs, item.homepage?.elanous, item.homepage?.elanvital, item.readme]
+        .some(lateProof)).length / visible.length < 0.8
+    );
+  return { coverage, pending, unassessed,
+    ratio: coverage.length && !unassessed.length ? covered / coverage.length : null,
+    verdict: pass ? 'pass' as const : impossible ? 'fail' as const : 'unmeasured' as const };
+}
+
+/** Persist a per-release report and queue each missing docs/home item once for MK. */
+export function recordDocsFollow(root: string, manifest: ReleaseManifest, items: readonly DocsFollowItem[], now: Date = new Date(), publishedAt?: string) {
+  if (!Number.isFinite(now.getTime())) throw new Error('invalid docs-follow time');
+  if (!/^\d+\.\d+\.\d+$/.test(manifest.version)) throw new Error('invalid docs-follow version');
+  const report = calculateDocsFollow(manifest, items, publishedAt, now.toISOString());
+  const path = join(root, 'release', manifest.version, 'docs-follow.json');
+  const journal = join(root, 'seat-requests', 'requests.jsonl');
+  withSeatRequestLedgerLock(journal, () => {
+    const known = new Set(listSeatRequests(root).map((row) => row.key));
+    const missing = [
+      ...report.pending.map((item) => ({ id: item.id, text: `문서 반영 대기 목록 v${manifest.version} · ${item.id}: ${item.missing.join(', ')} — 착지 ${item.sha}; docs·홈 실측 뒤 닫기` })),
+      ...report.unassessed.map((id) => ({ id, text: `문서 반영 대기 목록 v${manifest.version} · ${id}: 착지·green·EXPOSE-RUBRIC 근거 미판정 — 확인 전 공개 문면 금지` })),
+    ];
+    const rows = missing.filter((item) => !known.has(`docs-follow:${manifest.version}:${item.id}`)).map((item) => ({
+      key: `docs-follow:${manifest.version}:${item.id}`, seat: 'MK', status: 'queued' as const,
+      text: item.text, queuedAt: now.toISOString(), ref: `release:${manifest.version}:docs-follow`,
+    }));
+    mkdirSync(join(root, 'release', manifest.version), { recursive: true });
+    const temp = `${path}.${createHash('sha256').update(now.toISOString()).digest('hex').slice(0, 12)}.tmp`;
+    try {
+      writeFileSync(temp, JSON.stringify({ version: manifest.version, measuredAt: now.toISOString(), ...report }, null, 2) + '\n');
+      renameSync(temp, path);
+    } finally {
+      if (existsSync(temp)) unlinkSync(temp);
+    }
+    appendSeatRequestRows(journal, rows);
+  });
+  return report;
+}
+
 /** Render public IN lines only; keep private titles and PR numbers out of release notes. */
 export function renderReleaseNotes(manifest: ReleaseManifest, version: string): string {
   const sections = [

package/scripts/release-loop/vault-note-node.ts

@@ -215,11 +215,28 @@ function landingClause(text: string): string {
   // A candidate with broken punctuation is not repaired by deleting its unmatched character.
   if (!balanced(text)) return '';
   // release/next.md lines lead with their kind («feat — …»); the headline is the change, not the kind.
-  const body = text.replace(/^-\s+/, '').replace(/^(feat|fix|internal|docs|test|perf|refactor|chore|ops|security|breaking)\s+[—–-]\s+/i, '');
-  const clause = firstClause(body);
+  const trimmed = text.replace(/^-\s+/, '');
+  // Release bookkeeping (version bumps, «release 0.2.14» notes) is never this release's headline (0.2.15 real note).
+  if (/^(?:version|release)\s*:/i.test(trimmed) || /^(?:docs|chore)(?:\([^)]*\))?\s*:\s*release\s+v?\d/i.test(trimmed)) return '';
+  // Commit subjects lead with a conventional prefix («docs(marketing): …»); the headline is the change itself.
+  const body = trimmed.replace(/^(feat|fix|internal|docs|test|perf|refactor|chore|ops|security|breaking)\s+[—–-]\s+/i, '')
+    .replace(/^[a-z]+(?:\([^)]*\))?!?:\s+/i, '');
+  const clause = shortClause(firstClause(body));
   return balanced(clause) ? clause : '';
 }
 
+/** A headline clause longer than 60 characters is cut at its first comma/semicolon, else at a word boundary with «…». */
+function shortClause(clause: string): string {
+  const chars = [...clause];
+  if (chars.length <= 60) return clause;
+  const head = chars.slice(0, 60).join('');
+  // The first comma/semicolon after a minimal 10-character lead ends the clause.
+  const stop = head.slice(10).search(/[,;，；]/);
+  if (stop >= 0) return head.slice(0, 10 + stop);
+  const space = head.lastIndexOf(' ');
+  return `${(space >= 20 ? head.slice(0, space) : head).trimEnd()}…`;
+}
+
 function versionKey(value: string): number[] | null {
   const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
   return match ? match.slice(1).map(Number) : null;

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

@@ -64,7 +64,7 @@ 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 {
+function landing(repo: string, kind: Kind, releaseVersion: string, cut?: string, cutCommit?: string, forceFreeze = false): Output {
   const target = kind === 'release' ? releaseVersion : nextDevVersion(releaseVersion);
   const source = kind === 'release' ? `${releaseVersion}-dev.N` : releaseVersion;
   fetchMain(repo);
@@ -183,7 +183,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 ?? ''}`;
@@ -211,6 +212,7 @@ function main(args: string[] = process.argv.slice(2), repo = process.cwd()): Out
   let version: string | null = null;
   let cut: string | undefined;
   let cutCommit: string | undefined;
+  let forceFreeze = 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 +226,9 @@ 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 }; outputs?: Record<string, { commit?: unknown } | undefined> };
       if (!version && typeof context.input?.version === 'string') version = context.input.version;
+      forceFreeze = context.input?.forceFreeze === 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,7 +240,7 @@ 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);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const worktree = /\[worktree: ([^\]]+)\]$/.exec(message)?.[1];

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');