elanous 0.2.14 → 0.2.16

package/src/self-implement/app-api-budget.ts

@@ -0,0 +1,166 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { debug } from '../debug/log.js';
+import { releaseGitDiffPaths, releasePrFilePaths } from '../self-dev/release-path-guard.js';
+
+const defaultExecFile = promisify(execFileCb);
+const GIT_TIMEOUT = 20_000;
+
+export type AppApiExecFile = (
+  file: string,
+  args: readonly string[],
+  opts: { cwd: string; encoding: 'utf8'; timeout: number; maxBuffer?: number; env?: NodeJS.ProcessEnv },
+) => Promise<{ stdout: string; stderr?: string }>;
+
+let execFileImpl: AppApiExecFile = (file, args, opts) => defaultExecFile(file, [...args], opts);
+
+/** Tests inject the `gh` runner. Production keeps `execFile`. */
+export function setAppApiExecFileForTest(impl: AppApiExecFile | undefined): void {
+  execFileImpl = impl ?? ((file, args, opts) => defaultExecFile(file, [...args], opts));
+}
+
+/** App-token `gh` calls only. Caller names are fixed strings; the token value is never logged. */
+const GH_APP_CALLERS = {
+  'post-pr-comment-history': 'postPrComment',
+  'post-pr-comment': 'postPrComment',
+  'find-pr-comment': 'findPrComment',
+  'edit-pr-comment': 'editPrComment',
+  'add-pr-label-list': 'addPrLabel',
+  'add-pr-label-create': 'addPrLabel',
+  'add-pr-label': 'addPrLabel',
+  'read-pr-files': 'readPrFiles',
+} as const;
+
+export type GhAppCaller = keyof typeof GH_APP_CALLERS;
+
+export const APP_API_RATE_LIMIT_RETRY_CAP_MS = 15 * 60_000;
+
+export class AppApiRateLimitError extends Error {
+  readonly rateLimited = true as const;
+  readonly status: 403 | 429;
+  readonly resetAtMs: number | undefined;
+  constructor(message: string, status: 403 | 429, resetAtMs: number | undefined) {
+    super(message);
+    this.name = 'AppApiRateLimitError';
+    this.status = status;
+    this.resetAtMs = resetAtMs;
+  }
+}
+
+export function isAppApiRateLimitFailure(status: number | undefined, text: string, remaining?: string): boolean {
+  if (remaining === '0') return true;
+  if (status !== undefined && status !== 403 && status !== 429) return false;
+  return /API rate limit exceeded|rate limit/i.test(text) && (status === 403 || status === 429 || status === undefined);
+}
+
+function ghHeader(stderr: string, name: string): string | undefined {
+  const match = new RegExp(`^${name}:\\s*(.*)$`, 'im').exec(stderr);
+  return match?.[1]?.trim();
+}
+
+function ghStatusCode(stderr: string, error: unknown): number | undefined {
+  const fromHeader = ghHeader(stderr, 'HTTP') ?? ghHeader(stderr, 'status');
+  const headerCode = fromHeader ? Number.parseInt(fromHeader, 10) : NaN;
+  if (Number.isFinite(headerCode)) return headerCode;
+  const text = `${stderr}\n${error instanceof Error ? error.message : String(error ?? '')}`;
+  const match = /\b(403|429)\b/.exec(text);
+  return match ? Number(match[1]) : undefined;
+}
+
+/** Wait until X-RateLimit-Reset, never longer than 15 minutes. Returns false when the reset is already past or unreadable. */
+export async function waitForAppApiRateLimitReset(
+  resetAtMs: number | undefined,
+  now = Date.now(),
+  sleep: (ms: number) => Promise<void> = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+): Promise<boolean> {
+  if (resetAtMs === undefined || !Number.isFinite(resetAtMs)) return false;
+  const waitMs = Math.min(Math.max(0, resetAtMs - now), APP_API_RATE_LIMIT_RETRY_CAP_MS);
+  if (waitMs <= 0) return false;
+  await sleep(waitMs);
+  return true;
+}
+
+export async function runGhApp(
+  caller: GhAppCaller,
+  args: readonly string[],
+  opts: { cwd: string; encoding: 'utf8'; timeout: number; maxBuffer?: number; env: NodeJS.ProcessEnv },
+): Promise<{ stdout: string; stderr: string }> {
+  let stdout = '';
+  let stderr = '';
+  let status: number | undefined;
+  let error: unknown;
+  try {
+    const result = await execFileImpl('gh', args, opts);
+    stdout = result.stdout;
+    stderr = result.stderr ?? '';
+    status = 200;
+  } catch (caught) {
+    error = caught;
+    const failed = caught as { stdout?: string; stderr?: string };
+    stdout = typeof failed.stdout === 'string' ? failed.stdout : '';
+    stderr = typeof failed.stderr === 'string' ? failed.stderr : '';
+    status = ghStatusCode(stderr, caught);
+  }
+  const remaining = ghHeader(stderr, 'X-RateLimit-Remaining');
+  debug.log('github.app-api', 'call', {
+    caller: GH_APP_CALLERS[caller],
+    endpoint: args.filter((arg) => !arg.startsWith('-')).at(-1) ?? 'gh',
+    status: status ?? 0,
+    remaining: remaining ?? '',
+  });
+  if (error) {
+    const text = `${stderr}\n${error instanceof Error ? error.message : String(error)}`;
+    if (isAppApiRateLimitFailure(status, text, remaining)) {
+      const reset = ghHeader(stderr, 'X-RateLimit-Reset');
+      const resetSeconds = reset ? Number(reset) : NaN;
+      throw new AppApiRateLimitError(
+        text.trim() || 'API rate limit exceeded',
+        status === 429 ? 429 : 403,
+        Number.isFinite(resetSeconds) ? resetSeconds * 1000 : undefined,
+      );
+    }
+    throw error;
+  }
+  return { stdout, stderr };
+}
+
+export async function readPrFilesWithRateLimitFallback(input: {
+  number: number;
+  cwd: string;
+  base?: string;
+  env: NodeJS.ProcessEnv;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}): Promise<string[]> {
+  const env = input.env;
+  const endpoint = [
+    'api', '--paginate', '--slurp', '--method', 'GET', '-f', 'per_page=100',
+    `repos/{owner}/{repo}/pulls/${input.number}/files`,
+  ];
+  const ghOpts = { cwd: input.cwd, encoding: 'utf8' as const, timeout: GIT_TIMEOUT, maxBuffer: 64 * 1024 * 1024, env };
+  const fromApi = async () => releasePrFilePaths(JSON.parse((await runGhApp('read-pr-files', endpoint, ghOpts)).stdout));
+  const fromGit = async (): Promise<string[]> => {
+    const base = input.base ?? 'origin/main';
+    const { stdout } = await execFileImpl('git', ['diff', '--find-renames', '--name-status', '-z', `${base}...HEAD`], {
+      cwd: input.cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, maxBuffer: 64 * 1024 * 1024,
+    });
+    return releaseGitDiffPaths(stdout);
+  };
+  try {
+    return await fromApi();
+  } catch (error) {
+    if (!(error instanceof AppApiRateLimitError)) throw error;
+    try {
+      return await fromGit();
+    } catch (gitError) {
+      const waited = await waitForAppApiRateLimitReset(error.resetAtMs, input.now?.() ?? Date.now(), input.sleep);
+      if (!waited) throw error;
+      try {
+        return await fromApi();
+      } catch (retryError) {
+        if (retryError instanceof AppApiRateLimitError) throw retryError;
+        throw gitError;
+      }
+    }
+  }
+}

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

