elanous 0.2.43 → 0.2.44

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

@@ -8,7 +8,7 @@ export type { SupervisorStopReason } from './run-types.js';
 export { SUPERVISOR_STOP_REASONS } from './run-types.js';
 import { recordSelfDevRunSupervisorStop, selfDevRunsDir } from './run-store.js';
 import { readRunChart, recordRunChartDecision } from '../self-implement/run-chart.js';
-import { runLedgerDir } from '../self-implement/run-ledger.js';
+import { loadRunLedger, runLedgerDir } from '../self-implement/run-ledger.js';
 import { debug } from '../debug/log.js';
 import { sweepFrozenMerges } from '../self-implement/frozen-merges.js';
 import { selectKnowhowPack } from '../self-implement/knowhow-pack.js';
@@ -105,6 +105,25 @@ interface DecomposePromotionObservation {
   hotPathEdges?: number;
 }
 
+export interface SupervisorReauthorObservation {
+  round: number;
+  classifications: Array<{ taskId: string; text: string; kind: 'code-defect' | 'authorship-defect'; action: 'must-fix' | 'scope-reduction-fu' }>;
+  prescription: {
+    outcome: '부분 착지 + FU';
+    narrowedProposal: string;
+    partialLanding: string;
+    followUp: {
+      lane: 'REVIEW-ROUND-REAUTHOR-FU';
+      goalId: string;
+      feature: string;
+      targetPaths: string[];
+      completionBoundary: string;
+      mockScenarioId: string;
+      mockScenario: { id: string; injection: string; observation: string };
+    };
+  };
+}
+
 export interface SupervisorDecision {
   action: 'relaunch' | 'add-repair-task' | 'stop';
   stopReason?: SupervisorStopReason;
@@ -130,6 +149,8 @@ export interface SupervisorDecision {
   reviewMustFixTrend: ReviewRework['trend'];
   /** REVIEW-MUSTFIX-CLASSIFY — this round's leading must-fix class (② › ③ observed › ①); omitted when unmeasured (지금 동작 그대로). */
   mustFix?: MustFixRoundClassification;
+  /** REVIEW-ROUND-REAUTHOR — supervisory reauthoring decision, omitted for ordinary/legacy rounds. */
+  reauthor?: SupervisorReauthorObservation;
   /** REVIEW-MUSTFIX-CLASSIFY — every oscillating task's measured class, so a mixed round keeps each task's decision. */
   mustFixByTask?: Record<string, MustFixRoundClassification>;
   /**
@@ -367,6 +388,70 @@ function mustFixFromResults(results: readonly SupervisorJobResult[]): MustFixRou
   return items.length > 0 ? { items } : {};
 }
 
+function authoringDefect(text: string): boolean {
+  return /(?:불필요한\s*(?:경계|목표)|아직\s*없는\s*(?:부품|운영|배선)|미구현\s*(?:부품|운영|배선)|실물\s*전제|미래\s*가정|out[- ]of[- ]scope|not yet existing|future assumption)/iu.test(text);
+}
+
+function repeatedMustFix(text: string, taskId: string, history: readonly SupervisorRound[]): boolean {
+  const normalized = text.trim().replace(/\s+/gu, ' ').toLowerCase();
+  return history.filter((round) => round.mustFix?.items?.some((item) => item.taskId === taskId
+    && item.text.trim().replace(/\s+/gu, ' ').toLowerCase() === normalized)).length >= 1;
+}
+
+function reauthorObservation(results: readonly SupervisorJobResult[], history: readonly SupervisorRound[]): SupervisorReauthorObservation | undefined {
+  const reviewed = results.flatMap((result) => (result.reviewMustFix ?? []).map((text) => ({ result, text })));
+  if (!reviewed.length) return undefined;
+  const rounds = Math.max(...reviewed.map(({ result }) => result.rework?.rounds ?? 0));
+  const classified = reviewed.map(({ result, text }) => ({ result, text, authored: authoringDefect(text) }));
+  const triggered = classified.some(({ result, text }) => (result.rework?.rounds ?? 0) > 3
+    || repeatedMustFix(text, result.taskId, history));
+  if (!triggered) return undefined;
+  const round = Math.max(rounds, history.length + 1);
+  const classifications = classified.map(({ result, text, authored }) => ({
+    taskId: result.taskId, text, kind: authored ? 'authorship-defect' as const : 'code-defect' as const,
+    action: authored ? 'scope-reduction-fu' as const : 'must-fix' as const,
+  }));
+  const authored = classified.filter((item) => item.authored);
+  const targetPaths = [...new Set(authored.flatMap(({ result }) => result.targetPaths ?? []))];
+  const narrowedProposal = authored.length
+    ? `골·칸·시험에서 제거: ${authored.map(({ text }) => text).join(' · ')}`
+    : '현재 목표와 완료 경계에 한정하고 리뷰에서 확인된 코드 결함만 수정한다';
+  return {
+    round, classifications,
+    prescription: {
+      outcome: '부분 착지 + FU', narrowedProposal,
+      partialLanding: `현재 완결 가능한 범위만 착지한다${targetPaths.length ? ` — ${targetPaths.join(', ')}` : ''}`,
+      followUp: {
+        lane: 'REVIEW-ROUND-REAUTHOR-FU',
+        goalId: `reauthor-fu-${authored[0]?.result.prNumber ?? authored[0]?.result.taskId ?? 'unbound'}`,
+        feature: `저작 결함을 제외한 완결 범위를 구현하고 검증한다 — ${narrowedProposal}`,
+        targetPaths,
+        completionBoundary: targetPaths.length ? `대상 경로: ${targetPaths.join(', ')}; 완료 경계: 해당 경로 내 범위` : '대상 경로 및 완료 경계는 다음 저작에서 재접지한다',
+        mockScenarioId: 'MS-03',
+        mockScenario: {
+          id: 'MS-03',
+          injection: `기존 리뷰 결과 주입: ${authored.map(({ text }) => text).join(' · ') || '반복 must-fix 재검토'}`,
+          observation: '제외된 저작 결함이 must-fix 목록에 없고, 부분 착지 및 FU 완료 경계가 관측된다',
+        },
+      },
+    },
+  };
+}
+
+function reauthorMustFixes(results: readonly SupervisorJobResult[], observation: SupervisorReauthorObservation | undefined): SupervisorJobResult[] {
+  if (!observation) return [...results];
+  const excluded = new Map<string, Set<string>>();
+  for (const item of observation.classifications) {
+    if (item.kind !== 'authorship-defect') continue;
+    const texts = excluded.get(item.taskId) ?? new Set<string>();
+    texts.add(item.text);
+    excluded.set(item.taskId, texts);
+  }
+  return results.map((result) => ({ ...result,
+    reviewMustFix: (result.reviewMustFix ?? []).filter((text) => !excluded.get(result.taskId)?.has(text)),
+  }));
+}
+
 /**
  * REVIEW-MUSTFIX-CLASSIFY — per-task class. `prev` is the preceding round's items of the same task or its repair
  * lineage (`oscillationRepairOf`), and only when that preceding round authored a repair for it — «수리 뒤 같은 지적»
@@ -470,8 +555,9 @@ type DecideNextRunInput = {
 };
 
 function decideNextRunCore(input: DecideNextRunInput): SupervisorDecision {
-  const results = [...input.results];
   const history = [...(input.history ?? [])];
+  const reauthor = reauthorObservation(input.results, history);
+  const results = reauthorMustFixes(input.results, reauthor);
   const maxRounds = input.limits?.maxRounds ?? DEFAULT_MAX_ROUNDS;
   const stallRounds = input.limits?.stallRounds ?? DEFAULT_STALL_ROUNDS;
   const observation = input.deliverableObservation
@@ -537,6 +623,7 @@ function decideNextRunCore(input: DecideNextRunInput): SupervisorDecision {
     deliverableUnmeasured: t.deliverableUnmeasured,
     deliverableMergeCompleteness,
     reviewMustFixTrend,
+    ...(reauthor ? { reauthor } : {}),
     rerunnable: t.rerunnable,
     reworkable: t.reworkable,
     decomposable: t.decomposable,
@@ -983,6 +1070,7 @@ export function appendRound(
     ...(baseCompleted > 0 || base !== undefined ? { baseCompleted, ...(base === undefined ? {} : { base }) } : {}),
     actionable: countActionable(t),
     ...(reviewMustFixTrend === undefined ? {} : { reviewMustFixTrend }),
+    ...(decision?.reauthor ? { reauthor: decision.reauthor } : {}),
     ...((mustFix.items ?? []).length > 0 ? { mustFix } : {}),
     ...(Object.keys(lostTimeMsByTask).length > 0 ? { lostTimeMsByTask } : {}),
     ...(unknownTimeTaskIds.size > 0 ? { unknownTimeTaskIds: [...unknownTimeTaskIds] } : {}),
@@ -1250,6 +1338,55 @@ export interface SuperviseRunOptions {
   }>;
 }
 
+/** Adapt REVIEW-ROUND-REAUTHOR's decision into an observation without duplicating its classification logic. */
+export function supervisorReauthorRequestObservations(
+  decision: SupervisorDecision,
+  parentRunId: string | null,
+  results: readonly SupervisorJobResult[],
+  resolveAuthorRunId: (ledgerRunId: string) => string | null = (ledgerRunId) => {
+    try {
+      const entries = loadRunLedger(ledgerRunId);
+      for (const entry of [...(entries ?? [])].reverse()) {
+        const authorRunId = entry.event === 'goal-authored' ? entry.data.authorRunId : undefined;
+        if (typeof authorRunId === 'string' && authorRunId.trim()) return authorRunId;
+      }
+    } catch { /* an absent or unreadable lineage ledger leaves this event unjoined */ }
+    return null;
+  },
+): Array<{ event: 'supervisor.reauthor-request' | 'supervisor.reauthor-unjoined'; data: Record<string, unknown> }> {
+  const reauthor = decision.reauthor;
+  if (!reauthor) return [];
+  return reauthor.classifications.flatMap((classification): Array<{ event: 'supervisor.reauthor-request' | 'supervisor.reauthor-unjoined'; data: Record<string, unknown> }> => {
+    if (classification.kind !== 'authorship-defect') return [];
+    const result = results.find((candidate) => candidate.taskId === classification.taskId);
+    const sourceReviewRunId = result?.runId;
+    const authorRunId = (parentRunId ? resolveAuthorRunId(parentRunId) : null)
+      ?? (sourceReviewRunId ? resolveAuthorRunId(sourceReviewRunId) : null);
+    if (!authorRunId) return [{
+      event: 'supervisor.reauthor-unjoined',
+      data: {
+        ...(parentRunId ? { parentRunId } : {}),
+        ...(sourceReviewRunId ? { sourceReviewRunId } : {}),
+        taskId: classification.taskId,
+        attempt: reauthor.round,
+        classification: 'authorship-defect',
+        reason: 'author-run-id-unresolved',
+      },
+    }];
+    return [{
+      event: 'supervisor.reauthor-request' as const,
+      data: {
+        conversationId: authorRunId,
+        runId: authorRunId,
+        ...(parentRunId ? { parentRunId } : {}),
+        ...(sourceReviewRunId ? { sourceReviewRunId } : {}),
+        attempt: reauthor.round,
+        classification: 'authorship-defect',
+      },
+    }];
+  });
+}
+
 type SupervisorStopStorageSource = 'operator-dir' | 'run-store-dir' | 'process-default';
 
 function resolveSupervisorStopStorage(runStore: SuperviseRunOptions['runStore']): {
@@ -1345,6 +1482,15 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
         ...(allUnreviewedAreNoDiff ? { reviewReason: 'no-diff' } : {}),
       } : {}),
     });
