elanous 0.2.37 → 0.2.40

package/src/agent-substrate/self-review-cli.ts

@@ -14,13 +14,13 @@
 //
 // index.ts 의 액션은 옵션 파싱과 실제 의존 배선만 남는다(얇은 껍데기).
 
-import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { tierModel } from '../llm/model-defaults.js';
-import { buildReviewObservation, safeLogText } from './review-observation.js';
-import { checkCitedReviewPathsAtHead } from './review-finding-key.js';
+import { buildReviewObservation, reviewIntentFingerprint, safeLogText } from './review-observation.js';
+import { checkCitedReviewPathsAtHead, citedReviewPaths } from './review-finding-key.js';
 import { DEFAULT_REVIEW_BACKEND, defaultAcpReviewTimeoutSec } from './acp-reviewer.js';
 import { ZAI_OPENROUTER_FALLBACK_MODEL } from '../llm/zai-coding-plan.js';
 import { debug } from '../debug/log.js';
@@ -89,9 +89,13 @@ export interface SelfReviewCliOpts {
   context?: string[] | undefined;
   contextText?: string[] | undefined;
   contextOrder?: Array<{ kind: 'file' | 'text'; value: string }> | undefined;
+  /** Skip the default repository-grounded review context pack. */
+  noContextPack?: boolean | undefined;
   json?: boolean | undefined;
   /** Save completed reviews under the task-agent state's review-results directory. */
   save?: string | undefined;
+  /** Review only commits after a previously saved PR review head. */
+  sinceReview?: string | undefined;
   /** One invocation past r5, only for a PR in OP's traffic.json allowlist; the reason is recorded before review starts. */
   overCapReason?: string | undefined;
 }
@@ -171,37 +175,187 @@ export interface SelfReviewCliOutcome {
   failed: number;
 }
 