@@ -9,6 +9,7 @@ import type { UsageSnapshot } from '../budget/types.js';
 import { debug } from '../debug/log.js';
 import {
   DEFAULT_BUDGET_GATE_MAX_USED_PERCENT,
+  LAUNCH_GROK_USED_PERCENT_CAP,
   type BudgetGateMaxUsedPercent,
   type BudgetGateOnShortfall,
 } from '../user-config.js';
@@ -137,16 +138,17 @@ function slotUsable(
     return { usable: measuredUsable || unmeasured, reason: formatCodexReason(input.codexCandidates, cap), ...(unmeasured ? { unmeasured: true } : {}) };
   }
   if (provider === GROK_PROVIDER) {
-    const cap = capFor(input.maxUsedPercent, GROK_PROVIDER);
+    const configured = capFor(input.maxUsedPercent, GROK_PROVIDER);
+    // 발사 관문은 `elanous usage` 와 같은 주간 사용률에 80% 상한을 실제로 적용한다.
+    // «못 쟀다»(undefined)는 통과가 아니다. decideBudget 은 설정 상한을 그대로 쓴다.
+    const cap = allowUnmeasured ? LAUNCH_GROK_USED_PERCENT_CAP : configured;
     const known = typeof input.grokUsedPercent === 'number' && Number.isFinite(input.grokUsedPercent);
-    const unmeasured = allowUnmeasured && !known;
-    const usable = unmeasured || (cap === undefined
+    const usable = cap === undefined
       ? known
-      : known && (input.grokUsedPercent as number) < cap);
+      : known && (input.grokUsedPercent as number) < cap;
     return {
       usable,
       reason: formatGrokReason(input.grokUsedPercent, cap),
-      ...(unmeasured ? { unmeasured: true } : {}),
     };
   }
   return { usable: false, reason: `${provider}: 예산 판정 없음` };

