elanous 0.2.34 → 0.2.35

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

@@ -2619,6 +2619,244 @@ export function goalContextEvidence(root: string): string[] {
     });
 }
 
+/** ACCEPTANCE-FROM-VERIFY-MENU — 저작기가 모든 골에 직접 쓰는 TDD 다섯 줄 절(사람 손 저작 대체). */
+export const VERIFICATION_PLAN_HEADING = '### 검증 계획(TDD)';
+export type InjectionLadderLevel = 'L0' | 'L1' | 'L2' | 'L3' | 'L4';
+const INJECTION_LADDER: Record<InjectionLadderLevel, string> = {
+  L0: 'test 우주 합성 사건',
+  L1: '생산 함수 ⊕ 기록된 실제 입력',
+  L2: 'src/ux-sim fake-llm·fake-bin·fake-clock',
+  L3: '격리 실물 런 — bare origin ⊕ fake gh',
+  L4: '격리 fixture Pod Job',
+};
+const VERIFICATION_MENU_DOC = join('docs', 'goal-context', '03-verification-menu.md');
+const MOCK_CATALOG_DOC = join('docs', 'goal-context', '04-mock-scenarios.md');
+
+/** 저장소 안의 검증 메뉴·무대 카탈로그를 읽는다. 없으면 null(저작은 «새 무대»로 내려간다). */
+export function readVerificationMenuDocs(root: string | undefined): { menu: string | null; catalog: string | null } {
+  const read = (relativePath: string): string | null => {
+    if (!root) return null;
+    try { return readFileSync(join(root, relativePath), 'utf8'); } catch { return null; }
+  };
+  return { menu: read(VERIFICATION_MENU_DOC), catalog: read(MOCK_CATALOG_DOC) };
+}
+
+interface CatalogStage { id: string; name: string; run: string; level: InjectionLadderLevel; strong: string[]; weak: string[] }
+interface MenuRow { method: string; command: string; stages: string }
+
+const CATALOG_STOP_WORDS = new Set(['bun', 'bin', 'elanous', 'elanous.mjs', 'mjs', 'test', 'git', 'grep', 'head', 'json', 'path', 'paths']);
+const CATALOG_KOREAN_STOP_WORDS = new Set(['무대', '시험', '실제', '생산', '격리', '바퀴']);
+
+function catalogField(block: string, label: string): string {
+  return new RegExp(`^- \\*\\*${label}:\\*\\*\\s*(.*)$`, 'mu').exec(block)?.[1]?.trim() ?? '';
+}
+
+/** 우주 필드로 주입 사다리 단을 정한다 — 카탈로그 문면이 바뀌어도 코드가 MS 번호를 외우지 않게. */
+function ladderLevelForUniverse(universe: string): InjectionLadderLevel {
+  if (/Pod|Job/u.test(universe)) return 'L4';
+  if (/임시 git|bare|clone|stub|격리 HOME|가지/u.test(universe)) return 'L3';
+  if (/ux-sim|fake/u.test(universe)) return 'L2';
+  if (/test|--test/u.test(universe)) return 'L0';
+  return 'L1';
+}
+
+function parseCatalogStages(catalog: string): CatalogStage[] {
+  const blocks = catalog.split(/^(?=### )/mu).filter((block) => /^### .*\bMS-\d+\b/u.test(block));
+  return blocks.flatMap((block) => {
+    const header = /^### (?:<a [^>]*><\/a>\s*)?(MS-\d+)\s+(.*)$/mu.exec(block);
+    if (!header) return [];
+    const [, id, name] = header as unknown as [string, string, string];
+    const universe = catalogField(block, '우주');
+    const behaviour = catalogField(block, '증명하는 동작');
+    const run = catalogField(block, '실행');
+    const text = `${name} ${behaviour} ${run}`;
+    const strong = new Set<string>();
+    const weak = new Set<string>();
+    for (const span of text.match(/`[^`]+`/gu) ?? []) {
+      for (const word of span.slice(1, -1).match(/[A-Za-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*/gu) ?? []) strong.add(word.toLowerCase());
+    }
+    for (const word of text.match(/[A-Za-z][A-Za-z0-9_-]{3,}/gu) ?? []) {
+      const lower = word.toLowerCase();
+      if (!CATALOG_STOP_WORDS.has(lower) && !strong.has(lower)) weak.add(lower);
+      if (/[a-z][A-Z]/u.test(word)) strong.add(lower);
+    }
+    for (const word of name.split(/[^\p{Script=Hangul}]+/u)) {
+      if (word.length >= 2 && !CATALOG_KOREAN_STOP_WORDS.has(word)) weak.add(word);
+    }
+    for (const word of strong) weak.delete(word);
+    return [{ id, name: name.trim(), run, level: ladderLevelForUniverse(universe), strong: [...strong], weak: [...weak] }];
+  });
+}
+
+function parseMenuRows(menu: string): MenuRow[] {
+  return menu.split(/\r?\n/u)
+    .filter((line) => line.startsWith('|') && !/^\|\s*-/u.test(line) && !/^\|\s*방법\s*\|/u.test(line))
+    .map((line) => line.split('|').slice(1, -1).map((cell) => cell.trim()))
+    .filter((cells) => cells.length >= 5)
+    .map((cells) => ({ method: cells[0]!, command: cells[3]!, stages: cells[4]! }));
+}
+
+function oneLine(text: string, max = 160): string {
+  const flat = text.replace(/\s+/gu, ' ').trim();
+  return [...flat].length > max ? `${[...flat].slice(0, max - 1).join('')}…` : flat;
+}
+
+function firstTestTarget(targetPaths: readonly string[]): string {
+  const test = targetPaths.find((path) => /\.test\.[cm]?[jt]sx?$/u.test(path));
+  if (test) return test;
+  const source = targetPaths.find((path) => /\.[cm]?[jt]sx?$/u.test(path));
+  return source ? source.replace(/\.([cm]?[jt]sx?)$/u, '.test.$1') : '<대상>.test.ts';
+}
+
+function wiringSymbol(ask: string): string | null {
+  for (const span of ask.match(/`([A-Za-z_$][\w$]*)(?:\(\))?`/gu) ?? []) {
+    const name = /`([A-Za-z_$][\w$]*)/u.exec(span)?.[1];
+    if (name && /[a-z][A-Z]|^[A-Z][a-z]+[A-Z]/u.test(name)) return name;
+  }
+  return ask.match(/\b[a-z][a-z0-9]*[A-Z][A-Za-z0-9]*\b/u)?.[0] ?? null;
+}
+
+const OPERATIONAL_MENTION = /운영\s*(?:데이터|사건|실물)|production\s+(?:data|events?)/iu;
+const OPERATIONAL_EXCLUSION = /없이|제외|말고|금지|빼고|아니|않|못\s|쓰지|안\s*(?:쓴|쓰|읽|본)|대신|without|\bnot\b|\bno\b|never|avoid|exclud/iu;
+
+/** 운영 데이터·사건을 «입력»으로 선언한 문장이 하나라도 있나 — 배제·부정 문장은 세지 않는다(메뉴 §선택 원칙). */
+export function operationalInputDeclared(ask: string): boolean {
+  return ask.split(/(?<=[.!?。])\s+|\r?\n/u)
+    .some((sentence) => OPERATIONAL_MENTION.test(sentence) && !OPERATIONAL_EXCLUSION.test(sentence));
+}
+
+export interface VerificationPlanInput {
+  ask: string;
+  behaviour: string;
+  targetPaths: readonly string[];
+  menu: string | null;
+  catalog: string | null;
+}
+export interface VerificationPlan {
+  lines: string[];
+  stage: { source: 'catalog' | 'new-stage'; id: string | null; level: InjectionLadderLevel };
+  menuPresent: boolean;
+  catalogPresent: boolean;
+}
+
+/**
+ * 순수 함수: 검증 메뉴·무대 카탈로그를 근거로 «검증 계획(TDD)» 다섯 줄을 쓴다.
+ * ① 증명할 동작 ② 무대(MS-xx 또는 «새 무대: 이름 — 명령») ⊕ 주입 사다리 L0–L4
+ * ③ 먼저 쓸 RED 시험 ④ GREEN 뒤 같은 명령 ⑤ 생산 진입점 배선(MS-05).
+ * 운영 실물은 메뉴 원칙대로 «운영 데이터·사건이 입력일 때만» 가리킨다.
+ */
+export function authorVerificationPlan(input: VerificationPlanInput): VerificationPlan {
+  const { ask } = input;
+  const askLower = ask.toLowerCase();
+  const stages = input.catalog ? parseCatalogStages(input.catalog) : [];
+  const menuRows = input.menu ? parseMenuRows(input.menu) : [];
+  let best: { stage: CatalogStage; score: number } | null = null;
+  for (const stage of stages) {
+    if (stage.id === 'MS-05') continue;   // 배선은 ⑤ 줄 몫이다.
+    const score = stage.strong.filter((word) => askLower.includes(word)).length * 2
+      + stage.weak.filter((word) => askLower.includes(word)).length;
+    if (score >= 2 && (!best || score > best.score)) best = { stage, score };
+  }
+  // ⛔ 언급이 아니라 «입력»일 때만 — 「운영 실물 없이 fixture 로」처럼 배제하는 문장은 고르지 않는다(리뷰 must-fix).
+  //   글자 창이 아니라 «문장» 단위로 본다 — 운영 데이터를 말한 문장에 배제·부정 표현이 하나라도 있으면 그 문장은 입력 선언이 아니다.
+  const operational = operationalInputDeclared(ask);
+  const operationalRow = menuRows.find((row) => row.method.includes('운영 실물'));
+  const operationalNote = operational
+    ? ` · 운영 실물: 메뉴 «${operationalRow?.method ?? '운영 실물 로그 관측'}» — 운영 데이터가 입력일 때만${operationalRow ? ` (${oneLine(operationalRow.command.replace(/`/gu, ''), 120)})` : ''}`
+    : '';
+  const testFile = firstTestTarget(input.targetPaths);
+  const cellId = ask.match(/\b[A-Z][A-Z0-9]+(?:-[A-Z0-9]+)+\b/u)?.[0];
+  const behaviour = oneLine((input.behaviour || '').split(/\s*(?:판정선|판정\s*신호)\s*(?:\(반증\))?\s*:/u)[0] || 'ask 에서 동작 문장을 고르지 못했다 — 사람이 ① 을 채운다', 120);
+  // ⛔ 시험 이름이 ④ 의 인라인 코드 안 `-t` 정규식으로 들어간다 — 백틱·따옴표·정규식 메타문자가 남으면
+  //   명령이 깨지거나 자기 시험을 못 고른다. 칸 id 가 이미 문장에 있으면 다시 붙이지 않는다(실측 2026-10-21).
+  const testName = oneLine(`${cellId && !behaviour.includes(cellId) ? `${cellId}: ` : ''}${behaviour}`, 70)
+    .replace(/[`'"()[\]{}.*+?^$|\\…]/gu, '').trim();
+  const testCommand = `bun test ${testFile} -t '${testName}'`;
+  let stageLine: string;
+  let stage: VerificationPlan['stage'];
+  if (best) {
+    const row = menuRows.find((candidate) => candidate.stages.includes(best!.stage.id));
+    const run = /`([^`]+)`/u.exec(best.stage.run)?.[1];
+    stage = { source: 'catalog', id: best.stage.id, level: best.stage.level };
+    stageLine = `- ② 무대: ${best.stage.id} ${best.stage.name} · ${best.stage.level} (${INJECTION_LADDER[best.stage.level]})${row ? ` · 메뉴: ${row.method}` : ''}${run ? ` · 실행: \`${run}\`` : ''}${operationalNote}`;
+  } else {
+    const screen = /TUI|화면|렌더|위젯|ux-sim|fake-llm|fake-bin|fake-clock|타이머/iu.test(ask);
+    const level: InjectionLadderLevel = screen ? 'L2' : 'L1';
+    const uxRow = menuRows.find((row) => row.method.includes('ux-sim'));
+    const command = screen
+      ? (/`([^`]+)`/u.exec(uxRow?.command ?? '')?.[1] ?? "bun test -- 'src/ux-sim/<관련 시험 파일>.test.ts'")
+      : `bun test ${testFile}`;
+    const base = (input.targetPaths.find((path) => !/\.test\./u.test(path)) ?? testFile).split('/').pop()!.replace(/\.[^.]+$/u, '');
+    const name = screen ? `${base} ux-sim 고정 입력` : `${base} 기록된 실제 입력 fixture`;
+    stage = { source: 'new-stage', id: null, level };
+    stageLine = `- ② 무대: 새 무대: ${name} — \`${command}\` · ${level} (${INJECTION_LADDER[level]})${input.catalog ? ' · 카탈로그(04-mock-scenarios.md)에 맞는 MS 없음' : ' · 카탈로그 문서 없음'}${operationalNote}`;
+  }
+  const docOnly = input.targetPaths.length > 0 && input.targetPaths.every((path) => /\.md$/iu.test(path));
+  if (docOnly) {
+    // 문서 전용 골: 시험 파일·생산 호출부가 없다 — 문구 대조로 RED/GREEN 을 재고 ⑤ 는 비적용 사유·대체 증거를 쓴다(리뷰 must-fix).
+    const docs = input.targetPaths.join(' ');
+    const phrase = (/`([^`]+)`/u.exec(behaviour)?.[1] ?? behaviour.replace(/[`'"]/gu, '').slice(0, 30)).trim();
+    const check = `rg -n -F '${phrase.replace(/'/gu, '’')}' ${docs}`;
+    stage = { source: 'new-stage', id: null, level: 'L1' };
+    return {
+      lines: [
+        VERIFICATION_PLAN_HEADING,
+        `- ① 증명할 동작: ${behaviour}`,
+        `- ② 무대: 새 무대: 문서 문구 대조 — \`${check}\` · L1 (${INJECTION_LADDER.L1}) · 문서 전용 골이라 카탈로그 무대 비적용${operationalNote}`,
+        `- ③ 먼저 확인할 RED: \`${check}\` — 고치기 전에는 0행이다(그 문구가 아직 문서에 없다)`,
+        `- ④ GREEN 뒤 같은 명령: \`${check}\` → 1행 이상`,
+        `- ⑤ 생산 진입점 배선: 해당 없음 — 문서 전용 골이라 생산 호출부가 없다 · 대신 ④ 의 문구 대조와 문서 안 링크 대상이 실제 파일인지(\`test -f <링크 경로>\`)를 증거로 쓴다`,
+      ],
+      stage,
+      menuPresent: input.menu !== null,
+      catalogPresent: input.catalog !== null,
+    };
+  }
+  const symbol = wiringSymbol(ask);
+  const productionPaths = input.targetPaths.filter((path) => !/\.test\./u.test(path) && !/\.md$/u.test(path));
+  const wiring = `git grep -n -F '${symbol ?? '<새 함수>'}(' HEAD -- ${productionPaths.length ? productionPaths.join(' ') : 'src'}`;
+  return {
+    lines: [
+      VERIFICATION_PLAN_HEADING,
+      `- ① 증명할 동작: ${behaviour}`,
+      stageLine,
+      `- ③ 먼저 쓸 시험(RED): \`${testFile}\` › '${testName}' — ① 의 동작이 아직 없어 단언이 실패한다(구현 전에 먼저 쓰고 실패를 확인한다)`,
+      `- ④ GREEN 뒤 같은 명령: \`${testCommand}\` → 0 fail`,
+      `- ⑤ 생산 진입점 배선(MS-05): \`${wiring}\` — 호출부를 커밋한 뒤 PR head 에서 돌린다 · 정의·주석·시험 행이 아닌 생산 호출 문장 1건 이상(0건만으로 미배선 판정 금지)`,
+    ],
+    stage,
+    menuPresent: input.menu !== null,
+    catalogPresent: input.catalog !== null,
+  };
+}
+
+const NON_BEHAVIOUR_LINE = /^(?:[-*]\s*)?(?:대상\s*경로|신설|경계|불변식|판정선|판정\s*신호|완료\s*경계|답하지\s*못하는\s*것|칸\s*id)(?=\s|:|\(|$)|대상\s*경로(?:는|:)/u;
+
+/** ① 의 재료: 대상 경로·표지 줄을 되풀이한 요구는 «동작»이 아니다 — 첫 동작 문장을 고른다(실측 2026-10-21). */
+export function verificationBehaviour(checklist: readonly string[], ask: string): string {
+  const candidate = checklist.find((item) => item.trim() && !NON_BEHAVIOUR_LINE.test(item.trim()));
+  if (candidate) return candidate;
+  const line = ask.split(/\r?\n/u).map((text) => text.trim())
+    .find((text) => text && !NON_BEHAVIOUR_LINE.test(text) && !/^#/u.test(text));
+  return line ?? goalSummary(ask);
+}
+
+function observedVerificationPlan(input: Omit<VerificationPlanInput, 'menu' | 'catalog'>, repositoryRoot: string | undefined, authorRunId: string): string[] {
+  try {
+    const plan = authorVerificationPlan({ ...input, ...readVerificationMenuDocs(repositoryRoot) });
+    try {
+      observeGoalAuthor('goal-author', 'verification-plan', {
+        authorRunId, source: plan.stage.source, stageId: plan.stage.id, level: plan.stage.level,
+        menuPresent: plan.menuPresent, catalogPresent: plan.catalogPresent,
+      });
+    } catch { /* observation is fail-soft */ }
+    return plan.lines;
+  } catch (error) {
+    try { observeGoalAuthor('goal-author', 'verification-plan-failed', { authorRunId, error: error instanceof Error ? error.message : String(error) }); } catch { /* fail-soft */ }
+    return [VERIFICATION_PLAN_HEADING, '- UNVERIFIABLE: 검증 계획 저작이 실패했다 — 사람이 다섯 줄(동작·무대·RED·GREEN·배선)을 채운다.'];
+  }
+}
+
 function groundedProblem(facts: CodebaseGrounding, tracedPathsIncluded: boolean): string[] {
   const persistentEvidence = persistentEvidenceItems(facts);
   return [
@@ -5298,6 +5536,12 @@ async function authorGoalWithSupersededRootIntent(
       '## 답하지 못하는 것',
       '- No persistent grounding was performed in lite authoring.',
       '',
+      // ⭐ full 과 같은 자리 — `## 답하지 못하는 것` → `### 수용 구별 관측` → `### 검증 계획(TDD)` → `## 불변식`.
+      '### 수용 구별 관측',
+      '- Status: not-observed — lite authoring records no acceptance-distinction observation.',
+      '',
+      ...observedVerificationPlan({ ask, behaviour: verificationBehaviour(enhancement.checklist, ask), targetPaths }, deps.repositoryRoot, authorRunId),
+      '',
       '## 불변식',
       '- No persistent grounding was performed in lite authoring.',
       '',
@@ -5754,6 +5998,12 @@ async function authorGoalWithSupersededRootIntent(
     '### 수용 구별 관측',
     ...distinctionSection,
     '',
+    ...observedVerificationPlan({
+      ask,
+      behaviour: verificationBehaviour(enhancement.checklist, ask),
+      targetPaths: [...new Set(declaredTargetPaths(ask))],
+    }, deps.repositoryRoot, authorRunId),
+    '',
     '## 불변식',
     ...invariants.lines,
     '',

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 };
+}