elanous 0.2.17 → 0.2.18

package/src/cli/release-cli.ts

@@ -5,8 +5,10 @@
 //   elanous release tag --version <x.y.z> --source <commit> [--yes]
 //   elanous release verify  [--version <x.y.z>]
 //   elanous release notes   --from <ref> [--to <ref>]
-//   elanous release run     --version <x.y.z> [--cut-commit <sha>] [--dry-run] [--json] [--if-ready]
+//   elanous release run     --version <x.y.z> [--prerelease rc] [--main-cut | --cut-commit <sha>] [--dry-run] [--json] [--if-ready]
+//   elanous release resume  --run <runId> --from <node> [--json]   (release/<v> 수리 뒤 새 끝으로 이어 달리기)
 //   elanous release auto-start [--window-minutes <n>] [--apply] [--json]
+//   elanous release preflight --version <x.y.z> [--publish-at <iso>] [--json]   (컷 30분 전 사전 점검 · 읽기 전용 · ⛔ 있으면 exit 1)
 //   elanous release cut-branch --version <x.y.z> --base <sha> --pick <sha>... [--dry-run]
 //
 // 🩸 계기(2026-09-25 v0.1.0 첫 공개): 손으로 밟은 절차에서 둘을 빠뜨릴 뻔했다 — 공개본 git 커밋(판 커밋이 공개본 커밋이 된다) ·
@@ -25,11 +27,12 @@ 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, claimItem, decodeClaimHistoryEntry, devVersion, listChecklist, ownerMatches, parseOwner, parityGap, removeItem, seedFromRoadmap, setItem, summarizeChecklist, type ChecklistStatus, type ChecklistDisposition, type ChecklistKind } from '../release-loop/checklist.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 * 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';
 import { placeCell, rebalance, seatMove, type PlacementPriority } from '../release-loop/placement.js';
+import { parseRubric, readRubricItems, rubricGrade, rubricScore } from '../release-loop/rubric.js';
 import { writeStdoutJson } from './stdout-json.js';
 import { CliUserError } from './cli-user-error.js';
 import { hqCliWriteAllowed, type HqDeps } from '../hq/hq.js';
@@ -37,8 +40,11 @@ import { fileLeaseStore } from '../hq/lease.js';
 import { isIsolatedLedgerWriteRoot } from '../hq/ledger-write-target.js';
 import { runUnattendedRelease, type UnattendedReleaseDeps } from '../../scripts/release-loop/unattended-release.js';
 import { cutReleaseBranch } from '../../scripts/release-loop/cut-branch.js';
+import { resumeReleaseRun } from '../../scripts/release-loop/resume-release.js';
+import type { PrereleaseKind } from '../../scripts/release-loop/release-version.js';
 import { releaseReadiness } from '../../scripts/release-loop/release-readiness.js';
 import { runReleaseIfReady } from './release-run-if-ready.js';
+import { formatPreflight, releasePreflight } from '../../scripts/release-loop/preflight.js';
 import { autoStartScheduledRelease, type AutoStartDeferral } from '../release-loop/auto-start.js';
 import { landingFreezeMessage, LandingFrozenError, readLandingFreeze } from '../release-loop/landing-freeze.js';
 
@@ -151,7 +157,7 @@ export async function prepareRelease(opts: PrepareOptions, run: Runner = default
     must(run('git', ['add', '-A'], publicDir), 'git add');
     must(run('git', ['-c', `user.name=${name}`, '-c', `user.email=${email}`, 'commit', '-q', '--allow-empty', '-m', `elanous ${tag}`], publicDir), 'git commit');
     const publicCommit = must(run('git', ['rev-parse', 'HEAD'], publicDir), 'git rev-parse');
-    log(`③ 공개 커밋 ${publicCommit.slice(0, 12)} (${publicRepo} main 위)`);
+    log(`③ 공개 커밋 ${publicCommit.slice(0, 12)} (${publicRepo} main 위${isPrerelease(opts.version) ? ` · 미리보기 — 공개 main 이 아니라 release/${opts.version} 가지 ⊕ 태그로 나간다` : ''})`);
 
     // ④ PWA 빌드 — ⛔ 빠뜨리면 «웹 화면 없는 판»(빌드 산출은 공개본에 안 실린다).
     symlinkSync(join(modulesRoot, 'node_modules'), join(publicDir, 'node_modules'), 'dir');
@@ -216,12 +222,17 @@ export function planPublish(m: ReleaseManifest, notesFile: string): PublishStep[
   //    🩸 2026-09-25 v0.1.1 드라이런: release-build 의 `files` 에는 SHA256SUMS 가 없어(체크섬 대상 목록이라) «자산 4» 로 올릴 뻔했다.
   const assets = [...new Set([...m.files.map((f) => f.name), 'SHA256SUMS'])];
   return [
-    { what: `공개 저장소 ${m.publicRepo} main 푸시(${m.publicCommit.slice(0, 12)})`, command: 'git', args: ['push', 'origin', 'HEAD:main'], cwd: m.publicDir },
+    // RELEASE-REHEARSAL-RC: a prerelease never moves public main — its export goes to release/<v> plus its tag (one atomic push).
+    m.prerelease
+      ? { what: `공개 저장소 ${m.publicRepo} release/${m.version} 가지 ⊕ 태그 ${m.tag} 푸시(${m.publicCommit.slice(0, 12)} · main 무접촉)`, command: 'git',
+        args: ['push', '--atomic', 'origin', `${m.publicCommit}:refs/heads/release/${m.version}`, `${m.publicCommit}:refs/tags/${m.tag}`], cwd: m.publicDir }
+      : { what: `공개 저장소 ${m.publicRepo} main 푸시(${m.publicCommit.slice(0, 12)})`, command: 'git', args: ['push', 'origin', 'HEAD:main'], cwd: m.publicDir },
     {
       what: `릴리스 ${m.tag}${m.prerelease ? ' (prerelease)' : ''} 생성 ⊕ 자산 ${assets.length}(${assets.join(' · ')})`,
       command: 'gh',
       args: ['release', 'create', m.tag, ...assets.map((name) => join(m.distDir, name)), '--repo', m.publicRepo, '--target', m.publicCommit,
-        '--title', `elanous ${m.tag}`, '--notes-file', notesFile, ...(m.prerelease ? ['--prerelease'] : [])],
+        // RELEASE-REHEARSAL-RC: a prerelease is never Latest — the one-line installer keeps serving the last stable release.
+        '--title', `elanous ${m.tag}${m.prerelease ? ' (pre-release)' : ''}`, '--notes-file', notesFile, ...(m.prerelease ? ['--prerelease', '--latest=false', '--verify-tag'] : [])],
       cwd: m.publicDir,
     },
   ];
@@ -660,6 +671,36 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
   };
   const withContext = (cmd: Command) => cmd.option('--version <v>', '판 또는 별칭').option('--json', '결과 JSON').option('--hq-override', '본부 임대 거부를 관측하며 수동 우회');
   const actor = () => process.env.ELANOUS_TRACK || 'cli';
