elanous 0.2.18 → 0.2.19

package/src/self-dev/pr-preview.ts

@@ -0,0 +1,179 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface PreviewOptions {
+  target: string;
+  repoRoot: string;
+  scenario?: string;
+  /** Main-based combined preview: only existing config paths may be enabled. */
+  flags?: readonly string[];
+  commentPr?: number;
+}
+export interface PreviewResult {
+  target: string;
+  head: string;
+  scenario: string;
+  status: 'passed' | 'friction';
+  report: string;
+  prNumber?: number;
+  commented: boolean;
+}
+export function readPreviewResult(directory: string): PreviewResult | null {
+  try {
+    const value = JSON.parse(readFileSync(join(directory, 'preview-result.json'), 'utf8')) as PreviewResult;
+    return value && (value.status === 'passed' || value.status === 'friction') && typeof value.head === 'string' ? value : null;
+  } catch { return null; }
+}
+
+export interface PreviewDeps {
+  run?: (command: string, args: readonly string[], cwd: string, timeoutMs?: number) => { status: number | null; stdout: string; stderr: string };
+  makeDir?: () => string;
+  dispose?: (directory: string) => void;
+  wait?: (ms: number) => Promise<void>;
+  /** Probe a test-mode daemon without injecting a global HTTP client into the command runner. */
+  probePwa?: (url: string) => Promise<boolean>;
+}
+
+const SCENARIOS: Record<string, string> = {
+  S2: '/help', S3: '/status', S6: '/now', S7: '/term list', S8: '/model', S9: '/harness',
+};
+
+export function previewScenarioInput(scenario: string): string {
+  const text = Object.hasOwn(SCENARIOS, scenario) ? SCENARIOS[scenario] : undefined;
+  if (!text) throw new Error(`TUI-COMFORT §4: unsupported scenario ${scenario}; available: ${Object.keys(SCENARIOS).join(', ')}`);
+  return text;
+}
+
+const defaultRun: NonNullable<PreviewDeps['run']> = (command, args, cwd, timeoutMs = 120_000) => {
+  const r = spawnSync(command, [...args], { cwd, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 });
+  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? String(r.error ?? '') };
+};
+
+/** Build and exercise a detached head, never the caller's checkout. The report is posted only after measurement. */
+export async function runPrPreview(options: PreviewOptions, deps: PreviewDeps = {}): Promise<PreviewResult> {
+  const run = deps.run ?? defaultRun;
+  const root = resolve(options.repoRoot);
+  const target = options.target.trim();
+  if (!target || target.startsWith('-') || /[\s\x00-\x1f]/u.test(target)) throw new Error('preview: invalid PR number or branch');
+  const isPr = /^[1-9]\d*$/u.test(target);
+  if (isPr && !Number.isSafeInteger(Number(target))) throw new Error('preview: invalid PR number');
+  if (/^\d+$/u.test(target) && !isPr) throw new Error('preview: invalid PR number');
+  if (options.commentPr !== undefined && (!Number.isSafeInteger(options.commentPr) || options.commentPr <= 0)) throw new Error('preview: invalid --comment-pr');
+  if (target === 'main' && options.commentPr === undefined) throw new Error('preview: main ⊕ flags requires --comment-pr <PR number> to publish the result');
+  if (isPr && options.commentPr !== undefined && options.commentPr !== Number(target)) throw new Error('preview: --comment-pr must match the target PR');
+  const flags = options.flags ?? [];
+  if (flags.length && target !== 'main') throw new Error('preview: --flag requires main (main ⊕ feature flags)');
+  if (flags.some((flag) => !/^[a-zA-Z][\w-]*(?:\.[a-zA-Z][\w-]*)+$/u.test(flag))) throw new Error('preview: --flag expects an existing dotted config path');
+  const scenario = options.scenario ?? 'S2';
+  const input = previewScenarioInput(scenario);
+  const check = (command: string, args: readonly string[], cwd: string, timeout?: number): string => {
+    const r = run(command, args, cwd, timeout);
+    if (r.status !== 0) throw new Error(`preview: ${command} ${args.join(' ')} failed: ${(r.stdout + '\n' + r.stderr).slice(-600)}`);
+    return r.stdout.trim();
+  };
+  let prNumber = isPr ? Number(target) : options.commentPr;
+  let branchPrHead: string | undefined;
+  let ref = target;
+  if (isPr) {
+    const pr = JSON.parse(check('gh', ['pr', 'view', target, '--json', 'number,headRefOid'], root)) as { number?: number; headRefOid?: string };
+    if (pr.number !== Number(target) || !/^[0-9a-f]{40}$/iu.test(pr.headRefOid ?? '')) throw new Error('preview: PR head is unavailable');
+    ref = pr.headRefOid!;
+  } else if (target !== 'main') {
+    check('git', ['check-ref-format', '--branch', target], root);
+    if (options.commentPr === undefined) {
+      const matching = JSON.parse(check('gh', ['pr', 'list', '--head', target, '--state', 'open', '--json', 'number,headRefOid'], root)) as Array<{ number?: number; headRefOid?: string }>;
+      if (matching.length !== 1 || !Number.isSafeInteger(matching[0]?.number)) throw new Error('preview: branch has no unique open PR; use --comment-pr <PR number>');
+      prNumber = matching[0]!.number;
+      branchPrHead = matching[0]!.headRefOid;
+    }
+  }
+  if (isPr && run('git', ['cat-file', '-e', `${ref}^{commit}`], root).status !== 0) {
+    check('git', ['fetch', '--no-tags', 'origin', `pull/${target}/head`], root, 120_000);
+    const fetched = check('git', ['rev-parse', '--verify', 'FETCH_HEAD^{commit}'], root);
+    if (fetched !== ref) throw new Error('preview: PR head changed while fetching; retry');
+  }
+  const head = check('git', ['rev-parse', '--verify', `${ref}^{commit}`], root);
+  if (!/^[0-9a-f]{40}$/iu.test(head)) throw new Error('preview: unresolved commit');
+  if (target !== 'main' && !isPr) {
+    const pr = JSON.parse(check('gh', ['pr', 'view', String(prNumber), '--json', 'headRefOid,headRefName'], root)) as { headRefOid?: string; headRefName?: string };
+    if (pr.headRefName !== target || pr.headRefOid !== head || (branchPrHead !== undefined && branchPrHead !== head)) throw new Error('preview: branch does not match the target PR head; use the PR number');
+  }
+  const directory = (deps.makeDir ?? (() => {
+    const previews = join(root, '.elanous-test', 'previews');
+    mkdirSync(previews, { recursive: true });
+    return mkdtempSync(join(previews, 'preview-'));
+  }))();
+  const worktree = join(directory, 'checkout');
+  let added = false;
+  let heldPty: string | undefined;
+  let report = '';
+  const wait = deps.wait ?? ((ms: number) => new Promise<void>((done) => setTimeout(done, ms)));
+  try {
+    check('git', ['worktree', 'add', '--detach', worktree, head], root);
+    added = true;
+    check('bun', ['install', '--frozen-lockfile'], worktree, 300_000);
+    check('bun', ['install', '--frozen-lockfile'], join(worktree, 'apps/pwa'), 300_000);
+    for (const flag of flags) {
+      const existing = check('bun', ['bin/elanous.mjs', '--test', 'config', 'get', flag], worktree);
+      if (existing !== 'true' && existing !== 'false') throw new Error(`preview: ${flag} is not a boolean feature flag`);
+      check('bun', ['bin/elanous.mjs', '--test', 'config', 'set', flag, 'true'], worktree);
+    }
+    check('bun', ['bin/elanous.mjs', '--test', 'nexus', 'build', '--cwd', join(worktree, 'apps/pwa')], worktree, 300_000);
+    const pwa = check('bun', ['bin/elanous.mjs', '--test', 'nexus', 'run', '--test', '--tool-cwd', worktree], worktree, 120_000);
+    const port = /\bnexus\s+:(314[5-9]\d)\b/u.exec(pwa)?.[1];
+    const endpoint = port ? `http://127.0.0.1:${port}` : undefined;
+    if (!endpoint) throw new Error('preview: P-1 has no local test endpoint');
+    const probeOnce = deps.probePwa ?? (async (url: string) => {
+      try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+        return response.ok && (await response.text()).includes('<');
+      } catch { return false; }
+    });
+    // `nexus run` detaches and returns before the daemon listens — its exit is not readiness. Poll.
+    let probe = false;
+    for (let attempt = 0; attempt < 60 && !probe; attempt++) {
+      probe = await probeOnce(`${endpoint}/app/`);
+      if (!probe) await wait(1000);
+    }
+    if (!probe) throw new Error('preview: P-1 did not serve the built PWA');
+    const version = check('bun', ['bin/elanous.mjs', '--version'], worktree);
+    if (!version) throw new Error('preview: B-1 version probe returned no output');
+    const held = check('bun', ['bin/elanous.mjs', '--test', 'dev', '--elanous', '--hold', '--cwd', worktree, '--isolated-root', join(directory, 'tui'), '--json'], worktree, 120_000);
+    const last = held.split('\n').reverse().find((line: string) => line.trim().startsWith('{'));
+    const pty = last ? JSON.parse(last) as { held?: boolean; ptyId?: string } : {};
+    if (pty.held !== true || !/^pty_[\w-]+$/u.test(pty.ptyId ?? '')) throw new Error('preview: B-1 held TUI did not return a PTY reference');
+    heldPty = pty.ptyId;
+    const snapshotArgs = ['bin/elanous.mjs', '--test', 'pty', 'snapshot', pty.ptyId!] as const;
+    const before = check('bun', snapshotArgs, worktree);
+    check('bun', ['bin/elanous.mjs', '--test', 'pty', 'text', pty.ptyId!, input, '--enter'], worktree);
+    // A constant sleep misses slow frames under load — poll until the screen answers (≤ 20s).
+    let snapshot = '';
+    for (let attempt = 0; attempt < 20; attempt++) {
+      await wait(1000);
+      snapshot = check('bun', snapshotArgs, worktree);
+      if (snapshot && snapshot !== 'ok' && snapshot !== before) break;
+    }
+    if (!snapshot || snapshot === 'ok' || snapshot === before) throw new Error('preview: inner PTY did not show a response to the scenario input within 20s');
+    report = `| Check | Observation |\n|---|---|\n| head | \`${head}\` |\n| B-1 version | ${version.slice(0, 120)} |\n| P-1 PWA | \`${endpoint}/app/\` served the built PWA |\n| TUI-COMFORT §4 ${scenario} | \`${input}\` → snapshot captured |\n\n<details><summary>Inner PTY snapshot</summary>\n\n\`\`\`text\n${snapshot.slice(-3000).replaceAll('```', "'''")}\n\`\`\`\n</details>`;
+  } catch (error) {
+    report = `| Check | Friction |\n|---|---|\n| head | \`${head}\` |\n| TUI-COMFORT §4 ${scenario} | ${String(error).replaceAll('|', '\\|').slice(0, 700)} |`;
+  } finally {
+    if (added) {
+      if (heldPty) run('bun', ['bin/elanous.mjs', '--test', 'pty', 'key', heldPty, 'ctrl+c'], worktree, 30_000);
+      run('bun', ['bin/elanous.mjs', '--test', 'nexus', 'run', '--test', '--stop'], worktree, 30_000);
+      const removed = run('git', ['worktree', 'remove', '--force', worktree], root, 30_000);
+      if (removed.status !== 0) throw new Error(`preview: failed to remove isolated worktree: ${removed.stderr}`);
+    }
+    (deps.dispose ?? ((dir) => rmSync(dir, { recursive: true, force: true })))(directory);
+  }
+  const status = report.includes('| Friction |') ? 'friction' : 'passed';
+  const body = `## PR preview — ${target} (${status})\n\n${report}`;
+  if (prNumber === undefined) throw new Error('preview: cannot comment without a PR number');
+  check('gh', ['pr', 'comment', String(prNumber), '--body', body], root);
+  const result: PreviewResult = { target, head, scenario, status, report: body, prNumber, commented: true };
+  const resultDir = join(root, '.elanous-test');
+  mkdirSync(resultDir, { recursive: true });
+  writeFileSync(join(resultDir, 'preview-result.json'), JSON.stringify(result), { mode: 0o600 });
+  return result;
+}

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

