elanous 0.2.32 → 0.2.35

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

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { debug } from '../debug/log.js';
+import type { FrontNodeId } from './graph-front-nodes.js';
+import type { PipelineNodeId } from '../self-implement/pipeline-shape.js';
 import { GRAPH_SPECS, GRAPH_TEMPLATES, GRAPH_TEMPLATES_SOURCE, pipelineNodeEntryPayload, templateForGoalType, type GraphTemplate } from '../self-implement/graph-templates.js';
 import type { GoalType } from '../self-implement/goal-author.js';
 
@@ -37,11 +39,14 @@ export const JOURNEY_NODE_IDS = [
   'salvage',
   'heal',
   'next-move',
+  'decision-card',
   'ready',
   'pr-head-checkout',
   'stopped',
 ] as const;
 export type JourneyNodeId = typeof JOURNEY_NODE_IDS[number];
+/** Existing author/front and self-implement pipeline nodes may use the same observation helpers. */
+export type JourneyObservationNodeId = JourneyNodeId | FrontNodeId | PipelineNodeId;
 
 export const JOURNEY_KEY_ENV = 'ELANOUS_JOURNEY_KEY';
 const QUEUE_LAUNCH_ENV = 'ELANOUS_HARNESS_QUEUE_LAUNCH';
@@ -81,7 +86,7 @@ export interface JourneyObservation {
   readonly data?: Readonly<Record<string, unknown>>;
 }
 
