elanous 0.2.32 → 0.2.34

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

@@ -4,6 +4,7 @@ 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';
+import { parseOverlayCondition } from './graph-overlay-condition.js';
 
 /** ⭐ RFC-graph-templates-as-yaml §5 «0단계» — YAML 저작본을 읽어 실행·해시·원장용 정규형으로.
  *
@@ -36,6 +37,8 @@ export interface GraphNodeSpec {
   /** Entry selected by this call when a unit exposes more than one entry. */
   readonly callEntry?: string;
   readonly budget?: { readonly innerSteps: number };
+  /** L1: skip this optional node when a measured state condition holds. */
+  readonly skipWhen?: string;
 }
 
 export interface GraphEdgeSpec {
@@ -48,6 +51,8 @@ export interface GraphEdgeSpec {
   /** 심이 «주입 안 됐을 때» 내려가는 순서. `requires` 는 그 심 이름들. */
   readonly fallback?: readonly { readonly node: string; readonly requires: readonly string[]; readonly observed?: number }[];
   readonly observed?: number;
+  /** L1: a measured state condition takes precedence over the default edge. */
+  readonly when?: string;
 }
 
 export interface GraphTemplateSpec {
@@ -63,10 +68,41 @@ export interface GraphTemplateSpec {
   /** ⭐ 런 계약(선택) — 이 그래프가 «기본으로» 요구하는 실행 칸 등. 발사 인자가 덮는다(graph-run-contract.ts). */
   readonly runContract?: GraphRunContractSpec;
   readonly unit?: { readonly inputs: readonly string[]; readonly outputs: readonly string[]; readonly exits: readonly string[]; readonly entries?: readonly string[] };
+  /** Non-executable landing policy declaration. The train executor consumes this in a later slice. */
+  readonly policy?: LandUnitTrainPolicySpec;
   readonly nodes: readonly GraphNodeSpec[];
   readonly edges: readonly GraphEdgeSpec[];
 }
 
+export interface LandUnitTrainPolicySpec {
+  readonly express: {
+    readonly by: readonly ('queueFlag' | 'predecessorOf' | 'multiplierTier' | 'p0InCutWindow2h')[];
+    readonly waitsForBatch: false;
+    readonly directive: string;
+  };
+  readonly batch: {
+    readonly min: number;
+    readonly max: number;
+    readonly groupBy: readonly ('area' | 'cellPrefix')[];
+    readonly maxWaitMin: number;
+    readonly order: readonly ('express' | 'predecessor' | 'enqueued')[];
+    readonly directive: string;
+  };
+  readonly scenarioPrebuild: {
+    readonly source: readonly ('src/ux-sim' | 'scenarios/ux-sim' | 'fake-llm' | 'fake-harness')[];
+    readonly mock: 'required';
+    readonly directive: string;
+  };
+  readonly gate: { readonly oncePerBatch: true; readonly directive: string };
+  readonly land: {
+    readonly perPr: 'squash';
+    readonly pinnedHead: true;
+    readonly ejectOnFail: true;
+    readonly integrationPr: false;
+    readonly directive: string;
+  };
+}
+
 export interface GraphParseIssue {
   readonly path: string;
   readonly message: string;
@@ -80,6 +116,7 @@ export interface GraphParseResult {
 
 /** ⚠️ YAML 함정 — `no`/`off`/`yes`/`on` 이 boolean 으로 파싱된다(Norway 문제). 노드 이름에 쓰면 조용히 깨진다. */
 const YAML_TRAP_WORDS = new Set(['true', 'false', 'yes', 'no', 'on', 'off', 'null', '~']);
+export const L1_PROTECTED_ROUTE_NODES = new Set(['gate', 'regate', 'review', 'merge', 'freeze-check']);
 
 function asArray(value: unknown): unknown[] {
   return Array.isArray(value) ? value : [];
@@ -102,6 +139,8 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
 
   const graphId = typeof doc.graph_id === 'string' ? doc.graph_id : undefined;
   if (graphId === undefined) errors.push({ path: `${label}/graph_id`, message: 'graph_id 가 없거나 문자열이 아니다' });
+  const policy = graphId === 'land' ? parseLandUnitTrainPolicy(doc.policy, `${label}/policy`, errors) : undefined;
+  if (graphId === 'land' && doc.policy === undefined) errors.push({ path: `${label}/policy`, message: 'land 유닛에는 착지 열차 policy 가 필요하다' });
   const version = typeof doc.version === 'number' && Number.isInteger(doc.version) ? doc.version : undefined;
   if (version === undefined) errors.push({ path: `${label}/version`, message: 'version 이 없거나 정수가 아니다' });
   const entryNode = typeof doc.entry_node === 'string' ? doc.entry_node : undefined;
@@ -147,6 +186,12 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
         : 'journey_stage 는 비어 있지 않은 문자열이어야 한다' });
       continue;
     }
+    if (n.skip_when !== undefined) {
+      if (typeof n.skip_when !== 'string' || !parseOverlayCondition(n.skip_when).ok)
+        errors.push({ path: `${at}/skip_when`, message: 'skip_when 은 오버레이 조건 한 개(key op literal)여야 한다' });
+      if (L1_PROTECTED_ROUTE_NODES.has(nodeId) || kind === 'gate' || terminalNodes.includes(nodeId))
+        errors.push({ path: `${at}/skip_when`, message: `'${nodeId}' 는 필수 검증·착지·종결 노드라 건너뛸 수 없다` });
+    }
     const contractRaw = n.contract as Record<string, unknown> | undefined;
     const contract: GraphNodeContract | undefined = contractRaw && typeof contractRaw === 'object'
       ? {
@@ -190,6 +235,7 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
       ...(kind === 'subgraph' && n.budget && typeof n.budget === 'object' && !Array.isArray(n.budget) &&
         typeof (n.budget as Record<string, unknown>).inner_steps === 'number'
         ? { budget: { innerSteps: (n.budget as { inner_steps: number }).inner_steps } } : {}),
+      ...(typeof n.skip_when === 'string' ? { skipWhen: n.skip_when } : {}),
     });
   }
   if (nodes.length === 0) errors.push({ path: `${label}/nodes`, message: '노드가 하나도 없다' });
