elanous 0.2.20 → 0.2.22

package/src/cli/decisions-cli.ts

@@ -11,6 +11,7 @@ import { getUserConfig } from '../user-config.js';
 import { projectDecisionsToLinear } from '../decisions/decision-linear-projection.js';
 import { DecisionLedger, importDecisionMarkdown, type DecisionCategory, type DecisionLedgerOptions, type DecisionOption, type DecisionTrack, type DecisionEntry, type Seat, type SeatDecisionRecord } from '../decisions/decision-ledger.js';
 import { formatProactMeter, readProactMeter } from '../decisions/proact-meter.js';
+import { writeStdoutFully } from './stdout-flush.js';
 
 const repeat = (value: string, values: string[]) => [...values, value];
 function date(raw?: string): string | undefined {
@@ -75,14 +76,24 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
     return hqCliWriteAllowed(`decisions ${command}`, Boolean(override || root.opts().hqOverride),
       (getElanousConfigDirOverride() || config.stateDir) && !hqDeps.store && !getUserConfig().hq?.arbiter ? { ...hqDeps, store: fileLeaseStore(join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'lease.json')), seenPath: join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'seen-generation'), localPath: join(config.stateDir ?? effectiveInstanceRoot(), 'hq', 'local.json') } : hqDeps);
   };
-  const emit = (value: unknown, json?: boolean, text?: string) => out.log(json ? JSON.stringify(value) : text ?? JSON.stringify(value));
-  const fail = (action: () => void) => { try { action(); } catch (e) { throw new Error(`decisions: ${e instanceof Error ? e.message : String(e)}`); } };
+  const emit = (value: unknown, json?: boolean, text?: string): void | Promise<void> => {
+    const line = json ? JSON.stringify(value) : text ?? JSON.stringify(value);
+    if (json && out === console) return writeStdoutFully(line);
+    out.log(line);
+  };
+  const fail = (action: () => void | Promise<void>): void | Promise<void> => {
+    const wrap = (e: unknown) => new Error(`decisions: ${e instanceof Error ? e.message : String(e)}`);
+    try {
+      const result = action();
+      return result instanceof Promise ? result.catch(e => { throw wrap(e); }) : result;
+    } catch (e) { throw wrap(e); }
+  };
   root.command('linear-sync').description('열린 결정을 COO Linear 프로젝트에 투영하고 닫힌 결정을 동기화한다')
     .option('--dry-run').option('--json').option('--hq-override')
     .action(async (o: { dryRun?: boolean; json?: boolean; hqOverride?: boolean }) => {
       if (!o.dryRun && !mayWrite('linear-sync', o.hqOverride)) return;
       const result = await projectDecisionsToLinear({ stateDir: config.stateDir, dryRun: o.dryRun });
-      emit(result, o.json, result.reason ?? `생성 ${result.created} · 닫음 ${result.closed} · 건너뜀 ${result.skipped} · 실패 ${result.failed}${result.plan?.length ? `\n${result.plan.map(p => `${p.action} ${p.decisionId}${p.issue ? ` ${p.issue}` : ''}`).join('\n')}` : ''}`);
+      await emit(result, o.json, result.reason ?? `생성 ${result.created} · 닫음 ${result.closed} · 건너뜀 ${result.skipped} · 실패 ${result.failed}${result.plan?.length ? `\n${result.plan.map(p => `${p.action} ${p.decisionId}${p.issue ? ` ${p.issue}` : ''}`).join('\n')}` : ''}`);
     });
   root.command('raise').description('SCQA·선택지와 권고로 결정 항목을 올린다')
     .requiredOption('--title <text>').requiredOption('--category <category>')
@@ -121,7 +132,7 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
         ...(o.resumeQuestion !== undefined ? { resume: { questionId: o.resumeQuestion, ...(o.run !== undefined ? { runId: o.run } : {}) } } : {}),
         ...(o.due ? { dueAt: dueAt(o.due) } : {}) });
       if (entry.crossCheckSkipped === 'missing') console.error('교차 확인 없음 — --xcheck SEAT:메모 또는 --no-xcheck 이유');
