elanous 0.2.35 → 0.2.37

package/src/self-dev/shard-plan.ts

@@ -105,3 +105,51 @@ export function planFixedGateTestShards(files: readonly string[], shardCount: nu
   }
   return groups.map((group, index) => ({ id: `shard-${index + 1}`, files: group, plannedRssMb: 0, plannedSeconds: 0 }));
 }
+
+/** GATE-REMOTE-SHARD-PLAN — one remote shard carrying its orchestration identity; introducedFiles are this shard's own
+ *  files, so introduced attribution stays file-level (a shard never inherits another shard's introduced files). */
+export interface GateRemoteShard {
+  orchestrationId: string;
+  shardId: string;
+  totalShards: number;
+  position: number;
+  files: string[];
+  introducedFiles: string[];
+}
+
+/** Deterministic orchestration id for a changed-file list: same files in any order produce the same id, so re-plans stay joinable. */
+export function shardPlanOrchestrationId(files: readonly string[]): string {
+  const sorted = [...new Set(files)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  let hash = 0x811c9dc5;
+  for (const file of sorted) {
+    for (let index = 0; index < file.length; index += 1) {
+      hash ^= file.charCodeAt(index);
+      hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+  }
+  return `gate-${sorted.length}-${hash.toString(16).padStart(8, '0')}`;
+}
+
+/** Split a changed-file list (e.g. 183 files) into identity-carrying shards; every file is introduced by its own shard.
+ *  Contiguous slices keep each shard's files in input order, so concatenating shards reproduces the input list. */
+export function planGateRemoteShards(files: readonly string[], shardCount: number, orchestrationId: string): GateRemoteShard[] {
+  if (!Number.isSafeInteger(shardCount) || shardCount < 1) throw new Error('invalid shard count');
+  const sorted = [...new Set(files)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  if (!sorted.length) throw new Error('no files to shard');
+  if (shardCount > sorted.length) throw new Error(`shard count ${shardCount} exceeds file count ${sorted.length}`);
+  const base = Math.floor(sorted.length / shardCount);
+  const extra = sorted.length % shardCount;
+  return Array.from({ length: shardCount }, (_, index) => {
+    const start = index * base + Math.min(index, extra);
+    const size = base + (index < extra ? 1 : 0);
+    const shardFiles = sorted.slice(start, start + size);
+    return {
+      orchestrationId,
+      shardId: `${orchestrationId}/shard-${index + 1}`,
+      totalShards: shardCount,
+      position: index + 1,
+      files: shardFiles,
+      introducedFiles: [...shardFiles],
+    };
+  });
+}

package/src/self-dev/shard-run.ts

@@ -51,6 +51,16 @@ export interface ShardRunMode {
   fixedDistribution?: boolean;
   /** Measured on the executing host; override only for deterministic planning tests. */
   hostResources?: { cores: number; freeMemoryGiB: number; freeTmpGiB: number };
+  /** Observation after each bundle's first current+baseline attempt; never controls retries or verdict. */
+  onShardComplete?: (progress: ShardRunProgress) => void;
+}
+
+export interface ShardRunProgress {
+  shardId: string;
+  completedShards: number;
+  totalShards: number;
+  completedFiles: number;
+  totalFiles: number;
 }
 
 function hostResources(): ShardRunMode['hostResources'] | undefined {
@@ -162,7 +172,7 @@ export function runShardedGateTests(
     try { fixed = planFixedGateTestShards(files, count); }
     catch (error) { return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error), distribution: 'fixed' }; }
     debug.log('self-dev.shard', 'fixed-distribution', { shards: fixed.length, files: fixed.reduce((sum, shard) => sum + shard.files.length, 0) });
-    return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree), distribution: 'fixed' };
+    return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree, mode.onShardComplete), distribution: 'fixed' };
   }
   const rss = new Map<string, number>();
   const seconds = new Map<string, number>();