package/src/self-implement/follow-up-goals.ts

@@ -0,0 +1,289 @@
+// FOLLOWUP-LOOP① — after a harness PR merges, leftover findings become one
+// follow-up goal draft. Default mode is shadow: record only. `live` also
+// enqueues through the same function as `harness queue add`.
+//
+// The test process injects every store. Nothing here opens the operational
+// ledger or queue unless the caller passes those seams.
+
+import { createHash } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { addHarnessQueue, type QueueSeat } from '../harness/harness-queue.js';
+import { debug } from '../debug/log.js';
+import { withFileLockSync } from '../storage/file-lock.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { devVersion, listChecklist, parseOwner } from '../release-loop/checklist.js';
+import { getUserConfig } from '../user-config.js';
+
+export const FOLLOW_UP_DEPTH_LIMIT = 3;
+export const FOLLOW_UP_OP_CARD_REQUIRED = 'OP 카드 필요';
+
+const REMAINING_SECTION = '남은 조각';
+const SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
+
+export type FollowUpMode = 'shadow' | 'live';
+
+export interface FollowUpDraftRecord {
+  prNumber: number;
+  cellId: string;
+  depth: number;
+  draftHash: string;
+  kind: 'draft' | 'op-card-required';
+  originalAskFirstLine: string;
+  remainings: readonly string[];
+  draft?: string;
+  note?: string;
+  queued: boolean;
+  /** live 대기열 넣기가 실패했을 때의 이유(초안은 그대로 남는다). */
+  enqueueError?: string;
+  seat?: QueueSeat;
+}
+
+export interface FollowUpMergeInput {
+  prNumber: number;
+  /** Result field set when the review budget is exhausted. */
+  followUpMustFix?: readonly string[];
+  /** Last review's non-blocking findings. */
+  shouldFix?: readonly string[];
+  /** Opened PR body — the «남은 조각» section is read verbatim. */
+  prBody?: string;
+  /** Original request. Only its first line enters the draft. */
+  feature: string;
+  /** Release-cell id. Absent means the goal file's GoalId, else the feature's first token. */
+  cellId?: string;
+  goalFile?: string;
+}
+
+export interface FollowUpSeams {
+  stateRoot?: string;
+  mode?: FollowUpMode;
+  /**
+   * Prior follow-up records for this cell, oldest first.
+   * Absent means the caller did not hand over a store — the test process writes nothing.
+   * Production `defaultSeams` always sets this to the state-root ledger.
+   */
+  readDrafts?: (cellId: string) => readonly FollowUpDraftRecord[];
+  appendDraft?: (record: FollowUpDraftRecord) => void;
+  /** Same function `harness queue add` calls. Injected in tests so the real queue is never opened. */
+  enqueue?: (input: { seat: QueueSeat; say: string; idempotencyKey: string }) => Promise<unknown> | unknown;
+  /** Release-cell owner (`TC`, `TC/rel`, …). Absent means look up the developing checklist. */
+  cellOwner?: (cellId: string) => string | undefined;
+  log?: (category: string, event: string, data?: unknown) => void;
+}
+
+export function followUpDraftsPath(stateRoot = elanousStateRoot()): string {
+  return join(stateRoot, 'follow-up', 'drafts.jsonl');
+}
+
+export function readFollowUpMode(read: () => { harness?: { followUp?: unknown } } = getUserConfig): FollowUpMode {
+  return read().harness?.followUp === 'live' ? 'live' : 'shadow';
+}
+
+/** Lines under a markdown heading «남은 조각», verbatim, without the bullet mark. */
+export function remainingPiecesFromPrBody(body: string | undefined): string[] {
+  if (!body) return [];
+  const lines = body.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === `## ${REMAINING_SECTION}`);
+  if (start < 0) return [];
+  const out: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^#{1,6}\s/.test(line)) break;
+    const item = line.match(/^\s*[-*]\s+(.+?)\s*$/)?.[1];
+    if (item) out.push(item);
+  }
+  return out;
+}
+
+export function collectRemainings(input: Pick<FollowUpMergeInput, 'followUpMustFix' | 'shouldFix' | 'prBody'>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const item of [
+    ...(input.followUpMustFix ?? []),
+    ...(input.shouldFix ?? []),
+    ...remainingPiecesFromPrBody(input.prBody),
+  ]) {
+    const text = item.trim();
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    out.push(text);
+  }
+  return out;
+}
+
+export function followUpCellId(input: Pick<FollowUpMergeInput, 'cellId' | 'goalFile' | 'feature'>, readGoal: (path: string) => string = (path) => readFileSync(path, 'utf8')): string | undefined {
+  const explicit = input.cellId?.trim();
+  if (explicit) return explicit;
+  if (input.goalFile) {
+    try {
+      const goalId = readGoal(input.goalFile).match(/^- GoalId:\s*(\S+)\s*$/m)?.[1];
+      if (goalId) return goalId;
+    } catch { /* a missing goal file is not a cell id */ }
+  }
+  // 자리 발사 머리(`[MK 자리 · 0.2.16 체크리스트 칸 FOLLOWUP-LOOP · …]`)가 칸을 «명시»한 경우만 읽는다.
+  // 추정(요청문 첫 단어)으로는 기록하지 않는다 — 다른 골이 한 칸으로 합쳐져 깊이·담당이 틀린다.
+  // 자리 머리 줄만 본다 — 본문이 다른 칸을 언급해도 그 칸으로 기록하지 않는다.
+  // 저작 Pod 규칙(OP 10-06)에서 첫 줄은 `대상 경로:` 이고 머리는 둘째 줄이라, 앞의 `대상 경로:` 줄 하나는 건너뛴다.
+  const lines = input.feature.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const header = /^대상 경로:/u.test(lines[0] ?? '') ? lines[1] : lines[0];
+  return header?.match(/^\[(?:OP|MK|TC|UX) 자리 · [^\]]*?체크리스트 칸 ([A-Z][A-Z0-9-]*[A-Z0-9])(?: ·|\])/u)?.[1];
+}
+
+export function originalAskFirstLine(feature: string): string {
+  return feature.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? '';
+}
+
+export function followUpDraftText(firstLine: string, remainings: readonly string[]): string {
+  return [
+    firstLine,
+    ...remainings,
+    'origin/main 에서 시작 · 남은 것만',
+  ].join('\n');
+}
+
+export function followUpDraftHash(text: string): string {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
+/** Chain length of follow-up goals already recorded for this cell, before this one. */
+export function followUpChainDepth(prior: readonly Pick<FollowUpDraftRecord, 'kind' | 'prNumber'>[]): number {
+  // 한 PR 이 «기록 → 대기열 확정» 두 줄을 남길 수 있으니 PR 번호로 센다.
+  return new Set(prior.filter((record) => record.kind === 'draft' || record.kind === 'op-card-required').map((record) => record.prNumber)).size;
+}
+
+/** Seat = the cell's owner. `TC/rel` keeps the seat `TC`. Unknown or absent owners go to OP (ONEDOOR). */
+export function seatForCellOwner(owner: string | undefined): QueueSeat {
+  if (!owner) return 'OP';
+  try {
+    const seat = parseOwner(owner.trim()).seat;
+    if ((SEATS as readonly string[]).includes(seat)) return seat as QueueSeat;
+  } catch { /* not a seat */ }
+  const head = owner.trim().split(/[/\s·]/)[0] ?? '';
+  return (SEATS as readonly string[]).includes(head) ? head as QueueSeat : 'OP';
+}
+
+function defaultReadDrafts(stateRoot: string, cellId: string): FollowUpDraftRecord[] {
+  let text = '';
+  try { text = readFileSync(followUpDraftsPath(stateRoot), 'utf8'); } catch { return []; }
+  const out: FollowUpDraftRecord[] = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const record = JSON.parse(line) as FollowUpDraftRecord;
+      if (record.cellId === cellId) out.push(record);
+    } catch { /* a torn line does not invent a chain */ }
+  }
+  return out;
+}
+
+/** 같은 PR 은 칸과 무관하게 한 번 — 칸 id 가 달리 들어와도 다시 만들지 않는다. */
+function defaultPrRecorded(stateRoot: string, prNumber: number): boolean {
+  let text = '';
+  try { text = readFileSync(followUpDraftsPath(stateRoot), 'utf8'); } catch { return false; }
+  return text.split('\n').some((line) => {
+    if (!line.trim()) return false;
+    try { return (JSON.parse(line) as FollowUpDraftRecord).prNumber === prNumber; } catch { return false; }
+  });
+}
+
+function defaultAppendDraft(stateRoot: string, record: FollowUpDraftRecord): void {
+  const path = followUpDraftsPath(stateRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}\n`);
+}
+
+function defaultCellOwner(cellId: string): string | undefined {
+  try {
+    return listChecklist(devVersion()).items.find((item) => item.id === cellId)?.owner;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Record one follow-up draft for a merged PR. Same PR is recorded once.
+ * Depth above {@link FOLLOW_UP_DEPTH_LIMIT} records «OP 카드 필요» instead of a draft.
+ * `live` enqueues; `shadow` (the default) only records. Returns null when nothing remains.
+ * Every failure is `debug.log` only — the merge result is the caller's to return unchanged.
+ */
+export async function recordFollowUpOnMerge(input: FollowUpMergeInput, seams: FollowUpSeams = {}): Promise<FollowUpDraftRecord | null> {
+  const log = seams.log ?? ((category, event, data) => { debug.log(category, event, data); });
+  try {
+    const remainings = collectRemainings(input);
+    if (remainings.length === 0) return null;
+    // No injected store and no explicit state root: this is the test process.
+    // Do not open the operational ledger or the harness queue.
+    // A test process handed the operational root (defaultSeams) is refused the same way.
+    const testProcess = process.env.NODE_ENV === 'test' || !!process.env.ELANOUS_TEST_HOME;
+    if (!seams.readDrafts && !seams.appendDraft && (!seams.stateRoot || (testProcess && seams.stateRoot === elanousStateRoot()))) return null;
+    const stateRoot = seams.stateRoot ?? elanousStateRoot();
+    const cellId = followUpCellId(input);
+    if (!cellId) {
+      log('self-implement.follow-up', 'draft-skipped-no-cell', { prNumber: input.prNumber });
+      return null;
+    }
+    const prior = (seams.readDrafts ?? ((id) => defaultReadDrafts(stateRoot, id)))(cellId);
+    if (prior.some((record) => record.prNumber === input.prNumber)) return null;
+    if (!seams.readDrafts && defaultPrRecorded(stateRoot, input.prNumber)) return null;
+    const depth = followUpChainDepth(prior) + 1;
+    const firstLine = originalAskFirstLine(input.feature);
+    const mode = seams.mode ?? readFollowUpMode();
+    const overDepth = depth > FOLLOW_UP_DEPTH_LIMIT;
+    const draft = overDepth ? undefined : followUpDraftText(firstLine, remainings);
+    const record: FollowUpDraftRecord = {
+      prNumber: input.prNumber,
+      cellId,
+      depth,
+      draftHash: followUpDraftHash(draft ?? `${firstLine}\n${FOLLOW_UP_OP_CARD_REQUIRED}`),
+      kind: overDepth ? 'op-card-required' : 'draft',
+      originalAskFirstLine: firstLine,
+      remainings,
+      ...(draft ? { draft } : {}),
+      ...(overDepth ? { note: FOLLOW_UP_OP_CARD_REQUIRED } : {}),
+      queued: false,
+    };
+    // 운영 원장은 «같은 PR 확인 ⊕ 첫 기록»을 한 잠금 안에서 한다 — 동시 병합 둘이 초안 둘을 만들지 않게.
+    const append = seams.appendDraft ?? ((row: FollowUpDraftRecord) => defaultAppendDraft(stateRoot, row));
+    const appendFirst = seams.appendDraft
+      ? (row: FollowUpDraftRecord) => { append(row); return true; }
+      : (row: FollowUpDraftRecord) => (mkdirSync(dirname(followUpDraftsPath(stateRoot)), { recursive: true }), withFileLockSync(`${followUpDraftsPath(stateRoot)}.lock`, () => {
+        if (defaultPrRecorded(stateRoot, row.prNumber)) return false;
+        defaultAppendDraft(stateRoot, row);
+        return true;
+      }));
+    if (!overDepth && mode === 'live' && draft) record.seat = seatForCellOwner((seams.cellOwner ?? defaultCellOwner)(cellId));
+    // 원장 기록을 먼저 확정한다 — 기록이 실패하면 대기열에 넣지 않는다(같은 PR 한 번 · 원장 밖 연결골 0).
+    if (!appendFirst(record)) return null;
+    if (!overDepth && mode === 'live' && draft && record.seat) {
+      const seat = record.seat;
+      if (testProcess && !seams.enqueue) return record;
+      try {
+        await (seams.enqueue ?? ((item) => addHarnessQueue({ seat: item.seat, say: item.say, idempotencyKey: item.idempotencyKey })))({
+          seat,
+          say: draft,
+          idempotencyKey: `follow-up:${input.prNumber}`,
+        });
+        record.queued = true;
+      } catch (error) {
+        // 대기열 넣기가 실패해도 초안은 남긴다 — 같은 PR 은 다시 오지 않으므로 여기서 잃으면 영영 없다.
+        // queued=false ⊕ enqueueError 로 원장에 남기고, 재투입은 같은 idempotencyKey 로 사람이·다음 수리 노드가 한다.
+        record.enqueueError = (error instanceof Error ? error.message : String(error)).slice(0, 300);
+        log('self-implement.follow-up', 'enqueue-failed', { prNumber: input.prNumber, seat, error: record.enqueueError });
+      }
+      // 대기열 결과를 원장에 한 줄 더 — 이 쓰기의 실패는 대기열 실패와 다른 사건이다.
+      try {
+        append({ ...record });
+      } catch (error) {
+        log('self-implement.follow-up', 'ledger-confirm-failed', {
+          prNumber: input.prNumber, seat, queued: record.queued, error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    return record;
+  } catch (error) {
+    log('self-implement.follow-up', 'draft-failed', {
+      prNumber: input.prNumber,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}

package/src/self-implement/frozen-merges.ts

@@ -7,7 +7,7 @@ import { debug } from '../debug/log.js';
 import { beginLandingMerge, readLandingFreeze, type LandingFreeze } from '../release-loop/landing-freeze.js';
 
 /** `manual`: the owning repository could not be determined — a sweep never resumes it; a person does. */
-export interface FrozenMerge { prNumber: number; headCommit: string; repoRoot: string; manual?: true }
+export interface FrozenMerge { prNumber: number; headCommit: string; repoRoot: string; manual?: true; /** Host goal document, so a resumed merge can still apply its «이 칸 완료» declaration (CL-AUTO). */ goalFile?: string }
 /** What a resume sweep hands its merge function: the held entry, marked as already claimed by this sweep. */
 export type ResumedMerge = FrozenMerge & { resumed: true };
 
@@ -65,7 +65,8 @@ function readQueue(root: string): FrozenMerge[] {
     Number.isSafeInteger(item.prNumber) && item.prNumber > 0 &&
     typeof item.headCommit === 'string' && /^[a-f0-9]{40}$/i.test(item.headCommit) &&
     typeof item.repoRoot === 'string' && item.repoRoot.length > 0 &&
-    (item.manual === undefined || item.manual === true))) throw new Error(`invalid frozen merge queue: ${path}`);
+    (item.manual === undefined || item.manual === true) &&
+    (item.goalFile === undefined || (typeof item.goalFile === 'string' && item.goalFile.length > 0)))) throw new Error(`invalid frozen merge queue: ${path}`);
   return data as FrozenMerge[];
 }
 

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');
@@ -5426,10 +5452,28 @@ async function authorGoalWithSupersededRootIntent(
     assembleCompleted = true;
     endGoalAuthorPhase('assemble', assembleStartedAt, authorRunId, deps.onProgress);
     const lintStartedAt = startGoalAuthorPhase('lint', authorRunId, deps.onProgress);
+    let lintPassed = false;
     try {
       assertRequiredBlocks(document);
+      lintPassed = true;
     } finally {
-      endGoalAuthorPhase('lint', lintStartedAt, authorRunId, deps.onProgress);
+      try {
+        endGoalAuthorPhase('lint', lintStartedAt, authorRunId, deps.onProgress);
+      } finally {
+        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),
+            ...(!lintPassed ? { outcome: 'lint-failed' } : {}),
+          });
+        } catch { /* observation is fail-soft */ }
+      }
     }
     return { document, facts, grounded: !groundingError && hasEvidence, authorRunId };
   } finally {

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;