elanous 0.2.27 → 0.2.29

package/src/self-dev/ask-path-candidates.ts

@@ -1,15 +1,31 @@
 import { execFileSync } from 'node:child_process';
 import { statSync } from 'node:fs';
-import { isAbsolute, relative, resolve } from 'node:path';
+import { basename, extname, isAbsolute, relative, resolve } from 'node:path';
 
 export interface AskPathCandidateOptions {
   readonly cwd: string;
   readonly run?: (command: string, args: readonly string[], options: { cwd: string; encoding: 'utf8' }) => string;
 }
 
-export type AskPathCandidates =
-  | { readonly tokens: string[]; readonly paths: string[]; readonly error?: undefined }
-  | { readonly tokens: string[]; readonly paths: string[]; readonly error: string };
+export interface AskPathCandidates {
+  readonly tokens: string[];
+  readonly paths: string[];
+  readonly evidence?: AskPathEvidence[];
+  readonly selection?: AskPathSelection;
+  readonly error?: string;
+}
+
+export interface AskPathEvidence {
+  readonly path: string;
+  readonly pathTokens: string[];
+  readonly strongestPathMatch: 'explicit-file' | 'filename' | 'directory' | null;
+  readonly contentTokens: string[];
+  readonly score: number;
+}
+
+export type AskPathSelection =
+  | { readonly path: string; readonly reason: 'unique-strongest-evidence' }
+  | { readonly path: null; readonly reason: 'tied-strongest-evidence' };
 
 const STOP_WORDS = new Set(['the', 'and', 'test', 'src', 'scripts', 'file', 'path', 'paths', 'code', 'with', 'from', 'this', 'that', 'into', 'for', 'then', 'when', 'have', 'does', 'should', 'will', 'please', 'target', 'change']);
 const WORD = /[-/]?[A-Za-z][A-Za-z0-9_.-]*(?:\/[A-Za-z0-9_.-]+)*/g;
