elanous 0.2.32 → 0.2.35

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

@@ -0,0 +1,295 @@
+/**
+ * GOAL-ELABORATE-ON-ARRIVAL — E1 착수 구체화(spec-on-arrival).
+ *
+ * 설계 = 내부 문서 `RFC-progressive-goal-elaboration-2026-10-21` §2 E1 · §7 간선 ①(author → implement «구체화 층 v1»).
+ * 골은 두 층이다: 고정 층(방향·KPI·불변식·보호 구역 — 런이 못 바꾼다) ⊕ 구체화 층(건드릴 파일·세부 요구·
+ * 먼저 쓸 시험 — 런이 채운다). 이 모듈은 구현 첫 단계 전에 구체화 카드를 쓰게 하고, 카드가 고정 층과
+ * 맞는지만 판정한다(안 맞으면 다시 쓰기 1회 → 그래도면 사람).
+ *
+ * ⛔ 골의 KPI·판정 신호는 바꾸지 않는다 — 카드는 골 원문 «뒤에» 덧붙을 뿐이고 고정 층을 다시 쓰지 않는다.
+ * ⭐ 순수 함수 ⊕ 주입한 LLM 호출 — 시험은 대본 응답으로 돈다(주입 사다리 L2).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type ElaborationCallLLM = (args: { prompt: string; systemPrompt?: string }) => Promise<string>;
+
+const INJECTION_LEVELS = ['L0', 'L1', 'L2', 'L3', 'L4'] as const;
+export type InjectionLevel = typeof INJECTION_LEVELS[number];
+
+export interface GoalFixedLayer {
+  direction: string[];
+  kpi: string[];
+  invariants: string[];
+  /** 불변식 문면에서 «바꾸지 않는다/금지» 절에 실린 경로 — 카드가 건드리면 위반이다. */
+  protectedPaths: string[];
+}
+
+export interface ElaborationCard {
+  files: string[];
+  newFiles: string[];
+  requirements: string[];
+  firstTest: { path: string; name: string; redReason: string };
+  stage: string;
+  level: InjectionLevel;
+}
+
+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: '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;
+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;
+
+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));
+}
+
+/** 골 원문에서 고정 층을 «그대로» 뽑는다(요약·재서술하지 않는다 — 판정기가 원문 줄을 본다). */
+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));
+  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);
+  const protectedPaths = 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]);
+    }
+  }
+  return { direction: clip(direction), kpi: clip(kpi), invariants: clip(invariants), protectedPaths: [...protectedPaths] };
+}
+
+function stringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value.filter((item): item is string => typeof item === 'string').map((item) => item.trim()).filter(Boolean);
+  return out.length === value.length ? out : undefined;
+}
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/** 마지막 JSON 객체를 읽는다(펜스 · 앞뒤 산문 허용). */
+function lastJsonObject(text: string): unknown {
+  const fenced = [...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g)].map((match) => match[1]!);
+  const candidates = [...fenced.reverse(), text];
+  for (const candidate of candidates) {
+    const start = candidate.indexOf('{');
+    const end = candidate.lastIndexOf('}');
+    if (start === -1 || end <= start) continue;
+    try { return JSON.parse(candidate.slice(start, end + 1)); } catch { /* next */ }
+  }
+  return undefined;
+}
+
+export function parseElaborationCard(text: string): { ok: true; card: ElaborationCard } | { ok: false; error: string } {
+  const raw = lastJsonObject(text);
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, error: 'no JSON object' };
+  const record = raw as Record<string, unknown>;
+  const files = stringList(record.files);
+  if (!files?.length || files.length > MAX_CARD_FILES) return { ok: false, error: `files must be 1..${MAX_CARD_FILES} strings` };
+  const newFiles = record.newFiles === undefined ? [] : stringList(record.newFiles);
+  if (!newFiles) return { ok: false, error: 'newFiles must be strings' };
+  const requirements = stringList(record.requirements);
+  if (!requirements?.length) return { ok: false, error: 'requirements must be a non-empty string list' };
+  const test = record.firstTest as Record<string, unknown> | undefined;
+  if (!test || !nonEmpty(test.path) || !nonEmpty(test.name) || !nonEmpty(test.redReason)) {
+    return { ok: false, error: 'firstTest needs path, name and redReason' };
+  }
+  if (!nonEmpty(record.stage)) return { ok: false, error: 'stage is required' };
+  if (!INJECTION_LEVELS.includes(record.level as InjectionLevel)) return { ok: false, error: 'level must be L0..L4' };
+  return {
+    ok: true,
+    card: {
+      files: [...new Set(files)],
+      newFiles: [...new Set(newFiles)],
+      requirements,
+      firstTest: { path: test.path.trim(), name: test.name.trim(), redReason: test.redReason.trim() },
+      stage: record.stage.trim(),
+      level: record.level as InjectionLevel,
+    },
+  };
+}
+
+function touchesProtected(path: string, protectedPath: string): boolean {
+  return path === protectedPath || path.endsWith(`/${protectedPath}`);
+}
+
+/** 결정론 대조 — 보호 경로를 건드리나 · 저장소에 없는 경로를 «기존»으로 적었나(접지). */
+export function checkCardAgainstFixedLayer(card: ElaborationCard, fixed: GoalFixedLayer, fileExists: (path: string) => boolean): string[] {
+  const violations: string[] = [];
+  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})`);
+    else if (!card.newFiles.includes(path) && !fileExists(path)) violations.push(`ungrounded path: ${path} does not exist and is not listed in newFiles`);
+  }
+  return violations;
+}
+
+const CARD_SYSTEM = 'You elaborate a software goal into a concrete implementation card before coding starts. Reply with one JSON object only.';
+const JUDGE_SYSTEM = 'You check only whether an implementation card stays inside a goal\'s fixed layer (direction, KPI/acceptance signals, invariants, protected areas). Reply with one JSON object only.';
+
+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 {
+  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}`)] : []),
+    '',
+    '## 고정 층(바꾸지 않는다)',
+    section('방향', fixed.direction),
+    section('KPI·판정 신호', fixed.kpi),
+    section('불변식·보호 구역', fixed.invariants),
+    '',
+    '## 골 원문',
+    goal,
+    ...(context && context !== goal ? ['', '## 저장소 맥락', context.slice(0, 12_000)] : []),
+  ].join('\n');
+}
+
+function buildJudgePrompt(fixed: GoalFixedLayer, card: ElaborationCard): string {
+  return [
+    '카드가 고정 층과 «맞는지만» 본다. 카드가 KPI·판정 신호를 약화·삭제·대체하거나, 방향을 바꾸거나, 불변식·보호 구역을 어기면 불일치다. 구현 방법의 좋고 나쁨은 판정하지 않는다.',
+    'JSON 형식: {"consistent": true|false, "violations": [어긋난 점]}',
+    '',
+    section('방향', fixed.direction),
+    section('KPI·판정 신호', fixed.kpi),
+    section('불변식·보호 구역', fixed.invariants),
+    '',
+    '### 카드',
+    JSON.stringify(card, null, 2),
+  ].join('\n');
+}
+
+function parseJudge(text: string): { consistent: boolean; violations: string[] } | 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'] };
+}
+
+function cardSha(card: ElaborationCard): string {
+  return createHash('sha256').update(JSON.stringify(card)).digest('hex');
+}
+
+function errorText(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 200);
+}
+
+/**
+ * 카드 쓰기 → 판정(결정론 ⊕ LLM) → 어긋나면 다시 쓰기 1회 → 그래도면 needs-human.
+ * 공급자 실패·카드 판독 실패는 skipped(런을 막지 않는다 — 카드 없이 오늘처럼 구현한다).
+ */
+export async function elaborateGoalOnArrival(
+  input: { goal: string; context?: string; fileExists: (path: string) => boolean },
+  deps: { callLLM?: ElaborationCallLLM; maxRewrites?: number },
+): 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);
+  const fixedLayerEmpty = !fixed.kpi.length && !fixed.invariants.length;
+  /** 다시 쓰기 프롬프트에 실을 앞 회차의 문제(판독 실패 포함). */
+  let feedback: string[] = [];
+  /** 고정 층 위반은 «판독된 카드»에만 귀속한다 — 해시와 위반이 같은 카드를 가리킨다. */
+  let lastRejected: { sha: string; violations: string[] } | 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 });
+    } catch (error) {
+      return { status: 'skipped', reason: 'provider-failed', attempts: attempt, error: errorText(error) };
+    }
+    const parsed = parseElaborationCard(text);
+    if (!parsed.ok) {
+      feedback = [`card-unparseable: ${parsed.error}`];
+      continue;
+    }
+    const card = parsed.card;
+    const sha = cardSha(card);
+    let violations = checkCardAgainstFixedLayer(card, fixed, input.fileExists);
+    let judge: 'llm' | 'deterministic-only' = 'deterministic-only';
+    if (!violations.length) {
+      try {
+        const verdict = parseJudge(await deps.callLLM({ prompt: buildJudgePrompt(fixed, card), systemPrompt: JUDGE_SYSTEM }));
+        if (verdict) {
+          judge = 'llm';
+          if (!verdict.consistent) violations = verdict.violations;
+        } else judgeErrors.push('judge-unparseable');
+      } catch (error) {
+        // 판정기 실패는 결정론 대조만으로 — 카드는 고정 층을 다시 쓰지 않는다. 실패 사실은 관측에 남긴다.
+        judgeErrors.push(`judge-failed: ${errorText(error)}`);
+      }
+    }
+    if (!violations.length) {
+      return { status: 'elaborated', card, cardSha: sha, fileCount: card.files.length, level: card.level, attempts: attempt, judge,
+        ...(judgeErrors.length ? { judgeErrors } : {}), ...(fixedLayerEmpty ? { fixedLayerEmpty } : {}) };
+    }
+    lastRejected = { sha, violations };
+    feedback = 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 };
+}
+
+export function renderElaborationCard(card: ElaborationCard, sha: string): string {
+  return [
+    `## 착수 구체화 카드 (E1 · 구체화 층 v1 · ${sha.slice(0, 12)})`,
+    '> 고정 층(방향·KPI·판정 신호·불변식)은 위 골 원문이 정본이다 — 이 카드는 그것을 바꾸지 않고 «어디서부터 어떻게» 만 정한다. 구현 중 카드가 틀렸으면 고치고 이유를 남긴다.',
+    `- 무대: ${card.stage} · 주입 층: ${card.level}`,
+    '### 건드릴 파일',
+    ...card.files.map((path) => `- ${path}${card.newFiles.includes(path) ? ' (신설)' : ''}`),
+    '### 세부 요구',
+    ...card.requirements.map((line) => `- ${line}`),
+    '### 먼저 쓸 시험 (RED)',
+    `- ${card.firstTest.path} — ${card.firstTest.name}`,
+    `- 지금 실패하는 이유: ${card.firstTest.redReason}`,
+  ].join('\n');
+}
+
+/** orchestrator 호출점 한 곳 — 관측(`observe` → 로그 ⊕ 런 원장)까지 여기서 낸다. */
+export async function runArrivalElaboration(input: {
+  goal: string;
+  prompt: string;
+  cwd?: string;
+  fileExists?: (path: string) => boolean;
+  callLLM?: ElaborationCallLLM;
+  observe: (event: string, data: Record<string, unknown>, opt?: { level?: 'warn' }) => void;
+}): Promise<{ prompt: string; parked: boolean; detail?: string }> {
+  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 });
+  } catch (error) {
+    outcome = { status: 'skipped', reason: 'provider-failed', attempts: 0, error: errorText(error) };
+  }
+  if (outcome.status === 'elaborated') {
+    // `outcome` 은 여정 그래프 관측기(graphs/journey/units/author-dialogue/observe.ts)가 읽는 값이다.
+    input.observe('goal-elaborated', { outcome: 'elaborated', cardSha: outcome.cardSha, fileCount: outcome.fileCount, level: outcome.level, stage: outcome.card.stage, attempts: outcome.attempts, judge: outcome.judge,
+      ...(outcome.judgeErrors ? { judgeErrors: outcome.judgeErrors } : {}), ...(outcome.fixedLayerEmpty ? { fixedLayerEmpty: true } : {}) },
+      outcome.judgeErrors || outcome.fixedLayerEmpty ? { level: 'warn' } : undefined);
+    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-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

@@ -0,0 +1,270 @@
+/**
+ * GOAL-REFINE-FROM-FIRST-IMPL — E3 첫 구현 → 골 저작 역피드백(골 v2).
+ *
+ * 설계 = 내부 문서 `RFC-progressive-goal-elaboration-2026-10-21` §7 간선 ②③④ — ta-journey 의 author-dialogue 단위에서
+ * judge «findings» → author → «deliver vN+1» → implement 되돌이를 «한 번»(max_visits) 실행한다.
+ * 첫 라운드(구현 → gate → 리뷰) 뒤 «재그라운딩 노트»(지나간 생산 경로 · 건드린 파일 · 운영이 골 가정과 다른 점 ·
+ * 불가능/모호한 수용선과 바꿀 문면 · 남은 일)를 받아 골 v2 를 만든다.
+ *
+ * ⛔ 방향·KPI 줄은 바뀌지 않는다(사람 몫) — 바꾸려 들면 v2 를 «버리고» v1 을 유지한다 ⊕ 사유를 남긴다.
+ * ⭐ 바뀌어도 되는 칸은 셋뿐: 예상 구역(`대상 경로:`·`신설:`) · 수용선 문구(`완료 경계 코드:`·`완료 경계 실물:`·`수용선:`·`- Checkable requested criterion:`) ·
+ *    검증 무대(`검증 무대:`·`무대:`). 줄 머리 꼴은 저작 문법(goal-author.ts GOAL_DONE_BOUNDARY_LABELS ⊕ 칸 문면)을 따른다.
+ *    `완료 경계 증거 명령`은 «재는 명령»이라 KPI 로 본다(E1 extractGoalFixedLayer 의 KPI 줄에서 수용선 문구만 뺀 것).
+ * ⭐ 순수 함수 ⊕ 주입한 LLM — 시험은 대본 응답(fake-llm)으로 돈다(주입 사다리 L2).
+ */
+import { createHash } from 'node:crypto';
+
+export type RefineCallLLM = (args: { prompt: string; systemPrompt?: string }) => Promise<string>;
+
+/** 골 한 줄의 칸. fixed = 방향·KPI(불변) · zone/acceptance/stage = 바뀌어도 되는 칸 · other = 이 칸이 안 건드린다. */
+export type GoalLineZone = 'direction' | 'kpi' | 'zone' | 'acceptance' | 'stage' | 'other';
+const EDITABLE: ReadonlySet<GoalLineZone> = new Set(['zone', 'acceptance', 'stage']);
+
+/**
+ * 편집 가능 칸의 줄 머리 — 분류기(classifyGoalLine)와 노트 프롬프트(buildRegroundingPrompt)가 «이 상수 하나»에서 만든다.
+ * `Checkable requested criterion` = 저작기가 쓰는 «요구된 수용 기준» 줄(REFUTE 인용 자격 줄 — reflect-mustfix.ts) · preservation 은 고정(other).
+ */
+export const EDITABLE_GOAL_LABELS = {
+  zone: ['대상 경로', '신설', '예상 구역'],
+  acceptance: ['완료 경계 코드', '완료 경계 실물', '수용선', 'acceptance', 'Checkable requested criterion'],
+  stage: ['검증 무대', '무대', 'stage'],
+} as const satisfies Record<'zone' | 'acceptance' | 'stage', readonly string[]>;
+const EDITABLE_ZONE_NAMES: Record<keyof typeof EDITABLE_GOAL_LABELS, string> = { zone: '예상 구역', acceptance: '수용선 문구', stage: '검증 무대' };
+
+const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const LABEL = (labels: string) => new RegExp(`^\\s*(?:[-*]\\s*)?(?:${labels})\\s*[:：]`, 'i');
+const LABELS = (labels: readonly string[]) => LABEL(labels.map(escapeRegExp).join('|'));
+const KPI_LABEL = LABEL('완료 경계 증거 명령|증거 명령|판정 신호(?:\\([^)]*\\))?|KPI|verify|반증');
+const ACCEPTANCE_LABEL = LABELS(EDITABLE_GOAL_LABELS.acceptance);
+const ZONE_LABEL = LABELS(EDITABLE_GOAL_LABELS.zone);
+const STAGE_LABEL = LABELS(EDITABLE_GOAL_LABELS.stage);
+const DIRECTION_LABEL = LABEL('바꿀 것|목표|무엇|왜|현재 계약|Goal|Why|What');
+/** 라벨 없는 줄도 KPI 낱말을 품으면 고정으로 본다(보수 쪽). */
+const KPI_WORD = /판정 신호|KPI/i;
+
+export function classifyGoalLine(line: string): GoalLineZone {
+  if (KPI_LABEL.test(line)) return 'kpi';
+  if (ACCEPTANCE_LABEL.test(line)) return 'acceptance';
+  if (ZONE_LABEL.test(line)) return 'zone';
+  if (STAGE_LABEL.test(line)) return 'stage';
+  if (DIRECTION_LABEL.test(line)) return 'direction';
+  if (KPI_WORD.test(line)) return 'kpi';
+  return 'other';
+}
+
+function labelOf(line: string): string {
+  return /^\s*(?:[-*]\s*)?([^:：]+)[:：]/.exec(line)?.[1]?.trim() ?? '';
+}
+
+/** 방향·KPI 줄(원문 그대로 · 순서 보존) — v1·v2 대조의 정본. */
+export function fixedGoalLines(goal: string): string[] {
+  return goal.split(/\r?\n/).filter((line) => {
+    const zone = classifyGoalLine(line);
+    return zone === 'direction' || zone === 'kpi';
+  });
+}
+
+export interface RegroundEdit { from: string; to: string; reason: string }
+export interface RegroundingNote {
+  productionPath: string[];
+  touchedFiles: string[];
+  divergences: string[];
+  edits: RegroundEdit[];
+  remaining: string[];
+}
+
+export interface GoalChangedLine { index: number; zone: GoalLineZone; before: string; after: string; reason: string }
+export type GoalKeptReason = 'no-provider' | 'provider-failed' | 'note-unparseable' | 'empty-note' | 'no-applicable-edits' | 'fixed-layer-edit' | 'max-visits';
+export type GoalRefinement =
+  | { outcome: 'refined'; v1Hash: string; v2Hash: string; v2: string; changedLines: GoalChangedLine[]; reasons: string[]; rejectedEdits: string[]; note: RegroundingNote }
+  | { outcome: 'kept'; v1Hash: string; v2Hash: string; kept: GoalKeptReason; detail?: string; rejectedEdits: string[] };
+
+export function goalHash(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+function strings(value: unknown, max = 20): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === 'string').map((item) => item.trim()).filter(Boolean).slice(0, max).map((item) => item.slice(0, 400));
+}
+
+function lastJsonObject(text: string): unknown {
+  const fenced = [...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g)].map((match) => match[1]!);
+  for (const candidate of [...fenced.reverse(), text]) {
+    const start = candidate.indexOf('{');
+    const end = candidate.lastIndexOf('}');
+    if (start === -1 || end <= start) continue;
+    try { return JSON.parse(candidate.slice(start, end + 1)); } catch { /* next */ }
+  }
+  return undefined;
+}
+
+export function parseRegroundingNote(text: string): { ok: true; note: RegroundingNote } | { ok: false; error: string } {
+  const raw = lastJsonObject(text);
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, error: 'no JSON object' };
+  const record = raw as Record<string, unknown>;
+  const edits: RegroundEdit[] = Array.isArray(record.edits)
+    ? record.edits.flatMap((edit) => {
+      const e = edit as Record<string, unknown> | null;
+      return e && typeof e.from === 'string' && typeof e.to === 'string'
+        ? [{ from: e.from, to: e.to, reason: typeof e.reason === 'string' && e.reason.trim() ? e.reason.trim().slice(0, 400) : '(이유 없음)' }]
+        : [];
+    }).slice(0, 20)
+    : [];
+  return { ok: true, note: { productionPath: strings(record.productionPath), touchedFiles: strings(record.touchedFiles, 40), divergences: strings(record.divergences), edits, remaining: strings(record.remaining) } };
+}
+
+function noteIsEmpty(note: RegroundingNote): boolean {
+  return !note.edits.length && !note.productionPath.length && !note.touchedFiles.length && !note.divergences.length && !note.remaining.length;
+}
+
+const REGROUND_NOTE_HEADER = '## 재그라운딩 노트 (골 v2 · 첫 라운드 실전 — 참고, 고정 층 아님)';
+
+/**
+ * (v1 골 문면, 재그라운딩 노트) → v2 ⊕ 바뀐 줄·이유 ⊕ 해시.
+ * ⛔ 방향·KPI 줄을 겨눈 편집이 «하나라도» 있으면 v2 전체를 버린다(kept: fixed-layer-edit).
+ * 바뀌어도 되는 칸 밖(other)·없는 줄·칸 머리를 바꾼 편집은 그 편집만 버리고 이유를 rejectedEdits 에 남긴다.
+ */
+export function applyRegroundingNote(v1: string, note: RegroundingNote): GoalRefinement {
+  const v1Hash = goalHash(v1);
+  const kept = (reason: GoalKeptReason, rejectedEdits: string[] = [], detail?: string): GoalRefinement =>
+    ({ outcome: 'kept', v1Hash, v2Hash: v1Hash, kept: reason, rejectedEdits, ...(detail ? { detail } : {}) });
+  if (noteIsEmpty(note)) return kept('empty-note');
+  const lines = v1.split('\n');
+  const rejected: string[] = [];
+  const changed: GoalChangedLine[] = [];
+  for (const edit of note.edits) {
+    const from = edit.from.trim();
+    const index = lines.findIndex((line, i) => line.trim() === from && !changed.some((c) => c.index === i));
+    if (index === -1) { rejected.push(`not-in-goal: ${from.slice(0, 120)}`); continue; }
+    const before = lines[index]!;
+    const zone = classifyGoalLine(before);
+    if (zone === 'direction' || zone === 'kpi') {
+      return kept('fixed-layer-edit', [...rejected, `${zone}: ${before.trim().slice(0, 160)}`], edit.reason);
+    }
+    const after = edit.to.replace(/\r?\n/g, ' ').trim();
+    if (!EDITABLE.has(zone)) { rejected.push(`out-of-zone(${zone}): ${before.trim().slice(0, 120)}`); continue; }
+    if (classifyGoalLine(after) !== zone || labelOf(after) !== labelOf(before.trim())) { rejected.push(`label-changed: ${before.trim().slice(0, 120)}`); continue; }
+    if (after === before.trim()) { rejected.push(`no-op: ${before.trim().slice(0, 120)}`); continue; }
+    const indent = /^\s*/.exec(before)![0];
+    lines[index] = `${indent}${after}`;
+    changed.push({ index, zone, before: before.trim(), after, reason: edit.reason });
+  }
+  if (!changed.length) return kept('no-applicable-edits', rejected);
+  const body = lines.join('\n');
+  // 방어 이중화 — 적용 뒤에도 방향·KPI 줄이 원문 그대로인가(줄 분류가 편집으로 바뀌는 경우까지 막는다).
+  if (JSON.stringify(fixedGoalLines(body)) !== JSON.stringify(fixedGoalLines(v1))) return kept('fixed-layer-edit', rejected, 'fixed lines differ after applying edits');
+  const section = (title: string, items: string[]) => (items.length ? [`### ${title}`, ...items.map((item) => `- ${item.replace(/\r?\n/g, ' ')}`)] : []);
+  const v2 = [
+    body.trimEnd(),
+    '',
+    REGROUND_NOTE_HEADER,
+    ...section('지나간 생산 경로', note.productionPath),
+    ...section('건드린 파일', note.touchedFiles),
+    ...section('운영이 골 가정과 다른 점', note.divergences),
+    ...section('바뀐 문면(v1 → v2)', changed.map((c) => `${c.before} → ${c.after} — ${c.reason}`)),
+    ...section('남은 일', note.remaining),
+  ].join('\n');
+  return { outcome: 'refined', v1Hash, v2Hash: goalHash(v2), v2, changedLines: changed, reasons: changed.map((c) => c.reason), rejectedEdits: rejected, note };
+}
+
+const NOTE_SYSTEM = 'You re-ground a software goal after its first implementation round. Reply with one JSON object only.';
+
+export interface FirstRoundEvidence {
+  /** 첫 라운드 자식 요약(무엇을 해 봤나). */
+  implSummary?: string;
+  /** 첫 라운드 gate·리뷰가 돌려준 지적(must-fix 등). */
+  findings?: string;
+  /** 첫 라운드가 실제로 건드린 파일. */
+  changedFiles?: readonly string[];
+}
+
+/** 내부 — 시험은 refineGoalFromFirstRound 가 LLM 에 넘긴 프롬프트로 본다. */
+function buildRegroundingPrompt(v1: string, evidence: FirstRoundEvidence): string {
+  const fixed = fixedGoalLines(v1);
+  return [
+    '## 할 일 — 재그라운딩 노트(E3 · 첫 라운드 → 골 v2)',
+    '첫 라운드(구현 → gate → 리뷰) 실전에서 알게 된 것으로 골을 다시 접지한다. 방향·KPI 줄은 바꾸지 않는다(사람 몫).',
+    `바꿀 수 있는 줄은 셋뿐이다: ${(Object.keys(EDITABLE_GOAL_LABELS) as Array<keyof typeof EDITABLE_GOAL_LABELS>)
+      .map((zone) => `${EDITABLE_ZONE_NAMES[zone]}(${EDITABLE_GOAL_LABELS[zone].map((label) => `\`${label}:\``).join('·')})`).join(' · ')}. 줄 머리(라벨)는 그대로 두고 값만 고친다.`,
+    'JSON 형식: {"productionPath": [실제로 지나간 생산 경로], "touchedFiles": [건드린 파일], "divergences": [운영이 골 가정과 다른 점], "edits": [{"from": "골 원문 한 줄 그대로", "to": "고친 한 줄", "reason": "왜(불가능·모호·경로 틀림)"}], "remaining": [남은 일]}',
+    '',
+    '## 고정 층(바꾸지 않는다 — 방향·KPI)',
+    ...(fixed.length ? fixed.map((line) => `- ${line.trim()}`) : ['- (없음)']),
+    '',
+    '## 첫 라운드 실전',
+    `- 자식 요약: ${(evidence.implSummary ?? '').replace(/\s+/g, ' ').trim().slice(0, 600) || '(없음)'}`,
+    `- 건드린 파일: ${evidence.changedFiles?.length ? evidence.changedFiles.slice(0, 40).join(', ') : '(관측 없음)'}`,
+    '### gate·리뷰 지적',
+    (evidence.findings ?? '').trim().slice(0, 4000) || '(없음)',
+    '',
+    '## 골 v1 원문',
+    v1,
+  ].join('\n');
+}
+
+/** 노트 생성(LLM) → v2. 실패·빈 노트·상한 초과는 v1 유지(보수 쪽) ⊕ 사유 — 조용한 폴백은 없다(호출부가 사건으로 남긴다). */
+export async function refineGoalFromFirstRound(
+  input: { v1: string; evidence: FirstRoundEvidence; visit: number; maxVisits?: number },
+  deps: { callLLM?: RefineCallLLM },
+): Promise<GoalRefinement> {
+  const v1Hash = goalHash(input.v1);
+  const kept = (reason: GoalKeptReason, detail?: string): GoalRefinement => ({ outcome: 'kept', v1Hash, v2Hash: v1Hash, kept: reason, rejectedEdits: [], ...(detail ? { detail } : {}) });
+  if (input.visit > (input.maxVisits ?? GOAL_REFINE_MAX_VISITS)) return kept('max-visits', `visit ${input.visit} > ${input.maxVisits ?? GOAL_REFINE_MAX_VISITS}`);
+  if (!deps.callLLM) return kept('no-provider');
+  let text: string;
+  try {
+    text = await deps.callLLM({ prompt: buildRegroundingPrompt(input.v1, input.evidence), systemPrompt: NOTE_SYSTEM });
+  } catch (error) {
+    return kept('provider-failed', (error instanceof Error ? error.message : String(error)).slice(0, 200));
+  }
+  const parsed = parseRegroundingNote(text);
+  if (!parsed.ok) return kept('note-unparseable', parsed.error);
+  return applyRegroundingNote(input.v1, parsed.note);
+}
+
+/** 되돌이 상한 — ta-journey author-dialogue 의 refine 왕복은 런당 한 번(첫 라운드 뒤). */
+export const GOAL_REFINE_MAX_VISITS = 1;
+
+/** 원장 `goal-refined` 사건 값 — v1·v2 해시 ⊕ 바뀐 줄 ⊕ 이유 ⊕ (유지면) kept 사유. */
+export function goalRefinedEvent(refinement: GoalRefinement, round: number): Record<string, unknown> {
+  const base = { outcome: refinement.outcome, round, v1Hash: refinement.v1Hash, v2Hash: refinement.v2Hash,
+    ...(refinement.rejectedEdits.length ? { rejectedEdits: refinement.rejectedEdits } : {}) };
+  if (refinement.outcome === 'kept') return { ...base, changedLines: [], reasons: [], kept: refinement.kept, ...(refinement.detail ? { detail: refinement.detail } : {}) };
+  return { ...base, changedLines: refinement.changedLines, reasons: refinement.reasons };
+}
+
+/** PR 본문 «골 변경» 절 — v1→v2 바뀐 줄과 이유(유지면 그 사유). */
+export function renderGoalChangeSection(refinement: GoalRefinement): string {
+  const head = ['## 골 변경', `- v1 ${refinement.v1Hash.slice(0, 12)} → v2 ${refinement.v2Hash.slice(0, 12)} (방향·KPI 줄 불변)`];
+  if (refinement.outcome === 'kept') return [...head, `- 시도 · v1 유지 · 사유 ${refinement.kept}${refinement.detail ? ` (${refinement.detail})` : ''}`,
+    ...refinement.rejectedEdits.map((edit) => `- 버린 편집: ${edit}`)].join('\n');
+  return [...head,
+    ...refinement.changedLines.flatMap((c) => [`- [${c.zone}] \`${c.before}\``, `  → \`${c.after}\``, `  이유: ${c.reason}`]),
+    ...refinement.rejectedEdits.map((edit) => `- 버린 편집: ${edit}`)].join('\n');
+}
+
+/**
+ * orchestrator 호출점 한 곳 — 첫 라운드 뒤 · 둘째 라운드 프롬프트 직전.
+ * 관측 = 원장 `goal-refined`(observe → 런 원장 ⊕ debug.log 범주 `self-implement.goal-refine`).
+ * 돌려준 goal 이 다음 라운드 프롬프트의 골이다(유지면 v1).
+ */
+export async function runFirstRoundRefine(input: {
+  goal: string;
+  evidence: FirstRoundEvidence;
+  round: number;
+  visit: number;
+  callLLM?: RefineCallLLM;
+  observe: (event: string, data: Record<string, unknown>, opt?: { category?: string; level?: 'warn' }) => void;
+}): Promise<{ goal: string; refinement: GoalRefinement }> {
+  let refinement: GoalRefinement;
+  try {
+    refinement = await refineGoalFromFirstRound({ v1: input.goal, evidence: input.evidence, visit: input.visit }, { callLLM: input.callLLM });
+  } catch (error) {
+    const v1Hash = goalHash(input.goal);
+    refinement = { outcome: 'kept', v1Hash, v2Hash: v1Hash, kept: 'provider-failed', rejectedEdits: [], detail: (error instanceof Error ? error.message : String(error)).slice(0, 200) };
+  }
+  // ⚠️ 유지(kept)는 전부 warn — seam(callLLM) 부재로 늘 no-provider 인 런도 «조용히 꺼지지» 않는다(리뷰 r1 should-fix 4).
+  input.observe('goal-refined', goalRefinedEvent(refinement, input.round), { category: 'self-implement.goal-refine', ...(refinement.outcome === 'refined' ? {} : { level: 'warn' as const }) });
+  return { goal: refinement.outcome === 'refined' ? refinement.v2 : input.goal, refinement };
+}

