elanous 0.2.0 → 0.2.5

package/src/self-implement/goal-run-store.ts

@@ -362,34 +362,52 @@ export class GoalRunStore {
     }
     if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
     this.db = new Database(path);
-    this.db.run('PRAGMA journal_mode = WAL');
-    this.db.run(`CREATE TABLE IF NOT EXISTS goal_run (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      run_id TEXT NOT NULL,
-      goal_id TEXT NOT NULL,
-      goal_file TEXT NOT NULL,
-      doc TEXT NOT NULL,
-      started_at TEXT GENERATED ALWAYS AS (json_extract(doc, '$.startedAt')) VIRTUAL,
-      outcome TEXT GENERATED ALWAYS AS (json_extract(doc, '$.outcome')) VIRTUAL,
-      rounds INTEGER GENERATED ALWAYS AS (json_extract(doc, '$.rounds')) VIRTUAL,
-      executor TEXT GENERATED ALWAYS AS (json_extract(doc, '$.model')) VIRTUAL
-    )`);
-    // RFC 런 출처 O5 — 기계별 집계를 인덱스로. 옛 DB 는 VIRTUAL 생성 열이라 ALTER 로 더할 수 있다(옛 행은 NULL).
-    const columns = this.db.query('PRAGMA table_xinfo(goal_run)').all() as Array<{ name: string }>;
-    if (!columns.some((c) => c.name === 'host_id')) {
-      this.db.run("ALTER TABLE goal_run ADD COLUMN host_id TEXT GENERATED ALWAYS AS (json_extract(doc, '$.hostId')) VIRTUAL");
+    this.db.run('PRAGMA busy_timeout = 5000');
+    const openedAt = Date.now();
+    try {
+      this.db.run('PRAGMA journal_mode = WAL');
+      this.db.run(`CREATE TABLE IF NOT EXISTS goal_run (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        run_id TEXT NOT NULL,
+        goal_id TEXT NOT NULL,
+        goal_file TEXT NOT NULL,
+        doc TEXT NOT NULL,
+        started_at TEXT GENERATED ALWAYS AS (json_extract(doc, '$.startedAt')) VIRTUAL,
+        outcome TEXT GENERATED ALWAYS AS (json_extract(doc, '$.outcome')) VIRTUAL,
+        rounds INTEGER GENERATED ALWAYS AS (json_extract(doc, '$.rounds')) VIRTUAL,
+        executor TEXT GENERATED ALWAYS AS (json_extract(doc, '$.model')) VIRTUAL
+      )`);
+      // RFC 런 출처 O5 — 기계별 집계를 인덱스로. 옛 DB 는 VIRTUAL 생성 열이라 ALTER 로 더할 수 있다(옛 행은 NULL).
+      const columns = this.db.query('PRAGMA table_xinfo(goal_run)').all() as Array<{ name: string }>;
+      if (!columns.some((c) => c.name === 'host_id')) {
+        this.db.run("ALTER TABLE goal_run ADD COLUMN host_id TEXT GENERATED ALWAYS AS (json_extract(doc, '$.hostId')) VIRTUAL");
+      }
+      this.db.run('CREATE INDEX IF NOT EXISTS goal_run_by_host ON goal_run(host_id, started_at)');
+      this.db.run('CREATE INDEX IF NOT EXISTS goal_run_by_goal ON goal_run(goal_id, started_at)');
+      this.db.run('CREATE INDEX IF NOT EXISTS goal_run_by_run ON goal_run(run_id)');
+      this.db.run('CREATE INDEX IF NOT EXISTS goal_run_by_file ON goal_run(goal_file)');
+    } catch (error) {
+      this.db.close();
+      if (/SQLITE_BUSY|SQLITE_LOCKED|database is locked|database is busy/i.test(String(error))) {
+        debug.log('store.sqlite', 'busy-lost', { store: 'goal_run', op: 'open', waitedMs: Date.now() - openedAt });
+      }
+      throw error;
     }
-    this.db.run('CREATE INDEX IF NOT EXISTS goal_run_by_host ON goal_run(host_id, started_at)');
-    this.db.run('CREATE INDEX IF NOT EXISTS goal_run_by_goal ON goal_run(goal_id, started_at)');
-    this.db.run('CREATE INDEX IF NOT EXISTS goal_run_by_run ON goal_run(run_id)');
-    this.db.run('CREATE INDEX IF NOT EXISTS goal_run_by_file ON goal_run(goal_file)');
   }
 
   insert(goalFile: string, record: GoalExecutionRecord, goalId?: string): void {
-    this.db.run(
-      'INSERT INTO goal_run (run_id, goal_id, goal_file, doc) VALUES (?, ?, ?, ?)',
-      [record.runId, goalId ?? goalIdFromDocument(goalFile), normalizeGoalFile(goalFile), serializeGoalExecutionRecord(withRecordOrigin(record))],
-    );
+    const startedAt = Date.now();
+    try {
+      this.db.run(
+        'INSERT INTO goal_run (run_id, goal_id, goal_file, doc) VALUES (?, ?, ?, ?)',
+        [record.runId, goalId ?? goalIdFromDocument(goalFile), normalizeGoalFile(goalFile), serializeGoalExecutionRecord(withRecordOrigin(record))],
+      );
+    } catch (error) {
+      if (/SQLITE_BUSY|SQLITE_LOCKED|database is locked|database is busy/i.test(String(error))) {
+        debug.log('store.sqlite', 'busy-lost', { store: 'goal_run', op: 'insert', waitedMs: Date.now() - startedAt });
+      }
+      throw error;
+    }
   }
 
   byRunId(runId: string): GoalRunRecord[] {

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

@@ -1,9 +1,8 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, normalize } from 'node:path/posix';
 import type { GoalType } from './goal-author.js';