-      emit(entry, o.json, `올림: ${formatDecisionRow(entry)}`);
+      return emit(entry, o.json, `올림: ${formatDecisionRow(entry)}`);
     }));
   root.command('record-seat').description('위임 범위에서 이미 내린 자리 결정을 사후 보고로 원장에 기록 (대표 카드 아님)')
     .requiredOption('--seat <OP|MK|TC|UX>').requiredOption('--title <text>')
@@ -133,13 +144,13 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
       if (!mayWrite('record-seat', o.hqOverride)) return;
       const entry = new DecisionLedger(config).recordSeatDecision({ seat: o.seat, title: o.title, decision: o.decision,
         delegation: o.delegation, ...(o.at ? { decidedAt: o.at } : {}), ...(o.ref.length ? { refs: o.ref } : {}) });
-      emit(entry, o.json, formatSeatDecisionRow(entry));
+      return emit(entry, o.json, formatSeatDecisionRow(entry));
     }));
   root.command('seat-report').description('밤사이 자리들의 사후 결정을 한 번에 조회 (기본 최근 24시간)')
     .option('--since <date>', '조회 시작 UTC ISO 또는 Nd', '1d').option('--seat <OP|MK|TC|UX>').option('--json')
     .action((o: { since: string; seat?: Seat; json?: boolean }) => fail(() => {
       const rows = new DecisionLedger(config).seatReport({ since: date(o.since), seat: o.seat });
-      emit(rows, o.json, rows.length ? rows.map(formatSeatDecisionRow).join('\n') : '자리 결정 0건');
+      return emit(rows, o.json, rows.length ? rows.map(formatSeatDecisionRow).join('\n') : '자리 결정 0건');
     }));
   root.command('proact').description('선제성 기준선 — 지난 7일, 먼저 낸 수·채택 수·물어서야 드러난 수')
     .option('--days <n>', 'KST 일수 (기본 7)', '7').option('--json')
@@ -147,17 +158,17 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
       const days = Number(o.days);
       if (!Number.isInteger(days) || days < 1) throw new Error('invalid days');
       const meter = readProactMeter({ ...(config.stateDir ? { stateDir: config.stateDir, instanceRoot: config.stateDir } : {}), ...(config.now ? { now: config.now() } : {}), days });
-      emit(meter, o.json, formatProactMeter(meter));
+      return emit(meter, o.json, formatProactMeter(meter));
     }));
   root.command('list').description('결정 목록 (기본 열린 것)')
     .option('--status <open|decided|all>', '기본 open', 'open').option('--since <date>').option('--version <version>')
     .option('--decided-by <human|auto>').option('--category <category>').option('--json')
     .action((o: { status: 'open' | 'decided' | 'all'; since?: string; version?: string; decidedBy?: 'human' | 'auto'; category?: DecisionCategory; json?: boolean }) => fail(() => {
       const rows = new DecisionLedger(config).list({ status: o.status, since: date(o.since), version: o.version, decidedBy: o.decidedBy, category: o.category });
-      emit(rows, o.json, rows.length ? rows.map(formatDecisionRow).join('\n') : '결정 0건');
+      return emit(rows, o.json, rows.length ? rows.map(formatDecisionRow).join('\n') : '결정 0건');
     }));
   root.command('show <id>').description('SCQA · 선택지 · 권고 · 이력 · 판').option('--json')
