elanous 0.2.17 → 0.2.18

package/src/nexus/api/loop-edges.ts

@@ -1,5 +1,7 @@
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { listSeatRequests, type SeatRequestRow } from '../../seat-dispatch/seat-request-ledger.js';
 import { listCoordEvents } from '../../context-bus/coord-events.js';
 import { CardStore, cardIndexPath, type TaskCard } from '../../task-cards/card-store.js';
 import { loadRunLedger, resolveFederatedRunLedgerDirectories, type RunLedgerEntry } from '../../self-implement/run-ledger.js';
@@ -21,7 +23,9 @@ export interface LoopEdgesDeps {
   cardRoot?: string;
   ledgerDir?: string;
   listCards?: () => TaskCard[];
-  listRunStarts?: (since: string) => Array<{ runId: string; at: string; seat: string }>;
+  listRunStarts?: (since: string) => Array<{ runId: string; at: string; seat: string; mergedAt?: string }>;
+  listSeatRequests?: () => SeatRequestRow[];
+  listOrchestratorLaunches?: () => Array<{ key: string; runId: string }>;
   listLoopOwners?: () => Array<{ id: string; owner?: string | null }>;
   seatIds?: () => string[];
 }
@@ -47,7 +51,9 @@ function inWindow(at: string, since: number, now: number): boolean {
   return Number.isFinite(ms) && ms >= since && ms <= now;
 }
 