@@ -205,6 +251,12 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
     if (!known.has(from)) { errors.push({ path: `${at}/from`, message: `'${from}' 은 선언된 노드가 아니다` }); continue; }
     const hasTo = typeof e.to === 'string';
     const hasMap = e.map !== null && typeof e.map === 'object';
+    if (e.when !== undefined && (typeof e.when !== 'string' || !parseOverlayCondition(e.when).ok))
+      errors.push({ path: `${at}/when`, message: 'when 은 오버레이 조건 한 개(key op literal)여야 한다' });
+    if (e.when !== undefined && (L1_PROTECTED_ROUTE_NODES.has(from) || nodes.some(node => node.nodeId === from && node.kind === 'gate') || terminalNodes.includes(from)))
+      errors.push({ path: `${at}/when`, message: `'${from}' 의 필수 검증·착지 결과는 when 간선으로 덮을 수 없다` });
+    if (e.when !== undefined && (!hasTo || hasMap || e.on !== undefined))
+      errors.push({ path: `${at}/when`, message: 'when 은 to 간선에서만 쓴다' });
     if (hasTo === hasMap) {
       errors.push({ path: at, message: 'to 와 map 중 «정확히 하나»를 써야 한다' });
       continue;
@@ -237,8 +289,21 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
       ...(hasMap ? { on: String(e.on), map } : {}),
       ...(fallback.length > 0 ? { fallback } : {}),
       ...(typeof e.observed === 'number' ? { observed: e.observed } : {}),
+      ...(typeof e.when === 'string' ? { when: e.when } : {}),
     });
   }
+  for (const node of nodes) {
+    if (node.skipWhen === undefined) continue;
+    const outgoing = edges.filter(edge => edge.from === node.nodeId);
+    if (outgoing.length !== 1 || outgoing[0]?.to === undefined || outgoing[0]?.when !== undefined ||
+        (outgoing[0]?.fallback?.length ?? 0) > 0)
+      errors.push({ path: `${label}/nodes/${node.nodeId}/skip_when`, message: 'skip_when 노드에는 분기 없는 무조건 to 후속 간선 하나만 필요하다' });
+  }
+  for (const edge of edges) {
+    if (edge.when === undefined) continue;
+    if (!edges.some(candidate => candidate.from === edge.from && candidate.when === undefined))
+      errors.push({ path: `${label}/edges/${edge.from}/when`, message: 'when 간선에는 모호·미관측 때 탈 무조건 기본 간선이 필요하다' });
+  }
 
   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}' 는 선언된 노드가 아니다` });