@@ -199,7 +209,7 @@ export function runShardedGateTests(
       const fixed = planFixedGateTestShards(files, maxCount);
       debug.log('self-dev.shard', 'host-cap-fixed-fallback', { requested: count, cap: maxCount,
         files: new Set(files).size, reason, measurementFailures: measurementFailures ?? 0 });
-      return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree), distribution: 'fixed-cap-fallback',
+      return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree, mode.onShardComplete), distribution: 'fixed-cap-fallback',
         fallbackReason: reason, ...(measurementFailures ? { measurementFailures } : {}) };
     } catch (error) {
       return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [],
@@ -232,7 +242,7 @@ export function runShardedGateTests(
     requested: count, planned: shards.length, files: new Set(files).size, budgetGiB,
     measurementFailures: measurementFailures ?? 0,
   });
-  return { ...runPlannedShards(cwd, shards, baseRef, run, baselineWorktree), ...(plannedCount > count ? { expandedFrom: count } : {}), ...(measurementFailures ? { measurementFailures } : {}) };
+  return { ...runPlannedShards(cwd, shards, baseRef, run, baselineWorktree, mode.onShardComplete), ...(plannedCount > count ? { expandedFrom: count } : {}), ...(measurementFailures ? { measurementFailures } : {}) };
 }
 
 /** Shared by the measured and the fixed planner: current + baseline per shard, one retry round, one aggregate. */