-    .action((id: string, o: { json?: boolean }) => fail(() => { const entry = new DecisionLedger(config).show(id); emit(entry, o.json, formatDecisionDetail(entry)); }));
+    .action((id: string, o: { json?: boolean }) => fail(() => { const entry = new DecisionLedger(config).show(id); return emit(entry, o.json, formatDecisionDetail(entry)); }));
   root.command('decide <id> <option>').description('사람 또는 AUTO 위임 결정 기록')
     .option('--note <text>').option('--auto').option('--delegation <reason>').option('--track <track>').option('--agent <agent>').option('--json').option('--hq-override')
     .action((id: string, choice: string, o: { note?: string; auto?: boolean; delegation?: string; track?: DecisionTrack; agent?: string; json?: boolean; hqOverride?: boolean }) => fail(() => {
@@ -169,17 +180,16 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
       if (delivery && !delivery.ok) {
         // The decision is recorded; only the answer to the waiting run failed — say so and how to retry, never «success».
         const hint = `⚠ 답 전달 실패(${delivery.questionId} · ${delivery.reason}) — 결정은 기록됐다 · 다시: elanous decisions retry-answer ${entry.id}`;
-        emit({ ...entry, delivery }, o.json, `결정: ${formatDecisionDetail(entry)}\n${hint}`);
         process.exitCode = 3;
-        return;
+        return emit({ ...entry, delivery }, o.json, `결정: ${formatDecisionDetail(entry)}\n${hint}`);
       }
-      emit(delivery ? { ...entry, delivery } : entry, o.json, `결정: ${formatDecisionDetail(entry)}`);
+      return emit(delivery ? { ...entry, delivery } : entry, o.json, `결정: ${formatDecisionDetail(entry)}`);
     }));
   root.command('retry-answer <id>').description('기록된 결정의 대기 질문 답 전달만 재시도한다').option('--json').option('--hq-override')
     .action((id: string, o: { json?: boolean; hqOverride?: boolean }) => fail(() => {
       if (!mayWrite('retry-answer', o.hqOverride)) return;
       const entry = new DecisionLedger(config).retryAnswer(id);
-      emit(entry, o.json, `답 전달: ${entry.id} → ${entry.resume?.questionId}`);
+      return emit(entry, o.json, `답 전달: ${entry.id} → ${entry.resume?.questionId}`);
     }));
   root.command('add-options <id>').description('선택지가 미기재된 과거 항목에 확인된 선택지를 추가')
     .requiredOption('--option <key=label:consequence>', '선택지 (두 번 이상)', repeat, [] as string[])
@@ -188,15 +198,15 @@ export function registerDecisionsCommands(program: Command, config: DecisionLedg
       const who = agent(o.agent);
       if (!mayWrite('add-options', o.hqOverride)) return;
       const entry = new DecisionLedger(config).addOptions(id, o.option.map(parseOption), who);
-      emit(entry, o.json, formatDecisionDetail(entry));
+      return emit(entry, o.json, formatDecisionDetail(entry));
     }));
   root.command('withdraw <id>').description('결정 철회도 원장에 남긴다').requiredOption('--reason <reason>').option('--json').option('--hq-override')
-    .action((id: string, o: { reason: string; json?: boolean; hqOverride?: boolean }) => fail(() => { if (!mayWrite('withdraw', o.hqOverride)) return; const entry = new DecisionLedger(config).withdraw(id, o.reason); emit(entry, o.json, `철회: ${formatDecisionDetail(entry)}`); }));
+    .action((id: string, o: { reason: string; json?: boolean; hqOverride?: boolean }) => fail(() => { if (!mayWrite('withdraw', o.hqOverride)) return; const entry = new DecisionLedger(config).withdraw(id, o.reason); return emit(entry, o.json, `철회: ${formatDecisionDetail(entry)}`); }));
   root.command('import-markdown <file>').description('기존 대표 결정 문서 씨앗을 가져온다 (재실행 안전)').option('--json').option('--hq-override')
     .action((file: string, o: { json?: boolean; hqOverride?: boolean }) => fail(() => {
       if (!mayWrite('import-markdown', o.hqOverride)) return;
       const result = importDecisionMarkdown(new DecisionLedger(config), file);
-      emit(result, o.json, `가져옴 ${result.imported.length} · 기존 ${result.existing.length} · 불완전 ${result.incomplete.length} · 못 읽음 ${result.unread.length}${result.incomplete.length ? `\n${result.incomplete.join('\n')}` : ''}${result.unread.length ? `\n${result.unread.join('\n')}` : ''}`);
       if (result.unread.length) process.exitCode = 1;
+      return emit(result, o.json, `가져옴 ${result.imported.length} · 기존 ${result.existing.length} · 불완전 ${result.incomplete.length} · 못 읽음 ${result.unread.length}${result.incomplete.length ? `\n${result.incomplete.join('\n')}` : ''}${result.unread.length ? `\n${result.unread.join('\n')}` : ''}`);
     }));
 }

package/src/cli/logs-model-input.ts

