elanous 0.2.27 → 0.2.29

package/src/self-health/signatures.ts

@@ -0,0 +1,132 @@
+// ── 실패 지문 사전 (L4 자기 인지 · TUI-FAILURE-SIGNATURES) ──
+//
+// 결함 기록(`seat-state/OPC/tui-op-issues.md`)을 «데이터»로 옮긴 것이다 — 증상 → 원인 → 처방.
+// 지문 ↔ 결함 번호 ↔ 칸 대응은 PR #27498 본문 표가 정본이다(여기 복제하지 않는다).
+// TUI 턴이 오류로 끝날 때 디버그 원문(영어 덤프) 대신 «무슨 일 → 다음 행동» 한국어 한 줄을 보이고,
+// 원문은 `/detail` 쪽으로 보낸다. 설계 정본 = `RFC-tui-self-awareness-and-continuity` L4.
+//
+// ⭐ 공용 모듈이다 — 화면 경로(plain-turn 오류) 말고도 가드 문구 현지화
+//    (UX `TUI-GUARD-NOTICE`)·자기 건강 한 줄(L3 `opc-self-health`)이 이 사전을 가져다 쓴다.
+//    ⛔ 지문 문면을 호출부에 복제하지 말고 여기 한 줄을 더한다.
+// 📋 관측: 지문이 맞으면 `debug.log('tui.failure-signature', 'matched', { id, surface })` 하나.
+//    `elanous logs --category tui.failure-signature` 로 지문별 빈도를 센다.
+
+import { debug } from '../debug/log.js';
+
+export interface FailureEventInput {
+  category: string;
+  event: string;
+  data?: Record<string, unknown>;
+}
+
+export interface FailureSignature {
+  /** 안정 id — 관측 이벤트·L3 집계의 키. ⛔ 바꾸면 집계가 끊긴다. */
+  readonly id: string;
+  /** 오류 문자열·응답 문면에서 이 지문을 알아보는 패턴(하나라도 맞으면). */
+  readonly text?: readonly RegExp[];
+  /** 로그 이벤트로 알아보는 패턴. */
+  readonly event?: {
+    readonly category: string;
+    readonly event: string;
+    readonly when?: (data: Record<string, unknown>) => boolean;
+  };
+  /** 무슨 일 — 한국어 한 줄. */
+  readonly cause: string;
+  /** 다음 행동 — 한국어 한 줄. */
+  readonly next: string;
+}
+
+/** 이벤트 루프 정지를 «지문»으로 볼 문턱 — 0.25s 표본은 잦아 소음이고, 결함 #1(14s)·#14(최대 2.35s)는 이 위다. */
+export const EVENT_LOOP_STALL_SIGNATURE_MS = 2_000;
+
+// ⚠️ 순서가 뜻이다 — 앞의 것이 먼저 맞는다. 원인 지문(400)을 결과 지문(공급자 소진) 앞에 둔다:
+//    소진 문면 안에 `Codex API 400` 이 시도 이력으로 들어 있으면 처방은 400 쪽이 맞다.
+export const FAILURE_SIGNATURES: readonly FailureSignature[] = [
+  {
+    id: 'codex-400-bad-request',
+    // 모델 API 오류 머리로만 — `storage API 400 Bad Request` 같은 무관한 400 은 옛 출력 그대로 둔다.
+    text: [/\b(?:Codex|LLM) API 400\b/],
+    cause: '모델 API 가 요청을 400 으로 거절(대화 기록 어긋남 의심)',
+    next: '/session new 뒤 짧게 다시 묻기',
+  },
+  {
+    id: 'provider-fallback-exhausted',
+    // 머리(`[LLM PROVIDER …]`)만으로는 안 맞춘다 — 소진이 아닌 STOPPED·BLOCKED 는 옛 출력 그대로 둔다.
+    text: [/\[LLM PROVIDER (?:BLOCKED|STOPPED)\] fallback candidates exhausted/],
+    cause: '응답이 끊겼고 대체 공급자도 못 씀',
+    next: '잠시 뒤 다시 보내기 · 되풀이되면 eln usage',
+  },
+  {
+    id: 'tool-budget-reached',
+    text: [/Tool budget reached/],
+    cause: '이 턴의 도구 호출 상한 소진(짧은 질문은 상한이 작다)',
+    next: '«자세히 조사해» 로 다시 묻기',
+  },
+  {
+    id: 'broad-search-loop',
+    text: [/RUNTIME BLOCKED\W+repeated broad search loop/],
+    cause: '넓은 탐색이 연달아 이어져 탐색 가드가 막음',
+    next: '파일 경로를 짚어 읽게 하기',
+  },
+  {
+    id: 'synthesis-ignored',
+    text: [/\[(?:SYNTHESIS|ACTION|EXECUTION) IGNORED\]/],
+    cause: '도구만 부르는 루프를 가드가 끊음(근거 부족)',
+    next: '파일 3~5개로 좁혀 다시 묻기',
+  },
+  {
+    id: 'event-loop-stall',
+    event: {
+      category: 'tui.event-loop',
+      event: 'stall',
+      when: (data) => typeof data.lagMs === 'number' && data.lagMs >= EVENT_LOOP_STALL_SIGNATURE_MS,
+    },
+    cause: '화면 루프가 2초 넘게 멈춤(TUI 안 무거운 동기 작업)',
+    next: 'eln logs --event stall 로 직전 작업 보기',
+  },
+  {
+    id: 'stale-build',
+    event: { category: 'tui.run-state', event: 'stale' },
+    cause: '이 TUI 는 옛 판으로 도는 중(설치본이 그 뒤 갱신)',
+    next: 'TUI 다시 띄우기',
+  },
+];
+
+/** 오류 문자열에 맞는 첫 지문. 순수 — 관측을 남기지 않는다.
+ *  ⚠️ «던져진 오류·로그 이벤트»용이다 — 모델이 쓴 응답·도구 결과(인용이 섞인다)에 대면 오탐한다(PR #27498 r1~r5). */
+export function matchFailureText(text: string): FailureSignature | null {
+  if (!text) return null;
+  for (const sig of FAILURE_SIGNATURES) {
+    if (sig.text?.some((re) => re.test(text))) return sig;
+  }
+  return null;
+}
+
+/** 로그 이벤트에 맞는 첫 지문. 순수. */
+export function matchFailureEvent(input: FailureEventInput): FailureSignature | null {
+  for (const sig of FAILURE_SIGNATURES) {
+    const ev = sig.event;
+    if (!ev || ev.category !== input.category || ev.event !== input.event) continue;
+    if (ev.when && !ev.when(input.data ?? {})) continue;
+    return sig;
+  }
+  return null;
+}
+
+/** «무슨 일 → 다음 행동» 한국어 한 줄. `rawHint` 는 원문을 볼 자리(예: `/detail open`).
+ *  ⚠️ 한 화면 줄(한글은 두 칸)에 들어가게 짧게 — 140칸 TUI 에서 처방이 잘리면(…+N) 한 줄의 뜻이 없다. */
+export function formatFailureNotice(sig: FailureSignature, opts: { rawHint?: string } = {}): string {
+  const raw = opts.rawHint ? ` · 원문 ${opts.rawHint}` : '';
+  return `⚠ ${sig.cause} → ${sig.next}${raw}`;
+}
+
+/** 지문이 맞았다는 관측 한 줄 — L3 자기 건강이 이 이벤트를 센다. 관측은 화면을 막지 않는다. */
+export function recordFailureSignatureMatch(
+  sig: FailureSignature,
+  surface: string,
+  log: (category: string, event: string, data: Record<string, unknown>) => void = (c, e, d) => debug.log(c, e, d),
+): void {
+  try {
+    log('tui.failure-signature', 'matched', { id: sig.id, surface });
+  } catch { /* fail-soft — 관측이 화면을 막지 않는다 */ }
+}