@@ -242,6 +252,7 @@ function runPlannedShards(
   baseRef: string,
   run: ShardProcess,
   baselineWorktree: typeof withBaselineWorktree,
+  onShardComplete?: ShardRunMode['onShardComplete'],
 ): ShardRunResult {
   const attempts: GateShardAttempt[] = [];
   const failureEvidence: ShardFailureEvidence[] = [];
@@ -256,6 +267,8 @@ function runPlannedShards(
     const treeReadable = (() => { try { return statSync(dir).isDirectory(); } catch { return false; } })();
     const atBase = (shard: GateTestShard) => treeReadable ? shard.files.filter((file) => !absentAtBaseline(join(dir, file))) : [...shard.files];
     let pending = shards;
+    let completedFiles = 0;
+    const totalFiles = new Set(shards.flatMap((shard) => shard.files)).size;
     for (let round = 1; round <= 2 && pending.length; round++) {
       for (const shard of pending) {
         const runSafely = (location: string, selected: readonly string[]): ReturnType<ShardProcess> => {
@@ -279,6 +292,13 @@ function runPlannedShards(
           baselineFiles,
           currentRoot: cwd, baselineRoot: dir,
         });
+        if (round === 1 && onShardComplete) {
+          completedFiles += shard.files.length;
+          try {
+            onShardComplete({ shardId: shard.id, completedShards: attempts.length,
+              totalShards: shards.length, completedFiles, totalFiles });
+          } catch { /* progress is observation only */ }
+        }
       }
       const retry = new Set(aggregateGateTestShards(shards, attempts).retryShardIds);
       pending = shards.filter((shard) => retry.has(shard.id));
@@ -360,3 +380,30 @@ export function runBunShardWithSpawn(cwd: string, files: readonly string[], spaw
     rmSync(dir, { recursive: true, force: true });
   }
 }
+
+/** GATE-REMOTE-SHARD-PLAN — identity of one remote shard. files/introducedFiles are optional: a caller that only relays
+ *  identity (CLI wiring) passes none, while a planner-produced shard carries its file-level attribution. */
+export interface RemoteShardSpec {
+  orchestrationId: string;
+  shardId: string;
+  totalShards: number;
+  position: number;
+  files?: readonly string[];
+  introducedFiles?: readonly string[];
+}
+
+/** The identity slice that rides a remote gate command line — validated so a dropped flag fails loudly, not silently. */
+export function remoteShardArgArgs(shard: RemoteShardSpec, options?: { planFile?: string }): string[] {
+  if (!shard.orchestrationId.trim()) throw new Error('orchestration id must be non-empty');
+  if (!shard.shardId.trim()) throw new Error('shard id must be non-empty');
+  if (!Number.isSafeInteger(shard.totalShards) || shard.totalShards < 1) throw new Error('shard total must be a positive integer');
+  if (!Number.isSafeInteger(shard.position) || shard.position < 1) throw new Error('shard position must be a positive integer');
+  const args = ['--orchestration-id', shard.orchestrationId, '--shard-id', shard.shardId, '--shard-position', String(shard.position)];
+  if (options?.planFile !== undefined && options.planFile !== '') args.push('--shard-plan', options.planFile);
+  return args;
+}
+
+/** Full remote command for one shard — the exact argv a remote host (e.g. an node-b pod shard) would run. */
+export function remoteShardArgv(shard: RemoteShardSpec, options?: { planFile?: string }): string[] {
+  return ['bun', 'bin/elanous.mjs', '--test', 'self', 'gate', '--changed', '--shards', String(shard.totalShards), ...remoteShardArgArgs(shard, options)];
+}

package/src/self-health/autoheal.ts

@@ -0,0 +1,153 @@
+// ── 자동 회복 (TUI-400-AUTOHEAL-FALLBACK · 대표 10-22) ──
+//
+// 대표 «400 같은 오류로 멈추면 스스로 회복 · 자동 provider fallback 이 없으면 작업을 못 잇는다».
+// 실측(10-22 07:1x OPT): TUI 턴이 «Codex API 400(대화 기록 어긋남 의심)» 로 끝나고 멈췄다 — 지문
+// `codex-400-bad-request` 는 «/session new 뒤 다시» 를 사람에게 «보여줄» 뿐이었고, OP 가 손으로 쳐서 회복했다.
+//
+// 이 모듈은 «판정»만 갖는다(순수 · 관측·화면은 호출부가 남긴다). 사다리:
+//   ① 같은 턴 400(대화 기록) → 새 백엔드 세션 ⊕ 직전 요약(짧게)으로 1회 재시도
+//   ② 그래도 400 → `llm.fallbackChain` 다음 공급자로 그 턴 재시도
+//   ③ 그래도 실패 → 턴당 2회 상한에서 멈추고 사람에게 이유 한 줄
+// ⛔ 답·도구 호출이 이미 흘렀으면 다시 보내지 않는다(중복 출력·부작용). ⛔ 무한 반복 금지(AUTOHEAL_MAX_ATTEMPTS).
+// 📋 관측 = `debug.log('self-health.autoheal', attempt|recovered|exhausted|skipped, …)` — 호출부(plain-turn 런타임).
+
+import { matchFailureText, type FailureSignature } from './signatures.js';
+
+/** 턴당 자동 회복 상한 — ① 새 세션 ② 공급자. ⛔ 늘리면 «무한 반복 금지» 판정선이 같이 움직인다. */
+export const AUTOHEAL_MAX_ATTEMPTS = 2;
+
+export type AutohealStep = 'new-session' | 'provider-fallback';
+
+/** 재시도 요청에 실리는 ACP `_meta` 키 — 서버 다리(`core-turn-bridge`)가 «이 턴은 다음 공급자로» 를 읽는다.
+ *  ⛔ 공급자 «이름»은 싣지 않는다 — 고르는 것은 서버가 자기 `llm.fallbackChain` 으로 한다(클라이언트가 지갑을 못 고른다). */
+export const AUTOHEAL_META_KEY = 'elanousAutoheal';
+
+export interface AutohealProviderFallbackMeta {
+  readonly providerFallback: true;
+}
+
+export function autohealProviderFallbackMeta(): Record<string, AutohealProviderFallbackMeta> {
+  return { [AUTOHEAL_META_KEY]: { providerFallback: true } };
+}
+
+/** 프롬프트 `_meta` 에 «다음 공급자로» 표지가 있나. */
+export function readAutohealProviderFallback(meta: Readonly<Record<string, unknown>> | undefined): boolean {
+  const value = meta?.[AUTOHEAL_META_KEY];
+  return typeof value === 'object' && value !== null
+    && (value as { providerFallback?: unknown }).providerFallback === true;
+}
+
+/** 자동 회복을 거는 지문 — 오류 «원문»으로 판정한다(지문 번역문으로 판정하면 안 걸린다 · #27452 교훈). */
+export function autohealSignatureFor(detail: string): FailureSignature | null {
+  const sig = matchFailureText(detail);
+  return sig?.autoheal ? sig : null;
+}
+
+export type AutohealStopReason =
+  | 'not-autoheal-signature'
+  | 'output-emitted'
+  | 'tool-dispatched'
+  | 'aborted'
+  | 'history-changed'
+  | 'no-fallback-provider'
+  | 'max-attempts';
+
+export type AutohealDecision =
+  | { readonly kind: 'retry'; readonly step: AutohealStep; readonly attempt: number; readonly provider?: string }
+  | { readonly kind: 'stop'; readonly reason: AutohealStopReason };
+
+export interface AutohealDecisionInput {
+  /** 이번 실패의 오류 원문. */
+  readonly detail: string;
+  /** 이미 한 자동 회복 횟수(0 = 첫 실패). */
+  readonly attemptsDone: number;
+  /** 이 턴에서 답·도구 호출이 화면/서버로 흘렀나. */
+  readonly emitted: boolean;
+  /** 도구 실행 수가 바뀌었나(모르면 false — 그때는 emitted 로만 가른다). */
+  readonly toolDispatched: boolean;
+  readonly aborted: boolean;
+  /** ② 칸에서 쓸 다음 공급자(없으면 null). ① 칸에서는 안 본다. */
+  readonly fallbackProvider: string | null;
+}
+
+/** 다음 한 걸음. 순수 — 같은 입력이면 같은 답. */
+export function decideAutohealStep(input: AutohealDecisionInput): AutohealDecision {
+  if (!autohealSignatureFor(input.detail)) return { kind: 'stop', reason: 'not-autoheal-signature' };
+  if (input.aborted) return { kind: 'stop', reason: 'aborted' };
+  if (input.emitted) return { kind: 'stop', reason: 'output-emitted' };
+  if (input.toolDispatched) return { kind: 'stop', reason: 'tool-dispatched' };
+  if (input.attemptsDone >= AUTOHEAL_MAX_ATTEMPTS) return { kind: 'stop', reason: 'max-attempts' };
+  if (input.attemptsDone === 0) return { kind: 'retry', step: 'new-session', attempt: 1 };
+  if (!input.fallbackProvider) return { kind: 'stop', reason: 'no-fallback-provider' };
+  return { kind: 'retry', step: 'provider-fallback', attempt: 2, provider: input.fallbackProvider };
+}
+
+/** 화면 한 줄 — 시도할 때. */
+export function formatAutohealAttemptLine(decision: Extract<AutohealDecision, { kind: 'retry' }>): string {
+  const what = decision.step === 'new-session' ? '새 세션 ⊕ 요약으로' : `공급자 ${decision.provider ?? '?'} 로`;
+  return `자동 회복: ${what} 다시 시도 (${decision.attempt}/${AUTOHEAL_MAX_ATTEMPTS})`;
+}
+
+export interface AutohealAttemptRecord {
+  readonly step: AutohealStep;
+  readonly provider?: string;
+}
+
+/** 화면 한 줄 — 상한에서 멈출 때. 한글 두 칸으로 130칸 안(지문 한 줄과 같은 규율). */
+export function formatAutohealExhaustedNotice(
+  attempts: readonly AutohealAttemptRecord[],
+  reason: AutohealStopReason,
+  opts: { rawHint?: string } = {},
+): string {
+  const steps = attempts.map((a) => (a.step === 'new-session' ? '새 세션' : `공급자 ${a.provider ?? '?'}`)).join(' → ');
+  const why = reason === 'no-fallback-provider' ? `${steps} · 대체 공급자 없음` : steps;
+  const raw = opts.rawHint ? ` · 원문 ${opts.rawHint}` : '';
+  return `⚠ 자동 회복 ${attempts.length}회 실패(${why}) → 잠시 뒤 다시 · eln usage${raw}`;
+}
+
+/** 상한에서 멈춘 턴 — 메시지는 «원문 그대로»(지문·#27452 판정이 원문으로 돈다), 회복 이력은 따로 싣는다. */
+export class AutohealExhaustedError extends Error {
+  constructor(
+    readonly original: unknown,
+    readonly attempts: readonly AutohealAttemptRecord[],
+    readonly reason: AutohealStopReason,
+  ) {
+    super(original instanceof Error ? original.message : String(original));
+    this.name = 'AutohealExhaustedError';
+  }
+}
+
+/** 직전 요약을 «짧게» — 이미 있는 압축 요약(`compactConversation`)을 쓰고, 실패·시간 초과면
+ *  같은 압축 모듈의 대화록(`buildCompactTranscript`) 꼬리로 대신한다. ⛔ 여기서 요약을 다시 만들지 않는다. */
+export async function summarizeForAutoheal<T>(
+  prior: readonly T[],
+  deps: {
+    compact: (history: readonly T[]) => Promise<{ summary: string }>;
+    transcript: (history: readonly T[]) => string;
+    timeoutMs?: number;
+    maxChars?: number;
+  },
+): Promise<{ summary: string; source: 'compact' | 'transcript-tail' | 'empty' }> {
+  const maxChars = deps.maxChars ?? 1_200;
+  const clip = (text: string, tail: boolean): string => {
+    const trimmed = text.trim();
+    if (trimmed.length <= maxChars) return trimmed;
+    return tail ? `…${trimmed.slice(-maxChars)}` : `${trimmed.slice(0, maxChars)}…`;
+  };
+  try {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error('autoheal summary timed out')), deps.timeoutMs ?? 20_000);
+    });
+    try {
+      const { summary } = await Promise.race([deps.compact(prior), timeout]);
+      if (summary.trim()) return { summary: clip(summary, false), source: 'compact' };
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  } catch { /* 요약 실패는 대화록 꼬리로 — 회복을 막지 않는다 */ }
+  const transcript = deps.transcript(prior);
+  return transcript.trim()
+    ? { summary: clip(transcript, true), source: 'transcript-tail' }
+    : { summary: '', source: 'empty' };
+}