@@ -79,7 +79,7 @@ export function renderModelInput(report: ModelInputReport): string {
     `model input tokens · ${report.since} ~ ${report.until} · stores=${report.stores.join(', ') || '(없음)'} · records=${report.records}`,
     'scope\tnodeKind\tmeasured\tmedian\tp90\t못 잼',
     ...(report.baselines.length === 0 ? ['(관측 표본 없음)'] : report.baselines.map((item) =>
-      `${item.scope}\t${item.nodeKind}\t${item.measured}\t${item.median ?? '—'}\t${item.p90 ?? '—'}\t${item.unmeasured}`)),
+      `${item.scope}\t${item.nodeKind}\t${item.measured}\t${item.median ?? '못 잼'}\t${item.p90 ?? '못 잼'}\t${item.unmeasured}`)),
   ].join('\n');
 }
 

package/src/cli/ops-cli.ts

@@ -213,6 +213,17 @@ opsCmd.command('status').description('현재 상태 종합(미션·태스크·
     }
     return o.allInstances ? runOpsFleet(o.json === true, o.includeTest === true) : runOps('snapshot', o);
   });
+// OPS-OVERVIEW-CLI (RFC-ops-overview-flow-health-cli-2026-10-08) — 판정 먼저 · 이유 사슬 · 절. 못 잼 = null(0 아님).
+opsCmd.command('overview').description('흐름 한 장 — 저작→구현→착지가 흐르나(판정 먼저·이유 사슬) · 판·일꾼·기계·착지·루프 · 못 잼은 null · exit 0=흐름 정상/저하 3=그 밖 1=수집 실패')
+  .option('--json', '칸 꼴 그대로 ⊕ 머리 {verdict, reasons, nextActions, meta.elapsedMs}')
+  .option('--watch [seconds]', '주기 재조회(기본 30초)')
+  .option('--since <window>', '착지 창(<n>m|h|d · 기본 1h)', '1h')
+  .option('--owner <owner>', '일꾼 절 거르기 — seat:TC · TC · unassigned · all')
+  .option('--version <v>', '판(기본: 다음 컷)')
+  .action(async (o: { json?: boolean; watch?: string | boolean; since?: string; owner?: string; version?: string }) => {
+    const { runOpsOverview } = await import('./ops-overview-cli.js');
+    process.exitCode = await runOpsOverview(o);
+  });
 opsCmd.command('health').description('이상 판정만(blocked·errored·stale)').option('--json')
   .action((o: OpsOpts) => runOps('health', o));
 opsCmd.command('timeline').description('상태 전이 최근순 통합')

package/src/cli/ops-overview-cli.ts

