elanous 0.2.35 → 0.2.37

package/src/self-implement/goal-elaborate.ts

@@ -24,6 +24,9 @@ export interface GoalFixedLayer {
   invariants: string[];
   /** 불변식 문면에서 «바꾸지 않는다/금지» 절에 실린 경로 — 카드가 건드리면 위반이다. */
   protectedPaths: string[];
+  /** ELABORATION-PROTECTED-PATH-INVERSION — 골이 «고치라고» 준 경로(대상 경로·신설·증거 명령의 파일).
+   *  이 경로는 불변식 문면에 같이 나와도 보호 구역이 되지 않는다(대상을 수정 금지로 뒤집지 않는다). */
+  targetPaths: string[];
 }
 
 export interface ElaborationCard {
@@ -37,17 +40,74 @@ export interface ElaborationCard {
 
 export type ElaborationOutcome =
   | { status: 'elaborated'; card: ElaborationCard; cardSha: string; fileCount: number; level: InjectionLevel; attempts: number; judge: 'llm' | 'deterministic-only'; judgeErrors?: string[]; fixedLayerEmpty?: boolean }
-  | { status: 'needs-human'; attempts: number; violations: string[]; cardSha: string }
+  | { status: 'needs-human'; reason: ElaborationFailureReason; attempts: number; violations: string[]; cardSha: string }
   | { status: 'skipped'; reason: 'no-provider' | 'provider-failed' | 'card-unparseable'; attempts: number; error?: string };
 
 const MAX_LINES = 20;
 const MAX_LINE_CHARS = 300;
 const MAX_CARD_FILES = 30;
+export type ElaborationFailureReason = 'goal-elaboration-ungrounded-path' | 'goal-elaboration-protected-path'
+  | 'goal-elaboration-scope-conflict' | 'goal-elaboration-fixed-layer-conflict';
+
+function failureReason(violations: readonly string[]): ElaborationFailureReason {
+  if (violations.some((violation) => violation.startsWith('ungrounded path:'))) return 'goal-elaboration-ungrounded-path';
+  if (violations.some((violation) => violation.startsWith('protected path:'))) return 'goal-elaboration-protected-path';
+  // 판정기 자유 문면의 "KPI 범위 약화"는 확장 수복 대상이 아니다. 구조화된 kind=scope만 인정한다.
+  if (violations.some((violation) => violation.startsWith('scope expansion:'))) return 'goal-elaboration-scope-conflict';
+  return 'goal-elaboration-fixed-layer-conflict';
+}
+
+function repairInstruction(reason: ElaborationFailureReason, fixed: GoalFixedLayer): string {
+  switch (reason) {
+    case 'goal-elaboration-ungrounded-path':
+      return `없는 경로를 다시 접지한다. 저장소에 있는 파일이나 골에 명시된 대상 경로만 고르고, 새 파일은 골이 신설을 요구할 때만 newFiles에 적는다. 대상 경로: ${fixed.targetPaths.join(', ') || '(명시 없음)'}`;
+    case 'goal-elaboration-protected-path':
+      return `보호 경로를 카드에서 빼고 골의 대상 경로 안에서만 구현한다.${fixed.protectedPaths.length ? ` 보호 경로: ${fixed.protectedPaths.join(', ')}` : ' 위반 목록의 보호 경로 지적을 확인한다.'}`;
+    case 'goal-elaboration-scope-conflict':
+      return '범위 확장을 좁힌다. 골의 대상과 완료 경계를 유지하고 새 기능이나 새 판정 조건을 더하지 않는다.';
+    case 'goal-elaboration-fixed-layer-conflict':
+      return '고정 층의 방향·KPI·불변식을 보존한다. 지적된 문장만 고치고 완료 조건을 약화하지 않는다.';
+  }
+}
 const KPI_LINE = /판정 신호|수용선|완료 경계|증거 명령|KPI|acceptance|verify:|반증/i;
 const INVARIANT_LINE = /불변|경계:|⛔|바꾸지 않는다|하지 않는다|금지|보호|invariant|must not|do not/i;
 const DIRECTION_LINE = /^(?:[-*]\s*)?(?:바꿀 것|목표|무엇|왜|현재 계약|Goal|Why|What)\s*[:：]/i;
 const PROHIBITION = /바꾸지 않는다|건드리지 않는다|하지 않는다|금지|보호|⛔|must not|do not (?:touch|modify|change)/i;
 const PATH_TOKEN = /[\w@.-]+(?:\/[\w@.-]+)*\.(?:ts|tsx|js|mjs|cjs|json|ya?ml|md|sh)\b/g;
+/** 골이 바꾸라고 준 경로가 실리는 줄 — 대상 경로 · 신설 · 증거 명령(bun test <파일>). */
+//   ⛔ «줄 처음 ⊕ 콜론» 고정 — 경계 줄 안의 «…판정 신호 불변…» 을 대상 줄로 읽으면 보호 경로가 빠진다.
+//   ① 대상·신설 줄 = 그 줄의 모든 경로 ② 증거 명령·판정 신호·현재 계약 줄 = `bun test` 바로 뒤 시험 파일만
+//      (그 줄의 «goal-author.ts 는 바꾸지 않는다» 같은 보호 경로를 대상으로 빼지 않게 · r1 must-fix).
+const TARGET_LINE = /^(?:[-*]\s*)?(?:대상 경로|대상|신설|새 파일|target paths?|files?)\s*[:：]/i;
+const COMMAND_LINE = /^(?:[-*]\s*)?(?:완료 경계 증거 명령|증거 명령|판정 신호|현재 계약)\s*[:：]/i;
+const BUN_TEST_HEAD = /bun test\s+/g;
+/** `bun test` 인자 — 경로 꼴 토큰이 끊기는 곳(`·`·문장·`→`)에서 멈추고 시험 파일만 낸다(r2 must-fix). */
+export function bunTestPathArgs(line: string): string[] {
+  const out: string[] = [];
+  for (const head of line.matchAll(BUN_TEST_HEAD)) {
+    const rest = line.slice(head.index! + head[0].length).split(/\s+/);
+    for (const raw of rest) {
+      // 따옴표·백틱으로 감싼 인자도 시험 파일이다(r3 must-fix) — 짝이 맞는 감싸기만 벗긴다.
+      const tok = /^(["'`])(.*)\1$/.exec(raw)?.[2] ?? raw;
+      if (tok.startsWith('-')) continue;
+      if (!/^[\w@./-]+$/.test(tok)) break;
+      if (/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(tok)) out.push(tok);
+    }
+  }
+  return out;
+}
+/** 경로 바로 뒤가 «의 …»·«안의 …»·«'s …» 면 그 금지는 파일 «안의 내용»(기존 단언·동작·계약)에 대한 것이다. */
+const CONTENT_SCOPED = /^\s*(?:의|안의|에 있는|속)\s|^'s\s|^\s+(?:existing|assertions?|behaviou?r|contract)\b/i;
+/** 형식이 안 맞아 «검증 불가»로 처리된 경계 줄 — 금지 불변식으로 격상하지 않는다(10-22 실물). */
+const UNVERIFIABLE_LINE = /UNVERIFIABLE|검증 불가|형식 불일치/i;
+/** 사람이 쓴 경계 줄 — 대상 경로를 보호로 이길 수 있는 유일한 자리. */
+const BOUNDARY_LINE = /^(?:[-*]\s*)?경계\s*[:：]/;
+/** 경로 «바로 뒤»가 «는/를 바꾸지 않는다» 꼴일 때만 경로 자체 금지다 — «X 를 수정하되 기존 단언은 바꾸지 않는다» 는 아니다(r1 must-fix). */
+const BARE_PATH_PROHIBITION = /^\s*(?:파일)?\s*(?:은|는|을|를|도)?\s*(?:(?:바꾸|건드리|수정하|고치|변경하)지\s*않는다|(?:수정|변경)\s*금지)/;
+
+function samePathOrSuffix(a: string, b: string): boolean {
+  return a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`);
+}
 
 function clip(lines: string[]): string[] {
   return lines.slice(0, MAX_LINES).map((line) => (line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}…` : line));
@@ -57,17 +117,46 @@ function clip(lines: string[]): string[] {
 export function extractGoalFixedLayer(goal: string): GoalFixedLayer {
   const lines = goal.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
   const kpi = lines.filter((line) => KPI_LINE.test(line));
-  const invariants = lines.filter((line) => INVARIANT_LINE.test(line));
+  const invariants = lines.filter((line) => INVARIANT_LINE.test(line) && !UNVERIFIABLE_LINE.test(line));
+  const targetPaths = new Set<string>();
+  for (const line of lines.filter((l) => TARGET_LINE.test(l))) {
+    // 대상 줄 안의 금지 절(«· X 는 바꾸지 않는다»)은 대상이 아니다 — 보호로 남긴다(r4 must-fix). 쪼개기는 보호 구역과 같은 규칙.
+    for (const clause of line.split(/[·;,]|\s-\s/)) {
+      if (PROHIBITION.test(clause)) continue;
+      for (const match of clause.matchAll(PATH_TOKEN)) targetPaths.add(match[0]);
+    }
+  }
+  /** 증거·판정 명령이 «돌리라고» 준 시험 파일 — 어떤 금지 줄로도 보호 구역이 되지 않는다(TA-REMOTE-MIRROR-BIND 10-22). */
+  const evidencePaths = new Set<string>();
+  for (const line of lines.filter((l) => COMMAND_LINE.test(l))) {
+    for (const path of bunTestPathArgs(line)) { targetPaths.add(path); evidencePaths.add(path); }
+  }
   let direction = lines.filter((line) => DIRECTION_LINE.test(line));
-  if (!direction.length) direction = lines.filter((line) => !kpi.includes(line) && !invariants.includes(line)).slice(0, 3);
+  // UNVERIFIABLE 경계 줄은 방향 대체값으로도 고정 층에 들이지 않는다(r6 — 판정기 프롬프트에 «X 수정 금지»가 되살아났다).
+  if (!direction.length) direction = lines.filter((line) => !kpi.includes(line) && !invariants.includes(line) && !UNVERIFIABLE_LINE.test(line)).slice(0, 3);
   const protectedPaths = new Set<string>();
+  const explicitlyProtected = new Set<string>();
   for (const line of invariants) {
     for (const clause of line.split(/[·;,]|\s-\s/)) {
       if (!PROHIBITION.test(clause)) continue;
-      for (const match of clause.matchAll(PATH_TOKEN)) protectedPaths.add(match[0]);
+      for (const match of clause.matchAll(PATH_TOKEN)) {
+        const isTarget = [...targetPaths].some((target) => samePathOrSuffix(match[0], target));
+        if (isTarget) {
+          // 골이 고치거나 돌리라고 준 파일(대상·신설·증거 시험)은 «추론»으로 보호되지 않는다 —
+          //   저작기가 덧붙인 분해 인용·«단정하지 않는다» 같은 동작 금지 문장이 같은 절의 대상까지 보호로 뒤집었다(TA-REMOTE-MIRROR-BIND 10-22).
+          //   ⛔ 이기는 것은 사람이 쓴 «경계:» 줄의 맨 «X 는 바꾸지 않는다»(경로 자체 금지)뿐이고, 증거 명령의 시험 파일은 그것으로도 안 막는다(r5 ⊕ 이번 변종).
+          //   «X 의 기존 단언·동작은 바꾸지 않는다» 는 «내용» 금지다 — 파일은 고친다(10-22 밤샘 parked 다수의 뒤집힘).
+          const pathLevel = BOUNDARY_LINE.test(line) && BARE_PATH_PROHIBITION.test(clause.slice(match.index! + match[0].length));
+          const isEvidence = [...evidencePaths].some((path) => samePathOrSuffix(match[0], path));
+          if (!pathLevel || isEvidence) continue;
+          explicitlyProtected.add(match[0]);
+        }
+        protectedPaths.add(match[0]);
+      }
     }
   }
-  return { direction: clip(direction), kpi: clip(kpi), invariants: clip(invariants), protectedPaths: [...protectedPaths] };
+  const targets = [...targetPaths].filter((target) => ![...explicitlyProtected].some((p) => samePathOrSuffix(p, target)));
+  return { direction: clip(direction), kpi: clip(kpi), invariants: clip(invariants), protectedPaths: [...protectedPaths], targetPaths: targets };
 }
 
 function stringList(value: unknown): string[] | undefined {
@@ -132,7 +221,7 @@ export function checkCardAgainstFixedLayer(card: ElaborationCard, fixed: GoalFix
   const paths = [...new Set([...card.files, ...card.newFiles, card.firstTest.path])];
   for (const path of paths) {
     const hit = fixed.protectedPaths.find((protectedPath) => touchesProtected(path, protectedPath));
-    if (hit) violations.push(`protected path: ${path} (goal invariant forbids changing ${hit})`);
+    if (hit) violations.push(protectedPathViolation(path, hit));
     else if (!card.newFiles.includes(path) && !fileExists(path)) violations.push(`ungrounded path: ${path} does not exist and is not listed in newFiles`);
   }
   return violations;
@@ -145,12 +234,12 @@ function section(title: string, lines: string[]): string {
   return [`### ${title}`, ...(lines.length ? lines.map((line) => `- ${line}`) : ['- (없음)'])].join('\n');
 }
 
-function buildCardPrompt(goal: string, context: string, fixed: GoalFixedLayer, previousViolations: string[] = []): string {
+function buildCardPrompt(goal: string, context: string, fixed: GoalFixedLayer, previousViolations: string[] = [], repair?: string): string {
   return [
     '## 할 일 — 착수 구체화 카드(E1)',
     '아래 골을 구현하기 전에, 저장소 맥락을 근거로 «구체화 카드»를 쓴다. 고정 층(방향·KPI·불변식·보호 구역)은 바꾸지 않는다 — 카드는 «어디서부터 어떻게» 만 정한다.',
     'JSON 형식: {"files": [실제 건드릴 경로], "newFiles": [그중 새로 만들 경로], "requirements": [세부 요구], "firstTest": {"path": 시험 파일, "name": 시험 이름, "redReason": 지금 왜 실패하는가}, "stage": "unit|integration|live", "level": "L0|L1|L2|L3|L4"(주입 사다리 층)}',
-    ...(previousViolations.length ? ['', '## 앞 카드가 고정 층과 어긋났다 — 고쳐 다시 쓴다', ...previousViolations.map((v) => `- ${v}`)] : []),
+    ...(previousViolations.length ? ['', '## 앞 카드가 고정 층과 어긋났다 — 이 사유로 딱 한 번 고쳐 다시 쓴다', ...(repair ? [repair] : []), ...previousViolations.map((v) => `- ${v}`)] : []),
     '',
     '## 고정 층(바꾸지 않는다)',
     section('방향', fixed.direction),
@@ -166,7 +255,9 @@ function buildCardPrompt(goal: string, context: string, fixed: GoalFixedLayer, p
 function buildJudgePrompt(fixed: GoalFixedLayer, card: ElaborationCard): string {
   return [
     '카드가 고정 층과 «맞는지만» 본다. 카드가 KPI·판정 신호를 약화·삭제·대체하거나, 방향을 바꾸거나, 불변식·보호 구역을 어기면 불일치다. 구현 방법의 좋고 나쁨은 판정하지 않는다.',
-    'JSON 형식: {"consistent": true|false, "violations": [어긋난 점]}',
+    'JSON 형식: {"consistent": true|false, "violations": [{"kind": "path"|"content"|"scope", "path": "<경로 · path 일 때>", "text": "<어긋난 점>"}]}',
+    'kind=path = 그 경로를 «건드리는 것 자체»가 금지라는 지적 · kind=content = 기존 단언·동작·계약·KPI 를 바꾸거나 약화했다는 지적 · kind=scope = 골 밖의 새 기능으로 범위를 확장했다는 지적.',
+    ...(fixed.targetPaths.length ? [`대상 경로(골이 고치라고 준 파일 · 건드리는 것 자체는 위반 아님 · 그 안의 기존 계약을 바꾸면 content 위반): ${fixed.targetPaths.join(', ')}`] : []),
     '',
     section('방향', fixed.direction),
     section('KPI·판정 신호', fixed.kpi),
@@ -177,11 +268,55 @@ function buildJudgePrompt(fixed: GoalFixedLayer, card: ElaborationCard): string
   ].join('\n');
 }
 
-function parseJudge(text: string): { consistent: boolean; violations: string[] } | undefined {
+type JudgeViolation = { kind: 'path' | 'content' | 'scope' | 'unknown'; path?: string; text: string };
+
+const PROTECTED_PATH_PREFIX = 'protected path:';
+function protectedPathViolation(path: string, protectedPath: string): string {
+  return `${PROTECTED_PATH_PREFIX} ${path} (goal invariant forbids changing ${protectedPath})`;
+}
+
+function legacyProtectedPath(text: string): string | undefined {
+  const trimmed = text.trim();
+  if (!trimmed.toLowerCase().startsWith(PROTECTED_PATH_PREFIX)) return undefined;
+  const match = /^(\S+?)(?:\s+\(goal invariant forbids changing\s+(\S+)\))?\.?$/i.exec(trimmed.slice(PROTECTED_PATH_PREFIX.length).trim());
+  return match && (!match[2] || match[1] === match[2]) ? match[1] : undefined;
+}
+
+/** 판정기 지적이 «대상 경로를 건드리는 것 자체»(kind=path)인가 — 문구가 아니라 판정기가 낸 «종류»로 가른다(r2 must-fix).
+ *  ⛔ content·종류 없음(옛 문자열 꼴)은 버리지 않는다 — 기존 단언·동작·계약 위반은 문구와 무관하게 남는다. */
+function isTargetInversion(violation: JudgeViolation, targetPaths: readonly string[]): boolean {
+  // 이전 판정기는 kind 없이 결정론 검사와 똑같은 보호 경로 문장을 돌려주기도 했다
+  // (FIRST10-GATE: 신설 scripts/first10-gate.test.ts). 정확한 경로 수준 문법만 복구한다.
+  // 명시적 content 지적은 문구가 비슷해도 기존 계약 위반일 수 있으므로 버리지 않는다.
+  const legacy = violation.kind === 'unknown' ? legacyProtectedPath(violation.text) : undefined;
+  const path = violation.kind === 'path' ? violation.path
+    : legacy;
+  if (!path) return false;
+  return targetPaths.some((target) => samePathOrSuffix(path, target));
+}
+
+function judgeViolations(value: unknown): JudgeViolation[] {
+  if (!Array.isArray(value)) return [];
+  const out: JudgeViolation[] = [];
+  for (const item of value) {
+    if (typeof item === 'string') { if (item.trim()) out.push({ kind: 'unknown', text: item }); continue; }
+    if (!item || typeof item !== 'object') continue;
+    const rec = item as Record<string, unknown>;
+    const text = typeof rec.text === 'string' && rec.text.trim() ? rec.text : JSON.stringify(rec);
+    const kind = rec.kind === 'path' || rec.kind === 'content' || rec.kind === 'scope' ? rec.kind : 'unknown';
+    out.push({ kind, text, ...(typeof rec.path === 'string' && rec.path.trim() ? { path: rec.path.trim() } : {}) });
+  }
+  return out;
+}
+
+function parseJudge(text: string): { consistent: boolean; violations: JudgeViolation[] } | undefined {
   const raw = lastJsonObject(text) as Record<string, unknown> | undefined;
   if (!raw || typeof raw.consistent !== 'boolean') return undefined;
-  const violations = stringList(raw.violations ?? []) ?? [];
-  return { consistent: raw.consistent && violations.length === 0, violations: raw.consistent ? violations : violations.length ? violations : ['judge reported inconsistency'] };
+  const violations = judgeViolations(raw.violations ?? []);
+  return {
+    consistent: raw.consistent && violations.length === 0,
+    violations: raw.consistent ? violations : violations.length ? violations : [{ kind: 'unknown', text: 'judge reported inconsistency' }],
+  };
 }
 
 function cardSha(card: ElaborationCard): string {
@@ -198,21 +333,26 @@ function errorText(error: unknown): string {
  */
 export async function elaborateGoalOnArrival(
   input: { goal: string; context?: string; fileExists: (path: string) => boolean },
-  deps: { callLLM?: ElaborationCallLLM; maxRewrites?: number },
+  deps: { callLLM?: ElaborationCallLLM; maxRewrites?: number; observe?: (event: string, data: Record<string, unknown>) => void },
 ): Promise<ElaborationOutcome> {
   if (!deps.callLLM) return { status: 'skipped', reason: 'no-provider', attempts: 0 };
   const fixed = extractGoalFixedLayer(input.goal);
-  const maxAttempts = 1 + Math.max(0, deps.maxRewrites ?? 1);
+  // 같은 결함으로 LLM을 계속 부르지 않는다. 과도한 호출자 설정을 조용히 무시하지 않는다.
+  if (deps.maxRewrites !== undefined && deps.maxRewrites !== 0 && deps.maxRewrites !== 1) {
+    throw new RangeError('goal elaboration maxRewrites must be 0 or 1');
+  }
+  const maxAttempts = 1 + (deps.maxRewrites ?? 1);
   const fixedLayerEmpty = !fixed.kpi.length && !fixed.invariants.length;
   /** 다시 쓰기 프롬프트에 실을 앞 회차의 문제(판독 실패 포함). */
   let feedback: string[] = [];
+  let repair: string | undefined;
   /** 고정 층 위반은 «판독된 카드»에만 귀속한다 — 해시와 위반이 같은 카드를 가리킨다. */
-  let lastRejected: { sha: string; violations: string[] } | undefined;
+  let lastRejected: { sha: string; violations: string[]; reason: ElaborationFailureReason } | undefined;
   const judgeErrors: string[] = [];
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     let text: string;
     try {
-      text = await deps.callLLM({ prompt: buildCardPrompt(input.goal, input.context ?? '', fixed, feedback), systemPrompt: CARD_SYSTEM });
+      text = await deps.callLLM({ prompt: buildCardPrompt(input.goal, input.context ?? '', fixed, feedback, repair), systemPrompt: CARD_SYSTEM });
     } catch (error) {
       return { status: 'skipped', reason: 'provider-failed', attempts: attempt, error: errorText(error) };
     }
@@ -230,7 +370,14 @@ export async function elaborateGoalOnArrival(
         const verdict = parseJudge(await deps.callLLM({ prompt: buildJudgePrompt(fixed, card), systemPrompt: JUDGE_SYSTEM }));
         if (verdict) {
           judge = 'llm';
-          if (!verdict.consistent) violations = verdict.violations;
+          if (!verdict.consistent) {
+            // 판정기가 «대상 경로를 건드렸다 = 보호 구역 위반»이라고 하면 그 지적은 뒤집힘이다 — 버리고 관측에 남긴다.
+            const inverted = verdict.violations.filter((v) => isTargetInversion(v, fixed.targetPaths));
+            if (inverted.length) judgeErrors.push(`judge-target-inversion-dropped: ${inverted.length}`);
+            violations = verdict.violations.filter((v) => !isTargetInversion(v, fixed.targetPaths))
+              .map((v) => v.kind === 'scope' ? `scope expansion: ${v.text}`
+                : v.kind === 'content' ? `content violation: ${v.text}` : v.text);
+          }
         } else judgeErrors.push('judge-unparseable');
       } catch (error) {
         // 판정기 실패는 결정론 대조만으로 — 카드는 고정 층을 다시 쓰지 않는다. 실패 사실은 관측에 남긴다.
@@ -241,11 +388,16 @@ export async function elaborateGoalOnArrival(
       return { status: 'elaborated', card, cardSha: sha, fileCount: card.files.length, level: card.level, attempts: attempt, judge,
         ...(judgeErrors.length ? { judgeErrors } : {}), ...(fixedLayerEmpty ? { fixedLayerEmpty } : {}) };
     }
-    lastRejected = { sha, violations };
+    const reason = failureReason(violations);
+    lastRejected = { sha, violations, reason };
     feedback = violations;
+    if (attempt < maxAttempts) {
+      repair = [...new Set(violations.map((violation) => failureReason([violation])))].map((kind) => repairInstruction(kind, fixed)).join('\n');
+      deps.observe?.('goal-elaboration-self-heal', { reason, attempt, cardSha: sha, violations });
+    }
   }
   if (!lastRejected) return { status: 'skipped', reason: 'card-unparseable', attempts: maxAttempts, error: feedback[0] };
-  return { status: 'needs-human', attempts: maxAttempts, violations: lastRejected.violations, cardSha: lastRejected.sha };
+  return { status: 'needs-human', reason: lastRejected.reason, attempts: maxAttempts, violations: lastRejected.violations, cardSha: lastRejected.sha };
 }
 
 export function renderElaborationCard(card: ElaborationCard, sha: string): string {
@@ -275,8 +427,10 @@ export async function runArrivalElaboration(input: {
   const fileExists = input.fileExists ?? ((path: string) => existsSync(join(input.cwd ?? process.cwd(), path)));
   let outcome: ElaborationOutcome;
   try {
-    outcome = await elaborateGoalOnArrival({ goal: input.goal, context: input.prompt, fileExists }, { callLLM: input.callLLM });
+    outcome = await elaborateGoalOnArrival({ goal: input.goal, context: input.prompt, fileExists }, { callLLM: input.callLLM,
+      observe: (event, data) => input.observe(event, data, { level: 'warn' }) });
   } catch (error) {
+    if (error instanceof RangeError && error.message === 'goal elaboration maxRewrites must be 0 or 1') throw error;
     outcome = { status: 'skipped', reason: 'provider-failed', attempts: 0, error: errorText(error) };
   }
   if (outcome.status === 'elaborated') {
@@ -287,8 +441,8 @@ export async function runArrivalElaboration(input: {
     return { prompt: `${input.prompt}\n\n${renderElaborationCard(outcome.card, outcome.cardSha)}`, parked: false };
   }
   if (outcome.status === 'needs-human') {
-    input.observe('goal-elaboration-needs-human', { outcome: 'needs-human', attempts: outcome.attempts, violations: outcome.violations, cardSha: outcome.cardSha }, { level: 'warn' });
-    return { prompt: input.prompt, parked: true, detail: `goal-elaboration needs-human: ${outcome.violations.join(' | ').slice(0, 500)}` };
+    input.observe('goal-elaboration-needs-human', { outcome: 'needs-human', reason: outcome.reason, attempts: outcome.attempts, violations: outcome.violations, cardSha: outcome.cardSha }, { level: 'warn' });
+    return { prompt: input.prompt, parked: true, detail: `goal-elaboration needs-human: ${outcome.reason} (attempts: ${outcome.attempts}) · ${outcome.violations.join(' | ').slice(0, 500)}` };
   }
   input.observe('goal-elaboration-skipped', { outcome: 'skipped', reason: outcome.reason, attempts: outcome.attempts, ...(outcome.error ? { error: outcome.error } : {}) }, outcome.reason === 'no-provider' ? undefined : { level: 'warn' });
   return { prompt: input.prompt, parked: false };

package/src/self-implement/goal-refine.ts

@@ -177,6 +177,8 @@ export interface FirstRoundEvidence {
   findings?: string;
   /** 첫 라운드가 실제로 건드린 파일. */
   changedFiles?: readonly string[];
+  /** SCOPE-ESCAPE-AS-REFINE — 대상 경로 밖에서 바뀌었고 수용된 파일(«구현이 알려준 새 범위» · 실패 아님). */
+  newScope?: readonly string[];
 }
 
 /** 내부 — 시험은 refineGoalFromFirstRound 가 LLM 에 넘긴 프롬프트로 본다. */
@@ -195,6 +197,7 @@ function buildRegroundingPrompt(v1: string, evidence: FirstRoundEvidence): strin
     '## 첫 라운드 실전',
     `- 자식 요약: ${(evidence.implSummary ?? '').replace(/\s+/g, ' ').trim().slice(0, 600) || '(없음)'}`,
     `- 건드린 파일: ${evidence.changedFiles?.length ? evidence.changedFiles.slice(0, 40).join(', ') : '(관측 없음)'}`,
+    ...(evidence.newScope?.length ? [`- 구현이 알려준 새 범위(대상 경로 밖 편집 · 실패 아님 · 예상 구역에 넣을지 판단): ${evidence.newScope.slice(0, 40).join(', ')}`] : []),
     '### gate·리뷰 지적',
     (evidence.findings ?? '').trim().slice(0, 4000) || '(없음)',
     '',

package/src/self-implement/goal-supervisor-fill.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { extractGoalDocSections } from './goal-doc/section.js';
@@ -8,8 +9,8 @@ export interface SupervisorGoalFillEvidence {
   reviewVerdict: 'pass' | 'warn' | 'fail';
   /** ⭐ 게이트 로그에서 **실제로 읽은** fail 수. 기대값이 아니다(리뷰 must-fix). */
   observedFail: number;
-  /** 게이트 로그의 baseline 행 원문 — 독립 검사기가 **이 문자열을 다시 판정**한다. */
-  baselineLine: string;
+  /** 실패 귀속 baseline이 실제 실행됐을 때만 있는 행. PASS에서는 실행하지 않는다. */
+  baselineLine?: string;
   /** ⭐ **원천 그대로** — 독립 검사기가 writer 의 파싱 결과가 아니라 **로그를 직접** 다시 읽는다. */
   gateLog: string;
 }
@@ -17,28 +18,41 @@ export interface SupervisorGoalFillEvidence {
 export interface SupervisorGoalFillInput {
   path: string;
   round: number;
-  gate: { passed: boolean; log?: string };
+  gate: { passed: boolean; log?: string; testStepExecuted?: boolean; scopeReason?: string };
   review?: { verdict: 'pass' | 'warn' | 'fail' };
   /** An external checker, deliberately separate from this writer/parser. */
   independentlyCheck: (document: string, evidence: SupervisorGoalFillEvidence) => Promise<boolean>;
+  wiring?: 'wired' | 'unwired';
+  observeDeficit?: (observation: SupervisorGoalDeficit) => void;
 }
 
-export type SupervisorGoalFillResult = 'filled' | 'already-filled' | 'unverifiable' | 'rejected';
+export interface SupervisorGoalDeficit {
+  evidenceId: string;
+  kind: 'unmeasured' | 'unwired' | 'unverified';
+  previousEvidence: string;
+  round: number;
+  gateLog?: string;
+  /** Decision branch, without gate log or goal text. */
+  reason?: 'missing-section' | 'missing-invariant-slot' | 'missing-signal-slot' | 'gate-evidence-unverified' | 'review-unavailable' | 'goal-unwired' | 'slot-format' | 'authored-signal-command-mismatch' | 'independent-check-failed';
+  inputSummary?: { gatePassed: boolean; hasGateLog: boolean; hasReview: boolean; invariantSlot: boolean; signalSlot: boolean };
+  gateLogRef?: string;
+}
+
+export type SupervisorGoalFillResult = 'filled' | 'already-filled' | 'not-applicable' | 'unverifiable' | 'rejected';
 
 const UNVERIFIABLE = 'UNVERIFIABLE';
 
 interface VerifiedGateEvidence {
   command: string;
   observedFail: number;
-  baselineLine: string;
+  baselineLine?: string;
 }
 
 /**
  * ⛔ **로그가 스스로 모순이면 채우지 않는다.** 종전 판은 ⓐ `[test] PASS` 접두와 명령 모양만 보고
- * ⓑ baseline 행이 **아예 없어도 통과**시켰다 ⇒ `[test] PASS bun test x — 0 pass | 5 fail` 같은
- * 로그로도 *"fail 0"* 을 채울 수 있었다(리뷰 must-fix).
- * ⇒ **fail 수를 실제로 읽고**, baseline 행을 **필수**로 하고, 그 원문을 증거에 실어 독립 검사기가
- *   같은 로그를 **다시** 판정할 수 있게 한다.
+ * ⓑ PASS 로그의 fail 수를 읽지 않아 `[test] PASS ... 5 fail`도 채울 수 있었다.
+ * ⇒ PASS의 실제 0 fail 요약을 필수로 읽는다. 실패 귀속용 baseline은 실행된 경우에만
+ *   원문을 검증하며, PASS에서 측정하지 않은 baseline 0건을 만들어 적지 않는다.
  */
 function verifiedGateEvidence(gate: SupervisorGoalFillInput['gate']): VerifiedGateEvidence | undefined {
   if (!gate.passed || !gate.log) return undefined;
@@ -54,11 +68,13 @@ function verifiedGateEvidence(gate: SupervisorGoalFillInput['gate']): VerifiedGa
   const observedFail = Number(failMatch[1]);
   if (observedFail !== 0) return undefined;   // PASS 라고 적혀 있어도 fail 이 있으면 모순이다
 
-  // ⛔ baseline 행은 **필수**다 — 없으면 "깨끗하다" 가 아니라 "안 쟀다" 이다.
+  // PASS 자체가 test 0 fail의 측정값이다. 실패 귀속 baseline은 PASS에서 실행되지 않는다.
+  // 행이 있다면 실제 값을 검증하고, 잘못된/모순된 행은 조용히 무시하지 않는다.
+  const rawBaseline = gate.log.split('\n').find((line) => line.startsWith('[gate-baseline]'));
   const baseline = gate.log.match(/^\[gate-baseline\]\s+introduced=(\d+),\s*preexisting=(\d+),\s*unknown=(\d+),\s*precondition-unmet=(\d+).*$/m);
-  if (!baseline) return undefined;
-  if (baseline.slice(1, 5).some((count) => count !== '0')) return undefined;
-  return { command, observedFail, baselineLine: baseline[0].trim() };
+  if (rawBaseline && !baseline) return undefined;
+  if (baseline?.slice(1, 5).some((count) => count !== '0')) return undefined;
+  return { command, observedFail, ...(baseline ? { baselineLine: baseline[0].trim() } : {}) };
 }
 
 function section(document: string, heading: string): { start: number; end: number; body: string } | undefined {
@@ -75,11 +91,11 @@ function section(document: string, heading: string): { start: number; end: numbe
  * ⛔ 그리고 **기대값이 아니라 관측값**을 적는다 — 종전 판은 로그를 안 읽고 `기대 — fail 0` 을 박았다.
  */
 function invariantReplacement(evidence: SupervisorGoalFillEvidence): string {
-  return `- filled-by: supervisor@round-${evidence.round}\n  조건 — ${evidence.command} 가 실패 없이 끝난다\n  이 라운드에서 관측됨 — fail ${evidence.observedFail}\n  근거 — round-${evidence.round} gate [test] PASS ${evidence.command} · ${evidence.baselineLine}`;
+  return `- filled-by: supervisor@round-${evidence.round}\n  조건 — ${evidence.command} 가 실패 없이 끝난다\n  이 라운드에서 관측됨 — fail ${evidence.observedFail}\n  근거 — round-${evidence.round} gate [test] PASS ${evidence.command} · ${evidence.baselineLine ?? 'baseline not run (test PASS)'}`;
 }
 
 function signalReplacement(evidence: SupervisorGoalFillEvidence): string {
-  return `- filled-by: supervisor@round-${evidence.round}\n  관측 — \`${evidence.command}\` 요약 줄의 fail 수\n  이번 라운드 관측값 — fail ${evidence.observedFail}\n  근거 — round-${evidence.round} review ${evidence.reviewVerdict} · ${evidence.baselineLine}`;
+  return `- filled-by: supervisor@round-${evidence.round}\n  관측 — \`${evidence.command}\` 요약 줄의 fail 수\n  이번 라운드 관측값 — fail ${evidence.observedFail}\n  근거 — round-${evidence.round} review ${evidence.reviewVerdict} · ${evidence.baselineLine ?? 'baseline not run (test PASS)'}`;
 }
 
 function replaceUnverifiableSlot(body: string, filled: string): string | undefined {
@@ -88,7 +104,7 @@ function replaceUnverifiableSlot(body: string, filled: string): string | undefin
 }
 
 /**
- * Fill only the two empty authored slots. Gate evidence is accepted only when
+ * Fill an empty invariant and either an empty signal or append an observation to an authored signal. Gate evidence is accepted only when
  * its logged test command and PASS status agree; baseline contradictions keep
  * the original document queued and byte-identical.
  */
@@ -96,27 +112,60 @@ export async function fillUnverifiableGoalSlots(input: SupervisorGoalFillInput):
   const original = readFileSync(input.path, 'utf8');
   const invariant = section(original, '## 불변식');
   const signals = section(original, '## 판정 신호');
-  if (!invariant || !signals) return 'unverifiable';
-  const invariantNeedsFill = invariant.body.includes(UNVERIFIABLE);
-  const signalsNeedFill = signals.body.includes(UNVERIFIABLE);
-  if (!invariantNeedsFill && !signalsNeedFill) return 'already-filled';
-
+  const invariantSlot = Boolean(invariant && /^- UNVERIFIABLE(?:[ \t]*:[^\r\n]*)?[ \t]*$/m.test(invariant.body));
+  const signalSlot = Boolean(signals && /^- UNVERIFIABLE(?:[ \t]*:[^\r\n]*)?[ \t]*$/m.test(signals.body));
   const gateEvidence = verifiedGateEvidence(input.gate);
-  if (!invariantNeedsFill || !signalsNeedFill || !gateEvidence || !input.review) return 'unverifiable';
+  const deficit = (reason: NonNullable<SupervisorGoalDeficit['reason']>): void => input.observeDeficit?.({
+    evidenceId: createHash('sha256').update(JSON.stringify([input.path, input.round, original])).digest('hex').slice(0, 16),
+    kind: !gateEvidence || !input.review ? 'unmeasured' : input.wiring === 'unwired' ? 'unwired' : 'unverified',
+    previousEvidence: original,
+    round: input.round,
+    ...(input.gate.log !== undefined ? { gateLog: input.gate.log } : {}),
+    reason,
+    inputSummary: { gatePassed: input.gate.passed, hasGateLog: Boolean(input.gate.log), hasReview: Boolean(input.review), invariantSlot, signalSlot },
+    ...(input.gate.log ? { gateLogRef: `sha256:${createHash('sha256').update(input.gate.log).digest('hex').slice(0, 16)}` } : {}),
+  });
+  if (!invariant || !signals) {
+    // A sectionless goal has no slot the supervisor can measure or repair.
+    // Report a deficit only when a present section contains an actual slot.
+    if (invariantSlot || signalSlot) deficit('missing-section');
+    return 'unverifiable';
+  }
+  if (!invariantSlot && !signalSlot && !invariant.body.includes(UNVERIFIABLE) && !signals.body.includes(UNVERIFIABLE)
+    && input.wiring !== 'unwired') return 'already-filled';
+  if (!invariantSlot) { deficit('missing-invariant-slot'); return 'unverifiable'; }
+  if (!signalSlot && !signals.body.trim()) { deficit('missing-signal-slot'); return 'unverifiable'; }
+  // A docs-only PASS has no test measurement to put into the authored slots.
+  // Trust the gate's structured scope, never a free-text log line, and leave the goal unchanged.
+  if (input.gate.passed && input.gate.testStepExecuted === false && input.gate.scopeReason === 'docs-only'
+    && input.wiring !== 'unwired') {
+    return 'not-applicable';
+  }
+  if (!gateEvidence) { deficit('gate-evidence-unverified'); return 'unverifiable'; }
+  if (!input.review) { deficit('review-unavailable'); return 'unverifiable'; }
+  if (input.wiring === 'unwired') { deficit('goal-unwired'); return 'unverifiable'; }
+  // The authored completion signal must name the test we actually measured.
+  if (!signalSlot) {
+    const authoredCommand = signals.body.match(/^\s*- Condition:\s*(bun test\s+[^\r\n]+?)(?:\s+를 실행한다)?\s*$/m)?.[1]?.trim();
+    if (!authoredCommand || authoredCommand !== gateEvidence.command) {
+      deficit('authored-signal-command-mismatch'); return 'unverifiable';
+    }
+  }
 
   const evidence: SupervisorGoalFillEvidence = {
     round: input.round,
     command: gateEvidence.command,
     reviewVerdict: input.review.verdict,
     observedFail: gateEvidence.observedFail,
-    baselineLine: gateEvidence.baselineLine,
+    ...(gateEvidence.baselineLine ? { baselineLine: gateEvidence.baselineLine } : {}),
     gateLog: input.gate.log ?? '',
   };
   const invariantBody = replaceUnverifiableSlot(invariant.body, invariantReplacement(evidence));
-  const signalBody = replaceUnverifiableSlot(signals.body, signalReplacement(evidence));
-  if (invariantBody === undefined || signalBody === undefined) return 'unverifiable';
+  const signalBody = signalSlot ? replaceUnverifiableSlot(signals.body, signalReplacement(evidence))
+    : `${signals.body.replace(/\s*$/, '')}\n${signalReplacement(evidence)}\n`;
+  if (invariantBody === undefined || signalBody === undefined) { deficit('slot-format'); return 'unverifiable'; }
   const candidate = `${original.slice(0, invariant.start)}## 불변식${invariantBody}${original.slice(invariant.end, signals.start)}## 판정 신호${signalBody}${original.slice(signals.end)}`;
-  if (!await input.independentlyCheck(candidate, evidence)) return 'rejected';
+  if (!await input.independentlyCheck(candidate, evidence)) { deficit('independent-check-failed'); return 'rejected'; }
 
   const temporary = join(dirname(input.path), `.${Math.random().toString(16).slice(2)}.goal-fill.tmp`);
   try {

package/src/self-implement/graph-variant.ts

@@ -3,6 +3,7 @@ import { applyGraphOverlays, type GraphOverlaySpec, type OverlayPatchOp, type Ov
 import { edgeMapOf, graphVersionHash, type GraphEdgeSpec, type GraphNodeSpec, type GraphTemplateSpec } from './graph-yaml.js';
 import { inspectPipelineGraph } from './pipeline-shape.js';
 import { hasNodeKind } from '../graph-kinds/registry.js';
+import { GOAL_TYPES, type GoalType } from './goal-author.js';
 
 /** A proposed change to one existing outcome of a conditional route. Unconditional and fallback edges are protected. */
 export interface GraphVariantRoute {
@@ -24,6 +25,18 @@ export interface GraphVariantPlan {
   readonly growth?: GraphVariantGrowth;
 }
 
+/** 골 분석 중 최초 변형 선택이 보는 «두» 입력 — 문서 전용·저작 등급 같은 원 칸의 다른 축은 이 조각에 없다. */
+export interface GraphVariantGoalAnalysis {
+  readonly goalType: GoalType;
+  readonly targetPathCount: number;
+}
+
+/** 최초 graph variant 선택 — id·선택 이유가 런 원장 옆 .graph.yaml 에 함께 저장되고 재조회된다. */
+export interface GraphVariantSelection {
+  readonly variantId: string;
+  readonly reason: string;
+}
+
 export type GraphVariantRejection =
   | { readonly kind: 'invalid-goal' }
   | { readonly kind: 'unknown-node'; readonly node: string }
@@ -35,25 +48,46 @@ export type GraphVariantRejection =
   | { readonly kind: 'unreachable-terminal'; readonly node: string }
   | { readonly kind: 'invalid-graph'; readonly defects: ReturnType<typeof inspectPipelineGraph> }
   | { readonly kind: 'overlay-rejected'; readonly rejections: readonly OverlayRejection[] }
-  | { readonly kind: 'invalid-growth'; readonly reason: string };
+  | { readonly kind: 'invalid-growth'; readonly reason: string }
+  | { readonly kind: 'invalid-goal-analysis' };
 
 export type GraphVariantResult =
-  | { readonly ok: true; readonly overlay: GraphOverlaySpec; readonly template: GraphTemplateSpec; readonly patches: readonly OverlayPatchOp[] }
+  | { readonly ok: true; readonly overlay: GraphOverlaySpec; readonly template: GraphTemplateSpec; readonly patches: readonly OverlayPatchOp[]; readonly selection?: GraphVariantSelection }
   | { readonly ok: false; readonly rejections: readonly GraphVariantRejection[] };
 
+/** 최초 변형 선택(id·선택 이유)의 결정론적 유도 — 같은 종류·대상 경로 수면 항상 같은 값을 낸다. */
+export function initialGraphVariantSelection(analysis: GraphVariantGoalAnalysis): GraphVariantSelection {
+  const variantId = `variant-${analysis.goalType}-${createHash('sha256')
+    .update(JSON.stringify({ goalType: analysis.goalType, targetPathCount: analysis.targetPathCount }))
+    .digest('hex').slice(0, 12)}`;
+  return {
+    variantId,
+    reason: `initial graph variant selected from goal type ${analysis.goalType} with ${analysis.targetPathCount} target path${analysis.targetPathCount === 1 ? '' : 's'}`,
+  };
+}
+
 /** Pure, deterministic variant authoring. Never mutates the supplied template and never writes an overlay. */
 export function createGraphVariant(input: {
   readonly template: GraphTemplateSpec;
   readonly goal: string;
   readonly plan: GraphVariantPlan;
+  readonly goalAnalysis?: GraphVariantGoalAnalysis;
 }): GraphVariantResult {
-  const { template, goal, plan } = input;
+  const { template, goal, plan, goalAnalysis } = input;
   const known = new Set(template.nodes.map((node) => node.nodeId));
   const rejections: GraphVariantRejection[] = [];
   if (!/^g_[a-z0-9_-]+$/i.test(goal)) rejections.push({ kind: 'invalid-goal' });
+  let selection: GraphVariantSelection | undefined;
+  if (goalAnalysis !== undefined) {
+    if (!GOAL_TYPES.includes(goalAnalysis.goalType) || !Number.isSafeInteger(goalAnalysis.targetPathCount) || goalAnalysis.targetPathCount < 0) {
+      rejections.push({ kind: 'invalid-goal-analysis' });
+    } else {
+      selection = initialGraphVariantSelection(goalAnalysis);
+    }
+  }
   if (plan.growth) {
     const { node, from, outcome, returnTo } = plan.growth;
-    if (!node || typeof node !== 'object') return { ok: false, rejections: [{ kind: 'invalid-growth', reason: 'growth requires one new contracted node' }] };
+    if (!node || typeof node !== 'object') return { ok: false, rejections: [...rejections, { kind: 'invalid-growth', reason: 'growth requires one new contracted node' }] };
     const edgeIndex = template.edges.findIndex((edge) => edge.from === from);
     const edge = template.edges[edgeIndex];
     if (!known.has(from) || known.has(node.nodeId) || template.terminalNodes.includes(from) ||
@@ -94,7 +128,7 @@ export function createGraphVariant(input: {
     }
     const unreachable = projected.terminalNodes.filter((terminal) => !reached.has(terminal) || (edges[terminal]?.length ?? 0) !== 0);
     if (unreachable.length) return { ok: false, rejections: unreachable.map((terminal) => ({ kind: 'unreachable-terminal', node: terminal })) };
-    return { ok: true, overlay, template: projected, patches };
+    return { ok: true, overlay, template: projected, patches, ...(selection === undefined ? {} : { selection }) };
   }
   const patches: OverlayPatchOp[] = [];
 
@@ -167,5 +201,5 @@ export function createGraphVariant(input: {
   })) };
   const applied = applyGraphOverlays(validationTemplate, [overlay]);
   if (!applied.ok) return { ok: false, rejections: [{ kind: 'overlay-rejected', rejections: applied.rejections }] };
-  return { ok: true, overlay, template: projected, patches };
+  return { ok: true, overlay, template: projected, patches, ...(selection === undefined ? {} : { selection }) };
 }