elanous 0.2.40 → 0.2.41

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

@@ -84,7 +84,7 @@ export interface GoalAuthorSelfResolutionContext {
 
 export type GoalAuthorSelfResolution =
   | { answer: string; evidence: readonly string[]; assumption?: string; declined?: undefined }
-  | { answer?: undefined; evidence?: undefined; declined?: boolean };
+  | { answer?: undefined; evidence?: undefined; declined?: boolean; failed?: boolean };
 
 export interface GoalAuthorClarificationResolutionDeps {
   /** Elanousic authoring seam; it must return no answer when the available evidence is insufficient. */
@@ -227,7 +227,7 @@ export async function defaultGoalAuthorSelfResolve(
       parsed = JSON.parse(result);
     } catch {
       observeSelfResolve('self-resolve-parse-failed', context, startedAt, { usage: deriveUsage(usages) });
-      return {};
+      return { failed: true };
     }
     const answer = parsed !== null && typeof parsed === 'object'
       ? (parsed as { answer?: unknown }).answer
@@ -256,7 +256,7 @@ export async function defaultGoalAuthorSelfResolve(
       startedAt,
       { usage: deriveUsage(usages) },
     );
-    return {};
+    return { failed: true };
   } finally {
     clearTimeout(timeout);
   }
@@ -530,7 +530,7 @@ export function goalClarificationDecisionCategory(
   const text = [clarification.header, clarification.question, ...clarification.options.flatMap((option) => [option.label, option.description])]
     .join(' ')
     .toLocaleLowerCase();
-  if (/\b(payment|purchase|spend|budget|credit|charge|price|cost|paid)\b|결제|구매|지출|예산|크레딧|과금|가격|비용/.test(text)) return 'money';
+  if (/\b(payment|purchase|spend|budget|credit|charge|price|cost|paid|refund|reimburse(?:ment)?|chargeback|transfer|wire(?:\s+transfer)?|withdraw(?:al)?|deposit|invoice|subscribe|subscription|renewal)\b|결제|구매|지출|예산|크레딧|과금|가격|비용|환불|환급|송금|이체|구독|정기결제/.test(text)) return 'money';
   if (/\b(security|credential|token|secret|password|authorization|authentication|permission|access control)\b|보안|자격 증명|토큰|비밀키|비밀번호|인가|인증|권한/.test(text)) return 'security';
   if (/\b(publish|publication|deploy|send|delete|release|irreversible|external side effect|production)\b|발행|게시|배포|전송|삭제|릴리스|되돌릴 수 없|외부 효과|운영 환경/.test(text)) return 'irreversible';
   return undefined;
@@ -827,7 +827,7 @@ export async function selfAnswerGoalDocumentClarifications(
     runId?: string;
     skipQuestionIds?: ReadonlySet<string>;
   },
-): Promise<{ document: string; asked: number; answered: number; unanswered: number; newlyAnswered: number }> {
+): Promise<{ document: string; asked: number; answered: number; unanswered: number; newlyAnswered: number; resolverFailedQuestionIds: string[] }> {
   const clarifications = parseGoalDocumentClarifications(document);
   const pending = clarifications.filter((item) => !item.answered);
   // The first say pass may already have self-answered some questions while authoring: count those,
@@ -837,6 +837,7 @@ export async function selfAnswerGoalDocumentClarifications(
     : 0;
   let updated = document;
   let answered = 0;
+  const resolverFailedQuestionIds: string[] = [];
   const evidence = options.evidence ?? document.split(/\r?\n/)
     .filter((line) => /^(?:\s*- (?:\[code:|\[document:|TRACED PATHS|evidence:|Evidence:)|\s*-?\s*`?(?:src|test|scripts)\/[^\s`]+:\d+)/i.test(line))
     .slice(0, 40);
@@ -844,6 +845,8 @@ export async function selfAnswerGoalDocumentClarifications(
     if (parseGoalDocumentClarifications(updated).filter((entry) => entry.questionId === item.questionId).length !== 1) continue;
     let response: Awaited<ReturnType<typeof resolveGoalAuthorClarification>>;
     let declined = false;
+    let resolverFailed = false;
+    const baseResolver = options.resolver ?? defaultGoalAuthorSelfResolve;
     try { response = await resolveGoalAuthorClarification({
       questionId: item.questionId,
       kind: 'scope',
@@ -853,17 +856,25 @@ export async function selfAnswerGoalDocumentClarifications(
       blocking: false,
     }, {
       selfResolve: async (context) => {
-        const resolution = await (options.resolver ?? defaultGoalAuthorSelfResolve)(context);
-        declined = resolution.declined === true;
-        return resolution;
+        try {
+          const resolution = await baseResolver(context);
+          declined = resolution.declined === true;
+          resolverFailed = 'failed' in resolution && resolution.failed === true;
+          return resolution;
+        } catch (error) {
+          resolverFailed = true;
+          throw error;
+        }
       },
       evidence,
       ask: options.ask,
       selfResolutionSelected: true,
     }); } catch {
       // A resolver failure leaves this question unanswered; the remaining questions are still attempted.
+      resolverFailedQuestionIds.push(item.questionId);
       continue;
     }
+    if (resolverFailed) resolverFailedQuestionIds.push(item.questionId);
     let defaultExportCount: number | undefined;
     if (response.answer === null && item.questionId === 'preservation_contract'
       && declined) {
@@ -916,7 +927,7 @@ export async function selfAnswerGoalDocumentClarifications(
     path: options.path, asked, answered, unanswered,
     reason: unanswered === 0 ? 'answered' : 'insufficient-evidence',
   });
-  return { document: updated, asked, answered, unanswered, newlyAnswered };
+  return { document: updated, asked, answered, unanswered, newlyAnswered, resolverFailedQuestionIds };
 }
 
 /** SelfImplement boundary: resolve pending questions itself and record a bounded policy assumption if that fails.
@@ -940,15 +951,23 @@ export async function selfAnswerOrAssumeGoalDocumentClarifications(
   const decisionRequired: Array<{ questionId: string; header: string; question: string; category: GoalClarificationDecisionCategory }> =
     safetyQuestions.map(({ entry, category }) => ({ questionId: entry.questionId, header: entry.header, question: entry.question, category }));
   for (const item of parseGoalDocumentClarifications(updated).filter((entry) => !entry.answered)) {
+    if (attempted.resolverFailedQuestionIds.includes(item.questionId)) continue;
     const category = goalClarificationDecisionCategory(item);
     if (category) continue;
     const offered = item.options.filter((option) => option.label.trim() && !/[\r\n]/.test(option.label));
-    const useOfferedOption = !item.includeOther && offered.length > 0;
+    const requestText = (options.ask ?? '').toLocaleLowerCase().replace(/\s+/g, ' ').trim();
+    const inScopeOptions = item.includeOther ? [] : offered.filter((option) =>
+      [option.label, option.description ?? ''].some((candidate) => {
+        const normalized = candidate.toLocaleLowerCase().replace(/\s+/g, ' ').trim();
+        return normalized.length >= 4 && requestText.includes(normalized);
+      }));
+    if (!item.includeOther && inScopeOptions.length !== 1) continue;
+    const useOfferedOption = !item.includeOther;
     const answer = useOfferedOption
-      ? offered[0]!.label.trim()
+      ? inScopeOptions[0]!.label.trim()
       : '근거가 부족하므로 요청에 명시된 범위만 진행한다고 가정한다';
     const assumption = useOfferedOption
-      ? '자가 해소가 답을 내지 못해 자유 답변 없이 제시된 첫 후보를 정책 가정으로 선택했다'
+      ? '요청 원문에 명시된 후보만 허용되어 그 후보를 정책 가정으로 선택했다'
       : '자가 해소가 답을 내지 못해 추가 범위를 만들지 않고 요청에 명시된 범위만 진행한다고 가정했다';
     try {
       const current = findUnansweredGoalDocumentClarification(updated, item.questionId);

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

@@ -57,6 +57,7 @@ import { targetScopedGoalText } from './goal-text-path-scope.js';
 import { parseReleaseNoteSection } from '../release-loop/release-note.js';
 import { declaredNewFilePaths } from './goal-new-paths.js';
 import { classifyGoalCommandExecution, type GoalCommandExecutionResult } from './goal-command-execution.js';
+import { formatShadowArmProbeRecord, probeShadowArm, type ShadowArmProbeRecord, type ShadowDifficulty } from '../budget/shadow-arms.js';
 import { identityLines, repositoryIdentifiers } from './goal-author-identity.js';
 import { selectRelevantAuthoringLessons } from './knowhow-pack.js';
 import { elanousStateRoot } from '../autopilot/state-paths.js';
@@ -385,6 +386,7 @@ type GoalAuthorTimedPhase = GoalAuthorPhase | GoalAuthorAssembleSubphase;
 function startGoalAuthorPhase(phase: GoalAuthorTimedPhase, authorRunId: string, onProgress?: GoalAuthorDeps['onProgress']): number {
   observeGoalAuthor('goal-author', 'phase-start', { phase, authorRunId });
   if (GOAL_AUTHOR_PHASES.includes(phase as GoalAuthorPhase)) {
+    if (phase === 'assemble') probeAuthoringShadowArm(authorRunId);
     if (onProgress) onProgress(phase as GoalAuthorPhase, 'start');
     else process.stderr.write(`[goal-author] ${phase} started\n`);
   }
@@ -403,6 +405,56 @@ function endGoalAuthorPhase(phase: GoalAuthorTimedPhase, startedAt: number, auth
   }
 }
 
+// ── SHADOW-MODEL-ARMS · 저작 단계 그림자 «1팔» probe(명시 실행 · 관측만) ────────────────
+/**
+ * ⭐ 저작 단계 그림자 1팔 — `planShadowArms`(src/budget/shadow-arms.ts) 를 일일 상한
+ *   안에서 «실제 호출»해 난이도·모델·예상/실제 비용·결과를 한 줄 원장 형식으로 기록한다.
+ *   ⛔ 관측만 한다 — 라이브 LLM(Claude 구독) 호출 0 · 골/PR/착지 파일 쓰기 0.
+ *      팔은 «계획»이고, 실행·자동 런 훅·다른 단계(implement·review·judge) 팔은 후속 조각이다.
+ *   ⛔ 오늘 이미 쓴 그림자 예산의 실 지출 원장 배선도 후속 — 지금은 0지출 고정값으로 판정한다.
+ */
+export const SHADOW_AUTHORING_ARM_MODEL = 'gpt-5.6-terra';
+export const SHADOW_AUTHORING_ARM_DIFFICULTY: ShadowDifficulty = 'medium';
+export const SHADOW_AUTHORING_ARM_INPUT_TOKENS = 24_000;
+export const SHADOW_AUTHORING_ARM_OUTPUT_TOKENS = 8_000;
+export const SHADOW_AUTHORING_SPENT_TODAY_USD = 0;
+export const SHADOW_AUTHORING_DAILY_CAP_USD = 5;
+
+export interface AuthoringShadowArmProbe {
+  record: ShadowArmProbeRecord;
+  line: string;
+}
+
+let shadowArmProbeObserver: ((probe: AuthoringShadowArmProbe, authorRunId: string) => void) | undefined;
+
+function defaultShadowArmProbeObserver(probe: AuthoringShadowArmProbe, authorRunId: string): void {
+  observeGoalAuthor('goal-author', 'shadow-arm-authoring', { authorRunId, ...probe.record, line: probe.line });
+}
+
+/** 저작 단계 그림자 1팔을 실제 호출해 기록을 낸다 — 부작용은 관측 원장뿐이다(관측만). */
+export function probeAuthoringShadowArm(authorRunId: string): AuthoringShadowArmProbe {
+  const record = probeShadowArm({
+    stage: 'authoring',
+    difficulty: SHADOW_AUTHORING_ARM_DIFFICULTY,
+    inputTokens: SHADOW_AUTHORING_ARM_INPUT_TOKENS,
+    expectedOutputTokens: SHADOW_AUTHORING_ARM_OUTPUT_TOKENS,
+    candidates: [SHADOW_AUTHORING_ARM_MODEL],
+    spentTodayUsd: SHADOW_AUTHORING_SPENT_TODAY_USD,
+    dailyCapUsd: SHADOW_AUTHORING_DAILY_CAP_USD,
+  });
+  const probe: AuthoringShadowArmProbe = { record, line: formatShadowArmProbeRecord(record) };
+  const observer = shadowArmProbeObserver ?? defaultShadowArmProbeObserver;
+  observer(probe, authorRunId);
+  return probe;
+}
+
+/** 관측 접합점 갈아끼우기(시험 전용) — 인자 없이 부르면 생산 기본 관측자로 복원한다. */
+export function _setShadowArmProbeObserverForTesting(
+  observer?: (probe: AuthoringShadowArmProbe, authorRunId: string) => void,
+): void {
+  shadowArmProbeObserver = observer;
+}
+
 export type GoalFileLintLevel = 'ERROR' | 'WARN';
 
 export type GoalFileLintTag = 'canonical-structure' | 'evidence-section' | 'boundary-size' | 'launch-branch' | 'unanswered-clarification' | 'shell-damage' | 'traced-path' | 'traced-path-new' | 'grounding-evidence' | 'empty-result-population' | 'decision-signal-numeric-source' | 'decision-signal-numeric-coverage' | 'decision-signal-proxy-expectation' | 'out-of-target-requirement' | 'heading-form-marker' | 'blanket-invariant' | 'self-question-subject' | 'artifact-launch-declaration' | 'all-negative-signals' | 'unreadable-signals' | 'alternative-signals' | 'count-observation' | 'identifier-name-observation' | 'self-reported-observation' | 'default-invocation-observation' | 'release-note';
@@ -2972,7 +3024,17 @@ export function readVerificationMenuDocs(root: string | undefined): { menu: stri
   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 CatalogStage {
+  id: string;
+  name: string;
+  universe: string;
+  injection: string;
+  observation: 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']);
@@ -2999,8 +3061,10 @@ function parseCatalogStages(catalog: string): CatalogStage[] {
     const [, id, name] = header as unknown as [string, string, string];
     const universe = catalogField(block, '우주');
     const behaviour = catalogField(block, '증명하는 동작');
+    const injection = catalogField(block, '무대 세우기');
+    const observation = catalogField(block, '판정');
     const run = catalogField(block, '실행');
-    const text = `${name} ${behaviour} ${run}`;
+    const text = `${name} ${behaviour} ${universe} ${injection} ${observation} ${run}`;
     const strong = new Set<string>();
     const weak = new Set<string>();
     for (const span of text.match(/`[^`]+`/gu) ?? []) {
@@ -3015,7 +3079,8 @@ function parseCatalogStages(catalog: string): CatalogStage[] {
       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] }];
+    return [{ id, name: name.trim(), universe, injection, observation, run,
+      level: ladderLevelForUniverse(universe), strong: [...strong], weak: [...weak] }];
   });
 }
 
@@ -3095,6 +3160,10 @@ export function authorVerificationPlan(input: VerificationPlanInput): Verificati
   const operationalNote = operational
     ? ` · 운영 실물: 메뉴 «${operationalRow?.method ?? '운영 실물 로그 관측'}» — 운영 데이터가 입력일 때만${operationalRow ? ` (${oneLine(operationalRow.command.replace(/`/gu, ''), 120)})` : ''}`
     : '';
+  const completionEvidenceCommandValue = /^\s*(?:[-*]\s*)?완료\s*경계\s*증거\s*명령\s*:\s*(.+?)\s*$/mu.exec(ask)?.[1];
+  const completionEvidenceCommand = completionEvidenceCommandValue
+    ? validateGoalDoneEvidenceCommand(completionEvidenceCommandValue).command
+    : undefined;
   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);
@@ -3109,7 +3178,7 @@ export function authorVerificationPlan(input: VerificationPlanInput): Verificati
     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}`;
+    stageLine = `- ② 무대: ${best.stage.id} ${best.stage.name} · 우주: ${oneLine(best.stage.universe, 90)} · 사건 주입: ${oneLine(best.stage.injection, 120)} · 관측: ${oneLine(best.stage.observation, 120)} · ${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';
@@ -3146,6 +3215,9 @@ export function authorVerificationPlan(input: VerificationPlanInput): Verificati
   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'}`;
+  const e2 = completionEvidenceCommand
+    ? `E2 완료 경계 증거 명령 \`${completionEvidenceCommand}\` 을 origin/main 에서 rc0 확인`
+    : 'E2 완료 경계 증거 명령은 ask에 없거나 유효하지 않아 저작자가 채움';
   return {
     lines: [
       VERIFICATION_PLAN_HEADING,
@@ -3153,7 +3225,7 @@ export function authorVerificationPlan(input: VerificationPlanInput): Verificati
       stageLine,
       `- ③ 먼저 쓸 시험(RED): \`${testFile}\` › '${testName}' — ① 의 동작이 아직 없어 단언이 실패한다(구현 전에 먼저 쓰고 실패를 확인한다)`,
       `- ④ GREEN 뒤 같은 명령: \`${testCommand}\` → 0 fail`,
-      `- ⑤ 생산 진입점 배선(MS-05): \`${wiring}\` — 호출부를 커밋한 뒤 PR head 에서 돌린다 · 정의·주석·시험 행이 아닌 생산 호출 문장 1건 이상(0건만으로 미배선 판정 금지)`,
+      `- ⑤ 생산 진입점 배선(MS-05 · G1 v4): \`${wiring}\` — 호출부를 커밋한 뒤 PR head에서 돌린다 · 정의·주석·시험 행이 아닌 생산 호출 문장 1건 이상(0건만으로 미배선 판정 금지) · E1 착지 뒤 PR head가 main의 조상인지 확인 · ${e2} · E3 생산 진입점 시험 또는 mock 무대 · E4 운영 실물은 필수 아님`,
     ],
     stage,
     menuPresent: input.menu !== null,

package/src/self-implement/graph-stage-units.ts

@@ -0,0 +1,172 @@
+import { join } from 'node:path';
+import { createGraphUnitResolver } from './graph-unit-resolver.js';
+import { flattenGraphUnits } from './graph-unit-flatten.js';
+import {
+  implementLoopUnitEquivalence,
+  implementLoopUnitSpec,
+  stageUnitSeamsForGraph,
+  type ImplementLoopUnitEquivalence,
+  type ImplementStageUnitId,
+  type ImplementStageUnitSeam,
+} from './graph-templates.js';
+import type { GraphTemplateSpec } from './graph-yaml.js';
+
+/** 한 부품이 «실제로» 어느 파일에서 해석됐나 — 원장·관측이 「어느 판의 부품으로 걸었나」를 답한다. */
+export interface ResolvedStageUnit {
+  readonly stage: ImplementStageUnitId;
+  readonly call: string;
+  readonly unitId: string;
+  readonly version: number;
+  readonly path: string;
+  readonly hash: string;
+  readonly entry: string;
+  readonly nodes: readonly string[];
+  readonly exits: readonly string[];
+}
+
+/** ⛔ 「부품이 없다」와 「부품을 못 읽었다」를 가른다 — 성공이면 reason 은 undefined 다. */
+export interface StageUnitResolution {
+  readonly units: readonly ResolvedStageUnit[];
+  readonly flattened?: GraphTemplateSpec;
+  readonly equivalence?: ImplementLoopUnitEquivalence;
+  readonly reason?: string;
+}
+
+/** ⭐ 하나의 NodeContext — 골·근거·되먹임·예산·체크포인트가 저작→구현으로 «같은 객체»로 흐른다. */
+export interface StageNodeContext {
+  readonly goal: {
+    readonly goalId?: string;
+    readonly goalType?: string;
+    readonly graphId: string;
+    readonly graphVersion: string;
+  };
+  readonly grounding: {
+    readonly units: readonly ResolvedStageUnit[];
+    readonly flattenedNodeCount: number | null;
+    /** null 이면 평탄화 자체를 못 했다 — 「불변」으로 읽지 않는다(reason 이 그 자리를 덮는다). */
+    readonly equivalence: ImplementLoopUnitEquivalence | null;
+    /** 부품 해석은 됐지만 합성 평탄화가 실패한 원인을 보존한다. */
+    readonly resolutionReason?: string;
+  };
+  readonly feedback: { readonly attempts?: number };
+  readonly budget: { readonly unitCount: number; readonly visitBudget: number | null };
+  readonly checkpoint: { readonly runId: string; readonly round?: number };
+}
+
+/** 등록 부품을 graphs/units 에서 `id@version` 으로 해석하고, 합성 선언을 평탄화해 불변식을 값으로 낸다. */
+export function resolveStageUnits(
+  seams: readonly ImplementStageUnitSeam[],
+  graphsDir: string,
+): StageUnitResolution {
+  if (seams.length === 0) return { units: [] };
+  // ⛔ 호출자 경로가 곧 탐색 규약이다(graph-unit-resolver: dirname(caller)/units → dirname(caller) → repo/graphs/units).
+  const callerPath = join(graphsDir, 'implement-loop.yaml');
+  const resolver = createGraphUnitResolver();
+  const units: ResolvedStageUnit[] = [];
+  try {
+    for (const seam of seams) {
+      const unit = resolver(seam.call, callerPath);
+      // 부품 «단독» 평탄화 — unit 계약(entries·exits·terminal_nodes)이 그 자리에서 성립하는지 검증한다.
+      flattenGraphUnits(unit.template, unit.path, resolver);
+      units.push({
+        stage: seam.stage,
+        call: seam.call,
+        unitId: unit.template.graphId,
+        version: unit.template.version,
+        path: unit.path,
+        hash: unit.hash,
+        entry: seam.entry,
+        nodes: seam.nodes,
+        exits: unit.template.unit?.exits ?? [],
+      });
+    }
+    const flattened = flattenGraphUnits(
+      implementLoopUnitSpec(),
+      join(graphsDir, 'self-implement-units.yaml'),
+      resolver,
+    );
+    return { units, flattened, equivalence: implementLoopUnitEquivalence(flattened) };
+  } catch (error) {
+    return { units, reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export function buildStageNodeContext(input: {
+  readonly resolution: StageUnitResolution;
+  readonly graphId: string;
+  readonly graphVersion: string;
+  readonly runId: string;
+  readonly attempts?: number;
+  readonly round?: number;
+  readonly goalId?: string;
+  readonly goalType?: string;
+}): StageNodeContext {
+  const { resolution } = input;
+  const visitBudget = resolution.flattened === undefined
+    ? null
+    : resolution.flattened.nodes.reduce((total, node) => total + node.maxVisits, 0);
+  return {
+    goal: {
+      ...(input.goalId === undefined ? {} : { goalId: input.goalId }),
+      ...(input.goalType === undefined ? {} : { goalType: input.goalType }),
+      graphId: input.graphId,
+      graphVersion: input.graphVersion,
+    },
+    grounding: {
+      units: resolution.units,
+      flattenedNodeCount: resolution.flattened?.nodes.length ?? null,
+      equivalence: resolution.equivalence ?? null,
+      ...(resolution.reason === undefined ? {} : { resolutionReason: resolution.reason }),
+    },
+    feedback: input.attempts === undefined ? {} : { attempts: input.attempts },
+    budget: { unitCount: resolution.units.length, visitBudget },
+    checkpoint: { runId: input.runId, ...(input.round === undefined ? {} : { round: input.round }) },
+  };
+}
+
+/** 원장 관측 payload — ⛔ 큰 구조(평탄화 그래프 전체)를 싣지 않고 «판정에 쓰는 값»만 싣는다. */
+export function stageNodeContextObservation(context: StageNodeContext): Record<string, unknown> {
+  const equivalence = context.grounding.equivalence;
+  return {
+    graphId: context.goal.graphId,
+    graphVersion: context.goal.graphVersion,
+    runId: context.checkpoint.runId,
+    ...(context.checkpoint.round === undefined ? {} : { round: context.checkpoint.round }),
+    ...(context.grounding.resolutionReason === undefined ? {} : { resolutionReason: context.grounding.resolutionReason }),
+    units: context.grounding.units.map((unit) => ({
+      stage: unit.stage, call: unit.call, unitId: unit.unitId, version: unit.version, hash: unit.hash,
+      entry: unit.entry, nodes: unit.nodes, exits: unit.exits,
+    })),
+    flattenedNodeCount: context.grounding.flattenedNodeCount,
+    kindMismatches: equivalence?.kindMismatches.length ?? null,
+    missingEdges: equivalence?.missingEdges.length ?? null,
+    extraEdges: equivalence?.extraEdges.length ?? null,
+    visitBudget: context.budget.visitBudget,
+  };
+}
+
+/** 라운드마다 같은 부품이 «여전히» 그 파일·그 판인가 — 파일이 도는 중에 바뀌면 걸음이 신원과 갈린다. */
+export function stageUnitDrift(
+  units: readonly ResolvedStageUnit[],
+  graphsDir: string,
+): { readonly missing: readonly string[]; readonly changed: readonly string[] } {
+  if (units.length === 0) return { missing: [], changed: [] };
+  const callerPath = join(graphsDir, 'implement-loop.yaml');
+  const resolver = createGraphUnitResolver();
+  const missing: string[] = [];
+  const changed: string[] = [];
+  for (const unit of units) {
+    try {
+      const current = resolver(unit.call, callerPath);
+      if (current.hash !== unit.hash) changed.push(unit.call);
+    } catch {
+      missing.push(unit.call);
+    }
+  }
+  return { missing, changed };
+}
+
+/** 그래프의 단계 부품을 «생산 진입점 문장» 하나로 — orchestrator 가 이 함수를 부른다. */
+export function resolveGraphStageUnits(graphId: string, graphsDir: string): StageUnitResolution {
+  return resolveStageUnits(stageUnitSeamsForGraph(graphId), graphsDir);
+}

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

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
 import { GOAL_TYPES, type GoalType } from './goal-author.js';
 import type { GraphRunContractSpec } from './graph-run-contract.js';
-import { edgeMapOf, loadGraphTemplates, type GraphNodeContract, type GraphNodeKind, type GraphNodeSpec, type GraphTemplateSpec } from './graph-yaml.js';
+import { edgeMapOf, loadGraphTemplates, type GraphEdgeSpec, type GraphNodeContract, type GraphNodeKind, type GraphNodeSpec, type GraphTemplateSpec } from './graph-yaml.js';
 
 /** ⭐ RFC §5 «3단계» — 템플릿을 «데이터»로 둔다(RFC §4.1 어휘).
  *
@@ -96,6 +96,167 @@ const RESEARCH_LOOP: GraphTemplate = {
   },
 };
 
+/** ⭐ SELFIMPL-NODE-SEAMS-BACK — 한 NodeContext 가 저작→구현으로 흐르는 다섯 입력 칸.
+ *
+ *  ⛔ 이 다섯은 «부품의 계약»이다 — units/<stage>/<stage>.yaml 의 unit.inputs 와 글자 그대로 같아야 한다
+ *    (flattenGraphUnits 가 호출 노드의 contract 와 unit.inputs 를 «길이·원소» 둘 다로 대조한다). */
+export const NODE_CONTEXT_INPUTS = ['goal', 'context', 'feedback', 'budget', 'checkpoint'] as const;
+
+/** 등록 부품의 이름 — 요구가 이름으로 든 다섯 단계(구현·gate·리뷰·git·착지). */
+export type ImplementStageUnitId = 'implement' | 'gate' | 'review' | 'git' | 'landing';
+
+export interface ImplementStageUnitExit {
+  /** unit.exits 의 이름 — flattenGraphUnits 가 호출 간선 map 의 키와 «정확히» 대조한다. */
+  readonly exit: string;
+  /** 그 출구가 향하는 «파이프라인 노드» — PIPELINE_EDGES_BY_NODE 의 목적지에서만 고른다. */
+  readonly to: string;
+}
+
+export interface ImplementStageUnitSeam {
+  readonly stage: ImplementStageUnitId;
+  /** `id@version` — createGraphUnitResolver 규약 그대로. */
+  readonly call: string;
+  /** 그 부품이 소유한 파이프라인 노드(PIPELINE_EDGES_BY_NODE 의 키). */
+  readonly nodes: readonly string[];
+  /** 이 부품에서 처음 밟는 노드(= 호출 노드의 call_entry). */
+  readonly entry: string;
+  /** 합성 호출되는 단계만 계약을 갖는다; landing은 종결 노드라 호출 계약이 없다. */
+  readonly outputs?: readonly string[];
+  readonly exits?: readonly ImplementStageUnitExit[];
+}
+
+/** ⛔ 출처는 «둘»이다 — kind 는 IMPLEMENT_LOOP, edges 는 PIPELINE_EDGES_BY_NODE. 여기서 새 어휘를 만들지 않는다.
+ *
+ *  📌 착지(landing) 부품은 합성 그래프에서 «평범한 merge 노드»로 남는다: flattenGraphUnits 는 호출 노드마다
+ *    나가는 outcome map 을 요구하는데 종결 노드(merge)에는 나가는 간선이 없다 — 즉 «종결 노드는 호출일 수 없다».
+ *    그래서 landing 은 등록·해석·단독 평탄화(계약 검증)로 생산 경로를 지나고, 합성 그래프의 종결은 merge 가 맡는다. */
+export const IMPLEMENT_STAGE_UNITS: readonly ImplementStageUnitSeam[] = [
+  { stage: 'implement', call: 'implement@1', nodes: ['implement'], entry: 'implement',
+    outputs: ['diff', 'evidence', 'result'],
+    exits: [{ exit: 'done', to: 'gate' }, { exit: 'rework', to: 'gate' }, { exit: 'failed', to: 'gate' }] },
+  { stage: 'gate', call: 'gate@1', nodes: ['gate'], entry: 'gate',
+    outputs: ['gate-verdict', 'evidence'],
+    exits: [{ exit: 'pass', to: 'review' }, { exit: 'fail', to: 'rework' },
+      { exit: 'sync', to: 'main-sync' }, { exit: 'open', to: 'open-pr' }] },
+  { stage: 'review', call: 'review@1', nodes: ['review'], entry: 'review',
+    outputs: ['verdict', 'must-fix', 'evidence'],
+    exits: [{ exit: 'pass', to: 'main-sync' }, { exit: 'fail', to: 'rework' },
+      { exit: 'sync', to: 'main-sync' }, { exit: 'open', to: 'open-pr' }] },
+  { stage: 'git', call: 'git@1', nodes: ['main-sync', 'open-pr'], entry: 'main-sync',
+    outputs: ['commit', 'pr-number', 'evidence'],
+    exits: [{ exit: 'to-regate', to: 'regate' }, { exit: 'to-open-pr', to: 'open-pr' },
+      { exit: 'to-merge', to: 'merge' }] },
+  { stage: 'landing', call: 'landing@1', nodes: ['merge'], entry: 'merge',
+    // 합성 그래프의 merge는 종결 노드라 landing 부품의 종료 매핑을 만들지 않는다.
+  },
+];
+
+/** 그 그래프가 «부품으로 떼어 놓은» 단계 목록 — self-implement 밖의 그래프는 빈 배열(동작 불변). */
+export function stageUnitSeamsForGraph(graphId: string): readonly ImplementStageUnitSeam[] {
+  return graphId === PIPELINE_GRAPH_ID ? IMPLEMENT_STAGE_UNITS : [];
+}
+
+/** 파이프라인 노드의 kind — IMPLEMENT_LOOP 과 «같은 출처»에서 읽는다(두 벌로 갈리지 않게). */
+export function pipelineNodeKind(nodeId: string): string | undefined {
+  return IMPLEMENT_LOOP.nodes.find((node) => node.nodeId === nodeId)?.kind;
+}
+
+const UNIT_CALL_CONTRACT = (outputs: readonly string[]): GraphNodeContract => ({
+  inputs: [...NODE_CONTEXT_INPUTS],
+  tools: 'none',
+  outputs: [...outputs],
+});
+
+/** ⭐ 부품 호출로 «재조립한» self-implement 선언 — 실행 그래프가 아니라 «정적 검증용 합성»이다.
+ *
+ *  ⛔ 실행 그래프(graphs/implement-loop.yaml)는 건드리지 않는다(보존 계약: 도는 동작 불변).
+ *    이 spec 은 flattenGraphUnits 의 정적 검증(entry/exit 매핑·inputs/outputs 계약·이름 충돌·순환/깊이≤3)을
+ *    «실제 등록 부품»에 걸어, 부품 분해가 기존 kind+edges 를 그대로 재현함을 값으로 낸다. */
+export function implementLoopUnitSpec(): GraphTemplateSpec {
+  const call = (seam: ImplementStageUnitSeam, callEntry?: string): GraphNodeSpec => ({
+    nodeId: callEntry ?? seam.entry,
+    kind: 'subgraph',
+    recipe: 'none',
+    maxVisits: 1,
+    call: seam.call,
+    ...(callEntry === undefined ? {} : { callEntry }),
+    contract: UNIT_CALL_CONTRACT(seam.outputs ?? []),
+  });
+  const seamOf = (stage: ImplementStageUnitId): ImplementStageUnitSeam =>
+    IMPLEMENT_STAGE_UNITS.find((seam) => seam.stage === stage)!;
+  const outcome = (stage: ImplementStageUnitId, from: string): GraphEdgeSpec => ({
+    from,
+    on: 'outcome',
+    map: Object.fromEntries((seamOf(stage).exits ?? []).map(({ exit, to }) => [exit, to])),
+  });
+  const nodes: GraphNodeSpec[] = [
+    call(seamOf('implement')),
+    call(seamOf('gate')),
+    call(seamOf('review')),
+    call(seamOf('git'), 'main-sync'),
+    call(seamOf('git'), 'open-pr'),
+    { nodeId: 'rework', kind: pipelineNodeKind('rework')!, recipe: 'none', maxVisits: 6 },
+    { nodeId: 'regate', kind: pipelineNodeKind('regate')!, recipe: 'none', maxVisits: 2 },
+    { nodeId: 'merge', kind: pipelineNodeKind('merge')!, recipe: 'none', maxVisits: 1 },
+  ];
+  const edges: GraphEdgeSpec[] = [
+    outcome('implement', 'implement'),
+    outcome('gate', 'gate'),
+    outcome('review', 'review'),
+    outcome('git', 'main-sync'),
+    outcome('git', 'open-pr'),
+    { from: 'rework', to: 'implement' },
+    { from: 'regate', to: 'open-pr' },
+  ];
+  return {
+    graphId: PIPELINE_GRAPH_ID,
+    version: 1,
+    entryNode: 'implement',
+    terminalNodes: ['merge'],
+    nodes,
+    edges,
+  };
+}
+
+export interface ImplementLoopUnitEquivalence {
+  /** 파이프라인 노드마다 «합성 그래프의 kind» 가 IMPLEMENT_LOOP 과 다른 것. */
+  readonly kindMismatches: readonly { node: string; expected: string; actual: string | undefined }[];
+  /** PIPELINE_EDGES_BY_NODE 에 있는데 평탄화 결과에 «없는» 간선. */
+  readonly missingEdges: readonly string[];
+  /** 평탄화 결과에 있는데 PIPELINE_EDGES_BY_NODE 에 «없는» 간선 — 0 이어야 동작 불변이다. */
+  readonly extraEdges: readonly string[];
+}
+
+/** flattenGraphUnits 는 호출 노드의 자식을 `${callNodeId}__${nodeId}` 로 접두한다 — 그 접두를 벗겨 되돌린다. */
+export function normalizeFlattenedNodeId(nodeId: string): string {
+  const at = nodeId.lastIndexOf('__');
+  return at < 0 ? nodeId : nodeId.slice(at + 2);
+}
+
+/** ⭐ 판정선: 평탄화 결과가 기존 kind+edges 와 «같은가»를 세 방향으로 낸다. */
+export function implementLoopUnitEquivalence(flattened: GraphTemplateSpec): ImplementLoopUnitEquivalence {
+  const kindMismatches: { node: string; expected: string; actual: string | undefined }[] = [];
+  const actualKinds = new Map<string, string>();
+  for (const node of flattened.nodes) actualKinds.set(normalizeFlattenedNodeId(node.nodeId), node.kind);
+  for (const nodeId of Object.keys(PIPELINE_EDGES_BY_NODE)) {
+    const expected = pipelineNodeKind(nodeId);
+    const actual = actualKinds.get(nodeId);
+    if (expected !== undefined && actual !== expected) kindMismatches.push({ node: nodeId, expected, actual });
+  }
+  const edgesOf = (map: Readonly<Record<string, readonly string[]>>): Set<string> =>
+    new Set(Object.entries(map).flatMap(([from, targets]) => targets.map((to) => `${from}->${to}`)));
+  const normalizedFlattened = Object.fromEntries(
+    Object.entries(edgeMapOf(flattened)).map(([from, targets]) => [normalizeFlattenedNodeId(from), targets.map(normalizeFlattenedNodeId)]),
+  );
+  const actual = edgesOf(normalizedFlattened);
+  const expected = edgesOf(PIPELINE_EDGES_BY_NODE as unknown as Record<string, readonly string[]>);
+  return {
+    kindMismatches,
+    missingEdges: [...expected].filter((edge) => !actual.has(edge)).sort(),
+    extraEdges: [...actual].filter((edge) => !expected.has(edge)).sort(),
+  };
+}
+
 /** ⭐⭐ RFC §5 «배선» — 선언의 «출처»가 YAML 이다(대표 지시: TypeScript 는 저장에서 빠진다).
  *
  *  ⛔ 이 상수들(IMPLEMENT_LOOP·RESEARCH_LOOP)은 «폴백»이다 — YAML 을 못 읽었을 때만 쓴다.