@@ -0,0 +1,50 @@
+import { debug } from '../debug/log.js';
+import { collectOverview, parseSince } from '../ops/overview-collect.js';
+import { computeVerdict, renderOverview, unmeasuredCells, verdictExitCode, VERDICT_LABEL } from '../ops/overview.js';
+import { writeStdoutJson } from './stdout-json.js';
+
+export interface OpsOverviewOptions { json?: boolean; watch?: string | boolean; since?: string; owner?: string; version?: string }
+
+/** 한 번 모아서 내고 exit code 를 돌려준다(RFC §A4: flowing·degraded 0 · 그 밖 3 · 수집 실패 1). */
+async function once(o: OpsOverviewOptions, previous: string | null): Promise<{ code: number; verdict: string | null }> {
+  const started = performance.now();
+  let since: { ms: number; label: string };
+  try { since = parseSince(o.since); } catch (error) { console.error(String((error as Error).message)); return { code: 1, verdict: null }; }
+  try {
+    const snapshot = await collectOverview({ sinceMs: since.ms, sinceLabel: since.label, ...(o.owner ? { owner: o.owner } : {}), ...(o.version ? { version: o.version } : {}) });
+    const result = computeVerdict(snapshot);
+    const elapsedMs = Math.round(performance.now() - started);
+    const unmeasured = unmeasuredCells(snapshot);
+    debug.log('ops.overview', 'computed', { verdict: result.verdict, elapsedMs, unmeasured });
+    debug.flush();
+    if (o.json) {
+      await writeStdoutJson(JSON.stringify({ verdict: result.verdict, verdictLabel: VERDICT_LABEL[result.verdict], reasons: result.reasons, nextActions: result.nextActions,
+        meta: { elapsedMs, source: 'local', unmeasured }, ...snapshot }, null, 2) + '\n');
+    } else {
+      const text = renderOverview(snapshot, result, { elapsedMs });
+      if (previous !== null && previous !== result.verdict) console.log(`🔔 판정 바뀜: ${previous} → ${result.verdict}`);
+      console.log(text);
+    }
+    return { code: verdictExitCode(result.verdict), verdict: result.verdict };
+  } catch (error) {
+    debug.log('ops.overview', 'failed', { reason: String(error) });
+    debug.flush();
+    console.error(`ops overview 수집 실패: ${String(error)}`);
+    return { code: 1, verdict: null };
+  }
+}
+
+export async function runOpsOverview(o: OpsOverviewOptions): Promise<number> {
+  // 독립 CLI 프로세스는 데몬 StoreSink 를 물려받지 않는다 — 등록 없이는 debug.log 가 logs.db 에 안 닿는다(관측 안 한 것).
+  try { await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('cli'); } catch { /* fail-open */ }
+  if (o.watch === undefined || o.watch === false) return (await once(o, null)).code;
+  const seconds = o.watch === true ? 30 : Number(o.watch);
+  if (!Number.isFinite(seconds) || seconds < 5) { console.error('--watch 는 5초 이상'); return 1; }
+  let previous: string | null = null;
+  for (;;) {
+    if (!o.json) process.stdout.write('\x1b[2J\x1b[H');
+    const r = await once(o, previous);
+    previous = r.verdict ?? previous;
+    await new Promise((res) => setTimeout(res, seconds * 1000));
+  }
+}

package/src/cli/pod-cli.ts

