elanous 0.2.15 → 0.2.16

package/scripts/docs-cli-check.ts

@@ -2,7 +2,7 @@
 // 공개 문서에 적힌 `elanous …` 명령·하위 명령·플래그가 «실제 CLI» 에 있나 — 문서가 실제와 어긋나는 1순위 원인을 잡는다.
 //   bun scripts/docs-cli-check.ts [--json] [files…]      (기본 = release/public/내부 문서 `*` ⊕ README.md)
 // 🩸 계기(2026-09-25 🅢 RFC 피드백 ③): README·install.md 가 거짓이 된 원인이 전부 «설치기·doctor 가 바뀌었는데 문서가 모름»이었다.
-// 자 = `bun bin/elanous.mjs <cmd> [<sub>] [<subsub>] --help` 산출(원천) — 문서의 코드 블록과 인라인 코드에서 `elanous ` 로 시작하는 것만 본다.
+// 자 = `bun bin/elanous.mjs <cmd> [<sub>] [<subsub>] --help` 산출(원천) — 문서의 코드 블록과 인라인 코드에서 `elanous ` 또는 `bun bin/elanous.mjs ` 로 시작하는 것만 본다.
 // ⛔ 못 본 것은 «없다»로 적지 않는다: `--help` 가 실패하면 그 명령은 `unmeasured` 로 따로 센다.
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
@@ -21,10 +21,10 @@ export function extractElanousCommands(file: string, text: string): DocCommand[]
     if (/^\s*(```|~~~)/.test(raw)) { inFence = !inFence; return; }
     const candidates: string[] = [];
     if (inFence) candidates.push(raw.replace(/#.*$/, ''));
-    for (const m of raw.matchAll(/`(elanous [^`]+)`/g)) candidates.push(m[1]!);
+    for (const m of raw.matchAll(/`((?:bun bin\/elanous\.mjs |elanous )[^`]+)`/g)) candidates.push(m[1]!);
     for (const c of candidates) {
       for (const seg of c.split(/&&|\|\||;|\|/)) {
-        const m = /^(?:(?:\$\s+|>\s+|sudo\s+|[A-Za-z_][A-Za-z0-9_]*=\S+\s+))*elanous\s+(.+)$/.exec(seg.trim());
+        const m = /^(?:(?:\$\s+|>\s+|sudo\s+|[A-Za-z_][A-Za-z0-9_]*=\S+\s+))*(?:bun bin\/elanous\.mjs |elanous\s+)(.+)$/.exec(seg.trim());
         if (!m) continue;
         const tokens = m[1]!.trim().split(/\s+/).filter(Boolean);
         const cmd = tokens[0];
@@ -86,7 +86,7 @@ export function checkCommands(refs: readonly DocCommand[], help: HelpRunner = de
       }
     }
     for (const f of ref.flags) {
-      if (!new RegExp(`(^|[\\s,])${f}(\\b|[\\s,=<\\[])`, 'm').test(flagsHelp)) findings.push({ kind: 'unknown-flag', ref, detail: `${f} (${flagsPath})` });
+      if (!new RegExp(`(^|[\\s,])${f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\b|[\\s,=<\\[])`, 'm').test(flagsHelp)) findings.push({ kind: 'unknown-flag', ref, detail: `${f} (${flagsPath})` });
     }
   }
   return findings;

package/scripts/goals/goal-census.ts

@@ -0,0 +1,343 @@
+#!/usr/bin/env bun
+/**
+ * GOAL-LIFE① — docs/goals 전수 분류(이관 전 측정).
+ *
+ * GitHub API·gh 를 부르지 않는다. git 이력과 파일 시스템만 읽고,
+ * docs/goals 아래 어떤 파일도 쓰지 않는다.
+ *
+ *   bun scripts/goals/goal-census.ts [--json] [--out <path>]
+ */
+import { spawnSync } from 'node:child_process';
+import { readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+
+export type GoalKind = 'GOAL' | 'ASK' | 'other';
+export type GoalClass = 'landed' | 'untracked' | 'tracked-no-pr';
+
+export interface GoalCensusEntry {
+  readonly path: string;
+  readonly classification: GoalClass;
+  readonly kind: GoalKind;
+  readonly bytes: number;
+  /** 추가 날짜 YYYY-MM-DD (KST). 미추적이면 파일 mtime. */
+  readonly addedDateKst: string;
+  readonly prNumber?: number;
+  readonly addCommit?: string;
+}
+
+export interface GoalCensusSummary {
+  readonly total: number;
+  readonly byClass: Record<GoalClass, number>;
+  readonly byKind: Record<GoalKind, number>;
+  readonly matrix: Record<GoalClass, Record<GoalKind, number>>;
+  readonly bytes: number;
+  readonly bytesByClass: Record<GoalClass, number>;
+  /** 월별 추가 수 — YYYY-MM (KST). */
+  readonly addedByMonth: Record<string, number>;
+}
+
+export interface GoalCensus {
+  readonly entries: readonly GoalCensusEntry[];
+  readonly summary: GoalCensusSummary;
+}
+
+export interface AddedCommit {
+  readonly hash: string;
+  readonly subject: string;
+  /** git %aI — ISO 8601 with offset. */
+  readonly authoredAt: string;
+}
+
+export interface CensusGoalsInput {
+  readonly repoRoot: string;
+  /** 경로(repo 상대, posix) → 그 파일을 처음 추가한 커밋. 없으면 미추적. */
+  readonly gitLog: (repoRoot: string) => ReadonlyMap<string, AddedCommit>;
+  /** repo 상대 미추적 경로. */
+  readonly listUntracked: (repoRoot: string) => readonly string[];
+  /** 테스트·대체 루트. 기본 docs/goals. */
+  readonly goalsDir?: string;
+}
+
+const CLASSES: readonly GoalClass[] = ['landed', 'untracked', 'tracked-no-pr'];
+const KINDS: readonly GoalKind[] = ['GOAL', 'ASK', 'other'];
+
+const PR_AT_END = /\(#(\d+)\)\s*$/;
+
+export function classifyKind(relPath: string): GoalKind {
+  const base = relPath.split('/').pop() ?? relPath;
+  if (base.startsWith('GOAL')) return 'GOAL';
+  if (base.startsWith('ASK')) return 'ASK';
+  return 'other';
+}
+
+export function prNumberFromSubject(subject: string): number | undefined {
+  const m = subject.match(PR_AT_END);
+  return m ? Number(m[1]) : undefined;
+}
+
+/** UTC ISO(또는 offset 포함) → KST YYYY-MM-DD. */
+export function kstDate(iso: string): string {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return iso.slice(0, 10);
+  const kst = new Date(t + 9 * 60 * 60 * 1000);
+  const y = kst.getUTCFullYear();
+  const m = String(kst.getUTCMonth() + 1).padStart(2, '0');
+  const d = String(kst.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+function emptyMatrix(): Record<GoalClass, Record<GoalKind, number>> {
+  const matrix = {} as Record<GoalClass, Record<GoalKind, number>>;
+  for (const c of CLASSES) {
+    matrix[c] = { GOAL: 0, ASK: 0, other: 0 };
+  }
+  return matrix;
+}
+
+function measureEntry(repoRoot: string, rel: string): { bytes: number; mtimeIso: string; files: string[] } {
+  const abs = resolve(repoRoot, rel);
+  const root = resolve(repoRoot);
+  try {
+    const st = statSync(abs);
+    if (!st.isDirectory()) return { bytes: st.size, mtimeIso: st.mtime.toISOString(), files: [rel] };
+    const files: string[] = [];
+    walkFiles(abs, root, files);
+    let bytes = 0;
+    for (const f of files) {
+      try { bytes += statSync(resolve(repoRoot, f)).size; } catch { /* skip missing */ }
+    }
+    return { bytes, mtimeIso: st.mtime.toISOString(), files };
+  } catch {
+    return { bytes: 0, mtimeIso: new Date(0).toISOString(), files: [] };
+  }
+}
+
+function earliestAddition(added: ReadonlyMap<string, AddedCommit>, prefix: string): AddedCommit | undefined {
+  let best: AddedCommit | undefined;
+  for (const [p, c] of added) {
+    if (!p.startsWith(prefix)) continue;
+    if (!best || c.authoredAt < best.authoredAt) best = c;
+  }
+  return best;
+}
+
+function walkFiles(dir: string, root: string, out: string[]): void {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name === '.git') continue;
+    const abs = join(dir, name);
+    let st;
+    try {
+      st = statSync(abs);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) walkFiles(abs, root, out);
+    else if (st.isFile()) out.push(relative(root, abs).split('\\').join('/'));
+  }
+}
+
+/**
+ * `ls docs/goals` 와 같은 최상위 이름(파일·디렉터리 각 1).
+ * 디렉터리의 크기·착지 근거는 그 아래 파일을 모아 정한다.
+ */
+export function listGoalFiles(repoRoot: string, goalsDir = 'docs/goals'): string[] {
+  const abs = resolve(repoRoot, goalsDir);
+  let names: string[];
+  try {
+    names = readdirSync(abs);
+  } catch {
+    return [];
+  }
+  return names.filter((n) => n !== '.' && n !== '..').map((n) => `${goalsDir}/${n}`).sort();
+}
+
+export function summarize(entries: readonly GoalCensusEntry[]): GoalCensusSummary {
+  const byClass = { landed: 0, untracked: 0, 'tracked-no-pr': 0 } as Record<GoalClass, number>;
+  const byKind = { GOAL: 0, ASK: 0, other: 0 } as Record<GoalKind, number>;
+  const matrix = emptyMatrix();
+  const bytesByClass = { landed: 0, untracked: 0, 'tracked-no-pr': 0 } as Record<GoalClass, number>;
+  const addedByMonth: Record<string, number> = {};
+  let bytes = 0;
+  for (const e of entries) {
+    byClass[e.classification] += 1;
+    byKind[e.kind] += 1;
+    matrix[e.classification][e.kind] += 1;
+    bytesByClass[e.classification] += e.bytes;
+    bytes += e.bytes;
+    const month = e.addedDateKst.slice(0, 7);
+    addedByMonth[month] = (addedByMonth[month] ?? 0) + 1;
+  }
+  return { total: entries.length, byClass, byKind, matrix, bytes, bytesByClass, addedByMonth };
+}
+
+export function censusGoals(input: CensusGoalsInput): GoalCensus {
+  const goalsDir = input.goalsDir ?? 'docs/goals';
+  const prefix = goalsDir.endsWith('/') ? goalsDir : `${goalsDir}/`;
+  const files = listGoalFiles(input.repoRoot, goalsDir);
+  const added = input.gitLog(input.repoRoot);
+  const untracked = new Set(input.listUntracked(input.repoRoot).map((p) => p.split('\\').join('/')));
+
+  const entries: GoalCensusEntry[] = [];
+  for (const path of files) {
+    if (!path.startsWith(prefix)) continue;
+    const kind = classifyKind(path);
+    const measured = measureEntry(input.repoRoot, path);
+    const { bytes, mtimeIso } = measured;
+    const commit = added.get(path) ?? earliestAddition(added, `${path}/`);
+    const nestedUntracked = measured.files.length > 0
+      && measured.files.every((f) => untracked.has(f) || !added.has(f));
+    if (!commit || untracked.has(path) || nestedUntracked) {
+      entries.push({
+        path,
+        classification: 'untracked',
+        kind,
+        bytes,
+        addedDateKst: kstDate(mtimeIso),
+      });
+      continue;
+    }
+    const prNumber = prNumberFromSubject(commit.subject);
+    if (prNumber !== undefined) {
+      entries.push({
+        path,
+        classification: 'landed',
+        kind,
+        bytes,
+        addedDateKst: kstDate(commit.authoredAt),
+        prNumber,
+        addCommit: commit.hash,
+      });
+    } else {
+      entries.push({
+        path,
+        classification: 'tracked-no-pr',
+        kind,
+        bytes,
+        addedDateKst: kstDate(commit.authoredAt),
+        addCommit: commit.hash,
+      });
+    }
+  }
+  return { entries, summary: summarize(entries) };
+}
+
+/**
+ * 파일을 처음 추가한 커밋만. `git log --diff-filter=A` 한 번.
+ * 최신→과거 순이므로 같은 경로가 다시 나오면 나중 값(최초 추가)이 이긴다.
+ */
+export function gitLogAdditions(repoRoot: string, goalsDir = 'docs/goals'): Map<string, AddedCommit> {
+  const r = spawnSync(
+    'git',
+    [
+      '-C', repoRoot,
+      'log',
+      '--diff-filter=A',
+      '--name-only',
+      '--format=@@%H%x09%s%x09%aI',
+      '--',
+      goalsDir,
+    ],
+    { encoding: 'utf8', maxBuffer: 512 * 1024 * 1024 },
+  );
+  if (r.status !== 0) {
+    throw new Error(`git log failed: ${(r.stderr || '').trim()}`);
+  }
+  const out = new Map<string, AddedCommit>();
+  let current: AddedCommit | undefined;
+  for (const line of r.stdout.split('\n')) {
+    if (!line) continue;
+    if (line.startsWith('@@')) {
+      const body = line.slice(2);
+      const tab = body.indexOf('\t');
+      const tab2 = body.lastIndexOf('\t');
+      if (tab > 0 && tab2 > tab) {
+        current = {
+          hash: body.slice(0, tab),
+          subject: body.slice(tab + 1, tab2),
+          authoredAt: body.slice(tab2 + 1),
+        };
+      }
+      continue;
+    }
+    if (current) out.set(line, current);
+  }
+  return out;
+}
+
+/** 작업 트리의 미추적 파일. `git ls-files --others --exclude-standard`. */
+export function gitListUntracked(repoRoot: string, goalsDir = 'docs/goals'): string[] {
+  const r = spawnSync(
+    'git',
+    ['-C', repoRoot, 'ls-files', '--others', '--exclude-standard', '--', goalsDir],
+    { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
+  );
+  if (r.status !== 0) {
+    throw new Error(`git ls-files failed: ${(r.stderr || '').trim()}`);
+  }
+  return r.stdout.split('\n').filter((p) => p.length > 0);
+}
+
+export function formatSummary(census: GoalCensus): string {
+  const { summary } = census;
+  const lines: string[] = [];
+  lines.push(`total ${summary.total}  bytes ${summary.bytes}`);
+  lines.push('class × kind');
+  const header = ['class', ...KINDS, 'bytes'].join('\t');
+  lines.push(header);
+  for (const c of CLASSES) {
+    const row = [
+      c,
+      ...KINDS.map((k) => String(summary.matrix[c][k])),
+      String(summary.bytesByClass[c]),
+    ];
+    lines.push(row.join('\t'));
+  }
+  lines.push('added by month (KST)');
+  const months = Object.keys(summary.addedByMonth).sort();
+  for (const month of months) lines.push(`${month}\t${summary.addedByMonth[month]}`);
+  return lines.join('\n') + '\n';
+}
+
+function parseArgs(argv: readonly string[]): { json: boolean; out?: string } {
+  let json = false;
+  let out: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') json = true;
+    else if (a === '--out') {
+      out = argv[i + 1];
+      i += 1;
+    } else if (a.startsWith('--out=')) out = a.slice('--out='.length);
+  }
+  return { json, out };
+}
+
+function main(argv: readonly string[]): void {
+  const repoRoot = resolve(import.meta.dir, '../..');
+  const args = parseArgs(argv);
+  const census = censusGoals({
+    repoRoot,
+    gitLog: (root) => gitLogAdditions(root),
+    listUntracked: (root) => gitListUntracked(root),
+  });
+  const { summary } = census;
+  debug.log('goals.census', 'scanned', {
+    total: summary.total,
+    landed: summary.byClass.landed,
+    untracked: summary.byClass.untracked,
+    trackedNoPr: summary.byClass['tracked-no-pr'],
+    bytes: summary.bytes,
+  });
+  const body = args.json ? JSON.stringify(census, null, 2) + '\n' : formatSummary(census);
+  if (args.out) writeFileSync(args.out, body);
+  process.stdout.write(body);
+}
+
+if (import.meta.main) main(process.argv.slice(2));

package/scripts/measure/author-section-contribution.ts

@@ -0,0 +1,84 @@
+import { Database } from 'bun:sqlite';
+import { readFileSync } from 'node:fs';
+
+export interface AuthorSummary {
+  authorRunId: string;
+  sectionChars: Record<string, number>;
+}
+
+export interface AssignedGoalEvent {
+  category: string;
+  event: string;
+  ts: string;
+  data: { authorRunId?: string; goalId?: string };
+}
+
+export interface ExecutionRun {
+  runId: string;
+  goalId: string;
+  startedAt: string;
+  outcome: string;
+}
+
+export interface SectionContribution {
+  authorRunId: string;
+  goalId: string;
+  runId: string;
+  section: string;
+  chars: number;
+  outcome: string;
+}
+
+/** Join an authored summary to the first execution starting after that author's assignment. */
+export function measureAuthorSectionContribution(
+  summaries: readonly AuthorSummary[],
+  events: readonly AssignedGoalEvent[],
+  runs: readonly ExecutionRun[],
+): SectionContribution[] {
+  const rows: SectionContribution[] = [];
+  for (const summary of summaries) {
+    const assignment = events.filter((event) => event.category === 'goal-author'
+      && event.event === 'goal-id-assigned'
+      && event.data?.authorRunId === summary.authorRunId
+      && typeof event.data.goalId === 'string'
+      && Number.isFinite(Date.parse(event.ts)))
+      .sort((left, right) => Date.parse(left.ts) - Date.parse(right.ts)
+        || left.data.goalId!.localeCompare(right.data.goalId!))[0];
+    if (!assignment) continue;
+    const assignedAt = Date.parse(assignment.ts);
+    const run = runs.filter((candidate) => candidate.goalId === assignment.data.goalId
+      && Number.isFinite(Date.parse(candidate.startedAt))
+      && Date.parse(candidate.startedAt) >= assignedAt)
+      .sort((left, right) => Date.parse(left.startedAt) - Date.parse(right.startedAt)
+        || left.runId.localeCompare(right.runId))[0];
+    if (!run) continue;
+    for (const [section, chars] of Object.entries(summary.sectionChars)) {
+      rows.push({ authorRunId: summary.authorRunId, goalId: run.goalId, runId: run.runId, section, chars, outcome: run.outcome });
+    }
+  }
+  return rows;
+}
+
+function readRunLedger(path: string): ExecutionRun[] {
+  const db = new Database(path, { readonly: true });
+  try {
+    const records = db.query('SELECT run_id, goal_id, doc FROM goal_run').all() as Array<{ run_id: string; goal_id: string; doc: string }>;
+    return records.map(({ run_id, goal_id, doc }) => {
+      const record = JSON.parse(doc) as { startedAt: string; outcome: string };
+      return { runId: run_id, goalId: goal_id, startedAt: record.startedAt, outcome: record.outcome };
+    });
+  } finally {
+    db.close();
+  }
+}
+
+if (import.meta.main) {
+  const [summaryFile, eventsFile, ledgerFile] = process.argv.slice(2);
+  if (!summaryFile || !eventsFile || !ledgerFile) throw new Error('usage: bun scripts/measure/author-section-contribution.ts <summaries.json> <events.jsonl> <goal-runs.db>');
+  const summaries = JSON.parse(readFileSync(summaryFile, 'utf8')) as AuthorSummary[];
+  const events = readFileSync(eventsFile, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line) as AssignedGoalEvent);
+  const rows = measureAuthorSectionContribution(summaries, events, readRunLedger(ledgerFile));
+  console.log('| authorRunId | goalId | runId | section | chars | outcome |');
+  console.log('| --- | --- | --- | --- | ---: | --- |');
+  for (const row of rows) console.log(`| ${row.authorRunId} | ${row.goalId} | ${row.runId} | ${row.section} | ${row.chars} | ${row.outcome} |`);
+}

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/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/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;