elanous 0.2.40 → 0.2.42

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) {

package/src/self-implement/headless-elanous-driver.ts

@@ -87,14 +87,14 @@ import type { ChannelBus } from '../terminal-matrix/channel-bus.js';
 import { federationObservation } from './orchestrator.js';
 // ⛔ 배달 상태는 「정하는 쪽」(orchestrator)이 소유한다 — 여기는 받아서 찍기만 한다.
 import type { SupervisorDeliveryLine, SupervisorDeliveryState } from './orchestrator.js';
-import type { RunShardIdentity } from './run-ledger.js';
+import { runLedgerDir, type RunShardIdentity } from './run-ledger.js';
+import { readRunChart, recordRunChartDecision, recordRunChartWaitHandoff, RUN_DOCTOR_HANDOFF_WAIT_THRESHOLD, RUN_DOCTOR_HANDOFF_INPUT_PREFIX } from './run-chart.js';
 
 const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
 
 // Boundary requests observed up to about 788 characters; preserve the complete request record.
 const HARNESS_BOUNDARY_REQUEST_STRING_MAX = 1024;
 const WAIT_SUPERVISION_PROGRESS_BATCH_SIZE = 5;
-
 /** Renders untrusted boundary metadata as one inert terminal line for the parent surface. */
 export function singleLineBoundarySurfaceValue(value: string): string {
   return value
@@ -1267,6 +1267,9 @@ export async function runHeadlessGoalLoopPty(opts: HeadlessGoalLoopPtyOptions):
   let sameCommandStallCount = 0;
   let pendingWaitSupervisionCount = 0;
   let pendingWaitLatestJudgment: string | undefined;
+  let consecutiveWaitDecisionCount = 0;
+  let waitStreakHandoffSent = false;
+  let waitStreakIndex = 0;
   // Repetition identity is exact full instruction-text equality after the existing delivery trim;
   // the first occurrence omits the surface marker, and later occurrences are only annotated.
   const inputInstructionOccurrences = new Map<string, number>();
@@ -1699,6 +1702,8 @@ export async function runHeadlessGoalLoopPty(opts: HeadlessGoalLoopPtyOptions):
                 descriptor: { controlStance: stance },
               });
               previousIntervention = intervention;
+              const chartDir = runLedgerDir(opts.stateDir);
+              const chartBeforeJudgment = readRunChart(runId, 'run-supervisor', chartDir);
               const controlObs: ControlObservation = {
                   screen: rendered,
                   state: curState,
@@ -1708,6 +1713,8 @@ export async function runHeadlessGoalLoopPty(opts: HeadlessGoalLoopPtyOptions):
                   sameScreenMs: Math.max(0, nowMs - frameObs.screenSinceMs),
                   stallRung: frameObs.stallRung,
                   ...(roundContext ? { roundContext } : {}),
+                  runId,
+                  runChart: chartBeforeJudgment,
                 };
                 const controller = new AbortController();
                 let rejectParentAbort: ((reason: Error) => void) | undefined;
@@ -1821,11 +1828,14 @@ export async function runHeadlessGoalLoopPty(opts: HeadlessGoalLoopPtyOptions):
                   debug.log('self-implement', 'brain.suggestion', supervisionVerdictPayload);
                   debug.log('self-implement', 'run-supervision.verdict', supervisionVerdictPayload);
                   if (decision.action === 'wait') {
+                    consecutiveWaitDecisionCount += 1;
                     pendingWaitSupervisionCount += 1;
                     pendingWaitLatestJudgment = decision.action;
                     if (pendingWaitSupervisionCount >= WAIT_SUPERVISION_PROGRESS_BATCH_SIZE) flushWaitSupervisionProgress();
                   } else {
                     flushWaitSupervisionProgress();
+                    consecutiveWaitDecisionCount = 0;
+                    waitStreakHandoffSent = false;
                     const input = decision.action === 'input' ? decision.text.trim() : '';
                     const inputInstructionOccurrence = input ? countInputInstructionOccurrence(input) : undefined;
                     const delivery = input ? (opts.onSupervisorInput ? 'queued' : 'not-delivered') : undefined;
@@ -1858,6 +1868,25 @@ export async function runHeadlessGoalLoopPty(opts: HeadlessGoalLoopPtyOptions):
                       }), 'supervision');
                     });
                   }
+                  const handoffNow = decision.action === 'wait'
+                    && consecutiveWaitDecisionCount >= RUN_DOCTOR_HANDOFF_WAIT_THRESHOLD && !waitStreakHandoffSent;
+                  const chartStopKey = handoffNow ? `${runId}:wait-streak:${waitStreakIndex + 1}` : `${runId}:supervisor:${i}`;
+                  const chartWrite = handoffNow
+                    ? recordRunChartWaitHandoff({ runId, stopKey: chartStopKey, waitCount: consecutiveWaitDecisionCount,
+                      readStopKeys: chartBeforeJudgment.map((cell) => cell.stopKey), dir: chartDir })
+                    : recordRunChartDecision({ runId, device: 'run-supervisor', stopKey: chartStopKey,
+                      observed: `${curState}; stallRung=${st?.rung ?? NO_STALL}`, verdict: decision.action,
+                      action: decision.action === 'input' ? decision.text.slice(0, 120) : decision.action,
+                      handoff: decision.action === 'no-progress' ? 'macrophage' : null,
+                      why: decision.action === 'no-progress' ? decision.reason : `supervisor ${decision.action}`,
+                      readStopKeys: chartBeforeJudgment.map((cell) => cell.stopKey), dir: chartDir });
+                  if (handoffNow && (chartWrite === 'recorded' || chartWrite === 'already-recorded')) {
+                    waitStreakHandoffSent = true; waitStreakIndex += 1;
+                    debug.log('run-supervisor', 'doctor-handoff', { runId, stopKey: chartStopKey, waitCount: consecutiveWaitDecisionCount, handoff: 'doctor' });
+                    opts.onSupervisorInput?.(`${RUN_DOCTOR_HANDOFF_INPUT_PREFIX} runId=${runId} stopKey=${chartStopKey} waitCount=${consecutiveWaitDecisionCount}`, (delivery, reason) => {
+                      try { debug.log('run-supervisor', 'doctor-handoff-delivery', { runId, stopKey: chartStopKey, delivery, ...(reason ? { reason } : {}) }); } catch { /* observation is fail-soft */ }
+                    });
+                  }
                   debug.log('self-implement', 'brain.input-outcome', {
                     ptyId: h.id, runId, step: i, axis: 'assist', action: decision.action,
                     applied: autoAssist.assist, why: autoAssist.why,