@@ -11,6 +11,7 @@ export interface ShardRunResult {
   shards: GateTestShard[];
   attempts: GateShardAttempt[];
   reason?: string;
+  measurementFailures?: number;
 }
 
 export type ShardProcess = (cwd: string, files: readonly string[]) => {
@@ -34,24 +35,39 @@ export function runShardedGateTests(
   if (!Number.isSafeInteger(count) || count < 1) throw new Error('invalid --shards count');
   const rss = new Map<string, number>();
   const seconds = new Map<string, number>();
+  const failedMeasurements: string[] = [];
   for (const file of [...new Set(files)]) {
     let sample: ReturnType<ShardProcess>;
     try {
       sample = run(cwd, [file]);
-    } catch (error) {
-      return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: `measurement failed: ${file}: ${String(error)}` };
+    } catch {
+      failedMeasurements.push(file);
+      continue;
     }
-    if (![0, 1].includes(sample.exitCode ?? -1) || sample.signal || !sample.junit || !Number.isFinite(sample.rssMb) || !Number.isFinite(sample.seconds)) {
-      return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: `measurement unavailable: ${file}` };
+    if (![0, 1].includes(sample.exitCode ?? -1) || sample.signal || !sample.junit
+      || !Number.isFinite(sample.rssMb) || sample.rssMb! <= 0
+      || !Number.isFinite(sample.seconds) || sample.seconds! < 0) {
+      failedMeasurements.push(file);
+      continue;
     }
     rss.set(file, sample.rssMb!);
     seconds.set(file, sample.seconds!);
   }
+  if (failedMeasurements.length) {
+    if (!rss.size) return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: 'no valid file measurements', measurementFailures: failedMeasurements.length };
+    const averageRss = [...rss.values()].reduce((sum, value) => sum + value, 0) / rss.size;
+    const averageSeconds = [...seconds.values()].reduce((sum, value) => sum + value, 0) / seconds.size;
+    for (const file of failedMeasurements) {
+      rss.set(file, averageRss);
+      seconds.set(file, averageSeconds);
+    }
+  }
+  const measurementFailures = failedMeasurements.length || undefined;
   let shards: GateTestShard[];
   try {
     shards = planGateTestShards(files, rss, seconds, budgetGiB, count);
   } catch (error) {
-    return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error) };
+    return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error), ...(measurementFailures ? { measurementFailures } : {}) };
   }
   const attempts: GateShardAttempt[] = [];
   const baseline = baselineWorktree(cwd, baseRef, (dir) => {
@@ -76,8 +92,8 @@ export function runShardedGateTests(
     }
     return aggregateGateTestShards(shards, attempts);
   });
