elanous 0.2.13 → 0.2.15

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

@@ -31,8 +31,32 @@
 import { importerTestsNotInRunSet, type ImporterTestIndex } from './importer-test-index.js';
 import type { RouteConsumerTestIndex } from './route-consumer-test-index.js';
 import { rankGateCallerCandidates } from './gate-candidate-ranking.js';
+import { debug } from '../debug/log.js';
 
 export const GATE_CALLER_TEST_LIMIT = 30;
+
+/** Command registries and their non-import-linked gate companions. Kept outside the caller cap. */
+const PAIRED_REGISTRY_TESTS = {
+  registries: [
+    'src/chat/index.ts',
+    'src/telegram-commands.ts',
+    'src/discord-slash-wire.ts',
+    'src/index.ts',
+  ],
+  tests: [
+    'src/maturity/feature-maturity.test.ts',
+    'src/maturity/tui-slash-maturity.test.ts',
+    'src/maturity/bot-command-maturity.test.ts',
+    'src/maturity/cli-maturity.test.ts',
+    'test/slash-filter.test.ts',
+    'test/bot-slash-parity.test.ts',
+  ],
+} as const;
+
+/** 게이트 로그와 PR Gate 절에서 공통으로 쓰는 미검증 경고(파일 목록은 자르지 않는다). */
+export function formatNoRelatedTestsWarning(files: readonly string[]): string {
+  return `⚠️ 동작 검증 0: ${files.join(', ')} — 사람 확인 필요`;
+}
 export type GateCallerReason = 'import' | 'route';
 
 /** 테스트 파일 판정(기존 `seams.ts` 정규식과 동일 — 어휘 분기 금지). */
