elanous 0.2.38 → 0.2.40

package/src/self-dev/ask-launch-flow.ts

@@ -38,17 +38,15 @@ import {
 import { execFileSync } from 'node:child_process';
 import { dirname, isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep } from 'node:path';
 import {
-  applyClarificationReply,
   planClarificationIntake,
   selfAnswerGoalDocumentClarifications,
   type GoalClarificationSelfResolver,
 } from '../self-implement/goal-author-clarification.js';
-import { classifyReauthoredAsk, countMissingAuthoredConstraintMarkers, askGoalTypeDeclaration, declaredGoalType, parseGoalId } from '../self-implement/goal-author.js';
+import { countMissingAuthoredConstraintMarkers, askGoalTypeDeclaration, declaredGoalType, parseGoalId } from '../self-implement/goal-author.js';
 import { observeFrontNodeEntry, observeFrontNodeExit, observeFrontNodeUnit, type AuthorExitOutcome } from './graph-front-nodes.js';
 import { emitDecision } from '../live/detail-switch.js';
 import { decomposeSelfDevGoal, type SelfDevDecomposeOptions, type SelfDevDecomposition } from './decompose.js';
 import { observeDecomposerSelection, readFabricDecomposeConfig, selectFabricDecomposer } from './self-orchestrate-runtime.js';
-import type { GoalDocumentClarification } from '../self-implement/goal-author-clarification.js';
 
 export type SelfResolveClarificationsSource = 'flag' | 'default';
 
@@ -187,7 +185,6 @@ export interface AskLaunchFlowDeps {
   readLine(prompt: string): Promise<string>;
   /** Optional structured clarification adapter. Omitted callers retain the
    * existing CLI line-input contract exactly. */
-  readClarification?(clarification: GoalDocumentClarification): Promise<string>;
   selfResolveClarification?: GoalClarificationSelfResolver;
   /** Replaces the goal document after a self-answer; production entrances pass an atomic writer. */
   writeGoalDocument?(path: string, document: string): void;
@@ -753,8 +750,7 @@ async function runPrePreflight(
     : false;
 }
 
-/** ⑴b 되묻기 «수신» — 답이 들어가면 «재저작»하고 그 새 골을 돌려준다.
- *  ⛔ 무인 계약은 그대로다 — 대화형이 «아니면» 종전처럼 지나가고, 그 사실을 관측에 남긴다. */
+/** ⑴b 되묻기 intake — shared self-resolution policy, then continue with answered/deferred goal. */
 async function intakeClarifications(
   authored: AskAuthoredGoal,
   input: AskLaunchFlowInput,
@@ -775,113 +771,45 @@ async function intakeClarifications(
     interactive: deps.isInteractive(),
     goalFile: effectiveGoalFile,
   }, 'info');
-  if (mode === 'none') {
+  if (pending.length === 0) {
     deps.print('[ask] ⑴b 되묻기 없음 — 저작기가 물을 것이 없었다');
     return effectiveGoalFile;
   }
-  if (mode === 'deferred-noninteractive') {
-    // The resolver comes in through deps (I/O seam): production entrances pass the author
-    // self-resolver; a caller that injects none keeps the previous deferred behaviour.
-    if (selfResolveClarifications.value && deps.selfResolveClarification) try {
-      const resolution = await selfAnswerGoalDocumentClarifications(document, {
-        path: 'ask', ask: input.askText, resolver: deps.selfResolveClarification,
-      });
-      if (resolution.newlyAnswered > 0) {
-        (deps.writeGoalDocument ?? deps.writeFile)(effectiveGoalFile, resolution.document);
-        document = resolution.document;
-      }
-    } catch (error) {
-      deps.log('ask-clarify', { goalFile: effectiveGoalFile, reason: 'self-answer-failed', error: error instanceof Error ? error.message : String(error) }, 'warn');
-    }
-    const remaining = planClarificationIntake(document, false).pending;
-    // 미답으로 남은 문항만 기존 답변 창구를 안내한다.
-    deps.print(`[ask] ⑴b ⚠️ 미답 되묻기 ${remaining.length}건 — 저작은 그대로 간다 · 구현 전에 LLM 릴레이가 먼저 답하고, 못 하면 미답으로 진행한다 (사람을 기다리지 않는다)`);
-    for (const item of remaining) {
-      deps.print(`[ask]    ❓ [${item.questionId}] ${item.question}`);
-      item.options.forEach((option, index) => deps.print(`[ask]       ${index}) ${option.label}`));
+  // Deferred and interactive entrances share the same per-question resolution policy used by
+  // direct goal authoring. In particular, never read from the TUI here: unresolved stays DEFERRED.
+  if (selfResolveClarifications.value && deps.selfResolveClarification) try {
+    const resolution = await selfAnswerGoalDocumentClarifications(document, {
+      path: 'ask', ask: input.askText, resolver: deps.selfResolveClarification,
+    });
+    if (resolution.newlyAnswered > 0) {
+      (deps.writeGoalDocument ?? deps.writeFile)(effectiveGoalFile, resolution.document);
+      document = resolution.document;
     }
-    if (remaining.length > 0) {
-      const goalArg = deps.relativeToCwd(effectiveGoalFile);
-      deps.print(`[ask]    ▶ 답하려면: elanous self clarify answer ${goalArg} <questionId> <옵션번호>   (자유 답은 --other "<문장>")`);
-      deps.print(`[ask]    ▶ 답한 뒤 재저작: elanous self author --supersedes ${goalArg}`);
+  } catch (error) {
+    deps.log('ask-clarify', { goalFile: effectiveGoalFile, reason: 'self-answer-failed', error: error instanceof Error ? error.message : String(error) }, 'warn');
     }
-    return effectiveGoalFile;
-  }
-  deps.print(`[ask] ⑴b 저작기가 ${pending.length}건 묻는다 — 빈 줄은 건너뛴다(그 건은 DEFERRED 로 남는다)`);
-  let answeredCount = 0;
-  let seedQuestionId = '';
-  for (const item of pending) {
-    deps.print(`\n[ask] ❓ ${item.question}`);
-    item.options.forEach((option, index) => deps.print(`        ${index}) ${option.label} — ${option.description}`));
-    if (item.includeOther) deps.print('        (숫자 = 위 옵션 · 그 밖의 입력 = 자유 답 · 빈 줄 = 건너뜀)');
-    const reply = deps.readClarification
-      ? await deps.readClarification(item)
-      : await deps.readLine('        > ');
-    // ⛔ 「옵션인가 자유 답인가 · 빈 줄인가」 판정도 순수 seam 이 한다.
-    const applied = applyClarificationReply(document, item, reply);
-    if (!applied.answered) continue;
-    document = applied.document;
-    if (answeredCount === 0) seedQuestionId = item.questionId;
-    answeredCount += 1;
-  }
+  const remaining = planClarificationIntake(document, false).pending;
   deps.log('ask-clarify', {
-    inputSource: input.inputSource, goalFile: effectiveGoalFile,
-    pendingCount: pending.length, answeredCount, interactive: deps.isInteractive(),
-  }, 'info');
-  if (answeredCount === 0) {
-    deps.print('[ask] ⑴b 답이 없다 — 그대로 간다(미답은 골에 DEFERRED 로 남는다)');
-    return effectiveGoalFile;
-  }
-  deps.writeFile(effectiveGoalFile, document);
-  deps.print(`[ask] ⑴b ${answeredCount}건 답함 — 그 답을 시드로 «재저작»한다`);
-  // ⭐ `--from-clarification` 은 답한 것 «전부»를 시드로 가져간다(하나만 지목해도 된다).
-  const reauthored = await deps.authorGoal([], {
-    cwd: deps.cwd(),
-    ...(input.groundingCwd === undefined ? {} : { groundingCwd: input.groundingCwd }),
-    ...(input.authorGrade === undefined ? {} : { authorGrade: input.authorGrade }),
-    fromClarification: `${deps.relativeToCwd(effectiveGoalFile)}#${seedQuestionId}`,
-    reauthorFromAnsweredClarification: true,
-    selfResolveClarifications: selfResolveClarifications.value,
-  });
-  const parentDocument = document;
-  effectiveGoalFile = isAbsolutePath(reauthored.path) ? reauthored.path : resolvePath(deps.cwd(), reauthored.path);
-  deps.print(`[ask] ⑴b 재저작됨: ${reauthored.path}`);
-  // 재저작도 «같은 저작 진입점»이다 — 접지가 예산 초과로 끊기면 같은 결과 줄을 쓴다(조용히 넘기지 않는다).
-  const reauthoredTimebox = reauthored.authored?.document === undefined
-    ? null
-    : readGoalAuthorGroundingTimebox(reauthored.authored.document);
-  if (reauthoredTimebox !== null) {
-    deps.print(formatGoalAuthorTimeboxResultLine(reauthored.path, reauthoredTimebox));
-    deps.log('ask-author-timebox', {
-      goalFile: reauthored.path,
-      provenance: 'reauthor',
-      outcome: 'NOT-GROUNDED',
-      budgetMs: reauthoredTimebox.budgetMs,
-      elapsedMs: reauthoredTimebox.elapsedMs,
-      grounded: reauthored.authored?.grounded ?? null,
-    }, 'warn');
-    // ⛔⭐⭐ 재저작 NOT-GROUNDED 도 «끝»이다 — 결과 줄을 쓰고 되묻기 이후 단계로 지나가지 않는다.
-    observeFrontNodeExit({ node: 'author', outcome: 'not-grounded' }, {
-      ...(input.runId === undefined ? {} : { runId: input.runId }),
-      attempt: 1, goalFile: effectiveGoalFile,
-      reason: `grounding-timebox-exhausted (budget ${reauthoredTimebox.budgetMs}ms, elapsed ${reauthoredTimebox.elapsedMs}ms)`,
-    });
-    return { kind: 'stopped-by-timebox', goalFile: effectiveGoalFile };
-  }
-  // ⛔ 「재저작이 «났다»」와 「재저작이 «옳았다»」는 다른 물음이다(JDG-T35 3단 ⑶).
-  const childDocument = reauthored.authored?.document ?? deps.readFile(effectiveGoalFile);
-  const askFidelity = classifyReauthoredAsk(parentDocument, childDocument);
-  if (askFidelity !== 'preserved') {
-    deps.print(`[ask] ⑴b ⚠️ 재저작 ask 판정: ${askFidelity} — ⛔ 「preserved」가 아니면 사람의 ask 가 살아남았는지 «확인하라»`);
+    goalFile: effectiveGoalFile, pendingCount: pending.length,
+    selfAnsweredCount: pending.length - remaining.length, unansweredCount: remaining.length,
+    interactive: deps.isInteractive(), continuedWithoutPrompt: true,
+  }, remaining.length ? 'warn' : 'info');
+  if (remaining.length > 0) {
+    deps.print(`[ask] ⑴b ⚠️ 미답 되묻기 ${remaining.length}건 — 골에 DEFERRED 로 기록하고 사람 입력을 기다리지 않고 진행한다`);
+    const goalFile = deps.relativeToCwd(effectiveGoalFile);
+    for (const item of remaining) {
+      deps.print(`[ask]    ❓ [${item.questionId}] ${item.question} — DEFERRED`);
+      if (item.options.length > 0) {
+        deps.print(`[ask]       선택지 답변: elanous self clarify answer ${goalFile} ${item.questionId} <0-based-optionIndex>`);
+      }
+      if (item.includeOther) {
+        deps.print(`[ask]       자유 답변: elanous self clarify answer ${goalFile} ${item.questionId} --other "<답>"`);
+      }
+      deps.print(`[ask]       골을 다시 저작하려면: elanous self author --from-clarification ${goalFile}#${item.questionId}`);
+    }
+  } else {
+    deps.print(`[ask] ⑴b ${pending.length}건 자동 후보 선택 — 근거와 가정을 골에 기록했다`);
   }
-  deps.log('ask-reauthored', {
-    inputSource: input.inputSource, fromGoalFile: authored.path,
-    goalFile: reauthored.path, answeredCount,
-    grounded: reauthored.authored?.grounded ?? null,
-    askFidelity,
-    selfResolveClarifications: selfResolveClarifications.value,
-    selfResolveClarificationsSource: selfResolveClarifications.source,
-  }, 'info');
   return effectiveGoalFile;
 }
 

package/src/self-dev/dev-cli.ts

@@ -1113,6 +1113,8 @@ export async function executeDevSelfRun(
     }
     await superviseRun({
       initial: [initialJob],
+      // Pod worktree paths are not necessarily mounted in this parent process.
+      knowhowRepo: process.cwd(),
       // A review-oscillation repair goal runs through the existing piece executor (fragment re-execution with the
       // authored goal as its feature). Without that executor the rerun could only replay the same goal — declare false.
       repairGoalExecution: supervise.executePiece !== undefined,

package/src/self-dev/dev-pipeline.ts

@@ -709,16 +709,16 @@ export function buildAgentMissionDevSpec(o: {
 export async function executeAgentMissionReroute(
   spec: DevPipelineSpec,
   agentBackend: AgentBackend,
-  deps?: { runDevPipeline?: typeof runDevPipeline },
+  deps?: { runDevPipeline?: typeof runDevPipeline; signal?: AbortSignal },
 ): Promise<{ result: AgentMissionResult; exitCode: number }> {
   const run = deps?.runDevPipeline ?? runDevPipeline;
-  const r = await run(spec, { resolveBackend: () => agentBackend });
+  const r = await run(spec, { resolveBackend: () => agentBackend, ...(deps?.signal ? { signal: deps.signal } : {}) });
   // ★ 잘못된 라우팅 즉시 표면화 — spec 이 external+pty 가 아니면 kind 불일치(무조건 캐스팅 금지).
   if (r.kind !== 'agent-mission') {
     throw new DevPipelineError(`executeAgentMissionReroute: 예상 밖 dispatch(kind=${r.kind}) — external+pty spec 이어야`);
   }
   const result = r.result;
-  return { result, exitCode: result.ok ? 0 : 2 };
+  return { result, exitCode: result.reason === 'aborted' ? 130 : result.ok ? 0 : 2 };
 }
 
 // ── U4b: self implement 재라우팅 seam(테스트 가능) ──
@@ -2234,6 +2234,7 @@ async function runDevPipelineDispatch(
     const result = await run({
       ...toSelfImplementOptions(text, plan, seams),
       ...(spec.runId ? { runId: spec.runId } : {}),
+      ...(deps.signal ? { signal: deps.signal } : {}),
       onNodeEntry: (node, round) => { walk.push({ node, round }); },
     });
     // ⛔ 「걸음이 비었다」와 「안 걸었다」를 가른다 — 빈 배열은 «싣지 않는다».
@@ -2252,5 +2253,8 @@ async function runDevPipelineDispatch(
   // agent-mission-pty
   const run = deps.runAgentMission ?? (await import('../agent-mission/driver.js')).runAgentMission;
   const resolveBackend = deps.resolveBackend ?? (await import('../agent-mission/driver.js')).resolveBackend;
-  return { plan, kind: 'agent-mission', result: await run(toAgentMissionSpec(text, plan, resolveBackend)) };
+  return { plan, kind: 'agent-mission', result: await run({
+    ...toAgentMissionSpec(text, plan, resolveBackend),
+    ...(deps.signal ? { signal: deps.signal } : {}),
+  }) };
 }

package/src/self-dev/graph-journey-route.ts

@@ -122,6 +122,10 @@ export function readJourneyEdge(
  *  그 밖의 칸은 그 간선에 결속할 근거(예: 착지 거부 원문·cardId · LAND-REFUSAL-EDGES) — 간선 칸(from·to·taken…)을 덮지 못한다. */
 export interface JourneyEdgeFields {
   readonly moveId?: string;
+  readonly runId?: string;
+  readonly card?: string;
+  readonly pr?: number;
+  readonly head?: string;
   readonly [key: string]: unknown;
 }
 
@@ -140,11 +144,15 @@ export function recordJourneyEdge(route: JourneyRoute, taken: string, reason?: s
       graphId: 'self-implement', node: skipped.node, reason: 'condition', condition: skipped.condition,
       ...journeyJoinFields(),
     });
-    // Evidence never overrides an edge field: the later spread wins, and `reason`/join keys are reserved.
-    const { reason: _reservedReason, journeyKey: _reservedJourney, queueLaunchId: _reservedLaunch, ...evidence } = data ?? {};
+    // Evidence never overrides an edge field: the later spread wins. Explicit repair join keys win over ambient context.
+    const { reason: _reservedReason, journeyKey: _reservedJourney, queueLaunchId: _reservedLaunch,
+      runId, card, pr, head, moveId, ...evidence } = data ?? {};
     debug.log('self-implement', 'graph-edge-taken', {
       ...evidence, graphId: 'self-implement', ...route, taken, honored: route.to === null || route.to === taken,
       ...(reason === undefined ? {} : { reason }), ...journeyJoinFields(),
+      ...(runId === undefined ? {} : { runId }), ...(card === undefined ? {} : { card }),
+      ...(pr === undefined ? {} : { pr }), ...(head === undefined ? {} : { head }),
+      ...(moveId === undefined ? {} : { moveId }),
     });
   } catch { /* 관측은 fail-soft */ }
 }

package/src/self-dev/launch-preflight-text.ts

@@ -22,8 +22,8 @@ export interface LaunchPreflightBlocker {
   readonly name: string;
   /** 왜 막혔는지 한 줄 — 경로와 수를 포함한다. */
   readonly detail: string;
-  /** 골 판독 실패(`goal-unreadable`)와 traced-path 오류(`missing-traced-path`)를 가르는 사유 코드. */
-  readonly reasonCode?: 'goal-unreadable' | 'missing-traced-path';
+  /** 골 판독 실패(`goal-unreadable`) · 골 해석 실패(`goal-parse`) · traced-path 오류(`missing-traced-path`)를 가르는 사유 코드. */
+  readonly reasonCode?: 'goal-unreadable' | 'goal-parse' | 'missing-traced-path';
   /** 어느 검사인지 — 경로를 접지 않은 검사 이름. */
   readonly checkName?: string;
   /** 잘리지 않은 대상 경로. 경로 없는 검사(빈 traced paths)는 생략한다. */

package/src/self-dev/launch-preflight.ts

@@ -1112,14 +1112,31 @@ export function decideAskPreflight(
   const inspectionRoot = goalDocument === null || !hasAuthoredGoal
     ? undefined
     : opts.declaredPathsRoot?.trim() || process.cwd();
-  const authoredTracedPaths = goalDocument === null
-    ? []
-    : inspectableAuthoredTracedPaths(deps.tracedPaths(goalDocument), inspectionRoot);
+  // ⛔ 골 «판독»(읽기) 실패와 골 «해석» 실패는 고칠 곳이 다르다 — 파서가 던진 예외를 사유 코드로 바꿔
+  //   원장에 «어느 검사가» 막았는지 남긴다(AUT-PREFLIGHT-REASON-OPAQUE: 두 갈래가 한 문장으로 뭉개졌다).
+  let goalParseFailure: { readonly checkName: string; readonly message: string } | undefined;
+  const authoredTracedPaths = (() => {
+    if (goalDocument === null) return [];
+    try {
+      return inspectableAuthoredTracedPaths(deps.tracedPaths(goalDocument), inspectionRoot);
+    } catch (error) {
+      goalParseFailure = { checkName: 'goal-parse', message: oneLineConfidenceFailureDetail(error) };
+      return [];
+    }
+  })();
   const tracedPathsRaw = opts.pathsOverride ?? authoredTracedPaths;
   const tracedPaths = inspectionRoot && !opts.pathsOverride
     ? tracedPathsRaw.filter((path) => tracedPathExists(path, inspectionRoot) || isFileShapedTracedPath(path))
     : tracedPathsRaw;
-  const declaredNewPaths = goalDocument === null ? new Set<string>() : new Set(declaredNewFilePaths(goalDocument));
+  const declaredNewPaths = (() => {
+    if (goalDocument === null) return new Set<string>();
+    try {
+      return new Set(declaredNewFilePaths(goalDocument));
+    } catch (error) {
+      goalParseFailure ??= { checkName: 'goal-new-paths', message: oneLineConfidenceFailureDetail(error) };
+      return new Set<string>();
+    }
+  })();
   const invalidTracedPaths: Array<{ path: string; reason: 'occupied-new' | 'not-file' | 'missing' | 'inaccessible' }> = inspectionRoot
     ? authoredTracedPaths.flatMap<{ path: string; reason: 'occupied-new' | 'not-file' | 'missing' | 'inaccessible' }>((path) => {
       const occupation = tracedPathOccupation(path, inspectionRoot);
@@ -1315,7 +1332,8 @@ export function decideAskPreflight(
     ...(recentChangesUnknownReason ? { recentChangesUnknownReason } : {}),
   });
   const missingTracedPathBlockers: LaunchPreflightBlocker[] = [
-    ...(hasAuthoredGoal && authoredTracedPaths.length === 0 ? [{
+    // ⛔ 해석 실패를 「traced path 0」으로 한 번 더 뭉개지 않는다 — 그건 다른 갈래다.
+    ...(hasAuthoredGoal && authoredTracedPaths.length === 0 && goalParseFailure === undefined ? [{
       kind: 'missing-traced-path' as const,
       name: '최종 골의 TRACED PATHS 경로 0',
       detail: '정리 후 보존된 traced 경로가 없다 — 실제 파일 또는 유효한 신설: 파일 경로를 골에 선언해야 발사할 수 있다',
@@ -1347,16 +1365,29 @@ export function decideAskPreflight(
     checkName: 'goal-read',
     targetPath: resolvedGoalFile,
   }] : [];
+  const goalParseBlockers: LaunchPreflightBlocker[] = goalParseFailure ? [{
+    kind: 'goal-unreadable',
+    name: `골 문서 해석 실패: ${opts.goalFile}`,
+    detail: `${goalParseFailure.checkName} 검사가 골 문서를 해석하지 못했다(${goalParseFailure.message}) — 골 판독 실패(goal-unreadable)도 traced path 오류(missing-traced-path)도 아닌 별개 갈래다 · 어느 검사가 막았는지는 checkName 이 가른다 — 골의 TRACED PATHS · 신설: 문면을 바로잡아야 한다`,
+    reasonCode: 'goal-parse' as const,
+    checkName: goalParseFailure.checkName,
+    targetPath: resolvedGoalFile,
+  }] : [];
   const decisionResult = {
     ...result,
-    blockers: [...result.blockers, ...missingTracedPathBlockers, ...goalReadBlockers],
+    // ⛔ 해석 실패를 「대상 경로 0」 문면으로 덮지 않는다 — 사유 코드가 이미 그 자리를 말한다.
+    blockers: [
+      ...result.blockers.filter((blocker) => goalParseFailure === undefined || blocker.kind !== 'no-target-paths'),
+      ...missingTracedPathBlockers, ...goalParseBlockers, ...goalReadBlockers,
+    ],
     warnings: [...result.warnings, ...askMarkerWarnings],
     runningRunsConfidenceAppendix: runningRunsConfidence.appendix,
   };
   emittedAskMarkerObservations.add(decisionResult);
   return {
     result: decisionResult,
-    shouldLaunch: missingTracedPathBlockers.length === 0 && goalReadBlockers.length === 0 && (result.blockers.length === 0 || force),
+    shouldLaunch: missingTracedPathBlockers.length === 0 && goalParseBlockers.length === 0 && goalReadBlockers.length === 0
+      && (result.blockers.length === 0 || force),
     plannedBranchResolution,
   };
 }

package/src/self-dev/orchestrate-cli.ts

@@ -451,6 +451,7 @@ export async function runSelfOrchestrateCliCommand(
       await recordRoundPrs(results);
       results = await superviseRun({
         initial: results,
+        knowhowRepo: deps.repositoryRoot ?? process.cwd(),
         // The add-repair-task branch below runs each authored review-oscillation repair goal as that goal's new
         // feature (a fresh piece, same goal id) — the supervisor records the repair text, so a second oscillation stops.
         repairGoalExecution: true,

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

@@ -9,6 +9,7 @@ export { SUPERVISOR_STOP_REASONS } from './run-types.js';
 import { recordSelfDevRunSupervisorStop, selfDevRunsDir } from './run-store.js';
 import { debug } from '../debug/log.js';
 import { sweepFrozenMerges } from '../self-implement/frozen-merges.js';
+import { selectKnowhowPack } from '../self-implement/knowhow-pack.js';
 import { routeSupervisorVerdict } from './supervisor-verdict-edges.js';
 import type { TaskAgentShadowInput } from '../task-agent/shadow.js';
 import { cardPrNumber, taskAgentStatePath } from '../task-agent/task-hand.js';
@@ -101,6 +102,10 @@ export interface SupervisorDecision {
   action: 'relaunch' | 'add-repair-task' | 'stop';
   stopReason?: SupervisorStopReason;
   why: string;
+  /** Repository lessons pulled at this decision, never appended to a child's goal. */
+  knowhowPackSliceIds?: string[];
+  /** Bounded reference for the supervisor handoff. It is evidence, not an executable child instruction. */
+  knowhowPackReference?: string;
   round: number;
   rerunnable: string[];
   reworkable: string[];
@@ -1027,6 +1032,8 @@ export function patternMineSignaturesFromDecision(decision: SupervisorDecision):
 
 export interface SuperviseRunOptions {
   initial: readonly SupervisorJobResult[];
+  /** Stable repository source for decision-time knowhow; falls back to a result worktree if omitted. */
+  knowhowRepo?: string;
   rerun: (previous: readonly SupervisorJobResult[], invocation: { relaunch: true; repairGoals?: Record<string, string> }) => Promise<readonly SupervisorJobResult[]>;
   limits?: SupervisorLimits;
   enrich?: (results: readonly SupervisorJobResult[]) => readonly SupervisorJobResult[];
@@ -1147,6 +1154,18 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
       } : {}),
     });
 
+    // The supervisor consumes knowhow when it judges a failed piece. Keep the child prompt untouched.
+    const failedPiece = results.find((result) => result.status === 'failed' && result.feature.trim());
+    if (failedPiece) {
+      const repo = opts.knowhowRepo ?? failedPiece.worktreePath;
+      if (repo) {
+        const pulled = selectKnowhowPack(repo, failedPiece.feature);
+        try { opts.observe?.('knowhow-pack-decision', { taskId: failedPiece.taskId, ids: pulled.ids, reason: pulled.reason, action: decision.action }); } catch { /* fail-soft */ }
+        if (pulled.ids.length) decision = { ...decision, knowhowPackSliceIds: pulled.ids, knowhowPackReference: pulled.text,
+          why: `${decision.why} · 판단 참고 노하우 ${pulled.ids.join(',')}` };
+      }
+    }
+
     const runId = opts.runStore?.runId ?? results.find((result) => result.runId?.trim())?.runId ?? null;
 
     let decomposePromotion: DecomposePromotionObservation = decision.decomposable.length === 0

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

@@ -72,6 +72,12 @@ export function ensureDeviceFirstSteps(goal: string, steps: readonly string[], r
   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/'));
+  // ⭐ TDD 를 로직으로(S4) — 문면이 아니라 로직 판정에 필요한 RED→GREEN 기록 필드를 조각 계획에 실어
+  //   넘긴다. 오케스트레이터가 [tdd-red]/[tdd-green] 기록의 태그·같은 명령·결과를 판정한다(문면 유지).
+  const tddRecordFields = 'TDD 기록 필드: 첫 조각 커밋에 피처 시험을 먼저 쓰고 구현 전 실행 RED 기록을 남긴다'
+    + " — 'EVIDENCE: [tdd-red] <무엇을 확인했나> || <증거 명령>' 다음 줄 'RESULT: <실패 요약 한 줄>'"
+    + " · 구현 뒤 같은 명령의 GREEN 기록을 남긴다 — 'EVIDENCE: [tdd-green] <무엇을 확인했나> || <같은 증거 명령>' 다음 줄 'RESULT: <통과 요약 한 줄>'"
+    + ' · 오케스트레이터가 두 기록의 태그·같은 명령·결과를 로직으로 판정하고 없으면 수리 라운드를 돌린다';
   const completeFeatureStage = (stage: string, index: number): string => {
     const withPredecessor = stage.includes(predecessor) ? stage : `${stage}\n${predecessor}`;
     const declaredGoalTest = index === 0 ? goalFeatureTest : undefined;
@@ -87,10 +93,10 @@ export function ensureDeviceFirstSteps(goal: string, steps: readonly string[], r
       ? 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을 확인한다.`;
+    if (!featureTest) return `${withoutWrongPlan}\n검증 계획(TDD): 시험 경로 미확정(${stageSource ? `${stageSource}의 시험 확장자 미정` : '조각 대상 경로 없음'}) · 이 조각에서 시험 경로를 먼저 정하고 RED 실패 뒤 같은 명령으로 GREEN을 확인한다. ${tddRecordFields}`;
     const inventory = root === undefined ? '시험 재고 미측정(대상 루트 미상)'
       : existsSync(join(root, featureTest)) ? '기존 시험' : '신규 시험(이 조각에서 먼저 신설)';
-    return `${withoutWrongPlan}\n검증 계획(TDD): ${inventory} ${featureTest} · 피처 시험 bun test ${featureTest}를 구현 전에 RED로 확인하고 생산 경로를 구현한 뒤 같은 명령으로 GREEN을 확인한다.`;
+    return `${withoutWrongPlan}\n검증 계획(TDD): ${inventory} ${featureTest} · 피처 시험 bun test ${featureTest}를 구현 전에 RED로 확인하고 생산 경로를 구현한 뒤 같은 명령으로 GREEN을 확인한다. ${tddRecordFields}`;
   };
   const targetPaths = [decision.device, test].filter((path) => root !== undefined && existsSync(join(root, path)));
   const newPaths = [decision.device, test].filter((path) => !targetPaths.includes(path));