elanous 0.2.31 → 0.2.34

package/src/self-dev/graph-journey-route.ts

@@ -1,7 +1,8 @@
 import { debug } from '../debug/log.js';
 import { GRAPH_SPECS } from '../self-implement/graph-templates.js';
 import { applyGraphOverlays, defaultOverlaysDir, loadGraphOverlays, selectOverlays, type GraphOverlaySpec } from '../self-implement/graph-overlay-yaml.js';
-import type { GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { L1_PROTECTED_ROUTE_NODES, type GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { evaluateOverlayCondition } from '../self-implement/graph-overlay-condition.js';
 import { journeyJoinFields } from './graph-journey-nodes.js';
 
 /** ⭐ HARNESS-FULL-GRAPH 2판 — 「다음 노드」를 코드가 아니라 «그래프»가 정한다.
@@ -21,6 +22,13 @@ export interface JourneyRoute {
   readonly to: string | null;
   readonly source: 'graph' | 'code-default';
   readonly overlays: readonly string[];
+  readonly via?: 'outcome' | 'when';
+  readonly condition?: string;
+  readonly ambiguousConditions?: readonly string[];
+  readonly unobservedConditions?: readonly string[];
+  readonly skippedNode?: string;
+  readonly skipCondition?: string;
+  readonly skippedNodes?: readonly { readonly node: string; readonly condition: string }[];
 }
 
 /** ⛔ 캐시하지 않는다 — 여러 런을 처리하는 프로세스(데몬·대기열 tick)가 다음 발사에서 오버레이 변경을 봐야 한다.
@@ -65,12 +73,46 @@ export function readJourneyEdge(
 ): JourneyRoute {
   const { spec, applied } = journeySpec(state, deps.base ?? GRAPH_SPECS['self-implement'], deps.overlays ?? launchOverlays());
   let route: JourneyRoute = { from, on: null, label, to: null, source: 'code-default', overlays: applied };
-  for (const edge of spec?.edges ?? []) {
-    if (edge.from !== from) continue;
-    if (edge.map !== undefined && Object.hasOwn(edge.map, label)) {
-      route = { from, on: edge.on ?? null, label, to: edge.map[label]!, source: 'graph', overlays: applied };
-      break;
+  const outgoing = (spec?.edges ?? []).filter(edge => edge.from === from);
+  const protectedFrom = L1_PROTECTED_ROUTE_NODES.has(from) || spec?.nodes.some(node => node.nodeId === from && node.kind === 'gate') ||
+    spec?.terminalNodes.includes(from);
+  const conditions = outgoing.filter(edge => edge.when !== undefined && !protectedFrom).map(edge => ({ edge, verdict: evaluateOverlayCondition(edge.when, state) }));
+  const matching = conditions.filter(({ verdict }) => verdict.kind === 'applies').map(({ edge }) => edge);
+  const unobservedConditions = conditions.filter(({ verdict }) => verdict.kind === 'key-absent').map(({ edge }) => edge.when!);
+  if (matching.length === 1 && unobservedConditions.length === 0 && matching[0]!.to !== undefined) {
+    route = { from, on: null, label, to: matching[0]!.to!, source: 'graph', overlays: applied,
+      via: 'when', condition: matching[0]!.when };
+  } else {
+    const mapped = outgoing.find(edge => edge.when === undefined && edge.map !== undefined && Object.hasOwn(edge.map, label));
+    const defaultEdge = mapped ?? outgoing.find(edge => edge.when === undefined && edge.to !== undefined);
+    if (defaultEdge?.map !== undefined) route = { from, on: defaultEdge.on ?? null, label,
+      to: defaultEdge.map[label]!, source: 'graph', overlays: applied, via: 'outcome' };
+    else if (defaultEdge?.to !== undefined) route = { from, on: null, label,
+      to: defaultEdge.to, source: 'graph', overlays: applied, via: 'outcome' };
+    if (matching.length > 1) route = { ...route, ambiguousConditions: matching.map(edge => edge.when!) };
+    if (unobservedConditions.length > 0) route = { ...route, unobservedConditions };
+  }
+  // A skipped optional node needs one unambiguous unconditional successor. Otherwise retain
+  // the ordinary route; neither a missing observation nor a branching node is a skip proof.
+  if (route.to && spec) {
+    const skipped: { node: string; condition: string }[] = [];
+    const visited = new Set<string>();
+    while (route.to && !visited.has(route.to)) {
+      visited.add(route.to);
+      const next = spec.nodes.find(node => node.nodeId === route.to);
+      if (!next?.skipWhen || next.kind === 'gate' ||
+          L1_PROTECTED_ROUTE_NODES.has(next.nodeId) ||
+          spec.terminalNodes.includes(next.nodeId) ||
+          evaluateOverlayCondition(next.skipWhen, state).kind !== 'applies') break;
+      const successors = spec.edges.filter(edge => edge.from === next.nodeId);
+      if (successors.length !== 1 || successors[0]?.to === undefined ||
+          successors[0]?.when !== undefined || (successors[0]?.fallback?.length ?? 0) > 0 ||
+          visited.has(successors[0].to)) break;
+      skipped.push({ node: next.nodeId, condition: next.skipWhen });
+      route = { ...route, to: successors[0]!.to! };
     }
+    if (skipped.length > 0) route = { ...route, skippedNode: skipped[0]!.node,
+      skipCondition: skipped[0]!.condition, skippedNodes: skipped };
   }
   return route;
 }
@@ -78,6 +120,18 @@ export function readJourneyEdge(
 /** 실제로 탄 간선을 남긴다 — `taken` 은 실제 다음 노드(그래프 답과 다르면 `honored: false` · 그 이유를 `reason` 에). */
 export function recordJourneyEdge(route: JourneyRoute, taken: string, reason?: string): void {
   try {
+    if (route.ambiguousConditions?.length) debug.log('self-implement', 'edge-ambiguous', {
+      graphId: 'self-implement', from: route.from, conditions: route.ambiguousConditions,
+      fallback: taken, ...journeyJoinFields(),
+    });
+    if (route.unobservedConditions?.length) debug.log('self-implement', 'edge-unobserved', {
+      graphId: 'self-implement', from: route.from, conditions: route.unobservedConditions,
+      fallback: taken, ...journeyJoinFields(),
+    });
+    if (route.to === taken) for (const skipped of route.skippedNodes ?? []) debug.log('self-implement', 'node-skipped', {
+      graphId: 'self-implement', node: skipped.node, reason: 'condition', condition: skipped.condition,
+      ...journeyJoinFields(),
+    });
     debug.log('self-implement', 'graph-edge-taken', {
       graphId: 'self-implement', ...route, taken, honored: route.to === null || route.to === taken,
       ...(reason === undefined ? {} : { reason }), ...journeyJoinFields(),

package/src/self-dev/orchestrate.ts

@@ -29,7 +29,7 @@ import { availableParallelism, cpus } from 'node:os';
 import { selfDevRunsDir } from './run-store.js';
 import { HARNESS_RUN_ID_ENV, normalizeRunId } from '../harness/harness-space.js';
 import { plannedSelfImplBranch } from '../harness/worktree-branch-prefix.js';
-import { parseGoalId } from '../self-implement/goal-author.js';
+import { inspectGoalDoneBoundary, parseGoalId } from '../self-implement/goal-author.js';
 import { isTransientExecutionFailure } from './execution-transient.js';
 import type { AbandonedClassification } from '../self-implement/abandoned-classification.js';
 import type { JobKind, SelfDevGoal, SelfDevJobResult } from './run-types.js';
@@ -204,7 +204,7 @@ interface SelfDevTerminalOutcome {
   stage: string | null;
   merged: boolean | null;
   prUrl: string | null;
-  blockReason?: 'parent-unlanded';
+  blockReason?: 'parent-unlanded' | 'dependency-needs-human';
   parentPrNumber?: number | null;
   parentNoPr?: true;
 }
@@ -493,6 +493,7 @@ export function classifyFailure(
   preflightWarning: PreflightWarningObservation = 'unknown',
 ): FailureKind | null {
   if (result.blockReason === 'parent-unlanded') return 'parent-unlanded';
+  if (result.blockReason === 'dependency-needs-human' || result.error?.code === 'GOAL_DONE_BOUNDARY_MISSING') return 'awaiting-human';
   const ledgerKind = result.failureClassification === undefined
     ? undefined
     : result.failureClassification === 'run-deadline-exceeded'
@@ -767,6 +768,8 @@ export function resolveOrchestrateConcurrency(
 
 export interface OrchestrateSelfDevOptions {
   goals: SelfDevGoal[];
+  /** TA 카드 출처. 생략하면 발사 환경의 ELANOUS_TASK_CARD_ID를 읽는다. */
+  taskCardId?: string;
   /** Original composite request. Multi-shard runs carry it to each child; omitted
    *  keeps legacy callers and non-decomposed goal lists byte-for-byte unchanged. */
   parentRequest?: string;
@@ -947,6 +950,77 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
   const now = opts.now ?? Date.now;
   const runId = opts.runId ?? process.env[HARNESS_RUN_ID_ENV];
   if (runId && runId !== normalizeRunId(runId)) throw new Error(`invalid self-dev run ID: ${runId}`);
+  const taskCardId = opts.taskCardId ?? process.env.ELANOUS_TASK_CARD_ID;
+  const boundaryResults: SelfDevJobResult[] = [];
+  if (taskCardId?.trim()) {
+    const parentBoundary = inspectGoalDoneBoundary(opts.parentRequest ?? '');
+    const inherited: Array<{ index: number; labels: string[] }> = [];
+    opts = { ...opts, goals: opts.goals.map((goal, index) => {
+      if (goal.kind && goal.kind !== 'dev') return goal;
+      const missing = inspectGoalDoneBoundary(goal.feature).missing;
+      const lines = missing.flatMap((label) => parentBoundary.values[label] ? [`- ${label}: ${parentBoundary.values[label]}`] : []);
+      if (lines.length === 0) return goal;
+      inherited.push({ index: index + 1, labels: missing.filter((label) => parentBoundary.values[label]) });
+      return { ...goal, feature: `${goal.feature.trimEnd()}\n${lines.join('\n')}` };
+    }) };
+    if (inherited.length > 0) {
+      try { debug.log('self-dev.orchestrate', 'done-boundary-inherited', { taskCardId, inherited }); } catch { /* fail-soft */ }
+    }
+    const boundaryMissing = opts.goals.flatMap((goal, index) => {
+      if (goal.kind && goal.kind !== 'dev') return [];
+      const boundary = inspectGoalDoneBoundary(goal.feature);
+      return boundary.missing.length ? [{ index: index + 1, goal: goal.id ?? goal.feature.split(/\r?\n/, 1)[0]?.slice(0, 80) ?? '', missing: boundary.missing }] : [];
+    });
+    if (boundaryMissing.length > 0) {
+      const blockedGoalIndexes = new Set<number>(boundaryMissing.map(({ index }) => index - 1));
+      const blockedByBoundaryId = new Set(boundaryMissing.map(({ index }) => {
+        const goal = opts.goals[index - 1]!;
+        return goal.id ?? String(index - 1);
+      }));
+      const blockedDependents = new Map<number, string>();
+      let changed = true;
+      while (changed) {
+        changed = false;
+        opts.goals.forEach((goal, index) => {
+          if (blockedDependents.has(index)) return;
+          const goalId = goal.id ?? String(index);
+          const predecessor = (goal.dependsOn ?? []).find((id) => id !== goalId && blockedByBoundaryId.has(id));
+          if (!predecessor) return;
+          blockedGoalIndexes.add(index);
+          blockedByBoundaryId.add(goalId);
+          blockedDependents.set(index, predecessor);
+          changed = true;
+        });
+      }
+      for (const item of boundaryMissing.filter(({ index }) => !blockedDependents.has(index - 1))) {
+        const goal = opts.goals[item.index - 1]!;
+        boundaryResults.push({
+          taskId: `boundary:${taskCardId}:needs-human:${item.index}`,
+          feature: goal.feature,
+          status: 'failed',
+          stage: 'needs-human',
+          stopReason: 'needs-human',
+          error: { code: 'GOAL_DONE_BOUNDARY_MISSING', message: item.missing.join(' · ') },
+        });
+      }
+      for (const [index, predecessor] of blockedDependents) {
+        const goal = opts.goals[index]!;
+        boundaryResults.push({
+          taskId: `boundary:${taskCardId}:blocked:${index + 1}`,
+          feature: goal.feature,
+          status: 'blocked',
+          blockReason: 'dependency-needs-human',
+          stopReason: 'needs-human',
+          error: { code: 'DEPENDENCY_NEEDS_HUMAN', message: `선행 needs-human: ${predecessor}` },
+        });
+      }
+      const withheld = [...blockedGoalIndexes].map((index) => index + 1);
+      try { debug.log('self-dev.orchestrate', 'done-boundary-missing', { taskCardId, boundaryMissing, withheld, action: 'needs-human', eligibleToLaunch: opts.goals.length - blockedGoalIndexes.size }); } catch { /* fail-soft */ }
+      opts = { ...opts, goals: opts.goals.flatMap((goal, index) => blockedGoalIndexes.has(index)
+        ? []
+        : [{ ...goal, id: goal.id ?? String(index) }]) };
+    }
+  }
   const pidPath = runId ? join(opts.runsDir ?? selfDevRunsDir(), runId, 'pid.json') : undefined;
   // Only the real run directory gets a host-wide binding by default — an overridden runsDir is an isolated test.
   const registryDir = opts.launchRegistryDir !== undefined ? opts.launchRegistryDir : opts.runsDir === undefined ? launchRegistryDir() : null;
@@ -1388,7 +1462,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
     // state (with disposition merged when the job has settled). Reused by
     // both `finish()` and the mid-run checkpoint.
     const buildResults = (): SelfDevJobResult[] => {
-      const out: SelfDevJobResult[] = [...resumedResults];
+      const out: SelfDevJobResult[] = [...resumedResults, ...boundaryResults];
       for (const [taskId, goal] of taskByGoal) {
         const status = graph.getTask(taskId)?.status ?? 'failed';
         const resumeDisposition = resumeDispositionByGoal.get(goal);
@@ -1420,6 +1494,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
           ...(disp?.providerErrors ? { providerErrors: disp.providerErrors } : {}),
           ...(disp?.rework ? { rework: disp.rework } : {}),
           ...(disp?.mustFix ? { reviewMustFix: disp.mustFix } : {}),
+          ...(disp?.mustFix && goal.hotPaths?.length ? { targetPaths: [...goal.hotPaths] } : {}),
           ...(goalCauseObservedFromFailureClassification(disp?.failureClassification) === true
             ? { goalCauseObserved: true } : {}),
           ...(disp?.runId ? { runId: disp.runId } : {}),
@@ -1496,6 +1571,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
         unclassified: failureKinds.unclassified,
         mainSyncBlocked: failureKinds.mainSyncBlocked,
         parentUnlanded: out.filter((r) => r.blockReason === 'parent-unlanded').length,
+        dependencyNeedsHuman: out.filter((r) => r.blockReason === 'dependency-needs-human').length,
         failures,
         blockedParents: out.filter((r) => r.blockReason === 'parent-unlanded').map((r) => ({ taskId: r.taskId, blockReason: r.blockReason, parentPrNumber: r.parentPrNumber ?? null, ...(r.parentNoPr ? { parentNoPr: true } : {}) })),
         ...(unionDiff ? { unionDiff } : {}),

package/src/self-dev/run-supervisor.ts

@@ -12,7 +12,10 @@ import { sweepFrozenMerges } from '../self-implement/frozen-merges.js';
 import { routeSupervisorVerdict } from './supervisor-verdict-edges.js';
 import { recordTaskAgentShadowMove, runCardFor, type TaskAgentShadowInput } from '../task-agent/shadow.js';
 import { cardPrNumber, taskAgentStatePath } from '../task-agent/task-hand.js';
-import { classifyMustFixRound, inferMustFixEvidence, type MustFixRoundClassification, type MustFixRoundObservation } from '../self-implement/review-mustfix-class.js';
+import {
+  classifyMustFixRound, inferMustFixEvidence, judgeMustFixScope, proposeMustFixSplit,
+  type MustFixRoundClassification, type MustFixRoundObservation, type MustFixScope, type MustFixScopeJudgement, type MustFixSplitProposal,
+} from '../self-implement/review-mustfix-class.js';
 
 export interface SupervisorRound {
   round: number;
@@ -115,6 +118,16 @@ export interface SupervisorDecision {
   mustFix?: MustFixRoundClassification;
   /** REVIEW-MUSTFIX-CLASSIFY — every oscillating task's measured class, so a mixed round keeps each task's decision. */
   mustFixByTask?: Record<string, MustFixRoundClassification>;
+  /**
+   * REVIEW-MUSTFIX-CLASSIFY 범위 축 — must-fix 한 줄마다 (가) in-scope / (나) split / (다) ask-owner.
+   * split 은 같은 런 재수리에서 빠지고 «중간 착지 ⊕ 연결 골» 제안을 싣는다(파일·칸 쓰기는 다음 조각 — 이번엔 결정 칸까지).
+   * ask-owner 는 칸 주인 HITL 제안. 진동 경로에서 must-fix 를 잰 조각만 — 없으면 생략(지금 동작 그대로).
+   */
+  mustFixScope?: {
+    byTask: Record<string, MustFixScopeJudgement[]>;
+    split?: Array<{ taskId: string; action: '중간 착지 ⊕ 연결 골'; proposals: MustFixSplitProposal[] }>;
+    askOwner?: Array<{ taskId: string; hitl: string; items: string[] }>;
+  };
   oscillation?: { taskIds: string[]; helper: 'review-oscillation'; signature: string; repairGoals?: Record<string, string>; heldTaskIds?: string[] };
   pendingDecision?: 'attempt-care-escalation';
 }
@@ -262,11 +275,70 @@ function classifyTaskMustFix(result: SupervisorJobResult, preceding: SupervisorR
 }
 
 /**
- * Classes that hold a task out of this round's same-run repair. Only ② acts in this slice; ③ recurring is
- * observed (decision `mustFix`/`mustFixByTask` · crossReview suggestion) but behaves as ① — acting on it is a
- * follow-up cell (REVIEW-MUSTFIX-CLASSIFY partial landing).
+ * Classes/scopes that hold a task out of this round's same-run repair: ② post-land-evidence, and (나) split when
+ * every must-fix item of the task is split (③ recurring items are split). A partly split task is repaired with its
+ * non-split items only.
+ */
+const MUST_FIX_HELD = new Set<MustFixRoundClassification['class'] | MustFixScope>(['post-land-evidence', 'split']);
+// ⚠️ 'post-land-evidence' 는 보류 «사유» 문면에만 쓰인다 — 보류 여부는 줄 단위 'split'(② 줄 포함)이 정한다.
+
+/**
+ * REVIEW-MUSTFIX-CLASSIFY 범위 축 — 한 조각의 must-fix 를 줄마다 범위 판정한다. `prevItems` 는 앞 회차 원장의 같은
+ * 조각(또는 수리 계보) 지적 — 앞 회차가 must-fix 를 안 쟀으면 undefined(new-axis 신호를 안 낸다).
  */
-const MUST_FIX_HELD = new Set<MustFixRoundClassification['class']>(['post-land-evidence']);
+function judgeTaskMustFixScope(
+  result: SupervisorJobResult, preceding: SupervisorRound | undefined, classification: MustFixRoundClassification,
+): MustFixScopeJudgement[] {
+  const items = mustFixFromResults([result]).items ?? [];
+  const pairIds = new Set([result.taskId, ...(result.oscillationRepairOf ? [result.oscillationRepairOf] : [])]);
+  const precedingItems = preceding?.mustFix?.items;
+  const prevItems = precedingItems === undefined ? undefined
+    : precedingItems.filter((item) => item.taskId !== undefined && pairIds.has(item.taskId));
+  return items.map((item) => judgeMustFixScope(item, {
+    ...(result.changedFiles ? { changedFiles: result.changedFiles } : {}),
+    ...(result.targetPaths ? { targetPaths: result.targetPaths } : {}),
+    ...(result.prNumber !== undefined ? { prNumber: result.prNumber } : {}),
+    ...(result.rework?.rounds !== undefined ? { reviewRound: result.rework.rounds } : {}),
+    ...(prevItems !== undefined ? { prevItems } : {}),
+    ...(classification.recurring ? { recurring: classification.recurring } : {}),
+  }));
+}
+
+/**
+ * 범위 판정을 결정 칸으로 접고 줄마다 관측을 남긴다 — (나) 는 «중간 착지 ⊕ 연결 골» 제안, (다) 는 칸 주인 HITL 제안.
+ * 실제 연결 골 파일·칸 근거 쓰기·intent 자동 주입 실행은 다음 조각.
+ */
+function mustFixScopeDecision(
+  oscillating: readonly SupervisorJobResult[],
+  taskClasses: ReadonlyMap<string, MustFixRoundClassification>,
+  taskScopes: ReadonlyMap<string, MustFixScopeJudgement[]>,
+): SupervisorDecision['mustFixScope'] {
+  const byTask: Record<string, MustFixScopeJudgement[]> = {};
+  const split: NonNullable<NonNullable<SupervisorDecision['mustFixScope']>['split']> = [];
+  const askOwner: NonNullable<NonNullable<SupervisorDecision['mustFixScope']>['askOwner']> = [];
+  for (const result of oscillating) {
+    const judged = taskScopes.get(result.taskId) ?? [];
+    if (judged.length === 0 || byTask[result.taskId]) continue;
+    byTask[result.taskId] = judged;
+    const cls = taskClasses.get(result.taskId)?.class ?? 'unmeasured';
+    for (const j of judged) {
+      const action = j.scope === 'split' ? 'split-link-goal' : j.scope === 'ask-owner' ? 'ask-owner-hitl' : 'fix-same-run';
+      try { debug.log('self-dev.supervisor', 'mustfix-scope', { taskId: result.taskId, class: cls, scope: j.scope, signals: j.signals, action }); } catch { /* fail-open */ }
+    }
+    const splits = judged.filter((j) => j.scope === 'split');
+    if (splits.length) {
+      split.push({ taskId: result.taskId, action: '중간 착지 ⊕ 연결 골',
+        proposals: splits.map((j) => proposeMustFixSplit(j)) });
+    }
+    const asks = judged.filter((j) => j.scope === 'ask-owner');
+    if (asks.length) {
+      askOwner.push({ taskId: result.taskId, items: asks.map((j) => j.text),
+        hitl: `칸 주인에게 묻는다 — must-fix ${asks.length}건 범위 판단 불가(${[...new Set(asks.map((j) => j.reason))].join(' · ')})` });
+    }
+  }
+  if (Object.keys(byTask).length === 0) return undefined;
+  return { byTask, ...(split.length ? { split } : {}), ...(askOwner.length ? { askOwner } : {}) };
+}
 
 export function decideNextRun(input: {
   results: readonly SupervisorJobResult[];
@@ -557,30 +629,52 @@ export function decideNextRun(input: {
     // REVIEW-MUSTFIX-CLASSIFY — 슈퍼바이저는 추이 대신 회차 분류를 먼저 본다(대표 10-12 «노하우가 아니라 로직으로» · 임의 임계 없음).
     //   ① new-defect — 그대로 수렴(진동 수리 유지).
     //   ② post-land-evidence — 증거는 착지 뒤에만 난다 ⇒ 같은 런 재수리 0, «그림자 착지 → 관측 → live» 쪼개기 결정.
-    //   ③ recurring — 수리 뒤 같은 지적 ⇒ 이 조각에선 관측만(교차 리뷰 제안을 결정에 싣고 동작은 ① 그대로 · 후속 칸).
+    //   ③ recurring — 수리 뒤 같은 지적 ⇒ 교차 리뷰 제안을 결정에 싣고, 그 줄은 범위 축에서 (나) split 으로 같은 런 수리에서 뺀다.
     //   unmeasured — 분류 불가 ⇒ 지금 동작 그대로. 분류는 조각마다 — 한 조각의 분류가 다른 조각의 수리를 끊지 않는다.
     const taskClasses = new Map(oscillating.map((result) => [result.taskId, classifyTaskMustFix(result, preceding)]));
-    const fresh = oscillating.filter((result) => !isRepaired(result) && !MUST_FIX_HELD.has(taskClasses.get(result.taskId)!.class));
+    // 범위 축 — must-fix 한 줄마다 (가)/(나)/(다). 모든 줄이 (나) 면 조각을 보류하고, 일부면 (나) 를 뺀 줄로만 수리한다.
+    const taskScopes = new Map(oscillating.map((result) => [result.taskId,
+      judgeTaskMustFixScope(result, preceding, taskClasses.get(result.taskId)!)]));
+    const allSplit = (taskId: string): boolean => {
+      const judged = taskScopes.get(taskId) ?? [];
+      return judged.length > 0 && judged.every((j) => j.scope === 'split');
+    };
+    // 보류는 줄 단위 범위로만 가른다 — ② 줄은 범위 축에서 늘 split 이므로 ② 회차(모든 줄이 착지 뒤 증거)는 allSplit 와 같고,
+    // 한 줄이라도 (가)/(다) 가 남으면 그 줄은 수리 골로 간다(조각 통째 보류 금지).
+    const isClassHeld = (taskId: string): boolean => MUST_FIX_HELD.has('split') && allSplit(taskId);
+    const fresh = oscillating.filter((result) => !isRepaired(result) && !isClassHeld(result.taskId));
     const classes = [...taskClasses.values()];
     // Decision-level class: ② (the only acting class) first, then observed ③, else ①.
     const mustFixClass = classes.find((c) => c.class === 'post-land-evidence') ?? classes.find((c) => c.class === 'recurring')
       ?? classes.find((c) => c.class === 'new-defect');
-    // Held = already repaired once, or classified ② — either way it never rides this round's rerun.
+    // Held = already repaired once, classified ②, or every must-fix item is (나) split — none rides this round's rerun.
     const classHeld = [...new Set(oscillating.filter((result) => !isRepaired(result)
-      && MUST_FIX_HELD.has(taskClasses.get(result.taskId)!.class)).map((result) => result.taskId))];
+      && isClassHeld(result.taskId)).map((result) => result.taskId))];
     const held = [...new Set([...oscillating.filter(isRepaired).map((result) => result.taskId), ...classHeld])];
     const repairedHeld = held.filter((id) => !classHeld.includes(id));
     // Every task's measured class survives in the decision — a mixed round keeps ② split and the observed ③ cross-review suggestion both.
     const mustFixByTask: Record<string, MustFixRoundClassification> = Object.fromEntries(
       [...taskClasses].filter(([, c]) => c.class !== 'unmeasured'));
-    const heldReasons = [...new Set(classes.filter((c) => MUST_FIX_HELD.has(c.class)).map((c) => c.reason))];
+    const heldReasons = [...new Set([
+      // 사유는 실제로 분류·범위로 보류된 조각에서만 — 수리되거나 이미 수리해 보류된 조각의 ② 사유는 싣지 않는다.
+      ...classHeld.map((id) => taskClasses.get(id)!).filter((c) => MUST_FIX_HELD.has(c.class)).map((c) => c.reason),
+      ...(classHeld.some((id) => !MUST_FIX_HELD.has(taskClasses.get(id)!.class))
+        ? ['must-fix 가 전부 (나) 범위 밖 — 같은 런 재수리 0, 중간 착지 ⊕ 연결 골'] : []),
+    ])];
     const heldReasonSuffix = heldReasons.length ? ` · ${heldReasons.join(' · ')}` : '';
+    // (나) split 줄은 같은 런 수리 골에서 뺀다 — 수리는 (가)·(다) 줄로만.
+    const repairMustFix = (result: SupervisorJobResult): string[] => {
+      const splitTexts = new Set((taskScopes.get(result.taskId) ?? []).filter((j) => j.scope === 'split').map((j) => j.text));
+      return (result.reviewMustFix ?? []).filter((text) => !splitTexts.has(text));
+    };
     const repairGoals: Record<string, string> = Object.fromEntries(fresh.flatMap((result) => {
-      const goal = result.prNumber && result.reviewMustFix?.length
+      const mustFix = repairMustFix(result);
+      const goal = result.prNumber && mustFix.length
         ? authorRepairGoal({ pr: result.prNumber, category: 'review-oscillation', originalRequest: result.feature,
-          mustFix: result.reviewMustFix }) : null;
+          mustFix }) : null;
       return goal ? [[result.taskId, goal]] : [];
     }));
+    const mustFixScope = mustFixScopeDecision(oscillating, taskClasses, taskScopes);
     // A caller that declares it cannot run the authored goal (false), or one that can but has no goal for every fresh
     // oscillating task, would turn add-repair-task into a same-strategy relaunch — stop for a human instead.
     // Undefined is the pure decision (caller unknown): it names the first repair as the goal contract asks.
@@ -606,6 +700,7 @@ export function decideNextRun(input: {
       ...(action === 'stop' ? { stopReason: 'review-oscillating' as const } : {}),
       ...(mustFixClass ? { mustFix: mustFixClass } : {}),
       ...(Object.keys(mustFixByTask).length ? { mustFixByTask } : {}),
+      ...(mustFixScope ? { mustFixScope } : {}),
       oscillation: { taskIds, helper: 'review-oscillation', signature, ...(Object.keys(repairGoals).length ? { repairGoals } : {}),
         ...(action === 'add-repair-task' && held.length ? { heldTaskIds: held } : {}) },
       pendingDecision: 'attempt-care-escalation',

package/src/self-dev/run-types.ts

@@ -98,7 +98,7 @@ export interface SelfDevJobResult {
   /** Commits this child added against its own `--base`. 0 is not completion progress. */
   commitsAheadOfBase?: number;
   /** A dependency is done but its result is not on main; no child was launched. */
-  blockReason?: 'parent-unlanded';
+  blockReason?: 'parent-unlanded' | 'dependency-needs-human';
   parentPrNumber?: number;
   /** The upstream completed in a worktree without opening a PR. */
   parentNoPr?: true;
@@ -127,6 +127,10 @@ export interface SelfDevJobResult {
   oscillationRepairOf?: string;
   /** Verbatim final reviewer must-fix items for a bounded helper repair. */
   reviewMustFix?: string[];
+  /** REVIEW-MUSTFIX-CLASSIFY 범위 축 — PR 변경 파일. undefined = 안 쟀다(범위 판정은 ask-owner 로 기운다 · 생산자는 다음 조각). */
+  changedFiles?: string[];
+  /** REVIEW-MUSTFIX-CLASSIFY 범위 축 — 골 대상 경로(goal.hotPaths). undefined = 골이 선언하지 않았다. */
+  targetPaths?: string[];
   /** Whether the child review actually ran; omitted preserves legacy producers. */
   reviewed?: boolean;
   /** Why the child did not run review; omitted preserves legacy review-unobserved handling. */

package/src/self-dev/shard-plan.ts

@@ -7,6 +7,11 @@ export interface GateTestShard {
   plannedSeconds: number;
 }
 
+/** A requested shard count cannot hold the measured files; more shards may make the same plan valid. */
+export class GateShardCapacityError extends Error {
+  constructor(message: string) { super(message); this.name = 'Error'; }
+}
+
 /** Keep real child/PTY tests out of ordinary self-gate shards, within the caller's shard budget. */
 export function planSelfGateSpawnSeparatedShards(
   files: readonly string[],
@@ -19,8 +24,11 @@ export function planSelfGateSpawnSeparatedShards(
   const spawn = unique.filter(isGateSpawnLaneFile);
   const regular = unique.filter((file) => !isGateSpawnLaneFile(file));
   if (!spawn.length || !regular.length) return planGateTestShards(unique, rssMb, seconds, budgetGiB, shardCount);
-  if (shardCount < 2) throw new Error('self gate spawn lane needs at least two shards when regular and spawn tests coexist');
-  const spawnCount = Math.min(3, spawn.length, shardCount - 1);
+  if (shardCount < 2) throw new GateShardCapacityError('self gate spawn lane needs at least two shards when regular and spawn tests coexist');
+  // Three spawn bundles are the normal lane width, not a memory ceiling. A 5 GiB spawn file cannot share an 8 GiB
+  // bundle with another such file; retain lane isolation while allowing the measured plan to grow past three.
+  const neededSpawn = planGateTestShards(spawn, rssMb, seconds, budgetGiB).length;
+  const spawnCount = Math.min(spawn.length, shardCount - 1, Math.max(3, neededSpawn));
   const planned = [
     ...planGateTestShards(regular, rssMb, seconds, budgetGiB, shardCount - spawnCount),
     ...planGateTestShards(spawn, rssMb, seconds, budgetGiB, spawnCount),
@@ -65,7 +73,7 @@ export function planGateTestShards(
     if (!shard) {
       const totalRssMb = sorted.reduce((sum, candidate) => sum + rssMb.get(candidate)!, 0);
       const largestRssMb = rssMb.get(sorted[0]!)!;
-      throw new Error(`test files exceed ${shardCount} shard memory budgets (files=${unique.length} · totalRssMb=${Math.round(totalRssMb)} · largestRssMb=${Math.round(largestRssMb)} · budgetMb=${capacity} · neededShards≥${Math.ceil(totalRssMb / capacity)})`);
+      throw new GateShardCapacityError(`test files exceed ${shardCount} shard memory budgets (files=${unique.length} · totalRssMb=${Math.round(totalRssMb)} · largestRssMb=${Math.round(largestRssMb)} · budgetMb=${capacity} · neededShards≥${Math.ceil(totalRssMb / capacity)})`);
     }
     shard.files.push(file);
     shard.plannedRssMb += rss;

package/src/self-dev/shard-run.ts

@@ -1,12 +1,12 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statfsSync, statSync, writeFileSync } from 'node:fs';
+import { availableParallelism, freemem, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { debug, redactSecretText } from '../debug/log.js';
 import { prepareDeterministicChildEnvironment } from '../../scripts/lib/deterministic-env.js';
 import { withGateTestEnv } from '../../scripts/lib/gate-test-env.js';
 import { withBaselineWorktree } from '../self-implement/gate-baseline.js';
 import { aggregateGateTestShards, type GateShardAttempt, type GateShardAggregate } from './shard-aggregate.js';
-import { planFixedGateTestShards, planSelfGateSpawnSeparatedShards, type GateTestShard } from './shard-plan.js';
+import { GateShardCapacityError, planFixedGateTestShards, planSelfGateSpawnSeparatedShards, type GateTestShard } from './shard-plan.js';
 import { isGateSpawnLaneFile } from './spawn-lane-files.js';
 
 export interface ShardRunResult {
@@ -15,11 +15,16 @@ export interface ShardRunResult {
   attempts: GateShardAttempt[];
   reason?: string;
   measurementFailures?: number;
-  /** Present only for opt-in `--fixed-shard-distribution` (no RSS pre-measurement). Absent = the measured planner. */
-  distribution?: 'fixed';
+  /** The measured RSS plan needed more bundles than the requested count. */
+  expandedFrom?: number;
+  /** A fixed plan selected explicitly, or after the measured plan exceeds host expansion capacity. */
+  distribution?: 'fixed' | 'fixed-cap-fallback';
+  fallbackReason?: string;
   /** OP FU (MK #8178 shard-9) — raw evidence of every failed shard process (exit≠0 · signal · no JUnit). Observation only:
    *  the aggregate never reads it. Absent = no shard process reported failure output. */
   failureEvidence?: ShardFailureEvidence[];
+  /** Latest failed attempt's reason for each incomplete shard; copied into the gate artifact summary. */
+  unmeasuredByShard?: Record<string, string>;
 }
 
 /** What a failed shard process leaves behind so «test failure vs runner error» can be told apart after the fact. */
@@ -42,6 +47,38 @@ export interface ShardFailureEvidence extends ShardFailureOutput {
 export interface ShardRunMode {
   /** OP FU — sorted round-robin into `count` shards, zero pre-measurement runs. Default off: the measured planner. */
   fixedDistribution?: boolean;
+  /** Measured on the executing host; override only for deterministic planning tests. */
+  hostResources?: { cores: number; freeMemoryGiB: number; freeTmpGiB: number };
+}
+
+function hostResources(): ShardRunMode['hostResources'] | undefined {
+  try {
+    const tmp = statfsSync(tmpdir());
+    // Linux page cache is reclaimable. `freemem()` alone saw only ~10 GiB on a WSL host
+    // with 24 GiB MemAvailable and would incorrectly cap a two-shard plan at one.
+    let freeMemoryGiB = freemem() / (1024 ** 3);
+    if (process.platform === 'linux') {
+      const availableKiB = /^MemAvailable:\s+(\d+)\s+kB/m.exec(readFileSync('/proc/meminfo', 'utf8'))?.[1];
+      if (availableKiB) freeMemoryGiB = Number(availableKiB) / (1024 ** 2);
+    }
+    return {
+      cores: availableParallelism(),
+      freeMemoryGiB,
+      freeTmpGiB: Number(tmp.bavail) * Number(tmp.bsize) / (1024 ** 3),
+    };
+  } catch { return undefined; }
+}
+
+/** One expansion slot needs one CPU, one shard memory budget, and 1 GiB of free tmp space.
+ *  Explicitly requested shards remain the caller's choice; this only limits automatic growth. */
+export function maxAutomaticShardCount(requested: number, budgetGiB: number, resources: ShardRunMode['hostResources']): number {
+  if (!resources || !Number.isFinite(budgetGiB) || budgetGiB <= 0) return requested;
+  const limit = Math.min(
+    Math.floor(resources.cores),
+    Math.floor(resources.freeMemoryGiB / budgetGiB),
+    Math.floor(resources.freeTmpGiB),
+  );
+  return Math.max(requested, Number.isFinite(limit) ? limit : requested);
 }
 
 export type ShardProcess = (cwd: string, files: readonly string[]) => {
@@ -155,13 +192,45 @@ export function runShardedGateTests(
     }
   }
   const measurementFailures = failedMeasurements.length || undefined;
-  let shards: GateTestShard[];
+  const fixedAtHostCap = (maxCount: number, reason: string): ShardRunResult => {
+    try {
+      const fixed = planFixedGateTestShards(files, maxCount);
+      debug.log('self-dev.shard', 'host-cap-fixed-fallback', { requested: count, cap: maxCount,
+        files: new Set(files).size, reason, measurementFailures: measurementFailures ?? 0 });
+      return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree), distribution: 'fixed-cap-fallback',
+        fallbackReason: reason, ...(measurementFailures ? { measurementFailures } : {}) };
+    } catch (error) {
+      return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [],
+        reason: `host-cap fixed fallback failed: ${String(error)}; measured plan: ${reason}`,
+        ...(measurementFailures ? { measurementFailures } : {}) };
+    }
+  };
+  let shards: GateTestShard[] | undefined;
+  let plannedCount = count;
   try {
-    shards = planSelfGateSpawnSeparatedShards(files, rss, seconds, budgetGiB, count);
+    const fileCount = new Set(files).size;
+    const totalRss = [...rss.values()].reduce((sum, value) => sum + value, 0);
+    const lowerBound = Number.isFinite(budgetGiB) && budgetGiB > 0 ? Math.ceil(totalRss / (budgetGiB * 1024)) : count;
+    plannedCount = Math.max(count, Math.min(fileCount, lowerBound));
+    // The requested count may exceed the number of files. Only expansion is bounded by file count.
+    const maxCount = Math.max(count, Math.min(fileCount, maxAutomaticShardCount(count, budgetGiB, mode.hostResources ?? hostResources())));
+    if (plannedCount > maxCount) return fixedAtHostCap(maxCount, `host shard expansion cap ${maxCount} < needed ${plannedCount} (requested ${count}, measured RSS sum ${Math.round(totalRss)} MiB, budget ${budgetGiB} GiB)`);
+    for (; plannedCount <= maxCount; plannedCount++) {
+      try { shards = planSelfGateSpawnSeparatedShards(files, rss, seconds, budgetGiB, plannedCount); break; }
+      catch (error) {
+        if (!(error instanceof GateShardCapacityError)) throw error;
+        if (plannedCount === maxCount) return fixedAtHostCap(maxCount, `host shard expansion cap ${maxCount} < needed ≥${maxCount + 1} (requested ${count}, ${error.message})`);
+      }
+    }
   } catch (error) {
     return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error), ...(measurementFailures ? { measurementFailures } : {}) };
   }
-  return { ...runPlannedShards(cwd, shards, baseRef, run, baselineWorktree), ...(measurementFailures ? { measurementFailures } : {}) };
+  if (!shards) return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: 'shard planning produced no result' };
+  if (plannedCount > count) debug.log('self-dev.shard', 'plan-expanded', {
+    requested: count, planned: shards.length, files: new Set(files).size, budgetGiB,
+    measurementFailures: measurementFailures ?? 0,
+  });
+  return { ...runPlannedShards(cwd, shards, baseRef, run, baselineWorktree), ...(plannedCount > count ? { expandedFrom: count } : {}), ...(measurementFailures ? { measurementFailures } : {}) };
 }
 
 /** Shared by the measured and the fixed planner: current + baseline per shard, one retry round, one aggregate. */
@@ -214,8 +283,32 @@ function runPlannedShards(
     return aggregateGateTestShards(shards, attempts);
   });
   const evidence = failureEvidence.length ? { failureEvidence } : {};
-  if ('retryShardIds' in baseline) return { aggregate: baseline, shards, attempts, ...evidence };
-  return { aggregate: { status: 'unmeasured', retryShardIds: shards.map((shard) => shard.id) }, shards, attempts, reason: baseline.log, ...evidence };
+  if ('retryShardIds' in baseline) return {
+    aggregate: baseline, shards, attempts, ...evidence,
+    ...(baseline.retryShardIds.length ? { unmeasuredByShard: incompleteShardReasons(baseline.retryShardIds, attempts) } : {}),
+  };
+  const retryShardIds = shards.map((shard) => shard.id);
+  return {
+    aggregate: { status: 'unmeasured', retryShardIds }, shards, attempts, reason: baseline.log, ...evidence,
+    unmeasuredByShard: Object.fromEntries(retryShardIds.map((id) => [id, `baseline worktree: ${redactSecretText(baseline.log).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').slice(0, 500)}`])),
+  };
+}
+
+function incompleteShardReasons(shardIds: readonly string[], attempts: readonly GateShardAttempt[]): Record<string, string> {
+  return Object.fromEntries(shardIds.map((id) => {
+    const latest = attempts.filter((attempt) => attempt.shardId === id).at(-1);
+    if (!latest) return [id, 'no shard attempt recorded'];
+    const side = (name: string, rc: number | null, signal: string | null | undefined, junit: string | undefined, diagnostic: string | undefined): string => {
+      const safeDiagnostic = diagnostic ? redactSecretText(diagnostic).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').slice(0, 500) : undefined;
+      return `${name}: exit ${rc ?? 'unavailable'}, signal ${signal ?? 'none'}, JUnit ${junit === undefined ? 'missing' : 'present'}`
+        + (safeDiagnostic ? `; ${safeDiagnostic}` : '');
+    };
+    const statuses = [
+      side('current', latest.currentExitCode, latest.currentSignal, latest.currentJUnit, latest.currentDiagnostic),
+      ...(latest.baselineFiles?.length === 0 ? [] : [side('baseline', latest.baselineExitCode, latest.baselineSignal, latest.baselineJUnit, latest.baselineDiagnostic)]),
+    ];
+    return [id, `${statuses.join(' · ')} · aggregate rejected (incomplete, malformed JUnit, or exit/JUnit mismatch)`];
+  }));
 }
 
 export function selfGateShardTimeoutMs(files: readonly string[]): number {