+    if (decision.reauthor) {
+      try {
+        opts.observe?.('review.reauthor', {
+          round: decision.reauthor.round,
+          classifications: decision.reauthor.classifications,
+          prescription: decision.reauthor.prescription,
+        });
+      } catch { /* fail-open */ }
+    }
     if (chartRunId) {
       recordRunChartDecision({ runId: chartRunId, device: 'outer-supervisor',
         stopKey: `${chartRunId}:outer-supervisor:${history.length + 1}`, observed: `results=${results.length}`,
@@ -1382,6 +1528,10 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
 
     const runId = chartRunId;
 
+    for (const request of supervisorReauthorRequestObservations(decision, runId, results)) {
+      try { opts.observe?.(request.event, request.data); } catch { /* observation is fail-soft */ }
+    }
+
     let decomposePromotion: DecomposePromotionObservation = decision.decomposable.length === 0
       ? { attempted: false, reason: 'no-decomposable-decision' }
       : decision.action === 'stop'

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

@@ -10,7 +10,7 @@ import type { LLMUsage } from '../prompt-cache/types.js';
 import { debug } from '../debug/log.js';
 import { ensureDeviceFirstSteps, inspectDeviceFirstGoal } from './device-first.js';
 import { COMPLETION_BOUNDARY_STEP_PREFIX, FOLDED_DEVICE_FIRST_ACTION_MARKER } from './goal-author-decompose.js';
-import { loadMockScenarioCatalog, type MockScenarioDevice, type MockScenarioEntry } from '../ux-sim/mock-scenario-catalog.js';
+import { loadMockScenarioCatalog, type MockScenarioCatalog, type MockScenarioDevice, type MockScenarioEntry } from '../ux-sim/mock-scenario-catalog.js';
 
 function observeGoalAuthor(
   category: 'goal-author' | 'goal-author.clarify',
@@ -81,10 +81,12 @@ export interface GoalAuthorDeps {
   ground: (ask: string, groundingDeps?: GoalAuthorGroundingDeps) => Promise<CodebaseGrounding>;
   persistentGrounding?: GoalAuthorGroundingDeps;
   authorGrade?: GoalAuthorGradeSelection;
+  /** Read-only, compact inventory of reusable mocks and event-injection scenarios. */
+  mockScenarioCatalog?: string;
   /** Production Terra reviewer precheck; omitted is disabled unless the shared config switch is on. */
   reviewerPrecheckEnabled?: boolean;
   /** Optional seam for focused tests; production uses the pinned Terra medium reviewer. */
-  reviewerPrecheck?: (document: string, authorRunId: string) => Promise<GoalAuthorReviewerPrecheckResult>;
+  reviewerPrecheck?: (document: string, authorRunId: string, context?: GoalAuthorReviewerPrecheckContext) => Promise<GoalAuthorReviewerPrecheckResult>;
   enhance: (ask: string, opts?: EnhanceOpts) => Promise<GoalEnhancement>;
   /** Additive enhancer options supplied by the file-writing entrypoint. */
   enhanceOpts?: EnhanceOpts;
@@ -154,6 +156,23 @@ export interface GoalAuthorReviewerPrecheckResult {
   readonly unappliedItems: readonly string[];
 }
 
+export interface GoalAuthorReviewerPrecheckContext {
+  readonly conversationId: string;
+  readonly round: number;
+  readonly priorRejectionReasonCodes: readonly string[];
+}
+
+export type GoalAuthorReviewerDialogOutcome = 'skipped' | 'converged' | 'cap-hit' | 'provider-error';
+
+export interface GoalAuthorReviewerDialogResult {
+  readonly document: string;
+  readonly status: 'skipped' | 'completed' | 'rejected-soft' | 'failed-soft';
+  readonly outcome: GoalAuthorReviewerDialogOutcome;
+  readonly rounds: number;
+  readonly hitl: boolean;
+  readonly result?: GoalAuthorReviewerPrecheckResult;
+}
+
 const GOAL_AUTHOR_REVIEWER_PRECHECK_MODEL = 'gpt-6.1-terra';
 
 export function parseGoalAuthorReviewerPrecheck(raw: string): GoalAuthorReviewerPrecheckResult {
@@ -240,7 +259,7 @@ export function resolveGoalAuthorReviewerPrecheckEnabled(config = getUserConfig(
 
 export async function runGoalAuthorReviewerPrecheck(
   document: string,
-  deps: { config?: ReturnType<typeof getUserConfig>; stream?: typeof streamLLM } = {},
+  deps: { config?: ReturnType<typeof getUserConfig>; stream?: typeof streamLLM; reviewContext?: GoalAuthorReviewerPrecheckContext; mockScenarioCatalog?: string } = {},
 ): Promise<GoalAuthorReviewerPrecheckResult> {
   const config = deps.config ?? getUserConfig();
   const pinnedConfig = {
@@ -250,7 +269,12 @@ export async function runGoalAuthorReviewerPrecheck(
   const provider = getProviderForConfig(pinnedConfig, GOAL_AUTHOR_REVIEWER_PRECHECK_MODEL);
   const prompt = [
     'Review this completed goal document before it is written. Return only JSON with string-array fields suggestions, fixes, remainingNeedsHuman, a fixEvidence array of { fix, originalText, revisedText }, and a revisedDocument string.',
+    'Challenge each completion-boundary constraint instead of treating it as inherently necessary. 제약을 의심하라: 저작 문면의 세계와 구현의 세계에서 같은 제약인가? 카탈로그에 있는 목장치나 사건 주입으로 같은 동작을 관찰할 수 있는가? 실물 점검만 요구하는 경계라면 의도를 보존하는 목장치·주입 사건을 제안하라. Do not require a real-world inspection by default. Preserve a live check when the ask explicitly requires an external-system outcome.',
+    ...(deps.mockScenarioCatalog?.trim() ? ['Reusable mock-device and event-injection catalog (reference only, not a completion gate):', deps.mockScenarioCatalog.trim()] : []),
     'Apply each necessary fix to revisedDocument exactly once while preserving the original ask, GoalId, RootIntent, GoalType, every existing criterion and scope boundary, and canonical section structure. Be strictly conservative: only append one complete sentence copied verbatim from the original ask to an existing acceptance-criteria or required-evidence line; never append a partial substring or clause, especially one inside a negation or condition, and do not delete or reword existing text, add new scope, or edit other sections. For every fixes item, include one fixEvidence object in the same order: fixes item and fix must both equal the exact complete sentence appended from the original ask; originalText and revisedText must be exact spans where revisedText starts with originalText and appends that sentence, and replaying every single replacement reproduces the complete revisedDocument with no other edits. If you cannot explain and ground every change this way, return no fixes and leave revisedDocument byte-for-byte unchanged. Keep optional suggestions separate; list unresolved decisions or evidence as remainingNeedsHuman.',
+    ...(deps.reviewContext ? [
+      `Author feedback for round ${deps.reviewContext.round}: prior proposal rejection codes = ${deps.reviewContext.priorRejectionReasonCodes.join(', ') || '(none)'}. Reconsider only those rejected proposals; do not repeat an unsupported edit.`,
+    ] : []),
     document,
   ].join('\n\n');
   const messages: LLMMessage[] = [{ role: 'user', content: prompt }];
@@ -274,15 +298,16 @@ export async function executeGoalAuthorReviewerPrecheck(
   enabled: boolean,
   document: string,
   authorRunId: string,
-  run: (document: string) => Promise<GoalAuthorReviewerPrecheckResult> = (value) => runGoalAuthorReviewerPrecheck(value),
+  run: (document: string, context?: GoalAuthorReviewerPrecheckContext) => Promise<GoalAuthorReviewerPrecheckResult> = (value) => runGoalAuthorReviewerPrecheck(value),
   observe: (event: string, data: Record<string, unknown>) => void = (event, data) => debug.log('author.reviewer-precheck', event, data),
+  context?: GoalAuthorReviewerPrecheckContext,
 ): Promise<{ status: 'skipped' | 'completed' | 'rejected-soft' | 'failed-soft'; result?: GoalAuthorReviewerPrecheckResult }> {
   if (!enabled) {
     observe('precheck-skipped', { authorRunId, reason: 'disabled', providerCalls: 0 });
     return { status: 'skipped' };
   }
   try {
-    const proposed = await run(document);
+    const proposed = await run(document, context);
     const evidence = proposed.fixEvidence ?? [];
     let replayed = document;
     let fixesSupported = proposed.fixes.length === 0
@@ -346,12 +371,131 @@ export async function executeGoalAuthorReviewerPrecheck(
   }
 }
 
+/** Run a bounded reviewer→author dialogue; every proposal remains grounded by the existing exact-edit validator. */
+export async function executeGoalAuthorReviewerDialog(
+  enabled: boolean,
+  document: string,
+  conversationId: string,
+  run: (document: string, context: GoalAuthorReviewerPrecheckContext) => Promise<GoalAuthorReviewerPrecheckResult> = (value, context) => runGoalAuthorReviewerPrecheck(value, { reviewContext: context }),
+  observe: (event: string, data: Record<string, unknown>) => void = (event, data) => debug.log('author.dialog', event, data),
+): Promise<GoalAuthorReviewerDialogResult> {
+  const emit = (event: string, data: Record<string, unknown>): void => {
+    try { observe(event, data); } catch { /* observability never changes author output */ }
+  };
+  let currentDocument = document;
+  let lastResult: GoalAuthorReviewerPrecheckResult | undefined;
+  let status: GoalAuthorReviewerDialogResult['status'] = 'completed';
+  let outcome: GoalAuthorReviewerDialogOutcome = 'converged';
+  let rolledBack = false;
+  let rounds = 0;
+  let hitl = false;
+  let priorRejectionReasonCodes: string[] = [];
+  const allSuggestions: string[] = [];
+  const allFixes: string[] = [];
+  const allFixEvidence: NonNullable<GoalAuthorReviewerPrecheckResult['fixEvidence']>[number][] = [];
+  const allAppliedFixes: string[] = [];
+  const allUnappliedItems: string[] = [];
+  const allRemainingNeedsHuman: string[] = [];
+
+  if (!enabled) {
+    emit('author.reviewer-precheck.skipped', { authorRunId: conversationId, conversationId, runId: conversationId, reason: 'disabled', providerCalls: 0 });
+    return { document, status: 'skipped', outcome: 'skipped', rounds: 0, hitl: false };
+  }
+
+  for (let round = 1; round <= 2; round += 1) {
+    rounds = round;
+    const context: GoalAuthorReviewerPrecheckContext = { conversationId, round, priorRejectionReasonCodes };
+    const response = await executeGoalAuthorReviewerPrecheck(
+      true,
+      currentDocument,
+      conversationId,
+      (candidate, receivedContext) => run(candidate, receivedContext ?? context),
+      (event, data) => emit(`author.reviewer-precheck.${event}`, data),
+      context,
+    );
+    status = response.status;
+    lastResult = response.result ?? lastResult;
+    if (response.status === 'failed-soft') {
+      outcome = 'provider-error';
+      currentDocument = document;
+      rolledBack = allAppliedFixes.length > 0;
+      break;
+    }
+    if (!response.result) break;
+
+    const result = response.result;
+    allSuggestions.push(...result.suggestions);
+    allFixes.push(...result.fixes);
+    allFixEvidence.push(...(result.fixEvidence ?? []));
+    allAppliedFixes.push(...result.appliedFixes);
+    allUnappliedItems.push(...result.unappliedItems);
+    allRemainingNeedsHuman.push(...result.remainingNeedsHuman);
+    const proposalCount = result.fixes.length;
+    const appliedCount = result.appliedFixes.length;
+    const rejectedCount = result.unappliedItems.length;
+    const reasonCodes = rejectedCount > 0 ? ['fix-not-grounded'] : [];
+    emit('author.reviewer.round', {
+      conversationId,
+      runId: conversationId,
+      round,
+      proposalCount,
+      appliedCount,
+      rejectedCount,
+      rejectionReasonCodes: reasonCodes,
+    });
+    if (response.status === 'completed') currentDocument = result.revisedDocument;
+
+    const unresolved = rejectedCount > 0 || result.remainingNeedsHuman.length > 0;
+    if (!unresolved && appliedCount === 0) {
+      outcome = 'converged';
+      break;
+    }
+    priorRejectionReasonCodes = reasonCodes;
+    if (round === 2) {
+      outcome = 'cap-hit';
+      hitl = true;
+    }
+  }
+
+  emit('author.dialog.closed', { conversationId, runId: conversationId, outcome, rounds, hitl });
+  const aggregatedResult = lastResult ? {
+    ...lastResult,
+    suggestions: [...new Set(allSuggestions)],
+    fixes: [...new Set(allFixes)],
+    fixEvidence: allFixEvidence,
+    appliedFixes: rolledBack ? [] : [...new Set(allAppliedFixes)],
+    unappliedItems: [...new Set([...allUnappliedItems, ...(rolledBack ? allAppliedFixes : [])])],
+    remainingNeedsHuman: [...new Set([...allRemainingNeedsHuman, ...(rolledBack ? allAppliedFixes : [])])],
+    revisedDocument: currentDocument,
+  } : undefined;
+  return {
+    document: currentDocument,
+    status,
+    outcome,
+    rounds,
+    hitl,
+    ...(aggregatedResult ? { result: aggregatedResult } : {}),
+  };
+}
+
 export type GoalAuthorGroundingPath = 'groundMissionInCodebase';
 
 export interface GoalAuthorGroundingDeps {
   /** Omit to preserve persistent grounding; false makes the authoring experiment opt out. */
   persistent?: false;
-  groundMission?: (ask: string, deps: { cwd: string; seedPaths?: readonly string[]; persistent?: false }) => Promise<CodebaseGrounding>;
+  groundMission?: (ask: string, deps: { cwd: string; seedPaths?: readonly string[]; persistent?: false; mockScenarioCatalog?: string }) => Promise<CodebaseGrounding>;
+  /** Reference inventory for selecting existing mock devices during goal grounding. */
+  mockScenarioCatalog?: string;
+}
+
+/** Compact prompt view of the canonical catalog; detailed run evidence stays in the catalog itself. */
+export function renderGoalAuthorMockScenarioCatalog(catalog: MockScenarioCatalog = loadMockScenarioCatalog()): string {
+  return [
+    'Reusable mock devices (src/ux-sim/mock-scenario-catalog.json):',
+    ...catalog.devices.map((device) => `- ${device.id} (${device.name}): target=${device.target}; inputs=${device.inputs.join(', ')}; observes=${device.observations.join(', ')}; entry=${device.entryCommands.join(' | ')}`),
+    'Reusable event-injection scenarios:',
+    ...catalog.scenarios.map((scenario) => `- ${scenario.id} (${scenario.kind}, device=${scenario.device}): trigger=${scenario.trigger}; observe=${scenario.observe.join(', ')}; expected=${scenario.expected}`),
+  ].join('\n');
 }
 
 export interface GoalAuthorGroundingResult {
@@ -912,7 +1056,9 @@ function behaviorTokens(value: string): Set<string> {
 
 function matchingScenarioBehaviorCount(scenario: MockScenarioEntry, ask: string): number {
   const { values } = inspectGoalDoneBoundary(ask);
-  const requestedText = `${values['완료 경계 코드'] ?? ''} ${values['완료 경계 실물'] ?? ''}`;
+  const requestedText = `${values['완료 경계 코드'] ?? ''} ${values['완료 경계 실물'] ?? ''}`
+    .replace(/(?:실물|실제)\s*(?:점검|검증|확인|테스트)\s*(?:으로|로)?/giu, '')
+    .replace(/real[- ]world\s+(?:check|inspection|verification|test)/giu, '');
   const describedText = `${scenario.name} ${scenario.kind} ${scenario.trigger} ${scenario.observe.join(' ')} ${scenario.expected}`;
   const requested = behaviorTokens(requestedText);
   const described = behaviorTokens(describedText);
@@ -925,7 +1071,11 @@ function matchingScenarioBehaviorCount(scenario: MockScenarioEntry, ask: string)
     ['harvestable', 'unharvestable'], ['independent', 'dependent'], ['succeeds', 'fails'], ['accepted', 'rejected'],
   ];
   const shared = [...described].filter((token) => requested.has(token));
+  const covered = new Set(described);
+  if (described.has('independent')) covered.add('distinct');
+  if (described.has('distinct')) covered.add('independent');
   if (shared.some((token) => polarity(requestedText, token) !== polarity(describedText, token))
+    || [...requested].some((token) => !covered.has(token))
     || oppositePairs.some(([left, right]) => (requested.has(left) && described.has(right)) || (requested.has(right) && described.has(left)))) return 0;
   return shared.length;
 }
@@ -944,12 +1094,13 @@ function nextGoalScenarioId(catalogIds: readonly string[], targets: readonly str
   return `${prefix}-${Date.now().toString(36).toUpperCase()}`;
 }
 
-function selectGoalMockStage(ask: string, targets: readonly string[]): { device: MockScenarioDevice; scenario?: MockScenarioEntry } | undefined {
+function selectGoalMockStage(ask: string, targets: readonly string[]): { device: MockScenarioDevice; scenario?: MockScenarioEntry; pathMatched: boolean } | undefined {
   const catalog = loadMockScenarioCatalog();
-  const device = catalog.devices
+  const matched = catalog.devices
     .map((candidate) => ({ candidate, score: matchingPathCount([...candidate.implementation, ...candidate.tests], targets) }))
     .filter((entry) => entry.score >= 2)
-    .sort((left, right) => right.score - left.score)[0]?.candidate
+    .sort((left, right) => right.score - left.score)[0];
+  const device = matched?.candidate
     ?? (/(?:author|goal|mission|저작|골|미션)/iu.test(`${targets.join(' ')}\n${ask}`)
       ? catalog.devices.find((candidate) => candidate.id === 'product-devices')
       : catalog.devices.find((candidate) => candidate.id === 'scenario-runner'));
@@ -959,7 +1110,14 @@ function selectGoalMockStage(ask: string, targets: readonly string[]): { device:
     .map((candidate) => ({ candidate, pathScore: matchingPathCount([...candidate.implementation, ...candidate.tests], targets), behaviorScore: matchingScenarioBehaviorCount(candidate, ask) }))
     .filter((entry) => entry.pathScore >= 2 && entry.behaviorScore >= 2)
     .sort((left, right) => right.behaviorScore - left.behaviorScore || right.pathScore - left.pathScore)[0]?.candidate;
-  return { device, ...(scenario ? { scenario } : {}) };
+  return { device, ...(scenario ? { scenario } : {}), pathMatched: Boolean(matched) };
+}
+
+function isGenericRealWorldInspectionBoundary(boundary: string, ask: string): boolean {
+  const combined = `${boundary}\n${ask}`;
+  const asksForRealInspection = /(?:실물\s*(?:점검|검증|확인|테스트)|실제\s*(?:점검|검증|확인|테스트)|real[- ]world\s+(?:check|inspection|verification|test)|live\s+(?:check|inspection|verification|test))/iu.test(boundary);
+  const namesExternalOutcome = /(?:외부\s*(?:시스템|서비스|서버|클러스터|API|데이터베이스|DB)|실서비스|운영\s*(?:시스템|서비스|서버|클러스터|API|데이터베이스|DB)|실제\s*(?:계정|결제|API|서버|클러스터|고객|사용자)|(?:고객|사용자|customer|client|recipient).{0,20}(?:메일|이메일|email|발송|전송|receive|send)|(?:메일|이메일|email).{0,20}(?:고객|사용자|customer|client|recipient|발송|전송|receive|send)|\b(?:external\s+(?:system|service|server|cluster|api|database|db)|(?:actual|real|live|production|staging|stage|external)\s+(?:[\w-]+\s+){0,2}(?:system|service|server|cluster|api|database|db)|(?:staging|stage|production|prod|test|dev)\s+(?:system|service|server|cluster|api|database|db)|database|db|email|mail|slack|discord|teams|telegram|webhook|channel|gcp\d+|github|stripe|aws|production\s+\w+|live\s+(?:api|service|server|cluster)|(?:posts?|sends?|publishes?|writes?|pushes?|creates?|deletes?|charges?|updates?|submits?|delivers?|notifies?)\b.{0,80}\b(?:to|on|into|against|via))\b)/iu.test(combined);
+  return asksForRealInspection && !namesExternalOutcome;
 }
 
 export function explicitGoalDoneBoundaryLines(ask: string, repositoryRoot?: string): string[] {
@@ -1002,6 +1160,17 @@ export function explicitGoalDoneBoundaryLines(ask: string, repositoryRoot?: stri
       lines.push(`- 시나리오: 신설 초안 (MS-id 후보: ${id})`);
       lines.push(`- 시나리오 초안: 사건은 ${targets.join(' · ') || '요청 대상'}에 «${requestedCode}» 경계를 적용한 입력; 기대는 생산 경로에서 «${requestedObservation}»을 관측하고 bun test ${plannedTestPath ?? '<대상 시험 파일>'}로 GREEN을 확인하는 것이다. 자식은 기존 카탈로그 API·ScenarioV0 형식에 맞춰 요청 대상의 사건·기대를 구체화해 등록한다.`);
     }
+    const realWorldBoundary = values['완료 경계 실물'];
+    if (realWorldBoundary && isGenericRealWorldInspectionBoundary(realWorldBoundary, ask) && mockStage?.pathMatched) {
+      const { device, scenario } = mockStage;
+      if (scenario) {
+        lines.push(`- 목장치 치환안: 완료 경계 실물의 일반 실물 점검을 ${device.id} (${device.name})로 대체 제안; 기존 사건 주입 ${scenario.id}: ${scenario.trigger}; 관측=${scenario.observe.join(' · ')}; 기대=${scenario.expected}`);
+      } else {
+        const requestedCode = values['완료 경계 코드'] ?? '요청 코드 경계';
+        const requestedObservation = values['완료 경계 실물'] ?? '요청된 생산 동작과 결과';
+        lines.push(`- 목장치 치환안: ${device.id} (${device.name}) 신규 ScenarioV0 초안·미등록; trigger=«${requestedCode}»가 참이 되도록 사건을 입력한다(카탈로그 입력 후보: ${device.inputs.join(' · ')}); observe=«${requestedObservation}»(관측 후보: ${device.observations.join(' · ')}); expected=«${requestedObservation}». 입력·관측 selector를 해당 요청과 맞춰 등록하고 회귀 시험으로 확인할 제안이다.`);
+      }
+    }
   }
   if (plannedTestPath) lines.push(`- 검증 계획(TDD): 장치 ${mockStage?.device.id ?? '미선정'} · 시나리오 ${mockStage?.scenario?.id ?? '신설 초안'} · ${needsNewTest ? '신설 시험' : '기존 시험에 요청 동작 회귀 사례 추가'} ${plannedTestPath} · 피처 시험 bun test ${plannedTestPath}를 구현 전에 RED로 확인한다.`);
   return lines;
@@ -6454,6 +6623,16 @@ async function authorGoalWithSupersededRootIntent(
   }
   // ⭐ 이 저작 «한 번»의 id. goalId 보다 «먼저» 있어야 ground·enhance 의 소요를 그 골에 붙일 수 있다.
   const authorRunId = generateGoalId();
+  if (deps.mockScenarioCatalog) {
+    try {
+      observeGoalAuthor('goal-author', 'mock-scenario-catalog-injected', {
+        authorRunId,
+        source: 'src/ux-sim/mock-scenario-catalog.json',
+        availableConsumers: ['ground', 'enhance', 'reviewer-precheck'],
+        contextChars: deps.mockScenarioCatalog.length,
+      });
+    } catch { /* observation must not change authoring */ }
+  }
   const authorGrade = deps.authorGrade ?? resolveGoalAuthorGrade(undefined, getUserConfig().harness?.authorGrade);
   const lite = authorGrade.grade === 'lite';
   // lite 는 판정선을 남기는 대신 단계를 덜 한다 — 요청에 반증 줄이 하나도 없으면 판정선 없는 골이 나가므로 시작 전에 멈춘다.
@@ -6480,7 +6659,10 @@ async function authorGoalWithSupersededRootIntent(
     const groundStartedAt = startGoalAuthorPhase('ground', authorRunId, deps.onProgress);
     const timeboxBudgetMs = deps.groundTimeboxMs ?? GOAL_AUTHOR_GROUND_TIMEBOX_MS;
     try {
-      const groundOutcome = await groundWithinTimebox(() => deps.ground(ask, persistentGrounding.deps), timeboxBudgetMs, groundStartedAt);
+      const groundOutcome = await groundWithinTimebox(() => deps.ground(ask, {
+        ...persistentGrounding.deps,
+        ...(deps.mockScenarioCatalog ? { mockScenarioCatalog: deps.mockScenarioCatalog } : {}),
+      }), timeboxBudgetMs, groundStartedAt);
       if ('timebox' in groundOutcome) {
         // ⛔ `groundingError` 를 «안» 쓴다 — 접지가 던진 것과 예산 초과로 끊긴 것은 다른 사건이고,
         //   처방도 다르다(앞은 채널 복구, 뒤는 더 좁은 ask/재시도). 두 값을 한 칸에 접으면 못 가른다.
@@ -6519,8 +6701,8 @@ async function authorGoalWithSupersededRootIntent(
       ? await deps.enhance(
         enhanceAsk,
         persistentFacts.length > 0
-          ? { ...deps.enhanceOpts, groundedFacts: persistentFacts, onUsage: onEnhanceUsage }
-          : { ...deps.enhanceOpts, onUsage: onEnhanceUsage },
+          ? { ...deps.enhanceOpts, groundedFacts: persistentFacts, onUsage: onEnhanceUsage, ...(deps.mockScenarioCatalog ? { mockScenarioCatalog: deps.mockScenarioCatalog } : {}) }
+          : { ...deps.enhanceOpts, onUsage: onEnhanceUsage, ...(deps.mockScenarioCatalog ? { mockScenarioCatalog: deps.mockScenarioCatalog } : {}) },
       )
       : { original: ask, checklist: [], verbatimPreserved: true };
     // ⭐ goal-context 규범이 «어디에도 안 실린다»는 것을 관측으로 남긴다.
@@ -7185,6 +7367,7 @@ export async function groundForGoalAuthor(
       cwd,
       seedPaths: askPathTokens(ask),
       ...(deps.persistent !== undefined ? { persistent: deps.persistent } : {}),
+      ...(deps.mockScenarioCatalog ? { mockScenarioCatalog: deps.mockScenarioCatalog } : {}),
     }),
   };
 }
@@ -7271,9 +7454,10 @@ async function runDefaultHelpProbe(cwd: string, argv: readonly string[]): Promis
  *   ⇒ 배선만 무는 테스트가 이것을 직접 부른다.
  */
 export function defaultGoalAuthorDeps(cwd: string): GoalAuthorDeps {
+  const mockScenarioCatalog = renderGoalAuthorMockScenarioCatalog();
   return {
     async ground(ask, groundingDeps) {
-      return (await groundForGoalAuthor(ask, cwd, groundingDeps)).facts;
+      return (await groundForGoalAuthor(ask, cwd, { ...groundingDeps, mockScenarioCatalog })).facts;
     },
     /**
      * ⭐⭐ 저작 경로는 체크리스트를 «완주 판정»이 아니라 «골 문서 재료»로 쓴다 — 그래서 용도를 밝힌다.
@@ -7287,8 +7471,9 @@ export function defaultGoalAuthorDeps(cwd: string): GoalAuthorDeps {
      *   이 칸을 «안 주므로» 기본값 `coverage-gate` 로 종전 문면을 그대로 받는다.
      */
     enhance(ask, opts) {
-      return enhancePrompt(ask, { ...opts, checklistUse: 'authoring', config: opts?.config ?? getUserConfig() });
+      return enhancePrompt(ask, { ...opts, mockScenarioCatalog, checklistUse: 'authoring', config: opts?.config ?? getUserConfig() });
     },
+    mockScenarioCatalog,
     readSourceFile: createRepositoryReferencedFileReader(cwd),
     runHelpProbe: (argv) => runDefaultHelpProbe(cwd, argv),
     selfResolveClarification: defaultGoalAuthorSelfResolve,
@@ -7409,17 +7594,17 @@ export async function writeAuthoredGoal(
         ...(supersededRootIntent !== null && { supersessionRootIntent: supersededRootIntent }),
       });
     const reviewerPrecheckEnabled = resolvedDeps.reviewerPrecheckEnabled ?? resolveGoalAuthorReviewerPrecheckEnabled();
-    const precheck = await executeGoalAuthorReviewerPrecheck(
+    const dialog = await executeGoalAuthorReviewerDialog(
       reviewerPrecheckEnabled,
       authored.document,
       authored.authorRunId,
-      (document) => (resolvedDeps.reviewerPrecheck
-        ? resolvedDeps.reviewerPrecheck(document, authored.authorRunId)
-        : runGoalAuthorReviewerPrecheck(document)),
+      (document, context) => (resolvedDeps.reviewerPrecheck
+        ? resolvedDeps.reviewerPrecheck(document, authored.authorRunId, context)
+        : runGoalAuthorReviewerPrecheck(document, { reviewContext: context, mockScenarioCatalog: resolvedDeps.mockScenarioCatalog })),
     );
-    if (precheck.result) {
-      authored.reviewerPrecheck = precheck.result;
-      if (precheck.status === 'completed') authored.document = precheck.result.revisedDocument;
+    authored.document = dialog.document;
+    if (dialog.result) {
+      authored.reviewerPrecheck = dialog.result;
     }
     const stampedAt = fileDeps.now?.() ?? new Date();
   const identity = identityLines(ask, cwd, fileDeps.env ?? process.env, stampedAt);