elanous 0.2.36 → 0.2.38

package/src/self-implement/knowhow-pack.ts

@@ -1,5 +1,6 @@
 /** Bounded, read-only context from promoted repository knowhow. */
 import { lstatSync, readFileSync, realpathSync, readdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { join, relative, resolve, sep } from 'node:path';
 
 export const KNOWHOW_PACK_MAX_BYTES = 4096;
@@ -10,6 +11,109 @@ export interface KnowhowPack {
   text: string;
   ids: string[];
   bytes: number;
+  reason: 'selected' | 'marker-present' | 'source-unreadable' | 'no-promoted-section' | 'no-path-overlap' | 'over-budget';
+}
+
+export interface SelectedAuthoringLessons {
+  readonly ids: readonly string[];
+  readonly prompt: string;
+  readonly status: 'loaded' | 'missing' | 'malformed' | 'unreadable' | 'empty';
+  readonly invalidRows: number;
+}
+
+const AUTHORING_LESSONS_MAX_BYTES = 2_000;
+const AUTHORING_LESSONS_MAX_ITEMS = 2;
+const AUTHORING_LESSON_CLASSES = new Set([
+  'a-missing-predecessor', 'b-stale-path', 'c-unbounded-goal', 'd-rigid-acceptance',
+  'e-format-trap', 'f-unaware-of-code', 'g-umbrella-scope', 'env-provider',
+  'env-capacity', 'env-stale-image',
+]);
+
+function authoringLessonClassHints(ask: string, targetPaths: readonly string[]): Set<string> {
+  const hints = new Set<string>();
+  const rules: readonly [string, RegExp][] = [
+    ['a-missing-predecessor', /predecessor|prerequisite|depends on|dependency|선행|의존|먼저 완료/iu],
+    ['b-stale-path', /unsupported path|missing path|path does not exist|not exist|경로.{0,12}(?:없|존재하지)|없는 파일|대상 경로.{0,12}없/iu],
+    ['c-unbounded-goal', /unbounded|no scope boundary|scope is unclear|범위.{0,12}(?:무한|불명확|제한 없|경계 없)/iu],
+    ['d-rigid-acceptance', /acceptance criteria|acceptance test|검수 기준|수용 기준|판정 조건/iu],
+    ['e-format-trap', /format|schema|json|template|형식|스키마|문면/iu],
+    ['f-unaware-of-code', /already implemented|existing code|cli registration|entry point|이미 구현|기존 코드|등록 파일|진입점/iu],
+    ['g-umbrella-scope', /umbrella|over.?scope|too broad|too many targets|여러 목표|범위가 넓|너무 넓|한 골에|포괄 골/iu],
+    ['env-provider', /provider|model|llm|모델|프로바이더/iu],
+    ['env-capacity', /capacity|resource|oom|용량|부하|자원/iu],
+    ['env-stale-image', /stale image|image mismatch|오래된 이미지|이미지 불일치/iu],
+  ];
+  for (const [lessonClass, pattern] of rules) if (pattern.test(ask)) hints.add(lessonClass);
+  if (targetPaths.length > 5) hints.add('g-umbrella-scope');
+  return hints;
+}
+
+function authoringAskPaths(ask: string): string[] {
+  const paths = new Set<string>();
+  for (const match of ask.matchAll(/(?<![\w./~-])([\w.-]+(?:\/[\w.-]+)+)/gu)) {
+    const path = match[1].replace(/[.,;:!?]+$/u, '');
+    const parts = path.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..')) continue;
+    if (/\.[\w-]+$/u.test(parts.at(-1) ?? '')) paths.add(path);
+  }
+  return [...paths];
+}
+
+/** Select up to two relevant lessons, capped by rendered prompt size. Bad optional ledgers only emit observation. */
+export function selectRelevantAuthoringLessons(root: string, ask: string): SelectedAuthoringLessons {
+  const path = join(root, 'docs', 'goal-context', '05-authoring-lessons.jsonl');
+  let source: string;
+  try { source = readFileSync(path, 'utf8'); }
+  catch (error) {
+    return { ids: [], prompt: '', status: (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'missing' : 'unreadable', invalidRows: 0 };
+  }
+  const rows: Record<string, unknown>[] = [];
+  let invalidRows = 0;
+  for (const line of source.split(/\r?\n/u)) {
+    if (!line.trim()) continue;
+    try {
+      const value: unknown = JSON.parse(line);
+      if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('not an object');
+      const row = value as Record<string, unknown>;
+      if (typeof row.lesson !== 'string' || typeof row.class !== 'string') throw new Error('missing lesson/class');
+      // The canonical ledger predates the closed class vocabulary and contains three `other` rows.
+      // Ignore those rows individually so valid lessons remain usable; never inject an unknown class.
+      if (!AUTHORING_LESSON_CLASSES.has(row.class) && !/^env-[a-z0-9-]+$/u.test(row.class)) { invalidRows += 1; continue; }
+      rows.push(row);
+    } catch {
+      invalidRows += 1;
+      return { ids: [], prompt: '', status: 'malformed', invalidRows };
+    }
+  }
+  if (rows.length === 0) return { ids: [], prompt: '', status: 'empty', invalidRows };
+  const targetPaths = authoringAskPaths(ask);
+  const classHints = authoringLessonClassHints(ask, targetPaths);
+  const ranked = rows.map((row, index) => {
+    const lessonPaths = typeof row.paths === 'string' ? row.paths.split(/\s*[·,]\s*/u).filter(Boolean) : [];
+    const pathMatches = lessonPaths.some((lessonPath) => targetPaths.some((target) =>
+      target === lessonPath || target.startsWith(`${lessonPath}/`) || lessonPath.startsWith(`${target}/`)));
+    const classMatch = classHints.has(String(row.class));
+    const score = (pathMatches ? 4 : 0) + (classMatch ? 2 : 0);
+    const lesson = String(row.lesson).trim().replace(/\s+/gu, ' ');
+    const cell = typeof row.cell === 'string' ? row.cell.trim() : '';
+    const run = typeof row.run === 'string' && row.run.trim() ? row.run.trim() : '';
+    const suppliedId = typeof row.id === 'string' && /^[A-Za-z0-9._:-]{1,80}$/u.test(row.id) ? row.id : undefined;
+    const digest = createHash('sha256').update(JSON.stringify([row.ts ?? '', row.cell ?? '', row.class, row.lesson, row.paths ?? ''])).digest('hex').slice(0, 10);
+    const id = suppliedId ?? `AL-${digest}`;
+    const detail = [cell && `칸=${cell}`, `class=${row.class}`, `lesson=${lesson}`, run && `run=${run}`].filter(Boolean).join(' · ');
+    return { id, detail, score, index, timestamp: typeof row.ts === 'string' ? row.ts : '' };
+  }).filter((row) => row.score > 0)
+    .sort((left, right) => right.score - left.score || right.timestamp.localeCompare(left.timestamp) || left.index - right.index);
+  const selected: { id: string; detail: string }[] = [];
+  for (const candidate of ranked) {
+    if (selected.length >= AUTHORING_LESSONS_MAX_ITEMS) break;
+    const line = `- [${candidate.id}] ${candidate.detail}`;
+    const next = [...selected.map((entry) => `- [${entry.id}] ${entry.detail}`), line].join('\n');
+    if (Buffer.byteLength(next, 'utf8') > AUTHORING_LESSONS_MAX_BYTES) continue;
+    selected.push({ id: candidate.id, detail: candidate.detail });
+  }
+  const prompt = selected.map((entry) => `- [${entry.id}] ${entry.detail}`).join('\n');
+  return { ids: selected.map((entry) => entry.id), prompt, status: 'loaded', invalidRows };
 }
 
 function inside(root: string, path: string): boolean {
@@ -42,8 +146,8 @@ function mentionedPaths(text: string): Set<string> {
   return paths;
 }
 
-function relevance(goal: string, section: string): number {
-  const paths = mentionedPaths(goal);
+function relevance(goal: string, section: string, targetPaths?: readonly string[]): number {
+  const paths = targetPaths === undefined ? mentionedPaths(goal) : new Set(targetPaths);
   const sourcePaths = mentionedPaths(section);
   let score = 0;
   for (const path of paths) {
@@ -58,18 +162,21 @@ function relevance(goal: string, section: string): number {
   return score;
 }
 
-/** Reads only 내부 문서 `KNOWHOW` inside the supplied repository. */
-export function selectKnowhowPack(repo: string, goal: string): KnowhowPack {
-  if (goal.includes(MARKER)) return { text: '', ids: [], bytes: 0 };
+/** Reads only 내부 문서 `KNOWHOW` inside the supplied repository. Verified target paths narrow relevance when supplied. */
+export function selectKnowhowPack(repo: string, goal: string, targetPaths?: readonly string[]): KnowhowPack {
+  const empty = (reason: KnowhowPack['reason']): KnowhowPack => ({ text: '', ids: [], bytes: 0, reason });
+  if (goal.includes(MARKER)) return empty('marker-present');
   const rolesDir = resolve(repo, 'docs/roles');
   let realRoles: string;
   try {
     realRoles = realpathSync(rolesDir);
-    if (!inside(realpathSync(repo), realRoles)) return { text: '', ids: [], bytes: 0 };
-  } catch { return { text: '', ids: [], bytes: 0 }; }
+    if (!inside(realpathSync(repo), realRoles)) return empty('source-unreadable');
+  } catch { return empty('source-unreadable'); }
   const candidates: Array<{ id: string; text: string; score: number }> = [];
   let seatDirs: string[];
-  try { seatDirs = readdirSync(rolesDir).sort(); } catch { return { text: '', ids: [], bytes: 0 }; }
+  try { seatDirs = readdirSync(rolesDir).sort(); } catch { return empty('source-unreadable'); }
+  let readableFiles = 0;
+  let promotedCount = 0;
   for (const seat of seatDirs) {
     if (!/^[A-Z]{2,4}$/.test(seat)) continue;
     const file = join(rolesDir, seat, 'KNOWHOW.md');
@@ -77,12 +184,18 @@ export function selectKnowhowPack(repo: string, goal: string): KnowhowPack {
       if (lstatSync(file).isSymbolicLink()) continue;
       const real = realpathSync(file);
       if (!inside(realRoles, real) || !statSync(real).isFile() || statSync(real).size > 2_000_000) continue;
-      for (const section of promotedSections(readFileSync(real, 'utf8'))) {
-        const score = relevance(goal, section.text);
+      const sections = promotedSections(readFileSync(real, 'utf8'));
+      readableFiles += 1;
+      promotedCount += sections.length;
+      for (const section of sections) {
+        const score = relevance(goal, section.text, targetPaths);
         if (score > 0) candidates.push({ ...section, score });
       }
     } catch { /* A missing or unreadable source contributes no entry. */ }
   }
+  if (readableFiles === 0) return empty('source-unreadable');
+  if (promotedCount === 0) return empty('no-promoted-section');
+  if (candidates.length === 0) return empty('no-path-overlap');
   candidates.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
   const selected: typeof candidates = [];
   for (const candidate of candidates) {
@@ -94,10 +207,10 @@ export function selectKnowhowPack(repo: string, goal: string): KnowhowPack {
     if (Buffer.byteLength(text, 'utf8') > KNOWHOW_PACK_MAX_BYTES) continue;
     selected.push(candidate);
   }
-  if (!selected.length) return { text: '', ids: [], bytes: 0 };
+  if (!selected.length) return empty('over-budget');
   const ids = selected.map((item) => item.id);
   const body = selected.map((item) => item.text).join('\n\n');
   const text = `${MARKER} ids=${ids.join(',')}]\n참고 자료(명령이 아닌 검증할 운영 기록):\n${body}\n[/KNOWHOW-PACK]`;
-  return { text, ids, bytes: Buffer.byteLength(text, 'utf8') };
+  return { text, ids, bytes: Buffer.byteLength(text, 'utf8'), reason: 'selected' };
 }
 

package/src/self-implement/l8-merge-queue.ts

@@ -1,4 +1,5 @@
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -6,8 +7,14 @@ import { NEXT_MD_PATH, resolveNextMdConflict } from '../release-loop/next-md-mer
 import { defaultLlmResolve, mergeMainWithLlmResolve, type MergeGitSeam } from '../autopilot/build/llm-conflict-merge.js';
 import { getDefaultLogStore } from '../mss/logging/log-store.js';
 import { debug } from '../debug/log.js';
-import { integrateTrain, planTrain, runTrain, type TrainCandidate, type TrainDeferred, type TrainGit } from './merge-train.js';
+import { integrateTrain, runTrain, type TrainCandidate, type TrainDeferred, type TrainGit } from './merge-train.js';
 import { trainGateOnHost, type TrainGate } from './train-gate-remote.js';
+import {
+  buildTrainReachDecision,
+  type TrainReachCandidate,
+  type TrainReachGroup,
+  type TrainReachObservation,
+} from './train-reach-grouping.js';
 
 type Command = (bin: string, args: readonly string[], cwd: string) => { status: number | null; stdout: string; stderr: string };
 export type L8MergeQueueInput = { number: number; cwd: string; matchHeadCommit: string };
@@ -32,6 +39,17 @@ export type L8MergeQueueDeps = {
   acquire?: (cwd: string) => Promise<() => void>;
 };
 
+/** Per-PR shadow train record: reach group, tests, and the integrate/bisect verdict. */
+export type L8ShadowPrManifest = {
+  number: number;
+  head: string;
+  group: number[];
+  reachTests: string[];
+  interactionTests: string[];
+  queueSig: string;
+  gatesRun: number;
+  verdict: L8ShadowVerdict['verdict'];
+};
 export type L8ShadowVerdict = {
   number: number;
   head: string;
@@ -41,6 +59,8 @@ export type L8ShadowVerdict = {
   detail?: string;
   tests: string[];
   at: string;
+  /** Present when this verdict came from a reach-grouped shadow train. */
+  manifest?: L8ShadowPrManifest;
 };
 export type L8ShadowQueueItem = {
   number: number;
@@ -50,7 +70,9 @@ export type L8ShadowQueueItem = {
   overlapsWith?: number[];
   overlapsUnknownWith?: number[];
 };
-export type L8ShadowQueueState = { pending: L8ShadowQueueItem[]; verdicts: L8ShadowVerdict[] };
+/** Reach precheck outcome for a queued PR this run could not pin (stale view, changed head, or worktree failure). */
+export type L8ShadowDeferred = { number: number; head: string; reason: string; at: string };
+export type L8ShadowQueueState = { pending: L8ShadowQueueItem[]; verdicts: L8ShadowVerdict[]; deferred?: L8ShadowDeferred[] };
 export type L8ShadowEnqueueObservation = {
   number: number;
   head: string;
@@ -68,8 +90,10 @@ export type L8ShadowQueueDeps = L8MergeQueueDeps & {
   trainGate?: (repo: string, baseSha: string) => TrainGate;
   /** Shadow merge train integration git seam (default: the queue's own command executor). */
   trainGit?: TrainGit;
-  /** Maximum PRs per shadow train batch (default 2). */
+  /** Maximum PRs per shadow train batch (default 5, the reach-group capacity). */
   trainMaxBatch?: number;
+  /** Reach observation seam (default: inspect each fetched PR worktree via buildTrainReachDecision). */
+  trainReachInspect?: (candidate: TrainReachCandidate, baseSha: string) => TrainReachObservation;
 };
 
 function shadowCommand(execute: Command, bin: string, args: string[], cwd: string): string {
@@ -89,7 +113,8 @@ function readShadowQueue(path: string): L8ShadowQueueState {
   const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
   if (!value || typeof value !== 'object' || !('pending' in value) || !Array.isArray(value.pending)
     || !value.pending.every((p: { number?: number; head?: string }) => Number.isSafeInteger(p?.number) && p.number! > 0 && typeof p.head === 'string' && /^[0-9a-f]{40}$/i.test(p.head))
-    || !('verdicts' in value) || !Array.isArray(value.verdicts)) throw new Error('invalid shadow queue ledger');
+    || !('verdicts' in value) || !Array.isArray(value.verdicts)
+    || !('deferred' in value ? Array.isArray(value.deferred) : true)) throw new Error('invalid shadow queue ledger');
   return value as L8ShadowQueueState;
 }
 
@@ -180,10 +205,94 @@ export async function enqueueL8ShadowQueue(cwd: string, number: number, deps: L8
   });
 }
 
-/** LAND-QUEUE — shadow merge train: planTrain → integrateTrain → runTrain(trainGateOnHost) when the queue holds
- *  two or more measured, non-overlapping PRs. Per-PR verdicts (pass · culprit · unmeasured) land in the queue
- *  ledger and in debug.log ('self-implement.merge-train' · 'shadow-verdict'). Shadow only: no push, no merge API;
- *  the single-PR evaluation path in runL8ShadowQueue stays untouched for every queue this train cannot take. */
+function shadowQueueSig(base: string, pending: readonly L8ShadowQueueItem[]): string {
+  return createHash('sha256').update(`${base}\0${pending.map((item) => `${item.number}:${item.head}`).join('\0')}`).digest('hex');
+}
+
+function shadowReachWorktree(cwd: string, run: (bin: string, args: string[], where?: string) => string, item: L8ShadowQueueItem, base: string): string {
+  const tree = mkdtempSync(join(tmpdir(), `elanous-l8-reach-${item.number}-`));
+  try {
+    run('git', ['worktree', 'add', '--detach', tree, item.head], cwd);
+    if (run('git', ['rev-parse', 'HEAD'], tree) !== item.head) throw new Error(`reach worktree HEAD changed: #${item.number}`);
+    run('git', ['cat-file', '-e', `${base}^{commit}`], tree);
+    return tree;
+  } catch (error) {
+    try { run('git', ['worktree', 'remove', '--force', tree], cwd); } catch { /* still delete the directory */ }
+    rmSync(tree, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function pinShadowReachCandidates(
+  cwd: string,
+  run: (bin: string, args: string[], where?: string) => string,
+  pending: readonly L8ShadowQueueItem[],
+  base: string,
+  skip: ReadonlySet<number>,
+): { candidates: TrainReachCandidate[]; trees: string[]; failures: { number: number; head: string; reason: string }[] } {
+  const candidates: TrainReachCandidate[] = [];
+  const trees: string[] = [];
+  const failures: { number: number; head: string; reason: string }[] = [];
+  for (const item of pending) {
+    if (skip.has(item.number) || item.filesUnmeasured || !item.files?.length) continue;
+    try {
+      const tree = shadowReachWorktree(cwd, run, item, base);
+      trees.push(tree);
+      candidates.push({ pr: String(item.number), headSha: item.head, tree, changedFiles: [...item.files] });
+    } catch (error) {
+      // shadowReachWorktree cleans up its own tree; this PR only leaves the reach candidate set.
+      failures.push({ number: item.number, head: item.head, reason: String(error) });
+    }
+  }
+  return { candidates, trees, failures };
+}
+
+/** Keep one deferred record per queued PR (latest reason wins) so the ledger stays bounded. */
+function recordShadowDeferred(state: L8ShadowQueueState, entries: readonly L8ShadowDeferred[]): void {
+  const rest = (state.deferred ?? []).filter((entry) => !entries.some((current) => current.number === entry.number));
+  state.deferred = [...rest, ...entries];
+}
+
+function planShadowReachTrain(
+  pending: readonly L8ShadowQueueItem[],
+  group: TrainReachGroup,
+  { maxBatch }: { maxBatch: number },
+): { batch: TrainCandidate[]; deferred: TrainDeferred[] } {
+  const byNumber = new Map(pending.map((item) => [item.number, item]));
+  const numbers = group.prs.map((pr) => Number(pr)).filter((number) => byNumber.has(number));
+  const batch: TrainCandidate[] = [];
+  const deferred: TrainDeferred[] = [];
+  for (const number of numbers) {
+    const item = byNumber.get(number)!;
+    const candidate: TrainCandidate = { number: item.number, head: item.head, files: item.files, filesUnmeasured: item.filesUnmeasured };
+    if (batch.length < maxBatch) batch.push(candidate);
+    else deferred.push({ number, reason: 'overlap', with: batch.map((entry) => entry.number) });
+  }
+  return { batch, deferred };
+}
+
+function shadowPrManifest(
+  item: TrainCandidate,
+  group: TrainReachGroup,
+  queueSig: string,
+  gatesRun: number,
+  verdict: L8ShadowVerdict['verdict'],
+): L8ShadowPrManifest {
+  return {
+    number: item.number,
+    head: item.head,
+    group: group.prs.map((pr) => Number(pr)),
+    reachTests: [...group.reachTests],
+    interactionTests: [...group.interactionTests],
+    queueSig,
+    gatesRun,
+    verdict,
+  };
+}
+
+/** LAND-QUEUE — shadow merge train: pinned queue → buildTrainReachDecision → integrateTrain → runTrain.
+ *  Per-PR verdicts (pass · culprit · unmeasured) land in the queue ledger with a reach-group manifest.
+ *  Shadow only: no push, no merge API; the single-PR evaluation path stays for every queue this train cannot take. */
 async function runShadowMergeTrain(
   state: L8ShadowQueueState,
   path: string,
@@ -191,6 +300,9 @@ async function runShadowMergeTrain(
   run: (bin: string, args: string[], where?: string) => string,
   execute: Command,
   plan: { batch: TrainCandidate[]; deferred: TrainDeferred[] },
+  group: TrainReachGroup,
+  queueSig: string,
+  base: string,
   deps: L8ShadowQueueDeps,
 ): Promise<L8ShadowVerdict | null> {
   for (const item of plan.batch) {
@@ -200,9 +312,6 @@ async function runShadowMergeTrain(
     if (view.headRefOid !== item.head || view.baseRefName !== 'main' || view.state !== 'OPEN'
       || view.isDraft !== false || view.isCrossRepository !== false) throw new Error(`queued PR #${item.number} changed or is not ready`);
   }
-  run('git', ['fetch', 'origin', 'refs/heads/main'], cwd);
-  const base = run('git', ['rev-parse', 'FETCH_HEAD'], cwd);
-  if (!/^[0-9a-f]{40}$/i.test(base)) throw new Error('main commit unavailable');
   for (const item of plan.batch) {
     run('git', ['fetch', 'origin', `refs/pull/${item.number}/head`], cwd);
     if (run('git', ['rev-parse', 'FETCH_HEAD'], cwd) !== item.head) throw new Error(`fetched PR head changed: #${item.number}`);
@@ -213,49 +322,106 @@ async function runShadowMergeTrain(
     integrate: (batch) => integrateTrain(cwd, base, batch, trainGit),
     gate,
     deferred: plan.deferred,
-    // The train's observation channel is debug.log (LAND-QUEUE); the ledger below carries the authoritative state.
     observe: (data) => { debug.log('self-implement.merge-train', 'shadow-verdict', data); },
   });
   const at = new Date().toISOString();
   const batchNumbers = plan.batch.map((item) => item.number);
-  const verdicts: L8ShadowVerdict[] = result.verdicts.map((entry) => ({
-    number: entry.number,
-    head: plan.batch.find((item) => item.number === entry.number)!.head,
-    base,
-    verdict: entry.verdict,
-    detail: `merge train shadow · batch [${batchNumbers.join(',')}] · gatesRun ${result.gatesRun}`,
-    tests: [],
-    at,
-  }));
+  const verdicts: L8ShadowVerdict[] = result.verdicts.map((entry) => {
+    const item = plan.batch.find((candidate) => candidate.number === entry.number)!;
+    const manifest = shadowPrManifest(item, group, queueSig, result.gatesRun, entry.verdict);
+    return {
+      number: entry.number,
+      head: item.head,
+      base,
+      verdict: entry.verdict,
+      detail: `merge train shadow · reach [${group.prs.join(',')}] · batch [${batchNumbers.join(',')}] · gatesRun ${result.gatesRun}`,
+      tests: [...group.reachTests],
+      at,
+      manifest,
+    };
+  });
   state.pending = state.pending.filter((item) => !batchNumbers.includes(item.number));
   state.verdicts.push(...verdicts);
   writeShadowQueue(path, state);
   return verdicts[0] ?? null;
 }
 
-/** Evaluate one pinned queue head against freshly fetched main — or, when the queue holds two or more measured,
- *  non-overlapping PRs, one shadow merge train. Never push or call a merge API. */
+/** Evaluate one pinned queue head against freshly fetched main — or, when reach grouping finds a measured
+ *  two-or-more-PR component, one shadow merge train. Never push or call a merge API. */
 export async function runL8ShadowQueue(cwd: string, deps: L8ShadowQueueDeps = {}): Promise<L8ShadowVerdict | null> {
   return withShadowQueue(cwd, deps, async (state, path) => {
     const item = state.pending[0];
     if (!item) return null;
     const execute = deps.command ?? command;
     const run = (bin: string, args: string[], where = cwd) => shadowCommand(execute, bin, args, where);
-    // LAND-QUEUE — two or more measured, non-overlapping queued PRs evaluate as one shadow merge train first.
-    const trainPlan = planTrain(
-      state.pending.map((pending) => ({ number: pending.number, head: pending.head, files: pending.files, filesUnmeasured: pending.filesUnmeasured })),
-      { maxBatch: deps.trainMaxBatch ?? 2 },
-    );
-    if (trainPlan.batch.length >= 2) return runShadowMergeTrain(state, path, cwd, run, execute, trainPlan, deps);
+    run('git', ['fetch', 'origin', 'refs/heads/main']);
+    const base = run('git', ['rev-parse', 'FETCH_HEAD']);
+    if (!/^[0-9a-f]{40}$/i.test(base)) throw new Error('main commit unavailable');
+    const queueSig = shadowQueueSig(base, state.pending);
+    let trees: string[] = [];
+    // Preservation contract: a reach failure on any non-head queued PR defers only that PR; the queue head keeps
+    // both its shadow-train chance and the single-PR evaluation path. Only the head's own failure throws.
+    const reachDeferred: L8ShadowDeferred[] = [];
+    const reachSkip = new Set<number>();
+    try {
+      for (const pending of state.pending) {
+        if (pending.filesUnmeasured || !pending.files?.length) continue;
+        const isHead = pending === item;
+        try {
+          const view = JSON.parse(run('gh', ['pr', 'view', String(pending.number), '--json', 'headRefOid,baseRefName,state,isDraft,isCrossRepository'])) as {
+            headRefOid?: string; baseRefName?: string; state?: string; isDraft?: boolean; isCrossRepository?: boolean;
+          };
+          if (view.headRefOid !== pending.head || view.baseRefName !== 'main' || view.state !== 'OPEN'
+            || view.isDraft !== false || view.isCrossRepository !== false) {
+            throw new Error(`queued PR #${pending.number} changed or is not ready`);
+          }
+          run('git', ['fetch', 'origin', `refs/pull/${pending.number}/head`]);
+          if (run('git', ['rev-parse', 'FETCH_HEAD']) !== pending.head) {
+            throw new Error(`fetched PR head changed: #${pending.number}`);
+          }
+        } catch (error) {
+          if (isHead) throw error;
+          reachDeferred.push({ number: pending.number, head: pending.head, reason: String(error), at: new Date().toISOString() });
+          reachSkip.add(pending.number);
+        }
+      }
+      const pinned = pinShadowReachCandidates(cwd, run, state.pending, base, reachSkip);
+      trees = pinned.trees;
+      for (const failure of pinned.failures) {
+        const reason = `reach worktree failed: #${failure.number}: ${failure.reason}`;
+        if (failure.number === item.number) throw new Error(reason);
+        reachDeferred.push({ number: failure.number, head: failure.head, reason, at: new Date().toISOString() });
+      }
+      if (reachDeferred.length) {
+        recordShadowDeferred(state, reachDeferred);
+        writeShadowQueue(path, state);
+      }
+      if (pinned.candidates.length >= 2) {
+        const decision = buildTrainReachDecision(
+          { version: 1, baseSha: base, queueSig, prs: pinned.candidates },
+          deps.trainReachInspect,
+        );
+        const group = decision.groups.find((entry) => entry.status === 'measured' && !entry.capacityBlocked && entry.prs.length >= 2
+          && entry.prs.includes(String(item.number)));
+        if (group) {
+          const trainPlan = planShadowReachTrain(state.pending, group, { maxBatch: deps.trainMaxBatch ?? 5 });
+          if (trainPlan.batch.length >= 2) {
+            return await runShadowMergeTrain(state, path, cwd, run, execute, trainPlan, group, queueSig, base, deps);
+          }
+        }
+      }
+    } finally {
+      for (const tree of trees) {
+        try { run('git', ['worktree', 'remove', '--force', tree]); } catch { /* still delete the directory */ }
+        rmSync(tree, { recursive: true, force: true });
+      }
+    }
     const verdict: L8ShadowVerdict = { number: item.number, head: item.head, verdict: 'fail', tests: [], at: new Date().toISOString() };
     const view = JSON.parse(run('gh', ['pr', 'view', String(item.number), '--json', 'headRefOid,baseRefName,state,isDraft,isCrossRepository'])) as {
       headRefOid?: string; baseRefName?: string; state?: string; isDraft?: boolean; isCrossRepository?: boolean;
     };
     if (view.headRefOid !== item.head || view.baseRefName !== 'main' || view.state !== 'OPEN'
       || view.isDraft !== false || view.isCrossRepository !== false) throw new Error('queued PR changed or is not ready');
-    run('git', ['fetch', 'origin', 'refs/heads/main']);
-    const base = run('git', ['rev-parse', 'FETCH_HEAD']);
-    if (!/^[0-9a-f]{40}$/i.test(base)) throw new Error('main commit unavailable');
     verdict.base = base;
     run('git', ['fetch', 'origin', `refs/pull/${item.number}/head`]);
     if (run('git', ['rev-parse', 'FETCH_HEAD']) !== item.head) throw new Error('fetched PR head changed');

package/src/self-implement/off-diff-evidence.ts

@@ -5,6 +5,7 @@ import { spawnSync } from 'node:child_process';
 import { debug } from '../debug/log.js';
 import { narrowerEvidenceCommand } from './evidence-command-budget.js';
 import { resolveRunIdentity } from '../harness/harness-space.js';
+import { authoredSignalCommandFromGoal } from './goal-doc/section.js';
 //
 // ⛔ **왜 필요한가** — 리뷰어의 증거 채널은 워크트리 diff 하나다(`seams.ts` 의 `reviewDiff`).
 // 그래서 자식이 **diff 로 드러나지 않는 이행**(명령을 돌려 확인한 결과·라이브 관측)을 했을 때
@@ -334,6 +335,26 @@ interface RequiredEvidenceCheckRun {
   readonly substitutedFor?: string;
 }
 
+function authoredSignalCommand(goal: string): string | undefined {
+  const command = authoredSignalCommandFromGoal(goal);
+  if (!command) return undefined;
+  // Goal-authored signals run as one explicit command. Reject shell composition and
+  // substitutions; keep the accepted executable set aligned with goal-author's contract.
+  if (/[\r\n;|&<>`$()]/u.test(command) || /\b(?:sudo|eval|exec)\b/u.test(command)) return undefined;
+  const match = command.match(/^([A-Za-z0-9_./~-]+)\s+(.+)$/u);
+  if (!match) return undefined;
+  const executable = match[1]!.split('/').at(-1);
+  if (!new Set(['eln','bun','git','gh','rg','test','npm','pnpm','yarn','node','python','python3','pytest','make','cargo','go','curl','jq','sqlite3','grep','sed','awk','cat','find','docker','kubectl']).has(executable!)) return undefined;
+  if (executable === 'test' && !/^(?:-f|-e)\s+[^\s]+$/u.test(match[2]!)) return undefined;
+  return command;
+}
+
+export function authoredSignalExecution(goal: string, checks: readonly RequiredEvidenceCheckRun[]): { command: string; exitCode: number | null; stdout: string; stderr: string } | undefined {
+  const command = authoredSignalCommand(goal);
+  const run = command ? checks.find((check) => check.command === command) : undefined;
+  return run ? { command: run.command, exitCode: run.exitCode, stdout: run.stdout, stderr: run.stderr } : undefined;
+}
+
 type EvidenceCommandRunner = (command: string, cwd: string) => Pick<ReturnType<typeof spawnSync>, 'status' | 'stdout' | 'stderr' | 'error'>;
 
 /**
@@ -436,6 +457,8 @@ export function runRequiredEvidenceChecks(goal: string, cwd: string, runId?: str
 } = {}): RequiredEvidenceCheckRun[] {
   const identity = resolveRunIdentity({ explicit: runId });
   const checks = requiredEvidenceFromGoal(goal).flatMap(({ tag, verifyCommand }) => verifyCommand ? [{ tag, command: verifyCommand }] : []);
+  const signalCommand = authoredSignalCommand(goal);
+  if (signalCommand && !checks.some(({ command }) => command === signalCommand)) checks.push({ tag: 'authored-signal', command: signalCommand });
   // Direct callers without a measured HEAD have no stable revision identity;
   // the run-owned wrapper supplies a temporary identity when appropriate.
   const timeoutCounts = options.headCommit ? options.timeoutCounts : undefined;