elanous 0.2.38 → 0.2.40

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 {
@@ -163,7 +310,7 @@ function relevance(goal: string, section: string, targetPaths?: readonly string[
 }
 
 /** 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 +351,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 +361,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,
+  };
+}

package/src/self-implement/orchestrator.ts

@@ -226,7 +226,7 @@ import { formatGateFailedId, type PremiseReviewCard, type PremiseReviewInput } f
 import { runWorkflowToCompletion } from '../workflow-runtime/executor.js';
 import { mapReworkVerdict, supervisionObservationFields } from './supervision-vocabulary.js';
 import { resolveRunOutcome } from './run-outcome.js';
-import { authorLimitationCountFromGoal, authoredSignalExecution, harvestEvidenceLines, harvestedEvidenceObservation, MAX_HARVESTED_EVIDENCE_CHARS, parseOffDiffEvidence, requiredEvidenceFromGoal, createRequiredEvidenceBudget, coverRequiredEvidence, settleUncoveredEvidence, formatUncoveredEvidenceFeedback, type OffDiffEvidenceParse } from './off-diff-evidence.js';
+import { authorLimitationCountFromGoal, authoredSignalExecution, harvestEvidenceLines, harvestedEvidenceObservation, MAX_HARVESTED_EVIDENCE_CHARS, parseOffDiffEvidence, judgeTddEvidence, requiredEvidenceFromGoal, createRequiredEvidenceBudget, coverRequiredEvidence, settleUncoveredEvidence, formatUncoveredEvidenceFeedback, type OffDiffEvidenceParse } from './off-diff-evidence.js';
 import { resolveEvidenceHeadCommit } from './evidence-command-budget.js';
 import { pressDecisionSignals, type DecisionSignalPressResult } from './decision-signal-press.js';
 import { inspectDecisionObservations, inspectDecisionSignalKinds, inspectDecisionSignalObservations } from '../../scripts/ask-marker-check.js';
@@ -2180,6 +2180,8 @@ export function appendGoalExecutionRecord(goalFile: string, record: GoalExecutio
 }
 
 export interface SelfImplementOptions {
+  /** Parent managed-task cancellation, linked to the active implementation child. */
+  signal?: AbortSignal;
   /** ⭐ 걸음을 «호출부»로 흘리는 이음매 — 노드에 들어갈 때마다 한 번.
    *  🩸 2026-09-08: 이 콜백은 «내부에» 있었고 ***호출부가 0*** 이라 걸음이 런 밖으로 안 나갔다.
    *    ⇒ 런 슈퍼바이저는 「시도의 요약 판정」만 보고 「어떻게 걸었나」를 «못 봤다».
@@ -5465,13 +5467,20 @@ async function runSelfImplementInner(
   }
 
   // The repository copy travels with both local and Pod worktrees. Operational HQ ledgers are never read here.
-  const knowhow = selectKnowhowPack(wt.path, opts.feature);
-  if (knowhow.text) round0Feature = `${knowhow.text}\n\n${round0Feature}`;
+  const knowhow = selectKnowhowPack(
+    wt.path,
+    opts.feature,
+    undefined,
+    { goalFile: opts.goalFile ?? null },
+  );
+  // Keep the original ask first: the child preflight and PR title read its first line.
+  const injectKnowhow = getUserConfig().harness?.knowhowChildInjection === true;
+  if (injectKnowhow && knowhow.text) round0Feature = `${round0Feature}\n\n${knowhow.text}`;
   const knowhowRevisionRead = runGitCommand(wt.path, ['rev-parse', '--verify', 'HEAD'], { encoding: 'utf8', timeout: 10_000 });
   const knowhowRevision = knowhowRevisionRead.status === 0 && /^[0-9a-f]{40,64}$/i.test(knowhowRevisionRead.stdout.trim())
     ? knowhowRevisionRead.stdout.trim() : null;
-  observe('knowhow-pack', { ids: knowhow.ids, bytes: knowhow.bytes, injected: knowhow.bytes > 0,
-    reason: knowhow.reason, repoPath: wt.path, repoRevision: knowhowRevision });
+  observe('knowhow-pack', { goal: opts.feature.slice(0, 4096), ids: knowhow.ids, bytes: knowhow.bytes, sources: knowhow.sources ?? [], injected: injectKnowhow && knowhow.bytes > 0,
+    reason: knowhow.reason, knowhowReason: knowhow.knowhowReason ?? knowhow.reason, repoPath: wt.path, repoRevision: knowhowRevision });
 
   // E1 착수 구체화(RFC-progressive-goal-elaboration §2 E1 · §7 간선 ①) — 고정 층(KPI·판정 신호)은 그대로, 카드만 덧붙인다.
   const elaboration = await (await import('./goal-elaborate.js')).runArrivalElaboration({ goal: opts.feature, prompt: round0Feature, cwd: wt.path, callLLM: s.elaborateCallLLM, observe });
@@ -7270,6 +7279,9 @@ async function runSelfImplementInner(
       throw error;
     }
     const implementAbortController = new AbortController();
+    const abortImplementation = (): void => implementAbortController.abort(opts.signal?.reason);
+    if (opts.signal?.aborted) abortImplementation();
+    else opts.signal?.addEventListener('abort', abortImplementation, { once: true });
     let implementPromise: ReturnType<SelfImplementSeams['implement']>;
     // Rework needs landed sibling PRs only after the initial round; shard eligibility avoids an expensive impossible lookup.
     const landedSiblings = round > 0
@@ -7336,7 +7348,10 @@ async function runSelfImplementInner(
       }
       finalizeSupervisorDeliveries(error instanceof StepTimeoutError ? 'next-round-implement-timeout' : 'next-round-implement-rejected');
       throw error;
+    } finally {
+      opts.signal?.removeEventListener('abort', abortImplementation);
     }
+    if (opts.signal?.aborted) throw opts.signal.reason ?? new Error('SelfImplement aborted');
     // ⭐ 성공 경로에서도 닫는다 — 이 호출은 끝났고, 이후 자식이 늦게 보내는 입력은
     //   「이 라운드의 재투입」이 아니다(다음 라운드는 자기 콜백을 새로 만든다).
     closeSupervisorInput();
@@ -7452,6 +7467,69 @@ async function runSelfImplementInner(
         impl = { ...impl, ok: true, completionDisposition: undefined };
       }
     }
+    // ⭐ TDD 를 로직으로(S4) — 문면(device-first 조각 계획)이 아니라 실행 판정으로 끼운다.
+    //   ① 자식의 [tdd-red]/[tdd-green] 기록을 태그·같은 명령·결과로 판정한다.
+    //   ② 첫 조각 커밋의 피처 시험·구현 전 실행 RED 기록과 구현 뒤 같은 명령 GREEN 기록이
+    //     없으면 수리 라운드 1회(완료 경계·기존 동작은 보존), 그래도 없으면 fail-closed.
+    //   ③ 관측 원장에 tdd-red/tdd-green 이벤트를 남긴다.
+    let tddJudgment = judgeTddEvidence(roundGoal, parseOffDiffEvidence(impl.evidenceTranscript?.trim() || impl.summary));
+    if (tddJudgment.needsRepair && impl.ok && round < effectiveMax && opts.goalFile
+      && !hasCurrentProviderError() && !hasCurrentCredentialFailure()) {
+      let goalDocument: string | undefined;
+      try { goalDocument = readFileSync(opts.goalFile, 'utf8'); } catch { goalDocument = undefined; }
+      if (goalDocument !== undefined) {
+        const tddRetryNote = [
+          '[구현 재작업 · tdd-evidence-missing]',
+          `대상 경로: ${declaredPathsFromGoalDocumentText(goalDocument).paths.join(' · ') || '골 문서에 선언된 대상 경로 없음'}`,
+          '첫 조각 커밋에 피처 시험을 먼저 쓰고 구현 전 실행 RED 기록을 남기고, 구현 뒤 같은 명령의 GREEN 기록을 남겨라.',
+          "기록 양식(두 줄씩): 'EVIDENCE: [tdd-red] <무엇을 확인했나> || <증거 명령>' 다음 줄 'RESULT: <실패 요약 한 줄>' ·",
+          "'EVIDENCE: [tdd-green] <무엇을 확인했나> || <같은 증거 명령>' 다음 줄 'RESULT: <통과 요약 한 줄>'.",
+          `지금 잡힌 결손: ${tddJudgment.missing.join(' · ')}`,
+          '원래 골 문서(완료 경계 포함):',
+          goalDocument,
+        ].join('\n');
+        const tddRetryRound = round + 1;
+        observe('implementation-tdd-rework', { status: 'started', round: tddRetryRound, missing: [...tddJudgment.missing] }, { level: 'warn' });
+        progress('implementing', `[구현 재작업 · tdd-evidence-missing] 수리 라운드 ${tddRetryRound} 시작 — RED/GREEN 기록 결손`);
+        onNodeEntry(node('rework'), tddRetryRound);
+        onNodeEntry(node('implement'), tddRetryRound);
+        const tddRetryAbort = new AbortController();
+        const beforeTddRetry = impl;
+        let tddRetryImpl = impl;
+        try {
+          tddRetryImpl = await stepTimeout(s.implement({
+            sessionId, cwd: wt.path, feature: `${feature}\n\n${tddRetryNote}`, runId, shardIdentity, signal: tddRetryAbort.signal,
+            ...(harnessSeededPaths.length ? { harnessSeededPaths } : {}),
+            onSurfaceProgress: (line) => progress('implementing', line.trimEnd()),
+            roundContext: { round: tddRetryRound, effectiveMax, previousRoundFailure: tddRetryNote },
+            ...(opts.childLlm ? { childLlm: opts.childLlm } : {}),
+            ...(opts.documentReferences ? { documentReferences: opts.documentReferences } : {}),
+          }), T.implement, 'implement');
+        } catch (error) {
+          tddRetryAbort.abort();
+          tddRetryImpl = { ...beforeTddRetry, ok: false, summary: `[구현 재작업 · tdd-evidence-missing] 수리 라운드 실패 — ${safeErrorDescription(error)}` };
+        }
+        const tddRetryJudgment = judgeTddEvidence(roundGoal, parseOffDiffEvidence(tddRetryImpl.evidenceTranscript?.trim() || tddRetryImpl.summary));
+        if (tddRetryImpl.ok && !tddRetryJudgment.needsRepair) {
+          observe('implementation-tdd-rework', { status: 'succeeded', round: tddRetryRound, missing: [] });
+          tddJudgment = tddRetryJudgment;
+          impl = tddRetryImpl;
+          round = tddRetryRound;
+        } else {
+          observe('implementation-tdd-rework', { status: 'exhausted', round: tddRetryRound, missing: [...tddRetryJudgment.missing] }, { level: 'warn' });
+          impl = { ...beforeTddRetry, ok: false, summary: `[구현 재작업 · tdd-evidence-missing] RED/GREEN 기록 결손 — ${beforeTddRetry.summary}` };
+        }
+      }
+    }
+    observe('tdd-red', {
+      round, planned: tddJudgment.planned, observed: tddJudgment.red.observed, missing: tddJudgment.red.observed ? [] : ['tdd-red'],
+      verify: tddJudgment.red.verify ?? null, result: tddJudgment.red.result ?? null,
+    }, tddJudgment.planned && !tddJudgment.red.observed ? { level: 'warn' } : {});
+    observe('tdd-green', {
+      round, planned: tddJudgment.planned, observed: tddJudgment.green.observed, sameCommand: tddJudgment.sameCommand,
+      missing: tddJudgment.green.observed && tddJudgment.sameCommand ? [] : ['tdd-green'],
+      verify: tddJudgment.green.verify ?? null, result: tddJudgment.green.result ?? null,
+    }, tddJudgment.planned && !(tddJudgment.green.observed && tddJudgment.sameCommand) ? { level: 'warn' } : {});
     // A finished child can leave edits without a commit. Measure them before any
     // diff/no-changes classification, and commit only paths declared in the goal.
     finishedChildCommitMissing = false;
@@ -9046,9 +9124,9 @@ async function runSelfImplementInner(
       const mergedBase = m.baseRefName?.trim() || observedPrBase;
       if (mergedBase && displayBranchName(mergedBase) === 'main') {
         try {
-          const { syncMergedPrChecklist } = await import('../release-loop/merged-pr-checklist.js');
+          const { syncMergedPrChecklistWithFeedback } = await import('../release-loop/merged-pr-checklist.js');
           const goalFile = opts.goalFile ?? (opts.goalId ? s.goalDocumentPathByGoalId?.(opts.goalId) : undefined);
-          syncMergedPrChecklist(pr.number, wt.path, goalFile);
+          await syncMergedPrChecklistWithFeedback(pr.number, wt.path, goalFile);
         } catch (error) {
           observe('merged-pr-checklist-sync-failed', { number: pr.number, error: safeErrorDescription(error) }, { level: 'warn' });
         }

package/src/self-implement/run-ledger.ts

@@ -719,7 +719,9 @@ export interface RunLedgerCheckedAppendOutcome<T> {
  * Thrown (typed, with the stable `runId-mismatch` reason) when a checked-append
  * decision returns an entry whose `runId` differs from the locked `runId`. Callers
  * classify identity violations from `error.reason === 'runId-mismatch'` instead of
- * parsing message substrings.
+ * parsing message substrings. `RunLedgerEntryRunIdMismatchError` below is the same
+ * identity violation observed on already-written ledger bytes, so one `instanceof`
+ * covers both producers.
  */
 export class RunLedgerCheckedAppendRunIdMismatchError extends Error {
   readonly reason = 'runId-mismatch' as const;
@@ -731,6 +733,21 @@ export class RunLedgerCheckedAppendRunIdMismatchError extends Error {
   }
 }
 
+/**
+ * Thrown (typed, same `runId-mismatch` reason) when a stored ledger *row* declares a
+ * `runId` other than the one being loaded. The message prefixes the stable reason and keeps
+ * the parser's existing wording, so message-based classifiers (`goal-archive`, the
+ * doctor-compare caller's own regression test) keep recognizing it, while
+ * `decisionRunId`/`lockedRunId` travel as typed fields so no caller has to re-parse it.
+ */
+export class RunLedgerEntryRunIdMismatchError extends RunLedgerCheckedAppendRunIdMismatchError {
+  constructor(decisionRunId: string, lockedRunId: string, readonly lineNumber: number) {
+    super(decisionRunId, lockedRunId);
+    this.name = 'RunLedgerEntryRunIdMismatchError';
+    this.message = `runId-mismatch: invalid run ledger entry at line ${lineNumber}: runId does not match ${lockedRunId}`;
+  }
+}
+
 /**
  * Atomically decide-and-append under a single per-run lock: the caller-supplied
  * decision runs on the loaded ledger inside `withRunLedgerLock`, and at most one
@@ -896,7 +913,7 @@ function parseRunLedgerEntry(line: string, lineNumber: number, expectedRunId: st
     throw new Error(`invalid run ledger entry at line ${lineNumber}: expected optional timestamp, goalId, shard identity, runId, event, and object data`);
   }
   if (entry.runId !== expectedRunId) {
-    throw new Error(`invalid run ledger entry at line ${lineNumber}: runId does not match ${expectedRunId}`);
+    throw new RunLedgerEntryRunIdMismatchError(entry.runId, expectedRunId, lineNumber);
   }
   return entry as RunLedgerEntry;
 }
@@ -1154,15 +1171,24 @@ export interface GraphAdaptReport {
   nonAdapted: { landed: number; denominator: number; rate: number | null };
   excludedCount: number;
   exclusionReasons: Record<string, number>;
+  unmeasuredCount: number;
+  unmeasuredReasons: Record<string, number>;
+  window: { since: string | null; until: string | null };
 }
 
 /** Measure only producer-observed traversals and variant applications; never activate adaptation. */
-export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoot()): GraphAdaptReport {
+export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoot(), window: { since?: string; until?: string } = {}): GraphAdaptReport {
   const dir = runLedgerDir(stateDir);
   const signatures = new Set<string>();
   const counts = { adapted: { landed: 0, denominator: 0 }, nonAdapted: { landed: 0, denominator: 0 } };
   const exclusionReasons: Record<string, number> = {};
+  const unmeasuredReasons: Record<string, number> = {};
   const exclude = (reason: string): void => { exclusionReasons[reason] = (exclusionReasons[reason] ?? 0) + 1; };
+  const unmeasured = (reason: string): void => { unmeasuredReasons[reason] = (unmeasuredReasons[reason] ?? 0) + 1; };
+  const since = window.since === undefined ? null : Date.parse(window.since);
+  const until = window.until === undefined ? null : Date.parse(window.until);
+  if ((since !== null && !Number.isFinite(since)) || (until !== null && !Number.isFinite(until)) ||
+    (since !== null && until !== null && since > until)) throw new Error('invalid adaptation measurement window');
   let unitCallCount = 0;
   let adaptationCount = 0;
   let fileNames: string[];
@@ -1181,6 +1207,15 @@ export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoo
     const goalIds = new Set(ledger.map(entry => entry.goalId).filter((id): id is string => typeof id === 'string' && id.length > 0));
     if (goalIds.size === 1 && !goalIds.has(goalId)) continue;
     if (goalIds.size !== 1) { exclude('goal-id-missing-or-conflicting'); continue; }
+    const start = ledger.find(entry => entry.event === 'start');
+    const startedAt = start && typeof start.timestamp === 'string' ? Date.parse(start.timestamp) : NaN;
+    if (!Number.isFinite(startedAt)) { unmeasured('start-time-missing-or-invalid'); continue; }
+    if ((since !== null && startedAt < since) || (until !== null && startedAt >= until)) { exclude('outside-start-window'); continue; }
+    const lastStatus = [...ledger].reverse().find(entry => entry.event === 'run-status');
+    if (lastStatus && !['completed', 'failed', 'cancelled'].includes(String(lastStatus.data.runStatus))) {
+      exclude('in-flight'); continue;
+    }
+    if (!lastStatus && !ledger.some(entry => entry.event === 'merged')) { exclude('in-flight'); continue; }
     const traversals = ledger.filter(entry => entry.event === 'pipeline-traversal-shadow');
     const paths = traversals.map(entry => entry.data.observedNodes);
     if (paths.length === 0 || paths.some(path => !Array.isArray(path) || path.length === 0 || !path.every(node => typeof node === 'string' && node.length > 0))) {
@@ -1189,12 +1224,13 @@ export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoo
     let graphRun: unknown;
     try { graphRun = JSON.parse(readFileSync(join(stateDir, 'graph-runs', 'self-implement', `${runId}.json`), 'utf8')); }
     catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') { exclude('graph-run-unreadable'); continue; }
+      unmeasured((error as NodeJS.ErrnoException).code === 'ENOENT' ? 'graph-run-missing' : 'graph-run-unreadable');
+      continue;
     }
     const recorded = graphRun && typeof graphRun === 'object' && !Array.isArray(graphRun) ? graphRun as Record<string, unknown> : null;
-    if (recorded && (recorded.runId !== runId || recorded.graphId !== 'self-implement' ||
-      (recorded.unitCalls !== undefined && !Array.isArray(recorded.unitCalls)))) {
-      exclude('unit-calls-invalid'); continue;
+    if (!recorded || recorded.runId !== runId || recorded.graphId !== 'self-implement' ||
+      (recorded.unitCalls !== undefined && !Array.isArray(recorded.unitCalls))) {
+      unmeasured('graph-run-invalid'); continue;
     }
     const merge = [...ledger].reverse().find(entry => entry.event === 'merged');
     if (merge && typeof merge.data.merged !== 'boolean') { exclude('landing-invalid'); continue; }
@@ -1210,7 +1246,9 @@ export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoo
   return { goalId, runCount: counts.adapted.denominator + counts.nonAdapted.denominator,
     uniquePathSignatures: signatures.size, unitCallCount, adaptationCount,
     adapted: rate(counts.adapted), nonAdapted: rate(counts.nonAdapted),
-    excludedCount: Object.values(exclusionReasons).reduce((total, count) => total + count, 0), exclusionReasons };
+    excludedCount: Object.values(exclusionReasons).reduce((total, count) => total + count, 0), exclusionReasons,
+    unmeasuredCount: Object.values(unmeasuredReasons).reduce((total, count) => total + count, 0), unmeasuredReasons,
+    window: { since: window.since ?? null, until: window.until ?? null } };
 }
 
 export interface GoalSourceDistributionQuery {