-  if ('retryShardIds' in baseline) return { aggregate: baseline, shards, attempts };
-  return { aggregate: { status: 'unmeasured', retryShardIds: shards.map((shard) => shard.id) }, shards, attempts, reason: baseline.log };
+  if ('retryShardIds' in baseline) return { aggregate: baseline, shards, attempts, ...(measurementFailures ? { measurementFailures } : {}) };
+  return { aggregate: { status: 'unmeasured', retryShardIds: shards.map((shard) => shard.id) }, shards, attempts, reason: baseline.log, ...(measurementFailures ? { measurementFailures } : {}) };
 }
 
 export function runBunShard(cwd: string, files: readonly string[]): ReturnType<ShardProcess> {

package/src/self-implement/gate-cli.ts

@@ -26,10 +26,13 @@ import {
 import { listWorktrees } from '../git-fs/worktree.js';
 import { runShardedGateTests } from '../self-dev/shard-run.js';
 
-interface SelfGateCliOptions {
+export interface SelfGateCliOptions {
   base?: string;
   pr?: string;
   shards?: number;
+  /** LIGHT-RC (0.2.19) — repository-relative test paths run on every call, whatever changed. Existing ones join the
+   *  run (deduplicated, same introduced/preexisting baseline as the rest); missing ones go to `alwaysIncludeMissing`. */
+  alwaysInclude?: readonly string[];
 }
 
 interface ProcessResult {
@@ -102,7 +105,7 @@ interface GateOutput {
   error: (message: string) => void;
 }
 
-interface SelfGateCliResult {
+export interface SelfGateCliResult {
   exitCode: number;
   lines: string[];
   changedFiles: string[];
@@ -110,6 +113,11 @@ interface SelfGateCliResult {
   unverified: readonly string[];
   documentPaths: readonly string[];
   documentsWithoutDerivedTests: readonly string[];
+  /** `alwaysInclude` paths that do not exist in the tree (empty when none were given). */
+  alwaysIncludeMissing: readonly string[];
+  /** New vs. already-present failures (unknown/preconditionUnmet = failures it could not classify). Absent = the test
+   *  step did not produce a measurement (e.g. shards unmeasured). */
+  baseline?: { introduced: number; preexisting: number; unknown: number; preconditionUnmet: number };
 }
 
 /** 시험 단계와 독립인 정책 관문 넷. skipTestStep 이든 시험 통과든 같은 함수를 부른다. */
@@ -590,7 +598,12 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   const expose = publicExposureFiles(selection.files).length > 0
     ? runExposeGate(cwd, selection.files, getUserConfig().harness?.exposeGate === 'strict' ? 'strict' : 'warn', deps.runCommand)
     : { passed: true, log: '' };
-  const testFiles = [...(scope.testArgs ?? [])];
+  const alwaysInclude = [...new Set((options.alwaysInclude ?? []).map(normalizeGatePath).filter(Boolean))];
+  const alwaysIncludeMissing = alwaysInclude.filter((path) => !exists(path));
+  const scopedTests = scope.testArgs ?? [];
+  const alwaysIncludeExtra = alwaysInclude.filter((path) => exists(path) && !scopedTests.includes(path));
+  const testFiles = [...scopedTests, ...alwaysIncludeExtra];
+  const skipTestStep = scope.skipTestStep && alwaysIncludeExtra.length === 0;
   const unrunImporterTotal = lookupFailed ? null : (scope.importerTestsNotRun?.total ?? 0);
   const importerLookupFailed = Boolean(lookupFailed);
   const lines = [
@@ -619,6 +632,10 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     ...(routeIndex?.lookupFailures.length ? [`⚠️ caller route base lookup failed — unmeasured: ${routeIndex.lookupFailures.map(({ source, reason }) => `${source} (${reason})`).join(', ')}`] : []),
     ...(scope.callerTestsOverflow.length ? [`⚠️ caller test cap exceeded — not run: ${scope.callerTestsOverflow.map(({ file, reasons }) => `${file} (${reasons.join('+')})`).join(', ')}`] : []),
     changedTestCountNote(cwd, selection.files, selection.baseRef, deps.runCommand, deps.readFile),
+    // Only printed when the caller asked for always-include paths — the plain `self gate` output is unchanged.
+    ...(options.alwaysInclude !== undefined
+      ? [`always include: ${alwaysInclude.length - alwaysIncludeMissing.length}/${alwaysInclude.length} (added ${alwaysIncludeExtra.length}${alwaysIncludeMissing.length ? ` · missing: ${alwaysIncludeMissing.join(', ')}` : ''})`]
+      : []),
   ];
   if (expose.log) lines.push(expose.log);
   if (options.pr) {
@@ -641,17 +658,18 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   const iosPassed = runAdditionalGate('ios-gate', deps.runIosGate ?? runIosUnitTestGate, selection.files, cwd, lines);
   const pwaPassed = runAdditionalGate('pwa-gate', deps.runPwaGate ?? runPwaBuildGate, selection.files, cwd, lines);
 
-  if (scope.skipTestStep) {
+  if (skipTestStep) {
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
-    return { exitCode: androidPassed && iosPassed && pwaPassed && policyPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles: [], unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
+    return { exitCode: androidPassed && iosPassed && pwaPassed && policyPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles: [], unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, baseline: { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 } };
   }
 
   if (options.shards !== undefined) {
     const sharded = (deps.runShards ?? runShardedGateTests)(cwd, testFiles, selection.baseRef, options.shards);
-    lines.push(`shards: ${sharded.shards.length} (${sharded.shards.map((shard) => `${shard.id}=${shard.files.join(',')}`).join('; ')})`);
+    lines.push(`shards: ${sharded.shards.length} (${sharded.shards.map((shard) => `${shard.id}=${shard.files.join(',')}`).join('; ')})${sharded.measurementFailures ? ` · 측정 실패 ${sharded.measurementFailures}` : ''}`);
     for (const attempt of sharded.attempts) lines.push(`shard attempt: ${attempt.shardId} #${attempt.attempt}`);
     const { aggregate } = sharded;
+    let shardBaseline: SelfGateCliResult['baseline'];
     if (aggregate.status === 'unmeasured') lines.push(`shards: unmeasured (${aggregate.retryShardIds.join(', ') || sharded.reason || 'no complete JUnit'})`);
     else if (aggregate.report) {
       const report = aggregate.report;
@@ -662,15 +680,18 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
         baselineFiles: report.files, baselineStatus: report.baselineStatus, unrunImporterTotal, lookupFailed: importerLookupFailed,
       });
       lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, formatGateBaselineNote(report, unrunImporterTotal ?? 0)));
+      shardBaseline = { introduced: report.introduced, preexisting: report.preexisting, unknown: report.unknown, preconditionUnmet: report.preconditionUnmet };
     } else {
       lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, `tests: pass (${testFiles.length} files)`));
       logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
+      shardBaseline = { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 };
     }
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     return {
       exitCode: aggregate.status !== 'passed' || !policyPassed || !androidPassed || !iosPassed || !pwaPassed || !expose.passed ? 1 : 0,
       lines, changedFiles: selection.files, testFiles, unverified: scope.unverified,
       documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests,
+      alwaysIncludeMissing, ...(shardBaseline ? { baseline: shardBaseline } : {}),
     };
   }
 
@@ -680,7 +701,7 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, `tests: pass (${testFiles.length} files)`));
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
-    return { exitCode: policyPassed && androidPassed && iosPassed && pwaPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
+    return { exitCode: policyPassed && androidPassed && iosPassed && pwaPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, baseline: { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 } };
   }
 
   if (worktreeLog.includes('deterministic environment setup failed')) lines.push(worktreeLog);
@@ -702,5 +723,5 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, formatGateBaselineNote(report, unrunImporterTotal ?? 0)));
   const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
   const exitCode = !androidPassed || !iosPassed || !pwaPassed || !policyPassed || !expose.passed || report.introduced > 0 || report.unknown > 0 || report.preconditionUnmet > 0 ? 1 : 0;
