elanous 0.2.13 → 0.2.14

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

@@ -0,0 +1,294 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dlopen, FFIType } from 'bun:ffi';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+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 }
+/** What a resume sweep hands its merge function: the held entry, marked as already claimed by this sweep. */
+export type ResumedMerge = FrozenMerge & { resumed: true };
+
+function queuePath(root: string): string { return join(root, 'landing-freeze-pending.json'); }
+
+/** flock(2) through bun:ffi — the kernel drops the lock when its holder exits, so there is no stale lock to reclaim
+ *  and no reclaim race. The lock file itself is never deleted (unlinking a flock file would split later lockers). */
+const LOCK_EX = 2, LOCK_NB = 4;
+let flockCall: ((fd: number, op: number) => number) | undefined;
+function flock(fd: number, op: number): number {
+  if (!flockCall) {
+    const names = process.platform === 'darwin' ? ['libc.dylib'] : ['libc.so.6', `libc.musl-${process.arch === 'arm64' ? 'aarch64' : 'x86_64'}.so.1`];
+    let lastError: unknown;
+    for (const name of names) {
+      try {
+        const lib = dlopen(name, { flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 } });
+        flockCall = (descriptor, operation) => lib.symbols.flock(descriptor, operation) as number;
+        break;
+      } catch (error) { lastError = error; }
+    }
+    if (!flockCall) throw new Error(`flock unavailable (${names.join(', ')}): ${String(lastError)}`);
+  }
+  return flockCall(fd, op);
+}
+
+export function tryLandingLock(path: string): (() => void) | null {
+  mkdirSync(dirname(path), { recursive: true });
+  const fd = openSync(path, 'a', 0o600);
+  if (flock(fd, LOCK_EX | LOCK_NB) !== 0) { closeSync(fd); return null; }
+  let released = false;
+  return () => { if (!released) { released = true; closeSync(fd); } };
+}
+
+function tryLock(path: string): (() => void) | null { return tryLandingLock(path); }
+
+function lockedQueue<T>(root: string, action: () => T): T {
+  mkdirSync(root, { recursive: true });
+  const path = join(root, 'landing-freeze-pending.lock');
+  const deadline = Date.now() + 5_000;
+  let release = tryLock(path);
+  while (!release) {
+    if (Date.now() >= deadline) throw new Error(`frozen merge queue lock busy: ${path}`);
+    Bun.sleepSync(25);
+    release = tryLock(path);
+  }
+  try { return action(); }
+  finally { release(); }
+}
+
+function readQueue(root: string): FrozenMerge[] {
+  const path = queuePath(root);
+  if (!existsSync(path)) return [];
+  const data: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!Array.isArray(data) || !data.every((item) => item && typeof item === 'object' &&
+    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}`);
+  return data as FrozenMerge[];
+}
+
+function writeQueue(root: string, entries: FrozenMerge[]): void {
+  mkdirSync(root, { recursive: true });
+  const path = queuePath(root);
+  const temp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(entries, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, path);
+  } finally { rmSync(temp, { force: true }); }
+}
+
+/** Ordering of two heads of one PR in `repoRoot`: 'older' when `a` is a strict ancestor of `b`, 'newer' when `b` is one
+ *  of `a`, otherwise unknown (unrelated, or git cannot see both objects). */
+function headOrder(repoRoot: string, a: string, b: string): 'older' | 'newer' | 'unknown' {
+  const ancestor = (x: string, y: string) => {
+    try { return Bun.spawnSync(['git', '-C', repoRoot, 'merge-base', '--is-ancestor', x, y], { env: process.env }).exitCode === 0; }
+    catch { return false; }
+  };
+  if (a === b) return 'unknown';
+  if (ancestor(a, b)) return 'older';
+  if (ancestor(b, a)) return 'newer';
+  return 'unknown';
+}
+
+/** GitHub's current head of the PR, or null when it cannot be read. */
+function githubHead(entry: FrozenMerge): string | null {
+  try {
+    const gh = Bun.which('gh', { PATH: process.env.PATH ?? '' }) ?? 'gh';
+    const view = Bun.spawnSync([gh, 'pr', 'view', String(entry.prNumber), '--json', 'headRefOid'], { cwd: entry.repoRoot, env: process.env, timeout: 30_000 });
+    if (view.exitCode !== 0) return null;
+    const head = (JSON.parse(view.stdout.toString()) as { headRefOid?: string }).headRefOid;
+    return typeof head === 'string' && /^[0-9a-f]{40}$/i.test(head) ? head : null;
+  } catch { return null; }
+}
+
+export function queueFrozenMerge(entry: FrozenMerge, root = effectiveInstanceRoot(), currentHead: (entry: FrozenMerge) => string | null = githubHead): void {
+  if (!Number.isSafeInteger(entry.prNumber) || entry.prNumber <= 0 || !/^[0-9a-f]{40}$/i.test(entry.headCommit) || !entry.repoRoot) throw new Error('invalid frozen merge entry');
+  const repoRoot = repoIdentity(entry.repoRoot);
+  // Slow lookups (git, GitHub) happen outside the queue lock; inside it only the held head they were judged against
+  // is re-checked — if it changed meanwhile, the judgement is made again.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const seen = readQueue(root).find((item) => item.repoRoot === repoRoot && item.prNumber === entry.prNumber)?.headCommit;
+    let keepExisting = false;
+    let by = 'none';
+    if (seen && seen !== entry.headCommit) {
+      const order = headOrder(repoRoot, entry.headCommit, seen);
+      if (order !== 'unknown') { keepExisting = order === 'older'; by = 'ancestry'; }
+      else { keepExisting = currentHead({ ...entry, repoRoot }) !== entry.headCommit; by = 'github-or-unknown'; }
+    }
+    const done = lockedQueue(root, () => {
+      const current = readQueue(root);
+      const existing = current.find((item) => item.repoRoot === repoRoot && item.prNumber === entry.prNumber);
+      if (existing?.headCommit !== seen) return false; // changed while we looked: judge again
+      if (existing && keepExisting) {
+        debug.log('harness.merge', 'frozen-head-kept', { pr: entry.prNumber, kept: existing.headCommit, ignored: entry.headCommit, by });
+        return true;
+      }
+      writeQueue(root, [...current.filter((item) => item !== existing), { ...entry, repoRoot }]);
+      return true;
+    });
+    if (done) return;
+  }
+  throw new Error(`frozen merge queue kept changing for PR ${entry.prNumber}`);
+}
+
+export function pendingFrozenMerges(root = effectiveInstanceRoot()): number { return readQueue(root).length; }
+
+/** The repository a run worktree belongs to, as a path that outlives the worktree: the main worktree when there is
+ *  one (also with a separate git dir), else the bare repository directory; the worktree itself only if git cannot say. */
+export function owningRepoRoot(worktree: string, spawn: typeof Bun.spawnSync = Bun.spawnSync): string | null {
+  let list: ReturnType<typeof Bun.spawnSync>;
+  try { list = spawn(['git', '-C', worktree, 'worktree', 'list', '--porcelain'], { env: process.env }); }
+  catch { return null; } // git could not even run: unknown owner — the held PR stays for a person
+  if (list.exitCode === 0) {
+    const first = (list.stdout?.toString() ?? "").split('\n\n')[0] ?? '';
+    const path = /^worktree (.+)$/m.exec(first)?.[1];
+    if (path) return path; // main worktree, or the bare repository directory (gh reads the remote from the git dir)
+  }
+  return null;
+}
+
+const sameEntry = (a: FrozenMerge, b: FrozenMerge) => a.prNumber === b.prNumber && a.repoRoot === b.repoRoot && a.headCommit === b.headCommit;
+
+/** One runner per held PR: whoever creates the claim file (resume sweep or the original lander) merges it. */
+/** One identity per repository path: symlinks and `..` resolve to the real path (absolute path when it does not exist). */
+export function repoIdentity(path: string): string {
+  try { return realpathSync(path); } catch { return resolve(path); }
+}
+
+/** A claim names the repository as well as the PR number — the queue tells PRs apart the same way. */
+export function claimPath(key: { prNumber: number; repoRoot: string }, root: string): string {
+  const repo = createHash('sha256').update(repoIdentity(key.repoRoot)).digest('hex').slice(0, 12);
+  return join(root, `landing-freeze-claim-${key.prNumber}-${repo}.lock`);
+}
+
+function claimFrozenMerge(entry: FrozenMerge, root: string): { release: () => void } | null {
+  mkdirSync(root, { recursive: true });
+  const release = tryLock(claimPath(entry, root));
+  return release ? { release } : null;
+}
+
+export type LandingAdmission =
+  | { kind: 'merge'; /** `true` once the merge is confirmed: drops this lander's own held entry. */ end: (merged?: boolean) => void }
+  | { kind: 'held'; freeze: LandingFreeze }
+  | { kind: 'taken' };
+
+/** Gate one merge/publication on the freeze. While frozen the entry is queued; if the freeze is lifted while queueing,
+ *  the entry is taken back and the caller merges now — unless a resume sweep already claimed it ('taken'). */
+export function admitLandingMerge(
+  heldEntry: FrozenMerge | null | (() => FrozenMerge | null),
+  root = effectiveInstanceRoot(),
+  hooks: { afterQueue?: () => void } = {},
+  claimKey?: { prNumber: number; repoRoot: string; headCommit?: string },
+): LandingAdmission {
+  let entry: FrozenMerge | null | undefined;
+  // A held PR is merged by exactly one runner: the claim (repository + PR) is held from admission until the lander's
+  // merge has ended. Its queue entry stays until that merge is confirmed — `end(true)` removes this lander's own head;
+  // a failed or interrupted merge leaves it for the next resume sweep.
+  let claim: { release: () => void } | null = null;
+  let ownHead: { prNumber: number; repoRoot: string; headCommit?: string } | null = null;
+  const finish = (landing: { end: () => void }, held: { release: () => void } | null, own: typeof ownHead) => (merged?: boolean) => {
+    try {
+      // Only a confirmed merge of a known head removes that head; without a head nothing is dequeued (a sweep will
+      // find the PR merged on GitHub and drop it).
+      if (merged && own?.headCommit) {
+        const head = own.headCommit;
+        lockedQueue(root, () => writeQueue(root, readQueue(root).filter((item) =>
+          item.prNumber !== own.prNumber || item.repoRoot !== own.repoRoot || item.headCommit !== head)));
+      }
+    } finally { landing.end(); held?.release(); }
+  };
+  for (;;) {
+    const landing = beginLandingMerge(root);
+    if (!landing.frozen) {
+      if (!claim && claimKey) {
+        const key = { prNumber: claimKey.prNumber, repoRoot: repoIdentity(claimKey.repoRoot), headCommit: claimKey.headCommit };
+        const queued = () => readQueue(root).some((item) => item.prNumber === key.prNumber && item.repoRoot === key.repoRoot);
+        if (existsSync(claimPath(key, root)) || queued()) {
+          const probe = tryLock(claimPath(key, root));
+          if (!probe) { landing.end(); return { kind: 'taken' }; }
+          claim = { release: probe };
+          ownHead = key;
+        }
+      }
+      return { kind: 'merge', end: finish(landing, claim, ownHead) };
+    }
+    claim?.release();
+    claim = null;
+    ownHead = null;
+    if (entry === undefined) entry = typeof heldEntry === 'function' ? heldEntry() : heldEntry; // only built when frozen
+    if (!entry) return { kind: 'held', freeze: landing.frozen };
+    queueFrozenMerge(entry, root);
+    hooks.afterQueue?.();
+    if (readLandingFreeze(root)) return { kind: 'held', freeze: landing.frozen };
+    const mine = { ...entry, repoRoot: repoIdentity(entry.repoRoot) };
+    claim = claimFrozenMerge(mine, root);
+    if (!claim) return { kind: 'taken' };
+    // A resume sweep already merged and dequeued it between our queueing and our claim: nothing left to merge.
+    let stillHeld = false;
+    try { stillHeld = readQueue(root).some((item) => sameEntry(item, mine)); }
+    catch (error) { claim.release(); throw error; }
+    if (!stillHeld) { claim.release(); return { kind: 'taken' }; }
+    ownHead = mine;
+    debug.log('harness.merge', 'freeze-lifted-while-queueing', { pr: entry.prNumber });
+  }
+}
+
+/** Default «is this PR already merged at this head?» check — GitHub is the final word. */
+function githubMergedAt(entry: FrozenMerge): boolean {
+  try {
+    // Resolve gh against the current PATH (Bun's spawn would otherwise use the PATH from process start).
+    const gh = Bun.which('gh', { PATH: process.env.PATH ?? '' }) ?? 'gh';
+    const view = Bun.spawnSync([gh, 'pr', 'view', String(entry.prNumber), '--json', 'state,headRefOid'], { cwd: entry.repoRoot, env: process.env, timeout: 30_000 });
+    if (view.exitCode !== 0) return false;
+    const pr = JSON.parse(view.stdout.toString()) as { state?: string; headRefOid?: string };
+    return pr.state === 'MERGED' && pr.headRefOid === entry.headCommit;
+  } catch { return false; } // unknown is «not known merged»: the head-pinned merge still refuses a second merge
+}
+
+/** Invoke at a supervision tick. A failed re-gate remains queued; only a confirmed merge is removed.
+ *  «Merged once» does not rest on the claim lock alone: every merge is pinned to the held head
+ *  (`gh pr merge --match-head-commit`, which refuses an already-merged PR), and before and after each attempt the
+ *  sweep asks GitHub whether the PR is already merged at that head — a duplicate runner can at most repeat a re-gate. */
+export async function sweepFrozenMerges(
+  merge: (entry: ResumedMerge) => Promise<{ passed: boolean; status?: string }> = async (entry) => {
+    const { runHostRegate } = await import('./host-regate.js');
+    return runHostRegate(entry);
+  },
+  root = effectiveInstanceRoot(),
+  alreadyMerged: (entry: FrozenMerge) => boolean | Promise<boolean> = githubMergedAt,
+): Promise<{ pending: number; merged: number }> {
+  const frozen = readLandingFreeze(root);
+  if (frozen) return { pending: readQueue(root).length, merged: 0 };
+  const pending = readQueue(root);
+  let merged = 0;
+  for (const entry of pending) {
+    if (readLandingFreeze(root)) break;
+    const claim = claimFrozenMerge(entry, root);
+    if (!claim) continue; // another sweep or the original lander is on it
+    try {
+      if (!readQueue(root).some((item) => sameEntry(item, entry))) continue; // taken back by its lander
+      if (entry.manual) { debug.log('harness.merge', 'resume-manual', { pr: entry.prNumber, repoRoot: entry.repoRoot }); continue; }
+      if (!(await alreadyMerged(entry))) {
+        const outcome = await merge({ ...entry, resumed: true });
+        if (outcome.status === 'frozen') continue;
+        // Whatever the merge call reported, only GitHub showing the PR merged at the held head dequeues it.
+        if (!(await alreadyMerged(entry))) {
+          if (outcome.passed) debug.log('harness.merge', 'resume-unconfirmed', { pr: entry.prNumber, head: entry.headCommit });
+          continue;
+        }
+      }
+      lockedQueue(root, () => {
+        const current = readQueue(root);
+        if (current.some((item) => sameEntry(item, entry))) {
+          writeQueue(root, current.filter((item) => !sameEntry(item, entry)));
+          merged++;
+        }
+      });
+    } catch (error) {
+      debug.log('harness.merge', 'resume-failed', { pr: entry.prNumber, error: String(error) });
+    } finally { claim.release(); }
+  }
+  return { pending: readQueue(root).length, merged };
+}

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

@@ -12,6 +12,8 @@ import { runMockModuleRestoreGate } from '../../scripts/ci-mock-module-restore-g
 import { parseReviewDepthFromFilesJson } from '../agent-mission/review-depth.js';
 import { buildGateBaselineReport, calculateGateTestCountChange, formatGateBaselineNote, formatGateTestCountNote, isGateTestFile, runGateBaseline, type BaselineProcessResult, type BaselineProcessStatus, type GateTestFailure } from './gate-baseline.js';
 import { resolveGateScope } from './gate-scope.js';
+import { publicExposureFiles, runExposeGate } from './expose-gate.js';
+import { getUserConfig } from '../user-config.js';
 import { debug } from '../debug/log.js';
 import { buildDocumentGuardianIndex, formatDocumentGuardians } from './document-guardian-index.js';
 import { buildImporterTestIndex, isTestPath, type ImporterTestIndex } from './importer-test-index.js';
@@ -585,6 +587,9 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     ? buildRouteConsumerTestIndex(cwd, availableIndex.testPaths, selection.files, selection.baseRef) : null;
   const scope = resolveGateScope(selection.files, exists, availableIndex,
     { routeConsumerTestIndex: routeIndex ?? undefined });
+  const expose = publicExposureFiles(selection.files).length > 0
+    ? runExposeGate(cwd, selection.files, getUserConfig().harness?.exposeGate === 'strict' ? 'strict' : 'warn', deps.runCommand)
+    : { passed: true, log: '' };
   const testFiles = [...(scope.testArgs ?? [])];
   const unrunImporterTotal = lookupFailed ? null : (scope.importerTestsNotRun?.total ?? 0);
   const importerLookupFailed = Boolean(lookupFailed);
@@ -615,6 +620,7 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     ...(scope.callerTestsOverflow.length ? [`⚠️ caller test cap exceeded — not run: ${scope.callerTestsOverflow.map(({ file, reasons }) => `${file} (${reasons.join('+')})`).join(', ')}`] : []),
     changedTestCountNote(cwd, selection.files, selection.baseRef, deps.runCommand, deps.readFile),
   ];
+  if (expose.log) lines.push(expose.log);
   if (options.pr) {
     const worktreeObservation = observePrWorktreeDirtiness(cwd, selection.prHeadRefName, {
       runCommand: deps.runCommand,
@@ -638,7 +644,7 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   if (scope.skipTestStep) {
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
-    return { exitCode: androidPassed && iosPassed && pwaPassed && policyPassed ? 0 : 1, lines, changedFiles: selection.files, testFiles: [], unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
+    return { exitCode: androidPassed && iosPassed && pwaPassed && policyPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles: [], unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
   }
 
   if (options.shards !== undefined) {
@@ -662,7 +668,7 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     }
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     return {
-      exitCode: aggregate.status !== 'passed' || !policyPassed || !androidPassed || !iosPassed || !pwaPassed ? 1 : 0,
+      exitCode: aggregate.status !== 'passed' || !policyPassed || !androidPassed || !iosPassed || !pwaPassed || !expose.passed ? 1 : 0,
       lines, changedFiles: selection.files, testFiles, unverified: scope.unverified,
       documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests,
     };
@@ -674,7 +680,7 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, `tests: pass (${testFiles.length} files)`));
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
-    return { exitCode: policyPassed && androidPassed && iosPassed && pwaPassed ? 0 : 1, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
+    return { exitCode: policyPassed && androidPassed && iosPassed && pwaPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
   }
 
   if (worktreeLog.includes('deterministic environment setup failed')) lines.push(worktreeLog);
@@ -695,6 +701,6 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   });
   lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, formatGateBaselineNote(report, unrunImporterTotal ?? 0)));
   const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
-  const exitCode = !androidPassed || !iosPassed || !pwaPassed || !policyPassed || report.introduced > 0 || report.unknown > 0 || report.preconditionUnmet > 0 ? 1 : 0;
+  const exitCode = !androidPassed || !iosPassed || !pwaPassed || !policyPassed || !expose.passed || report.introduced > 0 || report.unknown > 0 || report.preconditionUnmet > 0 ? 1 : 0;
   return { exitCode, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
 }

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' };
 }