-import { graphAuthoritativeConfigValue, type UserConfig } from '../user-config.js';
+import type { UserConfig } from '../user-config.js';
 import ts from 'typescript';
-import { resolveRunControl } from './run-controls.js';
 import {
   GRAPH_SPECS,
   GRAPH_TEMPLATES,
@@ -19,50 +18,37 @@ import { applyGraphOverlays, selectOverlays, type GraphOverlaySpec, type Overlay
 import type { OverlayPatch } from './graph-overlay.js';
 import type { GraphTemplateSpec } from './graph-yaml.js';
 
-/** ⭐ RFC §5 «1단계 승격» — 선언을 «실행 권위»로 올리는 스위치.
- *
- *  ⭐ **실행 기본은 user-config adapter에서 켜짐**이다. 명시로 끈 상태에서는 종전과
- *    «같은» 걸음이어야 한다 — 그것이 이 모듈의 첫째 반증이다.
- *
- *  ⛔ **「아무도 정하지 않았다」와 「명시로 켰다/껐다」를 가른다** — `source` 가 그 축이다.
- *    (`observeOnlySource` 의 선례를 그대로 따른다: 그것을 안 갈라서 측정이 한 번 무효가 됐다.) */
-export type GraphAuthoritySource = 'flag' | 'config' | 'default';
+/** 2026-09-26 설정 졸업 — 그래프 권위는 항상 켬. 관측 출처는 default로 고정한다. */
+export type GraphAuthoritySource = 'default';
 
 export interface GraphAuthority {
   readonly enabled: boolean;
   readonly source: GraphAuthoritySource;
 }
 
-/** 플래그 → config → 범용 run-control 기본 순으로 해석한다. 실행 기본은 user-config adapter가 공급한다. */
-export function resolveGraphAuthority(input: {
+/** 옛 호출자의 입력은 해석하지 않는다. 권위는 항상 켜져 있다. */
+export function resolveGraphAuthority(_input: {
   readonly flag?: boolean | undefined;
   readonly config?: boolean | undefined;
-}): GraphAuthority {
-  const resolved = resolveRunControl('graph', {
-    ...(input.flag === undefined ? {} : { flag: { graph: input.flag } }),
-    ...(input.config === undefined ? {} : { config: { graph: input.config } }),
-  });
-  return { enabled: resolved.value as boolean, source: resolved.source === 'prefix' ? 'flag' : resolved.source };
+} = {}): GraphAuthority {
+  return { enabled: true, source: 'default' };
 }
 
 export function resolveGraphAuthorityForUserConfig(
-  config: UserConfig,
-  flag?: boolean,
+  _config?: UserConfig,
+  _flag?: boolean,
 ): GraphAuthority {
-  const graphConfig = graphAuthoritativeConfigValue(config);
-  if (flag !== undefined) return resolveGraphAuthority({ flag, ...(graphConfig === undefined ? {} : { config: graphConfig }) });
-  if (graphConfig !== undefined) return resolveGraphAuthority({ config: graphConfig });
-  return { enabled: config.tools.selfImplement.graphAuthoritative, source: 'default' };
+  return { enabled: true, source: 'default' };
 }
 
-/** 이 런이 실제로 따를 템플릿. ⛔ 꺼져 있으면 «언제나» implement-loop 다(골 종류와 무관하게). */
+/** 이 런이 실제로 따를 템플릿. 기존 비권위 입력을 직접 주입한 호출은 구현 루프로 폴백한다. */
 export function activeTemplate(goalType: GoalType | undefined, authority: GraphAuthority): GraphTemplate {
   const implementLoop = GRAPH_TEMPLATES['self-implement'] as GraphTemplate;
   if (!authority.enabled) return implementLoop;
   return templateForGoalType(goalType) ?? implementLoop;
 }
 
-/** 앞단 관측의 구현 골 정체성. 권위 스위치 상태와 무관하게 implement의 활성 템플릿을 사용한다. */
+/** 앞단 관측의 구현 골 정체성. implement의 활성 템플릿을 사용한다. */
 export function activeImplementTemplate(): GraphTemplate {
   return activeTemplate('implement', resolveGraphAuthority({}));
 }
@@ -292,8 +278,7 @@ export function graphAuthorityFields(authority: GraphAuthority, template: GraphT
  *    목적지 목록으로 접어 버려서 패치 포인터가 가리킬 자리가 «없다».
  *  ⛔ **선택을 «전부» 낸다** — 얹힌 것만 내면 「왜 안 얹혔나」를 못 묻는다
  *    (`wrong-stage` · `does-not-apply` · `key-absent` · `unparseable` 이 서로 다른 처방이다).
- *  ⛔ **거절은 조용하지 않다** — 패치가 안 물면 `rejections` 로 나오고 «기준 선언»이 그대로 산다.
- *  ⛔ 승격이 꺼져 있으면 «변형도 없다» — 오늘과 같은 걸음이어야 한다(이 모듈의 첫째 반증). */
+ *  ⛔ **거절은 조용하지 않다** — 패치가 안 물면 `rejections` 로 나오고 «기준 선언»이 그대로 산다. */
 /** 오버레이 조건이 «읽을 수 있는» 상태 키. ⛔ 여기 없는 키는 원장에 값이 안 실린다.
  *  🔑 그래서 «떨어뜨리되 말은 한다» — 아래 `stateExtraKeys` 가 그 이름을 남긴다. */
 export const OVERLAY_STATE_KEYS = ['attempts', 'goal_id'] as const;

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

@@ -0,0 +1,48 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import type { GraphNodeKind, GraphTemplateSpec } from './graph-yaml.js';
+
+export interface NodeCatalogRole {
+  readonly kind: GraphNodeKind;
+  readonly outcomes: readonly string[];
+  readonly spawn: string;
+  readonly grain: string;
+  readonly effects: string;
+}
+
+export interface NodeCatalog {
+  readonly roles: Map<string, NodeCatalogRole>;
+  readonly kinds: string[];
+}
+
+/** Catalog location follows this repository's source, not the caller's working directory. */
+export function loadNodeCatalog(path = join(import.meta.dir, '../../graphs/catalog/catalog.yaml')): NodeCatalog {
+  const doc = parseYaml(readFileSync(path, 'utf8')) as {
+    kinds: { existing: string[]; proposed: Record<string, string> };
+    roles: Array<{ role: string; kind: GraphNodeKind; outcomes: string[]; spawn: string; grain: string; effects: string }>;
+  };
+  return {
+    roles: new Map(doc.roles.map(({ role, kind, outcomes, spawn, grain, effects }) =>
+      [role, { kind, outcomes, spawn, grain, effects }])),
+    kinds: [...doc.kinds.existing, ...Object.keys(doc.kinds.proposed)],
+  };
+}
+
+export interface RecipeCatalogIssue {
+  readonly nodeId: string;
+  readonly recipe: string;
+  readonly problem: 'unknown-role' | 'kind-mismatch';
+}
+
+/** Declaration-only inspection: existing recipes are reported, never rejected at execution time. */
+export function inspectRecipesAgainstCatalog(template: GraphTemplateSpec, catalog: NodeCatalog): RecipeCatalogIssue[] {
+  const issues: RecipeCatalogIssue[] = [];
+  for (const { nodeId, kind, recipe } of template.nodes) {
+    if (recipe === 'none' || recipe.startsWith('cmd:') || recipe.startsWith('approval:') || recipe.startsWith('wf:')) continue;
+    const role = catalog.roles.get(recipe);
+    if (!role) issues.push({ nodeId, recipe, problem: 'unknown-role' });
+    else if (kind !== role.kind) issues.push({ nodeId, recipe, problem: 'kind-mismatch' });
+  }
+  return issues;
+}

package/src/self-implement/graph-run-contract.ts

@@ -0,0 +1,127 @@
+/** ⭐ 런 계약 — 그래프가 «시작할 때 한 번» 정하고 모든 노드가 따르는 약속(대표 2026-09-26).
+ *
+ *  대표: «초반에 계약을 기술하면 안에 있는 그래프 노드들이 그 계약(원격)을 준수하는 구조».
+ *  🩸 그 전까지 그래프 선언에는 «실행 칸»을 적을 자리가 없었다(`graph-yaml.ts` 최상위 칸 여덟).
+ *    `--substrate pod` 는 CLI 갈래였고, Pod 안의 그래프는 자기가 Pod 인 줄 몰랐다 —
+ *    그래서 Pod 안에서 `completion: worktree-only` 로 끝나면 결과가 Pod 와 함께 사라질 수 있었다.
+ *
+ *  해석 순서(먼저 있는 것이 이긴다): 발사 인자 → 부모가 실어 준 계약(env) → 그래프 선언 → 기본(local).
+ *  ⛔ 계약은 런 안에서 «바뀌지 않는다» — 미래 노드를 바꾸는 것은 계약에서 «파생»된 오버레이다(RFC §4.3 ⑴).
+ */
+
+export type RunSubstrate = 'local' | 'pod';
+/** 허용 부작용(우주 RFC #20662 A3) — 발급 자격과 «짝»으로 검증된다(시크릿 콜렉션 뒤). */
+export type RunEffects = 'none' | 'draft-pr' | 'merge' | 'outbound';
+const EFFECTS: readonly RunEffects[] = ['none', 'draft-pr', 'merge', 'outbound'];
+export function isRunEffects(value: unknown): value is RunEffects {
+  return typeof value === 'string' && (EFFECTS as readonly string[]).includes(value);
+}
+export type RunContractSource = 'launch' | 'parent' | 'graph' | 'default';
+
+export interface RunContract {
+  readonly substrate: RunSubstrate;
+  readonly source: RunContractSource;
+  /** 주입 프로필 이름(우주 RFC #20662 A1) — 없으면 «선언 안 됨». */
+  readonly profile?: string;
+  readonly profileSource?: RunContractSource;
+  readonly effects?: RunEffects;
+  readonly effectsSource?: RunContractSource;
+}
+
+/** 그래프 YAML 의 `run_contract:` 칸(선택). */
+export interface GraphRunContractSpec {
+  readonly substrate?: RunSubstrate;
+  readonly profile?: string;
+  readonly effects?: RunEffects;
+}
+
+/** 부모가 자식(Pod)에게 계약을 싣는 환경 변수. */
+export const RUN_CONTRACT_ENV = 'ELANOUS_RUN_CONTRACT';
+/** 지금 프로세스가 «실제로» 어느 칸에서 도는가 — Pod 매니페스트가 단다. */
+export const ACTUAL_SUBSTRATE_ENV = 'ELANOUS_SUBSTRATE';
+
+export function isRunSubstrate(value: unknown): value is RunSubstrate {
+  return value === 'local' || value === 'pod';
+}
+
+const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
+
+export function parseGraphRunContract(raw: unknown): { spec?: GraphRunContractSpec; error?: string } {
+  if (raw === undefined) return {};
+  if (raw === null || typeof raw !== 'object') return { error: 'run_contract 는 맵이어야 한다' };
+  const r = raw as Record<string, unknown>;
+  if (r.substrate !== undefined && !isRunSubstrate(r.substrate)) return { error: `run_contract.substrate 는 local|pod (받은 값: ${JSON.stringify(r.substrate)})` };
+  if (r.profile !== undefined && (typeof r.profile !== 'string' || !PROFILE_NAME.test(r.profile))) return { error: `run_contract.profile 은 이름(영숫자·-·_) (받은 값: ${JSON.stringify(r.profile)})` };
+  if (r.effects !== undefined && !isRunEffects(r.effects)) return { error: `run_contract.effects 는 ${EFFECTS.join('|')} (받은 값: ${JSON.stringify(r.effects)})` };
+  return { spec: { ...(r.substrate !== undefined ? { substrate: r.substrate as RunSubstrate } : {}), ...(r.profile !== undefined ? { profile: r.profile as string } : {}), ...(r.effects !== undefined ? { effects: r.effects as RunEffects } : {}) } };
+}
+
+export function resolveRunContract(input: {
+  launch?: RunSubstrate;
+  launchProfile?: string;
+  launchEffects?: RunEffects;
+  graph?: GraphRunContractSpec;
+  env?: NodeJS.ProcessEnv;
+}): RunContract {
+  const carried = readCarriedContract(input.env ?? process.env);
+  // 칸마다 따로 푼다 — 발사 인자 → 부모가 실은 계약 → 그래프 선언 → 기본.
+  const pick = <T>(launch: T | undefined, parent: T | undefined, graph: T | undefined): { value?: T; source?: RunContractSource } =>
+    launch !== undefined ? { value: launch, source: 'launch' }
+      : parent !== undefined ? { value: parent, source: 'parent' }
+        : graph !== undefined ? { value: graph, source: 'graph' } : {};
+  const sub = pick(input.launch, carried?.substrate, input.graph?.substrate);
+  const profile = pick(input.launchProfile, carried?.profile, input.graph?.profile);
+  const effects = pick(input.launchEffects, carried?.effects, input.graph?.effects);
+  return {
+    substrate: sub.value ?? 'local', source: sub.source ?? 'default',
+    ...(profile.value !== undefined ? { profile: profile.value, profileSource: profile.source! } : {}),
+    ...(effects.value !== undefined ? { effects: effects.value, effectsSource: effects.source! } : {}),
+  };
+}
+
+function readCarriedContract(env: NodeJS.ProcessEnv): { substrate?: RunSubstrate; profile?: string; effects?: RunEffects } | null {
+  const raw = env[RUN_CONTRACT_ENV]?.trim();
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as { substrate?: unknown; profile?: unknown; effects?: unknown };
+    const out = {
+      ...(isRunSubstrate(parsed.substrate) ? { substrate: parsed.substrate } : {}),
+      ...(typeof parsed.profile === 'string' && PROFILE_NAME.test(parsed.profile) ? { profile: parsed.profile } : {}),
+      ...(isRunEffects(parsed.effects) ? { effects: parsed.effects } : {}),
+    };
+    return Object.keys(out).length > 0 ? out : null;
+  } catch { return null; }
+}
+
+/** 자식에게 실을 값 — 부모가 정한 계약을 그대로 넘긴다(자식이 다시 고르지 않는다). */
+export function carryRunContract(contract: Pick<RunContract, 'substrate'> & Partial<Pick<RunContract, 'profile' | 'effects'>>): string {
+  return JSON.stringify({ substrate: contract.substrate, ...(contract.profile ? { profile: contract.profile } : {}), ...(contract.effects ? { effects: contract.effects } : {}) });
+}
+
+export function actualSubstrate(env: NodeJS.ProcessEnv = process.env): RunSubstrate {
+  return env[ACTUAL_SUBSTRATE_ENV] === 'pod' ? 'pod' : 'local';
+}
+
+/** 노드 진입마다 싣는 대조 — 「이 걸음이 계약대로의 칸에서 났나」를 원장이 답하게 한다. */
+export function runContractAtNode(contract: RunContract, env: NodeJS.ProcessEnv = process.env): {
+  readonly contractSubstrate: RunSubstrate;
+  readonly actualSubstrate: RunSubstrate;
+  readonly contractHonored: boolean;
+  readonly profile?: string;
+  readonly effects?: RunEffects;
+  /** 발급 자격 ↔ effects 짝. ⛔ 시크릿 콜렉션(발급 원장)이 서기 전엔 잴 수 없다 — true 로 채우지 않는다. */
+  readonly effectsHonored: boolean | 'unmeasured';
+} {
+  const actual = actualSubstrate(env);
+  return {
+    contractSubstrate: contract.substrate, actualSubstrate: actual, contractHonored: actual === contract.substrate,
+    ...(contract.profile !== undefined ? { profile: contract.profile } : {}),
+    ...(contract.effects !== undefined ? { effects: contract.effects } : {}),
+    effectsHonored: 'unmeasured',
+  };
+}
+
+/** 계약에서 파생된 완료 하한 — Pod 는 끝나면 사라지므로 작업 트리로만 끝내면 결과가 없어진다. */
+export function completionFloorFor(contract: Pick<RunContract, 'substrate'>): 'pr' | null {
+  return contract.substrate === 'pod' ? 'pr' : null;
+}

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

@@ -4,7 +4,8 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
 import { GOAL_TYPES, type GoalType } from './goal-author.js';
-import { edgeMapOf, loadGraphTemplates, type GraphNodeContract, type GraphNodeSpec, type GraphTemplateSpec } from './graph-yaml.js';
+import type { GraphRunContractSpec } from './graph-run-contract.js';
+import { edgeMapOf, loadGraphTemplates, type GraphNodeContract, type GraphNodeKind, type GraphNodeSpec, type GraphTemplateSpec } from './graph-yaml.js';
 
 /** ⭐ RFC §5 «3단계» — 템플릿을 «데이터»로 둔다(RFC §4.1 어휘).
  *
@@ -13,14 +14,17 @@ import { edgeMapOf, loadGraphTemplates, type GraphNodeContract, type GraphNodeSp
  *  이 선언은 한때 그림자였으나, 승격 게이트 넷이 2026-09-08에 모두 서서 대표 승인으로 승격했다.
  *  정정 이력과 게이트 근거는 `내부 문서 `RFC-graph-engineering-for-the-harness-2026-09-07``를 따른다.
  *
- *  ⛔ `kind` 어휘는 «늘리지 않는다»(RFC §7). 늘어도 되는 것은 `node_id` 다(§4.2a). */
-export type GraphNodeKind = 'agent' | 'gate' | 'git' | 'judge';
+ *  ⛔ RFC §7 의 kind 어휘 제한은 2026-09-26 지시로 열렸다. 정의는 graph-yaml.ts 한 곳이다. */
+export type { GraphNodeKind } from './graph-yaml.js';
 
 export interface GraphTemplateNode {
   readonly nodeId: string;
-  readonly kind: GraphNodeKind;
+  // 플러그인 kind(`<plugin>:<kind>`)가 들어오므로 스펙과 같은 넓은 형(P-T1 #21684) — 좁은 union 이면 PWA(Next) 타입 검사가 빌드를 막는다.
+  readonly kind: GraphNodeSpec['kind'];
   /** 그 노드의 재방문 상한. ⛔ 지금의 rework 상한이 «여기로 올라올» 자리다(RFC §4.1). */
   readonly maxVisits: number;
+  /** YAML recipe identifier; existing orchestrator does not execute it. */
+  readonly recipe?: string;
   /** YAML이 선언한 선택 계약. 관측용이며 실행 권한을 강제하지 않는다. */
   readonly contract?: GraphNodeContract;
 }
@@ -32,6 +36,8 @@ export interface GraphTemplate {
   readonly terminalNodes: readonly string[];
   /** YAML 템플릿이 선언한 문서 전용 변경의 gate 건너뛰기 정책. */
   readonly docsOnlyGateSkip?: boolean;
+  /** 선언된 런 계약(선택) — 런 시작 때 발사 인자·부모 계약과 함께 한 번 해석된다. */
+  readonly runContract?: GraphRunContractSpec;
   readonly nodes: readonly GraphTemplateNode[];
   readonly edges: Readonly<Record<string, readonly string[]>>;
 }
@@ -98,7 +104,7 @@ export function defaultGraphsDir(): string {
   return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'graphs');
 }
 
-export type DiscardedGraphNodeField = Exclude<keyof GraphNodeSpec, 'nodeId' | 'kind' | 'maxVisits' | 'contract'>;
+export type DiscardedGraphNodeField = Exclude<keyof GraphNodeSpec, 'nodeId' | 'kind' | 'maxVisits' | 'recipe' | 'contract'>;
 
 export interface GraphTemplateCompilation {
   readonly template: GraphTemplate;
@@ -109,7 +115,6 @@ export interface GraphTemplateCompilation {
 }
 
 const DISCARDED_NODE_FIELDS: readonly DiscardedGraphNodeField[] = [
-  'recipe',
   'progress',
   'phases',
   'terminalStages',
@@ -125,10 +130,12 @@ export function compileGraphTemplate(spec: GraphTemplateSpec): GraphTemplateComp
       entryNode: spec.entryNode,
       terminalNodes: spec.terminalNodes,
       ...(spec.docsOnlyGateSkip !== undefined ? { docsOnlyGateSkip: spec.docsOnlyGateSkip } : {}),
+      ...(spec.runContract !== undefined ? { runContract: spec.runContract } : {}),
       nodes: spec.nodes.map((n) => ({
         nodeId: n.nodeId,
-        kind: n.kind as GraphNodeKind,
+        kind: n.kind,
         maxVisits: n.maxVisits,
+        ...(n.recipe === undefined ? {} : { recipe: n.recipe }),
         ...(n.contract === undefined ? {} : { contract: n.contract }),
       })),
       edges: edgeMapOf(spec),

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

@@ -1,7 +1,9 @@
+import { parseGraphRunContract, type GraphRunContractSpec } from './graph-run-contract.js';
 import { createHash } from 'node:crypto';
 import { readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import { HARNESS_CORE_KINDS, hasNodeKind } from '../graph-kinds/registry.js';
 
 /** ⭐ RFC-graph-templates-as-yaml §5 «0단계» — YAML 저작본을 읽어 실행·해시·원장용 정규형으로.
  *
@@ -9,7 +11,7 @@ import { parse as parseYaml } from 'yaml';
  *    (`playground-scenario/yaml-parser.ts` 의 계약을 따른다 · 재발명 0).
  *  ⛔⭐ **뿌리를 «인자»로 받는다** — `import.meta.url` 로 코드 트리에 묶지 않는다.
  *    🩸 §4.6 이 지목한 병: `mission-capabilities/registry.ts` 가 그 방식이라 `--root` 격리가 불가능하다. */
-export type GraphNodeKind = 'agent' | 'gate' | 'git' | 'judge';
+export type GraphNodeKind = typeof HARNESS_CORE_KINDS[number];
 
 export interface GraphNodeContract {
   readonly inputs: readonly string[];
@@ -19,7 +21,7 @@ export interface GraphNodeContract {
 
 export interface GraphNodeSpec {
   readonly nodeId: string;
-  readonly kind: GraphNodeKind;
+  readonly kind: GraphNodeKind | (string & {});
   readonly recipe: string;
   readonly maxVisits: number;
   readonly progress?: readonly string[];
@@ -43,6 +45,7 @@ export interface GraphEdgeSpec {
 }
 
 export interface GraphTemplateSpec {
+  readonly loop?: { readonly title?: string; readonly description?: string; readonly trigger?: { readonly cron?: string; readonly events?: readonly string[] } };
   readonly graphId: string;
   readonly version: number;
   readonly entryNode: string;
@@ -50,6 +53,8 @@ export interface GraphTemplateSpec {
   /** 문서 전용 변경이면 gate 노드를 건너뛸 수 있다는 템플릿 정책. */
   readonly docsOnlyGateSkip?: boolean;
   readonly state?: readonly string[];
+  /** ⭐ 런 계약(선택) — 이 그래프가 «기본으로» 요구하는 실행 칸 등. 발사 인자가 덮는다(graph-run-contract.ts). */
+  readonly runContract?: GraphRunContractSpec;
   readonly nodes: readonly GraphNodeSpec[];
   readonly edges: readonly GraphEdgeSpec[];
 }
@@ -65,7 +70,6 @@ export interface GraphParseResult {
   readonly warnings: readonly GraphParseIssue[];
 }
 
-const KINDS = new Set<GraphNodeKind>(['agent', 'gate', 'git', 'judge']);
 /** ⚠️ YAML 함정 — `no`/`off`/`yes`/`on` 이 boolean 으로 파싱된다(Norway 문제). 노드 이름에 쓰면 조용히 깨진다. */
 const YAML_TRAP_WORDS = new Set(['true', 'false', 'yes', 'no', 'on', 'off', 'null', '~']);
 
@@ -111,8 +115,8 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
     }
     if (YAML_TRAP_WORDS.has(nodeId.toLowerCase())) warnings.push({ path: `${at}/node_id`, message: `'${nodeId}' 는 YAML 이 다른 값으로 읽을 수 있는 낱말이다` });
     const kind = n.kind;
-    if (typeof kind !== 'string' || !KINDS.has(kind as GraphNodeKind)) {
-      errors.push({ path: `${at}/kind`, message: `kind 는 ${[...KINDS].join('|')} 중 하나여야 한다 (받은 값: ${JSON.stringify(kind)})` });
+    if (typeof kind !== 'string' || !hasNodeKind('harness', kind)) {
+      errors.push({ path: `${at}/kind`, message: `kind 는 ${HARNESS_CORE_KINDS.join('|')} 또는 등록된 플러그인 종류여야 한다 (받은 값: ${JSON.stringify(kind)})` });
       continue;
     }
     const recipe = n.recipe;
@@ -135,7 +139,7 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
     else if (contract.tools === '') warnings.push({ path: `${at}/contract/tools`, message: 'tools 가 비었다' });
 
     nodes.push({
-      nodeId, kind: kind as GraphNodeKind, recipe, maxVisits,
+      nodeId, kind, recipe, maxVisits,
       ...(Array.isArray(n.progress) ? { progress: n.progress.filter((v): v is string => typeof v === 'string') } : {}),
       ...(Array.isArray(n.phases) ? { phases: n.phases.filter((v): v is string => typeof v === 'string') } : {}),
       ...(Array.isArray(n.terminal_stages) ? { terminalStages: n.terminal_stages.filter((v): v is string => typeof v === 'string') } : {}),
@@ -194,12 +198,37 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
   if (entryNode !== undefined && !known.has(entryNode)) errors.push({ path: `${label}/entry_node`, message: `'${entryNode}' 는 선언된 노드가 아니다` });
   for (const t of terminalNodes) if (!known.has(t)) errors.push({ path: `${label}/terminal_nodes`, message: `'${t}' 는 선언된 노드가 아니다` });
 
+  const runContract = parseGraphRunContract(doc.run_contract);
+  if (runContract.error) errors.push({ path: `${label}/run_contract`, message: runContract.error });
+  let loop: GraphTemplateSpec['loop'];
+  if (doc.loop !== undefined) {
+    const l = doc.loop;
+    if (!l || typeof l !== 'object' || Array.isArray(l)) errors.push({ path: `${label}/loop`, message: 'loop 는 맵이어야 한다' });
+    else {
+      const obj = l as Record<string, unknown>;
+      const t = obj.trigger;
+      if (obj.title !== undefined && typeof obj.title !== 'string') errors.push({ path: `${label}/loop/title`, message: 'title 은 문자열이어야 한다' });
+      if (obj.description !== undefined && typeof obj.description !== 'string') errors.push({ path: `${label}/loop/description`, message: 'description 은 문자열이어야 한다' });
+      if (t !== undefined && (!t || typeof t !== 'object' || Array.isArray(t))) errors.push({ path: `${label}/loop/trigger`, message: 'trigger 는 맵이어야 한다' });
+      const trigger = t && typeof t === 'object' && !Array.isArray(t) ? t as Record<string, unknown> : null;
+      if (trigger?.cron !== undefined && typeof trigger.cron !== 'string') errors.push({ path: `${label}/loop/trigger/cron`, message: 'cron 은 문자열이어야 한다' });
+      if (trigger?.events !== undefined && (!Array.isArray(trigger.events) || !trigger.events.every(e => typeof e === 'string'))) errors.push({ path: `${label}/loop/trigger/events`, message: 'events 는 문자열 배열이어야 한다' });
+      loop = {
+        ...(typeof obj.title === 'string' ? { title: obj.title } : {}),
+        ...(typeof obj.description === 'string' ? { description: obj.description } : {}),
+        ...(trigger ? { trigger: { ...(typeof trigger.cron === 'string' ? { cron: trigger.cron } : {}),
+          ...(Array.isArray(trigger.events) ? { events: trigger.events as string[] } : {}) } } : {}),
+      };
+    }
+  }
   if (errors.length > 0) return { errors, warnings };
   return {
     template: {
       graphId: graphId!, version: version!, entryNode: entryNode!, terminalNodes, nodes, edges,
+      ...(loop ? { loop } : {}),
       ...(typeof doc.docs_only_gate_skip === 'boolean' ? { docsOnlyGateSkip: doc.docs_only_gate_skip } : {}),
       ...(Array.isArray(doc.state) ? { state: doc.state.filter((v): v is string => typeof v === 'string') } : {}),
+      ...(runContract.spec ? { runContract: runContract.spec } : {}),
     },
     errors, warnings,
   };

package/src/self-implement/harness-policy-gates.ts

@@ -0,0 +1,42 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { runIsolationHardcodeGate } from '../../scripts/ci-isolation-hardcode-gate.js';
+import { runMockModuleRestoreGate } from '../../scripts/ci-mock-module-restore-gate.js';
+import { runModelHardcodeGate } from '../../scripts/ci-model-hardcode-gate.js';
+import { runDaemonPortGate } from '../../scripts/ci-daemon-port-gate.js';
+
+type GateName = 'isolation-gate' | 'mock-module-restore-gate' | 'model-hardcode-gate' | 'daemon-port-gate';
+type GateOutput = { args: string[]; cwd: string; log: (line: string) => void; error: (line: string) => void };
+type GateRunner = (out: GateOutput) => number;
+
+export function runHarnessPolicyGates(input: {
+  cwd: string;
+  changedFiles: readonly string[];
+  gates?: Partial<Record<GateName, GateRunner>>;
+}): { passed: boolean; failures: Array<{ gate: GateName; lines: string[] }>; skipped?: string } {
+  try {
+    if (!statSync(join(input.cwd, 'scripts')).isDirectory()) {
+      return { passed: true, failures: [], skipped: 'no-scripts' };
+    }
+  } catch {
+    return { passed: true, failures: [], skipped: 'no-scripts' };
+  }
+
+  const runners: readonly [GateName, GateRunner][] = [
+    ['isolation-gate', input.gates?.['isolation-gate'] ?? runIsolationHardcodeGate],
+    ['mock-module-restore-gate', input.gates?.['mock-module-restore-gate'] ?? runMockModuleRestoreGate],
+    ['model-hardcode-gate', input.gates?.['model-hardcode-gate'] ?? runModelHardcodeGate],
+    ['daemon-port-gate', input.gates?.['daemon-port-gate'] ?? ((out) => runDaemonPortGate({ log: out.log, error: out.error, cwd: out.cwd, args: [] }))],
+  ];
+  const failures: Array<{ gate: GateName; lines: string[] }> = [];
+  for (const [gate, run] of runners) {
+    const lines: string[] = [];
+    try {
+      const status = run({ cwd: input.cwd, args: ['--changed-files', ...input.changedFiles], log: (line) => lines.push(line), error: (line) => lines.push(line) });
+      if (status !== 0) failures.push({ gate, lines: [...lines, `✗ ${gate}: violation detected`] });
+    } catch (error) {
+      failures.push({ gate, lines: [...lines, `⚠ ${gate}: 게이트가 «못 쟀다» — ${error instanceof Error ? error.message : String(error)}`] });
+    }
+  }
+  return { passed: failures.length === 0, failures };
+}