@@ -151,6 +151,7 @@ export function registerPodCommands(program: Command, deps: PodCliDeps = {}): vo
       try {
         const result = await run({
           command: commandArgs,
+          returnLogs: true,
           ...(opts.pool ? { pool: opts.pool } : {}),
           ...(skills.length ? { skills } : {}),
           ...(opts.llm === 'grok' ? { llm: 'grok' as const } : {}),

package/src/cli/pr-cli.ts

@@ -62,6 +62,9 @@ import { enqueueL8ShadowQueue, runL8ShadowQueue, shadowPrNumber, statusL8ShadowQ
 export { branchLineageSlug, findSiblingPrs };
 
 export interface PrLandOpts {
+  /** Pin an existing PR and its reviewed head; both must be supplied together. */
+  pr?: string;
+  expectedHead?: string;
   base?: string;
   cwd?: string;
   dryRun?: boolean;
@@ -1180,10 +1183,33 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
 
   const cwd = opts.cwd ?? process.cwd();
   const run = deps.run ?? defaultCmdRunner;
+  const pinned = opts.pr !== undefined || opts.expectedHead !== undefined;
+  let pinnedBranch: string | undefined;
+  let pinnedUrl: string | undefined;
+  if (pinned) {
+    const pr = Number(opts.pr);
+    if (!/^[1-9]\d*$/.test(opts.pr ?? '') || !Number.isSafeInteger(pr) || !/^[a-f0-9]{40}$/i.test(opts.expectedHead ?? '') || opts.hold || opts.dryRun) {
+      out.error('✗ expected-head: --pr and --expected-head (full SHA) are required together without --hold/--dry-run');
+      return 1;
+    }
+    const viewed = run('gh', ['pr', 'view', String(pr), '--json', 'headRefOid,headRefName,state,isDraft,url'], { cwd });
+    let value: { headRefOid?: string; headRefName?: string; state?: string; isDraft?: boolean; url?: string } = {};
+    try { if (viewed.ok) value = JSON.parse(viewed.out) as typeof value; } catch { /* unreadable is not approval */ }
+    const local = run('git', ['rev-parse', 'HEAD'], { cwd });
+    const dirty = run('git', ['status', '--porcelain'], { cwd });
+    if (value.state !== 'OPEN' || value.isDraft !== false || value.headRefOid?.toLowerCase() !== opts.expectedHead!.toLowerCase()
+      || !value.url?.endsWith(`/pull/${pr}`) || !value.headRefName || !local.ok || local.out.trim().toLowerCase() !== opts.expectedHead!.toLowerCase()
+      || !dirty.ok || dirty.out.trim()) {
+      out.error('✗ expected-head: PR OPEN non-draft, matching local HEAD and clean worktree required');
+      return 1;
+    }
+    pinnedBranch = value.headRefName;
+    pinnedUrl = value.url;
+  }
   const resolveBase = deps.resolveBase ?? resolveDeliverableBase;
   const branch = (deps.currentBranch ?? liveCurrentBranch)(cwd);
-  if (!branch) {
-    const detail = '현재 브랜치를 해석하지 못했습니다.';
+  if (!branch || (pinned && branch !== pinnedBranch)) {
+    const detail = pinned ? 'PR head branch와 현재 브랜치가 다릅니다.' : '현재 브랜치를 해석하지 못했습니다.';
     record('branch', false);
     out.error(`✗ branch: ${detail}`);
     return 1;
@@ -1567,6 +1593,10 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     });
   }
   const hold = !!opts.hold || overlapDecision?.outcome === 'user-hold';
+  if (pinned && overlapDecision && overlapDecision.outcome !== 'user-merge') {
+    out.error('✗ expected-head: overlap merge approval unavailable for the reviewed head');
+    return 1;
+  }
 
   const manager = deps.manager ?? makePrManager(run);
   const existing = manager.findPrForBranchOutcome(branch, cwd);
@@ -1638,7 +1668,12 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     }
   }
 
-  const upsert = manager.upsertPr({
+  // A pinned, already-reviewed commit must not go through upsertPr (git add/commit/force-push/PR edit).
+  const upsert = pinned
+    ? existing.status === 'ok OUTPUT' && existing.url === pinnedUrl
+      ? { ok: true as const, url: pinnedUrl!, reused: true }
+      : { ok: false as const, reason: 'gh' as const, detail: 'pinned PR is not the branch open PR' }
+    : manager.upsertPr({
     branch,
     worktreePath: cwd,
     base,
@@ -1654,7 +1689,7 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     ...(excludingActiveRunFiles ? { excludePaths } : {}),
   });
   if (!upsert.ok) {
-    if (upsert.reason === 'noop' && excludingActiveRunFiles) {
+    if (upsert.reason === 'noop' && excludingActiveRunFiles && !pinned) {
       record('upsert-ready-noop', true, { excludePaths, detail: upsert.detail });
       out.log(`✓ upsert-ready: 제외 후 올릴 것이 없습니다 — ${upsert.detail}`);
       return 0;
@@ -1664,6 +1699,13 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     return 1;
   }
   record('upsert-ready', true);
+  if (pinned) {
+    const upsertHead = run('git', ['rev-parse', 'HEAD'], { cwd });
+    if (!upsert.reused || upsert.url !== pinnedUrl || !upsertHead.ok || upsertHead.out.trim().toLowerCase() !== opts.expectedHead!.toLowerCase()) {
+      out.error('✗ expected-head: pinned PR identity or reviewed HEAD changed');
+      return 1;
+    }
+  }
   out.log(`✓ upsert-ready: ${upsert.url}${upsert.reused ? ' (기존 PR)' : ' (새 PR)'}`);
 
   if (hold) {
@@ -1688,21 +1730,34 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     debug.log('harness.merge', 'frozen', { prUrl: upsert.url, reason: frozen.reason, until: frozen.until });
     record('freeze', true, { url: upsert.url, reason: frozen.reason, until: frozen.until });
     out.log(`✓ ready: ${upsert.url} — ${landingFreezeMessage(frozen)} · 병합 연기`);
-    return 0;
+    return pinned ? 1 : 0;
   }
   if (admission.kind === 'taken') {
     record('freeze', true, { url: upsert.url, resumedElsewhere: true });
     out.log(`✓ ready: ${upsert.url} — 동결이 막 풀려 보류 병합 재개가 이 PR 을 맡았습니다`);
-    return 0;
+    return pinned ? 1 : 0;
   }
   const landing = admission;
+  if (pinned) {
+    const view = run('gh', ['pr', 'view', String(opts.pr), '--json', 'headRefOid,state,isDraft'], { cwd });
+    let current: { headRefOid?: string; state?: string; isDraft?: boolean } = {};
+    try { if (view.ok) current = JSON.parse(view.out) as typeof current; } catch { /* fail closed */ }
+    const finalHead = run('git', ['rev-parse', 'HEAD'], { cwd });
+    if (current.headRefOid?.toLowerCase() !== opts.expectedHead!.toLowerCase() || current.state !== 'OPEN' || current.isDraft !== false
+      || !finalHead.ok || finalHead.out.trim().toLowerCase() !== opts.expectedHead!.toLowerCase()) {
+      landing.end(false);
+      out.error('✗ expected-head: PR head/state changed before merge');
+      return 1;
+    }
+  }
   let merged: ReturnType<typeof manager.mergePrOutcome>;
   try {
-  merged = manager.mergePrOutcome(upsert.url);
+  merged = manager.mergePrOutcome(upsert.url, pinned ? opts.expectedHead : undefined, pinned ? cwd : undefined);
   // `GIT-S14` — 병합이 «미완료(OPEN)»로 끝났고 GitHub 가 아직 `mergeable=UNKNOWN`(병합 가능 여부 계산 중)이면
   //   짧게 기다렸다 다시 병합한다. 표본 셋(08-25 · 09-24 🅢 #20233 등)이 모두 «같은 명령 재시도에 병합»이었다.
   //   ⛔ UNKNOWN 일 때만 재시도한다 — CONFLICTING 등 다른 값은 기다려도 안 풀린다(그대로 실패를 낸다).
   const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  // pinned 도 재시도한다 — mergePrOutcome 이 머리를 다시 확인하고 --match-head-commit 으로 병합하므로 바뀐 머리로는 안 들어간다.
   for (let attempt = 1; !merged.ok && merged.kind === 'not-merged' && merged.state === 'OPEN' && attempt <= PR_LAND_MERGEABLE_UNKNOWN_RETRIES; attempt += 1) {
     const mergeable = run('gh', ['pr', 'view', upsert.url, '--json', 'mergeable', '--jq', '.mergeable'], { cwd });
     const value = mergeable.ok ? mergeable.out.trim() : '';
@@ -1710,7 +1765,7 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     record('merge-retry', true, { attempt, mergeable: value, waitMs: PR_LAND_MERGEABLE_UNKNOWN_WAIT_MS });
     out.log(`⏳ merge: mergeable=UNKNOWN — GitHub 가 병합 가능 여부를 아직 계산 중입니다 · ${PR_LAND_MERGEABLE_UNKNOWN_WAIT_MS / 1000}초 뒤 다시 병합 (${attempt}/${PR_LAND_MERGEABLE_UNKNOWN_RETRIES})`);
     await sleep(PR_LAND_MERGEABLE_UNKNOWN_WAIT_MS);
-    merged = manager.mergePrOutcome(upsert.url);
+    merged = manager.mergePrOutcome(upsert.url, pinned ? opts.expectedHead : undefined, pinned ? cwd : undefined);
   }
   } finally { landing.end(merged!?.ok === true); }
   if (!merged.ok) {
@@ -1781,6 +1836,8 @@ export function registerPrCommands(program: Command, deps: PrLandDeps = {}, queu
     .description('현재 브랜치 PR을 생성 또는 갱신해 ready 상태로 만들고 squash merge')
     .option('--base <branch>', 'PR base branch')
     .option('--cwd <path>', '작업 트리 경로')
+    .option('--pr <number>', '기존 PR 번호 고정 (--expected-head 와 함께)')
+    .option('--expected-head <sha>', '리뷰된 PR 머리 SHA 고정 (--pr 와 함께)')
     .option('--dry-run', '변경 없이 landing 계획만 출력')
     .option('--hold', 'PR을 생성 또는 갱신한 뒤 병합하지 않고 쌓아 둔다')
     .option('--title <title>', 'PR title')

package/src/cli/release-cli.ts

@@ -18,7 +18,7 @@
 // ⛔ 공개본은 «원본 매니페스트»(`release/public-export.yaml`)대로만 만든다 — 매매 실행 코드는 그 매니페스트가 이미 뺀다(🅢 #20529).
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import type { Command } from 'commander';
@@ -27,7 +27,7 @@ import { effectiveInstanceRoot, releaseLedgerRoot } from '../instance/resolve.js
 import { getElanousConfigDirOverride } from '../elanous-config-dir.js';
 import { envLiteral } from '../platform/env-literal.js';
 import { getUserConfig, userConfigPath } from '../user-config.js';
-import { addItem, cellsReferencingDoc, claimItem, decodeClaimHistoryEntry, devVersion, listChecklist, ownerMatches, parseOwner, parityGap, removeItem, renderRefsStatus, seedFromRoadmap, setItem, summarizeChecklist, type ChecklistStatus, type ChecklistDisposition, type ChecklistKind } from '../release-loop/checklist.js';
+import { addItem, cellsReferencingDoc, claimItem, decodeClaimHistoryEntry, devVersion, lintDocRefs, listChecklist, normalizeRefs, ownerMatches, parseOwner, parityGap, refRoots, removeItem, renderRefsStatus, seedFromRoadmap, setItem, summarizeChecklist, type ChecklistStatus, type ChecklistDisposition, type ChecklistKind } from '../release-loop/checklist.js';
 import * as features from '../release-loop/feature-store.js';
 import { evidencePlan, landedButYellow, type MergedChecklistPr } from '../release-loop/landed-but-yellow.js';
 import { formatSchedule, getSchedule, listSchedules, setSchedule } from '../release-loop/release-schedule.js';
@@ -705,11 +705,28 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
       console.log(`루브릭 없는 칸 ${missing}`);
     });
   withContext(checklist.command('refs <doc>').description('문서를 인용하는 칸 — 모든 판의 구현 현황(읽기 전용)'))
-    .action(async (doc: string, _opts: unknown, cmd: Command) => {
+    .option('--lint', '문서 절과 칸 인용을 양방향 대조(읽기 전용)')
+    .action(async (doc: string, opts: { lint?: boolean }, cmd: Command) => {
       if (!doc.trim() || doc.trim().startsWith('#')) throw new CliUserError(`잘못된 문서: ${doc}`, '저장소 상대 경로[#절] — 예: docs/RFC-x.md#§3');
       const { json } = context(cmd);
       const ledgerRoot = releaseLedgerRoot();
-      const rows = cellsReferencingDoc(doc, features.assignedVersions(ledgerRoot).map((version) => listChecklist(version, ledgerRoot)));
+      const checklists = features.assignedVersions(ledgerRoot).map((version) => listChecklist(version, ledgerRoot));
+      if (opts.lint) {
+        const path = doc.trim().split('#')[0]!.replace(/^\.\//, '');
+        const roots = refRoots();
+        normalizeRefs([path], roots);
+        const file = roots.map((root) => join(root, path)).find((candidate) => {
+          try { return statSync(candidate).isFile(); } catch { return false; }
+        })!;
+        const result = lintDocRefs(path, readFileSync(file, 'utf8'), checklists);
+        debug.log('release.checklist', 'refs-lint', { doc, sections: result.sections.length, uncovered: result.uncoveredSections.length, dangling: result.danglingRefs.length });
+        if (json) { await writeStdoutJson(`${JSON.stringify({ doc, ...result })}\n`); return; }
+        console.log(`칸 없는 절: ${result.uncoveredSections.join(', ') || '없음'}`);
+        console.log(`없는 절을 가리키는 칸: ${result.danglingRefs.map(({ version, id, ref }) => `${version} ${id} ${ref}`).join(' · ') || '없음'}`);
+        console.log(`절 ${result.sections.length} · 칸 없는 절 ${result.uncoveredSections.length} · 없는 절을 가리키는 칸 ${result.danglingRefs.length}`);
+        return;
+      }
+      const rows = cellsReferencingDoc(doc, checklists);
       const byStatus = { green: 0, yellow: 0, red: 0, done: 0 } as Record<ChecklistStatus, number>;
       for (const row of rows) byStatus[row.status] += 1;
       debug.log('release.checklist', 'refs-read', { doc, rows: rows.length });