elanous 0.2.38 → 0.2.41

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

@@ -39,7 +39,7 @@ export function resolveGoalAuthorGrade(flag?: GoalAuthorGrade, configured?: unkn
 import type { ObserveOnlySource } from './observe-only.js';
 import type { Question } from '../ask-user-question/types.js';
 import { requestTestScenario as defaultRequestTestScenario, type TestScenarioRequestInput, type TestScenarioRequestResult } from './test-scenario-request.js';
-import { resolveGoalAuthorClarification, parseGoalDocumentClarifications, serializeGoalAuthorParent, type GoalAuthorClarificationResponse, type GoalAuthorParent, type GoalAuthorSelfResolution } from './goal-author-clarification.js';
+import { defaultGoalAuthorSelfResolve, resolveGoalAuthorClarification, parseGoalDocumentClarifications, serializeGoalAuthorParent, type GoalAuthorClarificationResponse, type GoalAuthorParent, type GoalAuthorSelfResolution } from './goal-author-clarification.js';
 import { acquireLockSync } from '../storage/file-lock.js';
 import { createRepositoryReferencedFileReader, type ReferencedFileReadResult } from './goal-file-reader.js';
 import { extractGoalDocSections, type GoalDocSourceLine } from './goal-doc/section.js';
@@ -57,8 +57,10 @@ 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';
 export { selectRelevantAuthoringLessons } from './knowhow-pack.js';
 export { formatSubmittedAt } from './goal-author-identity.js';
 import { hasUnmetRequirementOutsidePreservationClause } from './goal-author-preservation-obligation.js';
@@ -116,7 +118,7 @@ export interface GoalAuthorDeps {
   /** Optional externally decomposed plan steps rendered verbatim into the authored goal; the author never generates them. */
   steps?: readonly string[];
   /** Optional injected decomposition seam; omitted means authoring never invokes an LLM or decomposition. */
-  decomposeSteps?: (objective: string, opts?: { context?: string; runId?: string }) => Promise<readonly string[]>;
+  decomposeSteps?: (objective: string, opts?: { context?: string; runId?: string; goalId?: string }) => Promise<readonly string[]>;
   /** Optional launch preflight result supplied by the caller; authoring never reads the ledger or logs itself. */
   launchPreflight?: LaunchPreflightResult;
   /** Optional in-process notification for each authored-goal phase transition. */
@@ -384,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`);
   }
@@ -402,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';
@@ -2971,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']);
@@ -2998,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) ?? []) {
@@ -3014,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] }];
   });
 }
 
@@ -3094,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);
@@ -3108,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';
@@ -3145,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,
@@ -3152,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,
@@ -3907,6 +3980,8 @@ function renderClarification(
     `  - includeOther: ${question.includeOther !== false}`,
     `  - answer: ${answerValue}`,
     ...(provenance ? [`  - provenance.source: ${provenance.source}`] : []),
+    ...(provenance?.assumption ? [`  - provenance.assumption: ${renderClarificationValue(provenance.assumption)}`] : []),
+    ...(provenance?.assumptionSource ? [`  - provenance.assumption-source: ${provenance.assumptionSource}`] : []),
     ...(provenance?.evidence ?? []).map((evidence) => `  - evidence: ${renderClarificationValue(evidence)}`),
   ];
 }
@@ -6031,6 +6106,7 @@ async function authorGoalWithSupersededRootIntent(
     throw new Error('legacy parent document has no RootIntent; rootIntent is required');
   }
   const rootIntent = validateRootIntent(supersessionRootIntent ?? inheritedRootIntent ?? requestedRootIntent ?? goalSummary(enhancement.original));
+  const assignedGoalId = deps.goalId ?? generateGoalId();
   let resolvedSteps = deps.steps;
   if (resolvedSteps === undefined && goalType === 'implement' && deps.decomposeSteps) {
     const startedAt = Date.now();
@@ -6041,7 +6117,7 @@ async function authorGoalWithSupersededRootIntent(
         ? [device.exists ? `existing: ${device.device}` : `missing: ${device.device}`] : undefined;
       const context = [facts?.context, deviceInventory?.length ? `Device inventory (measured at goal-author repository root): ${deviceInventory.join(', ')}` : undefined]
         .filter(Boolean).join('\n') || undefined;
-      const decomposed = await deps.decomposeSteps(ask, { context, runId: process.env.ELANOUS_RUN_ID?.trim() || authorRunId });
+      const decomposed = await deps.decomposeSteps(ask, { context, runId: process.env.ELANOUS_RUN_ID?.trim() || authorRunId, goalId: assignedGoalId });
       if (decomposed.length > 0) resolvedSteps = decomposed;
     } catch {
       failed = true;
@@ -6270,7 +6346,6 @@ async function authorGoalWithSupersededRootIntent(
   //   ⚠️⭐ 계약 — 이 줄은 조립·린트가 «끝나기 전»에 난다(goalId 가 여기서 정해지므로 더 늦출 수 없다).
   //      ⇒ 저작이 그 «뒤»에 실패하면 이 조인 행만 남는다(dangling). 그러므로 ***집계는 「착지한 골」과의
   //      inner join 으로만 한다*** — 이 행 자체를 「골이 하나 생겼다」로 세면 «실패분까지» 센다(무인 리뷰 지적).
-  const assignedGoalId = deps.goalId ?? generateGoalId();
   const askFile = deps.askFile === undefined ? undefined : validateAskFile(deps.askFile);
   try { observeGoalAuthor('goal-author', 'goal-id-assigned', { authorRunId, goalId: assignedGoalId, superseded: Boolean(deps.goalId) }); }
   catch { /* 관측은 fail-soft */ }
@@ -6565,6 +6640,7 @@ export function defaultGoalAuthorDeps(cwd: string): GoalAuthorDeps {
     },
     readSourceFile: createRepositoryReferencedFileReader(cwd),
     runHelpProbe: (argv) => runDefaultHelpProbe(cwd, argv),
+    selfResolveClarification: defaultGoalAuthorSelfResolve,
   };
 }
 
@@ -6613,7 +6689,7 @@ export async function writeAuthoredGoal(
     repositoryRoot: deps.repositoryRoot ?? groundingRoot,
   };
   const mandatoryGoalContextEvidence = goalContextEvidence(cwd);
-  const authoringLessons = selectRelevantAuthoringLessons(cwd, ask);
+  const authoringLessons = selectRelevantAuthoringLessons(cwd, ask, elanousStateRoot());
   observeGoalAuthor('goal-author', 'authoring-lessons', {
     status: authoringLessons.status,
     invalidRows: authoringLessons.invalidRows,

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 을 못 읽었을 때만 쓴다.

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

@@ -31,10 +31,38 @@ export interface GraphVariantGoalAnalysis {
   readonly targetPathCount: number;
 }
 
+/** 한 런이 읽은 unit 선언의 원문 — 해시 근거를 만들 입력이며 결과에는 실리지 않는다. */
+export interface GraphVariantUnitDeclaration {
+  readonly path: string;
+  readonly content: string;
+}
+
+/** 선택된 unit 선언의 근거 — 경로와 내용 해시만. 본문은 로그·원장에 복제하지 않는다. */
+export interface GraphVariantUnitDeclarationEvidence {
+  readonly path: string;
+  readonly contentHash: string;
+}
+
 /** 최초 graph variant 선택 — id·선택 이유가 런 원장 옆 .graph.yaml 에 함께 저장되고 재조회된다. */
 export interface GraphVariantSelection {
   readonly variantId: string;
   readonly reason: string;
+  /** 선택된 unit 선언의 경로·내용 해시 — 선언이 없으면 키 자체가 없다(기존 두 키 계약 불변). */
+  readonly unitDeclarations?: readonly GraphVariantUnitDeclarationEvidence[];
+}
+
+/** unit 선언 본문의 sha256 — 내용 대신 이 값만 근거에 남긴다(goalContentHash 와 같은 해시-only 예비). */
+export function hashUnitDeclarationContent(content: string): string {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+/** 경로 오름차순·경로당 한 줄로 정렬한 근거 — 선언 순서가 달라도 같은 값을 낸다. */
+function unitDeclarationEvidence(unitDeclarations: readonly GraphVariantUnitDeclaration[]): GraphVariantUnitDeclarationEvidence[] {
+  const byPath = new Map<string, string>();
+  for (const declaration of [...unitDeclarations].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) {
+    byPath.set(declaration.path, hashUnitDeclarationContent(declaration.content));
+  }
+  return [...byPath].map(([path, contentHash]) => ({ path, contentHash }));
 }
 
 export type GraphVariantRejection =
@@ -55,14 +83,17 @@ export type GraphVariantResult =
   | { readonly ok: true; readonly overlay: GraphOverlaySpec; readonly template: GraphTemplateSpec; readonly patches: readonly OverlayPatchOp[]; readonly selection?: GraphVariantSelection }
   | { readonly ok: false; readonly rejections: readonly GraphVariantRejection[] };
 
-/** 최초 변형 선택(id·선택 이유)의 결정론적 유도 — 같은 종류·대상 경로 수면 항상 같은 값을 낸다. */
-export function initialGraphVariantSelection(analysis: GraphVariantGoalAnalysis): GraphVariantSelection {
+/** 최초 변형 선택(id·선택 이유 + 선택된 unit 선언의 경로·해시)의 결정론적 유도 — 같은 입력이면 항상 같은 값을 낸다. */
+export function initialGraphVariantSelection(analysis: GraphVariantGoalAnalysis,
+    unitDeclarations: readonly GraphVariantUnitDeclaration[] = []): GraphVariantSelection {
   const variantId = `variant-${analysis.goalType}-${createHash('sha256')
     .update(JSON.stringify({ goalType: analysis.goalType, targetPathCount: analysis.targetPathCount }))
     .digest('hex').slice(0, 12)}`;
+  const evidence = unitDeclarationEvidence(unitDeclarations);
   return {
     variantId,
     reason: `initial graph variant selected from goal type ${analysis.goalType} with ${analysis.targetPathCount} target path${analysis.targetPathCount === 1 ? '' : 's'}`,
+    ...(evidence.length === 0 ? {} : { unitDeclarations: evidence }),
   };
 }
 
@@ -72,8 +103,10 @@ export function createGraphVariant(input: {
   readonly goal: string;
   readonly plan: GraphVariantPlan;
   readonly goalAnalysis?: GraphVariantGoalAnalysis;
+  /** 이 런이 읽은 unit 선언 — 경로·내용 해시만 근거에 실리고 본문은 결과에 남지 않는다. */
+  readonly unitDeclarations?: readonly GraphVariantUnitDeclaration[];
 }): GraphVariantResult {
-  const { template, goal, plan, goalAnalysis } = input;
+  const { template, goal, plan, goalAnalysis, unitDeclarations = [] } = input;
   const known = new Set(template.nodes.map((node) => node.nodeId));
   const rejections: GraphVariantRejection[] = [];
   if (!/^g_[a-z0-9_-]+$/i.test(goal)) rejections.push({ kind: 'invalid-goal' });
@@ -82,7 +115,7 @@ export function createGraphVariant(input: {
     if (!GOAL_TYPES.includes(goalAnalysis.goalType) || !Number.isSafeInteger(goalAnalysis.targetPathCount) || goalAnalysis.targetPathCount < 0) {
       rejections.push({ kind: 'invalid-goal-analysis' });
     } else {
-      selection = initialGraphVariantSelection(goalAnalysis);
+      selection = initialGraphVariantSelection(goalAnalysis, unitDeclarations);
     }
   }
   if (plan.growth) {