@@ -288,6 +353,7 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
     template: {
       graphId: graphId!, version: version!, entryNode: entryNode!, terminalNodes, nodes, edges,
       ...(unit ? { unit } : {}),
+      ...(policy ? { policy } : {}),
       ...(Array.isArray(journeyStages) ? { journeyStages: journeyStages as string[] } : {}),
       ...(loop ? { loop } : {}),
       ...(typeof doc.docs_only_gate_skip === 'boolean' ? { docsOnlyGateSkip: doc.docs_only_gate_skip } : {}),
@@ -298,6 +364,89 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
   };
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function isEnumList<T extends string>(value: unknown, allowed: readonly T[], expected: readonly T[]): value is T[] {
+  return Array.isArray(value) && value.every((item): item is T => typeof item === 'string' && allowed.includes(item as T))
+    && value.length === expected.length && expected.every((item, index) => value[index] === item);
+}
+
+function isDirectiveText(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  const entry = value.replace(/[\p{P}\p{S}\s]/gu, '');
+  return entry.length > 0;
+}
+
+function parseLandUnitTrainPolicy(
+  value: unknown,
+  path: string,
+  errors: GraphParseIssue[],
+): LandUnitTrainPolicySpec | undefined {
+  if (value === undefined) return undefined;
+  const fail = (suffix: string, message: string): void => { errors.push({ path: `${path}${suffix}`, message }); };
+  if (!isRecord(value) || !exactKeys(value, ['express', 'batch', 'scenarioPrebuild', 'gate', 'land'])) {
+    fail('', 'policy 는 express·batch·scenarioPrebuild·gate·land 만 가진 맵이어야 한다');
+    return undefined;
+  }
+  const express = value.express;
+  const batch = value.batch;
+  const scenarioPrebuild = value.scenarioPrebuild;
+  const gate = value.gate;
+  const land = value.land;
+  const field = (name: string, raw: unknown, keys: readonly string[]): Record<string, unknown> | undefined => {
+    if (!isRecord(raw) || !exactKeys(raw, keys)) {
+      fail(`/${name}`, `${name} 필드는 ${keys.join('·')} 키만 가진 맵이어야 한다`);
+      return undefined;
+    }
+    if (!isDirectiveText(raw.directive))
+      fail(`/${name}/directive`, 'directive 는 구두점만으로 된 값이 아닌 비어 있지 않은 문자열이어야 한다');
+    return raw;
+  };
+  const e = field('express', express, ['by', 'waitsForBatch', 'directive']);
+  const b = field('batch', batch, ['min', 'max', 'groupBy', 'maxWaitMin', 'order', 'directive']);
+  const s = field('scenarioPrebuild', scenarioPrebuild, ['source', 'mock', 'directive']);
+  const g = field('gate', gate, ['oncePerBatch', 'directive']);
+  const l = field('land', land, ['perPr', 'pinnedHead', 'ejectOnFail', 'integrationPr', 'directive']);
+
+  if (e && !isEnumList(e.by, ['queueFlag', 'predecessorOf', 'multiplierTier', 'p0InCutWindow2h'], ['queueFlag', 'predecessorOf', 'multiplierTier', 'p0InCutWindow2h']))
+    fail('/express/by', 'by 는 queueFlag·predecessorOf·multiplierTier·p0InCutWindow2h 를 각각 한 번 포함해야 한다');
+  if (e && e.waitsForBatch !== false) fail('/express/waitsForBatch', 'express 는 waitsForBatch: false 여야 한다');
+  if (b) {
+    if (!Number.isSafeInteger(b.min) || b.min !== 2) fail('/batch/min', 'min 은 정확히 2여야 한다');
+    if (!Number.isSafeInteger(b.max) || b.max !== 4) fail('/batch/max', 'max 는 정확히 4여야 한다');
+    if (Number.isSafeInteger(b.min) && Number.isSafeInteger(b.max) && (b.min as number) > (b.max as number)) fail('/batch', 'min 은 max 이하여야 한다');
+    if (!isEnumList(b.groupBy, ['area', 'cellPrefix'], ['area', 'cellPrefix'])) fail('/batch/groupBy', 'groupBy 는 area·cellPrefix 를 각각 한 번 포함해야 한다');
+    if (!Number.isSafeInteger(b.maxWaitMin) || (b.maxWaitMin as number) !== 30) fail('/batch/maxWaitMin', 'maxWaitMin 은 30 정수여야 한다');
+    if (!Array.isArray(b.order) || b.order.length !== 3 || b.order.some((item, index) => item !== ['express', 'predecessor', 'enqueued'][index]))
+      fail('/batch/order', 'order 는 express·predecessor·enqueued 순이어야 한다');
+  }
+  if (s && !isEnumList(s.source, ['src/ux-sim', 'scenarios/ux-sim', 'fake-llm', 'fake-harness'], ['src/ux-sim', 'scenarios/ux-sim', 'fake-llm', 'fake-harness']))
+    fail('/scenarioPrebuild/source', 'source 는 UX sim·fake LLM·fake harness 네 경로를 각각 한 번 포함해야 한다');
+  if (s && s.mock !== 'required') fail('/scenarioPrebuild/mock', 'mock 은 required 여야 한다');
+  if (g && g.oncePerBatch !== true) fail('/gate/oncePerBatch', 'oncePerBatch 는 true 여야 한다');
+  if (l) {
+    if (l.perPr !== 'squash') fail('/land/perPr', 'perPr 은 squash 여야 한다');
+    if (l.pinnedHead !== true) fail('/land/pinnedHead', 'pinnedHead 는 true 여야 한다');
+    if (l.ejectOnFail !== true) fail('/land/ejectOnFail', 'ejectOnFail 은 true 여야 한다');
+    if (l.integrationPr !== false) fail('/land/integrationPr', 'integrationPr 는 false 여야 한다');
+  }
+  if (!e || !b || !s || !g || !l || errors.some((error) => error.path.startsWith(`${path}/`))) return undefined;
+  return {
+    express: { by: e.by as LandUnitTrainPolicySpec['express']['by'], waitsForBatch: false, directive: e.directive as string },
+    batch: { min: b.min as number, max: b.max as number, groupBy: b.groupBy as LandUnitTrainPolicySpec['batch']['groupBy'], maxWaitMin: b.maxWaitMin as number,
+      order: b.order as LandUnitTrainPolicySpec['batch']['order'], directive: b.directive as string },
+    scenarioPrebuild: { source: s.source as LandUnitTrainPolicySpec['scenarioPrebuild']['source'], mock: 'required', directive: s.directive as string },
+    gate: { oncePerBatch: true, directive: g.directive as string },
+    land: { perPr: 'squash', pinnedHead: true, ejectOnFail: true, integrationPr: false, directive: l.directive as string },
+  };
+}
+
 /** 정규 JSON — 「같은 그래프인가」를 답하는 유일한 형식. ⛔ 키를 «정렬»해 직렬화 순서를 없앤다. */
 export function canonicalGraphJson(template: GraphTemplateSpec): string {
   const sort = (value: unknown): unknown => {
@@ -330,7 +479,8 @@ export function loadGraphTemplates(dir: string): GraphLoadResult {
   const templates: Record<string, GraphTemplateSpec> = {};
   let files: string[];
   try {
-    files = readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml')).sort();
+    // recipes are command catalogs consumed by the runner, not graph templates.
+    files = readdirSync(dir).filter((f) => (f.endsWith('.yaml') || f.endsWith('.yml')) && f !== 'recipes.yaml' && f !== 'recipes.yml').sort();
   } catch (error) {
     return { templates, errors: [{ path: dir, message: `그래프 디렉토리를 못 읽었다: ${error instanceof Error ? error.message : String(error)}` }], warnings, scannedFiles: 0 };
   }

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

@@ -1329,6 +1329,7 @@ export async function runHeadlessGoalLoopPty(opts: HeadlessGoalLoopPtyOptions):
     workdir: opts.cwd,
     env: {
       ...(opts.stateDir ? { ELANOUS_STATE_DIR: opts.stateDir } : {}),
+      ...(process.env.XDG_DATA_HOME?.trim() ? { XDG_DATA_HOME: process.env.XDG_DATA_HOME } : {}),
       [CHILD_LIVENESS_HEARTBEAT_ENV]: resolveChildLivenessHeartbeatPath(opts.cwd),
       ...controlInboxEnv(controlInboxDir),
 // ⛔⭐ 뿌리와 «한 벌»로 간다(`OBS-T121`) — 안 주면 자식이 「파생」을 「명시 격리」로 읽는다.

package/src/self-implement/knowhow-pack.ts

@@ -0,0 +1,103 @@
+/** Bounded, read-only context from promoted repository knowhow. */
+import { lstatSync, readFileSync, realpathSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+
+export const KNOWHOW_PACK_MAX_BYTES = 4096;
+const MARKER = '[KNOWHOW-PACK v1';
+const SIGNATURES = ['no-progress', 'scope-escape', 'wallclock-cap', 'pod-job-failed', 'gate-failed', 'review-blocked', 'token_revoked'];
+
+export interface KnowhowPack {
+  text: string;
+  ids: string[];
+  bytes: number;
+}
+
+function inside(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep));
+}
+
+function promotedSections(source: string): Array<{ id: string; text: string }> {
+  const sections: Array<{ id: string; text: string }> = [];
+  for (const block of source.split(/(?=^## K-[A-Z]+-\d+\b)/m)) {
+    const id = /^## (K-[A-Z]+-\d+)\b/m.exec(block)?.[1];
+    if (!id || !/^[-*] 출처:.*상태: active\s*$/m.test(block)) continue;
+    sections.push({ id, text: block.trim() });
+  }
+  return sections;
+}
+
+function mentionedPaths(text: string): Set<string> {
+  // Keep the complete repository-relative path, including package/docs prefixes.
+  // First slice: root filenames have no directory context and are deliberately excluded.
+  // A path may use any extension; reject absolute and parent-relative paths as whole tokens.
+  const paths = new Set<string>();
+  for (const match of text.matchAll(/(?<![\w./~-])([\w.-]+(?:\/[\w.-]+)+)/g)) {
+    const path = match[1].replace(/[.,;:!?]+$/, '');
+    const segments = path.split('/');
+    if (segments.some((segment) => segment === '.' || segment === '..' || !segment)) continue;
+    if (!/\.[\w-]+$/.test(segments.at(-1) ?? '')) continue;
+    paths.add(path);
+  }
+  return paths;
+}
+
+function relevance(goal: string, section: string): number {
+  const paths = mentionedPaths(goal);
+  const sourcePaths = mentionedPaths(section);
+  let score = 0;
+  for (const path of paths) {
+    if (sourcePaths.has(path)) score += 20;
+  }
+  // A path-scoped remedy must not be selected solely because an unrelated goal shares its failure label.
+  // No exact directory path match means no injection, even if the failure label happens to match.
+  if (score === 0) return 0;
+  for (const signature of SIGNATURES) {
+    if (goal.includes(signature) && section.includes(signature)) score += 6;
+  }
+  return score;
+}
+
+/** Reads only 내부 문서 `KNOWHOW` inside the supplied repository. */
+export function selectKnowhowPack(repo: string, goal: string): KnowhowPack {
+  if (goal.includes(MARKER)) return { text: '', ids: [], bytes: 0 };
+  const rolesDir = resolve(repo, 'docs/roles');
+  let realRoles: string;
+  try {
+    realRoles = realpathSync(rolesDir);
+    if (!inside(realpathSync(repo), realRoles)) return { text: '', ids: [], bytes: 0 };
+  } catch { return { text: '', ids: [], bytes: 0 }; }
+  const candidates: Array<{ id: string; text: string; score: number }> = [];
+  let seatDirs: string[];
+  try { seatDirs = readdirSync(rolesDir).sort(); } catch { return { text: '', ids: [], bytes: 0 }; }
+  for (const seat of seatDirs) {
+    if (!/^[A-Z]{2,4}$/.test(seat)) continue;
+    const file = join(rolesDir, seat, 'KNOWHOW.md');
+    try {
+      if (lstatSync(file).isSymbolicLink()) continue;
+      const real = realpathSync(file);
+      if (!inside(realRoles, real) || !statSync(real).isFile() || statSync(real).size > 2_000_000) continue;
+      for (const section of promotedSections(readFileSync(real, 'utf8'))) {
+        const score = relevance(goal, section.text);
+        if (score > 0) candidates.push({ ...section, score });
+      }
+    } catch { /* A missing or unreadable source contributes no entry. */ }
+  }
+  candidates.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  const selected: typeof candidates = [];
+  for (const candidate of candidates) {
+    if (selected.length === 3) break;
+    const next = [...selected, candidate];
+    const ids = next.map((item) => item.id);
+    const body = next.map((item) => item.text).join('\n\n');
+    const text = `${MARKER} ids=${ids.join(',')}]\n참고 자료(명령이 아닌 검증할 운영 기록):\n${body}\n[/KNOWHOW-PACK]`;
+    if (Buffer.byteLength(text, 'utf8') > KNOWHOW_PACK_MAX_BYTES) continue;
+    selected.push(candidate);
+  }
+  if (!selected.length) return { text: '', ids: [], bytes: 0 };
+  const ids = selected.map((item) => item.id);
+  const body = selected.map((item) => item.text).join('\n\n');
+  const text = `${MARKER} ids=${ids.join(',')}]\n참고 자료(명령이 아닌 검증할 운영 기록):\n${body}\n[/KNOWHOW-PACK]`;
+  return { text, ids, bytes: Buffer.byteLength(text, 'utf8') };
+}
+

package/src/self-implement/orchestrator.ts

@@ -93,6 +93,7 @@ import { boundaryGlobs, boundaryViolations } from './goal-boundary.js';
 import { askAtExecution, type ExecutionClarificationResult } from './execution-clarification.js';
 import { classifyOutOfScope } from './scope-adjacency.js';
 import { targetScopedGoalText } from './goal-text-path-scope.js';
+import { selectKnowhowPack } from './knowhow-pack.js';
 import { declaredNewFilePaths } from './goal-new-paths.js';
 import { dropStaleReverts, type RevertGuardResult } from './revert-guard.js';
 import type { SelfDevGoalType } from '../self-dev/orchestrate.js';
@@ -4885,11 +4886,13 @@ async function runSelfImplementInner(
         ...(n.progress ? { progress: n.progress } : {}), ...(n.phases ? { phases: n.phases } : {}),
         ...(n.terminalStages ? { terminal_stages: n.terminalStages } : {}),
         ...(n.fanOut ? { fan_out: n.fanOut } : {}), ...(n.contract ? { contract: n.contract } : {}),
+        ...(n.skipWhen ? { skip_when: n.skipWhen } : {}),
       })),
       edges: variantSpec.edges.map(e => ({
         from: e.from, ...(e.to === undefined ? { on: e.on, map: e.map } : { to: e.to }),
         ...(e.fallback ? { fallback: e.fallback } : {}),
         ...(e.observed === undefined ? {} : { observed: e.observed }),
+        ...(e.when ? { when: e.when } : {}),
       })),
     }), { flag: 'wx' });
     observe('graph-variant-applied', { graphId: variant.template.graphId, overlayId: variant.overlay.overlayId,
@@ -5251,6 +5254,11 @@ async function runSelfImplementInner(
     } else observe('memory', { injected: false });
   }
 
+  // The repository copy travels with both local and Pod worktrees. Operational HQ ledgers are never read here.
+  const knowhow = selectKnowhowPack(wt.path, opts.feature);
+  if (knowhow.text) round0Feature = `${knowhow.text}\n\n${round0Feature}`;
+  observe('knowhow-pack', { ids: knowhow.ids, bytes: knowhow.bytes, injected: knowhow.bytes > 0 });
+
   const maxRework = Math.max(0, opts.maxReworkRounds ?? 2);
   const selfImplementConfig = (await import('../user-config.js')).getUserConfig().tools.selfImplement;
   const shadowStop = opts.reworkBudgetShadowStop ?? selfImplementConfig.reworkBudget.shadowStop;

package/src/self-implement/pod-warm-pool-profile.ts

@@ -0,0 +1,45 @@
+/** Warm-pool profile labels select a host/tier allocation policy. */
+export const WARM_POOL_PROFILES = ['fixed', 'gate', 'landing', 'feature'] as const;
+export type WarmPoolProfile = (typeof WARM_POOL_PROFILES)[number];
+export type WarmPoolTier = 'lite' | 'standard';
+const STANDARD_HOST_MAX: Readonly<Record<string, number>> = {
+  node-b: 16,
+  node-c: 4,
+  'host-e-wsl': 5,
+};
+
+// Only this host/tier pair has a measured lite allocation. Other pairs fail closed to zero.
+const LITE_HOST_MAX: Readonly<Record<string, number>> = { mbp: 7 };
+
+export function isWarmPoolProfile(value: unknown): value is WarmPoolProfile {
+  return typeof value === 'string' && (WARM_POOL_PROFILES as readonly string[]).includes(value);
+}
+
+/** Parse a configured profile. Missing or invalid values fail closed to the fixed profile. */
+function parseWarmPoolProfile(value: unknown): WarmPoolProfile {
+  return isWarmPoolProfile(value) ? value : 'fixed';
+}
+
+/** Read the profile from either the full config object or its pod section. */
+export function resolveWarmPoolProfile(config: unknown): WarmPoolProfile {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) return 'fixed';
+  const root = config as Record<string, unknown>;
+  const pod = root.pod && typeof root.pod === 'object' && !Array.isArray(root.pod)
+    ? root.pod as Record<string, unknown>
+    : root;
+  const raw = root.raw && typeof root.raw === 'object' && !Array.isArray(root.raw)
+    ? root.raw as Record<string, unknown>
+    : undefined;
+  const rawPod = raw?.pod && typeof raw.pod === 'object' && !Array.isArray(raw.pod)
+    ? raw.pod as Record<string, unknown>
+    : undefined;
+  return parseWarmPoolProfile(pod.warmPoolProfile ?? rawPod?.warmPoolProfile);
+}
+
+/** Physical warm-worker cap for a host and worker memory tier; unknown pairs are unmeasured (0). */
+export function resolveWarmPoolQuota(profile: WarmPoolProfile, host: string, tier: WarmPoolTier): number {
+  if (!isWarmPoolProfile(profile) || !host.trim()) return 0;
+  if (tier === 'lite') return Object.hasOwn(LITE_HOST_MAX, host) ? LITE_HOST_MAX[host] : 0;
+  if (tier === 'standard') return Object.hasOwn(STANDARD_HOST_MAX, host) ? STANDARD_HOST_MAX[host] : 0;
+  return 0;
+}