+  withContext(checklist.command('rubric').description('루브릭 채점(읽기 전용)'))
+    .action(async (_opts: unknown, cmd: Command) => {
+      if (cmd.opts().version === undefined && cmd.parent?.opts().version === undefined) throw new CliUserError('조회할 판을 지정하라', '--version <v>');
+      const { version, json } = context(cmd);
+      const items = readRubricItems(version, releaseLedgerRoot());
+      const rows = items.flatMap((item) => {
+        const rubric = parseRubric(`${item.title}\n${item.evidence ?? ''}`);
+        if (!rubric) return [];
+        const score = rubricScore(rubric);
+        return [{ id: item.id, score, grade: rubricGrade(score), priority: item.priority ?? null }];
+      }).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+      const missing = items.length - rows.length;
+      if (json) { await writeStdoutJson(`${JSON.stringify({ version, rows, missing })}\n`); return; }
+      console.log('id · 점수 · 등급 · 현재 우선순위');
+      for (const row of rows) console.log(`${row.id} · ${row.score} · ${row.grade} · ${row.priority ?? '-'}`);
+      console.log(`루브릭 없는 칸 ${missing}`);
+    });
+  withContext(checklist.command('refs <doc>').description('문서를 인용하는 칸 — 모든 판의 구현 현황(읽기 전용)'))
+    .action(async (doc: string, _opts: unknown, 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 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 });
+      if (json) { await writeStdoutJson(`${JSON.stringify({ doc, rows, byStatus })}\n`); return; }
+      console.log(renderRefsStatus(rows));
+      console.log(`칸 ${rows.length} · 🟢 ${byStatus.green} · 🟡 ${byStatus.yellow} · 🔴 ${byStatus.red} · ✅ ${byStatus.done}`);
+    });
   withContext(checklist.command('list').description('모든 칸')).option('--owner <owner>', '자리 또는 하위 자리로 거르기').action(async (opts: { owner?: string }, cmd: Command) => {
     const { version, codenames, json } = context(cmd);
     await checklistOutput(version, codenames, 'list', json, opts.owner);
@@ -742,10 +783,11 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
     .option('--ceo-minutes <minutes>', '대표 손 분량(분)').option('--ceo-date <date>', '대표 손 날짜 YYYY-MM-DD (없으면 판 착지일 KST)')
     .option('--accelerator', '가속 등급 — 다른 칸의 처리량을 올리는 칸(자율성·효율성·동시성). 생략하면 등급 없음')
     .option('--allow-duplicate-id', '다른 판에 같은 id 가 있어도 경고 후 추가')
-    .action((id: string, title: string, opts: { owner?: string; kind?: string; priority?: string; deadlineVersion?: string; predecessor?: string[]; ceoMinutes?: string; ceoDate?: string; accelerator?: boolean; allowDuplicateId?: boolean }, cmd: Command) => {
+    .option('--ref <path...>', '근거 문서 — 저장소 상대 경로[#절] (반복 가능)')
+    .action((id: string, title: string, opts: { ref?: string[]; owner?: string; kind?: string; priority?: string; deadlineVersion?: string; predecessor?: string[]; ceoMinutes?: string; ceoDate?: string; accelerator?: boolean; allowDuplicateId?: boolean }, cmd: Command) => {
     const { version, json } = context(cmd);
     if (!mayWrite(cmd)) return;
-    const data = addItem(version, { id, title, ...(opts.owner !== undefined ? { owner: opts.owner } : {}), ...(opts.kind !== undefined ? { kind: opts.kind as ChecklistKind } : {}), ...(opts.priority !== undefined ? { priority: opts.priority as PlacementPriority } : {}), ...(opts.deadlineVersion !== undefined ? { deadlineVersion: opts.deadlineVersion } : {}), ...(opts.predecessor !== undefined ? { predecessors: opts.predecessor } : {}), ...(opts.ceoMinutes !== undefined ? { ceoMinutes: ceoMinutes(opts.ceoMinutes) } : {}), ...(opts.ceoDate !== undefined ? { ceoDate: opts.ceoDate } : {}), ...(opts.accelerator ? { accelerator: true } : {}) }, { allowDuplicateId: opts.allowDuplicateId });
+    const data = addItem(version, { id, title, ...(opts.ref !== undefined ? { refs: opts.ref } : {}), ...(opts.owner !== undefined ? { owner: opts.owner } : {}), ...(opts.kind !== undefined ? { kind: opts.kind as ChecklistKind } : {}), ...(opts.priority !== undefined ? { priority: opts.priority as PlacementPriority } : {}), ...(opts.deadlineVersion !== undefined ? { deadlineVersion: opts.deadlineVersion } : {}), ...(opts.predecessor !== undefined ? { predecessors: opts.predecessor } : {}), ...(opts.ceoMinutes !== undefined ? { ceoMinutes: ceoMinutes(opts.ceoMinutes) } : {}), ...(opts.ceoDate !== undefined ? { ceoDate: opts.ceoDate } : {}), ...(opts.accelerator ? { accelerator: true } : {}) }, { allowDuplicateId: opts.allowDuplicateId });
     if (json) console.log(JSON.stringify(data)); else console.log(`✅ ${id} 추가`);
   });
   withContext(checklist.command('set <id>').description('칸 상태·근거·담당·처분 갱신'))
@@ -754,13 +796,14 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
     .option('--priority <priority>', 'P0|P1|P2').option('--deadline-version <v>', '마감 판').option('--predecessor <id...>', '선행 칸 id')
     .option('--ceo-minutes <minutes>', '대표 손 분량(분)').option('--ceo-date <date>', '대표 손 날짜 YYYY-MM-DD')
     .option('--accelerator', '가속 등급 부여').option('--no-accelerator', '가속 등급 해제(기본은 없음)')
-    .action((id: string, opts: { status?: string; evidence?: string; owner?: string; disposition?: string; kind?: string; priority?: string; deadlineVersion?: string; predecessor?: string[]; ceoMinutes?: string; ceoDate?: string; accelerator?: boolean }, cmd: Command) => {
+    .option('--ref <path...>', '근거 문서 더하기 — 저장소 상대 경로[#절] (반복 가능 · 중복 제거)')
+    .action((id: string, opts: { ref?: string[]; status?: string; evidence?: string; owner?: string; disposition?: string; kind?: string; priority?: string; deadlineVersion?: string; predecessor?: string[]; ceoMinutes?: string; ceoDate?: string; accelerator?: boolean }, cmd: Command) => {
       const { version, json } = context(cmd);
       if (opts.status !== undefined && !['green', 'yellow', 'red', 'done'].includes(opts.status)) throw new CliUserError(`잘못된 상태: ${opts.status}`, 'green|yellow|red|done');
       if (opts.disposition !== undefined && !['move', 'known-issue', 'block'].includes(opts.disposition)) throw new CliUserError(`잘못된 처분: ${opts.disposition}`, 'move|known-issue|block');
-      if (opts.status === undefined && opts.evidence === undefined && opts.owner === undefined && opts.disposition === undefined && opts.kind === undefined && opts.priority === undefined && opts.deadlineVersion === undefined && opts.predecessor === undefined && opts.ceoMinutes === undefined && opts.ceoDate === undefined && opts.accelerator === undefined) throw new CliUserError('갱신할 칸을 지정하라', '--status · --evidence · --owner · --disposition · --kind · --priority · --deadline-version · --predecessor · --ceo-minutes · --ceo-date · --accelerator · --no-accelerator 중 하나');
+      if (opts.status === undefined && opts.evidence === undefined && opts.owner === undefined && opts.disposition === undefined && opts.kind === undefined && opts.priority === undefined && opts.deadlineVersion === undefined && opts.predecessor === undefined && opts.ceoMinutes === undefined && opts.ceoDate === undefined && opts.accelerator === undefined && opts.ref === undefined) throw new CliUserError('갱신할 칸을 지정하라', '--ref · --status · --evidence · --owner · --disposition · --kind · --priority · --deadline-version · --predecessor · --ceo-minutes · --ceo-date · --accelerator · --no-accelerator 중 하나');
       if (!mayWrite(cmd)) return;
-      const data = setItem(version, id, { ...(opts.status !== undefined ? { status: opts.status as ChecklistStatus } : {}), ...(opts.evidence !== undefined ? { evidence: opts.evidence } : {}), ...(opts.owner !== undefined ? { owner: opts.owner } : {}), ...(opts.disposition !== undefined ? { disposition: opts.disposition as ChecklistDisposition } : {}), ...(opts.kind !== undefined ? { kind: opts.kind as ChecklistKind } : {}), ...(opts.priority !== undefined ? { priority: opts.priority as PlacementPriority } : {}), ...(opts.deadlineVersion !== undefined ? { deadlineVersion: opts.deadlineVersion } : {}), ...(opts.predecessor !== undefined ? { predecessors: opts.predecessor } : {}), ...(opts.ceoMinutes !== undefined ? { ceoMinutes: ceoMinutes(opts.ceoMinutes) } : {}), ...(opts.ceoDate !== undefined ? { ceoDate: opts.ceoDate } : {}), ...(opts.accelerator !== undefined ? { accelerator: opts.accelerator ? true : null } : {}) }, process.env.ELANOUS_TRACK || 'cli');
+      const data = setItem(version, id, { ...(opts.ref !== undefined ? { refs: opts.ref } : {}), ...(opts.status !== undefined ? { status: opts.status as ChecklistStatus } : {}), ...(opts.evidence !== undefined ? { evidence: opts.evidence } : {}), ...(opts.owner !== undefined ? { owner: opts.owner } : {}), ...(opts.disposition !== undefined ? { disposition: opts.disposition as ChecklistDisposition } : {}), ...(opts.kind !== undefined ? { kind: opts.kind as ChecklistKind } : {}), ...(opts.priority !== undefined ? { priority: opts.priority as PlacementPriority } : {}), ...(opts.deadlineVersion !== undefined ? { deadlineVersion: opts.deadlineVersion } : {}), ...(opts.predecessor !== undefined ? { predecessors: opts.predecessor } : {}), ...(opts.ceoMinutes !== undefined ? { ceoMinutes: ceoMinutes(opts.ceoMinutes) } : {}), ...(opts.ceoDate !== undefined ? { ceoDate: opts.ceoDate } : {}), ...(opts.accelerator !== undefined ? { accelerator: opts.accelerator ? true : null } : {}) }, process.env.ELANOUS_TRACK || 'cli');
       const item = data.items.find((entry) => entry.id === id);
       const why = item?.kind === 'screen' && item.status === 'green' ? parityGap(item.evidence) : null;
       if (why) {
@@ -909,7 +952,16 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
     .action(async (o: { version: string; base: string; pick: string[]; append?: boolean; dryRun?: boolean; json?: boolean }) => {
       await jsonAction(o.json, async (log) => cutReleaseBranch({ ...o, log }), () => true);
     });
-  const runAction = async (o: { version: string; cutCommit?: string; dryRun?: boolean; ifReady?: boolean; forceFreeze?: boolean; json?: boolean }, logRun = console.log): Promise<boolean | AutoStartDeferral | undefined> => {
+  const runAction = async (o: { version: string; cutCommit?: string; mainCut?: boolean; prerelease?: string; dryRun?: boolean; ifReady?: boolean; forceFreeze?: boolean; json?: boolean }, logRun = console.log): Promise<boolean | AutoStartDeferral | undefined> => {
+      // Only the rc rehearsal channel is operated for now (alpha/beta stay valid version shapes, not run options).
+      if (o.prerelease !== undefined && o.prerelease !== 'rc') {
+        const message = `--prerelease supports rc only: ${o.prerelease}`;
+        if (o.json) await writeStdoutJson(`${JSON.stringify({ ok: false, error: message })}\n`);
+        else console.error(`⛔ ${message}`);
+        process.exitCode = 1;
+        return false;
+      }
+      const prerelease = o.prerelease as PrereleaseKind | undefined;
       if (!o.dryRun) {
         try {
           const frozen = readLandingFreeze(releaseRunDeps.freezeRoot);
@@ -935,12 +987,13 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
           return false;
         }
       }
-      if (o.ifReady && !o.dryRun) {
+      // A prerelease rehearsal never reads the stable version's readiness (checklist cells): it runs directly.
+      if (o.ifReady && !o.dryRun && !prerelease) {
         try {
           const outcome = await runReleaseIfReady(o.version, {
             ledgerRoot: releaseRunDeps.ledgerRoot,
             readiness: (version, options) => releaseReadiness(version, { ledgerRoot: releaseRunDeps.ledgerRoot, checklist: releaseRunDeps.checklist, ...options }),
-            run: () => runUnattendedRelease({ version: o.version, cutCommit: o.cutCommit, forceFreeze: o.forceFreeze }, releaseRunDeps),
+            run: () => runUnattendedRelease({ version: o.version, cutCommit: o.cutCommit, mainCut: o.mainCut, prerelease, forceFreeze: o.forceFreeze }, releaseRunDeps),
           });
           if (outcome.skipped) {
             if (o.json) await writeStdoutJson(`${JSON.stringify(outcome)}\n`);
@@ -968,7 +1021,7 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
         }
       }
       await jsonAction(o.json, async (log) => {
-        const result = await runUnattendedRelease({ version: o.version, dryRun: o.dryRun, cutCommit: o.cutCommit, forceFreeze: o.forceFreeze }, releaseRunDeps);
+        const result = await runUnattendedRelease({ version: o.version, dryRun: o.dryRun, cutCommit: o.cutCommit, mainCut: o.mainCut, prerelease, forceFreeze: o.forceFreeze }, releaseRunDeps);
         log(`${result.dryRun ? '· 드라이런' : '▶ 릴리스 루프'} ${result.input.version} · 입력 ${JSON.stringify(result.input)}`);
         return result;
       }, (r) => r.dryRun || r.state?.status === 'done' || r.state?.status === 'awaiting-approval');
@@ -976,12 +1029,43 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
   release.command('run')
     .description('릴리스 루프 실행 — 원장 직전 판과 release.loop 설정으로 그래프 입력 구성 · --dry-run 은 입력만 출력')
     .requiredOption('--version <v>', '공개할 판(x.y.z)')
-    .option('--cut-commit <sha>', 'origin/main HEAD 대신 컷으로 쓸 커밋')
+    .option('--cut-commit <sha>', 'origin/main HEAD 대신 컷으로 쓸 커밋(이미 자른 release/<v> 끝 — 옛 경로)')
+    .option('--main-cut', '옛 경로: 판 올림을 main 에 착지(기본은 release/<v> 가지에만 올린다)')
+    .option('--prerelease <kind>', '미리보기 판(rc) — <v>-rc.<다음 빈 번호> · npm next · GitHub pre-release · docs-land/ops-upgrade/dev-bump 건너뜀')
     .option('--dry-run', '체크리스트·그래프 실행 없이 전체 입력 보기')
     .option('--if-ready', '준비되지 않았으면 사유를 출력하고 성공으로 건너뛴다')
-    .option('--force-freeze', '동결 중 게이트·발행 강행(관측 기록)')
+    .option('--force-freeze', '동결 중 게이트·발행 강행(관측 기록) — 가지 컷은 동결이 필요 없다 · 동결은 비상 스위치로 남는다')
     .option('--json', '결과 한 줄 JSON(stdout) · 사람 줄은 stderr')
-    .action(async (o: { version: string; cutCommit?: string; dryRun?: boolean; ifReady?: boolean; forceFreeze?: boolean; json?: boolean }) => { await runAction(o); });
+    .action(async (o: { version: string; cutCommit?: string; mainCut?: boolean; prerelease?: string; dryRun?: boolean; ifReady?: boolean; forceFreeze?: boolean; json?: boolean }) => { await runAction(o); });
+  release.command('preflight')
+    .description('컷 30분 전 사전 점검(읽기 전용) — 체크리스트 게이트 모의 · 발행 뒤 칸 · run --dry-run 입력 · 동결 · 일정/게이트 실측. ⛔ 있으면 exit 1')
+    .requiredOption('--version <v>', '점검할 판(x.y.z)')
+    .option('--publish-at <iso>', '계획 발행 시각(기본: 컷 뒤 첫 07·18시 KST)')
+    .option('--json', '결과 한 줄 JSON(stdout)')
+    .action(async (o: { version: string; publishAt?: string; json?: boolean }) => {
+      try {
+        const result = await releasePreflight(o.version, { publishAt: o.publishAt, releaseRunDeps });
+        if (o.json) await writeStdoutJson(`${JSON.stringify(result)}\n`);
+        else for (const line of formatPreflight(result)) console.log(line);
+        if (result.blockers > 0) process.exitCode = 1;
+      } catch (e) {
+        if (o.json) await writeStdoutJson(`${JSON.stringify({ ok: false, error: (e as Error).message })}\n`);
+        else console.error(`⛔ ${(e as Error).message}`);
+        process.exitCode = 1;
+      }
+    });
+  release.command('resume')
+    .description('실패한 릴리스 런을 이어 달린다 — cut-branch --append 로 고친 release/<v> 새 끝을 version-release 기록에 반영(빨리감기만·상태 백업) 뒤 --from 노드부터')
+    .requiredOption('--run <runId>', '실패한 release-loop 런 ID')
+    .requiredOption('--from <node>', '다시 시작할 노드(예: gate)')
+    .option('--json', '결과 한 줄 JSON(stdout)')
+    .action(async (o: { run: string; from: string; json?: boolean }) => {
+      await jsonAction(o.json, async (log) => {
+        const result = await resumeReleaseRun({ runId: o.run, from: o.from });
+        log(`${result.tip.changed ? `↻ ${result.tip.branch} ${result.tip.from.slice(0, 12)} → ${result.tip.to.slice(0, 12)} (백업 ${result.tip.backup})` : `· ${result.tip.branch} 끝 그대로 ${result.tip.to.slice(0, 12)}`} · ${o.from} 부터 → ${result.state.status}`);
+        return { tip: result.tip, status: result.state.status, runId: result.state.runId };
+      }, (r) => r.status === 'done' || r.status === 'awaiting-approval');
+    });
   release.command('auto-start')
     .description('판 일정의 컷 창에서 릴리스 시작을 미리 본다 · --apply 로 release run --if-ready 실행')
     .option('--window-minutes <n>', '컷 뒤 선택 창(분)', '15')

package/src/cli/tasks-cli.ts

@@ -1,9 +1,12 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import type { Command } from 'commander';
+import { InvalidArgumentError, Option, type Command } from 'commander';
+import { debug } from '../debug/log.js';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { readNexusRuntime } from '../nexus/runtime.js';
 import type { Task } from '../task-orchestrator/types.js';
+import { handTask, nextMoveFor, readTaskAgentState, readTaskCard, taskAgentStatePath as taskStatePathDefault, shellQuote, TASK_CARD_PREFIX, TASK_SEATS, type TaskCard, type TaskLauncher, type TaskSeat } from '../task-agent/task-hand.js';
+import { advanceMission, handMission, MissionAdvanceError, openMissionIds, recordPieceRef, type AdvanceMissionResult, type MissionDecompose, type PieceEvidenceReader } from '../task-agent/mission.js';
 
 type TaskRow = Pick<Task, 'id' | 'title' | 'priority' | 'status' | 'createdAt' | 'approval' | 'generatedBy'>;
 
@@ -12,6 +15,130 @@ export interface TasksCliDeps {
   bearerToken?: string;
   fetch?: typeof fetch;
   output?: (line: string) => void;
+  /** `task hand --live` 의 발사기(시험 주입). 기본은 운영 config-dir 로 `harness say` 를 떼어 띄운다. */
+  taskLauncher?: TaskLauncher;
+  /** 과제 카드 상태 파일(시험 주입). 기본 = `effectiveInstanceRoot()/task-agent-actions.json`. */
+  taskStatePath?: string;
+  /** logs.db 싱크 등록(시험 주입). 기본 = `registerStandaloneLogSink`. `hand`·`show` 가 부른다. */
+  registerSink?: (surface: string) => Promise<unknown>;
+  /** `task hand --mission` 의 분해기(시험 주입). 기본 = 나열형은 결정론 · 아니면 `decomposeSelfDevGoal`. */
+  missionDecompose?: MissionDecompose;
+  /** `task advance` 의 착지 근거 읽기(시험 주입). 기본 = `predecessorState`(gh · 런 원장). */
+  pieceEvidence?: PieceEvidenceReader;
+}
+
+/** `<조각id>=<값>` 반복 인자. */
+function collectPair(value: string, previous: Array<[string, string]> = []): Array<[string, string]> {
+  const at = value.indexOf('=');
+  if (at <= 0 || at === value.length - 1) throw new InvalidArgumentError(`<조각id>=<값> 모양이 아니다: ${value}`);
+  return [...previous, [value.slice(0, at), value.slice(at + 1)]];
+}
+
+function advanceLines(result: AdvanceMissionResult): string[] {
+  // 제안이 끝난 미션은 다시 조회하지 않는다 — «착지 0»으로 보이지 않게 따로 적는다.
+  if (result.green === 'already-proposed' && Object.keys(result.evidence).length === 0) return [`${result.missionId}\tadvance\t${result.mode}\tgreen already-proposed — 다시 조회·넘기지 않는다`];
+  return [
+    `${result.missionId}\tadvance\t${result.mode}\t착지 ${result.landed.length} · 준비 ${result.ready.length} · 넘김 ${result.handed.length} · green ${result.green}`,
+    ...Object.entries(result.evidence).map(([id, state]) => `  근거: ${id}\t${state}${result.landed.includes(id) ? '\t착지' : ''}`),
+    ...result.handed.map((piece) => `  넘김: ${piece.pieceId}\t${piece.launched ? 'launched' : piece.error ? 'failed' : 'not launched'}${piece.error ? `\t${piece.error}` : ''}`),
+    ...(result.green === 'proposed' ? ['  green 제안을 미션 카드에 적었다 — 체크리스트는 바꾸지 않는다(OP/주인이 뒤집는다)'] : []),
+  ];
+}
+
+/** `tasks hand`·`show` 가 남기는 `task-agent` 관측의 logs.db surface 라벨. */
+export const TASK_AGENT_SINK_SURFACE = 'task-agent';
+
+/**
+ * 독립 CLI 프로세스는 데몬의 logs.db 싱크를 상속하지 않는다 — 등록하지 않으면 `debug.log('task-agent', …)` 가
+ * 파일 트레일에만 남고 `elanous logs --category task-agent` 에 0건으로 보인다(10-06 실측: 카드 3장 · 이벤트 0).
+ * fail-open — 등록 실패가 과제 넘기기를 막지 않는다.
+ */
+export async function registerTaskAgentSink(register?: (surface: string) => Promise<unknown>): Promise<void> {
+  try {
+    const fn = register ?? (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink;
+    await fn(TASK_AGENT_SINK_SURFACE);
+  } catch { /* fail-open — 파일 트레일이 진실원 */ }
+}
+
+/**
+ * 기본 발사기 — 지금 도는 진입점으로 `--config-dir <운영 config>` 를 붙여 떼어 띄운다.
+ * config-dir 은 명시(`--config-dir`/`--test`)가 있으면 그것, 없으면 운영 루트(`prodInstanceRoot()`)다.
+ * (작업 트리에서 그냥 띄우면 test 우주로 가서 동결·몫·풀 상한 밖에서 돈다.)
+ */
+export async function defaultTaskLauncher(args: string[]): Promise<void> {
+  const { spawn } = await import('node:child_process');
+  const { getElanousConfigDirOverride } = await import('../elanous-config-dir.js');
+  const { prodInstanceRoot } = await import('../instance/resolve.js');
+  const configDir = getElanousConfigDirOverride() ?? prodInstanceRoot();
+  await spawnDetachedConfirmed(spawn as unknown as DetachedSpawn, process.execPath, [process.argv[1]!, '--config-dir', configDir, ...args]);
+}
+
+/** `spawn` 의 필요한 면만(시험 주입). */
+export type DetachedSpawn = (command: string, args: string[], options: { detached: true; stdio: 'ignore' }) => {
+  pid?: number;
+  once(event: 'spawn', listener: () => void): unknown;
+  once(event: 'error', listener: (error: Error) => void): unknown;
+  removeListener(event: string, listener: (...args: never[]) => void): unknown;
+  unref(): void;
+};
+
+/** 발사 확인 대기 상한 — 'spawn'·'error' 어느 쪽도 이 안에 안 오면 pid 유무로 판정한다. */
+export const SPAWN_CONFIRM_TIMEOUT_MS = 2_000;
+
+/**
+ * 떼어 띄우고 «떴는지» 확인한다 — 'spawn' 이면 성공, 'error'(ENOENT·EACCES 등)면 던진다.
+ * 확인 없이 돌려주면 비동기 error 가 처리되지 않고 카드가 `launched` 로 남는다(사후 리뷰 must-fix).
+ */
+export function spawnDetachedConfirmed(spawnFn: DetachedSpawn, command: string, args: string[], timeoutMs = SPAWN_CONFIRM_TIMEOUT_MS): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    let child: ReturnType<DetachedSpawn>;
+    try { child = spawnFn(command, args, { detached: true, stdio: 'ignore' }); } catch (error) { reject(error); return; }
+    let settled = false;
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.removeListener('spawn', onSpawn);
+      // error 리스너는 남겨 둔다 — 확인 뒤 늦게 오는 error 도 처리되지 않은 예외가 되지 않게.
+      if (error) { reject(error); return; }
+      child.unref();
+      resolve();
+    };
+    const onSpawn = () => finish();
+    const onError = (error: Error) => finish(error);
+    child.once('spawn', onSpawn);
+    child.once('error', onError);
+    const timer = setTimeout(() => finish(child.pid ? undefined : new Error(`발사 확인 시간 초과(${timeoutMs}ms) · pid 없음`)), timeoutMs);
+  });
+}
+
+function moveLine(card: TaskCard): string {
+  const move = nextMoveFor(card);
+  return `${move.kind}${move.command ? ` — elanous ${move.command.map(shellQuote).join(' ')}` : ''} (${move.reason})`;
+}
+
+function headLine(text: string): string {
+  const first = text.split('\n')[0]!.trim();
+  return first.length > 100 ? `${first.slice(0, 100)}…` : first;
+}
+
+function taskCardLines(card: TaskCard): string[] {
+  return [
+    [card.id, card.status, card.seat ?? '-', card.checklistId ?? '-', card.createdAt, card.text].join('\t'),
+    ...(card.mission ? [`미션: ${card.mission} · after: ${card.after?.length ? card.after.join(', ') : '-'}`] : []),
+    `다음 수: ${moveLine(card)}`,
+  ];
+}
+
+/** 미션 카드 — 머리 한 줄 ⊕ 조각 한 줄씩(상태·다음 수·선행) ⊕ 간선 한 줄씩. */
+function missionLines(mission: TaskCard, pieces: TaskCard[]): string[] {
+  const edges = pieces.flatMap((piece) => (piece.after ?? []).map((before) => `간선: ${before} -> ${piece.id}`));
+  return [
+    [mission.id, 'mission', mission.seat ?? '-', mission.checklistId ?? '-', mission.createdAt, `조각 ${pieces.length} · 간선 ${edges.length} · 출처 ${mission.splitSource ?? '-'}`, headLine(mission.text)].join('\t'),
+    ...pieces.map((piece) => [`조각: ${piece.id}`, piece.status, nextMoveFor(piece).kind, `after: ${piece.after?.length ? piece.after.join(',') : '-'}`, headLine(piece.text)].join('\t')),
+    ...edges,
+    ...(mission.greenProposal ? [`green 제안: ${mission.greenProposal.at} · 칸 ${mission.greenProposal.checklistId ?? '-'} · 근거 ${Object.entries(mission.greenProposal.evidence).map(([id, ref]) => `${id}=${ref}`).join(', ')}`] : []),
+  ];
 }
 
 const PRIORITY_RANK: Record<Task['priority'], number> = { urgent: 0, high: 1, medium: 2, low: 3 };
@@ -89,7 +216,7 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
     if (!auth) throw new NexusUnavailable();
     return auth;
   };
-  const tasks = program.command('tasks').alias('task').description('TOX 태스크 조회 및 승인');
+  const tasks = program.command('tasks').alias('task').description('TOX 태스크 조회 및 승인 · TASK-AGENT 과제 넘기기(hand)');
 
   tasks.command('list')
     .description('우선순위와 생성 시각 순으로 태스크 보기')
@@ -124,10 +251,189 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
       } catch (error) { handleError(error, out); }
     });
 
+  tasks.command('hand [text]')
+    .description('TASK-AGENT 에 과제 한 줄을 넘긴다 — 카드를 적고 첫 수(harness say --substrate pod --merge-by-host)를 고른다 · 기본 shadow(발사 0) · `--mission` 이면 조각 카드 ⊕ 선후로 쪼개 선행 없는 조각만 넘긴다')
+    .addOption(new Option('--seat <seat>', `과제 자리 (${TASK_SEATS.join('|')})`).choices([...TASK_SEATS]))
+    .option('--checklist <cellId>', '릴리스 체크리스트 칸 id')
+    .option('--mission <text>', '미션 문면 — 조각(`- …`·`① …`·`1. …` ⊕ `after: 1`)으로 나열돼 있으면 결정론, 아니면 분해기로 쪼갠다')
+    .option('--live', '실제로 발사한다(기본은 shadow — 명령만 출력)')
+    .option('--json', 'JSON 출력')
+    .action(async (text: string | undefined, opts: { seat?: TaskSeat; checklist?: string; mission?: string; live?: boolean; json?: boolean }) => {
+      await registerTaskAgentSink(deps.registerSink);
+      if ((text === undefined) === (opts.mission === undefined)) {
+        out('과제 한 줄 «또는» --mission <문면> 중 하나만 준다');
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.mission !== undefined) {
+        try {
+          const result = await handMission({
+            text: opts.mission,
+            ...(opts.seat ? { seat: opts.seat } : {}),
+            ...(opts.checklist ? { checklistId: opts.checklist } : {}),
+            live: opts.live === true,
+            ...(deps.taskStatePath ? { statePath: deps.taskStatePath } : {}),
+            launcher: deps.taskLauncher ?? defaultTaskLauncher,
+            ...(deps.missionDecompose ? { decompose: deps.missionDecompose } : {}),
+          });
+          if (opts.json) out(JSON.stringify(result));
+          else {
+            out(`${result.mission.id}\tmission\t${result.mode}\t조각 ${result.pieces.length} · 간선 ${result.edges.length} · 출처 ${result.source}`);
+            for (const piece of result.pieces) {
+              out([piece.card.id, piece.launched ? 'launched' : piece.error ? 'failed' : 'not launched', `${piece.move.kind} (${piece.move.reason})`, headLine(piece.card.text)].join('\t'));
+              if (piece.move.command) out(`  elanous ${piece.move.command.map(shellQuote).join(' ')}`);
+              if (piece.error) out(`  ${piece.error}`);
+            }
+            for (const [before, after] of result.edges) out(`간선: ${before} -> ${after}`);
+            if (result.mode === 'shadow') out('(shadow — 띄우지 않았다 · 띄우려면 --live)');
+          }
+          if (result.pieces.some((piece) => piece.error)) process.exitCode = 1;
+        } catch (error) {
+          out(error instanceof Error ? error.message : '미션 넘기기 실패');
+          process.exitCode = 1;
+        }
+        return;
+      }
+      try {
+        const result = await handTask({
+          text: text!,
+          ...(opts.seat ? { seat: opts.seat } : {}),
+          ...(opts.checklist ? { checklistId: opts.checklist } : {}),
+          live: opts.live === true,
+          ...(deps.taskStatePath ? { statePath: deps.taskStatePath } : {}),
+          launcher: deps.taskLauncher ?? defaultTaskLauncher,
+        });
+        if (opts.json) out(JSON.stringify(result));
+        else {
+          out(`${result.card.id}\t${result.mode}\t${result.launched ? 'launched' : 'not launched'}`);
+          out(`elanous ${result.move.command!.map(shellQuote).join(' ')}`);
+          if (!result.launched) out('(shadow — 띄우지 않았다 · 띄우려면 --live)');
+        }
+      } catch (error) {
+        out(error instanceof Error ? error.message : '과제 넘기기 실패');
+        process.exitCode = 1;
+      }
+    });
+
+  tasks.command('advance [missionId]')
+    .description('TASK-AGENT 미션 ② — 조각의 PR 병합(근거: `--pr`/`--goal` 로 카드에 적은 PR 번호·골 id)으로 착지를 가르고 새로 준비된 조각만 한 번 넘긴다 · 모두 착지면 green «제안»만 적는다 · 기본 shadow(발사 0)')
+    .option('--all', 'green 제안이 아직 없는 미션 전부')
+    .option('--pr <pieceId=N>', '조각 카드에 그 런의 PR 번호를 적는다(반복 가능)', collectPair)
+    .option('--goal <pieceId=goalId>', '조각 카드에 골 id(16자)를 적는다 — 런 원장 pr-opened 로 PR 을 찾는다(반복 가능)', collectPair)
+    .option('--live', '준비된 조각을 실제로 발사한다(기본은 shadow)')
+    .option('--json', 'JSON 출력')
+    .action(async (missionId: string | undefined, opts: { all?: boolean; pr?: Array<[string, string]>; goal?: Array<[string, string]>; live?: boolean; json?: boolean }) => {
+      await registerTaskAgentSink(deps.registerSink);
+      const started = Date.now();
+      if ((missionId === undefined) === (opts.all !== true)) {
+        const reason = '미션 id «또는» --all 중 하나만 준다';
+        try { debug.log('task-agent', 'mission-advance', { missionId: missionId ?? null, all: opts.all === true, mode: opts.live ? 'live' : 'shadow', stage: 'cli-args', error: reason, ms: Date.now() - started }); } catch { /* fail-soft */ }
+        out(reason);
+        process.exitCode = 1;
+        return;
+      }
+      const statePath = deps.taskStatePath;
+      try {
+        // 근거 인자는 운영자 입력이다 — 모양을 «먼저» 전부 검사해 하나라도 틀리면 아무것도 적지 않고 진행도 안 한다.
+        const refs: Array<[string, { pr: number } | { goalId: string }]> = [
+          ...(opts.pr ?? []).map(([pieceId, value]): [string, { pr: number }] => {
+            if (!/^#?[1-9]\d*$/.test(value)) throw new Error(`PR 번호가 아니다: ${value}`);
+            return [pieceId, { pr: Number(value.replace(/^#/, '')) }];
+          }),
+          ...(opts.goal ?? []).map(([pieceId, value]): [string, { goalId: string }] => {
+            if (!/^[a-f0-9]{16}$/.test(value)) throw new Error(`골 id 는 16자 hex 다: ${value}`);
+            return [pieceId, { goalId: value }];
+          }),
+        ];
+        const twice = refs.map(([pieceId]) => pieceId).filter((pieceId, at, all) => all.indexOf(pieceId) !== at);
+        if (twice.length) throw new Error(`한 조각에 근거를 두 번 줬다(--pr·--goal 은 조각마다 하나): ${[...new Set(twice)].join(', ')}`);
+        // 기록 실패(없는 조각 · 제안된 미션)는 그 근거만 실패로 적고 계속 — `--all` 의 나머지 미션을 막지 않는다.
+        const refFailures: string[] = [];
+        for (const [pieceId, ref] of refs) {
+          try { recordPieceRef(pieceId, ref, statePath, missionId); } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            if (missionId !== undefined) throw error;
+            refFailures.push(reason);
+          }
+        }
+        const ids = missionId !== undefined ? [missionId] : openMissionIds(statePath);
+        const results: AdvanceMissionResult[] = [];
+        const failures: Array<{ missionId: string; error: string }> = [];
+        for (const id of ids) {
+          try {
+            results.push(await advanceMission(id, {
+              live: opts.live === true,
+              ...(statePath ? { statePath } : {}),
+              launcher: deps.taskLauncher ?? defaultTaskLauncher,
+              ...(deps.pieceEvidence ? { readEvidence: deps.pieceEvidence } : {}),
+            }));
+          } catch (error) {
+            // 미션 id 하나면 그대로 실패 · --all 이면 그 미션만 실패로 적고 다음 미션으로 간다(크론이 한 미션에 막히지 않게).
+            if (missionId !== undefined) throw error;
+            failures.push({ missionId: id, error: error instanceof Error ? error.message : String(error) });
+          }
+        }
+        if (missionId === undefined) {
+          // --all 은 호출마다 요약 한 줄 — 대상 0·근거 기록 실패뿐인 호출도 관측에 남는다(미션별 줄은 advanceMission 이 남긴다).
+          try { debug.log('task-agent', 'mission-advance', { missionId: null, all: true, mode: opts.live ? 'live' : 'shadow', stage: 'all-summary', missions: ids.length, advanced: results.length, failures: failures.map((failure) => failure.missionId), refFailures: refFailures.length, ms: Date.now() - started }); } catch { /* fail-soft */ }
+        }
+        if (opts.json) out(JSON.stringify(missionId !== undefined ? results[0] : failures.length || refFailures.length ? { results, failures, refFailures } : results));
+        else {
+          if (results.length === 0 && failures.length === 0) out('넘길 미션이 없다 (green 제안 전 미션 0)');
+          for (const failure of failures) out(`${failure.missionId}\tadvance\tfailed\t${failure.error}`);
+          for (const reason of refFailures) out(`근거 기록 실패: ${reason}`);
+          for (const result of results) for (const line of advanceLines(result)) out(line);
+          if (!opts.live && results.some((result) => result.handed.length > 0)) out('(shadow — 띄우지 않았다 · 띄우려면 --live)');
+        }
+        if (failures.length || refFailures.length || results.some((result) => result.handed.some((piece) => piece.error))) process.exitCode = 1;
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : '미션 진행 실패';
+        // advanceMission 에 닿기 전(근거 인자 검사·기록)에 멈춘 호출도 한 줄 — 관측이 «호출마다» 남는다.
+        // advanceMission 안에서 던진 것은 거기서 이미 남겼다(같은 오류를 두 번 적지 않는다).
+        if (!(error instanceof MissionAdvanceError)) {
+          try { debug.log('task-agent', 'mission-advance', { missionId: missionId ?? null, all: opts.all === true, mode: opts.live ? 'live' : 'shadow', stage: 'cli-args', error: reason, ms: Date.now() - started }); } catch { /* fail-soft */ }
+        }
+        out(reason);
+        process.exitCode = 1;
+      }
+    });
+
   tasks.command('show <id>')
-    .description('태스크 상세 보기')
+    .description(`태스크 상세 보기 (id 가 \`${TASK_CARD_PREFIX}\` 로 시작하면 TASK-AGENT 과제 카드 ⊕ 다음 수)`)
     .option('--json', 'JSON 출력')
     .action(async (id: string, opts: { json?: boolean }) => {
+      if (id.startsWith(TASK_CARD_PREFIX)) {
+        await registerTaskAgentSink(deps.registerSink);
+        let card: TaskCard | undefined;
+        try { card = readTaskCard(id, deps.taskStatePath); } catch (error) {
+          out(error instanceof Error ? error.message : '과제 카드 읽기 실패');
+          process.exitCode = 1;
+          return;
+        }
+        if (!card) { out(`과제 카드 없음: ${id}`); process.exitCode = 1; return; }
+        if (card.pieces) {
+          let all: Record<string, TaskCard>;
+          try { all = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(deps.taskStatePath ?? taskStatePathDefault()).tasks ?? {}; } catch (error) {
+            out(error instanceof Error ? error.message : '과제 카드 읽기 실패');
+            process.exitCode = 1;
+            return;
+          }
+          const pieces = card.pieces.map((pieceId) => all[pieceId]).filter((piece): piece is TaskCard => piece !== undefined);
+          const missingPieces = card.pieces.filter((pieceId) => !all[pieceId]);
+          if (opts.json) {
+            out(JSON.stringify({ card, nextMove: nextMoveFor(card), pieces: pieces.map((piece) => ({ card: piece, nextMove: nextMoveFor(piece) })), missingPieces }));
+            if (missingPieces.length) process.exitCode = 1;
+          }
+          else {
+            for (const line of missionLines(card, pieces)) out(line);
+            for (const missing of missingPieces) { out(`조각 카드 없음: ${missing} — 선후 기록이 불완전하다`); process.exitCode = 1; }
+          }
+          return;
+        }
+        if (opts.json) out(JSON.stringify({ card, nextMove: nextMoveFor(card) }));
+        else for (const line of taskCardLines(card)) out(line);
+        return;
+      }
       try {
         activeToken = undefined;
         const auth = authenticate();