package/src/self-implement/doctor-visit.ts

@@ -0,0 +1,118 @@
+import { debug } from '../debug/log.js';
+import {
+  appendRunLedgerEntry,
+  listRunLedgers,
+  loadRunLedger,
+  lookupRunLedger,
+  type RunLedgerLookupOptions,
+} from './run-ledger.js';
+
+/** DOCTOR-VISIT 증상 닫힌 목록 — 이 밖의 값은 기록·조회 모두 거부한다. */
+export const DOCTOR_SYMPTOMS = [
+  'admit-starved',
+  'image-loop',
+  'no-progress',
+  'child-dead-no-result',
+  'stale-install',
+  'oom',
+  'slow-tool',
+  'host-overload',
+  'not-grounded',
+  'scope-drift',
+  'review-loop',
+  'knowledge-gap',
+  'too-big',
+] as const;
+
+export type DoctorSymptom = (typeof DOCTOR_SYMPTOMS)[number];
+
+/** 진료 요청을 보낸 쪽 닫힌 목록. */
+export const DOCTOR_VISIT_SOURCES = ['supervisor', 'parent', 'child', 'judge', 'seat'] as const;
+
+export type DoctorVisitSource = (typeof DOCTOR_VISIT_SOURCES)[number];
+
+const DOCTOR_SYMPTOM_SET: ReadonlySet<string> = new Set(DOCTOR_SYMPTOMS);
+const DOCTOR_VISIT_SOURCE_SET: ReadonlySet<string> = new Set(DOCTOR_VISIT_SOURCES);
+
+export function isDoctorSymptom(value: string): value is DoctorSymptom {
+  return DOCTOR_SYMPTOM_SET.has(value);
+}
+
+export function isDoctorVisitSource(value: string): value is DoctorVisitSource {
+  return DOCTOR_VISIT_SOURCE_SET.has(value);
+}
+
+export interface RecordDoctorVisitInput {
+  runId: string;
+  from: string;
+  symptom: string;
+  evidence?: string;
+  /** 원장 디렉터리(시험 seam) — 기본 = `runLedgerDir()`. */
+  dir?: string;
+}
+
+export interface DoctorVisit {
+  runId: string;
+  from: DoctorVisitSource;
+  symptom: DoctorSymptom;
+  evidence?: string;
+  timestamp?: string;
+}
+
+/**
+ * 런 원장에 진료 요청 한 줄(`event: 'doctor-visit'`)을 남긴다.
+ * 원장이 없는 runId 는 «없음»으로 거부한다 — 조용히 새 원장을 만들지 않는다.
+ */
+export function recordDoctorVisit(visit: RecordDoctorVisitInput): DoctorVisit {
+  if (!isDoctorSymptom(visit.symptom)) {
+    throw new Error(`unknown symptom: ${visit.symptom} — closed list: ${DOCTOR_SYMPTOMS.join(', ')}`);
+  }
+  if (!isDoctorVisitSource(visit.from)) {
+    throw new Error(`unknown from: ${visit.from} — closed list: ${DOCTOR_VISIT_SOURCES.join(', ')}`);
+  }
+  if (loadRunLedger(visit.runId, visit.dir) === null) {
+    throw new Error(`없음: 런 원장이 없습니다 (runId=${visit.runId}) — 새 원장을 만들지 않습니다`);
+  }
+  const timestamp = new Date().toISOString();
+  const data: Record<string, unknown> = { from: visit.from, symptom: visit.symptom };
+  if (typeof visit.evidence === 'string' && visit.evidence.length > 0) data.evidence = visit.evidence;
+  appendRunLedgerEntry({ timestamp, runId: visit.runId, event: 'doctor-visit', data }, visit.dir);
+  debug.log('run-doctor', 'visit', { runId: visit.runId, from: visit.from, symptom: visit.symptom });
+  return {
+    runId: visit.runId,
+    from: visit.from,
+    symptom: visit.symptom,
+    ...(typeof visit.evidence === 'string' && visit.evidence.length > 0 ? { evidence: visit.evidence } : {}),
+    timestamp,
+  };
+}
+
+export type ReadDoctorVisitsOptions = RunLedgerLookupOptions;
+
+/** `runId` 원장이 조회 범위 안에 있는가 — `doctor status --run` 이 없는 런을 «0건»으로 삼키지 않게 한다. */
+export function doctorVisitRunExists(runId: string, options: ReadDoctorVisitsOptions = {}): boolean {
+  return lookupRunLedger(runId, options).matches.length > 0;
+}
+
+/** 원장의 `doctor-visit` 사건을 읽는다. `runId` 를 주면 그 런만, 없으면 전체 원장을 훑는다. */
+export function readDoctorVisits(runId?: string, options: ReadDoctorVisitsOptions = {}): DoctorVisit[] {
+  const matches = runId === undefined ? listRunLedgers(options).matches : lookupRunLedger(runId, options).matches;
+  const visits: DoctorVisit[] = [];
+  for (const match of matches) {
+    for (const entry of match.entries) {
+      if (entry.event !== 'doctor-visit') continue;
+      const from = typeof entry.data.from === 'string' && isDoctorVisitSource(entry.data.from) ? entry.data.from : null;
+      const symptom = typeof entry.data.symptom === 'string' && isDoctorSymptom(entry.data.symptom) ? entry.data.symptom : null;
+      if (from === null || symptom === null) continue;
+      visits.push({
+        runId: entry.runId,
+        from,
+        symptom,
+        ...(typeof entry.data.evidence === 'string' && entry.data.evidence.length > 0 ? { evidence: entry.data.evidence } : {}),
+        ...(typeof entry.timestamp === 'string' ? { timestamp: entry.timestamp } : {}),
+      });
+    }
+  }
+  return visits.sort((left, right) =>
+    (left.timestamp ?? '').localeCompare(right.timestamp ?? '') || left.runId.localeCompare(right.runId));
+}