-function emit(entry: boolean, node: JourneyNodeId, o: JourneyObservation): void {
+function emit(entry: boolean, node: JourneyObservationNodeId, o: JourneyObservation): void {
   try {
     const template = journeyTemplate(node, o.goalType);
     const runId = o.runId ?? process.env[RUN_ID_ENV]?.trim();
@@ -104,14 +109,14 @@ function emit(entry: boolean, node: JourneyNodeId, o: JourneyObservation): void
 }
 
 /** 노드 진입. */
-export function enterJourneyNode(node: JourneyNodeId, o: JourneyObservation): void {
+export function enterJourneyNode(node: JourneyObservationNodeId, o: JourneyObservation): void {
   emit(true, node, o);
 }
 
 /** 노드 출구 — `outcome` 이 그 노드에서 나간 간선의 라벨(YAML `map` 키)이다.
  *  ⭐ 그 라벨이 선언에서 종결 노드 `stopped` 로 가면 `stopped` 진입도 남긴다 — 거절·포기 런이 «선언된 종결점»에서 끝난다.
  *  `outcome: 'error'` = 노드 안 작업이 예외를 던졌다(예외는 호출자에게 그대로 간다). */
-export function exitJourneyNode(node: JourneyNodeId, o: JourneyObservation & { readonly outcome: string }): void {
+export function exitJourneyNode(node: JourneyObservationNodeId, o: JourneyObservation & { readonly outcome: string }): void {
   emit(false, node, o);
   if (node !== 'stopped' && journeyEdgeTarget(node, o.outcome) === 'stopped') {
     const { outcome: _outcome, ...rest } = o;
@@ -130,7 +135,7 @@ export function journeyEdgeTarget(from: string, label: string): string | undefin
 }
 
 /** 노드 안 작업을 감싼다 — 예외면 출구 `error` 를 남기고 다시 던진다(진입 뒤 출구가 빠지지 않게). */
-export function withJourneyNode<T>(node: JourneyNodeId, o: JourneyObservation, work: () => Promise<T>): Promise<T> {
+export function withJourneyNode<T>(node: JourneyObservationNodeId, o: JourneyObservation, work: () => Promise<T>): Promise<T> {
   const onError = (error: unknown): void => {
     exitJourneyNode(node, { ...o, outcome: 'error', data: { ...o.data, error: error instanceof Error ? error.message : String(error) } });
   };
@@ -144,7 +149,7 @@ export function withJourneyNode<T>(node: JourneyNodeId, o: JourneyObservation, w
 }
 
 /** 동기 판. */
-export function withJourneyNodeSync<T>(node: JourneyNodeId, o: JourneyObservation, work: () => T): T {
+export function withJourneyNodeSync<T>(node: JourneyObservationNodeId, o: JourneyObservation, work: () => T): T {
   try { return work(); }
   catch (error) {
     exitJourneyNode(node, { ...o, outcome: 'error', data: { ...o.data, error: error instanceof Error ? error.message : String(error) } });
@@ -153,7 +158,7 @@ export function withJourneyNodeSync<T>(node: JourneyNodeId, o: JourneyObservatio
 }
 
 /** 진입·출구를 한 번에 — 판정만 하는 노드(대기 없는 관문)용. */
-export function passJourneyNode(node: JourneyNodeId, o: JourneyObservation & { readonly outcome: string }): void {
+export function passJourneyNode(node: JourneyObservationNodeId, o: JourneyObservation & { readonly outcome: string }): void {
   enterJourneyNode(node, o);
   exitJourneyNode(node, o);
 }

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/harness-run-cli.ts

@@ -1,28 +1,16 @@
 import { buildHarnessRunDevSpec, runDevPipeline, type DevHarnessDispatchArgs, type DevPipelineDeps } from './dev-pipeline.js';
 import type { SurfaceUxSource } from '../agent/surface-ux/build.js';
 import { debug } from '../debug/log.js';
-import { CLI_HARNESS_RUN_ENTRANCE, describeEntranceCommand, retiredEntranceNotice } from './entrance-registry.js';
+import { CLI_HARNESS_RUN_ENTRANCE, retiredEntranceNotice } from './entrance-registry.js';
+import { HARNESS_RUN_REPLACEMENT } from './cli-help-text.js';
+export { HARNESS_RUN_REPLACEMENT, HARNESS_RUN_DEPRECATION_HELP } from './cli-help-text.js';
 
 /** `elanous logs --category`로 레거시 입구의 제거 안전시점을 조회하는 브레드크럼. */
 export const HARNESS_RUN_DEPRECATION_LOG_CATEGORY = 'harness-cli.deprecated';
-export const HARNESS_RUN_REPLACEMENT = 'elanous harness say <objective>';
 /** 실행 «중»에 사람에게 내는 한 줄. ⛔ `--help` 용은 아래 HARNESS_RUN_DEPRECATION_HELP 다 —
  *  그쪽은 레지스트리가 은퇴 표시와 «갈 곳»을 이미 붙이므로 여기서 그것을 되풀이하지 않는다. */
 export const HARNESS_RUN_DEPRECATION_NOTICE = `ℹ️  \`elanous harness run\`은 deprecated 입구입니다 — \`${HARNESS_RUN_REPLACEMENT}\`로 이행하세요.`;
 
-/** `--help` 머리에 붙는 은퇴 표시.
- *
- *  ⛔⭐ **문면을 «손으로 짓지 않는다»** — 레지스트리가 낸다(RFC-one-door-many-entrances P2).
- *  📏 2026-08-20 실측: 은퇴로 «선언»된 입구 셋 중 `--help` 가 그 사실을 말한 것은 하나뿐이었고,
- *  ***그 하나(여기)조차 문면을 레지스트리와 «따로» 들고 있었다.***
- *  ⇒ 🔑 선언과 표면이 «두 곳»에 살면 한쪽만 고쳐지고 다른 쪽이 조용히 늙는다.
- *  ⚠️ 상수 «이름»은 유지한다 — 시험과 index.ts 가 이 이름으로 읽는다(뜻이 좁아지지 않는다). */
-export const HARNESS_RUN_DEPRECATION_HELP = describeEntranceCommand(
-  CLI_HARNESS_RUN_ENTRANCE,
-  HARNESS_RUN_REPLACEMENT,
-  '이 입구는 더 이상 실행되지 않습니다.',
-).trimEnd();
-
 /** ⭐ 진행 릴레이를 «단 곳» — 하니스 시퀀서가 스테이지마다 내는 progress 를 CLI 부모 stdout 까지 잇는다.
  *
  *  ⛔ **왜 `ctx` 가 아니라 `deps.uxSource` 인가**: `dispatchRunDevHarness` 의 detached 가드가

package/src/self-dev/orchestrate-cli-text.ts

@@ -0,0 +1,10 @@
+/** Shared, dependency-free text rules for both orchestrate CLI entrances. */
+export function splitOrchestrateGoalTexts(parts: readonly string[]): string[] {
+  const joined = parts.join(' ');
+  return (joined.includes(';;') ? joined.split(';;') : parts).map((goal) => goal.trim()).filter(Boolean);
+}
+
+export function normalizeOrchestrateRequest(input: readonly string[] | string): string {
+  const joined = typeof input === 'string' ? input : input.join(' ');
+  return joined.replace(/;;/g, ' ').trim();
+}

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/review-provider-fallback.ts

@@ -107,6 +107,36 @@ export function parseTeamclaudeBaseUrl(stdout: string): string | undefined {
   return match?.[1];
 }
 
+export interface TeamclaudeReviewRoute {
+  /** Present only when teamclaude printed its proxy base URL: the cct ACP spawn (billing scrub ⊕ base-url). */
+  spawn?: ReturnType<typeof subscriptionReviewerSpawn>;
+  reason: 'teamclaude-base-url' | 'teamclaude-no-base-url' | 'teamclaude-unavailable';
+  exit?: number | null;
+}
+
+/**
+ * ACP-REVIEW-VIA-TEAMCLAUDE (0.2.35): the explicit `--acp-backend claude` review reuses the cct route of the
+ * subscription lane — `teamclaude env --no-mitm` → base URL → `subscriptionReviewerSpawn` — without the quota gate
+ * (an explicit flag is the operator's choice). teamclaude missing or silent = no spawn; the caller keeps its prior path.
+ */
+export function resolveTeamclaudeReviewRoute(
+  env: NodeJS.ProcessEnv = process.env,
+  runStatus: NonNullable<SubscriptionReviewerDeps['runStatus']> = (command, args, cleanEnv) =>
+    spawnSync(command, args, { env: { ...cleanEnv, NODE_ENV: process.env.NODE_ENV }, encoding: 'utf8', timeout: 5_000 }),
+): TeamclaudeReviewRoute {
+  const spec: SubscriptionReviewerSpec = { provider: 'claude-acp', executor: 'cct' };
+  try {
+    const proxy = runStatus('teamclaude', ['env', '--no-mitm'], subscriptionReviewerSpawn(spec, env).env);
+    // Bun reports a missing binary as `status: undefined` (Node: null) — both mean «no teamclaude here».
+    if (proxy.status == null) return { reason: 'teamclaude-unavailable' };
+    const baseUrl = proxy.status === 0 ? parseTeamclaudeBaseUrl(String(proxy.stdout ?? '')) : undefined;
+    if (!baseUrl) return { reason: 'teamclaude-no-base-url', exit: proxy.status };
+    return { spawn: subscriptionReviewerSpawn(spec, env, baseUrl), reason: 'teamclaude-base-url' };
+  } catch {
+    return { reason: 'teamclaude-unavailable' };
+  }
+}
+
 /** Guard the ACP review before spawning. An unmeasured quota never authorizes subscription use. */
 export function subscriptionReviewerAvailability(
   spec: SubscriptionReviewerSpec,
@@ -291,7 +321,7 @@ export interface ReviewFallbackObservation {
 export async function runReviewWithFallback(
   attempts: readonly ReviewProviderAttempt[],
   call: (attempt: ReviewProviderAttempt, observeResolvedProvider: (provider?: string) => void) => Promise<string>,
-  observe: (event: 'attempt' | 'resolved' | 'fallback' | 'exhausted', data: ReviewFallbackObservation) => void = () => {},
+  observe: (event: 'attempt' | 'resolved' | 'completed' | 'fallback' | 'exhausted', data: ReviewFallbackObservation) => void = () => {},
 ): Promise<{ text: string; used: ReviewProviderAttempt; attemptIndex: number }> {
   if (attempts.length === 0) throw new Error('review fallback: no attempts configured');
   let lastError: unknown;
@@ -318,6 +348,10 @@ export async function runReviewWithFallback(
       if (resolvedProvider) {
         try { observe('resolved', { ...base, resolvedProvider }); } catch { /* fail-soft */ }
       }
+      // Provider calls are attempts; only a non-empty artifact completes a logical review round.
+      if (text.trim()) {
+        try { observe('completed', { ...base, ...(resolvedProvider ? { resolvedProvider } : {}) }); } catch { /* fail-soft */ }
+      }
       return { text, used: attempt, attemptIndex: i };
     } catch (error) {
       lastError = error;

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/self-orchestrate-runtime.ts

@@ -329,17 +329,7 @@ type OrchestrateRunIdentityResolver = (input: { explicit?: string; inherited?: s
 type OrchestrateResumeDisposition = 'skip' | 'rerun' | 'rerun-duplicate-risk';
 type OrchestrateResumeDispositionClassifier<T> = (result: T) => OrchestrateResumeDisposition;
 
-/** `harness orchestrate` 와 `self orchestrate` 가 공유하는 `;;` goal 분리 규칙. */
-export function splitOrchestrateGoalTexts(parts: readonly string[]): string[] {
-  const joined = parts.join(' ');
-  return (joined.includes(';;') ? joined.split(';;') : parts).map((goal) => goal.trim()).filter(Boolean);
-}
-
-/** `harness orchestrate` 와 `self orchestrate` 가 공유하는 `;;` 요청 문자열 결합 규칙. */
-export function normalizeOrchestrateRequest(input: readonly string[] | string): string {
-  const joined = typeof input === 'string' ? input : input.join(' ');
-  return joined.replace(/;;/g, ' ').trim();
-}
+export { splitOrchestrateGoalTexts, normalizeOrchestrateRequest } from './orchestrate-cli-text.js';
 
 /** `harness orchestrate` 와 `self orchestrate` 가 공유하는 분해 준비 인자 조립 규칙. */
 export function buildOrchestrateDecomposePrepareArgs<