-  return { exitCode, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
+  return { exitCode, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, baseline: { introduced: report.introduced, preexisting: report.preexisting, unknown: report.unknown, preconditionUnmet: report.preconditionUnmet } };
 }

package/src/self-implement/goal-author-clarification.ts

@@ -1,3 +1,6 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { resolve, relative, isAbsolute } from 'node:path';
+import ts from 'typescript';
 import { tierModel } from '../llm/model-defaults.js';
 import { debug } from '../debug/log.js';
 import type { LLMUsage } from '../prompt-cache/types.js';
@@ -42,7 +45,7 @@ export function parseGoalAuthorParent(document: string): GoalAuthorParent | null
   return matches.length === 1 ? matches[0] : null;
 }
 
-export type GoalAuthorClarificationAnswerSource = 'injected' | 'recommended' | 'self-authored';
+export type GoalAuthorClarificationAnswerSource = 'injected' | 'recommended' | 'self-authored' | 'default';
 
 export interface GoalAuthorClarificationProvenance {
   source: GoalAuthorClarificationAnswerSource;
@@ -78,8 +81,8 @@ export interface GoalAuthorSelfResolutionContext {
 }
 
 export type GoalAuthorSelfResolution =
-  | { answer: string; evidence: readonly string[] }
-  | { answer?: undefined; evidence?: undefined };
+  | { answer: string; evidence: readonly string[]; declined?: undefined }
+  | { answer?: undefined; evidence?: undefined; declined?: boolean };
 
 export interface GoalAuthorClarificationResolutionDeps {
   /** Elanousic authoring seam; it must return no answer when the available evidence is insufficient. */
@@ -189,7 +192,7 @@ export async function defaultGoalAuthorSelfResolve(
   const usages: LLMUsage[] = [];
   if (context.evidence.length === 0) {
     observeSelfResolve('self-resolve-no-evidence', context, startedAt, { usage: deriveUsage(usages) });
-    return {};
+    return context.questionId === 'preservation_contract' ? { declined: true } : {};
   }
   const controller = new AbortController();
   const timeout = setTimeout(
@@ -230,7 +233,7 @@ export async function defaultGoalAuthorSelfResolve(
       evidenceCount: context.evidence.length,
       usage: deriveUsage(usages),
     });
-    return {};
+    return answer === null && context.questionId === 'preservation_contract' ? { declined: true } : {};
   } catch (error) {
     observeSelfResolve(
       isSelfResolutionTimeout(error, controller.signal) ? 'self-resolve-timeout' : 'self-resolve-error',
@@ -471,6 +474,57 @@ interface GoalAuthorClarificationSeed {
   parent: GoalAuthorParent;
 }
 
+const PRESERVATION_DEFAULT = '대상 경로의 기존 공개 동작(내보내는 함수 시그니처 · CLI 인자·출력·종료 코드)은 그대로 유지한다 · 바뀌는 것은 골이 명시한 동작뿐';
+
+function preservationDefault(ask: string): { answer: string; exportCount: number } {
+  const request = /Original ask \(verbatim, unmodified\):\s*```\r?\n([\s\S]*?)\r?\n```/.exec(ask)?.[1] ?? ask;
+  // Every `대상 경로:` line counts, plain or as a Markdown list item; backticks around a path are cosmetic.
+  const paths = [...new Set(request.split(/\r?\n/).flatMap((line) => {
+    const match = /^\s*(?:(?:[-*+]|\d+[.)])\s+)?대상 경로:\s*(.*)$/.exec(line);
+    return match ? match[1].split(/\s*[,·]\s*/).map((path) => path.trim().replace(/^`|`$/g, '')) : [];
+  }))];
+  const exports: string[] = [];
+  for (const path of paths) {
+    if (!/^[\w./-]+\.[cm]?[jt]sx?$/.test(path) || path.startsWith('/') || path.split('/').includes('..')) continue;
+    const absolute = resolve(process.cwd(), path);
+    try {
+      const actual = realpathSync(absolute);
+      const withinRepo = relative(realpathSync(process.cwd()), actual);
+      if (withinRepo === '..' || withinRepo.startsWith('../') || isAbsolute(withinRepo)) continue;
+      const source = ts.createSourceFile(path, readFileSync(actual, 'utf8'), ts.ScriptTarget.Latest, true);
+      for (const statement of source.statements) {
+        if (ts.isExportDeclaration(statement)) {
+          if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+            for (const element of statement.exportClause.elements) exports.push(`${path}: ${element.name.text}`);
+          } else if (statement.exportClause && ts.isNamespaceExport(statement.exportClause)) {
+            exports.push(`${path}: ${statement.exportClause.name.text}`);
+          } else if (!statement.exportClause && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) {
+            // Names re-exported by `export *` are not resolved here; record the re-export itself so the preserved surface is explicit.
+            exports.push(`${path}: * from ${statement.moduleSpecifier.text}`);
+          }
+        } else if (ts.isExportAssignment(statement)) {
+          exports.push(`${path}: ${statement.isExportEquals ? 'export =' : 'default'}`);
+        } else if (ts.canHaveModifiers(statement) && ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+          if (ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword)) {
+            exports.push(`${path}: default`);
+          } else if (ts.isVariableStatement(statement)) {
+            const bindingNames = (name: ts.BindingName): string[] => ts.isIdentifier(name)
+              ? [name.text]
+              : name.elements.flatMap((element) => ts.isOmittedExpression(element) ? [] : bindingNames(element.name));
+            for (const declaration of statement.declarationList.declarations) {
+              for (const exported of bindingNames(declaration.name)) exports.push(`${path}: ${exported}`);
+            }
+          } else if ('name' in statement && statement.name && ts.isIdentifier(statement.name as ts.Node)) {
+            exports.push(`${path}: ${(statement.name as ts.Identifier).text}`);
+          }
+        }
+      }
+    } catch { /* An unavailable target cannot supply verified export names. */ }
+  }
+  const names = [...new Set(exports)];
+  return { answer: names.length ? `${PRESERVATION_DEFAULT} · export 이름: ${names.join(', ')}` : PRESERVATION_DEFAULT, exportCount: names.length };
+}
+
 const DEFERRED_ANSWER = 'DEFERRED-UNTIL: ';
 const DEFERRED_ANSWER_PREFIX = 'DEFERRED-UNTIL';
 
@@ -515,7 +569,7 @@ export function parseGoalDocumentClarifications(document: string): GoalDocumentC
         readingOptions = false;
         continue;
       }
