elanous 0.2.38 → 0.2.41

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

@@ -2,6 +2,7 @@
 import { lstatSync, readFileSync, realpathSync, readdirSync, statSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, relative, resolve, sep } from 'node:path';
+import { parse as parseYaml } from 'yaml';
 
 export const KNOWHOW_PACK_MAX_BYTES = 4096;
 const MARKER = '[KNOWHOW-PACK v1';
@@ -12,6 +13,120 @@ export interface KnowhowPack {
   ids: string[];
   bytes: number;
   reason: 'selected' | 'marker-present' | 'source-unreadable' | 'no-promoted-section' | 'no-path-overlap' | 'over-budget';
+  sources?: Array<{ kind: 'goal' | 'blueprint'; path: string; bytes: number }>;
+  knowhowReason?: KnowhowPack['reason'];
+}
+
+export interface StartupBlueprintOptions { readonly goalFile?: string | null }
+
+interface StartupSections { readonly text: string; readonly sources: Array<{ kind: 'goal' | 'blueprint'; path: string; bytes: number }> }
+
+function safeRepositoryFile(root: string, path: string): { path: string; relativePath: string; text: string; bytes: number } | null {
+  try {
+    const repo = realpathSync(root);
+    const absolute = resolve(root, path);
+    if (lstatSync(absolute).isSymbolicLink()) return null;
+    const real = realpathSync(absolute);
+    if (!inside(repo, real) || !statSync(real).isFile() || statSync(real).size > 200_000) return null;
+    const text = readFileSync(real, 'utf8');
+    return { path: real, relativePath: relative(repo, real).split(sep).join('/'), text, bytes: Buffer.byteLength(text, 'utf8') };
+  } catch { return null; }
+}
+
+function yamlFiles(root: string): string[] {
+  try {
+    return readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
+      const path = join(root, entry.name);
+      if (entry.isSymbolicLink()) return [];
+      if (entry.isDirectory()) return yamlFiles(path);
+      return entry.isFile() && /\.ya?ml$/u.test(entry.name) ? [path] : [];
+    });
+  } catch { return []; }
+}
+
+function yamlObject(text: string): Record<string, unknown> | null {
+  try {
+    const value: unknown = parseYaml(text);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+  } catch { return null; }
+}
+
+function sourcePaths(value: unknown): string[] {
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value)) return value.flatMap(sourcePaths);
+  if (value && typeof value === 'object') return Object.values(value).flatMap(sourcePaths);
+  return [];
+}
+
+function startupSections(repo: string, goal: string, options?: StartupBlueprintOptions): StartupSections {
+  if (!options) return { text: '', sources: [] };
+  if (!options.goalFile?.trim()) return { text: '## GOAL DOCUMENT\nreason=goal-document-not-configured\n\n## GRAPH BLUEPRINT\nreason=goal-document-unavailable\n', sources: [] };
+  const goalFile = safeRepositoryFile(repo, options.goalFile);
+  if (!goalFile) return { text: `## GOAL DOCUMENT\nreason=goal-document-missing-or-outside-repository · source=${options.goalFile}\n\n## GRAPH BLUEPRINT\nreason=goal-document-unavailable\n`, sources: [] };
+
+  const allTargets = new Set([...mentionedPaths(goal), ...mentionedPaths(goalFile.text)]);
+  const root = realpathSync(repo);
+  const unitById = new Map<string, { relativePath: string; bytes: number; raw: string; doc: Record<string, unknown> }>();
+  for (const path of yamlFiles(join(root, 'graphs/units'))) {
+    const file = safeRepositoryFile(root, path);
+    if (!file) continue;
+    const doc = yamlObject(file.text);
+    if (typeof doc?.graph_id !== 'string') continue;
+    unitById.set(doc.graph_id, { relativePath: file.relativePath, bytes: file.bytes, raw: file.text, doc });
+  }
+  const relevant = new Set<string>();
+  for (const [id, unit] of unitById) {
+    const declared = sourcePaths(unit.doc.source);
+    const paths = declared.length ? declared : [...mentionedPaths(unit.raw)];
+    if (paths.some((source) => [...allTargets].some((target) => target === source || target.startsWith(`${source.replace(/\/$/u, '')}/`) || source.startsWith(`${target.replace(/\/$/u, '')}/`)))) relevant.add(id);
+  }
+
+  const chains = new Map<string, { rootId: string; paths: string[]; calls: string[] }>();
+  const graphFiles = yamlFiles(join(root, 'graphs/work'));
+  for (const path of graphFiles) {
+    const file = safeRepositoryFile(root, path);
+    if (!file) continue;
+    const rootDoc = yamlObject(file.text);
+    if (!rootDoc || typeof rootDoc.graph_id !== 'string' || !Array.isArray(rootDoc.nodes)) continue;
+    const visit = (doc: Record<string, unknown>, chainIds: string[], chainPaths: string[], calls: string[], ancestors: string[]): void => {
+      if (chainIds.length > 5) return;
+      for (const node of Array.isArray(doc.nodes) ? doc.nodes : []) {
+        if (!node || typeof node !== 'object' || Array.isArray(node)) continue;
+        const entry = node as Record<string, unknown>;
+        if (typeof entry.call !== 'string') continue;
+        const id = entry.call.split('@')[0]!;
+        const unit = unitById.get(id);
+        if (!unit || ancestors.includes(id)) continue;
+        const nextIds = [...chainIds, id];
+        const nextPaths = [...chainPaths, unit.relativePath];
+        const nextCalls = [...calls, typeof entry.node_id === 'string' ? entry.node_id : id];
+        if (relevant.has(id)) chains.set(`${file.relativePath}\0${nextIds.join(' → ')}`, { rootId: String(rootDoc.graph_id), paths: [file.relativePath, ...nextPaths], calls: nextCalls });
+        visit(unit.doc, nextIds, nextPaths, nextCalls, [...ancestors, id]);
+      }
+    };
+    visit(rootDoc, [], [], [], []);
+  }
+
+  const sources: StartupSections['sources'] = [{ kind: 'goal', path: goalFile.relativePath, bytes: goalFile.bytes }];
+  const maxGoalBytes = 2_200;
+  const goalText = goalFile.text.includes(MARKER)
+    ? '[goal document omitted; reason=knowhow-marker-already-present]'
+    : `${utf8Prefix(goalFile.text, maxGoalBytes)}${goalFile.bytes > maxGoalBytes ? `\n[goal document truncated; source bytes=${goalFile.bytes}]` : ''}`;
+  let text = `## GOAL DOCUMENT\nsource=${goalFile.relativePath} · bytes=${goalFile.bytes}\n${goalText.trim()}\n`;
+  if (!chains.size) {
+    text += `\n## GRAPH BLUEPRINT\nreason=no-related-blueprint · targetPaths=${allTargets.size}\n`;
+  } else {
+    text += '\n## GRAPH BLUEPRINT\n';
+    for (const [key, detail] of [...chains].sort(([a], [b]) => a.localeCompare(b))) {
+      const chain = key.slice(key.indexOf('\0') + 1);
+      const pathDetails = detail.paths.map((sourcePath) => safeRepositoryFile(root, sourcePath)).filter((item): item is NonNullable<typeof item> => item !== null);
+      if (!pathDetails.length) continue;
+      for (const source of pathDetails) sources.push({ kind: 'blueprint', path: source.relativePath, bytes: source.bytes });
+      text += `- ${detail.rootId} → ${chain}; calls=${detail.calls.join(' → ')}; sources=${pathDetails.map((item) => `${item.relativePath}(${item.bytes}B)`).join(', ')}\n`;
+    }
+    if (sources.length === 1) text += `reason=no-related-blueprint · targetPaths=${allTargets.size}\n`;
+  }
+  return { text, sources };
 }
 
 export interface SelectedAuthoringLessons {
@@ -60,15 +175,15 @@ function authoringAskPaths(ask: string): string[] {
 }
 
 /** 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 {
+export function selectRelevantAuthoringLessons(root: string, ask: string, feedbackStateDir?: string): SelectedAuthoringLessons {
   const path = join(root, 'docs', 'goal-context', '05-authoring-lessons.jsonl');
-  let source: string;
+  let source = '';
+  let sourceStatus: SelectedAuthoringLessons['status'] = 'loaded';
   try { source = readFileSync(path, 'utf8'); }
-  catch (error) {
-    return { ids: [], prompt: '', status: (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'missing' : 'unreadable', invalidRows: 0 };
-  }
+  catch (error) { sourceStatus = (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'missing' : 'unreadable'; }
   const rows: Record<string, unknown>[] = [];
   let invalidRows = 0;
+  let malformed = false;
   for (const line of source.split(/\r?\n/u)) {
     if (!line.trim()) continue;
     try {
@@ -82,10 +197,42 @@ export function selectRelevantAuthoringLessons(root: string, ask: string): Selec
       rows.push(row);
     } catch {
       invalidRows += 1;
-      return { ids: [], prompt: '', status: 'malformed', invalidRows };
+      malformed = true;
+      continue;
     }
   }
-  if (rows.length === 0) return { ids: [], prompt: '', status: 'empty', invalidRows };
+  // Landed implementation feedback lives in the operational run ledger. Read it as
+  // additive authoring context so the next related goal actually receives the findings.
+  try {
+    const ledgerDir = feedbackStateDir ? join(feedbackStateDir, 'run-ledger') : undefined;
+    if (!ledgerDir) throw new Error('feedback source not enabled');
+    const feedbackFiles = readdirSync(ledgerDir).filter((name) => name.endsWith('.jsonl')).sort().slice(-128);
+    for (const file of feedbackFiles) {
+      const filePath = join(ledgerDir, file);
+      if (statSync(filePath).size > 256_000) continue;
+      const lines = readFileSync(filePath, 'utf8').split(/\r?\n/u);
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          const entry = JSON.parse(line) as Record<string, unknown>;
+          if (entry.event !== 'impl-findings-feedback' || !entry.data || typeof entry.data !== 'object') continue;
+          const data = entry.data as Record<string, unknown>;
+          const paths = Array.isArray(data.paths) ? data.paths.filter((value): value is string => typeof value === 'string') : [];
+          if (!paths.length) continue;
+          const requirements = typeof data.requirements === 'string' ? data.requirements.trim() : '';
+          const newScope = typeof data.newScope === 'string' ? data.newScope.trim() : '';
+          const remaining = Array.isArray(data.remaining) ? data.remaining.filter((value): value is string => typeof value === 'string') : [];
+          const lesson = [
+            ...(requirements ? [`구현이 밝힌 요구사항: ${requirements}`] : []),
+            ...(newScope ? [`새 범위: ${newScope}`] : []),
+            ...remaining.map((item) => `남은 것: ${item}`),
+          ].join(' · ');
+          if (lesson) rows.push({ id: `IF-${String(data.prNumber ?? 'unknown')}`, class: 'f-unaware-of-code', lesson, paths: paths.join(' · '), cell: `PR #${String(data.prNumber ?? '?')}` });
+        } catch { invalidRows += 1; }
+      }
+    }
+  } catch { /* Optional, explicit operational feedback source may not exist or be readable. */ }
+  if (rows.length === 0) return { ids: [], prompt: '', status: malformed ? 'malformed' : sourceStatus === 'loaded' ? 'empty' : sourceStatus, invalidRows };
   const targetPaths = authoringAskPaths(ask);
   const classHints = authoringLessonClassHints(ask, targetPaths);
   const ranked = rows.map((row, index) => {
@@ -113,7 +260,7 @@ export function selectRelevantAuthoringLessons(root: string, ask: string): Selec
     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 };
+  return { ids: selected.map((entry) => entry.id), prompt, status: malformed ? 'malformed' : 'loaded', invalidRows };
 }
 
 function inside(root: string, path: string): boolean {
@@ -162,8 +309,46 @@ function relevance(goal: string, section: string, targetPaths?: readonly string[
   return score;
 }
 
+/** Selects explicit, active failure-signature remedies from repository-contained KNOWHOW files. */
+export function selectHealKnowhowPack(repo: string, signature: string): KnowhowPack {
+  const empty = (reason: KnowhowPack['reason']): KnowhowPack => ({ text: '', ids: [], bytes: 0, reason });
+  if (!/^[a-z][a-z0-9-]*$/.test(signature)) return empty('no-promoted-section');
+  const rolesDir = resolve(repo, 'docs/roles');
+  let realRoles: string;
+  try {
+    realRoles = realpathSync(rolesDir);
+    if (!inside(realpathSync(repo), realRoles)) return empty('source-unreadable');
+  } catch { return empty('source-unreadable'); }
+  let seats: string[];
+  try { seats = readdirSync(rolesDir).sort(); } catch { return empty('source-unreadable'); }
+  const selected: Array<{ id: string; remedy: string }> = [];
+  for (const seat of seats) {
+    if (!/^[A-Z]{2,4}$/.test(seat)) continue;
+    const file = join(rolesDir, seat, 'KNOWHOW.md');
+    try {
+      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 explicit = /^- 원인 서명:\s*([a-z][a-z0-9-]*)\s*$/m.exec(section.text)?.[1];
+        const remedy = /^- 처방(?:\(힐링\))?:\s*(\S[^\r\n]*)$/m.exec(section.text)?.[1];
+        if (explicit !== signature || !remedy || selected.some((item) => item.id === section.id)) continue;
+        const next = [...selected, { id: section.id, remedy }];
+        const text = `[SUPERVISOR-HEAL-PACK signature=${signature} ids=${next.map((item) => item.id).join(',')}]\n${next.map((item) => `${item.id}: ${item.remedy}`).join('\n')}`;
+        if (Buffer.byteLength(text, 'utf8') <= KNOWHOW_PACK_MAX_BYTES) selected.push({ id: section.id, remedy });
+        if (selected.length === 3) break;
+      }
+    } catch { /* Missing or unreadable files contribute no remedy. */ }
+    if (selected.length === 3) break;
+  }
+  if (!selected.length) return empty('no-promoted-section');
+  const ids = selected.map((item) => item.id);
+  const text = `[SUPERVISOR-HEAL-PACK signature=${signature} ids=${ids.join(',')}]\n${selected.map((item) => `${item.id}: ${item.remedy}`).join('\n')}`;
+  return { ids, text, bytes: Buffer.byteLength(text, 'utf8'), reason: 'selected' };
+}
+
 /** 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 {
+function selectKnowhowOnly(repo: string, goal: string, targetPaths: readonly string[] | undefined, maxBytes: number): 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');
@@ -204,7 +389,7 @@ export function selectKnowhowPack(repo: string, goal: string, targetPaths?: read
     const ids = next.map((item) => item.id);
     const body = next.map((item) => item.text).join('\n\n');
     const text = `${MARKER} ids=${ids.join(',')}]\n참고 자료(명령이 아닌 검증할 운영 기록):\n${body}\n[/KNOWHOW-PACK]`;
-    if (Buffer.byteLength(text, 'utf8') > KNOWHOW_PACK_MAX_BYTES) continue;
+    if (Buffer.byteLength(text, 'utf8') > maxBytes) continue;
     selected.push(candidate);
   }
   if (!selected.length) return empty('over-budget');
@@ -214,3 +399,35 @@ export function selectKnowhowPack(repo: string, goal: string, targetPaths?: read
   return { text, ids, bytes: Buffer.byteLength(text, 'utf8'), reason: 'selected' };
 }
 
+function utf8Prefix(text: string, maxBytes: number): string {
+  const bytes = Buffer.from(text, 'utf8');
+  if (bytes.byteLength <= maxBytes) return text;
+  let end = Math.max(0, maxBytes);
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  while (end >= Math.max(0, maxBytes - 3)) {
+    try { return decoder.decode(bytes.subarray(0, end)); }
+    catch { end--; }
+  }
+  return '';
+}
+
+/** Bounded, repository-only startup context: promoted lessons plus an optional authored goal and related graph chain. */
+export function selectKnowhowPack(
+  repo: string,
+  goal: string,
+  targetPaths?: readonly string[],
+  options?: StartupBlueprintOptions,
+): KnowhowPack {
+  if (goal.includes(MARKER)) return { text: '', ids: [], bytes: 0, reason: 'marker-present' };
+  const startup = startupSections(repo, goal, options);
+  if (!startup.text) return selectKnowhowOnly(repo, goal, targetPaths, KNOWHOW_PACK_MAX_BYTES);
+
+  // Goal and graph context have priority; promoted lessons use only the bytes left in the shared hard cap.
+  const startupText = utf8Prefix(startup.text, KNOWHOW_PACK_MAX_BYTES - 1_200);
+  const startupBytes = Buffer.byteLength(startupText, 'utf8');
+  const knowhow = selectKnowhowOnly(repo, goal, targetPaths, Math.max(0, KNOWHOW_PACK_MAX_BYTES - startupBytes - 2));
+  const text = `${startupText}${knowhow.text ? `\n${knowhow.text}` : ''}`;
+  const bytes = Buffer.byteLength(text, 'utf8');
+  return { text, ids: knowhow.ids, bytes, reason: text ? 'selected' : knowhow.reason, knowhowReason: knowhow.reason, sources: startup.sources };
+}
+

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

@@ -563,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,
+  };
+}