@@ -63,7 +79,15 @@ function existingFile(fragment: string, cwd: string): string | null {
 
 /** Find existing code paths by lexical evidence from an unmodified ask. */
 export function findAskPathCandidates(askText: string, { cwd, run = execFileSync }: AskPathCandidateOptions): AskPathCandidates {
-  const scores = new Map<string, Set<string>>();
+  const scores = new Map<string, { explicit: Set<string>; filename: Set<string>; directory: Set<string>; content: Set<string> }>();
+  const hitsFor = (path: string) => {
+    let hits = scores.get(path);
+    if (!hits) {
+      hits = { explicit: new Set(), filename: new Set(), directory: new Set(), content: new Set() };
+      scores.set(path, hits);
+    }
+    return hits;
+  };
   const tokens: string[] = [];
   const seen = new Set<string>();
   const body = stripAskWrapper(askText);
@@ -73,11 +97,7 @@ export function findAskPathCandidates(askText: string, { cwd, run = execFileSync
       const raw = match[0];
       const token = raw.replace(/^\//, '');
       const file = existingFile(token, cwd);
-      if (file) {
-        const hits = scores.get(file) ?? new Set<string>();
-        hits.add(token);
-        scores.set(file, hits);
-      }
+      if (file) hitsFor(file).explicit.add(token);
       if (STOP_WORDS.has(token.toLowerCase()) || isGenericToken(token) || seen.has(token)) continue;
       if (!file && !token.includes('/') && !token.includes('.') && !token.includes('-') && !token.includes('_')
         && !/[a-z][A-Z]/.test(token) && token.length < 4) continue;
@@ -85,6 +105,24 @@ export function findAskPathCandidates(askText: string, { cwd, run = execFileSync
       tokens.push(token);
     }
   }
+  if (tokens.length > 0) {
+    let files: string;
+    try {
+      files = run('rg', ['--files', '--glob', '!*.test.ts', 'src', 'scripts'], { cwd, encoding: 'utf8' });
+    } catch (error) {
+      if ((error as { status?: number }).status === 1) files = '';
+      else return { tokens, paths: [], error: error instanceof Error ? error.message : String(error) };
+    }
+    for (const path of files.split(/\r?\n/).filter(Boolean)) {
+      const fileStem = basename(path, extname(path)).toLowerCase();
+      const directories = path.toLowerCase().split('/').slice(0, -1);
+      for (const token of tokens) {
+        const lower = token.toLowerCase();
+        if (fileStem === lower || basename(path).toLowerCase() === lower) hitsFor(path).filename.add(token);
+        else if (directories.includes(lower)) hitsFor(path).directory.add(token);
+      }
+    }
+  }
   for (const token of tokens) {
     let matches: string;
     try {
@@ -94,13 +132,30 @@ export function findAskPathCandidates(askText: string, { cwd, run = execFileSync
       return { tokens, paths: [], error: error instanceof Error ? error.message : String(error) };
     }
     for (const path of matches.split(/\r?\n/).filter(Boolean)) {
-      const hits = scores.get(path) ?? new Set<string>();
-      hits.add(token);
-      scores.set(path, hits);
+      hitsFor(path).content.add(token);
     }
   }
+  const evidence = [...scores].map<AskPathEvidence>(([path, hits]) => {
+    const tier = hits.explicit.size > 0 ? 3 : hits.filename.size > 0 ? 2 : hits.directory.size > 0 ? 1 : 0;
+    return {
+      path,
+      pathTokens: [...new Set([...hits.explicit, ...hits.filename, ...hits.directory])],
+      strongestPathMatch: tier === 3 ? 'explicit-file' : tier === 2 ? 'filename' : tier === 1 ? 'directory' : null,
+      contentTokens: [...hits.content],
+      // Lexicographic tiers: even many directory hits cannot outrank one filename hit.
+      score: tier * 1000 + Math.min(hits.explicit.size + hits.filename.size + hits.directory.size, 9) * 100
+        + Math.min(hits.content.size, 99),
+    };
+  }).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path, 'en'));
+  const top = evidence[0];
   return {
     tokens,
-    paths: [...scores].sort(([a, aHits], [b, bHits]) => bHits.size - aHits.size || a.localeCompare(b, 'en')).slice(0, 5).map(([path]) => path),
+    paths: evidence.slice(0, 5).map(({ path }) => path),
+    ...(top ? {
+      evidence: evidence.slice(0, 5),
+      selection: evidence[1]?.score === top.score
+        ? { path: null, reason: 'tied-strongest-evidence' as const }
+        : { path: top.path, reason: 'unique-strongest-evidence' as const },
+    } : {}),
   };
 }

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

@@ -348,7 +348,31 @@ export interface DecomposeApplication {
  *   ⓐ 같은 goal 을 «두 번» 쪼개지 않는다(alreadyDecomposed)
  *   ⓑ 조각이 둘 미만인 제안은 애초에 안 온다(pickDecomposeProposals 가 거른다)
  *   ⓒ 상한을 넘기면 «쪼개지 않는다» — 조각이 무한히 불어나는 것을 막는다
+ *
+ * ⭐ **조각은 원 골의 «대상 경로:» 머리줄을 물려받는다** (DECOMPOSE-PIECE-TARGET-LINE · 10-11 부검 run-76941fca):
+ *   조각 feature 가 골을 «통째로» 갈아 끼우면 첫 줄 선언이 사라져 Pod 예비 검사가 «대상 경로 0» →
+ *   재저작 NOT-GROUNDED 로 조각 전부가 exit 1 했다. 좁히는 규칙 = 원 선언 경로 중 조각 문장에
+ *   나오는 것만(없으면 원 선언 전부) · «신설:» 줄도 같은 규칙 · 첫 줄이 라벨이 아니면 지금 그대로.
  */
+
+// ── 머리줄 선언을 읽고 좁히는 순수 조각 (위 규칙의 실물) ──────────────────────────
+const TARGET_PATHS_LINE = /^대상 경로:[ \t]*(.*)$/;
+const NEW_PATHS_LINE = /^신설:[ \t]*(.*)$/;
+
+/** 선언 줄의 경로를 나눈다 — « · »·쉼표(`goal-new-paths` 와 같은 분리 규칙). 유효성은 걸러내지 않는다: 선언 그대로다. */
+function splitDeclaredPaths(payload: string): string[] {
+  return payload.split(/[·,]/).map((token) => token.trim()).filter((token) => token.length > 0);
+}
+
+/** 조각 문장에 «나오는» 선언 경로만 남긴다. 하나도 안 나오면 원 선언 전부 — 선언 밖 경로는 지어내지 않는다. */
+function narrowDeclaredPaths(declared: readonly string[], pieceFeature: string): string[] {
+  const mentioned = declared.filter((path) => {
+    const escaped = path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[^\\w./-])${escaped}(?=$|[^\\w./-]|\\.(?:\\s|$))`).test(pieceFeature);
+  });
+  return mentioned.length ? mentioned : [...declared];
+}
+
 export function applyDecomposeProposals(
   goals: readonly SelfDevGoal[],
   results: readonly SelfDevJobResult[],
@@ -374,11 +398,29 @@ export function applyDecomposeProposals(
     // ⛔ 상한을 넘기면 «쪼개지 않는다» — 조용히 자르지 않고 원본을 그대로 둔다.
     if (out.length + pieces.length + (goals.length - out.length - 1) > maxGoals) { out.push(goal); continue; }
     decomposed.push(goal.feature);
+    // 원 골의 머리줄 선언 — 첫 줄이 «대상 경로:» 가 아니면 조각은 지금 그대로(바이트 불변)다.
+    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) {
+      const inherited: string[] = [];
+      let paths: string[] = [];
+      if (targetLine) {
+        const declared = splitDeclaredPaths(targetLine[1]!);
+        paths = declared.length ? narrowDeclaredPaths(declared, piece.feature) : declared;
+        // 선언이 비어 있으면 원 줄을 그대로 실는다 — 라벨만이라도 예비 검사가 읽게 한다.
+        inherited.push(declared.length ? `대상 경로: ${paths.join(' · ')}` : goalLines[0]!);
+      }
+      if (newLine) {
+        const declaredNew = splitDeclaredPaths(newLine[1]!);
+        const narrowedNew = declaredNew.length ? narrowDeclaredPaths(declaredNew, piece.feature) : declaredNew;
+        inherited.push(declaredNew.length ? `신설: ${narrowedNew.join(' · ')}` : newLine[0]!);
+      }
       out.push({
         ...goal,                       // 승격 플래그(openPr·autoReview·autoMerge·base)를 물려받는다
         id: piece.id,
-        feature: piece.feature,
+        feature: inherited.length ? [...inherited, piece.feature].join('\n') : piece.feature,
         ...(piece.dependsOn.length ? { dependsOn: [...piece.dependsOn] } : {}),
         // ⛔⭐ `...goal` 이 «부모의» hotPaths 를 그대로 흘린다 — 그러면 조각 전부가 서로 겹쳐
         //   `orchestrate.ts` 가 전부를 직렬화한다(위상이 아니라 «한 줄»이 된다).

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

@@ -37,6 +37,8 @@ export const JOURNEY_NODE_IDS = [
   'salvage',
   'heal',
   'next-move',
+  'ready',
+  'pr-head-checkout',
   'stopped',
 ] as const;
 export type JourneyNodeId = typeof JOURNEY_NODE_IDS[number];

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

@@ -17,7 +17,7 @@ export interface LiveRunOverlapPath {
 
 /** 검사 대상 한 건이 막힌 이유. `name` 은 사람이 바로 열어 볼 수 있는 식별자다. */
 export interface LaunchPreflightBlocker {
-  readonly kind: 'open-pr' | 'sibling-pr' | 'live-run' | 'no-target-paths' | 'recent-change' | 'ask-outside-path' | 'ask-marker';
+  readonly kind: 'open-pr' | 'sibling-pr' | 'live-run' | 'no-target-paths' | 'missing-traced-path' | 'goal-unreadable' | 'recent-change' | 'ask-outside-path' | 'ask-marker';
   /** `#8100` · `run-6ce5765b…` 처럼 «바로 조회 가능한» 이름. */
   readonly name: string;
   /** 왜 막혔는지 한 줄 — 경로와 수를 포함한다. */
@@ -490,6 +490,10 @@ export function renderLaunchPreflight(
   }
   lines.push(`[preflight] ⛔ 막는 것 ${result.blockers.length}건${forced ? '' : ' — 발사하지 않는다'}`);
   for (const blocker of result.blockers) lines.push(`[preflight]   · ${blocker.name} — ${blocker.detail}`);
+  if (result.blockers.some((blocker) => blocker.kind === 'missing-traced-path' || blocker.kind === 'goal-unreadable')) {
+    lines.push('[preflight] 골 판독 실패 또는 traced path 오류는 --force-preflight 로 우회할 수 없다 — 골 문서와 경로를 바로잡아야 한다');
+    return lines.join('\n');
+  }
   lines.push(forced
     ? '[preflight] ⚠️ --force-preflight — 위 막힘을 «뚫고» 발사한다 (이 우회는 관측에 남는다)'
     : '[preflight] 그래도 가려면 --force-preflight (그 우회는 관측에 남는다) — elanous dev');

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

@@ -17,8 +17,10 @@
 //      ⛔ 그래도 관측·산출에는 «그대로» 남긴다 — 「지나갔다」와 「없었다」는 다른 값이다.
 
 import { execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { isAbsolute, resolve } from 'node:path';
+import { closeSync, existsSync, lstatSync, openSync, readSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, resolve, sep } from 'node:path';
+import { linesOutsideFencedCode } from '../self-implement/goal-author.js';
+import { declaredNewFilePaths } from '../self-implement/goal-new-paths.js';
 import { resolveLogTargets } from '../cli/logs-cli.js';
 import { debug } from '../debug/log.js';
 import { siblingTestPath, normalizePreexistingFailureObservedAt, normalizePreexistingFailureRecords, emitAskMarkerObservation, emittedAskMarkerObservations, setAskMarkerObserver } from './launch-preflight-text.js';
@@ -734,8 +736,9 @@ export interface AskPreflightOptions {
   readonly openPrsLimit?: number;
   /** 중단 런 원장 조회의 최대 반환 행 수. 상한 도달은 결과의 `truncated` 상태로 남는다. */
   readonly interruptedRunsLimit?: number;
-  /** ⛔ 저작 «전» 예비 검사용 — 주면 골 문서를 읽지 않고 이 경로로 판정한다(ask 힌트).
-   *  ⚠️ 이것은 «추정»이다. 정본은 저작된 골의 TRACED PATHS 이고 발사 직전에 다시 판정한다. */
+  /** ⛔ 저작 «전» 예비 검사용 — 충돌 판정에는 이 ask 힌트 경로를 쓴다.
+   *  골 파일이 이미 있으면 문서의 TRACED PATHS 는 별도로 읽어 누락을 검사한다.
+   *  ⚠️ 힌트는 «추정»이다. 정본은 저작된 골의 TRACED PATHS 이고 발사 직전에 다시 판정한다. */
   readonly pathsOverride?: readonly string[];
   /** 원 ask 경로와 최종 대상의 차이를 ask-outside-path 경고에 보인다. */
   readonly askOutsidePathHints?: readonly string[];
@@ -770,6 +773,78 @@ export interface AskPreflightDecision {
   readonly plannedBranchResolution?: PlannedBranchResolution;
 }
 
+/** OP #980: fragments kept by cleanup remain inspectable traced targets, including bare names. */
+function isFileShapedTracedPath(path: string): boolean {
+  return path.trim().length > 0 && (!/\s/.test(path) || path.includes('/'));
+}
+
+// Keep lexical `..`/`.` segments: resolving them first hides ENOTDIR behind a file parent.
+function tracedFsPath(path: string, root: string): string {
+  return isAbsolute(path) ? path : `${root}${root.endsWith(sep) ? '' : sep}${path}`;
+}
+
+function tracedPathExists(path: string, root: string): boolean {
+  try {
+    const target = tracedFsPath(path, root);
+    if (!statSync(target).isFile()) return false;
+    const fd = openSync(target, 'r');
+    try { readSync(fd, Buffer.alloc(1), 0, 1, 0); }
+    finally { closeSync(fd); }
+    return true;
+  }
+  catch { return false; }
+}
+
+function tracedPathIsFile(path: string, root: string): boolean {
+  try { return statSync(tracedFsPath(path, root)).isFile(); }
+  catch { return false; }
+}
+
+function tracedPathOccupation(path: string, root: string): 'occupied' | 'missing' | 'inaccessible' {
+  const target = tracedFsPath(path, root);
+  try { lstatSync(target); return 'occupied'; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') return 'inaccessible';
+    for (let parent = dirname(target); parent !== dirname(parent); parent = dirname(parent)) {
+      try {
+        if (lstatSync(parent).isSymbolicLink()) {
+          try { statSync(parent); } catch { return 'inaccessible'; }
+        }
+      } catch (parentError) {
+        if ((parentError as NodeJS.ErrnoException).code !== 'ENOENT') return 'inaccessible';
+      }
+    }
+    return 'missing';
+  }
+}
+
+/** Remove only malformed TRACED PATHS fragments before the child reads the goal file again. */
+export function discardNonFileTracedPathItems(document: string, _root: string): { document: string; dropped: string[] } {
+  const dropped: string[] = [];
+  let inTracedPaths = false;
+  const outsideStarts = new Set(linesOutsideFencedCode(document).map((line) => line.start));
+  let offset = 0;
+  const lines = document.split('\n').flatMap((line) => {
+    const lineStart = offset;
+    offset += line.length + 1;
+    if (!outsideStarts.has(lineStart)) return [line];
+    const body = line.replace(/\r$/, '');
+    if (/^\s*##\s+TRACED PATHS\s*$/.test(body)) { inTracedPaths = true; return [line]; }
+    if (inTracedPaths && /^\s*#{1,6}\s/.test(body)) inTracedPaths = false;
+    if (!inTracedPaths) return [line];
+    const item = /^(\s*(?:[-*+]|\d+[.)])\s+)(.*)$/.exec(body);
+    if (!item) return [line];
+    // OP #980: a fragment with whitespace and no slash is prose; all other forms stay verbatim.
+    const fragments = item[2]!.split(' · ');
+    const kept = fragments.filter((fragment) => !(/\s/.test(fragment.trim()) && !fragment.includes('/')));
+    if (kept.length === fragments.length) return [line];
+    if (kept.length === 0) { dropped.push(line); return []; }
+    dropped.push(line);
+    return [`${item[1]}${kept.join(' · ')}${line.endsWith('\r') ? '\r' : ''}`];
+  });
+  return { document: lines.join('\n'), dropped };
+}
+
 /** 인자 검증 — ⛔ 잘못된 값을 «조용히» 기본값으로 바꾸지 않는다(리뷰 should-fix). */
 /** ⛔ 기본값은 «내부 상수»다 — 아무도 안 넘기는 인자를 계약 표면으로 두지 않는다(리뷰 must-fix). */
 export const DEFAULT_LIVE_RUN_WINDOW_MINUTES = 30;
@@ -1001,20 +1076,48 @@ export function decideAskPreflight(
 ): AskPreflightDecision {
   const limit = opts.openPrsLimit ?? 200;
   const interruptedRunsLimit = resolveInterruptedRunsLimit(opts.interruptedRunsLimit);
-  // ⛔⭐ 「저작 전 예비 검사」 경로 — 골 파일이 «아직 없다». 그때는 ask 힌트를 대상 경로로 쓴다.
-  //   ⚠️ 골 문서를 읽지 «않는다» — 없는 파일을 읽으려 하면 여기서 던져 저작 자체가 막힌다.
+  // pathsOverride is an independent pre-authoring inspection, even if a stale goal file exists.
   let goalDocument: string | null = null;
   let goalRulersUnknownReason: string | undefined;
+  let goalReadFailed = false;
+  const resolvedGoalFile = opts.declaredPathsRoot?.trim() && !isAbsolute(opts.goalFile)
+    ? resolve(opts.declaredPathsRoot, opts.goalFile)
+    : opts.goalFile;
   if (!opts.pathsOverride) {
     try {
-      goalDocument = deps.readGoalDocument(opts.goalFile);
+      goalDocument = deps.readGoalDocument(resolvedGoalFile);
     } catch (error) {
+      goalReadFailed = true;
       goalRulersUnknownReason = `골 문서 판독 불가: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`;
     }
   } else {
     goalRulersUnknownReason = '저작 전 예비 검사에는 골 문서가 없다';
   }
-  const tracedPaths = opts.pathsOverride ?? (goalDocument === null ? [] : deps.tracedPaths(goalDocument));
+  // Resolve against the caller's root, but keep injected virtual goal documents out of
+  // filesystem checks when no authored file exists there.
+  const hasAuthoredGoal = !opts.pathsOverride && opts.goalFile !== '' && goalDocument !== null
+    && existsSync(resolvedGoalFile);
+  const authoredTracedPaths = goalDocument === null ? [] : deps.tracedPaths(goalDocument);
+  const tracedPathsRaw = opts.pathsOverride ?? authoredTracedPaths;
+  const inspectionRoot = goalDocument === null || !hasAuthoredGoal
+    ? undefined
+    : opts.declaredPathsRoot?.trim() || process.cwd();
+  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 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);
+      if (!isFileShapedTracedPath(path) && occupation !== 'occupied') return [];
+      const isDeclaredNew = declaredNewPaths.has(path.replace(/^\.\//, ''));
+      if (isDeclaredNew) return occupation === 'missing' ? [] : [{ path, reason: occupation === 'occupied' ? 'occupied-new' as const : 'inaccessible' as const }];
+      if (tracedPathExists(path, inspectionRoot)) return [];
+      return [{ path, reason: occupation === 'occupied'
+        ? (tracedPathIsFile(path, inspectionRoot) ? 'inaccessible' as const : 'not-file' as const)
+        : occupation }];
+    })
+    : [];
   let premiseMockedBySignal: number | null = null;
   let invariantFunctionExits: number | null = null;
   if (goalDocument !== null) {
@@ -1197,11 +1300,41 @@ export function decideAskPreflight(
     ...(interruptedRunsUnknownReason ? { interruptedRunsUnknownReason } : {}),
     ...(recentChangesUnknownReason ? { recentChangesUnknownReason } : {}),
   });
-  const decisionResult = { ...result, warnings: [...result.warnings, ...askMarkerWarnings], runningRunsConfidenceAppendix: runningRunsConfidence.appendix };
+  const missingTracedPathBlockers: LaunchPreflightBlocker[] = [
+    ...(hasAuthoredGoal && authoredTracedPaths.length === 0 ? [{
+      kind: 'missing-traced-path' as const,
+      name: '최종 골의 TRACED PATHS 경로 0',
+      detail: '정리 후 보존된 traced 경로가 없다 — 실제 파일 또는 유효한 신설: 파일 경로를 골에 선언해야 발사할 수 있다',
+    }] : []),
+    ...invalidTracedPaths.map(({ path, reason }) => ({
+      kind: 'missing-traced-path' as const,
+      name: reason === 'occupied-new' ? `신설 traced path 가 이미 점유됨: ${path}`
+        : reason === 'not-file' ? `traced path 가 파일이 아님: ${path}`
+          : reason === 'inaccessible' ? `traced path 경로 접근 불가: ${path}` : `실재하지 않는 traced path: ${path}`,
+      detail: reason === 'occupied-new'
+        ? `골의 신설: 경로 ${path} 가 이미 파일·디렉터리·링크로 점유돼 있다 — 새 파일 경로를 바로잡아야 한다`
+        : reason === 'not-file'
+          ? `골의 TRACED PATHS 경로 ${path} 가 존재하지만 읽을 수 있는 파일이 아니다 — 파일 경로를 바로잡아야 한다`
+          : reason === 'inaccessible'
+            ? `골의 TRACED PATHS 경로 ${path} 를 검사할 수 없다 — 부모가 파일이거나 접근 권한이 없다. 경로를 바로잡아야 한다`
+            : `골의 TRACED PATHS 에 선언됐지만 ${inspectionRoot} 에 없고 유효한 신설: 목록에도 없다 — 발사 전에 골 경로를 바로잡아야 한다. 신설은 파일 경로로(확장자 포함) 선언한다`,
+    })),
+  ];
+  const goalReadBlockers: LaunchPreflightBlocker[] = goalReadFailed ? [{
+    kind: 'goal-unreadable',
+    name: `골 문서 판독 불가: ${opts.goalFile}`,
+    detail: `${goalRulersUnknownReason} — 최종 골의 traced path 를 확인할 수 없어 발사를 멈춘다`,
+  }] : [];
+  const decisionResult = {
+    ...result,
+    blockers: [...result.blockers, ...missingTracedPathBlockers, ...goalReadBlockers],
+    warnings: [...result.warnings, ...askMarkerWarnings],
+    runningRunsConfidenceAppendix: runningRunsConfidence.appendix,
+  };
   emittedAskMarkerObservations.add(decisionResult);
   return {
     result: decisionResult,
-    shouldLaunch: result.blockers.length === 0 || force,
+    shouldLaunch: missingTracedPathBlockers.length === 0 && goalReadBlockers.length === 0 && (result.blockers.length === 0 || force),
     plannedBranchResolution,
   };
 }

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

@@ -11,6 +11,7 @@ import { sweepFrozenMerges } from '../self-implement/frozen-merges.js';
 import { routeSupervisorVerdict } from './supervisor-verdict-edges.js';
 import { recordTaskAgentShadowMove, runCardFor, type TaskAgentShadowInput } from '../task-agent/shadow.js';
 import { cardPrNumber, taskAgentStatePath } from '../task-agent/task-hand.js';
+import { classifyMustFixRound, inferMustFixEvidence, type MustFixRoundClassification, type MustFixRoundObservation } from '../self-implement/review-mustfix-class.js';
 
 export interface SupervisorRound {
   round: number;
@@ -46,6 +47,8 @@ export interface SupervisorRound {
    * streak pairs rounds by this key. Omitted on older history — the guard then pairs by taskId as before.
    */
   noPrFeatureKeys?: string[];
+  /** REVIEW-MUSTFIX-CLASSIFY — that round's observed must-fix items; pairs the next round's classification. */
+  mustFix?: MustFixRoundObservation;
 }
 
 /** Failed without a PR — a result that carries either a PR number or a PR URL has one (fixtures and older producers set only one). */
@@ -116,6 +119,10 @@ export interface SupervisorDecision {
   deliverableUnmeasured: boolean;
   deliverableMergeCompleteness: 'unmeasured' | 'complete' | 'incomplete';
   reviewMustFixTrend: ReviewRework['trend'];
+  /** REVIEW-MUSTFIX-CLASSIFY — this round's leading must-fix class (② › ③ observed › ①); omitted when unmeasured (지금 동작 그대로). */
+  mustFix?: MustFixRoundClassification;
+  /** REVIEW-MUSTFIX-CLASSIFY — every oscillating task's measured class, so a mixed round keeps each task's decision. */
+  mustFixByTask?: Record<string, MustFixRoundClassification>;
   oscillation?: { taskIds: string[]; helper: 'review-oscillation'; signature: string; repairGoals?: Record<string, string>; heldTaskIds?: string[] };
   pendingDecision?: 'attempt-care-escalation';
 }
@@ -234,6 +241,41 @@ export function aggregateReviewTrend(results: readonly SelfDevJobResult[]): Revi
   return severity[Math.max(...trends.map((trend) => severity.indexOf(trend)))];
 }
 
+/**
+ * REVIEW-MUSTFIX-CLASSIFY — this round's must-fix observation from the results' verbatim `reviewMustFix`.
+ * Each item carries its `taskId` so the next round pairs per task (one task's recurrence never holds another).
+ */
+function mustFixFromResults(results: readonly SupervisorJobResult[]): MustFixRoundObservation {
+  const items = results.flatMap((result) => (result.reviewMustFix ?? []).map((text) => {
+    const evidence = inferMustFixEvidence(text);
+    return { text, taskId: result.taskId, ...(evidence === undefined ? {} : { evidence }) };
+  }));
+  return items.length > 0 ? { items } : {};
+}
+
+/**
+ * REVIEW-MUSTFIX-CLASSIFY — per-task class. `prev` is the preceding round's items of the same task or its repair
+ * lineage (`oscillationRepairOf`), and only when that preceding round authored a repair for it — «수리 뒤 같은 지적»
+ * means a repair ran between the last observation and this one, not «repaired at any time». Lineage items are
+ * re-scoped to this task so the pure pairing accepts them; unrelated tasks never pair.
+ */
+function classifyTaskMustFix(result: SupervisorJobResult, preceding: SupervisorRound | undefined): MustFixRoundClassification {
+  const pairIds = new Set([result.taskId, ...(result.oscillationRepairOf ? [result.oscillationRepairOf] : [])]);
+  const repairedSincePrev = (preceding?.oscillationRepairTaskIds ?? []).some((id) => pairIds.has(id));
+  const prevItems = repairedSincePrev
+    ? (preceding?.mustFix?.items ?? []).filter((item) => item.taskId !== undefined && pairIds.has(item.taskId))
+      .map((item) => ({ ...item, taskId: result.taskId }))
+    : [];
+  return classifyMustFixRound(prevItems.length > 0 ? { items: prevItems } : undefined, mustFixFromResults([result]));
+}
+
+/**
+ * Classes that hold a task out of this round's same-run repair. Only ② acts in this slice; ③ recurring is
+ * observed (decision `mustFix`/`mustFixByTask` · crossReview suggestion) but behaves as ① — acting on it is a
+ * follow-up cell (REVIEW-MUSTFIX-CLASSIFY partial landing).
+ */
+const MUST_FIX_HELD = new Set<MustFixRoundClassification['class']>(['post-land-evidence']);
+
 export function decideNextRun(input: {
   results: readonly SupervisorJobResult[];
   history?: readonly SupervisorRound[];
@@ -520,8 +562,27 @@ export function decideNextRun(input: {
         || (entry.oscillationRepairFeatures?.[index] !== undefined && entry.oscillationRepairFeatures[index] === result.feature
           && Object.values(entry.oscillationRepairGoals ?? {}).includes(result.feature))));
     // Per task: a task that already got its one oscillation repair is held for a human; a fresh one may get it.
-    const fresh = oscillating.filter((result) => !isRepaired(result));
-    const held = [...new Set(oscillating.filter(isRepaired).map((result) => result.taskId))];
+    // REVIEW-MUSTFIX-CLASSIFY — 슈퍼바이저는 추이 대신 회차 분류를 먼저 본다(대표 10-12 «노하우가 아니라 로직으로» · 임의 임계 없음).
+    //   ① new-defect — 그대로 수렴(진동 수리 유지).
+    //   ② post-land-evidence — 증거는 착지 뒤에만 난다 ⇒ 같은 런 재수리 0, «그림자 착지 → 관측 → live» 쪼개기 결정.
+    //   ③ recurring — 수리 뒤 같은 지적 ⇒ 이 조각에선 관측만(교차 리뷰 제안을 결정에 싣고 동작은 ① 그대로 · 후속 칸).
+    //   unmeasured — 분류 불가 ⇒ 지금 동작 그대로. 분류는 조각마다 — 한 조각의 분류가 다른 조각의 수리를 끊지 않는다.
+    const taskClasses = new Map(oscillating.map((result) => [result.taskId, classifyTaskMustFix(result, preceding)]));
+    const fresh = oscillating.filter((result) => !isRepaired(result) && !MUST_FIX_HELD.has(taskClasses.get(result.taskId)!.class));
+    const classes = [...taskClasses.values()];
+    // Decision-level class: ② (the only acting class) first, then observed ③, else ①.
+    const mustFixClass = classes.find((c) => c.class === 'post-land-evidence') ?? classes.find((c) => c.class === 'recurring')
+      ?? classes.find((c) => c.class === 'new-defect');
+    // Held = already repaired once, or classified ② — either way it never rides this round's rerun.
+    const classHeld = [...new Set(oscillating.filter((result) => !isRepaired(result)
+      && MUST_FIX_HELD.has(taskClasses.get(result.taskId)!.class)).map((result) => result.taskId))];
+    const held = [...new Set([...oscillating.filter(isRepaired).map((result) => result.taskId), ...classHeld])];
+    const repairedHeld = held.filter((id) => !classHeld.includes(id));
+    // Every task's measured class survives in the decision — a mixed round keeps ② split and the observed ③ cross-review suggestion both.
+    const mustFixByTask: Record<string, MustFixRoundClassification> = Object.fromEntries(
+      [...taskClasses].filter(([, c]) => c.class !== 'unmeasured'));
+    const heldReasons = [...new Set(classes.filter((c) => MUST_FIX_HELD.has(c.class)).map((c) => c.reason))];
+    const heldReasonSuffix = heldReasons.length ? ` · ${heldReasons.join(' · ')}` : '';
     const repairGoals: Record<string, string> = Object.fromEntries(fresh.flatMap((result) => {
       const goal = result.prNumber && result.reviewMustFix?.length
         ? authorRepairGoal({ pr: result.prNumber, category: 'review-oscillation', originalRequest: result.feature,
@@ -551,14 +612,16 @@ export function decideNextRun(input: {
       } : {}),
       action,
       ...(action === 'stop' ? { stopReason: 'review-oscillating' as const } : {}),
+      ...(mustFixClass ? { mustFix: mustFixClass } : {}),
+      ...(Object.keys(mustFixByTask).length ? { mustFixByTask } : {}),
       oscillation: { taskIds, helper: 'review-oscillation', signature, ...(Object.keys(repairGoals).length ? { repairGoals } : {}),
         ...(action === 'add-repair-task' && held.length ? { heldTaskIds: held } : {}) },
       pendingDecision: 'attempt-care-escalation',
       why: fresh.length === 0
-        ? `리뷰 진동 반복 — ${signatureOf(oscillating)} · 사람 결정 필요(같은 전략 재발사 금지)`
+        ? `리뷰 진동 반복 — ${signatureOf(oscillating)} · 사람 결정 필요(같은 전략 재발사 금지)${heldReasonSuffix}`
         : cannotRepair
-          ? `리뷰 진동 — ${signatureOf(oscillating)} · ${input.repairGoalExecution === false ? '이 감독 경로가 수리 골 실행을 선언하지 않았다(미선언 또는 불가)' : '수리 원문/PR 관측 불가'} · 사람 결정 필요(같은 전략 재발사 금지)`
-          : `리뷰 진동 — ${signatureOf(fresh)} · review-oscillation 수리 조각을 한 번 붙인다${input.repairGoalExecution === true ? '' : '(실행 배선 미선언 — 결정 칸만)'}${held.length ? ` · 이미 수리한 조각 ${held.join(', ')} 은 사람 결정 대기` : ''}`,
+          ? `리뷰 진동 — ${signatureOf(oscillating)} · ${input.repairGoalExecution === false ? '이 감독 경로가 수리 골 실행을 선언하지 않았다(미선언 또는 불가)' : '수리 원문/PR 관측 불가'} · 사람 결정 필요(같은 전략 재발사 금지)${heldReasonSuffix}`
+          : `리뷰 진동 — ${signatureOf(fresh)} · review-oscillation 수리 조각을 한 번 붙인다${input.repairGoalExecution === true ? '' : '(실행 배선 미선언 — 결정 칸만)'}${repairedHeld.length ? ` · 이미 수리한 조각 ${repairedHeld.join(', ')} 은 사람 결정 대기` : ''}${classHeld.length ? ` · 분류로 보류한 조각 ${classHeld.join(', ')}` : ''}${heldReasonSuffix}`,
     };
   }
 
@@ -588,6 +651,8 @@ export function appendRound(
   const t = triageRun(results.filter((result) => result.salvage !== 'launched'), undefined, false, undefined, mainSyncRelaunchSpent(history));
   const baseCompleted = countBaseCompleted(results);
   const base = roundBase(results);
+  // REVIEW-MUSTFIX-CLASSIFY — 회차 원장에 관측을 실어 다음 회차 짝으로 쓴다(관측 없는 옛 원장은 그대로).
+  const mustFix = mustFixFromResults(results.filter((result) => result.salvage !== 'launched'));
   const noPrResults = results.filter(failedWithoutPr);
   const noPrTaskIds = noPrResults.map((result) => result.taskId);
   const noPrFeatureKeys = noPrResults.map((result) => noPrStreakKey(result.feature));
@@ -597,6 +662,7 @@ export function appendRound(
     ...(baseCompleted > 0 || base !== undefined ? { baseCompleted, ...(base === undefined ? {} : { base }) } : {}),
     actionable: countActionable(t),
     ...(reviewMustFixTrend === undefined ? {} : { reviewMustFixTrend }),
+    ...((mustFix.items ?? []).length > 0 ? { mustFix } : {}),
     ...(results.some((result) => result.rework?.signature)
       ? { signatures: Object.fromEntries(results.filter((result) => result.rework?.signature).map((result) => [result.taskId, result.rework!.signature])) } : {}),
     ...(decision && decision.action !== 'stop' && decision.relaunchOnMain.length > 0 ? {

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

@@ -16,6 +16,8 @@ export interface GateShardAttempt {
   baselineExitCode: number | null;
   currentSignal?: string | null;
   baselineSignal?: string | null;
+  currentDiagnostic?: string;
+  baselineDiagnostic?: string;
   /** LIGHT-RC-MEASURE — the shard files that exist in the baseline tree, i.e. what the baseline side actually ran.
    *  Absent = every shard file (the old shape). Empty = the baseline side was not run and contributes zero cases. */
   baselineFiles?: readonly string[];

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

@@ -1,7 +1,7 @@
 import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { debug } from '../debug/log.js';
+import { debug, redactSecretText } from '../debug/log.js';
 import { prepareDeterministicChildEnvironment } from '../../scripts/lib/deterministic-env.js';
 import { withBaselineWorktree } from '../self-implement/gate-baseline.js';
 import { aggregateGateTestShards, type GateShardAttempt, type GateShardAggregate } from './shard-aggregate.js';
@@ -21,8 +21,25 @@ export type ShardProcess = (cwd: string, files: readonly string[]) => {
   junit?: string;
   rssMb?: number;
   seconds?: number;
+  /** Bounded, redacted process output for an abnormal exit before JUnit exists. */
+  diagnostic?: string;
 };
 
+const DIAGNOSTIC_STREAM_LIMIT = 240;
+
+function boundedDiagnostic(stdout: Uint8Array, stderr: Uint8Array): string | undefined {
+  const oneStream = (bytes: Uint8Array): string => {
+    const safe = redactSecretText(Buffer.from(bytes).toString('utf8')).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').trim();
+    if (safe.length <= DIAGNOSTIC_STREAM_LIMIT) return safe;
+    // Bun can print the cause after a long preamble; keep both ends within the same bound.
+    const head = Math.floor((DIAGNOSTIC_STREAM_LIMIT - 1) / 2);
+    return `${safe.slice(0, head)}…${safe.slice(-(DIAGNOSTIC_STREAM_LIMIT - 1 - head))}`;
+  };
+  const out = oneStream(stdout);
+  const err = oneStream(stderr);
+  return [out && `stdout: ${out}`, err && `stderr: ${err}`].filter(Boolean).join(' · ') || undefined;
+}
+
 /** Absent only when the path provably is not a file there (missing, or not a regular file); any other stat error
  *  (permissions …) is not evidence of absence, so the file stays in the baseline run (fail-closed: unmeasured). */
 const absentAtBaseline = (path: string): boolean => {
@@ -102,6 +119,7 @@ export function runShardedGateTests(
           currentJUnit: current.junit, baselineJUnit: base.junit,
           currentExitCode: current.exitCode, baselineExitCode: base.exitCode,
           currentSignal: current.signal, baselineSignal: base.signal,
+          currentDiagnostic: current.diagnostic, baselineDiagnostic: base.diagnostic,
           baselineFiles,
         });
       }
@@ -125,10 +143,13 @@ export function runBunShard(cwd: string, files: readonly string[]): ReturnType<S
     const result = Bun.spawnSync(['bun', ...args], {
       cwd, env: isolated.env, stdout: 'pipe', stderr: 'pipe', timeout: 300_000,
     });
+    const junit = existsSync(report) ? readFileSync(report, 'utf8') : undefined;
     return {
       exitCode: result.exitCode,
       signal: result.signalCode ? String(result.signalCode) : undefined,
-      junit: existsSync(report) ? readFileSync(report, 'utf8') : undefined,
+      junit,
+      ...(junit === undefined && (result.exitCode !== 0 || result.signalCode)
+        ? { diagnostic: boundedDiagnostic(result.stdout, result.stderr) } : {}),
       rssMb: measured ? result.resourceUsage.maxRSS / (1024 * 1024) : undefined,
       seconds: measured ? (performance.now() - started) / 1000 : undefined,
     };