-/** Saved results are round evidence only when their PR, exact head and reviewed status agree. */
-function savedReviewRecords(pr: string, root = effectiveInstanceRoot()): Array<{ head: string; reviewedAt: number }> {
+interface SavedReviewEvidence {
+  heads: string[];
+  records: Array<{ head: string; reviewedAt: number }>;
+  unreadableFiles: string[];
+}
+
+interface SavedReviewForDelta {
+  file: string;
+  headCommit: string;
+  mustFix: string[];
+  reviewInputChars: number;
+  reviewDurationMs: number;
+}
+
+function selectSavedReviewForDelta(pr: string, selector: string, root = effectiveInstanceRoot()):
+  | { review: SavedReviewForDelta }
+  | { error: string } {
   const dir = join(root, 'review-results');
   let names: string[];
-  try { names = readdirSync(dir); } catch { return []; }
-  // Manual review saves in the operating house also use head10; the JSON's full head is authoritative.
-  const matching = new RegExp(`^.+-${pr}-([a-f0-9]{7,40})\\.json$`, 'i');
-  const records = new Map<string, { head: string; reviewedAt: number }>();
+  try { names = readdirSync(dir); } catch { return { error: 'saved-review-directory-missing' }; }
+  const token = selector.trim();
+  if (!token) return { error: 'saved-review-selector-empty' };
+  const records: Array<SavedReviewForDelta & { mtimeMs: number }> = [];
   for (const name of names) {
-    const match = matching.exec(name);
+    if (!name.toLowerCase().endsWith('.json')) continue;
+    let raw: unknown;
+    try { raw = JSON.parse(readFileSync(join(dir, name), 'utf8')); } catch { continue; }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+    const row = raw as Record<string, unknown>;
+    const recordPr = typeof row.pr === 'string' ? row.pr
+      : Number.isSafeInteger(row.pr) ? String(row.pr) : undefined;
+    if (recordPr !== pr || row.reviewed !== true || typeof row.headCommit !== 'string' || !COMMIT_OID.test(row.headCommit)) continue;
+    const named = name === token || name === `${token}.json` || name.startsWith(`${token}-${pr}-`);
+    const byHead = /^[a-f0-9]{7,64}$/i.test(token) && row.headCommit.toLowerCase().startsWith(token.toLowerCase());
+    if (!named && !byHead) continue;
+    if (!Array.isArray(row.mustFix) || !row.mustFix.every((item) => typeof item === 'string')) continue;
+    if (typeof row.reviewInputChars !== 'number' || !Number.isFinite(row.reviewInputChars) || row.reviewInputChars <= 0
+      || typeof row.reviewDurationMs !== 'number' || !Number.isFinite(row.reviewDurationMs) || row.reviewDurationMs <= 0) continue;
+    let mtimeMs = 0;
+    try { mtimeMs = statSync(join(dir, name)).mtimeMs; } catch { continue; }
+    records.push({ file: name, headCommit: row.headCommit.toLowerCase(), mustFix: row.mustFix as string[],
+      reviewInputChars: row.reviewInputChars, reviewDurationMs: row.reviewDurationMs, mtimeMs });
+  }
+  const distinctHeads = [...new Set(records.map((record) => record.headCommit))];
+  if (distinctHeads.length > 1) return { error: 'saved-review-selector-ambiguous' };
+  const selected = records.sort((a, b) => b.mtimeMs - a.mtimeMs)[0];
+  return selected ? { review: selected } : { error: 'saved-review-not-found-or-missing-efficiency-receipt' };
+}
+
+function reviewInputCharacterCount(input: ReviewInput): number {
+  return input.prDiff.length + input.phaseIntent.length + (input.acceptance?.length ?? 0)
+    + (input.evidenceNote?.length ?? 0)
+    + (input.workingMemory?.length ?? 0)
+    + (input.reviewerContext ?? []).reduce((sum, item) => sum + item.label.length + item.body.length, 0);
+}
+
+function readDeltaDiffAtHead(pr: string, base: string, deps: SelfReviewCliDeps):
+  | { read: DiffRead }
+  | { error: string; headCommit?: string } {
+  if (!COMMIT_OID.test(base)) return { error: 'saved-review-head-malformed' };
+  const before = prHeadCommit(pr, deps);
+  if (before.state !== 'known') return { error: 'current-pr-head-unavailable' };
+  if (before.value.toLowerCase() === base.toLowerCase()) return { error: 'no-new-head-since-review', headCommit: before.value };
+  const { repo } = prCompareAnchors(pr, deps);
+  if (!repo) return { error: 'pr-repository-unavailable', headCommit: before.value };
+  const comparePath = `repos/${repo}/compare/${base}...${before.value}`;
+  const comparison = deps.gh(['api', comparePath], 25_000);
+  if (comparison.status !== 0) return { error: 'saved-review-head-not-ancestor', headCommit: before.value };
+  try {
+    const parsed = JSON.parse(comparison.stdout) as { status?: unknown; merge_base_commit?: { sha?: unknown } };
+    if (parsed.status !== 'ahead' || typeof parsed.merge_base_commit?.sha !== 'string'
+      || parsed.merge_base_commit.sha.toLowerCase() !== base.toLowerCase()) {
+      return { error: 'saved-review-head-not-ancestor', headCommit: before.value };
+    }
+  } catch { return { error: 'compare-response-invalid', headCommit: before.value }; }
+  const diff = deps.gh(['api', comparePath, '-H', 'Accept: application/vnd.github.diff'], 25_000);
+  if (diff.status !== 0 || !diff.stdout.trim()) return { error: 'delta-diff-unavailable', headCommit: before.value };
+  const after = prHeadCommit(pr, deps);
+  if (after.state !== 'known' || after.value !== before.value) return { error: 'current-pr-head-moved', headCommit: before.value };
+  return { read: { diff, headCommit: before.value, headCommitState: 'known', currentHeadCommit: after.value,
+    currentHeadCommitState: 'known', stale: false, refetched: false, source: 'sha-pinned', baseCommit: base.toLowerCase() } };
+}
+
+function deltaReviewIntent(base: SavedReviewForDelta): string {
+  const findings = base.mustFix.length
+    ? base.mustFix.map((finding, index) => `${index + 1}. ${finding}`).join('\n')
+    : '(직전 mustFix 없음 — 새 정확성·안전·데이터 손실 문제만 확인)';
+  return [
+    'DELTA REVIEW — 직전 저장 리뷰와 현재 head 사이의 변경만 판정한다.',
+    '직전 mustFix 각각을 REQUIREMENTS 항목에 `DELTA-FINDING <번호>: FIXED|OPEN` 형식으로 정확히 한 번 기록한다. OPEN에는 짧은 근거를 덧붙인다.',
+    '새 MUST-FIX는 현재 delta가 만든 정확성·안전·데이터 손실 문제만 허용하며, 각 항목은 `[NEW-CORRECTNESS]`, `[NEW-SAFETY]`, `[NEW-DATA-LOSS]` 중 하나로 시작한다.',
+    '새 SHOULD-FIX나 스타일·범위 확장 지적은 만들지 않는다. 직전 findings를 다시 리뷰 전체로 확장하지 않는다.',
+    '직전 mustFix:', findings,
+  ].join('\n\n');
+}
+
+function assessDeltaReview(review: ReviewResult, previous: SavedReviewForDelta):
+  | { valid: true; mustFix: string[]; deltaFindings: Array<{ finding: string; status: 'fixed' | 'open' }>; excludedNewFindings: number }
+  | { valid: false; reason: string } {
+  const statuses = new Map<number, 'fixed' | 'open'>();
+  for (const item of review.requirements ?? []) {
+    const match = /^DELTA-FINDING\s+(\d+):\s*(FIXED|OPEN)(?:\s+—.*)?$/i.exec(item.trim());
     if (!match) continue;
+    const index = Number(match[1]);
+    if (index < 1 || index > previous.mustFix.length || statuses.has(index)) return { valid: false, reason: 'delta-assessment-invalid' };
+    statuses.set(index, match[2]!.toLowerCase() as 'fixed' | 'open');
+  }
+  if (statuses.size !== previous.mustFix.length) return { valid: false, reason: 'delta-assessment-incomplete' };
+  const deltaFindings = previous.mustFix.map((finding, index) => ({ finding, status: statuses.get(index + 1)! }));
+  const openFindings = deltaFindings.filter((item) => item.status === 'open').map((item) => item.finding);
+  const allowedPrefix = /^\[(?:NEW-CORRECTNESS|NEW-SAFETY|NEW-DATA-LOSS)\]\s*/i;
+  const newFindings = review.mustFix.filter((finding) => allowedPrefix.test(finding)).map((finding) => finding.replace(allowedPrefix, ''));
+  const excludedNewFindings = review.mustFix.length - newFindings.length;
+  return { valid: true, mustFix: [...openFindings, ...newFindings], deltaFindings, excludedNewFindings };
+}
+
+function savedReviewEvidence(
+  pr: string,
+  root = effectiveInstanceRoot(),
+  onUnreadable?: (file: string) => void,
+): SavedReviewEvidence {
+  const dir = join(root, 'review-results');
+  let names: string[];
+  try { names = readdirSync(dir); } catch { return { heads: [], records: [], unreadableFiles: [] }; }
+  const escapedPr = pr.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const matchingPrInName = new RegExp(`(?:^|-)${escapedPr}(?:-|\\.json$)`, 'i');
+  const records = new Map<string, { head: string; reviewedAt: number }>();
+  const unreadableFiles: string[] = [];
+  for (const name of names) {
+    if (!name.toLowerCase().endsWith('.json')) continue;
+    const nameSuggestsPr = matchingPrInName.test(name);
     try {
-      const recordPath = join(dir, name);
-      const raw: unknown = JSON.parse(readFileSync(recordPath, 'utf8'));
-      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+      const raw: unknown = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        if (nameSuggestsPr) { unreadableFiles.push(name); onUnreadable?.(name); }
+        continue;
+      }
       const result = raw as Record<string, unknown>;
+      const recordPr = typeof result.pr === 'string' ? result.pr
+        : Number.isSafeInteger(result.pr) ? String(result.pr) : undefined;
+      if (recordPr !== pr) {
+        // A parseable, explicit foreign PR identity outranks a misleading filename.
+        if (recordPr === undefined && nameSuggestsPr) { unreadableFiles.push(name); onUnreadable?.(name); }
+        continue;
+      }
+      if (result.reviewed !== true) continue;
       const head = result.headCommit;
-      if (String(result.pr) !== pr || result.reviewed !== true || typeof head !== 'string'
-        || !COMMIT_OID.test(head) || !head.toLowerCase().startsWith(match[1]!.toLowerCase())) continue;
-      const normalized = head.toLowerCase();
-      const existing = records.get(normalized);
+      if (typeof head !== 'string' || !COMMIT_OID.test(head)) {
+        unreadableFiles.push(name);
+        onUnreadable?.(name);
+        continue;
+      }
+      // The result payload is authoritative: round-tagged filenames and stale suffixes
+      // still count by their full PR/head identity, then deduplicate on that identity.
+      const recordPath = join(dir, name);
       const reviewedAt = typeof result.reviewedAt === 'number' && Number.isFinite(result.reviewedAt)
         ? result.reviewedAt : statSync(recordPath).mtimeMs;
+      const normalized = head.toLowerCase();
+      const existing = records.get(normalized);
       if (!existing || reviewedAt > existing.reviewedAt) records.set(normalized, { head: normalized, reviewedAt });
-    } catch { /* corrupt or partial result is not a completed round */ }
+    } catch {
+      // A filename can associate an unreadable record with this PR; fail closed at the cap.
+      if (nameSuggestsPr) { unreadableFiles.push(name); onUnreadable?.(name); }
+    }
   }