package/src/self-implement/gate-cli.ts

@@ -14,7 +14,7 @@ import { buildGateBaselineReport, calculateGateTestCountChange, formatGateBaseli
 import { resolveGateScope } from './gate-scope.js';
 import { publicExposureFiles, runExposeGate } from './expose-gate.js';
 import { getUserConfig } from '../user-config.js';
-import { debug } from '../debug/log.js';
+import { debug, redactSecretText } from '../debug/log.js';
 import { buildDocumentGuardianIndex, formatDocumentGuardians } from './document-guardian-index.js';
 import { buildImporterTestIndex, importerTestsNotInRunSet, isTestPath, type ImporterTestIndex } from './importer-test-index.js';
 import { buildRouteConsumerTestIndex } from './route-consumer-test-index.js';
@@ -426,6 +426,7 @@ function changedTestCountNote(
 
 const IMPORTER_GREP_PATHS = ['*.test.ts', '*.test.tsx', '*.test.mts', '*.test.mtsx', '*.test.cts', '*.test.ctsx', '*.test.js', '*.test.jsx', '*.test.mjs', '*.test.mjsx', '*.test.cjs', '*.test.cjsx'];
 const SOURCE_PATH_RE = /^src\/.+\.(?:[cm]?[jt]sx?)$/;
+const SCRIPT_SOURCE_PATH_RE = /^scripts\/.+\.(?:[cm]?[jt]sx?)$/;
 const SOURCE_FILE_RE = /\.(?:[cm]?[jt]sx?)$/;
 
 function buildGateImporterTestIndex(
@@ -433,7 +434,7 @@ function buildGateImporterTestIndex(
   cwd: string,
   runCommand: SelfGateCliDeps['runCommand'],
 ): ImporterTestIndex | null | { readonly lookupFailed: string } {
-  const sources = changed.filter((path) => SOURCE_PATH_RE.test(path) && !isTestPath(path));
+  const sources = changed.filter((path) => (SOURCE_PATH_RE.test(path) || SCRIPT_SOURCE_PATH_RE.test(path)) && !isTestPath(path));
   if (sources.length === 0) return null;
   const result = (runCommand ?? defaultRunCommand)('git', ['grep', '-l', '-e', '', '--', ...IMPORTER_GREP_PATHS], cwd);
   if ((result.status !== 0 && result.status !== 1) || result.error) {
@@ -596,7 +597,10 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   if (options.shards !== undefined && (!Number.isSafeInteger(options.shards) || options.shards < 1)) throw new Error('invalid --shards count');
   const selection = (deps.changedFiles ?? ((dir, input) => defaultChangedFiles(dir, input, deps.runCommand)))(cwd, options);
   const exists = deps.exists ?? ((path) => existsSync(`${cwd}/${path}`));
-  const importerIndex = buildGateImporterTestIndex(selection.files, cwd, deps.runCommand);
+  // Caller: src/release-loop/light-rc.ts runLightRc → runSelfGateCli(dir, { ..., includeImporterTests: true }).
+  // scripts/ joins the existing importer index only for that opt-in path.
+  const importerIndex = buildGateImporterTestIndex(options.includeImporterTests
+    ? selection.files : selection.files.filter((path) => !SCRIPT_SOURCE_PATH_RE.test(path)), cwd, deps.runCommand);
   const lookupFailed = importerIndex && 'lookupFailed' in importerIndex ? importerIndex.lookupFailed : undefined;
   const availableIndex = importerIndex && !('lookupFailed' in importerIndex) ? importerIndex : undefined;
   const routeIndex = availableIndex?.testPaths
@@ -691,7 +695,16 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     lines.push(`shards: ${sharded.shards.length} (${sharded.shards.map((shard) => `${shard.id}=${shard.files.join(',')}`).join('; ')})${sharded.measurementFailures ? ` · 측정 실패 ${sharded.measurementFailures}` : ''}`);
     // 조각이 «못 쟀다»일 때 이유가 줄에 없으면 자리·시간 초과·죽음을 가를 수 없다(OP 10-09 light RC) — 종료 코드·신호를 같이 싣는다.
     const side = (code: number | null, signal: string | null | undefined, junit: string | undefined) => signal ? `signal ${signal}` : code === null ? 'exit ?' : `exit ${code}${junit === undefined ? ' · junit 없음' : ''}`;
-    for (const attempt of sharded.attempts) lines.push(`shard attempt: ${attempt.shardId} #${attempt.attempt} · 지금 ${side(attempt.currentExitCode, attempt.currentSignal, attempt.currentJUnit)} · 기준 ${side(attempt.baselineExitCode, attempt.baselineSignal, attempt.baselineJUnit)}`);
+    for (const attempt of sharded.attempts) {
+      const plannedFiles = sharded.shards.find((shard) => shard.id === attempt.shardId)?.files;
+      const baselineFiles = attempt.baselineFiles;
+      const baselineDifference = baselineFiles && plannedFiles && (baselineFiles.length !== plannedFiles.length || baselineFiles.some((file, index) => file !== plannedFiles[index]))
+        ? ` · 기준 파일 ${baselineFiles.join(',') || '(none)'}` : '';
+      lines.push(`shard attempt: ${attempt.shardId} #${attempt.attempt} · 지금 ${side(attempt.currentExitCode, attempt.currentSignal, attempt.currentJUnit)} · 기준 ${side(attempt.baselineExitCode, attempt.baselineSignal, attempt.baselineJUnit)} · 파일 ${plannedFiles?.join(',') ?? '(unknown)'}${baselineDifference}`);
+      const renderDiagnostic = (value: string): string => redactSecretText(value).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').slice(0, 500);
+      if (attempt.currentJUnit === undefined && attempt.currentDiagnostic) lines.push(`shard diagnostic: ${attempt.shardId} #${attempt.attempt} 지금 · ${renderDiagnostic(attempt.currentDiagnostic)}`);
+      if (attempt.baselineJUnit === undefined && attempt.baselineDiagnostic) lines.push(`shard diagnostic: ${attempt.shardId} #${attempt.attempt} 기준 · ${renderDiagnostic(attempt.baselineDiagnostic)}`);
+    }
     const { aggregate } = sharded;
     let shardBaseline: SelfGateCliResult['baseline'];
     let unmeasuredReason: string | undefined;

package/src/self-implement/goal-author-decompose.ts

@@ -54,6 +54,51 @@ export function readRecentStepCountsFailOpen(reader: RecentStepCountReader = rea
   }
 }
 
+/**
+ * ⭐ AUTHOR-SHADOW-FIRST-SPLIT ① (0.2.29 · 근거 사례 #26644 · 대표 10-12 «착지해야만 낼 수 있는 증거는
+ * 처음 저작부터 쪼갰어야»). 골 문면에 «명시 표지» 한 줄이 있을 때만 처음부터 두 조각
+ * (① 그림자 → ② live 스위치, 선행 간선 1)으로 낸다. 표지가 없으면 어떤 문면이든 종전 LLM 분해 그대로다.
+ *
+ * ⛔ 발동은 명시 표지 «하나»뿐이다 — 자연어 감지(자율 표지·운영 실증·부정어)는 쓰지 않는다.
+ *   자연어 부정 판별은 수렴하지 않았고(리뷰 r4~r6), 오탐은 live 조각이 원 목표와 반대로 «켜라»를 지시하게 만든다.
+ *   자연어 감지 발동은 후속 개선(OP 결정 10-15).
+ * 런 슈퍼바이저 REVIEW-MUSTFIX-CLASSIFY ②가 «런 중간»에 같은 쪼개기를 한다 — 저작이 먼저 막고 그쪽은 놓친 것을 받는다.
+ */
+export const SHADOW_FIRST_SPLIT_MARKER = '분할: 그림자 먼저';
+/**
+ * 정확히 한 꼴 — 한 줄 «전체»가 `분할: 그림자 먼저` 와 같을 때만(콜론 뒤 공백 정확히 1개 · 앞·뒤 공백 불허).
+ * 줄바꿈은 LF·CRLF 만 — 홀로 남은 CR 은 줄의 일부로 남아 불일치(미발동)다.
+ */
+function hasShadowFirstSplitMarkerLine(objective: string): boolean {
+  return objective.split(/\r?\n/).some((line) => line === SHADOW_FIRST_SPLIT_MARKER);
+}
+
+export type ShadowFirstSplitPiece = { id: 'shadow' | 'live'; step: string; dependsOn: readonly ('shadow' | 'live')[] };
+
+export type ShadowFirstSplitVerdict =
+  | { kind: 'shadow-first-split'; pieces: readonly [ShadowFirstSplitPiece, ShadowFirstSplitPiece] }
+  | { kind: 'single-piece' };
+
+/** 순수 판정 — 골 문면의 명시 표지 줄만 본다(LLM·원장·자연어 감지 0 · 던지지 않는다). grounding context 는 읽지 않는다. */
+export function classifyShadowFirstSplit(objective: string): ShadowFirstSplitVerdict {
+  if (!hasShadowFirstSplitMarkerLine(objective)) return { kind: 'single-piece' };
+  return {
+    kind: 'shadow-first-split',
+    pieces: [
+      {
+        id: 'shadow',
+        step: '① 그림자 — 이 골의 배선이 자율 결정을 «기록만» 한다(자율 실행 0). 판정 = 시험 통과 ⊕ 그림자 관측 줄 모양(기록된 결정 1건 이상).',
+        dependsOn: [],
+      },
+      {
+        id: 'live',
+        step: '② live 스위치 — 선행 = ① 그림자 착지. 같은 배선의 자율 실행을 켠다. 판정 = ① 착지 뒤 그림자 로그에 기대 결정 1건 이상 ⊕ 스위치 켬 ⊕ 이 골의 원 판정.',
+        dependsOn: ['shadow'],
+      },
+    ],
+  };
+}
+
 /** Shared LLM-backed decomposition seam for every goal-author entrypoint. */
 export function createGoalAuthorDecomposeSteps(
   signal?: AbortSignal,
@@ -64,6 +109,41 @@ export function createGoalAuthorDecomposeSteps(
   } = {},
 ): NonNullable<GoalAuthorDeps['decomposeSteps']> {
   return async (objective, options) => {
+    const finalize = (finalSteps: string[], rationale?: string): string[] => {
+      if (finalSteps.length > 0 && rationale?.trim()) {
+        try {
+          emitDecision({
+            kind: 'PLAN',
+            what: finalSteps.length === 1 ? '분해 안 함(한 조각)' : `골을 조각 ${finalSteps.length}개로 분해`,
+            reason: rationale.trim().split(/\r?\n|(?<=[.!?。])\s+/)[0]!,
+            purpose: '조각마다 독립 런으로 · 실패를 작게 가둔다',
+            target: finalSteps.slice(0, 8).join(' · '),
+            paths: finalSteps.length,
+            ...(options?.runId === undefined ? {} : { runId: options.runId }),
+          });
+        } catch { /* Live detail cannot change the decomposition result. */ }
+      }
+      return finalSteps;
+    };
+    // ⭐ AUTHOR-SHADOW-FIRST-SPLIT ① — LLM 분해·적대 비평 «전에» 규칙 판정. 감지된 골은 처음부터 두 조각.
+    //   single-piece 는 관측 0 · 동작 0 변화(종전 그대로).
+    const shadowSplit = classifyShadowFirstSplit(objective);
+    if (shadowSplit.kind === 'shadow-first-split') {
+      try {
+        debug.log('goal-author', 'shadow-first-split', {
+          surface: 'goal-author',
+          verdict: shadowSplit.kind,
+          trigger: 'explicit-marker',
+          pieces: shadowSplit.pieces.map((piece) => piece.id),
+          edges: shadowSplit.pieces.reduce((n, piece) => n + piece.dependsOn.length, 0),
+          ...(options?.runId === undefined ? {} : { runId: options.runId }),
+        });
+      } catch { /* observation is fail-soft */ }
+      return finalize(
+        shadowSplit.pieces.map((piece) => piece.step),
+        `명시 표지 «${SHADOW_FIRST_SPLIT_MARKER}» — 그림자 우선 두 조각(선행 간선 1).`,
+      );
+    }
     const { streamLLM } = await import('../llm.js');
     // ⭐ AUTHOR-DECOMPOSE-KNOB(0.2.24 · G7 #25848) — 쪼개기·적대 비평의 두 streamLLM 호출이 인핸서와
     //   «같은 규칙»으로 planning 노브(roleLlm.planning ⊕ ELANOUS_PROMPT_ENHANCE_MODEL/EFFORT)를 따른다.
@@ -111,22 +191,6 @@ export function createGoalAuthorDecomposeSteps(
       reviewExecuted,
       reviewSkipReason,
     });
-    const finalize = (finalSteps: string[], rationale?: string): string[] => {
-      if (finalSteps.length > 0 && rationale?.trim()) {
-        try {
-          emitDecision({
-            kind: 'PLAN',
-            what: finalSteps.length === 1 ? '분해 안 함(한 조각)' : `골을 조각 ${finalSteps.length}개로 분해`,
-            reason: rationale.trim().split(/\r?\n|(?<=[.!?。])\s+/)[0]!,
-            purpose: '조각마다 독립 런으로 · 실패를 작게 가둔다',
-            target: finalSteps.slice(0, 8).join(' · '),
-            paths: finalSteps.length,
-            ...(options?.runId === undefined ? {} : { runId: options.runId }),
-          });
-        } catch { /* Live detail cannot change the decomposition result. */ }
-      }
-      return finalSteps;
-    };
     if (!reviewExecuted) return finalize(steps, decompositionRationale);
     const critic = (prompt: string) => streamLLM([{ role: 'user', content: prompt }], () => {}, llmOpts);