package/src/self-implement/review-mustfix-class.ts

@@ -113,3 +113,206 @@ export function classifyMustFixRound(
   }
   return { class: 'new-defect', reason: '앞 회차에 없던 새 지적 — 새 실결함 수렴으로 그대로 간다' };
 }
+
+// ── 범위 판정 축 (REVIEW-MUSTFIX-CLASSIFY 첫 조각 · 대표 10-17 19:3x) ──
+//
+// 회차 분류(①②③) 위에 must-fix «한 줄마다» 범위를 가른다:
+//   in-scope   (가) 이 PR 범위 안 — 언급한 파일이 PR 변경 파일·칸 대상 경로 안이고, 쪼갤 신호가 없다 → 고친다.
+//   split      (나) 새 축 — PR 밖 파일 · 다른 PR · 설계 문서 · 다른 자리 결정 · 앞 라운드에 없던 축(r≥3) · ③ recurring
+//                    · ② 착지 뒤 증거(③·② 는 범위 입력·경로와 무관하게 split) → 같은 런에서 고치지 않고 «중간 착지 ⊕ 연결 골»로 뗀다.
+//   ask-owner  (다) 판단 불가 — 신호가 엇갈리거나, 범위 입력(변경 파일·대상 경로)이 없거나, 신호가 하나도 없다 → 칸 주인 HITL.
+// ⛔ 결정적 신호만(이 조각엔 LLM 판정 없음). ⛔ 입력이 없으면 «범위 밖 신호 없음»으로 읽지 않는다 — ask-owner.
+// ⛔ in-scope 는 «긍정 증거»(PR 안 파일 언급)가 있을 때만 — 신호가 없다고 범위 안이 아니다.
+
+export type MustFixScope = 'in-scope' | 'split' | 'ask-owner';
+
+export type MustFixScopeSignal =
+  | 'path-inside' | 'path-outside' | 'other-pr' | 'design-doc' | 'seat-decision'
+  | 'new-axis' | 'recurring' | 'post-land-evidence' | 'no-scope-input' | 'no-signal'
+  /** PR 번호를 언급했지만 이 PR 번호를 모른다 — 자기 번호일 수 있어 other-pr 로 단정하지 않는다. */
+  | 'pr-unknown'
+  /** 대상 경로 밖이지만 PR 변경 파일을 안 쟀다 — 실제 변경 파일일 수 있어 «밖»으로 단정하지 않는다. */
+  | 'path-unmeasured';
+
+export interface MustFixScopeInput {
+  /** PR 변경 파일 목록. undefined = 안 쟀다(빈 배열과 다르다). */
+  readonly changedFiles?: readonly string[];
+  /** 칸·골 대상 경로(hotPaths). undefined = 안 쟀다. */
+  readonly targetPaths?: readonly string[];
+  /** 이 PR 번호 — 자기 번호 언급은 «다른 PR» 이 아니다. */
+  readonly prNumber?: number;
+  /** 리뷰 라운드(1부터). undefined = 안 쟀다 → new-axis 신호를 안 낸다. */
+  readonly reviewRound?: number;
+  /** 앞 라운드 must-fix. undefined = 안 쟀다 → new-axis 신호를 안 낸다. */
+  readonly prevItems?: readonly MustFixItem[];
+  /** 이 회차 ③ recurring 으로 짝지어진 정규화 문면. */
+  readonly recurring?: readonly string[];
+}
+
+export interface MustFixScopeJudgement {
+  readonly text: string;
+  readonly scope: MustFixScope;
+  readonly signals: readonly MustFixScopeSignal[];
+  readonly reason: string;
+  /** 언급한 경로 중 PR 범위 밖인 것 — 연결 골 대상 경로 초안. */
+  readonly outsidePaths?: readonly string[];
+  /** 언급한 경로 중 PR 범위 안인 것. */
+  readonly insidePaths?: readonly string[];
+  /** ② 착지 뒤 증거 종류 — 연결 골 판정선을 시험이 아니라 착지 후 관측으로 낸다. */
+  readonly evidence?: MustFixEvidenceKind;
+}
+
+const SPLIT_SIGNALS: ReadonlySet<MustFixScopeSignal> = new Set([
+  'path-outside', 'other-pr', 'design-doc', 'seat-decision', 'new-axis', 'recurring', 'post-land-evidence',
+]);
+/** «앞 라운드에 없던 축»이 쪼갤 신호가 되는 첫 라운드(대표 규칙 «r3 부터 (나) 먼저 뗀다»). */
+export const NEW_AXIS_SPLIT_FROM_ROUND = 3;
+
+const PATH_RE = /(?:[\w@.-]+\/)+[\w@.-]+\.[A-Za-z]{1,5}\b|\b[\w-]+(?:\.[\w-]+)*\.(?:tsx?|mjs|cjs|jsx?|json|md|ya?ml|sh|py)\b/gu;
+const DESIGN_DOC_RE = /\b(?:RFC|MANUAL|DECISION)[-_\s]/u;
+const SEAT_DECISION_RE = /(?:다른\s*자리|자리\s*결정|대표\s*결정|\u{1F451}|owner\s+decision|another\s+seat)/iu;
+
+function normPath(p: string): string {
+  return p.replace(/^\.\//u, '').replace(/[),.;:]+$/u, '');
+}
+
+/** 경로가 범위 집합 안인가 — 정확 일치 · 디렉터리 접두 · (언급이 파일 이름뿐이면) 파일 이름 일치. */
+function pathInside(mention: string, scope: readonly string[]): boolean {
+  const m = normPath(mention);
+  return scope.some((raw) => {
+    const s = normPath(raw);
+    if (s === m) return true;
+    if (s.endsWith('/') ? m.startsWith(s) : m.startsWith(`${s}/`)) return true;
+    return !m.includes('/') && s.split('/').at(-1) === m;
+  });
+}
+
+/** 단순 토큰 자카드(2자 이상 · 소문자) — 앞 라운드에 없던 축 판정용. */
+export function mustFixTokenJaccard(a: string, b: string): number {
+  const tok = (s: string): Set<string> => new Set(s.toLowerCase().split(/[^\p{L}\p{N}_]+/u).filter((t) => t.length >= 2));
+  const x = tok(a);
+  const y = tok(b);
+  if (x.size === 0 && y.size === 0) return 0;
+  let inter = 0;
+  for (const t of x) if (y.has(t)) inter++;
+  return inter / (x.size + y.size - inter);
+}
+
+export function judgeMustFixScope(item: MustFixItem, input: MustFixScopeInput): MustFixScopeJudgement {
+  const signals: MustFixScopeSignal[] = [];
+  const scopePaths = [...(input.changedFiles ?? []), ...(input.targetPaths ?? [])];
+  const scopeMeasured = input.changedFiles !== undefined || input.targetPaths !== undefined;
+  const mentions = [...new Set((item.text.match(PATH_RE) ?? []).map(normPath))];
+  const insidePaths = scopeMeasured ? mentions.filter((m) => pathInside(m, scopePaths)) : [];
+  const outsidePaths = scopeMeasured ? mentions.filter((m) => !pathInside(m, scopePaths)) : mentions;
+  if (!scopeMeasured) signals.push('no-scope-input');
+  else {
+    if (insidePaths.length) signals.push('path-inside');
+    // 변경 파일을 안 쟀으면 대상 경로 밖이라는 사실만으로 «PR 밖»이 아니다.
+    if (outsidePaths.length) signals.push(input.changedFiles === undefined ? 'path-unmeasured' : 'path-outside');
+  }
+  const prs = [...item.text.matchAll(/#(\d{5})\b/gu)].map((m) => Number(m[1]));
+  if (prs.length > 0 && input.prNumber === undefined) signals.push('pr-unknown');
+  else if (prs.some((n) => n !== input.prNumber)) signals.push('other-pr');
+  if (DESIGN_DOC_RE.test(item.text)) signals.push('design-doc');
+  if (SEAT_DECISION_RE.test(item.text)) signals.push('seat-decision');
+  if (item.evidence !== undefined) signals.push('post-land-evidence');
+  if (input.recurring?.includes(mustFixKey(item.text))) signals.push('recurring');
+  if (input.reviewRound !== undefined && input.reviewRound >= NEW_AXIS_SPLIT_FROM_ROUND
+    && input.prevItems !== undefined && input.prevItems.length > 0
+    && input.prevItems.every((p) => mustFixTokenJaccard(p.text, item.text) === 0)) signals.push('new-axis');
+
+  const split = signals.filter((s) => SPLIT_SIGNALS.has(s));
+  const paths = {
+    ...(outsidePaths.length ? { outsidePaths } : {}),
+    ...(insidePaths.length ? { insidePaths } : {}),
+    ...(item.evidence !== undefined ? { evidence: item.evidence } : {}),
+  };
+  if (signals.includes('recurring')) {
+    return { text: item.text, scope: 'split', signals, reason: '같은 축이 수리 뒤 다시 나왔다 — 같은 런 재수리 대신 연결 골로 뗀다', ...paths };
+  }
+  // ② 착지 뒤 증거는 줄 단위 사실 — 경로가 PR 안이어도 같은 런에서 못 낸다. 회차 분류 ② 와 늘 같은 갈래(split)로 간다.
+  if (signals.includes('post-land-evidence')) {
+    return { text: item.text, scope: 'split', signals, reason: '증거는 착지 뒤에만 난다 — 그림자 착지 → 관측 → live 연결 골로 뗀다', ...paths };
+  }
+  if (signals.includes('path-unmeasured')) {
+    return { text: item.text, scope: 'ask-owner', signals, reason: '대상 경로 밖 경로를 언급했지만 PR 변경 파일을 안 쟀다 — PR 밖인지 못 가린다', ...paths };
+  }
+  if (signals.includes('pr-unknown')) {
+    return { text: item.text, scope: 'ask-owner', signals, reason: 'PR 번호를 언급했는데 이 PR 번호를 모른다 — 다른 PR 인지 못 가린다', ...paths };
+  }
+  if (split.length > 0 && !scopeMeasured) {
+    return { text: item.text, scope: 'ask-owner', signals, reason: `쪼갤 신호(${split.join(' · ')})는 있으나 범위 입력이 없다 — 이 PR 이 이미 맡았는지 못 가린다`, ...paths };
+  }
+  if (split.length > 0 && signals.includes('path-inside')) {
+    return { text: item.text, scope: 'ask-owner', signals, reason: `신호가 엇갈린다 — PR 안 파일 언급 ⊕ 쪼갤 신호(${split.join(' · ')})`, ...paths };
+  }
+  if (split.length > 0) {
+    return { text: item.text, scope: 'split', signals, reason: `이 PR 범위 밖 신호(${split.join(' · ')}) — 중간 착지 ⊕ 연결 골로 뗀다`, ...paths };
+  }
+  if (signals.includes('path-inside')) {
+    return { text: item.text, scope: 'in-scope', signals, reason: '언급한 파일이 PR 범위 안이고 쪼갤 신호가 없다 — 이 PR 에서 고친다', ...paths };
+  }
+  if (scopeMeasured) signals.push('no-signal');
+  return {
+    text: item.text, scope: 'ask-owner', signals,
+    reason: scopeMeasured ? '범위 신호가 하나도 없다 — «없다»를 범위 안으로 읽지 않고 칸 주인에게 묻는다' : '범위 입력(변경 파일·대상 경로)이 없다 — 칸 주인에게 묻는다',
+    ...paths,
+  };
+}
+
+/** (나) split 한 줄의 «중간 착지 ⊕ 연결 골» 제안 — 다음 라운드 intent 스코프 경계 문장 ⊕ 연결 골 초안. */
+export interface MustFixSplitProposal {
+  readonly text: string;
+  /** 다음 라운드 intent «의도적 스코프 경계» 에 넣을 문장(이유 포함). */
+  readonly intentScopeBoundary: string;
+  /** 연결 골 초안 — 대상 경로 ⊕ 판정선 한 줄. targetPaths 가 비면 «대상 경로 미상»(저작 단계에서 채운다). */
+  readonly linkGoal: { readonly targetPaths: readonly string[]; readonly verdictLine: string };
+}
+
+function clip(text: string, n = 120): string {
+  const t = text.trim().replace(/\s+/gu, ' ');
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+}
+
+function testPathFor(path: string): string | undefined {
+  if (/\.test\.tsx?$/u.test(path)) return path;
+  const m = /^(.*)\.(tsx?)$/u.exec(path);
+  return m ? `${m[1]}.test.${m[2]}` : undefined;
+}
+
+const EVIDENCE_OBSERVATION: Record<MustFixEvidenceKind, string> = {
+  'live-caller': 'live 호출자가 실제로 부르는 것',
+  'ops-consumption': '운영이 실제로 소비하는 것',
+  'artifact-landing': '실물이 실제로 착지한 것',
+};
+
+/**
+ * 연결 골 대상 경로는 지적이 «언급한» 경로만 — 원래 골의 hotPaths 를 끌어다 대지 않는다(근거 없음 → 미상, 저작 단계에서 채운다).
+ * ② 착지 뒤 증거는 시험 통과로 증명되지 않으므로 판정선을 «그림자 착지 뒤 관측»으로 낸다.
+ */
+export function proposeMustFixSplit(j: MustFixScopeJudgement): MustFixSplitProposal {
+  const targetPaths = j.outsidePaths?.length ? [...j.outsidePaths] : j.insidePaths?.length ? [...j.insidePaths] : [];
+  const test = targetPaths.map(testPathFor).find((p): p is string => p !== undefined);
+  const subject = clip(j.text, 80);
+  if (j.evidence !== undefined) {
+    return {
+      text: j.text,
+      intentScopeBoundary: `«${subject}» — 미완이 아니라 이 PR 의 결정이다: ${j.reason}(신호 ${j.signals.join(' · ')}). 연결 골로 뗐다 · 이것으로 must-fix 를 만들지 말 것`,
+      linkGoal: {
+        targetPaths,
+        verdictLine: `판정(착지 뒤 관측): 그림자 착지 뒤 ${EVIDENCE_OBSERVATION[j.evidence]}을 로그·원장에서 관측 — 관측 명령은 저작 단계에서 채운다(시험 통과만으로는 증명 아님)`,
+      },
+    };
+  }
+  return {
+    text: j.text,
+    intentScopeBoundary: `«${subject}» — 미완이 아니라 이 PR 의 결정이다: ${j.reason}(신호 ${j.signals.join(' · ')}). 연결 골로 뗐다 · 이것으로 must-fix 를 만들지 말 것`,
+    linkGoal: {
+      targetPaths,
+      verdictLine: test
+        ? `판정: bun test ${test} → «${subject}» 고정 시험 ⊕ 0 fail`
+        : `판정: «${subject}» 해소를 반증 명령 한 줄로 — 대상 경로 ${targetPaths.length ? targetPaths.join(' ') : '미상'}(저작 단계에서 채운다)`,
+    },
+  };
+}