@@ -225,7 +249,7 @@ export function deriveRelatedTests(
 /** 왜 이 범위로 돌았나 — 로그만으로 답할 수 있게 하는 관측 필드(제1원칙).
  *  ⚠️ 비-export 유지(리뷰 must-fix) — 소비처가 이 모듈 안뿐이다. 구조적 사용(호출부의 `scope.reason`)은
  *  export 없이도 성립하므로 불필요한 공개 surface 를 만들지 않는다. */
-type GateScopeReason = 'changed-tests' | 'derived' | 'no-changes' | 'docs-only' | 'no-related-tests' | 'unmeasured';
+type GateScopeReason = 'changed-tests' | 'derived' | 'paired-registry' | 'no-changes' | 'docs-only' | 'no-related-tests' | 'unmeasured';
 
 export type GateScopeMode = 'worktree' | 'postsync';
 
@@ -279,7 +303,7 @@ export function resolveGateScope(
   changed: readonly string[],
   exists: (path: string) => boolean,
   importerTestIndex?: ImporterTestIndex,
-  opts?: { mode?: GateScopeMode; isDeleted?: (path: string) => boolean; routeConsumerTestIndex?: RouteConsumerTestIndex },
+  opts?: { mode?: GateScopeMode; isDeleted?: (path: string) => boolean; routeConsumerTestIndex?: RouteConsumerTestIndex; runChanged?: readonly string[]; round?: number },
 ): GateScopeDecision {
   // ⚠️ **실존 검증(리뷰 must-fix 4R)** — `gitChangedFiles` 는 `git diff --name-only HEAD` 라
   //   **삭제·rename 前 경로도 포함**한다. 그걸 그대로 `testArgs` 로 넘기면 필터가 아무것도 매치하지
@@ -292,9 +316,9 @@ export function resolveGateScope(
   const missingTestFiles = changedTests.length - testFiles.length;
   const sourceFiles = userChanged.filter((f) => SOURCE_RE.test(f));
   const ignoredOutsideSrc = sourceFiles.filter((f) => !isTestFile(f) && !f.startsWith('src/')).length;
-  /** ⭐ **문서가 아닌 사용자 변경** — 이게 비어야 docs-only 다(소스 부재가 아니라 **문서 전부**여야 한다). */
-  const documentPaths = userChanged.filter(isDocPath);
-  const nonDoc = userChanged.filter((f) => !isDocPath(f));
+  /** ⭐ **문서가 아닌 사용자 변경** — 시험 파일도 명시적으로 docs-only 대상에서 제외한다. */
+  const documentPaths = userChanged.filter((f) => isDocPath(f) && !isTestFile(f));
+  const nonDoc = userChanged.filter((f) => isTestFile(f) || !isDocPath(f));
   /**
    * ⭐ **이 변경 중 무엇이 검증되지 않나** — 분기와 **무관하게** 계산한다(리뷰 must-fix 2026-07-27).
    *
@@ -323,6 +347,8 @@ export function resolveGateScope(
     if (runSet.includes(f)) return true;
     if (opts?.isDeleted?.(f)) return true;
     if (importerTestIndex && (importerTestIndex.testsBySource.get(f) ?? []).some((t) => runSet.includes(t))) return true;
+    if (PAIRED_REGISTRY_TESTS.registries.some((registry) => registry === f)
+      && PAIRED_REGISTRY_TESTS.tests.some((test) => runSet.includes(test))) return true;
     const related = relatedFor(f);
     return related.length > 0 && related.every((t) => runSet.includes(t));
   };
@@ -354,7 +380,9 @@ export function resolveGateScope(
     importerTestIndex?.testsBySource ?? new Map());
   const callerTests = candidates.slice(0, GATE_CALLER_TEST_LIMIT);
   const callerTestsOverflow = candidates.slice(GATE_CALLER_TEST_LIMIT);
-  const runWithCallers = (tests: readonly string[]) => [...new Set([...tests, ...callerTests.map(({ file }) => file)])];
+  const pairedRegistryTests = userChanged.some((file) => PAIRED_REGISTRY_TESTS.registries.some((registry) => registry === file))
+    ? PAIRED_REGISTRY_TESTS.tests.filter(exists) : [];
+  const runWithCallers = (tests: readonly string[]) => [...new Set([...tests, ...callerTests.map(({ file }) => file), ...pairedRegistryTests])];
   const base = { sourceFiles, documentPaths, ignoredOutsideSrc, missingTestFiles, elanousRuntimeArtifacts, callerTests, callerTestsOverflow,
     unverified: [] as readonly string[], derived: [] as readonly string[], pulledInRelatedTests: [] as readonly string[] };
   const withDocumentNonContribution = (runSet: readonly string[]) => ({
@@ -381,8 +409,17 @@ export function resolveGateScope(
   const derived = conventional;
   const runSet = runWithCallers(derived);
   if (runSet.length > 0) {
-    return { ...base, ...withDocumentNonContribution(runSet), derived, testArgs: runSet, unverified: unverifiedFor(runSet), importerTestsNotRun: observationFor(runSet), skipTestStep: false, reason: 'derived' };
+    return { ...base, ...withDocumentNonContribution(runSet), derived, testArgs: runSet, unverified: unverifiedFor(runSet), importerTestsNotRun: observationFor(runSet), skipTestStep: false, reason: derived.length === 0 && callerTests.length === 0 ? 'paired-registry' : 'derived' };
+  }
+  // 마지막 라운드에 짝이 없어도 원 PR의 앞 라운드에서 편집한 소스·시험을 같은 규칙으로 한 번 더 잰다.
+  if (opts?.runChanged?.some((file) => !changed.includes(file))) {
+    const wholeRun = resolveGateScope([...new Set([...changed, ...opts.runChanged])], exists, importerTestIndex,
+      { ...opts, runChanged: undefined });
+    return wholeRun;
   }
-  // 실행 집합이 비었으므로 비문서 전부가 미검증이다.
-  return { ...base, ...withDocumentNonContribution([]), unverified: unverifiedFor([]), importerTestsNotRun: observationFor([]), skipTestStep: true, reason: 'no-related-tests' };
+  const unverified = unverifiedFor([]);
+  try {
+    debug.log('self-implement.gate-scope', 'no-related-tests', { files: unverified, round: opts?.round ?? null }, { level: 'warn' });
+  } catch { /* 관측 장애는 게이트 판정을 바꾸지 않는다. */ }
+  return { ...base, ...withDocumentNonContribution([]), unverified, importerTestsNotRun: observationFor([]), skipTestStep: true, reason: 'no-related-tests' };
 }

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

@@ -0,0 +1,222 @@
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+import { isGoalAuthorFileName } from './goal-document.js';
+import { hasTerminalRunStatus, loadRunLedger, queryUnfinishedRunLedgers, runLedgerDir } from './run-ledger.js';
+
+export interface GoalArchiveOptions {
+  repoRoot?: string;
+  stateRoot?: string;
+  before?: string;
+  apply?: boolean;
+  trustDocRecord?: boolean;
+  /** Failure-injection seam for the two write stages (copy · index); defaults use the real filesystem.
+   *  The repository is never written: removing the originals is a human PR from `filesForPr`. */
+  writes?: {
+    copy?: (source: string, destination: string) => void;
+    appendIndex?: (path: string, line: string) => void;
+  };
+}
+
+export interface GoalArchiveEntry {
+  goalId: string;
+  runId: string;
+  pr: number | null;
+  outcome: 'merged' | 'abandoned' | 'superseded';
+  source: 'ledger' | 'doc-record';
+  originalPath: string;
+  archivePath: string;
+}
+
+export interface GoalArchiveResult {
+  candidates: GoalArchiveEntry[];
+  applied: GoalArchiveEntry[];
+  skipped: Record<string, number>;
+  trustDocRecordAdds: number;
+  filesForPr: string[];
+}
+
+function gitRead(root: string, ...args: string[]): string {
+  return execFileSync('git', args, {
+    cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+  });
+}
+
+function applyArchiveEntry(index: string, source: string,
+  entry: GoalArchiveEntry, document: string, writes: GoalArchiveOptions['writes']): void {
+  const directory = dirname(entry.archivePath);
+  const hadDirectory = existsSync(directory);
+  const priorIndex = existsSync(index) ? readFileSync(index) : null;
+  let ownedCopy = false;
+  let indexAttempted = false;
+  try {
+    mkdirSync(directory, { recursive: true });
+    const reservation = openSync(entry.archivePath, 'wx');
+    ownedCopy = true;
+    closeSync(reservation);
+    (writes?.copy ?? copyFileSync)(source, entry.archivePath);
+    if (readFileSync(entry.archivePath, 'utf8') !== document) throw new Error(`archive copy mismatch: ${entry.originalPath}`);
+    indexAttempted = true;
+    (writes?.appendIndex ?? ((path, line) => appendFileSync(path, line, 'utf8')))(index, `${JSON.stringify(entry)}\n`);
+  } catch (error) {
+    try {
+      if (indexAttempted) {
+        if (priorIndex === null) rmSync(index, { force: true });
+        else if (!readFileSync(index).equals(priorIndex)) writeFileSync(index, priorIndex);
+      }
+      if (ownedCopy) rmSync(entry.archivePath, { force: true });
+      if (ownedCopy && !hadDirectory && existsSync(directory)) rmdirSync(directory);
+    } catch (rollbackError) {
+      throw new Error(`archive failed for ${entry.originalPath}: ${String(error)}; recovery required (archive rollback: ${String(rollbackError)}). Preserve ${entry.archivePath} and ${index}; reconcile the index before retry.`);
+    }
+    throw error;
+  }
+}
+
+function beforeDate(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`))
+    || new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) !== value) {
+    throw new Error(`--before requires a valid YYYY-MM-DD date: ${value}`);
+  }
+  return value;
+}
+
+function ledgerGoalFileContradicts(goalFile: unknown, originalPath: string): boolean {
+  if (typeof goalFile !== 'string' || !goalFile.trim()) return false;
+  const normalized = goalFile.replaceAll('\\', '/');
+  return normalized !== originalPath && !normalized.endsWith(`/${originalPath}`);
+}
+
+function lastExecution(document: string): Record<string, string> | null {
+  const sections = document.split(/^## 실행 기록\s*$/m).slice(1);
+  const block = sections.at(-1)?.split(/^#{1,2} /m, 1)[0];
+  const run = block?.split(/^- runId: /m).slice(1).at(-1);
+  if (!run) return null;
+  const id = run.split(/\r?\n/, 1)[0]?.trim();
+  if (!id) return null;
+  const fields: Record<string, string> = { runId: id };
+  for (const [, key, value] of run.matchAll(/^  (stage|outcome|prNumber|completedAt): ([^\r\n]*)$/gm)) fields[key!] = value!.trim();
+  return fields;
+}
+
+/** Preview by default. --apply only copies to the state archive and indexes; it never removes or stages anything in the repository —
+ *  `filesForPr` is the list a human removes in one PR. A missing ledger requires explicit trust in the document's finished-run record. */
+export function archiveGoals(options: GoalArchiveOptions = {}): GoalArchiveResult {
+  const root = resolve(options.repoRoot ?? gitRead(process.cwd(), 'rev-parse', '--show-toplevel').trim());
+  const state = resolve(options.stateRoot ?? elanousStateRoot());
+  const cutoff = beforeDate(options.before);
+  const goals = join(root, 'docs', 'goals');
+  const archive = join(state, 'goal-archive');
+  const index = join(archive, 'index.jsonl');
+  const result: GoalArchiveResult = { candidates: [], applied: [], skipped: {}, trustDocRecordAdds: 0, filesForPr: [] };
+  const skip = (reason: string): void => { result.skipped[reason] = (result.skipped[reason] ?? 0) + 1; };
+  const lock = join(archive, '.apply.lock');
+  if (options.apply) {
+    mkdirSync(archive, { recursive: true });
+    try { mkdirSync(lock); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      throw new Error(`EEXIST: goal archive --apply is already running or a previous run stopped mid-way (${lock}). `
+        + `If no other archive is running: compare ${index} with ${archive}/<YYYY-MM>/ copies, drop index lines whose copy is missing, then remove ${lock} and retry.`);
+    }
+  }
+  try {
+    const tracked = new Set(gitRead(root, 'ls-files', '-z', '--', 'docs/goals').split('\0').filter(Boolean));
+  const pendingRemovals = new Set(gitRead(root, 'diff', '--cached', '--name-only', '--diff-filter=D', '-z', '--', 'docs/goals').split('\0').filter(Boolean));
+  const unfinished = queryUnfinishedRunLedgers({ dir: runLedgerDir(state), goalsDir: goals, noCache: true });
+  if (unfinished.unreadableLedgerCount > 0) throw new Error('run ledger contains unreadable runs; archive refused');
+  const activePaths = new Set(unfinished.entries.filter((entry) => entry.goalDocumentPath)
+    .map((entry) => resolve(root, entry.goalDocumentPath!)));
+  const activeRunIds = new Set(unfinished.entries.map((entry) => entry.runId));
+  const indexed = new Set<string>();
+  if (existsSync(index)) {
+    for (const line of readFileSync(index, 'utf8').split('\n').filter(Boolean)) {
+      const entry = JSON.parse(line) as { originalPath: string };
+      indexed.add(entry.originalPath);
+    }
+  }
+  let names: string[];
+  try { names = readdirSync(goals).sort(); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    names = [];
+  }
+  for (const name of names) {
+    if (!isGoalAuthorFileName(name)) continue;
+    const path = join(goals, name);
+    const originalPath = relative(root, path).split(sep).join('/');
+    if (!tracked.has(originalPath) || pendingRemovals.has(originalPath)) { skip('untracked'); continue; }
+    const fileStat = lstatSync(path, { throwIfNoEntry: false });
+    if (!fileStat?.isFile() || fileStat.isSymbolicLink()) { skip('not-file'); continue; }
+    if (indexed.has(originalPath)) { skip('already-indexed'); continue; }
+    if (activePaths.has(path)) { skip('active-goal-run'); continue; }
+    const document = readFileSync(path, 'utf8');
+    const fields = lastExecution(document);
+    if (!fields) { skip('no-execution-record'); continue; }
+    const runId = fields.runId!;
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(runId)) { skip('invalid-run-id'); continue; }
+    if (activeRunIds.has(runId)) { skip('active-goal-run'); continue; }
+    const outcome = fields.stage === 'merged' && (fields.outcome === 'completed' || fields.outcome === 'merged') ? 'merged'
+      : fields.outcome === 'abandoned' ? 'abandoned'
+      : fields.outcome === 'superseded' ? 'superseded' : null;
+    if (!outcome) { skip('unfinished'); continue; }
+    let ledger;
+    try { ledger = loadRunLedger(runId, runLedgerDir(state)); }
+    catch (error) {
+      skip(error instanceof Error && /runId does not match /.test(error.message) ? 'ledger-run-id-mismatch' : 'unreadable-ledger');
+      continue;
+    }
+    const missingLedger = !ledger?.length;
+    if (missingLedger && (!fields.stage || !fields.outcome)) { skip('unfinished'); continue; }
+    const documentGoalId = /^- GoalId:\s*([0-9a-f]{16})\s*$/m.exec(document.split(/^## 실행 기록\s*$/m, 1)[0] ?? '')?.[1];
+    if (!documentGoalId) { skip('missing-goal-id'); continue; }
+    if (!missingLedger) {
+      const entries = ledger!;
+      const ledgerGoalIds = new Set(entries.map((entry) => entry.goalId).filter((id): id is string => typeof id === 'string'));
+      if (ledgerGoalIds.size !== 1 || !ledgerGoalIds.has(documentGoalId)) { skip('ledger-goal-id-mismatch'); continue; }
+      const starts = entries.filter((entry) => entry.event === 'start');
+      if (starts.length === 0 || starts.some((entry) => ledgerGoalFileContradicts(entry.data.goalFile, originalPath))) {
+        skip('ledger-goal-mismatch'); continue;
+      }
+    }
+    const latest = ledger?.filter((entry) => entry.event === 'run-status').at(-1);
+    if (!missingLedger) {
+      if (!latest || !hasTerminalRunStatus(ledger!) || !['completed', 'failed', 'cancelled'].includes(String(latest.data.runStatus))) {
+        skip('running-or-unconfirmed'); continue;
+      }
+      if (outcome === 'merged' && (latest.data.runStatus !== 'completed' || (latest.data.stage !== undefined && latest.data.stage !== 'merged'))
+        || outcome === 'abandoned' && latest.data.runStatus === 'completed'
+        || outcome === 'superseded' && latest.data.runStatus === 'failed') {
+        skip('status-mismatch'); continue;
+      }
+    }
+    const completedAt = missingLedger ? fields.completedAt : fields.completedAt ?? latest?.timestamp;
+    if (!completedAt || !Number.isFinite(Date.parse(completedAt))) { skip('no-completion-date'); continue; }
+    const date = new Date(completedAt).toISOString().slice(0, 10);
+    if (cutoff && date >= cutoff) { skip('after-before'); continue; }
+    const prRaw = fields.prNumber;
+    const pr = prRaw && /^[1-9]\d*$/.test(prRaw) && Number.isSafeInteger(Number(prRaw)) ? Number(prRaw) : null;
+    const archivePath = join(archive, date.slice(0, 7), basename(path));
+    if (existsSync(archivePath)) { skip('archive-collision'); continue; }
+    if (gitRead(root, 'status', '--porcelain', '--', originalPath).trim()) { skip('dirty'); continue; }
+    if (missingLedger && !options.trustDocRecord) { skip('missing-ledger'); result.trustDocRecordAdds += 1; continue; }
+    const entry: GoalArchiveEntry = { goalId: documentGoalId, runId, pr, outcome, source: missingLedger ? 'doc-record' : 'ledger', originalPath, archivePath };
+    result.candidates.push(entry);
+    if (options.apply) {
+      applyArchiveEntry(index, path, entry, document, options.writes);
+      result.applied.push(entry);
+      result.filesForPr.push(originalPath);
+    } else {
+      result.filesForPr.push(originalPath);
+    }
+  }
+  try { debug.log('harness.goal', 'archive', { candidates: result.candidates.length, applied: result.applied.length, skipped: result.skipped }); } catch { /* observation is fail-soft */ }
+  return result;
+  } finally {
+    if (options.apply) rmdirSync(lock);
+  }
+}

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

@@ -6,6 +6,7 @@ import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'no
 import { groundMissionInCodebase, isRepositoryImplementationCandidate, type CodebaseGrounding } from '../autopilot/mission-codebase-gate.js';
 import { extractSlugSource, generateMissionSlug, slugify } from '../autopilot/mission-registry.js';
 import { enhancePrompt, type EnhanceOpts, type EnhanceResult } from '../prompt-enhance/enhance.js';
+import type { LLMUsage } from '../prompt-cache/types.js';
 import { debug } from '../debug/log.js';
 
 function observeGoalAuthor(
@@ -324,9 +325,12 @@ function startGoalAuthorPhase(phase: GoalAuthorTimedPhase, authorRunId: string,
   return Date.now();
 }
 
-function endGoalAuthorPhase(phase: GoalAuthorTimedPhase, startedAt: number, authorRunId: string, onProgress?: GoalAuthorDeps['onProgress']): void {
+type GoalAuthorTokens = { inputTokens: number | null; outputTokens: number | null };
+const UNKNOWN_GOAL_AUTHOR_TOKENS: GoalAuthorTokens = { inputTokens: null, outputTokens: null };
+
+function endGoalAuthorPhase(phase: GoalAuthorTimedPhase, startedAt: number, authorRunId: string, onProgress?: GoalAuthorDeps['onProgress'], tokens: GoalAuthorTokens = UNKNOWN_GOAL_AUTHOR_TOKENS): void {
   const elapsedMs = Date.now() - startedAt;
-  observeGoalAuthor('goal-author', 'phase-end', { phase, authorRunId, elapsedMs });
+  observeGoalAuthor('goal-author', 'phase-end', { phase, authorRunId, elapsedMs, ...tokens });
   if (GOAL_AUTHOR_PHASES.includes(phase as GoalAuthorPhase)) {
     if (onProgress) onProgress(phase as GoalAuthorPhase, 'end');
     else process.stderr.write(`[goal-author] ${phase} ended in ${elapsedMs}ms\n`);
@@ -1156,6 +1160,21 @@ function observeAuthoredGroundingPathSections(document: string, paths: readonly
   }
 }
 
+function authoredGoalSectionChars(document: string): Record<string, number> {
+  const headings = linesOutsideFencedCode(document)
+    .filter(({ text }) => /^## (?:\S)/.test(text))
+    .map(({ text, start }) => ({ heading: text.slice(3).trim(), start }));
+  const sections: Record<string, number> = { preamble: [...document.slice(0, headings[0]?.start ?? document.length)].length };
+  for (let index = 0; index < headings.length; index += 1) {
+    const { heading, start } = headings[index];
+    sections[heading] = (sections[heading] ?? 0) + [...document.slice(start, headings[index + 1]?.start ?? document.length)].length;
+  }
+  for (const heading of ['PROBLEM', 'WHAT TO BUILD', 'ACCEPTANCE CRITERIA', 'TRACED PATHS', 'SCOPE BOUNDARY', 'STEPS', '답하지 못하는 것']) {
+    sections[heading] ??= 0;
+  }
+  return sections;
+}
+
 function canonicalBlocks(document: string): string[] {
   return linesOutsideFencedCode(document)
     .filter((line) => /^##(?:\s|$)/.test(line.text))
@@ -4906,6 +4925,13 @@ async function authorGoalWithSupersededRootIntent(
   }
   // ⭐ 이 저작 «한 번»의 id. goalId 보다 «먼저» 있어야 ground·enhance 의 소요를 그 골에 붙일 수 있다.
   const authorRunId = generateGoalId();
+  const authorStartedAt = Date.now();
+  const enhanceTokens: GoalAuthorTokens = { inputTokens: null, outputTokens: null };
+  const onEnhanceUsage = (usage: LLMUsage): void => {
+    if (usage.inputTokens !== undefined) enhanceTokens.inputTokens = (enhanceTokens.inputTokens ?? 0) + usage.inputTokens;
+    if (usage.outputTokens !== undefined) enhanceTokens.outputTokens = (enhanceTokens.outputTokens ?? 0) + usage.outputTokens;
+    try { deps.enhanceOpts?.onUsage?.(usage); } catch { /* usage observation is fail-soft */ }
+  };
   let facts: CodebaseGrounding | null = null;
   let groundingError = false;
   const persistentGrounding = resolveGoalAuthorPersistentGrounding('persistentGrounding' in deps ? deps.persistentGrounding : undefined);
@@ -4937,8 +4963,8 @@ async function authorGoalWithSupersededRootIntent(
       ? await deps.enhance(
         enhanceAsk,
         persistentFacts.length > 0
-          ? { ...deps.enhanceOpts, groundedFacts: persistentFacts }
-          : deps.enhanceOpts,
+          ? { ...deps.enhanceOpts, groundedFacts: persistentFacts, onUsage: onEnhanceUsage }
+          : { ...deps.enhanceOpts, onUsage: onEnhanceUsage },
       )
       : { original: ask, checklist: [], verbatimPreserved: true };
     // ⭐ goal-context 규범이 «어디에도 안 실린다»는 것을 관측으로 남긴다.
@@ -4956,7 +4982,7 @@ async function authorGoalWithSupersededRootIntent(
       placement: 'omitted',
     });
   } finally {
-    endGoalAuthorPhase('enhance', enhanceStartedAt, authorRunId, deps.onProgress);
+    endGoalAuthorPhase('enhance', enhanceStartedAt, authorRunId, deps.onProgress, enhanceTokens);
   }
   if (!enhancement.verbatimPreserved || (enhanceAsk && enhancement.original !== enhanceAsk)) {
     throw new Error('goal author refused an enhancement that does not preserve its input verbatim');
@@ -5431,6 +5457,18 @@ async function authorGoalWithSupersededRootIntent(
     } finally {
       endGoalAuthorPhase('lint', lintStartedAt, authorRunId, deps.onProgress);
     }
+    try {
+      observeGoalAuthor('goal-author', 'summary', {
+        authorRunId,
+        elapsedMs: Date.now() - authorStartedAt,
+        inputTokens: enhanceTokens.inputTokens,
+        outputTokens: enhanceTokens.outputTokens,
+        totalTokens: enhanceTokens.inputTokens === null || enhanceTokens.outputTokens === null
+          ? null : enhanceTokens.inputTokens + enhanceTokens.outputTokens,
+        goalChars: [...document].length,
+        sectionChars: authoredGoalSectionChars(document),
+      });
+    } catch { /* observation is fail-soft */ }
     return { document, facts, grounded: !groundingError && hasEvidence, authorRunId };
   } finally {
     endAssembleSubphase();

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

@@ -35,6 +35,8 @@ type GoalClarificationAnsweredBy = 'human' | 'agent' | 'none' | 'mixed';
 
 export interface GoalClarificationEscalationInput {
   goalFile: string;
+  /** Explicit provenance for isolated test fixtures; never inferred from goalFile. */
+  testOrigin?: true;
   delivery?: GoalClarificationDelivery;
   resolvedDelivery?: GoalClarificationObservedDelivery;
   dispatch?: (
@@ -577,6 +579,9 @@ export async function escalateGoalDocumentClarifications(
                   }],
                 },
                 input.dispatchContext?.sessionId,
+                {},
+                undefined,
+                { testOrigin: input.testOrigin },
               );
               pendingQuestionPersistence.write(pending);
               pendingWritten += 1;

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

@@ -0,0 +1,147 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { selfDevRunsDir, type SelfDevRunState } from '../self-dev/run-store.js';
+import { isGoalAuthorFileName } from './goal-document.js';
+
+export interface GoalLookupOptions {
+  /** Defaults to the current repository's docs/goals directory. */
+  goalsDir?: string;
+  /** Defaults to the current instance's self-dev-runs directory. */
+  runsDir?: string;
+}
+
+export interface GoalLookupRecord {
+  runId: string;
+  stage: string | null;
+  outcome: string | null;
+  prNumber: number | null;
+}
+
+/** The two sources are independent: null means that side did not match. */
+export interface GoalLookupResult {
+  goalBody: string | null;
+  goalFile: string | null;
+  kanId: string | null;
+  runId: string | null;
+  record: GoalLookupRecord | null;
+  runState: SelfDevRunState | null;
+}
+
+function filesIn(directory: string): string[] {
+  try {
+    return readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+type ValidResult = { runId: string; stage?: string | null; prNumber?: number | null };
+
+function isValidResult(result: unknown): result is ValidResult {
+  if (result === null || typeof result !== 'object' || Array.isArray(result)) return false;
+  const r = result as { runId?: unknown; stage?: unknown; prNumber?: unknown };
+  return typeof r.runId === 'string' && r.runId.length > 0
+    && (r.stage == null || typeof r.stage === 'string')
+    && (r.prNumber == null || (typeof r.prNumber === 'number' && Number.isSafeInteger(r.prNumber) && r.prNumber > 0));
+}
+
+function prNumber(value: string | undefined): number | null {
+  if (!value || !/^[1-9]\d*$/.test(value)) return null;
+  const number = Number(value);
+  return Number.isSafeInteger(number) ? number : null;
+}
+
+function executionRecords(document: string): GoalLookupRecord[] {
+  const sections = document.split(/^## 실행 기록\s*$/m).slice(1);
+  return sections.flatMap((section) => {
+    const block = section.split(/^#{1,2} /m, 1)[0] ?? '';
+    const entries = block.split(/^- runId: /m).slice(1);
+    return entries.flatMap((entry) => {
+      const runId = entry.split(/\r?\n/, 1)[0]?.trim();
+      if (!runId) return [];
+      const field = (name: string): string | undefined =>
+        new RegExp(`^  ${name}: ([^\\r\\n]*)$`, 'm').exec(entry)?.[1]?.trim();
+      return [{ runId, stage: field('stage') ?? null, outcome: field('outcome') ?? null, prNumber: prNumber(field('prNumber')) }];
+    });
+  });
+}
+
+/** Local, read-only lookup. A bare positive integer (or #number) is a PR; all other input is an exact run ID. */
+export function lookupGoal(reference: string, options: GoalLookupOptions = {}): GoalLookupResult {
+  const input = reference.trim();
+  const requestedPr = prNumber(input.replace(/^#/, ''));
+  const requestedRunId = requestedPr === null ? input : null;
+  const runsDir = options.runsDir ?? selfDevRunsDir();
+  const findRun = (matches: (result: ValidResult) => boolean, wantedRunId: string | null) => {
+    for (const name of filesIn(runsDir)) {
+      if (!/^[A-Za-z0-9][A-Za-z0-9_-]*\.json$/.test(name)) continue;
+      let candidate: SelfDevRunState;
+      try {
+        candidate = JSON.parse(readFileSync(join(runsDir, name), 'utf8')) as SelfDevRunState;
+      } catch { continue; }
+      if (!candidate || candidate.runId !== name.slice(0, -'.json'.length) || !Array.isArray(candidate.results)) continue;
+      const matchingResult = (candidate.results as unknown[]).find((result): result is ValidResult => isValidResult(result) && matches(result));
+      if (matchingResult || (wantedRunId !== null && candidate.runId === wantedRunId)) {
+        const runId = matchingResult?.runId ?? candidate.runId;
+        const record: GoalLookupRecord | null = matchingResult
+          ? { runId, stage: matchingResult.stage ?? null, outcome: null, prNumber: matchingResult.prNumber ?? null }
+          : null;
+        return { runState: candidate, runId, record };
+      }
+    }
+    return null;
+  };
+  const found = findRun((result) => requestedPr !== null ? result.prNumber === requestedPr : result.runId === requestedRunId, requestedRunId);
+  let runState: SelfDevRunState | null = found?.runState ?? null;
+  const resultRunId: string | null = found?.runId ?? null;
+  let runRecord: GoalLookupRecord | null = found?.record ?? null;
+
+  const goalsDir = options.goalsDir ?? resolve(process.cwd(), 'docs', 'goals');
+  let fallback: { goalFile: string; document: string; record: GoalLookupRecord } | null = null;
+  let selected: { goalFile: string; document: string; record: GoalLookupRecord } | null = null;
+  for (const name of filesIn(goalsDir)) {
+    if (!isGoalAuthorFileName(name)) continue;
+    const goalFile = join(goalsDir, name);
+    let document: string;
+    try { document = readFileSync(goalFile, 'utf8'); } catch { continue; }
+    const records = executionRecords(document);
+    const direct = records.find((candidate) => requestedPr !== null
+      ? candidate.prNumber === requestedPr
+      : candidate.runId === requestedRunId);
+    if (direct) { selected = { goalFile, document, record: direct }; break; }
+    if (requestedPr !== null && resultRunId !== null && fallback === null) {
+      const record = records.find((candidate) => candidate.prNumber === null && candidate.runId === resultRunId);
+      if (record) fallback = { goalFile, document, record };
+    }
+  }
+  const match = selected ?? fallback;
+  if (match) {
+    const { goalFile, document, record } = match;
+    // The returned run state must belong to the selected document record's run (review must-fix): re-resolve, or drop it.
+    if (resultRunId !== record.runId) {
+      const again = findRun((result) => result.runId === record.runId, record.runId);
+      runState = again?.runState ?? null;
+      runRecord = again?.record ?? null;
+    }
+    const body = document.split(/^## 실행 기록\s*$/m, 1)[0]!.replace(/\r?\n$/, '');
+    // A kan ID is only reported when the authored document explicitly names one.
+    const kanId = /^- Kan(?:Id|-ID):\s*(\S+)\s*$/im.exec(body)?.[1] ?? null;
+    return {
+      goalBody: body, goalFile, kanId, runId: record.runId,
+      record: {
+        ...record,
+        ...(runRecord?.runId === record.runId ? {
+          stage: record.stage ?? runRecord.stage,
+          outcome: record.outcome ?? runRecord.outcome,
+          prNumber: record.prNumber ?? runRecord.prNumber,
+        } : {}),
+      },
+      runState,
+    };
+  }
+  return { goalBody: null, goalFile: null, kanId: null, runId: resultRunId ?? requestedRunId, record: runRecord, runState };
+}