package/src/self-health/signatures.ts

@@ -34,6 +34,9 @@ export interface FailureSignature {
   readonly cause: string;
   /** 다음 행동 — 한국어 한 줄. */
   readonly next: string;
+  /** 자동 수복 — 있으면 TUI 턴이 사람에게 넘기기 «전에» 스스로 회복을 시도한다(`self-health/autoheal.ts`).
+   *  `new-session-then-provider` = ① 새 백엔드 세션 ⊕ 직전 요약 → ② fallbackChain 다음 공급자(턴당 2회 상한). */
+  readonly autoheal?: 'new-session-then-provider';
 }
 
 /** 이벤트 루프 정지를 «지문»으로 볼 문턱 — 0.25s 표본은 잦아 소음이고, 결함 #1(14s)·#14(최대 2.35s)는 이 위다. */
@@ -48,6 +51,9 @@ export const FAILURE_SIGNATURES: readonly FailureSignature[] = [
     text: [/\b(?:Codex|LLM) API 400\b/],
     cause: '모델 API 가 요청을 400 으로 거절(대화 기록 어긋남 의심)',
     next: '/session new 뒤 짧게 다시 묻기',
+    // TUI-400-AUTOHEAL-FALLBACK(대표 10-22) — 위 처방을 사람이 치기 전에 TUI 가 먼저 스스로 해 본다.
+    //   처방 한 줄은 자동 회복이 «안 걸린» 경우(답이 이미 흐름·배선 없음)에만 보인다.
+    autoheal: 'new-session-then-provider',
   },
   {
     id: 'provider-fallback-exhausted',

package/src/self-implement/device-first.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DEVICE_FIRST_STEP = 'DEVICE-FIRST-STAGE';
+
+export interface DeviceFirstDecision {
+  required: boolean;
+  device: string;
+  deviceSource: 'goal' | 'planner-stage';
+  exists: boolean;
+  inventoryMeasured: boolean;
+  firstSliceKind: 'device-test' | 'none';
+}
+
+/** Board goals carry an executable boundary. Ordinary free-form plans retain their existing decomposition. */
+export function inspectDeviceFirstGoal(goal: string, root?: string): DeviceFirstDecision {
+  const required = /완료\s*경계\s*증거\s*명령\s*:|검증\s*계획\s*\(TDD\)|DEVICE-FIRST|장치\s*우선/iu.test(goal)
+    && /(?:src|test)\/[\w./-]+\.[cm]?[jt]sx?/u.test(goal);
+  if (!required) return { required: false, device: '', deviceSource: 'goal', exists: false, inventoryMeasured: root !== undefined, firstSliceKind: 'none' };
+  const explicit = /(?:쓸\s*장치|필요한\s*장치|mock\s*장치)\s*:\s*`?([\w./-]+)/iu.exec(goal)?.[1];
+  const named = explicit ?? [...goal.matchAll(/src\/ux-sim\/([\w-]+)\.ts/gu)].map((match) => match[1]).find((name) => name !== 'event-monkey');
+  // A generic TDD boundary says nothing about which device is needed. Do not
+  // invent <feature>-device.ts from a production path.
+  if (!named) return { required: false, device: '', deviceSource: 'goal', exists: false,
+    inventoryMeasured: root !== undefined, firstSliceKind: 'none' };
+  const stem = named.replace(/^src\/ux-sim\//u, '').replace(/\.ts$/u, '');
+  const safeStem = stem.replace(/[^a-z0-9-]/giu, '-').replace(/^-+|-+$/gu, '') || 'goal-device';
+  const device = `src/ux-sim/${safeStem}.ts`;
+  return { required: true, device, deviceSource: 'goal', exists: root !== undefined && existsSync(join(root, device)),
+    inventoryMeasured: root !== undefined, firstSliceKind: 'device-test' };
+}
+
+export function ensureDeviceFirstSteps(goal: string, steps: readonly string[], root?: string): { steps: string[]; decision: DeviceFirstDecision } {
+  let decision = inspectDeviceFirstGoal(goal, root);
+  if (steps.length === 0) return { steps: [...steps], decision };
+  const existingStage = steps.findIndex((step) => step.includes(`동작: ${DEVICE_FIRST_STEP}`));
+  let rejectedStagedPath: string | undefined;
+  if (existingStage >= 0) {
+    const declaredPaths = steps[existingStage]!.split(/동작:/u)[0]!;
+    const stagedAction = steps[existingStage]!.split(/\n완료 경계/u)[0]!;
+    const declaredPath = /신설:\s*(src\/ux-sim\/[\w/-]+\.ts)/u.exec(steps[existingStage]!)?.[1]
+      ?? /src\/ux-sim\/[\w/-]+(?:\.test)?\.ts(?![\w.])/u.exec(stagedAction)?.[0]
+      ?? /(?:src|test)\/[\w./-]+\.[cm]?[jt]sx?(?![\w.])/u.exec(declaredPaths)?.[0];
+    const stagedPath = declaredPath?.replace(/\.test\.ts$/u, '.ts');
+    if (stagedPath && /^src\/ux-sim\/[\w/-]+\.ts$/u.test(stagedPath)) {
+      decision = { ...decision, required: true, device: stagedPath, deviceSource: 'planner-stage',
+        exists: root !== undefined && existsSync(join(root, stagedPath)), firstSliceKind: 'device-test' };
+    } else if (declaredPath) rejectedStagedPath = declaredPath;
+  }
+  // Without a repository root we cannot verify an existing device or declare
+  // its missing paths. Keep the feature plan and defer device inventory.
+  if (root === undefined && decision.required) decision = { ...decision, required: false, firstSliceKind: 'none' };
+  if (!decision.required) return { steps: existingStage < 0 ? [...steps]
+    : steps.filter((_, index) => index !== existingStage)
+      .map(step => step.replace(/\n?선행: DEVICE-FIRST-STAGE 조각 착지 뒤 발사/gu, '')), decision };
+  const predecessor = `선행: ${DEVICE_FIRST_STEP} 조각 착지 뒤 발사`;
+  const test = decision.device.replace(/\.ts$/u, '.test.ts');
+  // The parent goal's feature test is not evidence that the device itself works.
+  const deviceBoundary = [
+    `완료 경계 코드: ${decision.device}와 ${test}에서 mock 입력을 생산 호출에 주입하고 관측 가능한 결과를 단언한다. 운영 코드 변경 0.`,
+    '완료 경계 실물: 대상 저장소에서 mock 입력으로 실제 생산 호출을 통과시켜 입력·출력 또는 사건 원문을 남긴다. RED 실패 뒤 GREEN 통과를 같은 시험으로 확인한다.',
+    `완료 경계 증거 명령: bun test ${test}`,
+  ].join('\n');
+  const completeDeviceStage = (stage: string): string => {
+    // A planner may have copied the feature boundary onto this stage. Give the device one unambiguous boundary.
+    const body = stage.split('\n')
+      .filter((line) => !/^\s*(?:[-*]\s*)?완료 경계 (?:코드|실물|증거 명령):/u.test(line))
+      .map((line) => line.replace(/\s*·\s*완료 경계 (?:코드|실물|증거 명령):[^·]*/gu, ''))
+      .join('\n');
+    return `${body}\n${deviceBoundary}`;
+  };
+  const evidenceCommand = /완료\s*경계\s*증거\s*명령\s*[:：]\s*([^\r\n]+)/u.exec(goal)?.[1] ?? '';
+  const goalFeatureTest = [evidenceCommand, goal].flatMap((text) => [...text.matchAll(/(?:src|test)\/[\w./-]+\.test\.[cm]?[jt]sx?/gu)]
+    .map((match) => match[0])).find((path) => path !== test && !path.startsWith('src/ux-sim/'));
+  const completeFeatureStage = (stage: string, index: number): string => {
+    const withPredecessor = stage.includes(predecessor) ? stage : `${stage}\n${predecessor}`;
+    const declaredGoalTest = index === 0 ? goalFeatureTest : undefined;
+    const priorPlan = /검증 계획\(TDD\):[^\n]*/u.exec(withPredecessor)?.[0];
+    // An explicit goal command replaces the whole inherited plan. Merely
+    // containing that command is insufficient when a stale command remains.
+    if (priorPlan && !declaredGoalTest) return withPredecessor;
+    const withoutWrongPlan = priorPlan ? withPredecessor.replace(priorPlan, '').trimEnd() : withPredecessor;
+    const stagePaths = stage.split(/동작:/u)[0]!;
+    const stageTest = /(?:src|test)\/[\w./-]+\.test\.[cm]?[jt]sx?/u.exec(stagePaths)?.[0];
+    const stageSource = /(?:src|test)\/[\w./-]+\.[cm]?[jt]sx?/u.exec(stagePaths)?.[0];
+    const existingSiblingTest = stageSource?.endsWith('.ts') && root !== undefined
+      ? stageSource.replace(/\.ts$/u, '.test.ts') : undefined;
+    const featureTest = declaredGoalTest ?? stageTest
+      ?? (existingSiblingTest && existsSync(join(root!, existingSiblingTest)) ? existingSiblingTest : undefined);
+    if (!featureTest) return `${withoutWrongPlan}\n검증 계획(TDD): 시험 경로 미확정(${stageSource ? `${stageSource}의 시험 확장자 미정` : '조각 대상 경로 없음'}) · 이 조각에서 시험 경로를 먼저 정하고 RED 실패 뒤 같은 명령으로 GREEN을 확인한다.`;
+    const inventory = root === undefined ? '시험 재고 미측정(대상 루트 미상)'
+      : existsSync(join(root, featureTest)) ? '기존 시험' : '신규 시험(이 조각에서 먼저 신설)';
+    return `${withoutWrongPlan}\n검증 계획(TDD): ${inventory} ${featureTest} · 피처 시험 bun test ${featureTest}를 구현 전에 RED로 확인하고 생산 경로를 구현한 뒤 같은 명령으로 GREEN을 확인한다.`;
+  };
+  const targetPaths = [decision.device, test].filter((path) => root !== undefined && existsSync(join(root, path)));
+  const newPaths = [decision.device, test].filter((path) => !targetPaths.includes(path));
+  const firstTarget = targetPaths[0];
+  const first = `${firstTarget ? `대상 경로: ${firstTarget}\n` : ''}${newPaths.length ? `신설: ${newPaths.join(' · ')}\n` : ''}`
+    + `· 동작: ${DEVICE_FIRST_STEP} ${!decision.inventoryMeasured ? `${decision.device} 재고를 먼저 확인하고 기존이면 재사용하고 없으면 신설: 경로를 선언해` : decision.exists ? `기존 ${decision.device}를 사용해` : '필요한 mock 장치와 그 시험을 먼저 만들어'} mock 무대 시험 RED를 기록한다. 운영 코드 변경 0.`
+    + (!decision.inventoryMeasured ? '\n장치 재고: 미측정(대상 루트 미상).' : '');
+  if (existingStage >= 0) {
+    const oldStage = steps[existingStage]!;
+    // Replace copied completion boundaries, but retain planner instructions
+    // about the actual injection and verification of this named device.
+    const actionTail = oldStage.split(`동작: ${DEVICE_FIRST_STEP}`)[1]?.split('\n')[0] ?? '';
+    const actionClauses = actionTail.split(/\s+·\s+/u).map((clause) => clause.trim());
+    const retained = [...actionClauses, ...oldStage.split('\n').slice(1)]
+      .map((line) => line.trim())
+      .filter((line) => line && !/^(?:대상 경로|신설|[·*-]?\s*동작: DEVICE-FIRST-STAGE|장치 재고:|완료 경계 (?:코드|실물|증거 명령)|선행:)/u.test(line)
+        && !/^(?:필요한 mock 장치와 그 시험을 먼저 만들어|기존 src\/ux-sim\/[\w/-]+\.ts를 사용해|src\/ux-sim\/[\w/-]+\.ts 재고를 먼저 확인하고 기존이면 재사용하고 없으면 신설: 경로를 선언해) mock 무대 시험 RED를 기록한다\. 운영 코드 변경 0\.$/u.test(line));
+    const stage = `${first}${retained.length ? `\n${retained.join('\n')}` : ''}`
+      + (rejectedStagedPath ? `\n플래너 장치 경로 ${rejectedStagedPath}는 src/ux-sim/*.ts 규약 밖 — 골의 장치 후보로 복구.` : '');
+    return { decision, steps: [completeDeviceStage(stage), ...steps.filter((_, index) => index !== existingStage).map(completeFeatureStage)] };
+  }
+  return { decision, steps: [completeDeviceStage(first), ...steps.map(completeFeatureStage)] };
+}