elanous 0.2.35 → 0.2.36

package/src/pty-shell/tui-run-state.ts

@@ -17,14 +17,14 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { debug } from '../debug/log.js';
-import { createHerdrAgentReporter, type HerdrAgentReporterLike } from './herdr-agent-report.js';
+import { createHerdrAgentReporter, guardHerdrReleaseOnSignal, type HerdrAgentReporterLike, type HerdrSignalTarget } from './herdr-agent-report.js';
 import { runGitCommand } from '../git-fs/runner.js';
 import { codeRevision, packageVersion, readInstallMetadataCommit } from '../version/code-revision.js';
 import {
   buildStaleInstallRelaunchCommand,
   formatStaleInstallNotice,
   versionedDashboardInstallDir,
-} from '../dashboard/stale-install-check.js';
+} from './stale-install-check.js';
 import {
   updatePtyManifestBuild, updatePtyManifestTurn,
   type PtyBuildIdentity, type PtyManifestRow, type PtyTurnState,
@@ -321,6 +321,11 @@ export interface TuiRunStateRecorderDeps {
    * `null` 이면 신고하지 않는다.
    */
   readonly herdr?: HerdrAgentReporterLike | null;
+  /**
+   * SIGINT·SIGTERM 기본 죽음에도 herdr 를 반납하는 신호 지킴이의 대상(TUI-HERDR-EXIT-RACE).
+   * 생략 시: 기본 신고기(herdr 미주입)일 때만 실 `process` · 주입 herdr 는 지킴이 0. `null` 이면 안 건다.
+   */
+  readonly signals?: HerdrSignalTarget | null;
 }
 
 interface ActiveRecorder {
@@ -361,7 +366,14 @@ export function startTuiRunStateRecorder(surfaceId: string, deps: TuiRunStateRec
   active = recorder;
   writeTurnState(recorder, 'idle');
   if (herdr) { try { herdr.start(); } catch { /* 신고 실패가 녹음기를 깨지 않는다 */ } }
+  // raw 모드 전 ctrl+c(SIGINT 기본 죽음)는 'exit' 훅을 안 돌린다 — 신호에서도 반납한다.
+  const signals = deps.signals !== undefined ? deps.signals : (deps.herdr === undefined ? process : null);
+  let unguard: () => void = () => {};
+  if (herdr && signals) {
+    try { unguard = guardHerdrReleaseOnSignal(() => herdr.release(), signals); } catch { /* 지킴이 실패가 녹음기를 깨지 않는다 */ }
+  }
   return () => {
+    try { unguard(); } catch { /* 종료 경로를 깨지 않는다 */ }
     if (herdr) { try { herdr.release(); } catch { /* 종료 경로를 깨지 않는다 */ } }
     if (active === recorder) active = null;
   };

package/src/release-loop/auto-start.ts

@@ -21,9 +21,13 @@ export type AutoStartDeferral = { deferred: true; reason: Exclude<ReleaseReadine
 export type AutoStartResult =
   | { status: 'no-cut' }
   | { status: 'planned'; version: string; cutAt: string }
-  | { status: 'skipped'; version: string; reason: AutoStartDeferral['reason'] }
+  | { status: 'skipped'; version: string; reason: Exclude<AutoStartDeferral['reason'], 'already-running'> }
+  /** A live run of the selected version is a refusal (rc1), not a quiet deferral — the reason names that run. */
+  | { status: 'already-running'; version: string; runId: string; pid: number; startedAt: string }
   | { status: 'started'; version: string; cutAt: string; publishAt?: string };
 
+export interface AutoStartActiveRun { runId: string; pid: number; startedAt: string }
+
 export interface AutoStartOptions {
   windowMinutes: number;
   apply?: boolean;
@@ -31,6 +35,8 @@ export interface AutoStartOptions {
   ledgerRoot?: string;
   schedules?: (root: string) => ReleaseSchedule[];
   readiness?: (version: string, ledgerRoot: string, now: Date) => ReleaseReadiness;
+  /** The live run of `version` (graph-run ledger · force marker · run.lock), asked before readiness on `--apply`. */
+  activeRun?: (version: string, ledgerRoot: string) => AutoStartActiveRun | undefined;
   launch?: (version: string, launchOptions?: { publishAt?: string }) => void | AutoStartDeferral | Promise<void | AutoStartDeferral>;
 }
 
@@ -43,11 +49,23 @@ export async function autoStartScheduledRelease(options: AutoStartOptions): Prom
   if (!schedule) return { status: 'no-cut' };
   const { version, cutAt, publishAt } = schedule;
   if (!options.apply) return { status: 'planned', version, cutAt };
+  const refuse = (run: AutoStartActiveRun): AutoStartResult => {
+    debug.log('release.schedule', 'auto-start-already-running', { version, cutAt, ...run });
+    return { status: 'already-running', version, ...run };
+  };
+  const active = options.activeRun?.(version, root);
+  if (active) return refuse(active);
   const readiness = (options.readiness ?? ((v, ledgerRoot, at) => releaseReadiness(v, { ledgerRoot, now: () => at })))(version, root, now);
+  // A live run.lock without a resolvable run identity still refuses; its pid is the readiness detail.
+  if (!readiness.ready && readiness.reason === 'already-running') return refuse({ runId: 'pending', pid: Number(readiness.details), startedAt: 'unknown' });
   if (!readiness.ready) return { status: 'skipped', version, reason: readiness.reason };
   if (!options.launch) throw new Error('auto-start apply requires a launch callback');
   const launched = await options.launch(version, publishAt != null ? { publishAt: publishAt } : {});
-  if (launched?.deferred) return { status: 'skipped', version, reason: launched.reason };
+  if (launched?.deferred) {
+    const { reason } = launched;
+    if (reason === 'already-running') return refuse(options.activeRun?.(version, root) ?? { runId: 'pending', pid: 0, startedAt: 'unknown' });
+    return { status: 'skipped', version, reason };
+  }
   debug.log('release.schedule', 'auto-start', { version, cutAt, publishAt: publishAt ?? null });
   return { status: 'started', version, cutAt, ...(publishAt != null ? { publishAt: publishAt } : {}) };
 }

package/src/release-loop/checklist.ts

@@ -13,6 +13,15 @@ export type ChecklistKind = 'screen' | 'postpub';
 const CHECKLIST_KINDS: readonly ChecklistKind[] = ['screen', 'postpub'];
 export type ChecklistDispatchKind = 'code' | 'ops' | 'measure' | 'decision' | 'umbrella';
 const CHECKLIST_DISPATCH_KINDS: readonly ChecklistDispatchKind[] = ['code', 'ops', 'measure', 'decision', 'umbrella'];
+/** MUST 지정 — 이 칸이 지켜야 하는 조건과 그 효과. 원장에는 `must` 이벤트(전체 값)로만 실린다. */
+export interface ChecklistMust {
+  version: string;
+  reason: string;
+  setBy: string;
+  setAt: string;
+  effect: string;
+}
+const MUST_FIELDS = ['version', 'reason', 'setBy', 'setAt', 'effect'] as const;
 export interface ChecklistItem {
   id: string;
   title: string;
@@ -32,6 +41,8 @@ export interface ChecklistItem {
   kind?: ChecklistKind;
   /** Whether the seat dispatcher should launch a coding task. Missing in old rows means code. */
   dispatchKind?: ChecklistDispatchKind;
+  /** MUST 지정(있으면 이 칸은 MUST 다). 원장 스키마에 must 컬럼이 없어 `must` 이벤트에서 복원한다. */
+  must?: ChecklistMust;
   updatedAt: string;
   updatedBy: string;
 }
@@ -92,13 +103,51 @@ function decodeClaimHistory(data: Checklist): Checklist {
   return { ...data, history: data.history.map(decodeClaimHistoryEntry) };
 }
 
+/** A `must` event carries the whole MUST value in `to`; anything that is not five strings is not a MUST. */
+function mustValue(value: unknown): ChecklistMust | null {
+  if (!value || typeof value !== 'object') return null;
+  const record = value as Record<string, unknown>;
+  if (!MUST_FIELDS.every((field) => typeof record[field] === 'string')) return null;
+  return { version: record.version as string, reason: record.reason as string, setBy: record.setBy as string, setAt: record.setAt as string, effect: record.effect as string };
+}
+
+function decodeMustEntry<T extends ChecklistHistory>(entry: T): T {
+  if (entry.field !== 'must') return entry;
+  const must = mustValue(entry.to);
+  return must ? { ...entry, to: must } as T : entry;
+}
+
+/** The ledger event schema has no must column either; the last `must` event is this cell's MUST. */
+function decodeMustHistory(data: Checklist): Checklist {
+  const latest = new Map<string, ChecklistMust>();
+  for (const entry of data.history) {
+    if (entry.field !== 'must') continue;
+    const must = mustValue(entry.to);
+    if (must) latest.set(entry.id, must);
+  }
+  if (!latest.size) return data;
+  return { ...data, items: data.items.map((item) => {
+    const must = latest.get(item.id);
+    return must ? { ...item, must } : item;
+  }) };
+}
+
+function latestMust(history: readonly ChecklistHistory[], id: string): ChecklistMust | null {
+  for (let index = history.length - 1; index >= 0; index--) {
+    const entry = history[index]!;
+    if (entry.id !== id || entry.field !== 'must') continue;
+    return mustValue(entry.to);
+  }
+  return null;
+}
+
 export function listChecklist(v: string, root?: string): Checklist {
-  return decodeClaimHistory(root === undefined ? store.list(v) : store.list(v, undefined, undefined, root));
+  return decodeMustHistory(decodeClaimHistory(root === undefined ? store.list(v) : store.list(v, undefined, undefined, root)));
 }
 
 /** Events for this id across every release, ordered by event time (then ledger sequence). */
 export function checklistHistory(id: string): Array<ChecklistHistory & { version: string; seq: number }> {
-  return store.history(id).map(decodeClaimHistoryEntry);
+  return store.history(id).map((entry) => decodeMustEntry(decodeClaimHistoryEntry(entry)));
 }
 
 /** Status events in the requested window; other ledger fields never become status changes. */
@@ -116,8 +165,8 @@ function assertPredecessorsExist(predecessors: readonly string[] | undefined, da
 }
 
 function mutate(v: string, apply: (data: Checklist, otherItems: (id: string) => store.ChecklistCollision[]) => boolean): Checklist {
-  // addItem/setItem/claimItem/removeItem/seedFromRoadmap reach the generation-fenced ledger write here.
-  return decodeClaimHistory(store.mutate(v, store.releasedVersion(), devVersion(), apply));
+  // addItem/setItem/claimItem/removeItem/seedFromRoadmap/setMust reach the generation-fenced ledger write here.
+  return decodeMustHistory(decodeClaimHistory(store.mutate(v, store.releasedVersion(), devVersion(), apply)));
 }
 
 function change(data: Checklist, id: string, field: string, from: unknown, to: unknown, by: string, at: string): void {
@@ -360,6 +409,29 @@ export function setItem(v: string, id: string, patch: { status?: ChecklistStatus
   return setItemGuarded(v, id, patch, by);
 }
 
+/** 효과 없는 MUST 는 게이트가 판단할 근거가 없다 — 거부한다. */
+function validateMust(must: ChecklistMust): ChecklistMust {
+  if (!must.effect.trim()) throw new CliUserError('MUST 효과가 비었다', "release checklist must <id> --effect '<게이트에 미치는 효과>'");
+  return must;
+}
+
+/** 이 칸의 MUST 를 세운다. 저장은 `must` 이벤트(from = 이전 전체 값, to = 새 전체 값)로만 하고, 다른 칸 행은 건드리지 않는다. */
+export function setMust(v: string, id: string, input: { version: string; reason: string; effect: string }, by: string): Checklist {
+  if (!by.trim()) throw new CliUserError('MUST 기록 주체가 비었다');
+  const at = new Date().toISOString();
+  const must = validateMust({ version: input.version, reason: input.reason, setBy: by, setAt: at, effect: input.effect });
+  return mutate(v, (data) => {
+    const item = data.items.find((entry) => entry.id === id);
+    if (!item) throw new CliUserError(`없는 칸: ${id}`, 'list 로 칸 목록을 본다');
+    const previous = latestMust(data.history, id);
+    if (previous && JSON.stringify(previous) === JSON.stringify(must)) return false;
+    item.updatedAt = at;
+    item.updatedBy = by;
+    change(data, id, 'must', previous, must, by, at);
+    return true;
+  });
+}
+
 /** Remove only the exact machine-authored line; preserve all other evidence bytes and blank lines. */
 export function withoutDispatchSkipLine(evidence: string, line: string | null): string {
   if (!line) return evidence;

package/src/release-loop/rehearsal.ts

@@ -186,26 +186,23 @@ export function runRehearsalLeakCheck(checkout: string): { status: number | null
   } finally { rmSync(out, { recursive: true, force: true }); }
 }
 
-/** The hard rehearsal uses the release gate itself, pinned to the fetched main SHA and node-b Pod member. */
-async function runHardGate(version: string, checkout: string, sha: string, ledgerRoot: string, runId: string): Promise<HardGateResult> {
-  const configuredPool = releaseLoopConfig().gatePodPool;
-  if (!configuredPool) throw new Error('hard rehearsal requires release.loop.gatePodPool');
-  const members = parsePodPool(configuredPool);
-  const gateMember = members.find(member => member.sshHost === 'node-b');
-  if (!gateMember) throw new Error('hard rehearsal requires a live node-b Pod member');
-  const pool = configuredPool.split(',').map(part => part.trim())
-    .find(part => part.split(/[#:]/, 1)[0] === `${gateMember.context}@${gateMember.sshHost}`);
-  if (!pool) throw new Error('hard rehearsal cannot isolate the node-b Pod member');
-  const previous = latestPublishedPreviousVersion(version, ledgerRoot);
-  const logPath = join(ledgerRoot, 'release', version, 'rehearsal', `${runId}.log`);
-  mkdirSync(dirname(logPath), { recursive: true });
-  const run = (() => {
-    const log = openSync(logPath, 'wx', 0o600);
-    try { return spawnSync('bun', hardRehearsalGateArgs(version, runId, sha, previous, pool), {
-      cwd: checkout, encoding: 'utf8', stdio: ['ignore', log, log], timeout: 4 * 60 * 60_000,
-      env: { ...process.env, ELANOUS_STATE_DIR: ledgerRoot, ELANOUS_STATE_DIR_SOURCE: stateDirSourceForChild(ledgerRoot) },
-    }); } finally { closeSync(log); }
-  })();
+/** Run the exact hard-gate subprocess with an isolated clock budget for timeout replay. */
+export function spawnHardRehearsalGate(opts: {
+  binary: string; args: string[]; checkout: string; ledgerRoot: string; logPath: string; timeoutMs: number; sha: string;
+}): HardGateResult {
+  mkdirSync(dirname(opts.logPath), { recursive: true });
+  const log = openSync(opts.logPath, 'wx', 0o600);
+  let run: ReturnType<typeof spawnSync>;
+  try {
+    run = spawnSync(opts.binary, opts.args, {
+      cwd: opts.checkout, encoding: 'utf8', stdio: ['ignore', log, log], timeout: opts.timeoutMs,
+      env: { ...process.env, ELANOUS_STATE_DIR: opts.ledgerRoot, ELANOUS_STATE_DIR_SOURCE: stateDirSourceForChild(opts.ledgerRoot) },
+    });
+  } finally { closeSync(log); }
+  return parseHardRehearsalGateResult(run, opts.logPath, opts.sha);
+}
+
+function parseHardRehearsalGateResult(run: ReturnType<typeof spawnSync>, logPath: string, sha: string): HardGateResult {
   // stdout and stderr stream to the claim's durable evidence while the child is still running.
   const output = readFileSync(logPath, 'utf8');
   const line = output.split(/\r?\n/).reverse().find(value => value.trim().startsWith('{'));
@@ -225,6 +222,25 @@ async function runHardGate(version: string, checkout: string, sha: string, ledge
   throw new Error(`hard rehearsal gate rc=${run.status ?? 'spawn'} disagrees with outcome=${result.outcome}`);
 }
 
+/** The hard rehearsal uses the release gate itself, pinned to the fetched main SHA and node-b Pod member. */
+async function runHardGate(version: string, checkout: string, sha: string, ledgerRoot: string, runId: string): Promise<HardGateResult> {
+  const configuredPool = releaseLoopConfig().gatePodPool;
+  if (!configuredPool) throw new Error('hard rehearsal requires release.loop.gatePodPool');
+  const members = parsePodPool(configuredPool);
+  const gateMember = members.find(member => member.sshHost === 'node-b');
+  if (!gateMember) throw new Error('hard rehearsal requires a live node-b Pod member');
+  const pool = configuredPool.split(',').map(part => part.trim())
+    .find(part => part.split(/[#:]/, 1)[0] === `${gateMember.context}@${gateMember.sshHost}`);
+  if (!pool) throw new Error('hard rehearsal cannot isolate the node-b Pod member');
+  const previous = latestPublishedPreviousVersion(version, ledgerRoot);
+  const logPath = join(ledgerRoot, 'release', version, 'rehearsal', `${runId}.log`);
+  mkdirSync(dirname(logPath), { recursive: true });
+  return spawnHardRehearsalGate({
+    binary: 'bun', args: hardRehearsalGateArgs(version, runId, sha, previous, pool),
+    checkout, ledgerRoot, logPath, timeoutMs: 4 * 60 * 60_000, sha,
+  });
+}
+
 function oneLine(text: string): string { return text.replace(/\s+/g, ' ').trim(); }
 
 function outcomeLine(stamp: RehearsalStamp): string {

package/src/repl/index.ts

@@ -50,6 +50,7 @@ import { parse as parseYaml } from 'yaml';
 import type { PendingTaskNotification } from '../agent/task-notification.js';
 import { dispatchReplMessageTool, isReplMessageTool } from './ops-msg-bridge.js';
 import { buildSeatBootSystemMessages, type SeatBootDeps } from '../dashboard/seat-boot-preamble.js';
+import { installNextTuiSelfHealthTracker } from '../tui/chat/self-health-status.js';
 
 /** Private side channel for the next TUI. Ordinary REPL JSONL stdout is unchanged. */
 const NEXT_TUI_BG_PREFIX = 'ELANOUS_TUI_BG_STATUS\t';
@@ -189,6 +190,14 @@ function buildReplTools(): {
   const bashMod = require('../skills/tools/index.js') as typeof import('../skills/tools/index.js');
   specs.push(bashMod.buildBashTool());
   dispatchByName.set('Bash', async (args) => bashMod.dispatchBash(args, { cwd: process.cwd() }));
+  // TUI-NEXT-QUEUE-AND-WAKE: the next TUI parent opens an IPC hop only for its own REPL children;
+  // the classic ScheduleWakeup spec is advertised and each call is answered by the parent's scheduler.
+  const wakeMod = require('../tui-client/next-wakeup.js') as typeof import('../tui-client/next-wakeup.js');
+  const wakeup = wakeMod.createReplWakeupTool(process as unknown as import('../tui-client/next-wakeup.js').WakeupIpcProcess);
+  if (wakeup) {
+    specs.push(wakeup.spec);
+    dispatchByName.set(wakeup.spec.name, wakeup.dispatch);
+  }
   const planner = sr.createSearchPlannerState({ maxAutoNarrowCandidates: 2 });
   const dispatch = async (name: string, args: Record<string, unknown>): Promise<unknown> => {
     try {
@@ -594,6 +603,8 @@ export async function runRepl(opts: ReplOpts): Promise<number> {
     } catch { /* suggestions must not interrupt the REPL */ }
   }
   const sessionIdRef = { current: session.id };
+  const selfHealthTracker = installNextTuiSelfHealthTracker();
+  selfHealthTracker?.setSessionId(session.id);
 
   const nextTuiDelivery = process.env.ELANOUS_NEXT_TUI_BG_STATUS === '1'
     ? { pending: [] as PendingTaskNotification[] } : undefined;
@@ -747,6 +758,11 @@ export async function runRepl(opts: ReplOpts): Promise<number> {
         if (att) turnAttachments.push(att);
       }
       backgroundBridge?.beginTurn();
+      const selfHealth = selfHealthTracker?.snapshot(sessionIdRef.current) ?? null;
+      if (selfHealth && typeof turn.id === 'string') {
+        process.stdout.write(`${JSON.stringify({ event: 'self-health', turnId: turn.id, sessionId: sessionIdRef.current, selfHealth })}\n`);
+      }
+      const turnSystemPrompt = selfHealth ? `${systemPrompt}\n\n${selfHealth.line}` : systemPrompt;
       let result: Awaited<ReturnType<typeof runOneTurn>>;
       try {
         result = await runOneTurn(
@@ -755,7 +771,7 @@ export async function runRepl(opts: ReplOpts): Promise<number> {
           turn.prompt,
           turnAttachments,
           tools,
-          systemPrompt,
+          turnSystemPrompt,
           true, // JSONL stream → always JSON output
           nextTuiDelivery,
           process.env.ELANOUS_NEXT_TUI_STREAM === '1' && typeof turn.id === 'string'
@@ -779,10 +795,12 @@ export async function runRepl(opts: ReplOpts): Promise<number> {
         durationMs: result.durationMs,
         logPath: result.logPath,
         assertFailures: failures,
+        selfHealth,
       };
       console.log(JSON.stringify(out));
     }
     backgroundBridge?.dispose();
+    selfHealthTracker?.dispose();
     return 0;
   }
 

package/src/seat-loop/knowhow-lint.ts

@@ -139,7 +139,7 @@ interface KnowhowCard {
 }
 
 /** 카드 제목 — `## K-<자리>-<번호>` 뒤에는 줄 끝·공백·콜론·em 대시만 온다. */
-const CARD_HEADING = /^[ \t]{0,3}##\s+(K-[A-Za-z]+-\d+)(?=$|\s|:|—)/u;
+const CARD_HEADING = /^[ \t]{0,3}##\s+(K-[A-Za-z]+(?:-[A-Za-z]{1,4})?-\d+)(?=$|\s|:|—)/u;
 /** 카드처럼 보이는 `##` 제목(예: `## K-OP-7a`) — CARD_HEADING 을 벗어나면 인식 실패로 명시 거부한다. */
 const CARD_HEADING_LIKE = /^[ \t]{0,3}##\s*(K-[^\s:]*)/iu;
 

package/src/self-dev/decompose-proposal.ts

@@ -84,6 +84,49 @@ function hotPathOverlapsOf(pieces: readonly DecomposePiece[]): HotPathOverlap[]
   return pairs;
 }
 
+/** 분해 제안 문서를 «읽은» 결과. ⛔ 혼합 문서를 조각 문서로 «다시 매기지» 않는다. */
+export type DecomposeDocument =
+  | { kind: 'pieces'; pieces: DecomposePiece[] }
+  /** 단계꼴(`step`/문자열)과 조각꼴(`feature`)이 «섞인» 문서. 조용히 다시 매기지 않고 거부한다. */
+  | { kind: 'rejected'; reason: 'mixed-document'; stepEntries: number; pieceEntries: number }
+  /** 읽을 조각이 «하나도» 없다 — 빈 문서와 거부를 같은 값으로 접지 않는다. */
+  | { kind: 'empty' };
+
+/**
+ * 분해 제안 문서(원장 `data.pieces`)를 조각 목록으로 읽는다.
+ *
+ * ⛔⭐ **혼합 문서를 «다시 매기지» 않는다** — 단계꼴 항목(`{ step }`·맨 문자열)은 `feature` 가 없어
+ *   지금까지 «조용히» 버려졌고, 남은 조각 id 가 `String(pieces.length)` 로 **재번호**됐다.
+ *   그 재번호가 `shadow → live` 선행 간선을 «매달린» 것으로 바꿔, shadow 관측 없이 live 가 나갔다.
+ *   ⇒ 단계꼴이 «하나라도» 섞여 있으면 문서 전체를 거부하고 두 수를 값으로 남긴다(처방이 다르다).
+ */
+export function readDecomposeDocument(raw: unknown): DecomposeDocument {
+  if (!Array.isArray(raw) || raw.length === 0) return { kind: 'empty' };
+  const pieces: DecomposePiece[] = [];
+  let stepEntries = 0;
+  for (const entry of raw) {
+    if (typeof entry === 'string') { stepEntries++; continue; }
+    if (!entry || typeof entry !== 'object') continue;
+    const piece = entry as {
+      id?: unknown; feature?: unknown; dependsOn?: unknown; goalType?: unknown; hotPaths?: unknown; step?: unknown;
+    };
+    if (typeof piece.step === 'string' && piece.step.trim()) stepEntries++;
+    if (typeof piece.feature !== 'string' || !piece.feature.trim()) continue;
+    pieces.push({
+      id: typeof piece.id === 'string' && piece.id ? piece.id : String(pieces.length),
+      feature: piece.feature,
+      dependsOn: Array.isArray(piece.dependsOn) ? piece.dependsOn.filter((d): d is string => typeof d === 'string') : [],
+      ...(typeof piece.goalType === 'string' ? { goalType: piece.goalType } : {}),
+      ...(Array.isArray(piece.hotPaths) ? { hotPaths: piece.hotPaths.filter((path): path is string => typeof path === 'string') } : {}),
+    });
+  }
+  if (pieces.length === 0) return { kind: 'empty' };
+  if (stepEntries > 0) {
+    return { kind: 'rejected', reason: 'mixed-document', stepEntries, pieceEntries: pieces.length };
+  }
+  return { kind: 'pieces', pieces };
+}
+
 /** 원장 엔트리들에서 조각별 «가장 늦은» 분해 제안을 뽑는다. 형제 겹침이 있으면 hot-path-overlap 관측을 낸다(fail-open). */
 export function pickDecomposeProposals(entries: readonly Ledgerish[]): Map<string, DecomposeProposal> {
   const out = new Map<string, DecomposeProposal>();
@@ -94,20 +137,20 @@ export function pickDecomposeProposals(entries: readonly Ledgerish[]): Map<strin
       : typeof entry.runId === 'string' && entry.runId.trim() ? entry.runId : null;
     if (!shardId) continue;   // ⛔ 어느 조각인지도 어느 런인지도 모르는 제안은 «쓸 수 없다» — 조용히 아무 데나 붙이지 않는다
     const data = entry.data as { pieces?: unknown; round?: unknown } | undefined;
-    const raw = Array.isArray(data?.pieces) ? data!.pieces : null;
-    if (!raw?.length) continue;
-    const pieces: DecomposePiece[] = [];
-    for (const p of raw) {
-      const piece = p as { id?: unknown; feature?: unknown; dependsOn?: unknown; goalType?: unknown; hotPaths?: unknown };
-      if (typeof piece?.feature !== 'string' || !piece.feature.trim()) continue;
-      pieces.push({
-        id: typeof piece.id === 'string' && piece.id ? piece.id : String(pieces.length),
-        feature: piece.feature,
-        dependsOn: Array.isArray(piece.dependsOn) ? piece.dependsOn.filter((d): d is string => typeof d === 'string') : [],
-        ...(typeof piece.goalType === 'string' ? { goalType: piece.goalType } : {}),
-        ...(Array.isArray(piece.hotPaths) ? { hotPaths: piece.hotPaths.filter((path): path is string => typeof path === 'string') } : {}),
-      });
+    const document = readDecomposeDocument(data?.pieces);
+    if (document.kind === 'empty') continue;
+    // ⛔ 혼합 문서는 «뽑지 않는다» — 다시 매기면 shadow→live 선행 간선이 매달린 것이 된다.
+    if (document.kind === 'rejected') {
+      try {
+        debug.log('self-dev.decompose', 'mixed-decompose-document', {
+          shardId,
+          stepEntries: document.stepEntries,
+          pieceEntries: document.pieceEntries,
+        });
+      } catch { /* fail-open */ }
+      continue;
     }
+    const pieces = document.pieces;
     // ⛔ 조각이 «하나»면 분해가 아니다 — 같은 골을 이름만 바꿔 다시 거는 셈이다.
     if (pieces.length < 2) continue;
     const round = typeof data?.round === 'number' ? data.round : undefined;
@@ -158,8 +201,9 @@ export interface DecomposePieceOrdering {
  *   겹침은 직렬화하지 않고 `DecomposeProposal.hotPathOverlaps` 로 형제 겹침으로 따로 남는다.
  *   덕분에 ⓐ 와 배열 위치가 반대 방향을 가리켜 가짜 순환을 만들던 충돌 자체가 사라졌다.
  *
- * ⛔ 매달린 `dependsOn`(조각 목록에 없는 id)은 «버리고 센다» — 그것 때문에 승격 전체를 막지 않는다
- *   (연합 경로의 `pruneDanglingDependencies` 와 같은 판단).
+ * ⛔ 매달린 `dependsOn`(조각 목록에 없는 id)은 «버리고 센다» — 이 순서 계산기는 승격을 막지 않는다
+ *   (연합 경로의 `pruneDanglingDependencies` 와 같은 판단). 승격 «입구»는 다르다 —
+ *   `planShadowFirstDispatch` 가 매달린 간선을 «거부»한다(shadow 선행 간선이 사라진 채 live 가 나가는 것을 막는다).
  *
  * 순수 함수다 — 시계·파일·프로세스를 안 만진다. 동률은 «원래 순서»로 깬다(같은 입력 → 같은 출력).
  */
@@ -217,6 +261,73 @@ export function orderPiecesTopologically(pieces: readonly DecomposePiece[]): Dec
   return { ordered, dependsOnEdges, hotPathEdges: 0, danglingDependsOn };
 }
 
+/** shadow 조각의 id — 관측만 하는 조각. ⛔ 이름은 하니스 산출이 canonical 이다. */
+export const SHADOW_PIECE_ID = 'shadow';
+
+/** shadow-first 집행 계획의 관측 값 — 무엇이 관측이고 어디에 선행 간선이 걸렸나. */
+export interface ShadowFirstPlan {
+  shadowId: string;
+  /** shadow 뒤에 서는 «live» 조각 id — 제안 순서 그대로다. */
+  liveIds: string[];
+  /** 원 제안이 잃고 있어 «되살린» shadow 선행 간선 수. 0 이면 제안이 이미 shadow-first 였다. */
+  restoredEdges: number;
+}
+
+/** shadow-first 집행 판정. ⛔ 「고칠 수 없음」과 「거부」를 같은 값으로 접지 않는다. */
+export type ShadowFirstDispatch =
+  | { kind: 'ok'; pieces: DecomposePiece[]; shadowFirst?: ShadowFirstPlan }
+  | { kind: 'rejected'; reason: 'dangling-dependsOn'; danglingIds: string[] };
+
+/**
+ * ⭐⭐⭐ shadow 관측이 live 발사보다 «앞선다» — AUTHOR-SHADOW-FIRST-SPLIT ② (#26884 수확).
+ *
+ * 🔑 ***실패 뒤 분해 제안에서 관측이 «사라지고» live 만 나갔다.*** shadow 조각은
+ *   `dependsOn` 없이 제안에 실리고, live 조각이 그 선행 간선을 «잃은» 채 오면 위상 정렬이
+ *   둘을 «동시에» 세운다 ⇒ 관측 없이 live 발사가 먼저 도착한다.
+ *
+ * ⛔ 판정은 «둘»로 가른다 — 접으면 다음 사람이 못 고친다:
+ *   ⓐ 매달린 `dependsOn`(조각 목록에 없는 id) → `kind: 'rejected'`, 사유와 없는 id 를 값으로 남긴다.
+ *     없는 조각을 선행으로 단 제안은 승격하지 않는다(`danglingDependsOn` 을 세는 것만으로는 live 발사를 못 막는다).
+ *   ⓑ shadow 조각이 «둘» 이상 → `kind: 'ok'` 지만 «가드 없음» — 어느 쪽이 관측인지 모르는 제안은 고치지 않는다.
+ *
+ * ⭐ 선행 간선은 «실제 발사 지점»(다른 조각이 의존하지 않는 끝 조각)에만 건다 — 중간 조각은
+ *   자기 선행 순서만 들고 있으면 되고, 그 것까지 shadow 에 매달면 계획이 사슬로 납작해진다.
+ *   shadow 조각은 언제나 맨 앞으로 올라오고, 이미 shadow 를 선행으로 가진 조각은 건드리지 않는다.
+ *
+ * 순수 함수다 — 시계·파일·프로세스를 안 만진다. 입력 조각은 «변형하지 않는다».
+ */
+export function planShadowFirstDispatch(pieces: readonly DecomposePiece[]): ShadowFirstDispatch {
+  const known = new Set(pieces.map((piece) => piece.id));
+  const danglingIds: string[] = [];
+  for (const piece of pieces) {
+    for (const dep of piece.dependsOn) {
+      if (dep === piece.id || known.has(dep) || danglingIds.includes(dep)) continue;
+      danglingIds.push(dep);
+    }
+  }
+  if (danglingIds.length) return { kind: 'rejected', reason: 'dangling-dependsOn', danglingIds };
+
+  const shadowPieces = pieces.filter((piece) => piece.id === SHADOW_PIECE_ID);
+  if (shadowPieces.length !== 1) return { kind: 'ok', pieces: [...pieces] };
+
+  const shadow = shadowPieces[0]!;
+  const rest = pieces.filter((piece) => piece !== shadow);
+  const dependedUpon = new Set<string>();
+  for (const piece of rest) for (const dep of piece.dependsOn) dependedUpon.add(dep);
+
+  let restoredEdges = 0;
+  const reordered = rest.map((piece) => {
+    if (dependedUpon.has(piece.id) || piece.dependsOn.includes(SHADOW_PIECE_ID)) return piece;
+    restoredEdges++;
+    return { ...piece, dependsOn: [...piece.dependsOn, SHADOW_PIECE_ID] };
+  });
+  return {
+    kind: 'ok',
+    pieces: [shadow, ...reordered],
+    shadowFirst: { shadowId: shadow.id, liveIds: rest.map((piece) => piece.id), restoredEdges },
+  };
+}
+
 export interface DecomposeProposalScan {
   proposals: Map<string, DecomposeProposal>;
   goalPlanRevisions: Map<string, GoalPlanRevisionReadObservation>;
@@ -343,11 +454,21 @@ export function readDecomposeProposals(input: {
   };
 }
 
+/** 승격하지 «않은» 제안 하나 — ⛔ 조용히 원본만 두면 다음 라운드가 같은 제안을 다시 쓴다. */
+export interface DecomposeRejection {
+  feature: string;
+  reason: 'dangling-dependsOn';
+  /** 무엇이 매달렸나 — 조각 목록에 없는 선행 id 들. */
+  detail: string[];
+}
+
 /** 조각 하나를 «쪼갠» 결과. ⛔ 「무엇을 무엇으로」가 값으로 남아야 다음 라운드가 중복하지 않는다. */
 export interface DecomposeApplication {
   goals: SelfDevGoal[];
   /** 이번에 쪼갠 원래 goal 의 feature 들. 비면 아무것도 안 바뀌었다. */
   decomposed: string[];
+  /** 거부한 제안들 — 사유와 매달린 id 를 «값»으로 남긴다. 거부가 없으면 빈 배열이다. */
+  rejected: DecomposeRejection[];
 }
 
 /**
@@ -358,10 +479,12 @@ export interface DecomposeApplication {
  *     self_orchestrate 는 shouldDefer=true 라 «찾아야» 보인다. 그래서 복합도 단일로 들어온다.
  *   ⇒ 📌 입구를 고치는 대신 ***「들어온 뒤 스스로 쪼개게」*** 한다.
  *
- * ⛔ **안전 장치 셋** — 다시 거는 것은 쉽고 «멈출 줄 아는 것»이 어렵다:
+ * ⛔ **안전 장치 넷** — 다시 거는 것은 쉽고 «멈출 줄 아는 것»이 어렵다:
  *   ⓐ 같은 goal 을 «두 번» 쪼개지 않는다(alreadyDecomposed)
  *   ⓑ 조각이 둘 미만인 제안은 애초에 안 온다(pickDecomposeProposals 가 거른다)
  *   ⓒ 상한을 넘기면 «쪼개지 않는다» — 조각이 무한히 불어나는 것을 막는다
+ *   ⓓ shadow 관측이 live 발사 «앞»에 선다(`planShadowFirstDispatch`) — 매달린 `dependsOn` 은
+ *     승격하지 않고 사유와 id 를 `rejected` 로 남긴다. 관측은 조각을 내보내기 «전»에 남는다.
  *
  * ⭐ **조각은 원 골의 «대상 경로:» 머리줄을 물려받는다** (DECOMPOSE-PIECE-TARGET-LINE · 10-11 부검 run-76941fca):
  *   조각 feature 가 골을 «통째로» 갈아 끼우면 첫 줄 선언이 사라져 Pod 예비 검사가 «대상 경로 0» →
@@ -402,22 +525,51 @@ export function applyDecomposeProposals(
     if (already.has(r.feature)) continue;
     byFeature.set(r.feature, pieces);
   }
-  if (byFeature.size === 0) return { goals: [...goals], decomposed: [] };
+  if (byFeature.size === 0) return { goals: [...goals], decomposed: [], rejected: [] };
 
   const out: SelfDevGoal[] = [];
   const decomposed: string[] = [];
+  const rejected: DecomposeRejection[] = [];
   for (const goal of goals) {
     const pieces = byFeature.get(goal.feature);
     if (!pieces) { out.push(goal); continue; }
+    // ⛔⭐ shadow-first 가드 — 매달린 선행 간선이 있는 제안은 «쪼개지 않는다»(원본을 그대로 둔다).
+    const plan = planShadowFirstDispatch(pieces);
+    if (plan.kind === 'rejected') {
+      rejected.push({ feature: goal.feature, reason: plan.reason, detail: [...plan.danglingIds] });
+      // ⛔⭐ 거부를 «로그와 값에 다» 남긴다 — 조용히 버리면 다음 라운드가 같은 제안을 다시 쓴다.
+      //   혼합 문서 거부(mixed-decompose-document)와 같은 관측 채널·같은 fail-open 규율이다.
+      try {
+        debug.log('self-dev.decompose', 'decompose-rejected', {
+          feature: goal.feature,
+          reason: plan.reason,
+          danglingIds: [...plan.danglingIds],
+        });
+      } catch { /* fail-open */ }
+      out.push(goal);
+      continue;
+    }
+    const planned = plan.pieces;
     // ⛔ 상한을 넘기면 «쪼개지 않는다» — 조용히 자르지 않고 원본을 그대로 둔다.
-    if (out.length + pieces.length + (goals.length - out.length - 1) > maxGoals) { out.push(goal); continue; }
+    if (out.length + planned.length + (goals.length - out.length - 1) > maxGoals) { out.push(goal); continue; }
     decomposed.push(goal.feature);
+    // ⭐ 관측이 live 발사보다 «앞»에 남는다 — 조각을 out 에 넣기 전에 이 자리에서 찍는다.
+    if (plan.shadowFirst) {
+      try {
+        debug.log('self-dev.decompose', 'shadow-first-dispatch', {
+          feature: goal.feature,
+          shadowId: plan.shadowFirst.shadowId,
+          liveIds: [...plan.shadowFirst.liveIds],
+          restoredEdges: plan.shadowFirst.restoredEdges,
+        });
+      } catch { /* fail-open */ }
+    }
     // 원 골의 머리줄 선언 — 첫 줄이 «대상 경로:» 가 아니면 조각은 지금 그대로(바이트 불변)다.
     const goalLines = goal.feature.split('\n');
     const targetLine = TARGET_PATHS_LINE.exec(goalLines[0] ?? '');
     // «신설:» 상속은 머리줄 선언이 «있을 때만» — 첫 줄이 라벨이 아니면 조각은 바이트 불변이어야 한다.
     const newLine = targetLine ? goalLines.map((line) => NEW_PATHS_LINE.exec(line)).find((m) => m !== null) : null;
-    for (const piece of pieces) {
+    for (const piece of planned) {
       const inherited: string[] = [];
       let paths: string[] = [];
       if (targetLine) {
@@ -444,5 +596,5 @@ export function applyDecomposeProposals(
       } as SelfDevGoal);
     }
   }
-  return { goals: out, decomposed };
+  return { goals: out, decomposed, rejected };
 }