-function cardEdges(card: TaskCard, since: number, now: number, seats: ReadonlySet<string>): LoopEdge[] {
+type PlacedCell = { cardId: string; cellId: string; owner: string };
+
+function cardEdges(card: TaskCard, since: number, now: number, seats: ReadonlySet<string>, placedCells: PlacedCell[]): LoopEdge[] {
   if (!card.goalId.startsWith('wish:') || !ID.test(card.id)) return [];
   const node = `card:${card.id}`;
   const ref = card.id;
@@ -75,6 +81,7 @@ function cardEdges(card: TaskCard, since: number, now: number, seats: ReadonlySe
     if (!owner || !placement || placement.id !== cellId || !ID.test(cellId)
       || typeof placement.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(placement.version)) continue;
     placedOwners.add(owner);
+    placedCells.push({ cardId: card.id, cellId, owner });
     if (inWindow(section.createdAt, since, now)) {
       const cellNode = `loop:${cellId}`;
       edges.push({ at: section.createdAt, kind: 'card', from: node, to: cellNode, ref });
@@ -93,9 +100,9 @@ function cardEdges(card: TaskCard, since: number, now: number, seats: ReadonlySe
   return edges;
 }
 
-function runStarts(since: string, dir: string, owners: ReadonlyMap<string, string>, seats: ReadonlySet<string>): Array<{ runId: string; at: string; seat: string }> {
+function runStarts(since: string, dir: string, owners: ReadonlyMap<string, string>, seats: ReadonlySet<string>): Array<{ runId: string; at: string; seat: string; mergedAt?: string }> {
   if (!existsSync(dir)) return [];
-  const result: Array<{ runId: string; at: string; seat: string }> = [];
+  const result: Array<{ runId: string; at: string; seat: string; mergedAt?: string }> = [];
   let names: string[];
   try { names = readdirSync(dir); } catch { return []; }
   for (const name of names) {
@@ -110,14 +117,42 @@ function runStarts(since: string, dir: string, owners: ReadonlyMap<string, strin
     const feature = typeof start?.data.feature === 'string' ? start.data.feature : '';
     const launchSeat = start?.data.launchSeat ?? start?.data.seat ?? owners.get(feature)
       ?? start?.data.originAgent ?? start?.data.controller;
-    if (start?.timestamp && start.timestamp >= since && seat(launchSeat, seats)) {
-      result.push({ runId, at: start.timestamp, seat: launchSeat });
+    if (start?.timestamp && seat(launchSeat, seats)) {
+      const merged = entries?.find(entry => entry.event === 'merged' && entry.data.merged === true && typeof entry.timestamp === 'string');
+      if (start.timestamp >= since || (merged?.timestamp && merged.timestamp >= since)) {
+        result.push({ runId, at: start.timestamp, seat: launchSeat, ...(merged?.timestamp ? { mergedAt: merged.timestamp } : {}) });
+      }
     }
   }
   return result;
 }
 
-/** GET only; project an allowlist of fields from the three ledgers. Never serialize ledger records. */
+/** Project only the key and runId of orchestrator launches, never their card snapshots or prose. */
+function orchestratorLaunches(root: string): Array<{ key: string; runId: string }> {
+  const dir = join(root, 'loop', 'orchestrator');
+  if (!existsSync(dir)) return [];
+  const launches: Array<{ key: string; runId: string }> = [];
+  let names: string[];
+  try { names = readdirSync(dir); } catch { return []; }
+  for (const name of names) {
+    if (!/^[a-zA-Z0-9._-]+\.json$/.test(name)) continue;
+    const path = join(dir, name);
+    try {
+      if (!statSync(path).isFile() || statSync(path).size > 5 * 1024 * 1024) continue;
+      const state = parse(readFileSync(path, 'utf8'));
+      if (state?.mode !== 'live' || !Array.isArray(state.launched)) continue;
+      for (const item of state.launched) {
+        const launch = object(item);
+        if (typeof launch?.key === 'string' && typeof launch.runId === 'string') {
+          launches.push({ key: launch.key, runId: launch.runId });
+        }
+      }
+    } catch { /* An unreadable tick cannot establish a launch. */ }
+  }
+  return launches;
+}
+
+/** GET only; project an allowlist of fields from the ledgers. Never serialize ledger records. */
 export function handleLoopEdgesGet(req: Request, deps: LoopEdgesDeps = {}): Response {
   const params = new URL(req.url).searchParams;
   const rawSince = params.get('since');
@@ -143,13 +178,14 @@ export function handleLoopEdgesGet(req: Request, deps: LoopEdgesDeps = {}): Resp
       if (seat(recipient, seats)) edges.push({ at: event.at, kind, from: event.refs.seat, to: recipient, ref });
     }
   }
+  const placedCells: PlacedCell[] = [];
   if (deps.listCards) {
-    for (const card of deps.listCards()) edges.push(...cardEdges(card, since, now, seats));
+    for (const card of deps.listCards()) edges.push(...cardEdges(card, since, now, seats, placedCells));
   } else {
     const root = deps.cardRoot;
     if (existsSync(cardIndexPath(root))) {
       const store = new CardStore(root, true);
-      try { for (const card of store.listCards()) edges.push(...cardEdges(card, since, now, seats)); }
+      try { for (const card of store.listCards()) edges.push(...cardEdges(card, since, now, seats, placedCells)); }
       finally { store.close(); }
     }
   }
@@ -163,9 +199,29 @@ export function handleLoopEdgesGet(req: Request, deps: LoopEdgesDeps = {}): Resp
     return (deps.ledgerDir ? [deps.ledgerDir] : resolveFederatedRunLedgerDirectories({ includeTest: false }))
       .flatMap(dir => runStarts(from, dir, owners, seats));
   });
-  for (const run of readStarts(sinceIso)) {
-    if (seat(run.seat, seats) && ID.test(run.runId) && inWindow(run.at, since, now)) {
-      edges.push({ at: run.at, kind: 'run', from: run.seat, to: `loop:${run.runId}`, ref: run.runId });
+  const runs = readStarts(sinceIso).filter(run => seat(run.seat, seats) && ID.test(run.runId)
+    && (inWindow(run.at, since, now) || (run.mergedAt !== undefined && inWindow(run.mergedAt, since, now))));
+  for (const run of runs) {
+    if (inWindow(run.at, since, now)) edges.push({ at: run.at, kind: 'run', from: run.seat, to: `loop:${run.runId}`, ref: run.runId });
+  }
+  if (placedCells.length && runs.length) {
+    const root = deps.cardRoot ?? effectiveInstanceRoot();
+    let requests: SeatRequestRow[] = [];
+    let launches: Array<{ key: string; runId: string }> = [];
+    try { requests = (deps.listSeatRequests ?? (() => listSeatRequests(root)))(); } catch { /* Missing request evidence is not a match. */ }
+    try { launches = (deps.listOrchestratorLaunches ?? (() => orchestratorLaunches(root)))(); } catch { /* Missing launch evidence is not a match. */ }
+    const confirmed = new Set(launches.filter(item => ID.test(item.runId) && runs.some(run => run.runId === item.runId))
+      .map(item => JSON.stringify([item.key, item.runId])));
+    for (const cell of placedCells) {
+      const key = `orch:${cell.cardId}:${cell.cellId}`;
+      if (!requests.some(row => row.key === key && row.cell === cell.cellId && row.source === 'orchestrator' && row.seat === cell.owner)) continue;
+      for (const run of runs) {
+        if (run.seat !== cell.owner || !confirmed.has(JSON.stringify([key, run.runId]))) continue;
+        if (inWindow(run.at, since, now)) edges.push({ at: run.at, kind: 'card', from: cell.owner, to: `loop:${run.runId}`, ref: cell.cardId });
+        if (run.mergedAt && inWindow(run.mergedAt, since, now)) {
+          edges.push({ at: run.mergedAt, kind: 'card', from: `loop:${run.runId}`, to: `landed:${cell.cellId}`, ref: cell.cardId });
+        }
+      }
     }
   }
   edges.sort((a, b) => b.at.localeCompare(a.at) || a.kind.localeCompare(b.kind) || a.from.localeCompare(b.from) || a.to.localeCompare(b.to));

package/src/nexus/api/ops-seats-sources.ts

@@ -2,7 +2,7 @@
 // removed — same rule as decision replies), the release checklist, and the decision ledger. Each failure becomes null upstream.
 import { DecisionLedger } from '../../decisions/decision-ledger.js';
 import { listCoordEvents, type CoordEvent } from '../../context-bus/coord-events.js';
-import { devVersion, listChecklist, type ChecklistItem } from '../../release-loop/checklist.js';
+import { checklistDevVersion, listChecklist, type ChecklistItem } from '../../release-loop/checklist.js';
 import { getUserConfig } from '../../user-config.js';
 import { SEATS, kstDayRange, type ChannelComment, type ChannelSource, type MergedPr, type SeatsSources } from './ops-seats.js';
 
@@ -82,7 +82,7 @@ export function liveSeatsSources(deps: { listEvents?: typeof listCoordEvents; gi
       return lines?.map((line) => JSON.parse(line) as MergedPr) ?? null;
     },
     checklist() {
-      const dev = devVersion();
+      const dev = checklistDevVersion();
       const next = listChecklist(nextPatch(dev)).items;
       const current = listChecklist(dev).items;
       const all: ChecklistItem[] = [...current, ...next];

package/src/nexus/api/workflow-templates.ts

@@ -4,6 +4,7 @@
 
 import { readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { debug } from '../../debug/log.js';
 import { jsonResponse } from './http-server.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 
@@ -47,6 +48,8 @@ export function listTemplateCatalog(dir = findTemplateDir()): WorkflowTemplateEn
   try {
     files = readdirSync(dir).filter((f) => f.endsWith('.yaml'));
   } catch {
+    // An installed package without this folder used to answer «No templates available» silently (10-06 · files list).
+    debug.log('nexus.workflow-templates', 'template-dir-missing', { dir });
     return [];
   }
   const out: WorkflowTemplateEntry[] = [];

package/src/oauth/codex.ts

@@ -554,6 +554,44 @@ export function codexAccessHoursLeft(accessToken: unknown, now: number = Date.no
   return typeof exp === 'number' ? Math.round(((exp * 1000 - now) / 3_600_000) * 10) / 10 : null;
 }
 
+/** PREREFRESH-LOCK (10-06 · post-review of #24449) — the per-account host refresh lock path.
+ *  🩸 Two Pod launches on one host picked the same expiring account at once: both refreshed, the server
+ *  rotated the refresh token under the second, its refresh failed and that run dropped the account.
+ *  The lock file sits NEXT TO the account's credential state (`<codexHome>/.elanous-prerefresh.lock`) —
+ *  ⛔ never inside a token file, and it carries only the holder's pid/nonce. null = no named home to lock. */
+export function codexAccountRefreshLockPath(name: string, storePath: string = authStorePath()): string | null {
+  if (name === DEFAULT_CODEX_ACCOUNT || !isValidAccountName(name)) return null;
+  const codexHome = loadTokens(codexStoreKey(name), storePath)?.codexHome;
+  return codexHome ? join(codexHome, '.elanous-prerefresh.lock') : null;
+}
+
+/** A refresh (network + rotate + atomic write + import) can take tens of seconds — wait up to ~90 s,
+ *  and treat a lock as stale only after 2 min (the async holder heartbeats its mtime meanwhile). */
+export const CODEX_REFRESH_LOCK_OPTS = { staleMs: 120_000, retryBusyMs: 100, maxTries: 900 } as const;
+
+/** The refresh lock could not be acquired (timeout · ENOENT · EACCES …) — `fn` never ran, so nothing was refreshed. */
+export class CodexRefreshLockUnavailableError extends Error {
+  constructor(readonly reason: 'lock-timeout' | 'lock-error', cause: unknown) {
+    super(`codex refresh lock unavailable (${reason}): ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.name = 'CodexRefreshLockUnavailableError';
+  }
+}
+
+/** Runs `fn` while holding the account's refresh lock (cross-process · same-process). null path = no lock.
+ *  Any failure to acquire the lock throws `CodexRefreshLockUnavailableError` (fn not run); fn's own errors pass through. */
+export async function withCodexAccountRefreshLock<T>(lockPath: string | null, fn: () => Promise<T>, opts: { staleMs?: number; retryBusyMs?: number; maxTries?: number } = CODEX_REFRESH_LOCK_OPTS): Promise<T> {
+  if (!lockPath) return fn();
+  const { acquireLockAsync } = await import('../storage/file-lock.js');
+  let handle: Awaited<ReturnType<typeof acquireLockAsync>>;
+  try { handle = await acquireLockAsync(lockPath, opts); }
+  catch (error) {
+    const timedOut = error instanceof Error && error.message.startsWith('acquireLockAsync: timed out');
+    throw new CodexRefreshLockUnavailableError(timedOut ? 'lock-timeout' : 'lock-error', error);
+  }
+  try { return await fn(); }
+  finally { handle.release(); }
+}
+
 export async function refreshCodexAccountHome(
   name: string,
   opts: {

package/src/onboarding/first-chat-gate.ts

@@ -0,0 +1,29 @@
+import { debug } from '../debug/log.js';
+import { needsFirstRun, needsOnboarding } from '../onboarding.js';
+import type { UserConfig } from '../user-config.js';
+import type { FirstRunDeps, runFirstRun } from './first-run.js';
+import { UNATTENDED_SETUP_COMMAND } from './entry-hints.js';
+
+export interface FirstChatGateDeps {
+  isTTY: boolean;
+  runFirstRun: (deps: FirstRunDeps) => ReturnType<typeof runFirstRun>;
+  runInteractive: () => Promise<boolean>;
+  print: (line: string) => void;
+}
+
+export async function firstChatGate(cfg: UserConfig, deps: FirstChatGateDeps): Promise<'continue' | 'stop'> {
+  const decide = (decision: 'continue' | 'stop', outcome: string): 'continue' | 'stop' => {
+    debug.log('onboarding.first-chat', decision, { isTTY: deps.isTTY, outcome });
+    return decision;
+  };
+  if (!needsOnboarding(cfg)) return decide('continue', 'completed');
+  if (deps.isTTY) {
+    return decide(await deps.runInteractive() ? 'continue' : 'stop', 'interactive');
+  }
+  if (!needsFirstRun(cfg)) return decide('continue', 'already-ready');
+  const result = await deps.runFirstRun({ config: cfg, isTTY: false, print: () => {} });
+  if (result.outcome === 'ready') return decide('continue', result.outcome);
+  deps.print(`다음: elanous setup llm (또는 ${UNATTENDED_SETUP_COMMAND})`);
+  process.exitCode = 2;
+  return decide('stop', result.outcome);
+}

package/src/release-loop/checklist.ts

@@ -1,5 +1,6 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 import * as store from './feature-store.js';
 import { debug } from '../debug/log.js';
 import { CliUserError } from '../cli/cli-user-error.js';
@@ -20,6 +21,8 @@ export interface ChecklistItem {
   ceoDate?: string;
   /** 다른 칸의 처리량을 올리는 칸(자율성·효율성·동시성). 없으면 가속 등급이 아니다. */
   accelerator?: true;
+  /** 이 칸이 근거로 삼는 문서(저장소 상대 경로, 선택적으로 `#절`). 없으면 칸에 실리지 않는다. */
+  refs?: string[];
   evidence?: string;
   disposition?: ChecklistDisposition;
   kind?: ChecklistKind;
@@ -50,6 +53,12 @@ export function devVersion(): string {
   return (JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf8')) as { version: string }).version;
 }
 
+/** The checklist version of the development tree: package.json says `0.2.18-dev.0` once a release branch is cut,
+ * but the checklist only knows `0.2.18` (10-07: every server caller that passed devVersion() raw got null/throw). */
+export function checklistDevVersion(version = devVersion()): string {
+  return version.replace(/-dev\.\d+$/, '');
+}
+
 export function parseOwner(value: string): { seat: string; sub?: string } {
   const match = /^([A-Z]{2,8})(?:\/([a-z][a-z0-9-]{0,31}))?$/.exec(value);
   if (!match || match[0] !== value) throw new CliUserError(`잘못된 담당: ${value}`, 'TC 또는 TC/rel');
@@ -100,12 +109,82 @@ function change(data: Checklist, id: string, field: string, from: unknown, to: u
   debug.log('release-loop.checklist', 'change', { version: data.version, id, field, from: from ?? null, to: to ?? null, by });
 }
 
+const REPO_ROOT = join(import.meta.dir, '..', '..');
+
+/** `--ref` 문서를 찾는 뿌리들 — 이 코드의 트리 ⊕ 지금 작업 디렉토리의 git 뿌리.
+ *  ⭐ 설치본(`~/.local/share/elanous/current`)에는 `docs/` 가 없다 — 저장소 안에서 부른 설치본도 저장소 문서를 인용할 수 있게. */
+export function refRoots(cwd = process.cwd()): string[] {
+  const roots = [REPO_ROOT];
+  try {
+    const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', timeout: 5_000 });
+    const path = top.status === 0 ? top.stdout.trim() : '';
+    if (path && !roots.includes(path)) roots.push(path);
+  } catch { /* git 없음 — 코드 트리만 */ }
+  return roots;
+}
+
+/** `--ref` 값 검사: 저장소 상대 경로(⊕ `#절`)이고 그 파일이 뿌리들 중 하나에 있어야 한다. 중복은 순서를 지키며 지운다. */
+export function normalizeRefs(refs: readonly string[], root: string | readonly string[] = refRoots()): string[] {
+  const roots = typeof root === 'string' ? [root] : root;
+  const out: string[] = [];
+  for (const raw of refs) {
+    const ref = raw.trim();
+    const path = ref.split('#')[0] ?? '';
+    if (!path || isAbsolute(path) || path.split(/[\\/]/).some((part) => part === '..')) throw new CliUserError(`잘못된 문서 참조: ${raw}`, '저장소 상대 경로[#절] — 예: docs/manual/MANUAL-x.md#§1');
+    let isFile = false;
+    for (const base of roots) {
+      try { if (statSync(join(base, path)).isFile()) { isFile = true; break; } } catch { /* 없음 */ }
+    }
+    if (!isFile) throw new CliUserError(`없는 문서: ${path}`, '저장소 상대 «파일» 경로로 준다(폴더는 안 된다)');
+    if (!out.includes(ref)) out.push(ref);
+  }
+  return out;
+}
+
+/** 한 문서를 인용하는 칸 한 줄 — `release checklist refs <doc>` 의 «구현 현황» 행. */
+export interface DocRefRow { version: string; id: string; title: string; status: ChecklistStatus; owner: string | null; section: string | null }
+
+function splitRef(ref: string): { path: string; section: string | null } {
+  const at = ref.indexOf('#');
+  const path = (at < 0 ? ref : ref.slice(0, at)).trim().replace(/^\.\//, '');
+  return { path, section: at < 0 ? null : ref.slice(at + 1) };
+}
+
+/** 읽기 전용: 칸의 refs 중 경로(`#` 앞)가 doc 의 경로와 같은 것을 행으로 낸다. doc 에 `#절`이 붙으면 그 절과 정확히 같은 ref 만. */
+export function cellsReferencingDoc(doc: string, checklists: readonly Checklist[]): DocRefRow[] {
+  const want = splitRef(doc.trim());
+  const rows: DocRefRow[] = [];
+  for (const data of checklists) {
+    for (const item of data.items) {
+      // 칸마다 한 행 — 같은 문서의 절을 여럿 인용해도 절을 모아 한 줄로(절 없는 인용이 섞이면 문서 전체로 본다).
+      const sections: string[] = [];
+      let whole = false;
+      for (const ref of item.refs ?? []) {
+        const got = splitRef(ref);
+        if (got.path !== want.path) continue;
+        if (want.section !== null && got.section !== want.section) continue;
+        if (got.section === null) whole = true;
+        else if (!sections.includes(got.section)) sections.push(got.section);
+      }
+      if (!whole && sections.length === 0) continue;
+      rows.push({ version: data.version, id: item.id, title: item.title, status: item.status, owner: item.owner ?? null, section: whole ? null : sections.join(' · ') });
+    }
+  }
+  return rows;
+}
+
+/** `| 판 | 칸 | 상태 | 절 | 제목 |` 마크다운 표 — 행이 없으면 머리줄 둘만. */
+export function renderRefsStatus(rows: readonly DocRefRow[]): string {
+  const cell = (value: string) => value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+  return ['| 판 | 칸 | 상태 | 절 | 제목 |', '| --- | --- | --- | --- | --- |', ...rows.map((row) => `| ${cell(row.version)} | ${cell(row.id)} | ${row.status} | ${cell(row.section ?? '-')} | ${cell(row.title)} |`)].join('\n');
+}
+
 export function validateCeoLoad(input: { ceoMinutes?: number; ceoDate?: string }): void {
   if (input.ceoMinutes !== undefined && (!Number.isSafeInteger(input.ceoMinutes) || input.ceoMinutes < 0)) throw new CliUserError('대표 손 분량은 0 이상의 정수 분이어야 한다');
   if (input.ceoDate !== undefined && (!/^\d{4}-\d{2}-\d{2}$/.test(input.ceoDate) || !Number.isFinite(Date.parse(`${input.ceoDate}T00:00:00Z`)) || new Date(`${input.ceoDate}T00:00:00Z`).toISOString().slice(0, 10) !== input.ceoDate)) throw new CliUserError('대표 손 날짜는 YYYY-MM-DD 이어야 한다');
 }
 
-export function addItem(v: string, input: { id: string; title: string; owner?: string; kind?: ChecklistKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean }, options: { allowDuplicateId?: boolean } = {}): Checklist {
+export function addItem(v: string, input: { id: string; title: string; refs?: string[]; owner?: string; kind?: ChecklistKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean }, options: { allowDuplicateId?: boolean } = {}): Checklist {
   if (!input.id.trim()) throw new CliUserError('칸 id 가 비었다');
   if (!input.title.trim()) throw new CliUserError('칸 제목이 비었다');
   if (input.kind !== undefined && input.kind !== 'screen') throw new CliUserError(`잘못된 종류: ${input.kind}`, 'screen');
@@ -115,6 +194,7 @@ export function addItem(v: string, input: { id: string; title: string; owner?: s
   if (input.deadlineVersion !== undefined) store.validateVersion(input.deadlineVersion);
   if (input.accelerator !== undefined && input.accelerator !== true) throw new CliUserError('가속 등급은 true 이거나 생략한다');
   validateCeoLoad(input);
+  const refs = input.refs !== undefined && input.refs.length ? normalizeRefs(input.refs) : undefined;
   return mutate(v, (data, otherItems) => {
     if (data.items.some((item) => item.id === input.id)) throw new CliUserError(`이미 있는 칸: ${input.id}`, 'set <id> 로 고친다');
     const collisions = otherItems(input.id);
@@ -125,14 +205,14 @@ export function addItem(v: string, input: { id: string; title: string; owner?: s
     }
     const by = process.env.ELANOUS_TRACK || 'cli';
     const at = new Date().toISOString();
-    const item: ChecklistItem = { id: input.id, title: input.title, status: 'yellow', ...(input.owner !== undefined ? { owner: input.owner } : {}), ...(input.kind !== undefined ? { kind: input.kind } : {}), ...(input.priority !== undefined ? { priority: input.priority } : {}), ...(input.predecessors !== undefined ? { predecessors: input.predecessors } : {}), ...(input.deadlineVersion !== undefined ? { deadlineVersion: input.deadlineVersion } : {}), ...(input.ceoMinutes !== undefined ? { ceoMinutes: input.ceoMinutes } : {}), ...(input.ceoDate !== undefined ? { ceoDate: input.ceoDate } : {}), ...(input.accelerator === true ? { accelerator: true as const } : {}), updatedAt: at, updatedBy: by };
+    const item: ChecklistItem = { id: input.id, title: input.title, status: 'yellow', ...(input.owner !== undefined ? { owner: input.owner } : {}), ...(input.kind !== undefined ? { kind: input.kind } : {}), ...(input.priority !== undefined ? { priority: input.priority } : {}), ...(input.predecessors !== undefined ? { predecessors: input.predecessors } : {}), ...(input.deadlineVersion !== undefined ? { deadlineVersion: input.deadlineVersion } : {}), ...(input.ceoMinutes !== undefined ? { ceoMinutes: input.ceoMinutes } : {}), ...(input.ceoDate !== undefined ? { ceoDate: input.ceoDate } : {}), ...(input.accelerator === true ? { accelerator: true as const } : {}), ...(refs ? { refs } : {}), updatedAt: at, updatedBy: by };
     data.items.push(item);
     change(data, item.id, 'add', null, item, by, at);
     return true;
   });
 }
 
-export function setItem(v: string, id: string, patch: { status?: ChecklistStatus; evidence?: string; owner?: string; disposition?: ChecklistDisposition; kind?: ChecklistKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean | null }, by: string): Checklist {
+export function setItem(v: string, id: string, patch: { status?: ChecklistStatus; evidence?: string; refs?: string[]; owner?: string; disposition?: ChecklistDisposition; kind?: ChecklistKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean | null }, by: string): Checklist {
   return mutate(v, (data) => {
     const item = data.items.find((i) => i.id === id);
     if (!item) throw new CliUserError(`없는 칸: ${id}`, 'list 로 칸 목록을 본다');
@@ -144,13 +224,15 @@ export function setItem(v: string, id: string, patch: { status?: ChecklistStatus
     if (patch.deadlineVersion !== undefined) store.validateVersion(patch.deadlineVersion);
     if (patch.accelerator !== undefined && patch.accelerator !== true && patch.accelerator !== null) throw new CliUserError('가속 등급은 true(부여) 또는 null(해제)이다');
     validateCeoLoad(patch);
+    // --ref 는 «더하기»다 — 기존 참조 뒤에 붙이고 중복을 지운다.
+    if (patch.refs !== undefined) patch = { ...patch, refs: normalizeRefs([...(item.refs ?? []), ...patch.refs]) };
     if (patch.owner !== undefined) {
       parseOwner(patch.owner);
       if (item.owner && patch.owner !== item.owner) {
         throw new CliUserError(`지금 주인: ${item.owner} — --force 로만 바꾼다`, 'release checklist claim <id> --by <자리> --force');
       }
     }
-    const fields = (['evidence', 'owner', 'status', 'disposition', 'kind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator'] as const).filter((field) => patch[field] !== undefined && JSON.stringify(patch[field]) !== JSON.stringify(item[field] ?? null));
+    const fields = (['evidence', 'owner', 'status', 'disposition', 'kind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator', 'refs'] as const).filter((field) => patch[field] !== undefined && JSON.stringify(patch[field]) !== JSON.stringify(item[field] ?? null));
     if (fields.length === 0) return false;
     const at = new Date().toISOString();
     for (const field of fields) {
@@ -269,6 +351,22 @@ export function checklistGate(v: string): ChecklistGate {
   return result;
 }
 
+/** GATE-ENTRY-ALIGN: the cut-time judgement shared by `release run`'s entry check and the checklist-gate node —
+ *  past the landing deadline a non-P0 yellow without a disposition is carried (moved), and a P0 yellow always blocks. */
+export function cutChecklistGate(v: string, landBy: string | null | undefined, now: Date = new Date()): ChecklistGate & { autoMoved: string[] } {
+  const items = listChecklist(v).items;
+  const overdue = landBy !== null && landBy !== undefined && now.getTime() > Date.parse(landBy);
+  const autoMoved = overdue ? items.filter((item) => item.status === 'yellow' && item.priority !== 'P0' && item.disposition === undefined).map((item) => item.id) : [];
+  const p0 = items.filter((item) => item.status === 'yellow' && item.priority === 'P0').map((item) => item.id);
+  const gate = checklistGate(v);
+  gate.undecided = gate.undecided.filter((id) => !autoMoved.includes(id) && !p0.includes(id));
+  gate.moved = gate.moved.filter((id) => !p0.includes(id)).concat(autoMoved);
+  gate.knownIssues = gate.knownIssues.filter((item) => !p0.includes(item.id));
+  gate.blocked.push(...p0.filter((id) => !gate.blocked.includes(id)));
+  gate.ok = gate.red.length === 0 && gate.undecided.length === 0 && gate.blocked.length === 0;
+  return { ...gate, autoMoved };
+}
+
 export function seedFromRoadmap(v: string, markdown: string): Checklist {
   return mutate(v, (data) => {
     let added = false;

package/src/release-loop/feature-store.ts

@@ -33,7 +33,7 @@ const walWait = new Int32Array(new SharedArrayBuffer(4));
 const SCHEMA_COLUMNS: Record<string, readonly string[]> = {
   imported_versions: ['json_hash', 'imported_at'],
   events: ['reason'],
-  assignments: ['priority', 'predecessors', 'deadline_version', 'ceo_minutes', 'ceo_date', 'accelerator'],
+  assignments: ['priority', 'predecessors', 'deadline_version', 'ceo_minutes', 'ceo_date', 'accelerator', 'refs'],
   release_schedules: ['freeze_from', 'freeze_until'],
 };
 function schemaCurrent(db: Database): boolean {
@@ -75,7 +75,7 @@ function open(root = releaseLedgerRoot()): Database {
       if (!(db.query('PRAGMA table_info(events)').all() as Array<{ name: string }>).some((column) => column.name === 'reason')) db.exec('ALTER TABLE events ADD COLUMN reason TEXT');
       db.exec('CREATE TABLE IF NOT EXISTS release_schedules (version TEXT PRIMARY KEY, cut_at TEXT NOT NULL, land_by TEXT, updated_at TEXT NOT NULL, updated_by TEXT NOT NULL)');
       const assignmentColumns = db.query('PRAGMA table_info(assignments)').all() as Array<{ name: string }>;
-      for (const [name, sql] of [['priority', 'TEXT'], ['predecessors', 'TEXT'], ['deadline_version', 'TEXT'], ['ceo_minutes', 'INTEGER'], ['ceo_date', 'TEXT'], ['accelerator', 'INTEGER']] as const) {
+      for (const [name, sql] of [['priority', 'TEXT'], ['predecessors', 'TEXT'], ['deadline_version', 'TEXT'], ['ceo_minutes', 'INTEGER'], ['ceo_date', 'TEXT'], ['accelerator', 'INTEGER'], ['refs', 'TEXT']] as const) {
         if (!assignmentColumns.some((column) => column.name === name)) db.exec(`ALTER TABLE assignments ADD COLUMN ${name} ${sql}`);
       }
       const scheduleColumns = db.query('PRAGMA table_info(release_schedules)').all() as Array<{ name: string }>;
@@ -169,7 +169,7 @@ function evidenceRefs(db: Database, version: string, id: string): string[] {
   return (db.query('SELECT ref FROM evidence WHERE feature_id = ? AND version = ? ORDER BY rowid').all(id, version) as Array<{ ref: string }>).map((row) => row.ref);
 }
 function items(db: Database, version: string): ChecklistItem[] {
-  const rows = db.query(`SELECT f.id, COALESCE(a.title_override, f.title) AS title, a.owner, a.kind, a.priority, a.predecessors, a.deadline_version, a.ceo_minutes, a.ceo_date, a.accelerator, a.status, a.disposition, a.evidence, a.updated_at, a.updated_by
+  const rows = db.query(`SELECT f.id, COALESCE(a.title_override, f.title) AS title, a.owner, a.kind, a.priority, a.predecessors, a.deadline_version, a.ceo_minutes, a.ceo_date, a.accelerator, a.refs, a.status, a.disposition, a.evidence, a.updated_at, a.updated_by
     FROM assignments a JOIN features f ON f.id = a.feature_id WHERE a.version = ? ORDER BY a.rowid`).all(version) as Array<Record<string, string | number | null>>;
   return rows.map((r) => {
     const evidence = [r.evidence, ...evidenceRefs(db, version, r.id as string)].filter((value) => value !== null).join('\n');
@@ -179,6 +179,7 @@ function items(db: Database, version: string): ChecklistItem[] {
       ...(r.deadline_version !== null ? { deadlineVersion: r.deadline_version as string } : {}),
       ...(r.ceo_minutes !== null ? { ceoMinutes: r.ceo_minutes as number } : {}), ...(r.ceo_date !== null ? { ceoDate: r.ceo_date as string } : {}),
       ...(r.accelerator === 1 ? { accelerator: true as const } : {}),
+      ...(r.refs !== null && r.refs !== undefined ? { refs: JSON.parse(r.refs as string) as string[] } : {}),
       ...(r.evidence !== null || evidence ? { evidence } : {}), ...(r.disposition !== null ? { disposition: r.disposition as ChecklistItem['disposition'] } : {}),
       updatedAt: r.updated_at as string, updatedBy: r.updated_by as string };
   });
@@ -192,9 +193,9 @@ function putItem(db: Database, version: string, item: ChecklistItem): void {
   if (!feature) db.query('INSERT INTO features (id, title, owner, kind, created_at) VALUES (?, ?, ?, ?, ?)').run(item.id, item.title, item.owner ?? null, item.kind ?? null, item.updatedAt);
   // features.owner/kind follow the latest assignment so details() and the checklist never disagree after a set.
   else if (item.owner !== undefined || item.kind !== undefined) db.query('UPDATE features SET owner = COALESCE(?, owner), kind = COALESCE(?, kind) WHERE id = ?').run(item.owner ?? null, item.kind ?? null, item.id);
-  db.query(`INSERT INTO assignments (feature_id, version, status, disposition, evidence, title_override, owner, kind, priority, predecessors, deadline_version, ceo_minutes, ceo_date, accelerator, updated_at, updated_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(feature_id, version) DO UPDATE SET status=excluded.status, disposition=excluded.disposition, evidence=excluded.evidence, owner=excluded.owner, kind=excluded.kind, priority=excluded.priority, predecessors=excluded.predecessors, deadline_version=excluded.deadline_version, ceo_minutes=excluded.ceo_minutes, ceo_date=excluded.ceo_date, accelerator=excluded.accelerator, updated_at=excluded.updated_at, updated_by=excluded.updated_by`)
-    .run(item.id, version, item.status, item.disposition ?? null, item.evidence ?? null, feature && feature.title !== item.title ? item.title : null, item.owner ?? null, item.kind ?? null, item.priority ?? null, item.predecessors ? JSON.stringify(item.predecessors) : null, item.deadlineVersion ?? null, item.ceoMinutes ?? null, item.ceoDate ?? null, item.accelerator === true ? 1 : null, item.updatedAt, item.updatedBy);
+  db.query(`INSERT INTO assignments (feature_id, version, status, disposition, evidence, title_override, owner, kind, priority, predecessors, deadline_version, ceo_minutes, ceo_date, accelerator, refs, updated_at, updated_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(feature_id, version) DO UPDATE SET status=excluded.status, disposition=excluded.disposition, evidence=excluded.evidence, owner=excluded.owner, kind=excluded.kind, priority=excluded.priority, predecessors=excluded.predecessors, deadline_version=excluded.deadline_version, ceo_minutes=excluded.ceo_minutes, ceo_date=excluded.ceo_date, accelerator=excluded.accelerator, refs=excluded.refs, updated_at=excluded.updated_at, updated_by=excluded.updated_by`)
+    .run(item.id, version, item.status, item.disposition ?? null, item.evidence ?? null, feature && feature.title !== item.title ? item.title : null, item.owner ?? null, item.kind ?? null, item.priority ?? null, item.predecessors ? JSON.stringify(item.predecessors) : null, item.deadlineVersion ?? null, item.ceoMinutes ?? null, item.ceoDate ?? null, item.accelerator === true ? 1 : null, item.refs?.length ? JSON.stringify(item.refs) : null, item.updatedAt, item.updatedBy);
 }
 function jsonHash(contents: string | Buffer): string { return createHash('sha256').update(contents).digest('hex'); }
 
@@ -235,8 +236,8 @@ function importOnDb(db: Database, version: string): boolean {
       // Keep a legacy per-version title until an explicit retitle unifies the feature identity.
       if (!existing) putItem(db, version, item);
       else {
-        db.query('INSERT OR IGNORE INTO assignments (feature_id, version, status, disposition, evidence, title_override, owner, kind, priority, predecessors, deadline_version, ceo_minutes, ceo_date, accelerator, updated_at, updated_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
-          .run(item.id, version, item.status, item.disposition ?? null, item.evidence ?? null, item.title === existing.title ? null : item.title, item.owner ?? null, item.kind ?? null, item.priority ?? null, item.predecessors ? JSON.stringify(item.predecessors) : null, item.deadlineVersion ?? null, item.ceoMinutes ?? null, item.ceoDate ?? null, item.accelerator === true ? 1 : null, item.updatedAt, item.updatedBy);
+        db.query('INSERT OR IGNORE INTO assignments (feature_id, version, status, disposition, evidence, title_override, owner, kind, priority, predecessors, deadline_version, ceo_minutes, ceo_date, accelerator, refs, updated_at, updated_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+          .run(item.id, version, item.status, item.disposition ?? null, item.evidence ?? null, item.title === existing.title ? null : item.title, item.owner ?? null, item.kind ?? null, item.priority ?? null, item.predecessors ? JSON.stringify(item.predecessors) : null, item.deadlineVersion ?? null, item.ceoMinutes ?? null, item.ceoDate ?? null, item.accelerator === true ? 1 : null, item.refs?.length ? JSON.stringify(item.refs) : null, item.updatedAt, item.updatedBy);
       }
     }
     for (const entry of data.history) record(db, version, entry);
@@ -263,7 +264,7 @@ function importOnDb(db: Database, version: string): boolean {
       record(db, version, { at: new Date().toISOString(), by: item.updatedBy, id: item.id, field: 'reimport', from: null, to: item, released: data.released, dev: data.dev });
       continue;
     }
-    const fields = ['title', 'status', 'evidence', 'owner', 'disposition', 'kind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator'] as const;
+    const fields = ['title', 'status', 'evidence', 'owner', 'disposition', 'kind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator', 'refs'] as const;
     const baseEvidence = (db.query('SELECT evidence FROM assignments WHERE feature_id = ? AND version = ?').get(item.id, version) as { evidence: string | null }).evidence ?? undefined;
     const preserveRefs = item.evidence === baseEvidence || item.evidence === current.evidence;
     const differs = fields.some((field) => field === 'evidence'

package/src/release-loop/landing-freeze.ts

@@ -8,6 +8,7 @@ export interface LandingFreeze {
   startedAt: string;
   until: string | null;
   by: string;
+  holdLaunches?: boolean;
 }
 
 export function landingFreezePath(root = effectiveInstanceRoot()): string {
@@ -25,21 +26,22 @@ export function readLandingFreeze(root = effectiveInstanceRoot(), now = new Date
   const freeze = record as Partial<LandingFreeze>;
   if (typeof freeze.reason !== 'string' || typeof freeze.by !== 'string' ||
       typeof freeze.startedAt !== 'string' || !Number.isFinite(Date.parse(freeze.startedAt)) ||
-      !(freeze.until === null || (typeof freeze.until === 'string' && Number.isFinite(Date.parse(freeze.until))))) {
+      !(freeze.until === null || (typeof freeze.until === 'string' && Number.isFinite(Date.parse(freeze.until)))) ||
+      (freeze.holdLaunches !== undefined && typeof freeze.holdLaunches !== 'boolean')) {
     throw new Error(`invalid landing freeze: ${path}`);
   }
   // An expired freeze reads as «off». The file is left alone: deleting it here could race a concurrent `freeze on`
   // that just wrote a new one (only `freeze off` removes it; the next `freeze on` overwrites it).
   if (freeze.until && Date.parse(freeze.until) <= now.getTime()) return null;
-  return freeze as LandingFreeze;
+  return { ...freeze, holdLaunches: freeze.holdLaunches ?? false } as LandingFreeze;
 }
 
-export function enableLandingFreeze(opts: { reason?: string; until?: string; by?: string }, root = effectiveInstanceRoot(), now = new Date()): LandingFreeze {
+export function enableLandingFreeze(opts: { reason?: string; until?: string; by?: string; holdLaunches?: boolean }, root = effectiveInstanceRoot(), now = new Date()): LandingFreeze {
   const until = opts.until === undefined ? null : opts.until;
   if (until !== null && (!/^\d{4}-\d\d-\d\dT\d\d:\d\d(?::\d\d(?:\.\d+)?)?(?:Z|[+-]\d\d:\d\d)$/.test(until) || !Number.isFinite(Date.parse(until)) || Date.parse(until) <= now.getTime())) {
     throw new Error('--until must be a future ISO timestamp with timezone');
   }
-  const freeze: LandingFreeze = { reason: opts.reason?.trim() || 'operator freeze', startedAt: now.toISOString(), until: until === null ? null : new Date(until).toISOString(), by: opts.by?.trim() || process.env.ELANOUS_TRACK || process.env.USER || 'cli' };
+  const freeze: LandingFreeze = { reason: opts.reason?.trim() || 'operator freeze', startedAt: now.toISOString(), until: until === null ? null : new Date(until).toISOString(), by: opts.by?.trim() || process.env.ELANOUS_TRACK || process.env.USER || 'cli', holdLaunches: opts.holdLaunches ?? false };
   const path = landingFreezePath(root);
   mkdirSync(root, { recursive: true });
   const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;

package/src/release-loop/placement.ts

@@ -8,6 +8,7 @@ import { userConfigPath } from '../user-config.js';
 import { addItem, listChecklist, ownerMatches, parseOwner, setItem, validateCeoLoad, type ChecklistItem } from './checklist.js';
 import { move, releasedVersion } from './feature-store.js';
 import { listSchedules, type ReleaseSchedule } from './release-schedule.js';
+import { parseRubric, rubricScore } from './rubric.js';
 
 export type PlacementPriority = 'P0' | 'P1' | 'P2';
 export interface PlacementCell { id: string; title: string; owner: string; priority: PlacementPriority; predecessors: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean }
@@ -271,20 +272,29 @@ export function rebalance(version: string, deps: PlacementDeps = {}): RebalanceR
   const backlog = deps.backlog ?? BACKLOG_VERSIONS;
   const next = rows.find((row) => versionOrder(row.version, version) > 0 && !backlog.includes(row.version));
   const snapshots = new Map(rows.map((row) => [row.version, [...(deps.checklist ?? listChecklist)(row.version).items]]));
-  const unstarted = snapshots.get(version)!.filter((item) => item.status === 'yellow' && !item.evidence);
+  const unstarted = snapshots.get(version)!.filter((item) => item.status === 'yellow' && !item.evidence)
+    .map((item, index) => {
+      const rubric = parseRubric(`${item.title}\n${item.evidence ?? ''}`);
+      return { item, index, score: rubric ? rubricScore(rubric) : null };
+    })
+    .sort((a, b) => {
+      if (a.score === null) return b.score === null ? a.index - b.index : 1;
+      if (b.score === null) return -1;
+      return a.score - b.score || a.index - b.index;
+    });
   if (unstarted.length && !next) throw new CliUserError(`${version} 다음 판이 없다`);
   if (!unstarted.length) return { decisions: [], blocked: [] };
   const rate = deps.merged24h ?? mergedPrsLast24h(new Date(now));
   const caps = deps.seatCap ?? placementSeatCap();
   const ceoCap = validCeoCap(deps.ceoDailyCap ?? placementCeoDailyCap());
   const result: RebalanceResult = { decisions: [], blocked: [] };
-  for (const item of unstarted) {
+  for (const { item, score } of unstarted) {
     const violation = moveConstraint(item, next!, backlog, snapshots, now, rate, caps, rows, ceoCap);
     if (violation) {
       result.blocked.push({ id: item.id, from: version, to: next!.version, reason: violation });
       continue;
     }
-    const reason = `${version} 착지 마감 2시간 전 미시작 칸 이월`;
+    const reason = `${version} 착지 마감 2시간 전 미시작 칸 이월${score === null ? '' : ` · 루브릭 ${score}`}`;
     result.decisions.push({ id: item.id, from: version, version: next!.version, reason, displaced: [] });
     snapshots.set(version, snapshots.get(version)!.filter((cell) => cell.id !== item.id));
     snapshots.get(next!.version)!.push(item);