elanous 0.2.37 → 0.2.40

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;
@@ -540,3 +563,127 @@ export function coverRequiredEvidence(
     uncoveredCount: uncovered.length,
   };
 }
+
+// ── TDD 를 로직으로 (S4 · 대표 10-26 20:5x «쪼개기·TDD 가 로직에 박혀 있나») ──────
+//
+// ⛔ **왜 필요한가** — 조각 골(device-first)은 «검증 계획(TDD)» 문면만 조립하고, 사후 판정은
+// 증거 명령이 덮였는지만 본다(required-evidence-uncovered). ⇒ 자식이 **시험을 먼저 쓰고 구현 전에
+// RED 를 확인했는지**를 검사하는 경로가 전혀 없다. TDD 가 문면 요청으로만 존재한다.
+// ⇒ 오케스트레이터가 **첫 조각 커밋에 피처 시험·구현 전 실행 RED 기록**을 요구하고
+//   **구현 뒤 같은 명령의 GREEN 기록**을 요구한다. 판정은 기존 태그 동등 문법과 같다:
+//   자식은 `EVIDENCE: [tdd-red] … || <명령>` ⊕ `RESULT: <실패>` ·
+//   `EVIDENCE: [tdd-green] … || <같은 명령>` ⊕ `RESULT: <통과>` 를 남긴다.
+
+/** 자식이 남겨야 하는 TDD 증거 태그. ⛔ 판정은 **태그 동등**이다(해석 금지). */
+export const TDD_RED_TAG = 'tdd-red';
+export const TDD_GREEN_TAG = 'tdd-green';
+export type TddRecordTag = typeof TDD_RED_TAG | typeof TDD_GREEN_TAG;
+
+/** 골 문서의 «검증 계획(TDD)» 절 형식(완료 경계 증거 명령이 골 문서가 아니라 조각 계획에 박혀 있다). */
+const TDD_PLAN_HEADING = /^#{2,3}\s*검증\s*계획\s*\(TDD\)\s*$/iu;
+const TDD_RED_PLAN_PREFIX = /^[-*]\s*③\s*먼저\s*쓸\s*시험\(RED\)\s*:\s*/u;
+const TDD_GREEN_PLAN_PREFIX = /^[-*]\s*④\s*GREEN\s*뒤\s*같은\s*명령\s*:\s*/u;
+/** device-first 조각 계획의 한 줄 형식 — «피처 시험 bun test <경로>» 를 같은 명령으로 잡는다. 경로 토큰 경계([\\w./-]) 로 조사·역따옴표를 삼키지 않는다. */
+const TDD_PLAN_INLINE = /(?:--test-)?bun(?:x)?\s+test\s+(?:src|test)\/[\w./-]+/iu;
+/** `RESULT:` 한 줄이 통과 기록인가 — 기존 bun test 판정 문법(`0 fail`)과 같은 신호. */
+const TDD_PASS_RESULT = /(?:^|\s)0\s+fail/iu;
+
+export interface TddPlan {
+  readonly planned: boolean;
+  /** ③ 먼저 쓸 시험(RED) 문면(앞뒤 공백만 정리). */
+  readonly redStage: string | undefined;
+  /** ④ GREEN 뒤 같은 명령(예: `bun test <대상>.test.ts`). */
+  readonly greenCommand: string | undefined;
+}
+
+/** 골 문서에서 «검증 계획(TDD)» 절을 읽는다. **순수** — 절이 없으면 `planned: false`(추측 금지). */
+export function tddPlanFromGoal(goal: string): TddPlan {
+  const lines = goal.split(/\r?\n/);
+  const headingIndex = lines.findIndex((line) => TDD_PLAN_HEADING.test(line.trim()));
+  if (headingIndex >= 0) {
+    const section: string[] = [];
+    for (const line of lines.slice(headingIndex + 1)) {
+      const text = line.trim();
+      // ⛔ 다음 절 제목(`#`·`###` 도 절이다)에서 멈춘다 — requiredEvidenceFromGoal 과 같은 규율.
+      if (/^#{1,6}\s/.test(text)) break;
+      section.push(text);
+    }
+    const redStage = section.find((line) => TDD_RED_PLAN_PREFIX.test(line))
+      ?.replace(TDD_RED_PLAN_PREFIX, '').trim() || undefined;
+    const greenBody = section.find((line) => TDD_GREEN_PLAN_PREFIX.test(line))
+      ?.replace(TDD_GREEN_PLAN_PREFIX, '').trim();
+    const greenCommand = greenBody ? TDD_PLAN_INLINE.exec(greenBody)?.[0]?.trim() : undefined;
+    return { planned: true, redStage, greenCommand: greenCommand || undefined };
+  }
+  // device-first 조각 계획의 한 줄 형식 — «검증 계획(TDD): … 피처 시험 bun test <경로> …».
+  const inlineLine = lines.find((line) => /검증\s*계획\s*\(TDD\)\s*:\s*\S/u.test(line) && TDD_PLAN_INLINE.test(line));
+  const greenCommand = inlineLine ? TDD_PLAN_INLINE.exec(inlineLine)?.[0]?.trim() : undefined;
+  if (!greenCommand) return { planned: false, redStage: undefined, greenCommand: undefined };
+  return { planned: true, redStage: undefined, greenCommand };
+}
+
+export interface TddEvidenceRecord {
+  readonly tag: TddRecordTag;
+  /** 자식이 남긴 `EVIDENCE: [tag] …` 한 건(태그를 떼지 않는다). */
+  readonly claim: string;
+  /** 재현 명령. 없으면 기록이 아니다(기존 파서 규율과 같다). */
+  readonly verify: string | undefined;
+  /** 바로 다음 `RESULT:` 줄 — RED 는 실패 기록, GREEN 은 통과 기록이어야 한다. */
+  readonly result: string | undefined;
+  readonly observed: boolean;
+}
+
+export interface TddEvidenceJudgment {
+  readonly planned: boolean;
+  readonly red: TddEvidenceRecord;
+  readonly green: TddEvidenceRecord;
+  /** RED·GREEN 이 **같은 증거 명령**인가 — «GREEN 뒤 같은 명령» 계약의 판정. */
+  readonly sameCommand: boolean;
+  /** 결손 태그(관측·수리 지시의 원천). */
+  readonly missing: readonly TddRecordTag[];
+  /** 계획이 있는데 결손이 있다 — 오케스트레이터가 수리 라운드를 돌린다. */
+  readonly needsRepair: boolean;
+}
+
+/** 자식 기록 한 건의 태그를 뗀다 — coverRequiredEvidence 와 같은 문법. */
+function tddClaimTag(claim: string): string | undefined {
+  return claim.match(/^\s*\[([^\]]+)\]/)?.[1]?.trim() || undefined;
+}
+
+/** 태그 하나에 대한 자식 기록을 판정한다. RED 는 실패 기록(`0 fail` 없음), GREEN 은 통과 기록이다. */
+function tddRecordFromItems(items: readonly OffDiffEvidenceParse['items'][number][], tag: TddRecordTag): TddEvidenceRecord {
+  const item = items.find((candidate) => tddClaimTag(candidate.claim) === tag);
+  if (!item) return { tag, claim: '', verify: undefined, result: undefined, observed: false };
+  const verify = item.verify.trim() || undefined;
+  const result = item.result?.trim() || undefined;
+  const resultPasses = result !== undefined && TDD_PASS_RESULT.test(result);
+  const observed = tag === TDD_RED_TAG
+    ? verify !== undefined && result !== undefined && !resultPasses
+    : verify !== undefined && result !== undefined && resultPasses;
+  return { tag, claim: item.claim, verify, result, observed };
+}
+
+/**
+ * ★ TDD 를 로직으로 판정한다. **순수**.
+ *
+ * 판정은 셋이다: ① 골이 «검증 계획(TDD)» 을 계획했는가 ② 자식이 [tdd-red] RED 기록(구현 전 실패)을
+ * 남겼는가 ③ [tdd-green] GREEN 기록(구현 뒤 **같은 명령** 통과)을 남겼는가. 셋째는 문면이 아니라
+ * **명령 동등**으로 판정한다 — RED 의 명령과 GREEN 의 명령이 문자열로 같아야 한다.
+ */
+export function judgeTddEvidence(goal: string, evidence: OffDiffEvidenceParse): TddEvidenceJudgment {
+  const plan = tddPlanFromGoal(goal);
+  const red = tddRecordFromItems(evidence.items, TDD_RED_TAG);
+  const green = tddRecordFromItems(evidence.items, TDD_GREEN_TAG);
+  const sameCommand = red.verify !== undefined && red.verify === green.verify;
+  const missing: TddRecordTag[] = [];
+  if (!red.observed) missing.push(TDD_RED_TAG);
+  if (!green.observed || (red.verify !== undefined && green.verify !== undefined && !sameCommand)) missing.push(TDD_GREEN_TAG);
+  return {
+    planned: plan.planned,
+    red,
+    green,
+    sameCommand,
+    missing,
+    needsRepair: plan.planned && missing.length > 0,
+  };
+}