package/src/self-implement/graph-overlay-yaml.ts

@@ -199,9 +199,35 @@ export function applyGraphOverlays(
     applied.push(overlay.overlayId);
   }
 
-  // ⑵ 계약 없는 노드를 «거부» — 권한 없는 노드가 조용히 들어오는 것을 막는다.
+  // ⑵ 계약 없는 실행 노드를 거부한다. 기존 종결 gate 와 여정 선언은
+  // 원본 그대로일 때만 예외로 보존한다. 오버레이가 바꾼 노드에는 계약이 필요하다.
   for (const node of next.nodes) {
-    if (!node.contract || node.contract.tools === '') {
+    const original = template.nodes.find((candidate) => candidate.nodeId === node.nodeId);
+    // 기존 무계약 여정 선언은 노드와 그 출입 간선·종결 지위가 모두 그대로일 때만 보존한다.
+    // 새 경로가 실행 권한 없는 노드를 노출하면 계약 검사를 다시 건다.
+    const touchesNode = (edge: GraphTemplateSpec['edges'][number]) => edge.from === node.nodeId
+      || edge.to === node.nodeId
+      || Object.values(edge.map ?? {}).includes(node.nodeId)
+      || (edge.fallback ?? []).some((fallback) => fallback.node === node.nodeId);
+    const untouchedJourneyDeclaration = original?.journeyStage !== undefined
+      && original.contract === undefined
+      && JSON.stringify(node) === JSON.stringify(original)
+      && JSON.stringify(next.edges.filter(touchesNode)) === JSON.stringify(template.edges.filter(touchesNode))
+      && next.terminalNodes.includes(node.nodeId) === template.terminalNodes.includes(node.nodeId);
+    const existingTerminalGate = original?.kind === 'gate' && original.recipe === 'none'
+      && original.contract === undefined
+      && JSON.stringify(node) === JSON.stringify(original)
+      && template.terminalNodes.includes(node.nodeId)
+      && next.terminalNodes.includes(node.nodeId)
+      && !template.edges.some((edge) => edge.from === node.nodeId)
+      && !next.edges.some((edge) => edge.from === node.nodeId);
+    const contract = node.contract;
+    const validContract = contract != null && Array.isArray(contract.inputs)
+      && contract.inputs.every((input) => typeof input === 'string')
+      && typeof contract.tools === 'string' && contract.tools.trim() !== ''
+      && Array.isArray(contract.outputs)
+      && contract.outputs.every((output) => typeof output === 'string');
+    if (!untouchedJourneyDeclaration && !existingTerminalGate && !validContract) {
       rejections.push({ kind: 'node-without-contract', overlayId: applied.join(',') || '<none>', nodeId: node.nodeId });
     }
   }