-  return [...records.values()];
+  const saved = [...records.values()];
+  return { heads: saved.map(({ head }) => head), records: saved, unreadableFiles };
 }
 
 export function savedReviewHeads(pr: string, root = effectiveInstanceRoot()): string[] {
-  return savedReviewRecords(pr, root).map(({ head }) => head);
+  return savedReviewEvidence(pr, root).heads;
+}
+
+function isReplaceableErrorArtifact(path: string, pr: string, head: string): boolean {
+  try {
+    const result = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+    const recordPr = typeof result.pr === 'string' ? result.pr
+      : Number.isSafeInteger(result.pr) ? String(result.pr) : undefined;
+    return recordPr === pr && result.headCommit === head && result.reviewed === false
+      && typeof result.error === 'string' && result.error.length > 0;
+  } catch { return false; }
 }
 
 function normalizeReviewPrArg(input: string, deps: SelfReviewCliDeps): string | null {
@@ -742,7 +896,7 @@ interface AuthoredEvidence {
   /** 리뷰 증거로 쓸 diff. */
   diff: string;
   /** 좁혔나. `full` = 종전 three-dot 그대로. */
-  evidence: 'full' | 'authored-only';
+  evidence: 'full' | 'authored-only' | 'saved-review-delta';
   prDiffFiles: number;
   /** 좁힌 뒤 파일 수. 안 좁혔으면 **잰 적 없음**을 뜻하는 undefined 가 아니라, 잰 경우에만 채운다. */
   authoredFiles?: number;
@@ -1539,7 +1693,7 @@ export async function runSelfReviewCliCommand(
       : opts.reviewerMix;
     // The route is chosen outside the existing single-review pipeline so explicit CLI flags retain
     // their exact behavior. A failed reviewer is retried on the same pinned PR diff by the next lane.
-    if (reviewerMix && (opts.save === undefined || /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(opts.save)) &&
+    if (!opts.sinceReview && reviewerMix && (opts.save === undefined || /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(opts.save)) &&
         !opts.model?.trim() && !opts.acp && !opts.acpBackend && !opts.acpModel && !deps.envModel()) {
       const results: Array<Record<string, unknown>> = [];
       let failed = 0;
@@ -1566,6 +1720,17 @@ export async function runSelfReviewCliCommand(
         let attemptedLane: ReviewLane | undefined;
         let completedWithError = false;
         const pinnedHead = initialHead.value;
+        const priorEvidence = savedReviewEvidence(pr);
+        const capWasActive = priorEvidence.heads.length + priorEvidence.unreadableFiles.length >= 5;
+        const canonicalResultPath = join(effectiveInstanceRoot(), 'review-results', `pr-${pr}-${pinnedHead.slice(0, 12)}.json`);
+        if (capWasActive && existsSync(canonicalResultPath)
+          && !isReplaceableErrorArtifact(canonicalResultPath, pr, pinnedHead)) {
+          const message = `PR ${pr}: 동일 head 리뷰 결과가 이미 저장되어 있습니다: ${canonicalResultPath}`;
+          results.push({ pr, reviewed: false, refusal: 'cap-refused', existingResult: canonicalResultPath, headCommit: pinnedHead });
+          deps.error(message);
+          failed += 1;
+          continue;
+        }
         let capClaimed = false;
         let pendingFallback: { from: ReviewLane; reason: string } | undefined;
         for (const [index, lane] of lanes.entries()) {
@@ -1624,6 +1789,33 @@ export async function runSelfReviewCliCommand(
           const enriched: Record<string, unknown> = { ...result, reviewerMixPrimaryLane: lanes[0],
             ...(selectedLane ? { reviewerMixSelectedLane: selectedLane } : {}) };
           results.push(enriched);
+          if (completed && completed.reviewed === true) {
+            try {
+              mkdirSync(dirname(canonicalResultPath), { recursive: true });
+              const normalized = normalizeSavedReviewMustFix(enriched);
+              if (enriched.headCommit !== pinnedHead || enriched.stale === true
+                || enriched.currentHeadCommit !== pinnedHead) {
+                throw new Error('review result is not pinned to the confirmed current PR head');
+              }
+              writeFileSync(canonicalResultPath, selfReviewJsonLine([normalized.result]));
+            } catch (error) {
+              failed += 1;
+              deps.error(`PR ${pr}: 리뷰 결과 저장 실패 (${canonicalResultPath}): ${error instanceof Error ? error.message : String(error)}`);
+              if (capWasActive) {
+                const authorization = readCapOverride(pr);
+                const claimPath = authorization?.head === pinnedHead.toLowerCase()
+                  ? join(effectiveInstanceRoot(), 'review-results', `cap-override-${pr}.json`)
+                  : join(effectiveInstanceRoot(), 'review-results', `cap-override-${pr}-head-${pinnedHead.toLowerCase()}.json`);
+                try { unlinkSync(claimPath); } catch { /* already absent or owned by another lane */ }
+              }
+            }
+          } else if (capWasActive && !completed && capClaimed) {
+            const authorization = readCapOverride(pr);
+            const claimPath = authorization?.head === pinnedHead.toLowerCase()
+              ? join(effectiveInstanceRoot(), 'review-results', `cap-override-${pr}.json`)
+              : join(effectiveInstanceRoot(), 'review-results', `cap-override-${pr}-head-${pinnedHead.toLowerCase()}.json`);
+            try { unlinkSync(claimPath); } catch { /* already absent or owned by another lane */ }
+          }
           if (!opts.json) deps.print(`\n━━ PR ${pr} (${String(enriched.model ?? 'review failed')}) ━━\n${deps.renderReview(enriched as unknown as ReviewResult)}`);
         }
         if (!completed || completedWithError) failed += 1;
@@ -1662,6 +1854,11 @@ async function runSelfReviewCliCommandPinned(
     deps.error('--save 이름은 영문자·숫자로 시작하고 영문자·숫자·점·밑줄·하이픈만 포함해야 합니다.');
     return { results: [], failed: 1 };
   }
+  if (opts.sinceReview && ((opts.contextOrder?.length ?? 0) > 0 || (opts.context?.length ?? 0) > 0 || (opts.contextText?.length ?? 0) > 0)) {
+    const message = '--since-review 는 직전 지적에 인용된 파일만 맥락으로 싣습니다; --context/--context-text 와 함께 쓸 수 없습니다.';
+    deps.error(message);
+    return { results: opts.json ? [{ error: message, reviewed: false, refusal: 'delta-context-expansion' }] : [], failed: 1 };
+  }
 
   // An explicit API model is the caller's reviewer choice even when a default ACP lane supplied both flags.
   const requestedModel = opts.model?.trim() || undefined;
@@ -1769,8 +1966,12 @@ async function runSelfReviewCliCommandPinned(
   const providedReviewerContext = loadReviewerContext(opts, deps.readReferencedFile);
   const hasProvidedReviewerContext = (opts.contextOrder?.length ?? 0) > 0 || (opts.context?.length ?? 0) > 0 || (opts.contextText?.length ?? 0) > 0;
   for (const pr of normalizedPrArgs as string[]) {
-    const previousHeads = savedReviewHeads(pr);
-    const previousRoundCount = previousHeads.length;
+    const savedEvidence = savedReviewEvidence(pr, undefined, (file) => {
+      deps.observeDoctorReview?.('saved-result-unreadable', { pr, file }, { level: 'warn' });
+    });
+    const previousHeads = savedEvidence.heads;
+    const previousRoundCount = previousHeads.length + savedEvidence.unreadableFiles.length;
+    const shouldPersistCapResult = previousRoundCount >= 5 && !opts.reviewerMixPrimaryLane;
     const reason = opts.overCapReason?.trim();
     const authorization = previousRoundCount >= 5 ? readCapOverride(pr) : undefined;
     deps.observeDoctorReview?.('round-counted', { pr, previousRoundCount, round: previousRoundCount + 1 });
@@ -1789,7 +1990,49 @@ async function runSelfReviewCliCommandPinned(
       failed += 1;
       continue;
     }
-    const diffRead = readDiffAtHead(pr, deps);
+    let deltaBase: SavedReviewForDelta | undefined;
+    if (opts.sinceReview !== undefined) {
+      const selected = selectSavedReviewForDelta(pr, opts.sinceReview);
+      if ('error' in selected) {
+        const message = `PR ${pr}: --since-review 기준을 읽지 못했습니다 (${selected.error}).`;
+        deps.error(message);
+        if (opts.json || opts.save !== undefined) results.push({ pr, error: message, reviewed: false, refusal: 'delta-base-invalid', deltaRefusal: selected.error });
+        failed += 1;
+        continue;
+      }
+      deltaBase = selected.review;
+    }
+    const diffResult = deltaBase ? readDeltaDiffAtHead(pr, deltaBase.headCommit, deps) : { read: readDiffAtHead(pr, deps) };
+    if ('error' in diffResult) {
+      const message = `PR ${pr}: 델타 리뷰를 고정하지 못했습니다 (${diffResult.error}).`;
+      deps.error(message);
+      if (opts.json || opts.save !== undefined) results.push({ pr, error: message, reviewed: false, refusal: 'delta-base-invalid', deltaRefusal: diffResult.error,
+        ...(diffResult.headCommit ? { headCommit: diffResult.headCommit } : {}) });
+      failed += 1;
+      continue;
+    }
+    const diffRead = diffResult.read;
+    const canonicalResultPath = COMMIT_OID.test(diffRead.headCommit)
+      ? join(effectiveInstanceRoot(), 'review-results', `pr-${pr}-${diffRead.headCommit.slice(0, 12)}.json`)
+      : undefined;
+    let claimedCapPath: string | undefined;
+    const releaseCapClaim = (): void => {
+      if (!claimedCapPath || opts.reviewerMixPrimaryLane) return;
+      try {
+        unlinkSync(claimedCapPath);
+        claimedCapPath = undefined;
+      } catch (error) {
+        deps.error(`PR ${pr}: 상한 예외 사용 기록 롤백 실패 (${claimedCapPath}): ${error instanceof Error ? error.message : String(error)}`);
+      }
+    };
+    if (shouldPersistCapResult && canonicalResultPath && existsSync(canonicalResultPath)
+      && !isReplaceableErrorArtifact(canonicalResultPath, pr, diffRead.headCommit)) {
+      const message = `PR ${pr}: 동일 head 리뷰 결과가 이미 저장되어 있습니다: ${canonicalResultPath}`;
+      deps.error(message);
+      results.push({ pr, error: message, reviewed: false, refusal: 'cap-refused', previousRoundCount, headCommit: diffRead.headCommit, existingResult: canonicalResultPath });
+      failed += 1;
+      continue;
+    }
     if (opts.reviewerMixExpectedHead && diffRead.headCommit !== opts.reviewerMixExpectedHead) {
       const refusal = { pr, reviewed: false, verdict: null, mustFix: [], shouldFix: [],
         refusal: 'reviewer-mix-head-changed', stale: true, headCommit: diffRead.headCommit,
@@ -1801,10 +2044,13 @@ async function runSelfReviewCliCommandPinned(
       continue;
     }
     if (previousRoundCount >= 5 && authorization && diffRead.headCommit.toLowerCase() === authorization.head && !opts.reviewerMixCapClaimed) {
-      const message = `PR ${pr}: 동일 head는 이미 승인 소모 기록이 있습니다.`;
+      const resultExists = canonicalResultPath && existsSync(canonicalResultPath);
+      const message = resultExists
+        ? `PR ${pr}: 동일 head 리뷰 결과가 이미 저장되어 있습니다: ${canonicalResultPath}`
+        : `PR ${pr}: 동일 head는 이미 승인 소모 기록이 있습니다. 결과 파일을 찾을 수 없어 재리뷰하지 않습니다.`;
       deps.observeDoctorReview?.('cap-refused', { pr, head: diffRead.headCommit, previousRoundCount, round: previousRoundCount + 1, reason: 'same-head-already-used' }, { level: 'warn' });
       deps.error(message);
-      if (opts.json || opts.save !== undefined) results.push({ pr, error: message, reviewed: false, refusal: 'cap-refused', previousRoundCount, headCommit: diffRead.headCommit });
+      if (opts.json || opts.save !== undefined || resultExists) results.push({ pr, error: message, reviewed: false, refusal: 'cap-refused', previousRoundCount, headCommit: diffRead.headCommit, ...(resultExists ? { existingResult: canonicalResultPath } : {}) });
       failed += 1;
       continue;
     }
@@ -1827,7 +2073,7 @@ async function runSelfReviewCliCommandPinned(
         failed += 1;
         continue;
       }
-      const savedRecords = savedReviewRecords(pr);
+      const savedRecords = savedEvidence.records;
       const latestReviewed = savedRecords.reduce<(typeof savedRecords)[number] | undefined>(
         (latest, record) => !latest || record.reviewedAt > latest.reviewedAt ? record : latest, undefined,
       );
@@ -1875,6 +2121,9 @@ async function runSelfReviewCliCommandPinned(
         failed += 1;
         continue;
       }
+      claimedCapPath = join(effectiveInstanceRoot(), 'review-results', authorization
+        ? `cap-override-${pr}-head-${diffRead.headCommit.toLowerCase()}.json`
+        : `cap-override-${pr}.json`);
       deps.observeDoctorReview?.('cap-override', { pr, head: diffRead.headCommit, previousRoundCount, round: previousRoundCount + 1, reason }, { level: 'warn' });
     }
     if (mergeOnlyDeltaRange) {
@@ -1883,6 +2132,7 @@ async function runSelfReviewCliCommandPinned(
         const message = `PR ${pr}: merge-only 후속 head의 delta diff를 고정할 수 없습니다.`;
         deps.error(message);
         if (opts.json || opts.save !== undefined) results.push({ pr, error: message, reviewed: false, refusal: 'cap-refused', previousRoundCount, headCommit: diffRead.headCommit });
+        releaseCapClaim();
         failed += 1;
         continue;
       }
@@ -1897,32 +2147,58 @@ async function runSelfReviewCliCommandPinned(
       continue;
     }
     if (previousRoundCount >= 5 && authorization && !opts.reviewerMixCapClaimed) {
+      claimedCapPath = join(effectiveInstanceRoot(), 'review-results', `cap-override-${pr}-head-${diffRead.headCommit.toLowerCase()}.json`);
       deps.observeDoctorReview?.('cap-override', { pr, head: diffRead.headCommit, previousRoundCount, round: previousRoundCount + 1, reason: authorization.reason }, { level: 'warn' });
     }
     const localHeadComparison = compareLocalHead(pr, { value: diffRead.headCommit, state: diffRead.headCommitState }, deps);
     const { diff } = diffRead;
-    const baseReviewerContext = hasProvidedReviewerContext
-      ? providedReviewerContext
-      : loadPrDiffReviewerContext(pr, diffRead.headCommit, diffFilePaths(diff.stdout), deps);
+    const deltaContextPaths = deltaBase ? [...new Set(deltaBase.mustFix.flatMap(citedReviewPaths))] : undefined;
+    const baseReviewerContext = deltaBase
+      ? loadPrDiffReviewerContext(pr, diffRead.headCommit, deltaContextPaths ?? [], deps)
+      : hasProvidedReviewerContext
+        ? providedReviewerContext
+        : loadPrDiffReviewerContext(pr, diffRead.headCommit, diffFilePaths(diff.stdout), deps);
     const comparisonData = comparisonObservation(localHeadComparison);
     // ⛔ `relation-unknown` 도 경고한다(위 주석 · 리뷰가 두 라운드 반복 지적) — 그 밖 unavailable 은 조용하다.
     //    ⭐ 경고 여부 판정은 `localHeadWarningDetails` 한 곳에 있다(호출부에서 같은 함수를 두 번 부르지 않는다).
     const mismatchWarning = localHeadWarningDetails(localHeadComparison);
     const mergeState = readPrMergeState(pr, deps);
-    const view = deps.gh(['pr', 'view', pr, '--json', 'title,body'], 15_000);
+    const view = deltaBase ? { status: 1, stdout: '', stderr: '' }
+      : deps.gh(['pr', 'view', pr, '--json', 'title,body'], 15_000);
     let prView: { title?: string; body?: string } | undefined;
     if (view.status === 0) {
       try { prView = JSON.parse(view.stdout) as { title?: string; body?: string }; } catch { /* fallback below */ }
     }
     const title = prView?.title ?? '';
     const body = prView?.body;
-    const decompositionContext = lookupDecompositionContextForReview(`${title}\n${body ?? ''}`, deps);
-    const reviewerContext = appendDecompositionContext(baseReviewerContext, decompositionContext);
+    const decompositionContext = deltaBase ? { status: 'absent' as const }
+      : lookupDecompositionContextForReview(`${title}\n${body ?? ''}`, deps);
+    const pack = deltaBase || opts.noContextPack ? undefined : await import('./review-context-pack.js').then(({ buildReviewContextPack }) => buildReviewContextPack({
+      pr,
+      prTitle: title,
+      prBody: body ?? '',
+      files: diffFilePaths(diff.stdout),
+      rootDir: deps.reviewRepositoryPath,
+      gh: (args) => {
+        const result = deps.gh([...args], 15_000);
+        return result.status === 0
+          ? { ok: true, stdout: result.stdout }
+          : { ok: false, stdout: result.stdout, error: result.stderr || `gh exited ${String(result.status)}` };
+      },
+    }));
+    const contextWithPack = pack
+      ? { ...baseReviewerContext, items: [...baseReviewerContext.items, { label: 'review context pack', body: pack.text }] }
+      : baseReviewerContext;
+    const reviewerContext = appendDecompositionContext(contextWithPack, decompositionContext);
     const reviewerContextStatus = renderReviewerContextStatus(reviewerContext, decompositionContext);
     let intent: string;
     let intentSource: 'flag' | 'flag+pr-body' | 'pr-body' | 'pr-title' | 'fallback';
     let intentTruncation: ReturnType<typeof reviewIntentTruncationObservation>;
-    if (opts.intent !== undefined) {
+    if (deltaBase) {
+      intent = deltaReviewIntent(deltaBase);
+      intentTruncation = {};
+      intentSource = 'fallback';
+    } else if (opts.intent !== undefined) {
       if (body?.trim()) {
         const intentText = `## 명시 intent\n${opts.intent}\n\n## PR 본문\n${body.trim()}`;
         intent = buildManualReviewIntent(opts.intent, body.trim());
@@ -1941,7 +2217,7 @@ async function runSelfReviewCliCommandPinned(
       intentSource = body?.trim() ? 'pr-body' : title.trim() ? 'pr-title' : 'fallback';
       if (!intent) intent = `PR ${pr}`;
     }
-    if (previousRoundCount >= 2 && diff.status === 0 && !diffRead.stale && diffRead.headCommitState === 'known') {
+    if (!deltaBase && previousRoundCount >= 2 && diff.status === 0 && !diffRead.stale && diffRead.headCommitState === 'known') {
       if (!deps.loadDoctorReviewBrief) {
         deps.observeDoctorReview?.('brief-unavailable', { pr, head: diffRead.headCommit, previousRoundCount, reason: 'module-not-wired' });
       } else {
@@ -1989,22 +2265,40 @@ async function runSelfReviewCliCommandPinned(
         { pr: safeLogText(pr), exit: diff.status, error: safeLogText(diff.stderr || err, 160) },
         { level: 'warn' });
       const contextOutput = reviewerContextOutput(reviewerContext, decompositionContext);
-      if (opts.json || opts.save !== undefined) results.push({ pr, error: err, ...contextOutput, ...comparisonData, ...(mismatchWarning ?? {}) });
+      const errorResult = { pr, error: err, reviewed: false, headCommit: diffRead.headCommit,
+        currentHeadCommit: diffRead.currentHeadCommit, stale: diffRead.stale,
+        ...contextOutput, ...comparisonData, ...(mismatchWarning ?? {}) };
+      if (opts.json || opts.save !== undefined) results.push(errorResult);
+      if (canonicalResultPath && COMMIT_OID.test(diffRead.headCommit)
+        && diffRead.headCommitState === 'known' && diffRead.currentHeadCommitState === 'known'
+        && diffRead.currentHeadCommit === diffRead.headCommit && !diffRead.stale) {
+        try {
+          if (!existsSync(canonicalResultPath) || isReplaceableErrorArtifact(canonicalResultPath, pr, diffRead.headCommit)) {
+            mkdirSync(dirname(canonicalResultPath), { recursive: true });
+            writeFileSync(canonicalResultPath, selfReviewJsonLine([errorResult]));
+          }
+        } catch (error) {
+          deps.error(`PR ${pr}: 오류 리뷰 결과 저장 실패 (${canonicalResultPath}): ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
       if (!opts.json) deps.error(`PR ${pr}: ${err}\n${reviewerContextStatus}`);
+      releaseCapClaim();
       failed += 1;
       continue;
     }
     // ⭐ S2(2026-07-30) — 리뷰 증거를 **이 PR 이 저작한 변경**으로 좁힌다. 실측 7건에서 1건만
     //   좁히고(49→6) 나머지는 그대로다. ⚠️ 새 이벤트를 만들지 않는다 — 증거는 **입력의 성질**이므로
     //   `start` payload 에 싣는다(발화 순서 계약 보존).
-    const evidence = narrowEvidenceToAuthored(pr, diffRead.headCommit, diff.stdout, deps);
+    const evidence = deltaBase
+      ? { diff: diff.stdout, evidence: 'saved-review-delta' as const, prDiffFiles: diffFilePaths(diff.stdout).length }
+      : narrowEvidenceToAuthored(pr, diffRead.headCommit, diff.stdout, deps);
     const evidenceLine = renderEvidenceProvenance(evidence);
     // ⭐ 골 판정 신호는 reviewInput 조립 전에 PR당 한 번만 조회한다. ACP 폴백이 같은 객체를
     //    재사용하므로 리뷰 루프 안에서 queryRunChain 을 반복하지 않는다.
     const lookupGoalAcceptance = deps.lookupPrGoalAcceptance ?? lookupPrGoalAcceptance;
     let goalAcceptance: PrGoalAcceptanceLookup = { goalLoaded: false, acceptanceChars: 0 };
     try {
-      goalAcceptance = lookupGoalAcceptance(Number(pr));
+      if (!deltaBase) goalAcceptance = lookupGoalAcceptance(Number(pr));
     } catch {
       goalAcceptance = { goalLoaded: false, acceptanceChars: 0 };
     }
@@ -2052,6 +2346,7 @@ async function runSelfReviewCliCommandPinned(
       };
       if (opts.json || opts.save !== undefined) results.push(refused);
       if (!opts.json) deps.print(`\n━━ PR ${pr} (${primaryModel}) ━━\n${renderStaleRefusal(diffRead)}\n${reviewerContextStatus}`);
+      releaseCapClaim();
       continue;
     }
     // ⭐ 머지된 PR 만 머지 커밋 detached worktree 에서 리뷰한다 — main 최신이 아니라 그 PR 이 머지된 시점의 코드를 본다.
@@ -2096,7 +2391,7 @@ async function runSelfReviewCliCommandPinned(
     // ⛔ evidenceNote 는 **별도 채널**이다 — phaseIntent 에 섞으면 의도 채널이 오염된다(실측: 그렇게
     //   했다가 intent 배선 테스트 3개가 즉시 깨졌다).
     // ⛔ 사람 `--intent`(phaseIntent) 와 골 acceptance 는 다른 인자 — 충돌하지 않고, 충돌해도 intent 가 이긴다.
-    const reviewInput = {
+    const reviewInput: ReviewInput = {
       prDiff: evidence.diff,
       phaseIntent: intent,
       evidenceNote: evidenceLine,
@@ -2105,6 +2400,8 @@ async function runSelfReviewCliCommandPinned(
       ...(deps.readReferencedFile ? { readReferencedFile: deps.readReferencedFile } : {}),
       ...(goalAcceptance.acceptance ? { acceptance: goalAcceptance.acceptance } : {}),
     };
+    const reviewInputChars = reviewInputCharacterCount(reviewInput);
+    const intentFingerprint = reviewIntentFingerprint(reviewInput.phaseIntent);
     // ⭐ Role-config ACP lane: a completed ACP review is used as-is; anything else (throw, reviewed≠true)
     //    falls to the same API review this command ran before the lane existed — and is observed.
     // ⚠️ Stricter than the harness lane on purpose: `runSubscriptionReviewer` accepts any non-empty text;
@@ -2197,6 +2494,43 @@ async function runSelfReviewCliCommandPinned(
       claudeFallbackGlm = { reason, model: ZAI_OPENROUTER_FALLBACK_MODEL, glmReviewed: glmFailureReason === undefined,
         ...(glmFailureReason !== undefined ? { glmFailureReason } : {}) };
     }
+    const reviewDurationMs = Math.max(0, deps.now() - startedAt);
+    let deltaReceipt: Record<string, unknown> = {};
+    if (deltaBase) {
+      const assessed = assessDeltaReview(review, deltaBase);
+      const deltaEfficiency = {
+        inputRatio: reviewInputChars / deltaBase.reviewInputChars,
+        timeRatio: reviewDurationMs / deltaBase.reviewDurationMs,
+        maxRatio: 1 / 3,
+      };
+      const efficient = deltaEfficiency.inputRatio <= deltaEfficiency.maxRatio
+        && deltaEfficiency.timeRatio <= deltaEfficiency.maxRatio;
+      if (review.reviewed !== true) {
+        const reason = review.failureReason || 'delta-review-not-completed';
+        review = { ...review, reviewed: false, verdict: 'fail', mustFix: [], shouldFix: [], failureReason: reason };
+        deltaReceipt = { basedOn: deltaBase.headCommit, basedOnReview: deltaBase.file,
+          deltaInputChars: reviewInputChars, deltaDurationMs: reviewDurationMs, deltaEfficiency,
+          deltaRefusal: 'delta-review-not-completed' };
+      } else if (!assessed.valid) {
+        review = { ...review, reviewed: false, verdict: 'fail', mustFix: [], shouldFix: [],
+          failureReason: assessed.reason };
+        deltaReceipt = { basedOn: deltaBase.headCommit, basedOnReview: deltaBase.file,
+          deltaInputChars: reviewInputChars, deltaDurationMs: reviewDurationMs, deltaEfficiency,
+          deltaRefusal: assessed.reason };
+      } else if (!efficient) {
+        review = { ...review, reviewed: false, verdict: 'fail', mustFix: [], shouldFix: [],
+          failureReason: 'delta-efficiency-limit-exceeded' };
+        deltaReceipt = { basedOn: deltaBase.headCommit, basedOnReview: deltaBase.file,
+          deltaFindings: assessed.deltaFindings, deltaInputChars: reviewInputChars,
+          deltaDurationMs: reviewDurationMs, deltaEfficiency, deltaRefusal: 'delta-efficiency-limit-exceeded' };
+      } else {
+        review = { ...review, reviewed: true, verdict: assessed.mustFix.length ? 'fail' : 'pass',
+          mustFix: assessed.mustFix, shouldFix: [] };
+        deltaReceipt = { basedOn: deltaBase.headCommit, basedOnReview: deltaBase.file,
+          deltaFindings: assessed.deltaFindings, excludedNewFindings: assessed.excludedNewFindings,
+          deltaInputChars: reviewInputChars, deltaDurationMs: reviewDurationMs, deltaEfficiency };
+      }
+    }
     reviewPin?.remove();
     // reviewCwdCommit 은 «최종 판정을 낸 LLM 이 실제로 그 cwd 를 받았을 때만» 싣는다(role 실패 → API 폴백이면 안 싣는다).
     const reviewedOnPin = Boolean(reviewPin) && (roleReview ? rolePinned : reviewRoute === 'acp-fallback' ? true : reviewRoute === 'acp' && useAcp);
@@ -2299,7 +2633,7 @@ async function runSelfReviewCliCommandPinned(
     deps.log('done',
       {
         ...buildReviewObservation({
-          pr, model: selectedModel, intent, review, durationMs: deps.now() - startedAt,
+          pr, model: selectedModel, intent, intentFingerprint, review, durationMs: reviewDurationMs,
           ...reviewProvenance,
           ...intentTruncation,
           ...reviewDiffBudgetObservation(review),
@@ -2322,6 +2656,7 @@ async function runSelfReviewCliCommandPinned(
       const contextOutput = reviewerContextOutput(reviewerContext, decompositionContext);
       if (opts.json || opts.save !== undefined) results.push({ pr, error: err, ...review, verdict: null, ...reviewProvenance, ...respondedOutput, ...reviewerSelection, ...reviewCwdOutput, ...provenance, ...contextOutput });
       if (!opts.json) deps.error(`PR ${pr}: ${err}\n${renderProvenance(diffRead)}\n${reviewerContextStatus}`);
+      releaseCapClaim();
       failed += 1;
       continue;
     }
@@ -2330,7 +2665,27 @@ async function runSelfReviewCliCommandPinned(
     // ⛔ 금지 백엔드가 낸 판정은 «근거 거부»다 — verdict·mustFix 를 그대로 실어 보내면 읽는 쪽이
     //    그것을 착지 판정으로 쓴다(관문도 reviewed===true 를 근거 조건으로 본다).
     const refusalOverride = landingGateAdmitted ? {} : { reviewed: false, verdict: null, refusal: 'review-forbidden-acp-backend' as const };
-    if (opts.json || opts.save !== undefined) results.push({ pr, model: selectedModel, ...jsonReview, ...reviewProvenance, ...respondedOutput, ...reviewerSelection, ...reviewCwdOutput, ...provenance, ...contextOutput, ...refusalOverride, ...landingGateFields, findingPathHeadChecks, pathWarnings, evidence: evidence.evidence, prDiffFiles: evidence.prDiffFiles, ...(evidence.authoredFiles !== undefined ? { authoredFiles: evidence.authoredFiles } : {}) });
+    const resultOutput = { pr, model: selectedModel, ...jsonReview, reviewInputChars, reviewDurationMs,
+      ...(deltaBase ? deltaReceipt : {}), ...reviewProvenance, ...respondedOutput, ...reviewerSelection,
+      ...reviewCwdOutput, ...provenance, ...contextOutput, ...refusalOverride, ...landingGateFields,
+      findingPathHeadChecks, pathWarnings, evidence: evidence.evidence, prDiffFiles: evidence.prDiffFiles,
+      ...(evidence.authoredFiles !== undefined ? { authoredFiles: evidence.authoredFiles } : {}) };
+    if (opts.json || opts.save !== undefined || shouldPersistCapResult) results.push(resultOutput);
+    if (!shouldPersistCapResult
+      && landingGateAdmitted && review.reviewed === true && diffRead.headCommitState === 'known'
+      && diffRead.currentHeadCommitState === 'known' && diffRead.currentHeadCommit === diffRead.headCommit
+      && !diffRead.stale && COMMIT_OID.test(diffRead.headCommit)) {
+      const path = canonicalResultPath ?? join(effectiveInstanceRoot(), 'review-results', `pr-${pr}-${diffRead.headCommit.slice(0, 12)}.json`);
+      const normalized = normalizeSavedReviewMustFix(resultOutput);
+      try {
+        mkdirSync(dirname(path), { recursive: true });
+        // A successful review replaces an earlier error artifact for the same PR head.
+        writeFileSync(path, selfReviewJsonLine([normalized.result]));
+        if (normalized.count > 0 && opts.save === undefined) deps.log('mustfix-normalized', { pr, head: diffRead.headCommit, count: normalized.count });
+      } catch (error) {
+        deps.error(`PR ${pr}: 리뷰 결과 저장 실패 (${path}): ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
     if (!opts.json) {
       if (!landingGateAdmitted) deps.print(`\n━━ PR ${pr} (${selectedModel}) ━━\n${renderProvenance(diffRead)}\n⛔ LANDING GATE: review-forbidden-acp-backend (${landingGateDeniedBackend ?? 'unknown'}) — 이 리뷰는 착지 근거가 아닙니다.\n${reviewerContextStatus}`);
       else deps.print(`\n━━ PR ${pr} (${selectedModel}) ━━\n${renderProvenance(diffRead)}\n${evidenceLine}\n${reviewerContextStatus}\n${deps.renderReview(review)}${pathWarnings.length ? `\n${pathWarnings.join('\n')}` : ''}`);
@@ -2361,6 +2716,28 @@ async function runSelfReviewCliCommandPinned(
         }
       }
     }
+    if (shouldPersistCapResult) {
+      if (!landingGateAdmitted || review.reviewed !== true || !canonicalResultPath
+        || diffRead.headCommitState !== 'known' || diffRead.currentHeadCommitState !== 'known'
+        || diffRead.currentHeadCommit !== diffRead.headCommit || !COMMIT_OID.test(diffRead.headCommit)) {
+        releaseCapClaim();
+        deps.error(`PR ${pr}: 상한 예외 리뷰 결과가 저장 가능한 상태가 아니어서 승인 사용 기록을 되돌렸습니다.`);
+      } else {
+        const rawResult = results.at(-1);
+        const normalized = rawResult && typeof rawResult === 'object'
+          ? normalizeSavedReviewMustFix(rawResult)
+          : { result: rawResult, count: 0 };
+        try {
+          mkdirSync(dirname(canonicalResultPath), { recursive: true });
+          writeFileSync(canonicalResultPath, selfReviewJsonLine([normalized.result]));
+          if (normalized.count > 0) deps.log('mustfix-normalized', { pr, head: diffRead.headCommit, count: normalized.count });
+        } catch (error) {
+          releaseCapClaim();
+          failed += 1;
+          deps.error(`PR ${pr}: 상한 예외 리뷰 결과 저장 실패${canonicalResultPath ? ` (${canonicalResultPath})` : ''}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+    }
   }
   return { results, failed };
 }