-      const provenanceSource = /^  - provenance\.source: (injected|recommended|self-authored)$/.exec(line);
+      const provenanceSource = /^  - provenance\.source: (injected|recommended|self-authored|default)$/.exec(line);
       if (provenanceSource) {
         fields.set('provenanceSource', provenanceSource[1]);
         provenanceLines.push(index);
@@ -692,6 +746,7 @@ export async function selfAnswerGoalDocumentClarifications(
     ask?: string;
     evidence?: readonly string[];
     resolver?: GoalClarificationSelfResolver;
+    runId?: string;
   },
 ): Promise<{ document: string; asked: number; answered: number; unanswered: number; newlyAnswered: number }> {
   const clarifications = parseGoalDocumentClarifications(document);
@@ -699,7 +754,7 @@ export async function selfAnswerGoalDocumentClarifications(
   // The first say pass may already have self-answered some questions while authoring: count those,
   // never re-ask them, and still attempt every question that is left unanswered.
   const alreadySelfAnswered = options.path === 'say-first'
-    ? clarifications.filter((item) => item.answered && item.provenanceSource === 'self-authored').length
+    ? clarifications.filter((item) => item.answered && (item.provenanceSource === 'self-authored' || item.provenanceSource === 'default')).length
     : 0;
   let updated = document;
   let answered = 0;
@@ -709,6 +764,7 @@ export async function selfAnswerGoalDocumentClarifications(
   for (const item of pending) {
     if (parseGoalDocumentClarifications(updated).filter((entry) => entry.questionId === item.questionId).length !== 1) continue;
     let response: Awaited<ReturnType<typeof resolveGoalAuthorClarification>>;
+    let declined = false;
     try { response = await resolveGoalAuthorClarification({
       questionId: item.questionId,
       kind: 'scope',
@@ -717,7 +773,11 @@ export async function selfAnswerGoalDocumentClarifications(
       options: item.options.map((option) => ({ label: option.label, description: option.description })),
       blocking: false,
     }, {
-      selfResolve: options.resolver ?? defaultGoalAuthorSelfResolve,
+      selfResolve: async (context) => {
+        const resolution = await (options.resolver ?? defaultGoalAuthorSelfResolve)(context);
+        declined = resolution.declined === true;
+        return resolution;
+      },
       evidence,
       ask: options.ask,
       selfResolutionSelected: true,
@@ -725,11 +785,19 @@ export async function selfAnswerGoalDocumentClarifications(
       // A resolver failure leaves this question unanswered; the remaining questions are still attempted.
       continue;
     }
-    if (response.answer === null || response.provenance?.source !== 'self-authored'
+    let defaultExportCount: number | undefined;
+    if (response.answer === null && item.questionId === 'preservation_contract'
+      && declined) {
+      const fallback = preservationDefault(options.ask ?? document);
+      response = { ...response, answer: fallback.answer, status: 'ANSWERED', provenance: { source: 'default' } };
+      defaultExportCount = fallback.exportCount;
+    }
+    if (response.answer === null || (response.provenance?.source !== 'self-authored' && response.provenance?.source !== 'default')
       || response.answer.startsWith(DEFERRED_ANSWER_PREFIX)) continue;
+    const answerSource = response.provenance.source;
     try {
       if (!response.answer.trim() || /[\r\n]/.test(response.answer)
-        || (!item.includeOther && !item.options.some((option) => option.label === response.answer))) continue;
+        || (answerSource !== 'default' && !item.includeOther && !item.options.some((option) => option.label === response.answer))) continue;
       const current = findUnansweredGoalDocumentClarification(updated, item.questionId);
       const lines = updated.split(/\r?\n/);
       const provenanceLines = current.provenanceLines ?? [];
@@ -737,15 +805,22 @@ export async function selfAnswerGoalDocumentClarifications(
       const answerLine = current.answerLine - provenanceLines.filter((line) => line < current.answerLine).length;
       lines[answerLine] = `  - answer: ${response.answer}`;
       lines.splice(answerLine + 1, 0,
-        '  - provenance.source: self-authored',
-        ...response.provenance.evidence!.map((entry) => `  - evidence: ${entry.replace(/[\r\n]/g, ' ')}`));
+        `  - provenance.source: ${answerSource}`,
+        ...(response.provenance.evidence ?? []).map((entry) => `  - evidence: ${entry.replace(/[\r\n]/g, ' ')}`));
       updateWhatToBuildRenderAnswers(lines, item.questionId, response.answer);
       if (hasWhatToBuildUnansweredRenderAnswer(lines, item.questionId)) continue;
       const candidate = lines.join(document.includes('\r\n') ? '\r\n' : '\n');
       if (!parseGoalDocumentClarifications(candidate).some((entry) => entry.questionId === item.questionId
-        && entry.answered && entry.answer === response.answer && entry.provenanceSource === 'self-authored')) continue;
+        && entry.answered && entry.answer === response.answer && entry.provenanceSource === answerSource)) continue;
       updated = candidate;
       answered += 1;
+      if (defaultExportCount !== undefined) {
+        observeGoalAuthor('goal-author', 'self-answer-default-applied', {
+          runId: options.runId ?? process.env.ELANOUS_RUN_ID,
+          questionId: item.questionId,
+          exportCount: defaultExportCount,
+        });
+      }
     } catch {
       // Leave malformed or disallowed answers deferred.
     }

package/src/self-implement/goal-clarification-escalation.ts

@@ -39,6 +39,7 @@ type GoalClarificationAnsweredBy = 'human' | 'agent' | 'none' | 'mixed';
 
 export interface GoalClarificationEscalationInput {
   goalFile: string;
+  runId?: string;
   /** Explicit provenance for isolated test fixtures; never inferred from goalFile. */
   testOrigin?: true;
   delivery?: GoalClarificationDelivery;
@@ -443,6 +444,7 @@ export async function escalateGoalDocumentClarifications(
         path: input.selfAnswerPath,
         ask: document,
         resolver: input.selfResolveClarification,
+        runId: input.runId ?? process.env.ELANOUS_RUN_ID,
       });
       if (resolution.newlyAnswered > 0) {
         writeGoalDocumentAtomic(input.goalFile, resolution.document);

package/src/self-implement/orchestrator.ts

@@ -5381,6 +5381,7 @@ async function runSelfImplementInner(
       const { listSubscribers } = await import('../session/index.js');
       clarificationEscalation = await escalateGoalDocumentClarifications({
         goalFile: resolvedGoalFile,
+        runId,
         dispatchContext: clarificationDispatchContext,
         resolveOriginDelivery: (sessionId) => originHitlDelivery(listSubscribers(sessionId)),
         // ⛔ seam 이 주입되면 전역 리졸버는 «불리지 않는다» — 그때 'terminal' 이라 적으면
@@ -6231,7 +6232,7 @@ async function runSelfImplementInner(
                     const source = readFileSync(opts.goalFile, 'utf8');
                     // Always run the shared self-answer so every rework pass leaves one observation, even with nothing pending.
                     const resolved = await selfAnswerGoalDocumentClarifications(source, {
-                      path: 'rework', ask: source, resolver: s.selfResolveClarification,
+                      path: 'rework', ask: source, resolver: s.selfResolveClarification, runId,
                     });
                     if (resolved.newlyAnswered > 0) writeGoalDocumentAtomic(opts.goalFile, resolved.document);
                   } catch (error) {