elanous 0.2.34 → 0.2.36

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

@@ -5,6 +5,7 @@ export type WarmPoolTier = 'lite' | 'standard';
 const STANDARD_HOST_MAX: Readonly<Record<string, number>> = {
   node-b: 16,
   node-c: 4,
+  'elangram-wsl': 5,
   'host-e-wsl': 5,
 };
 

package/src/self-implement/pwa-import-graph.ts

@@ -29,7 +29,7 @@ function sourceFiles(cwd: string): string[] {
 const IMPORT_SPECIFIER = /\b(?:import|export)\s+(?:[^;'"]*?\s+from\s*)?['"](\.[^'"]+)['"]|\bimport\s*\(\s*['"](\.[^'"]+)['"]\s*\)/g;
 
 /** Repo-relative file candidates a relative import specifier (already joined to its importer's directory) can resolve to. */
-function importCandidates(base: string): string[] {
+export function importCandidates(base: string): string[] {
   return /\.js$/.test(base)
     // A real .js file wins over a same-named .ts source (the actual resolution order).
     ? [base, base.replace(/\.js$/, '.ts'), base.replace(/\.js$/, '.tsx'), `${base.slice(0, -3)}/index.ts`, `${base.slice(0, -3)}/index.tsx`, `${base.slice(0, -3)}/index.js`]

package/src/self-implement/rework-budget-judgment.ts

@@ -1,4 +1,4 @@
-import { executeClassifyNode } from '../workflow-runtime/nodes/classify.js';
+import { runGraphClassifyNode } from '../graph-runner/runner.js';
 import { buildPremiseCard, type PremiseReviewCard, type PremiseReviewInput } from './premise-review.js';
 import { SUPERVISION_REWORK_SOURCES, type SupervisionReworkSource } from './supervision-vocabulary.js';
 import type { ClassifyNode, JudgmentContext, JudgmentResult, NodeExecContext, WorkflowDefinition, WorkflowDeps } from '../workflow-runtime/types.js';
@@ -155,13 +155,10 @@ export function createReworkBudgetJudgment(callLLM: WorkflowDeps['callLLM'], opt
     };
     let modelReasoning = '';
     let premiseReview: PremiseReviewCard | undefined;
-    const result = await executeClassifyNode(node, execContext, {
-      callLLM: async (args) => {
-        modelReasoning = await callLLM(args);
-        return modelReasoning;
-      },
-      runBash: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
-    });
+    const result = await runGraphClassifyNode(node, execContext, async (args) => {
+      modelReasoning = await callLLM(args);
+      return modelReasoning;
+    }, { caller: 'rework-budget-judgment' });
     const evidence = (): ReworkBudgetEvidence => ({
       observations,
       modelReasoning,

package/src/self-implement/rework-policy.ts

@@ -316,6 +316,36 @@ export function parseReworkBudgetDecision(response: string | undefined): ReworkB
   return verdict && reason ? { verdict, reason } : undefined;
 }
 
+/** TDD-SUPERVISOR-IMPOSSIBLE-EVIDENCE — «구조적으로 불가능한 증거 요구» 표지.
+ *  base 에 없는 신규 파일·모듈의 시험은 base 에서 실패할 수 없다(missing-at-base). 그 «적색 증인 없음 · unproved» 지적이
+ *  라운드마다 반복돼도 구현이 고칠 수 있는 결함이 아니다 — 10-22 #30254 가 이 반복으로 UNCONVERGEABLE 에 버려졌다. */
+const IMPOSSIBLE_EVIDENCE_MARKERS: readonly { readonly id: string; readonly re: RegExp }[] = [
+  { id: 'missing-at-base', re: /missing-at-base/i },
+  { id: 'changed-test-unproved', re: /\[changed-test-evidence\][^\n]*verdict=unproved/i },
+  { id: 'base-fail-zero', re: /base-fail=0\/[1-9]/i },
+  { id: 'base-absent-new-module', re: /(베이스|base)\s*에\s*(없는|부재)[^\n]{0,40}(신규|새)[^\n]{0,20}(모듈|파일)|(신규|새)\s*(모듈|파일)[^\n]{0,40}(베이스|base)\s*에\s*(없|부재)/i },
+  { id: 'no-red-witness', re: /적색\s*증인\s*(없|부재)|red witness/i },
+];
+
+export interface ImpossibleEvidenceReclassification {
+  readonly response: string;
+  readonly applied: boolean;
+  readonly markers: readonly string[];
+}
+
+/** 감독이 UNCONVERGEABLE 을 냈는데 현재 지적이 «불가능한 증거 요구» 표지를 담으면 CONTRACT-CONFLICT 로 바꾼다.
+ *  다음 라운드는 그 요구가 불가능하다는 계획 수정(이유)을 들고 계속한다(런을 버리지 않는다). 다른 판정·표지 없는 지적은 그대로. */
+export function reclassifyImpossibleEvidence(response: string, note: string): ImpossibleEvidenceReclassification {
+  const decision = parseReworkBudgetDecision(response);
+  if (decision?.verdict !== 'UNCONVERGEABLE') return { response, applied: false, markers: [] };
+  const markers = IMPOSSIBLE_EVIDENCE_MARKERS.filter(({ re }) => re.test(note)).map(({ id }) => id);
+  if (markers.length === 0) return { response, applied: false, markers };
+  const lines = response.split(/\r?\n/);
+  lines[0] = 'BUDGET: CONTRACT-CONFLICT';
+  lines[1] = `REASON: 구조적으로 불가능한 증거 요구(${markers.join('·')}) — base 에 없는 신규 파일은 base 에서 실패할 수 없으니 같은 지적 반복으로 세지 않는다 · 감독 원판정: ${decision.reason}`;
+  return { response: lines.join('\n'), applied: true, markers };
+}
+
 /** Optional structured contract-conflict payload. Missing or partial fields deliberately remain legacy-compatible. */
 export function parseContractConflictRelaxation(response: string | undefined): ContractConflictRelaxation | undefined {
   const fields = new Map<string, string[]>();

package/src/self-implement/run-ledger.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
 import { refuseProductionLedgerWriteInTest } from '../harness/ledger-write-guard.js';
 import { tracedPathReferences, verbatimOriginalAsk } from './goal-author.js';
 import { parseAskTargetPathHintsResult } from '../self-dev/launch-preflight-text.js';
@@ -408,6 +409,49 @@ export function describeFederatedMissingRunLedger(runId: string, options: Federa
   };
 }
 
+/** 런 원장 옆 `.graph.yaml` 경로 — 원장 경로 계약(runLedgerPath)에서 파생한다. */
+export function runGraphVariantPath(runId: string, dir = runLedgerDir()): string {
+  return `${runLedgerPath(runId, dir)}.graph.yaml`;
+}
+
+/** 최초 graph variant 선택의 원장 옆 재조회 계약 — 같은 runId·파일이면 같은 id·선택 이유가 돌아온다. */
+export interface RunGraphVariantSelection {
+  /** createGraphVariant 가 골 종류·대상 경로 수에서 유도한 최초 variant id. */
+  readonly variantId: string;
+  /** 그 variant가 최초로 선택된 근거(종류·경로 수 기반) — 저장·재조회가 같은 문자열. */
+  readonly reason: string;
+}
+
+/** 런 원장 옆 .graph.yaml 을 처음 한 번 쓰고 저장 경로를 돌려준다 — 이미 있으면 덮쓰지 않는다(flag wx). */
+export function saveRunGraphVariant(runId: string, yamlText: string, dir = runLedgerDir()): string {
+  mkdirSync(dir, { recursive: true });
+  const path = runGraphVariantPath(runId, dir);
+  writeFileSync(path, yamlText, { flag: 'wx' });
+  return path;
+}
+
+/** 런 원장 옆 .graph.yaml 에서 최초 graph variant 선택(id·이유)을 재조회한다 — 파일·선택이 없으면 null. */
+export function loadRunGraphVariant(runId: string, dir = runLedgerDir()): RunGraphVariantSelection | null {
+  const path = runGraphVariantPath(runId, dir);
+  let text: string;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw new Error(`unable to read run graph variant ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(text);
+  } catch (error) {
+    throw new Error(`invalid run graph variant YAML at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const record = parsed as { variant_id?: unknown; reason?: unknown };
+  if (typeof record.variant_id !== 'string' || typeof record.reason !== 'string') return null;
+  return { variantId: record.variant_id, reason: record.reason };
+}
+
 /** Append one observer event. Callers own fail-soft handling. */
 export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()): void {
   if (refuseProductionLedgerWriteInTest(dir, 'run-ledger')) return;
@@ -423,6 +467,70 @@ export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()
   });
 }
 
+/** Caller decision inside `appendRunLedgerEntryChecked`: either `append` exactly one entry, or skip with `result`. */
+export type RunLedgerCheckedAppendDecision<T> =
+  | { append: false; result: T }
+  | { append: true; entry: RunLedgerEntry };
+
+export interface RunLedgerCheckedAppendOutcome<T> {
+  appended: boolean;
+  result: T | null;
+  /** Named reason when `appended:false` was produced without calling the decision — e.g. a test-universe refusal of an operating-ledger write. */
+  refusal: 'ledger-write-refused' | null;
+}
+
+/**
+ * Thrown (typed, with the stable `runId-mismatch` reason) when a checked-append
+ * decision returns an entry whose `runId` differs from the locked `runId`. Callers
+ * classify identity violations from `error.reason === 'runId-mismatch'` instead of
+ * parsing message substrings.
+ */
+export class RunLedgerCheckedAppendRunIdMismatchError extends Error {
+  readonly reason = 'runId-mismatch' as const;
+  constructor(readonly decisionRunId: string, readonly lockedRunId: string) {
+    super(
+      `runId-mismatch: appendRunLedgerEntryChecked: decision entry runId ${JSON.stringify(decisionRunId)} does not match locked runId ${JSON.stringify(lockedRunId)}`,
+    );
+    this.name = 'RunLedgerCheckedAppendRunIdMismatchError';
+  }
+}
+
+/**
+ * Atomically decide-and-append under a single per-run lock: the caller-supplied
+ * decision runs on the loaded ledger inside `withRunLedgerLock`, and at most one
+ * append is written by the same lock. Never calls `appendRunLedgerEntry` inside
+ * the lock (that function acquires the same lock itself, so nesting it would
+ * time out). Preserves the archived-ledger restore contract exactly like
+ * `appendRunLedgerEntry`. A missing ledger yields `null` entries to the
+ * decision (which may throw); a corrupt ledger throws before any append.
+ * Test-universe writes are refused before any lock directory or ledger path is created.
+ * The caller-supplied entry must carry the same `runId` as the acquired lock — on mismatch,
+ * the lock is released and a runId mismatch error is thrown before any append or archive restore.
+ */
+export function appendRunLedgerEntryChecked<T>(
+  runId: string,
+  decide: (entries: RunLedgerEntry[] | null) => RunLedgerCheckedAppendDecision<T>,
+  dir = runLedgerDir(),
+): RunLedgerCheckedAppendOutcome<T> {
+  if (refuseProductionLedgerWriteInTest(dir, 'run-ledger')) return { appended: false, result: null, refusal: 'ledger-write-refused' as const };
+  return withRunLedgerLock(dir, runId, () => {
+    const decision = decide(loadRunLedger(runId, dir));
+    if (!decision.append) return { appended: false, result: decision.result, refusal: null };
+    const entry = decision.entry;
+    if (entry.runId !== runId) {
+      throw new RunLedgerCheckedAppendRunIdMismatchError(entry.runId, runId);
+    }
+    const live = runLedgerPath(entry.runId, dir);
+    const devProject = process.env.ELANOUS_DEV_PROJECT;
+    const row = entry.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
+      ? { ...entry, devProject }
+      : entry;
+    const line = `${JSON.stringify(row)}\n`;
+    if (!restoreArchivedRunLedger(dir, entry.runId, line)) appendFileSync(live, line, 'utf8');
+    return { appended: true, result: null, refusal: null };
+  });
+}
+
 export interface HumanStopRunLedgerOptions {
   stoppedBy: string;
   stoppedAt?: string;

package/src/self-implement/run-stop.ts

@@ -23,6 +23,8 @@ export type RunStopClass = typeof RUN_STOP_CLASSES[number];
 /** 런 원장 `event='stop'` 줄의 `data` 모양(STOP-AUTOHEAL 이 소비한다). */
 export interface RunStopRecord {
   class: RunStopClass;
+  /** Last known stop site; absent in older ledger rows. */
+  site?: string;
   /** 한 줄 · ≤120자 · 결정 라벨(원 로그 꼬리 금지). */
   cause: string;
   /** 근거 위치 — PR URL · `run-ledger:<runId>:<event>` · 파일 경로. */
@@ -31,6 +33,8 @@ export interface RunStopRecord {
   nextMove: string;
   /** Facts from the complete child JSON, lifted before the Pod stdout tail is shortened. */
   childEvidence?: PodChildEvidence;
+  /** Exact structured Pod error code, when the host received one. */
+  terminationReason?: 'pod-job-failed';
 }
 
 export const RUN_STOP_EVENT = 'stop';
@@ -48,6 +52,7 @@ export interface RunStopInput {
   /** 관측용 — 어느 자리가 불렀나(merge-hold · implement-aborted · draft-pr-open-failed · pod-exit · launch-failed). */
   site?: string;
   childEvidence?: PodChildEvidence;
+  terminationReason?: 'pod-job-failed';
 }
 
 export function isRunStopClass(value: unknown): value is RunStopClass {
@@ -100,10 +105,12 @@ export function forgetRunStop(runId: string): void {
 export function recordRunStop(input: RunStopInput, write: RunLedgerWriter = appendRunLedgerEntry): RunLedgerEntry {
   const record: RunStopRecord = {
     class: isRunStopClass(input.class) ? input.class : 'unclassified',
+    ...(input.site ? { site: input.site } : {}),
     cause: boundRunStopCause(input.cause),
     evidenceRef: input.evidenceRef,
     nextMove: input.nextMove,
     ...(input.childEvidence ? { childEvidence: input.childEvidence } : {}),
+    ...(input.terminationReason ? { terminationReason: input.terminationReason } : {}),
   };
   const entry: RunLedgerEntry = {
     timestamp: new Date().toISOString(), runId: input.runId, event: RUN_STOP_EVENT,
@@ -126,5 +133,7 @@ export function readRunStopRecord(entry: RunLedgerEntry): RunStopRecord | undefi
   const data = entry.data as Partial<RunStopRecord>;
   if (typeof data.cause !== 'string' || typeof data.evidenceRef !== 'string' || typeof data.nextMove !== 'string') return undefined;
   return { class: isRunStopClass(data.class) ? data.class : 'unclassified', cause: data.cause, evidenceRef: data.evidenceRef, nextMove: data.nextMove,
-    ...(data.childEvidence ? { childEvidence: data.childEvidence } : {}) };
+    ...(typeof data.site === 'string' ? { site: data.site } : {}),
+    ...(data.childEvidence ? { childEvidence: data.childEvidence } : {}),
+    ...(data.terminationReason === 'pod-job-failed' ? { terminationReason: data.terminationReason } : {}) };
 }

package/src/self-implement/run-ttl.ts

@@ -5,13 +5,15 @@
  * Past `tools.selfImplement.runTtlHours` (default 24) since its last commit, the sweep makes one pre-emptive move:
  *   · live owning run → one resync memo in its control inbox (same path as SIBLING-RESYNC #24893/#24899),
  *                       at most once per (PR, head sha) — a rebase moves the head and re-arms it
- *   · no live run     → the registered `elanous:needs-rebase` label, once (QUIET-PR-COMMENTS: never a comment);
- *                       when `requestRegate` is supplied, at most one of those stale PRs is also selected
- *                       for a re-gate request (shadow: would-regate observation only; live: one call)
+ *   · no live run     → when `requestRegate` is supplied, at most one of those stale PRs is selected for a
+ *                       re-gate request (shadow: would-regate observation only; live: one call), and the
+ *                       registered `elanous:needs-rebase` label otherwise — once (QUIET-PR-COMMENTS: never a comment)
  *
  * Mode `tools.selfImplement.runTtl.mode`: `shadow` (default) only logs what it would do; `live` writes.
  * Cost bound: a PR opened inside the TTL is still inside its own time-to-landing and is never fetched
- * (`freshByCreation`), already-marked PRs without a live run are skipped before any fetch, at most `maxFetch` last-commit lookups per sweep with `concurrency` in flight, and at most `cap` actions.
+ * (`freshByCreation`), already-marked PRs without a live run are skipped before any fetch, at most `maxFetch`
+ * last-commit lookups per sweep with `concurrency` in flight, and at most `cap` actions — memo, marker and
+ * re-gate request all draw from that one budget, so a sweep never performs more than `cap` side effects.
  *
  * Pure core: every side effect is an injected adapter so tests never touch GitHub or the inbox.
  */
@@ -208,6 +210,12 @@ export async function runRunTtlSweep(input: {
   stalePrs.sort((a, b) => b.ageMs - a.ageMs || a.pr.number - b.pr.number);
   let actions = 0;
   let selectedRegate = false;
+  // One budget for the whole sweep: a memo, a marker and a re-gate request each spend one unit.
+  const spend = (): boolean => {
+    if (actions >= cap) return false;
+    actions += 1;
+    return true;
+  };
   for (const { pr, target, ageMs } of stalePrs) {
     const ageHours = ageMs / 3_600_000;
     const key = `${pr.number}:${pr.headSha}`;
@@ -220,10 +228,10 @@ export async function runRunTtlSweep(input: {
         continue;
       }
       if (already) { alreadyMemoed.push(pr.number); continue; }
-    }
-    if (!target.alive && pr.labels.includes(RUN_TTL_MARKER_LABEL)) { alreadyMarked.push(pr.number); continue; }
-    if (actions >= cap) { skippedOverCap.push(pr.number); continue; }
-    actions += 1;
+    } else if (pr.labels.includes(RUN_TTL_MARKER_LABEL)) { alreadyMarked.push(pr.number); continue; }
+    // The move this PR makes — memo, re-gate, or marker — takes the budget slot up front, so a sweep
+    // never emits more than `cap` side effects no matter how many of them a single PR would attract.
+    if (!spend()) { skippedOverCap.push(pr.number); continue; }
     if (target.alive) {
       if (mode === 'shadow') {
         memo.push(pr.number);
@@ -248,15 +256,31 @@ export async function runRunTtlSweep(input: {
       }
     }
     const reason = target.alive ? 'memo-failed' : target.reason;
-    const canRegate = Boolean(input.requestRegate) && !target.alive && !selectedRegate;
-    if (mode === 'shadow') {
-      label.push(pr.number);
-      emit('would-label', { pr: pr.number, label: RUN_TTL_MARKER_LABEL, reason, ageHours: Math.floor(ageHours) });
-      if (canRegate) {
-        selectedRegate = true;
+    // A re-gate request is the stronger move and spends the same budget as the marker, so it goes
+    // first: at `cap` 1 a sweep either re-gates (no marker) or — with no adapter — only marks.
+    if (Boolean(input.requestRegate) && !target.alive && !selectedRegate) {
+      selectedRegate = true;
+      if (mode === 'shadow') {
         regate.push(pr.number);
         emit('would-regate', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
+      } else {
+        try {
+          await input.requestRegate!(pr);
+          regate.push(pr.number);
+          emit('regate-requested', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
+        } catch (error) {
+          emit('regate-failed', { pr: pr.number, error: String(error) });
+        }
+      }
+      // The marker that used to ride along must buy its own slot — at `cap` 1 there is none left.
+      if (!spend()) {
+        emit('label-deferred-cap', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
+        continue;
       }
+    }
+    if (mode === 'shadow') {
+      label.push(pr.number);
+      emit('would-label', { pr: pr.number, label: RUN_TTL_MARKER_LABEL, reason, ageHours: Math.floor(ageHours) });
       continue;
     }
     try {
@@ -267,16 +291,6 @@ export async function runRunTtlSweep(input: {
       failed.push(pr.number);
       emit('label-failed', { pr: pr.number, error: String(error) });
     }
-    if (canRegate) {
-      selectedRegate = true;
-      try {
-        await input.requestRegate!(pr);
-        regate.push(pr.number);
-        emit('regate-requested', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
-      } catch (error) {
-        emit('regate-failed', { pr: pr.number, error: String(error) });
-      }
-    }
   }
   return summary(result());
 }

package/src/self-implement/running-runs.ts

@@ -424,6 +424,34 @@ export function assessRunningRuns(
   return { ...(partial ? { completeness: 'partial' as const, unreadable, count: { count: null, lowerBound: counts.running + counts['probable-running'], unreadable } } : {}), entries, counts, total, countedStatuses, quantities: quantitySummary({ entries, counts, total, countedStatuses, observation }), observation, lingeringLaunchParents: { observation: 'indeterminate' }, ledger: { ledgerDirectories: [], unreadableLedgerCount: ledgerObservation.unreadableLedgerCount, unreadableLedgerDirectoryCount: ledgerObservation.unreadableLedgerDirectoryCount, missingLedgerDirectoryCount: ledgerObservation.missingLedgerDirectoryCount, unreadableLedgerDirectoryAccessCount: ledgerObservation.unreadableLedgerDirectoryAccessCount, indeterminateLedgerDirectoryCount: ledgerObservation.indeterminateLedgerDirectoryCount }, pty: { unreadable: [...pty.unreadable], observedRefCount: pty.refs.length, withoutRunIdCount, notCountedRefCount }, phases: { targetCount: 0, readableTargetCount: 0, unreadableTargetCount: 0, unreadableTargets: [], discardedNonStageEventCount: 0 } };
 }
 
+/** A legacy state alias can point at the same physical ledger. Keep missing or unreadable
+ * directories in the query so they still contribute an incomplete-observation signal. */
+type LedgerDirectoryIdentity = { dev: bigint; ino: bigint; isDirectory(): boolean };
+
+export function distinctPhysicalLedgerDirectories(
+  directories: readonly string[],
+  statDirectory: (directory: string) => LedgerDirectoryIdentity = (directory) => statSync(directory, { bigint: true }),
+): string[] {
+  const seen = new Map<string, string>();
+  const distinct: string[] = [];
+  for (const directory of directories) {
+    try {
+      const stat = statDirectory(directory);
+      if (stat.isDirectory()) {
+        const identity = `${stat.dev}:${stat.ino}`;
+        const first = seen.get(identity);
+        if (first !== undefined) {
+          debug.log('self-implement.running-runs', 'ledger-directory-alias', { first, alias: directory });
+          continue;
+        }
+        seen.set(identity, directory);
+      }
+    } catch { /* Preserve this target for the federated query's missing/unreadable judgment. */ }
+    distinct.push(directory);
+  }
+  return distinct;
+}
+
 export function queryRunningRuns(options: { includeTest?: boolean; runIds?: readonly string[]; caller?: string; noCache?: boolean } = {}, deps: RunningRunsQueryDeps = {}): QueriedRunningRunsResult {
   const directoryFailures = new Map<string, ReturnType<typeof classifyFederatedLedgerDirectoryReadFailure>>();
   const queryLedgers = deps.queryLedgers ?? ((queryOptions: Parameters<typeof queryFederatedUnfinishedRunLedgers>[0]) => queryFederatedUnfinishedRunLedgers({
@@ -466,7 +494,7 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
     if (collectLedgerDirectories) {
       const ledgerDirectoryCollectionStartedAt = Date.now();
       try {
-        collectedLedgerDirectories = ledgerDirectories({ includeTest: options.includeTest });
+        collectedLedgerDirectories = distinctPhysicalLedgerDirectories(ledgerDirectories({ includeTest: options.includeTest }));
       } finally {
         ledgerDirectoryCollectionElapsedMs = Date.now() - ledgerDirectoryCollectionStartedAt;
       }

package/src/self-implement/scope-adjacency.ts

@@ -21,3 +21,118 @@ export function classifyOutOfScope(outsideFiles: readonly string[], declaredPath
   for (const file of outsideFiles) (folders.has(dirOf(normalize(file))) ? adjacent : other).push(file);
   return { adjacent, other };
 }
+
+// SCOPE-AS-DIRECTION (0.2.35 · 대표 10-21 «골은 방향·원칙·KPI 를 정하고 구현은 적응한다 — 파일 단위 마이크로 관리는 틀렸다»).
+// 10-20: 13 runs held with PR 0; half of the crossed files were necessary wiring (CLI registration, production callers,
+// ledger files). Target paths are now the starting point: outside edits are accepted, named with a kind, and handed to
+// the reviewer in the PR body. Only a deletion, a protected path, or an outside count over the cap stops the run.
+
+export type ScopeExpansionKind = 'neighbour' | 'caller-or-registration' | 'paired-test' | 'other';
+export interface ScopeExpansionFile { path: string; kind: ScopeExpansionKind }
+export interface ScopeExpansion { files: ScopeExpansionFile[]; count: number }
+/** Every stop reason, in report order — the one source; the Pod parent (self-implement.ts) reads held results against it. */
+export const SCOPE_STOP_REASONS = ['deletion', 'protected-path', 'over-cap', 'name-cap'] as const;
+export type ScopeStopReason = (typeof SCOPE_STOP_REASONS)[number];
+
+/** Accepted outside files above this count stop the run: past it the change is no longer «the goal, adapted». */
+export const SCOPE_EXPANSION_CAP = 10;
+
+const TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+const CODE_EXT = /\.(?:[cm]?[jt]sx?)$/;
+const baseOf = (path: string): string => path.slice(path.lastIndexOf('/') + 1);
+const stemOf = (path: string): string => baseOf(path).replace(TEST_FILE, '').replace(/\.[^.]+$/, '');
+const withoutCodeExt = (path: string): string => path.replace(CODE_EXT, '');
+
+/** Paths an unattended run never edits on its own: rules, anything credential-like, production elanous config. */
+export function isProtectedScopePath(path: string): boolean {
+  const p = normalize(path);
+  if (p === '.rules' || p.startsWith('.rules/')) return true;
+  if (/credential|secret/i.test(p)) return true;
+  const base = baseOf(p);
+  if (base === 'auth.json' || base === '.env' || base.startsWith('.env.')) return true;
+  return /(^|\/)\.elanous[^/]*\/(.*\/)?config\.json$/.test(p);
+}
+
+function resolveRelative(fromFile: string, spec: string): string {
+  const parts = dirOf(fromFile) ? dirOf(fromFile).split('/') : [];
+  for (const seg of spec.split('/')) {
+    if (seg === '.' || seg === '') continue;
+    if (seg === '..') parts.pop(); else parts.push(seg);
+  }
+  return parts.join('/');
+}
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Name each outside file's relation to the declared targets. Deterministic: path shape and plain text only.
+ *  Order of kinds: paired-test → neighbour (same folder as a declared file) → caller-or-registration (index.ts,
+ *  *-cli.ts, imports a declared file, or names an exported symbol of one) → other. `readFile` is relative to the tree. */
+export function classifyScopeExpansion(
+  outsideFiles: readonly string[], declaredPaths: readonly string[], readFile: (path: string) => string | undefined = () => undefined,
+): ScopeExpansionFile[] {
+  const declared = declaredPaths.map(normalize);
+  const adjacentSet = new Set(classifyOutOfScope(outsideFiles, declaredPaths).adjacent);
+  const declaredFiles = declared.filter(path => /\.[A-Za-z0-9]+$/.test(baseOf(path)));
+  const declaredModules = new Set(declaredFiles.filter(path => CODE_EXT.test(path)).map(withoutCodeExt));
+  const pairStems = new Set([...declaredFiles, ...outsideFiles.map(normalize).filter(path => !TEST_FILE.test(path))].map(stemOf));
+  const exportedNames: string[] = [];
+  for (const file of declaredFiles) {
+    let text: string | undefined;
+    try { text = readFile(file); } catch { text = undefined; }
+    if (!text) continue;
+    for (const match of text.matchAll(/export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|const|let|var|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/g)) {
+      if (match[1]!.length >= 4 && !exportedNames.includes(match[1]!)) exportedNames.push(match[1]!);
+    }
+  }
+  const namePatterns = exportedNames.map(name => new RegExp(`(^|[^\\w$])${escapeRegExp(name)}([^\\w$]|$)`));
+  const callsDeclared = (file: string): boolean => {
+    let text: string | undefined;
+    try { text = readFile(file); } catch { text = undefined; }
+    if (!text) return false;
+    for (const match of text.matchAll(/(?:from\s+|import\s*\(\s*|require\s*\(\s*|import\s+)['"]([^'"]+)['"]/g)) {
+      const spec = match[1]!;
+      if (spec.startsWith('.') && declaredModules.has(withoutCodeExt(resolveRelative(file, spec)))) return true;
+    }
+    return namePatterns.some(pattern => pattern.test(text!));
+  };
+  return outsideFiles.map(path => {
+    const p = normalize(path);
+    const base = baseOf(p);
+    const kind: ScopeExpansionKind = TEST_FILE.test(p) && pairStems.has(stemOf(p)) ? 'paired-test'
+      : adjacentSet.has(path) ? 'neighbour'
+      : /^index\.[cm]?[jt]sx?$/.test(base) || /-cli\.[cm]?[jt]sx?$/.test(base) || callsDeclared(p) ? 'caller-or-registration'
+      : 'other';
+    return { path, kind };
+  });
+}
+
+export type ScopeExpansionDecision =
+  | { accept: true; expansion: ScopeExpansion }
+  | { accept: false; reasons: ScopeStopReason[]; deleted: string[]; protectedPaths: string[]; expansion: ScopeExpansion };
+
+/** Accept outside edits by default; stop only on a deletion, a protected path, a count over the cap, or an
+ *  incomplete name list (the guard cannot judge files it did not see). */
+export function decideScopeExpansion(input: {
+  outsideFiles: readonly string[]; declaredPaths: readonly string[]; deleted: readonly string[]; nameCapReached: boolean;
+  cap?: number; readFile?: (path: string) => string | undefined;
+}): ScopeExpansionDecision {
+  const files = classifyScopeExpansion(input.outsideFiles, input.declaredPaths, input.readFile);
+  const expansion: ScopeExpansion = { files, count: files.length };
+  const protectedPaths = input.outsideFiles.filter(isProtectedScopePath);
+  const reasons: ScopeStopReason[] = [];
+  if (input.deleted.length) reasons.push('deletion');
+  if (protectedPaths.length) reasons.push('protected-path');
+  if (files.length > (input.cap ?? SCOPE_EXPANSION_CAP)) reasons.push('over-cap');
+  if (input.nameCapReached) reasons.push('name-cap');
+  return reasons.length ? { accept: false, reasons, deleted: [...input.deleted], protectedPaths, expansion } : { accept: true, expansion };
+}
+
+/** PR body section for the reviewer: each accepted outside file with its kind, judged against the goal's direction. */
+export function renderScopeExpansionSection(expansion: ScopeExpansion | undefined): string {
+  if (!expansion || expansion.files.length === 0) return '';
+  return [
+    '', '', `## 범위 확장 (${expansion.count})`,
+    '대상 경로는 출발점이다 — 아래 파일은 대상 밖에서 바뀌었고 자동으로 받아들였다. 골의 방향·원칙·KPI 에 비춰 판단해 달라.',
+    ...expansion.files.map(file => `- \`${file.path}\` — ${file.kind}`),
+  ].join('\n');
+}