elanous 0.2.18 → 0.2.20

package/src/self-implement/sibling-resync.ts

@@ -0,0 +1,223 @@
+/**
+ * SIBLING-RESYNC-ON-MERGE (0.2.21 P0) — when one harness PR merges, the open sibling PRs that touch the
+ * same paths learn it «now», not when their gate fails or main-sync breaks.
+ *
+ * Measured 2026-10-07: 76% of launches overlap an open PR or a running run on the same paths.
+ *
+ * Delivery reuses existing channels only:
+ *   · live owning run  → one supervisor memo in its control inbox (`elanous self send --memo` path)
+ *   · no live run      → the registered `elanous:needs-rebase` label (QUIET-PR-COMMENTS: never a comment)
+ *
+ * Cost bound (#24893 review should-fix ①, measured 186 open PRs → 186 `…/files` calls per merge):
+ *   · prefilter   — a PR already carrying the marker is skipped before any file fetch
+ *   · priority    — PRs whose branch shares path tokens with the merged files are fetched first
+ *   · fetch cap   — at most `maxFetch` file inventories per merge (config `harness.siblingResync.maxFetch`, default 40)
+ *   · concurrency — at most `fetchConcurrency` (default 6) fetches in flight
+ *
+ * Pure core: every side effect is an injected adapter so tests never touch GitHub or the inbox.
+ */
+import { debug } from '../debug/log.js';
+import type { ControlMemoPayload } from '../harness/control-inbox.js';
+
+export const SIBLING_RESYNC_CATEGORY = 'self-implement.sibling-resync';
+export const SIBLING_RESYNC_DEFAULT_CAP = 10;
+export const SIBLING_RESYNC_DEFAULT_MAX_FETCH = 40;
+export const SIBLING_RESYNC_DEFAULT_FETCH_CONCURRENCY = 6;
+export const SIBLING_RESYNC_MARKER_LABEL = 'elanous:needs-rebase';
+const HARNESS_BRANCH_PREFIX = 'self-impl/';
+
+/** An open PR before its file inventory is fetched. */
+export interface SiblingResyncCandidate {
+  readonly number: number;
+  readonly branch: string;
+  readonly labels: readonly string[];
+}
+
+export interface SiblingResyncPr extends SiblingResyncCandidate {
+  /** `undefined` means the file list could not be proven complete — such a PR never qualifies. */
+  readonly files: readonly string[] | undefined;
+}
+
+export type SiblingRunTarget =
+  | { readonly alive: true; readonly runId: string; readonly spaceId: string }
+  | { readonly alive: false; readonly runId?: string; readonly reason: string };
+
+export interface SiblingResyncAdapters {
+  /** Open PRs (draft or ready) against the default branch, without files. A rejection is not an empty list. */
+  listOpenPrs(): Promise<readonly SiblingResyncCandidate[]>;
+  /** One PR's files; `undefined` (or a rejection) means unknown and that PR never qualifies. */
+  prFiles(number: number): Promise<readonly string[] | undefined>;
+  /** The merged PR's files; `undefined` means unknown and nothing is sent. */
+  mergedFiles(): Promise<readonly string[] | undefined>;
+  resolveRun(pr: SiblingResyncPr): Promise<SiblingRunTarget>;
+  sendResync(target: { runId: string; spaceId: string }, memo: ControlMemoPayload): Promise<void> | void;
+  addMarker(prNumber: number, label: string): Promise<void> | void;
+}
+
+export interface SiblingResyncResult {
+  readonly requested: readonly number[];
+  readonly marked: readonly number[];
+  readonly failed: readonly number[];
+  readonly skippedOverCap: readonly number[];
+  /** Already marked before any fetch — not fetched. */
+  readonly skippedPrefilter: readonly number[];
+  /** Over the per-merge fetch cap — not fetched. */
+  readonly skippedFetchCap: readonly number[];
+  readonly filesFetched: number;
+  readonly durationMs: number;
+  readonly reason?: string;
+}
+
+export function siblingResyncMemo(merged: number, overlap: readonly string[]): ControlMemoPayload {
+  const shown = overlap.slice(0, 5).join(', ');
+  const more = overlap.length > 5 ? ` (+${overlap.length - 5} more)` : '';
+  return {
+    version: 1,
+    kind: 'sibling-resync',
+    urgency: 'normal',
+    body: `[sibling-resync] Sibling PR #${merged} just merged into main touching the same paths: ${shown}${more}. `
+      + 'Before continuing: git fetch origin main, rebase this branch onto origin/main (resolve conflicts keeping both intents), then re-run the gate on your changed files.',
+  };
+}
+
+/** Exact path intersection; a PR without a provable file list is never a sibling. */
+export function overlappingFiles(merged: readonly string[], sibling: readonly string[] | undefined): string[] {
+  if (!sibling || sibling.length === 0) return [];
+  const mergedSet = new Set(merged);
+  return [...new Set(sibling.filter((file) => mergedSet.has(file)))].sort();
+}
+
+const GENERIC_TOKENS = new Set(['src', 'test', 'tests', 'index', 'scripts', 'docs', 'goals', 'goal', 'self', 'impl', 'apps', 'main', 'json', 'html', 'spec', 'types', 'lib']);
+
+/** Lower-case path tokens (dir segments and file stems split on `-_.`), generic and short ones removed. */
+export function pathTokens(text: string): Set<string> {
+  return new Set(text.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length >= 3 && !GENERIC_TOKENS.has(token) && !/^\d+$/.test(token)));
+}
+
+/** Shared path tokens between the merged files and a branch name — a cheap ordering hint, never a filter. */
+export function branchAffinity(mergedTokens: ReadonlySet<string>, branch: string): number {
+  let score = 0;
+  for (const token of pathTokens(branch)) if (mergedTokens.has(token)) score += 1;
+  return score;
+}
+
+async function mapBounded<T, R>(items: readonly T[], limit: number, work: (item: T) => Promise<R>): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await work(items[index]!);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+const nonNegativeInt = (value: number | undefined, fallback: number): number =>
+  value !== undefined && Number.isSafeInteger(value) && value >= 0 ? value : fallback;
+
+export async function requestSiblingResync(input: {
+  merged: { number: number };
+  adapters: SiblingResyncAdapters;
+  cap?: number;
+  maxFetch?: number;
+  fetchConcurrency?: number;
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+  now?: () => number;
+}): Promise<SiblingResyncResult> {
+  const { merged, adapters } = input;
+  const now = input.now ?? Date.now;
+  const startedAt = now();
+  const cap = nonNegativeInt(input.cap, SIBLING_RESYNC_DEFAULT_CAP);
+  const maxFetch = nonNegativeInt(input.maxFetch, SIBLING_RESYNC_DEFAULT_MAX_FETCH);
+  const concurrency = Math.max(1, nonNegativeInt(input.fetchConcurrency, SIBLING_RESYNC_DEFAULT_FETCH_CONCURRENCY));
+  const log = input.log ?? ((category, event, data) => debug.log(category, event, data));
+  const emit = (event: string, data: Record<string, unknown>) => {
+    try { log(SIBLING_RESYNC_CATEGORY, event, { merged: merged.number, ...data }); } catch { /* fail-soft */ }
+  };
+  const requested: number[] = [];
+  const marked: number[] = [];
+  const failed: number[] = [];
+  const skippedOverCap: number[] = [];
+  const skippedPrefilter: number[] = [];
+  const skippedFetchCap: number[] = [];
+  let filesFetched = 0;
+  const result = (reason?: string): SiblingResyncResult => ({
+    requested, marked, failed, skippedOverCap, skippedPrefilter, skippedFetchCap, filesFetched,
+    durationMs: Math.max(0, now() - startedAt), ...(reason ? { reason } : {}),
+  });
+  let mergedFiles: readonly string[] | undefined;
+  let open: readonly SiblingResyncCandidate[];
+  try {
+    mergedFiles = await adapters.mergedFiles();
+    if (!mergedFiles || mergedFiles.length === 0) {
+      const out = result('merged-files-unknown');
+      emit('skipped', { reason: out.reason, durationMs: out.durationMs });
+      return out;
+    }
+    open = await adapters.listOpenPrs();
+  } catch (error) {
+    const out = result('inventory-failed');
+    emit('skipped', { reason: out.reason, error: String(error), durationMs: out.durationMs });
+    return out;
+  }
+  const mergedTokens = new Set<string>();
+  for (const file of mergedFiles) for (const token of pathTokens(file)) mergedTokens.add(token);
+  const candidates: { pr: SiblingResyncCandidate; affinity: number }[] = [];
+  for (const pr of open) {
+    if (pr.number === merged.number || !pr.branch.startsWith(HARNESS_BRANCH_PREFIX)) continue;
+    // Already marked: the quiet signal is in place, and a re-fetch would only re-confirm it.
+    if (pr.labels.includes(SIBLING_RESYNC_MARKER_LABEL)) { skippedPrefilter.push(pr.number); continue; }
+    candidates.push({ pr, affinity: branchAffinity(mergedTokens, pr.branch) });
+  }
+  // Most likely siblings first; ties go to the newest PR (most likely to have a live run).
+  candidates.sort((a, b) => b.affinity - a.affinity || b.pr.number - a.pr.number);
+  const toFetch = candidates.slice(0, maxFetch);
+  skippedFetchCap.push(...candidates.slice(maxFetch).map(({ pr }) => pr.number));
+  const fetched = await mapBounded(toFetch, concurrency, async ({ pr }): Promise<SiblingResyncPr> => {
+    let files: readonly string[] | undefined;
+    try { files = await adapters.prFiles(pr.number); } catch { files = undefined; }
+    filesFetched += 1;
+    return { ...pr, files };
+  });
+  const siblings = fetched
+    .map((pr) => ({ pr, overlap: overlappingFiles(mergedFiles!, pr.files) }))
+    .filter(({ overlap }) => overlap.length > 0)
+    .sort((a, b) => a.pr.number - b.pr.number);
+  for (const [index, { pr, overlap }] of siblings.entries()) {
+    if (index >= cap) { skippedOverCap.push(pr.number); continue; }
+    let target: SiblingRunTarget;
+    try {
+      target = await adapters.resolveRun(pr);
+    } catch (error) {
+      target = { alive: false, reason: `run-resolution-failed: ${String(error)}` };
+    }
+    if (target.alive) {
+      try {
+        await adapters.sendResync({ runId: target.runId, spaceId: target.spaceId }, siblingResyncMemo(merged.number, overlap));
+        requested.push(pr.number);
+        emit('requested', { sibling: pr.number, runId: target.runId, spaceId: target.spaceId, overlap });
+        continue;
+      } catch (error) {
+        // A live run we could not reach still needs to be visible — fall through to the quiet marker.
+        emit('send-failed', { sibling: pr.number, runId: target.runId, error: String(error) });
+      }
+    }
+    try {
+      await adapters.addMarker(pr.number, SIBLING_RESYNC_MARKER_LABEL);
+      marked.push(pr.number);
+      emit('marked', { sibling: pr.number, label: SIBLING_RESYNC_MARKER_LABEL, reason: target.alive ? 'send-failed' : target.reason, ...(target.runId ? { runId: target.runId } : {}), overlap });
+    } catch (error) {
+      failed.push(pr.number);
+      emit('mark-failed', { sibling: pr.number, error: String(error) });
+    }
+  }
+  const out = result();
+  emit('summary', {
+    siblings: siblings.length, requested, marked, failed, skippedOverCap, cap,
+    filesFetched, skippedPrefilter: skippedPrefilter.length, skippedFetchCap: skippedFetchCap.length, maxFetch, concurrency,
+    durationMs: out.durationMs,
+  });
+  return out;
+}

package/src/self-implement/stop-autoheal.ts

@@ -0,0 +1,204 @@
+/**
+ * STOP-AUTOHEAL (0.2.20 P0 · 첫 조각) — 멈춘 런의 stop 레코드(STOP-RECORD #24907)를 읽고
+ * 갈래마다 «한 번»만 스스로 고쳐 본다. 안 되면 `needs-owner` 로 사람에게 넘긴다.
+ *
+ * S: 런이 멈추면 원장에 `event='stop'` 한 줄(class·cause·evidenceRef·nextMove)이 남는다.
+ * C: 그 줄을 읽는 쪽이 없어서 환경 결손·main 동기화·Pod 사망·증거 누락처럼 «기계가 고칠 수 있는» 멈춤도 사람을 기다렸다.
+ * Q: 갈래별로 한 수를 정해 두고 «한 번만» 시도할 수 있나?
+ * A: `autohealFromStop` 하나가 class → action 을 고르고, 원장 `event='autoheal'` 줄로 시도를 남긴다.
+ *    같은 런·같은 갈래·같은 모드에 이미 줄이 있으면 다시 하지 않는다(원장 가드).
+ *
+ * 사다리(class → action):
+ *   env-unrelated      → clean-workspace-regate   깨끗한 자리에서 gate 만 다시 1회(GATE-ENV-RETRY 재사용 자리)
+ *   main-sync          → rebase-regate            리베이스(MERGE-INTENT-RESOLVE 의도 해석) 뒤 재게이트
+ *   pod-died           → resume-from-salvage      `salvage/run-<6hex>/<leaf>` 가지에서 resume(DRAFT-NOT-ARCHIVE)
+ *   evidence-uncovered → derive-evidence-rejudge  런 출력·시험·배선에서 증거를 끌어내 1회 재판정
+ *   review-repeat · review-out-of-scope · fabric · launch-failed · unclassified → needs-owner(새 라운드 없음)
+ *
+ * 모드 `tools.selfImplement.autoheal.mode` = `shadow`(기본: 할 일을 원장에만 적고 손대지 않는다) | `live`.
+ * ⛔ live 에서도 행동은 주입 seam 으로만 한다 — seam 이 없는 행동은 `needs-owner`(action-unwired)로 떨어진다.
+ *    «안 이어진 손»을 「고쳤다」로 읽지 않게.
+ * 관측 = `debug.log('self-implement.autoheal', …)` ⊕ 원장 `event='autoheal'`.
+ */
+import { debug } from '../debug/log.js';
+import { appendRunLedgerEntry, loadRunLedger, type RunLedgerEntry, type RunLedgerWriter } from './run-ledger.js';
+import type { RunStopClass, RunStopRecord } from './run-stop.js';
+
+export const AUTOHEAL_EVENT = 'autoheal';
+export type AutohealMode = 'shadow' | 'live';
+export const DEFAULT_AUTOHEAL_MODE: AutohealMode = 'shadow';
+
+export type AutohealAction =
+  | 'clean-workspace-regate'
+  | 'rebase-regate'
+  | 'resume-from-salvage'
+  | 'derive-evidence-rejudge'
+  | 'needs-owner';
+
+/** 닫힌 목록 전체를 덮는다 — 새 class 가 생기면 여기서 타입 오류가 난다. */
+export const AUTOHEAL_ACTION_BY_CLASS: Readonly<Record<RunStopClass, AutohealAction>> = {
+  'env-unrelated': 'clean-workspace-regate',
+  'main-sync': 'rebase-regate',
+  'pod-died': 'resume-from-salvage',
+  'evidence-uncovered': 'derive-evidence-rejudge',
+  'review-repeat': 'needs-owner',
+  'review-out-of-scope': 'needs-owner',
+  fabric: 'needs-owner',
+  'launch-failed': 'needs-owner',
+  unclassified: 'needs-owner',
+};
+
+/** 설정 원값 → 모드. 모르는 값은 «좁은 쪽»(shadow). */
+export function parseAutohealMode(raw: unknown): AutohealMode {
+  return raw === 'live' ? 'live' : 'shadow';
+}
+
+export interface AutohealContext {
+  runId: string;
+  goalId?: string;
+  record: RunStopRecord;
+}
+
+export interface AutohealActionResult {
+  ok: boolean;
+  /** 한 줄 — 무엇을 했나/왜 못 했나. */
+  detail?: string;
+}
+
+export type AutohealActionFn = (ctx: AutohealContext) => Promise<AutohealActionResult> | AutohealActionResult;
+
+/** 행동 seam — needs-owner 를 뺀 넷. 없는 seam 은 live 에서도 실행하지 않는다. */
+export type AutohealActions = Partial<Record<Exclude<AutohealAction, 'needs-owner'>, AutohealActionFn>>;
+
+export type AutohealOutcome =
+  /** shadow — 할 일을 적기만 했다. */
+  | 'would-act'
+  /** live — 행동을 했고 성공했다. */
+  | 'healed'
+  /** 사람에게 넘긴다(갈래가 needs-owner 이거나 행동이 실패·미배선). */
+  | 'needs-owner'
+  /** 같은 런·갈래·모드에 이미 시도가 있다 — 아무것도 안 했다(원장에 새 줄도 안 쓴다). */
+  | 'already-attempted';
+
+export interface AutohealResult {
+  runId: string;
+  class: RunStopClass;
+  action: AutohealAction;
+  mode: AutohealMode;
+  outcome: AutohealOutcome;
+  /** needs-owner 일 때 사람이 볼 이유(멈춘 원인 그대로 또는 행동 실패). */
+  reason?: string;
+  detail?: string;
+  entry?: RunLedgerEntry;
+}
+
+export interface AutohealDeps {
+  mode?: AutohealMode;
+  actions?: AutohealActions;
+  /** 가드용 원장 읽기 — 기본 `loadRunLedger(runId)`. null = 원장 없음(첫 시도). */
+  loadLedger?: (runId: string) => readonly RunLedgerEntry[] | null;
+  writeLedger?: RunLedgerWriter;
+}
+
+/**
+ * 이 프로세스가 쓴 autoheal 줄 — 원장 읽기가 주입 writer 와 다른 곳을 보거나(시험 seam) 비어 있어도
+ * 같은 프로세스 안에서는 «한 번»이 지켜지게 한다(리뷰 must-fix #24912).
+ */
+const writtenThisProcess = new Map<string, RunLedgerEntry[]>();
+const WRITTEN_MAX_RUNS = 4096;
+
+/** 시험용 — 프로세스 기억을 비운다. */
+export function resetAutohealProcessMemory(): void {
+  writtenThisProcess.clear();
+}
+
+/** 원장 가드 — 같은 런·같은 갈래·같은 모드의 autoheal 줄이 있으면 참. */
+export function autohealAlreadyAttempted(ledger: readonly RunLedgerEntry[] | null, cls: RunStopClass, mode: AutohealMode): boolean {
+  if (!ledger) return false;
+  return ledger.some((e) => e.event === AUTOHEAL_EVENT && e.data?.class === cls && e.data?.mode === mode);
+}
+
+function observe(event: string, data: Record<string, unknown>): void {
+  try { debug.log('self-implement.autoheal', event, data); } catch { /* observation is fail-soft */ }
+}
+
+/**
+ * stop 레코드 하나 → 최대 한 번의 힐 시도. 예외를 던지지 않는다(행동 seam 의 throw 도 needs-owner 로 접는다).
+ */
+export async function autohealFromStop(ctx: AutohealContext, deps: AutohealDeps = {}): Promise<AutohealResult> {
+  const mode = deps.mode ?? DEFAULT_AUTOHEAL_MODE;
+  const cls = ctx.record.class;
+  const action = AUTOHEAL_ACTION_BY_CLASS[cls] ?? 'needs-owner';
+  const base = { runId: ctx.runId, class: cls, action, mode };
+
+  let ledger: readonly RunLedgerEntry[] | null = null;
+  try {
+    ledger = (deps.loadLedger ?? ((id) => loadRunLedger(id)))(ctx.runId);
+  } catch (error) {
+    // ⛔ 가드를 못 읽으면 «한 번»을 보장할 수 없다 — live 행동을 하지 않고 사람에게 넘긴다.
+    const reason = `ledger-unreadable: ${error instanceof Error ? error.message : String(error)}`;
+    observe('guard-unreadable', { ...base, reason });
+    return { ...base, outcome: 'needs-owner', reason };
+  }
+  if (autohealAlreadyAttempted(ledger, cls, mode) || autohealAlreadyAttempted(writtenThisProcess.get(ctx.runId) ?? null, cls, mode)) {
+    observe('already-attempted', base);
+    return { ...base, outcome: 'already-attempted' };
+  }
+
+  let outcome: AutohealOutcome;
+  let reason: string | undefined;
+  let detail: string | undefined;
+  if (action === 'needs-owner') {
+    outcome = 'needs-owner';
+    reason = `stop ${cls}: ${ctx.record.cause}`;
+  } else if (mode === 'shadow') {
+    outcome = 'would-act';
+  } else {
+    const fn = deps.actions?.[action];
+    if (!fn) {
+      outcome = 'needs-owner';
+      reason = `action-unwired: ${action} (stop ${cls}: ${ctx.record.cause})`;
+    } else {
+      // ⭐ 시도 «전»에 원장 줄을 쓴다 — 행동 중 프로세스가 죽어도 두 번째 시도가 막힌다.
+      //    ⛔ 그 줄을 못 쓰면 «한 번»을 보장할 수 없으니 행동하지 않는다.
+      if (!writeEntry(ctx, deps, { ...base, phase: 'attempt' })) {
+        const unguarded = `guard-write-failed: ${action} not attempted (stop ${cls}: ${ctx.record.cause})`;
+        observe('needs-owner', { ...base, reason: unguarded });
+        return { ...base, outcome: 'needs-owner', reason: unguarded };
+      }
+      try {
+        const res = await fn(ctx);
+        detail = res.detail;
+        outcome = res.ok ? 'healed' : 'needs-owner';
+        if (!res.ok) reason = `${action} failed${res.detail ? `: ${res.detail}` : ''}`;
+      } catch (error) {
+        outcome = 'needs-owner';
+        reason = `${action} threw: ${error instanceof Error ? error.message : String(error)}`;
+      }
+    }
+  }
+
+  const entry = writeEntry(ctx, deps, {
+    ...base, phase: 'result', outcome,
+    ...(reason ? { reason } : {}), ...(detail ? { detail } : {}),
+    evidenceRef: ctx.record.evidenceRef, nextMove: ctx.record.nextMove,
+  });
+  observe(outcome, { ...base, ...(reason ? { reason } : {}), ...(detail ? { detail } : {}) });
+  return { ...base, outcome, ...(reason ? { reason } : {}), ...(detail ? { detail } : {}), ...(entry ? { entry } : {}) };
+}
+
+function writeEntry(ctx: AutohealContext, deps: AutohealDeps, data: Record<string, unknown>): RunLedgerEntry | undefined {
+  const entry: RunLedgerEntry = {
+    timestamp: new Date().toISOString(), runId: ctx.runId, event: AUTOHEAL_EVENT, data,
+    ...(ctx.goalId ? { goalId: ctx.goalId } : {}),
+  };
+  try {
+    (deps.writeLedger ?? appendRunLedgerEntry)(entry);
+    if (!writtenThisProcess.has(ctx.runId) && writtenThisProcess.size >= WRITTEN_MAX_RUNS) writtenThisProcess.clear();
+    writtenThisProcess.set(ctx.runId, [...(writtenThisProcess.get(ctx.runId) ?? []), entry]);
+    return entry;
+  } catch (error) {
+    observe('ledger-write-failed', { runId: ctx.runId, error: error instanceof Error ? error.message : String(error) });
+    return undefined;
+  }
+}

package/src/task-agent/actions.ts

@@ -1,4 +1,29 @@
-export type NextActionKind = 'review' | 'land' | 'retry' | 'green' | 'decision';
+import { copyFileSync, lstatSync, mkdirSync, realpathSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { debug } from '../debug/log.js';
+import { judgeNextMove } from './judge.js';
+import { checkCompletionEvidence } from './completion-evidence.js';
+
+export type DeliveryKind = 'research-report' | 'artifact' | 'content';
+export interface DeliveryEvidence { ok: boolean; files: string[]; reason: string }
+
+/**
+ * DEFAULT-HANDS-a: 판독은 복사된 최종 산출물에서만 하고, 규칙은 `completion-evidence.ts` 의
+ * `checkCompletionEvidence` 하나를 쓴다(종류별 규칙을 여기서 다시 짓지 않는다).
+ * 후보 중 하나라도 그 종류의 증거를 다 갖추면 ok — 후보 목록엔 곁 파일(미리보기 등)도 섞인다.
+ */
+export function readDeliveryEvidence(kind: DeliveryKind, outputDir: string, files: readonly string[]): DeliveryEvidence {
+  if (!files.length) return { ok: false, files: [], reason: '전달 후보 없음' };
+  const missing = new Set<string>();
+  for (const file of files) {
+    const verdict = checkCompletionEvidence(kind, { dir: outputDir, ref: relative(outputDir, file) });
+    if (verdict.ok) return { ok: true, files: [...files], reason: `전달 산출물 확인: ${verdict.ref}` };
+    for (const item of verdict.missing) missing.add(item);
+  }
+  return { ok: false, files: [...files], reason: `전달 증거 부족: ${[...missing].join(', ')}` };
+}
+
+export type NextActionKind = 'review' | 'land' | 'retry' | 'green' | 'decision' | 'deliver';
 /**
  * `retry` 의 갈래(RFC §A9 G1·G2). 없으면 종전 그대로 «must-fix 로 좁힌 재발사»다(must-fix 가 없으면 카드).
  * - narrow: 범위를 좁혀 한 번 재발사(must-fix 없이도 간다 — no-progress)
@@ -22,6 +47,7 @@ export interface NextAction {
   mustFix?: string[];
   cwd?: string;
   risk?: 'money' | 'security' | 'irreversible-publication';
+  delivery?: { kind: DeliveryKind; worktreePath: string; projectTarget: string; files: string[] };
 }
 export interface ActionDeps {
   command(args: string[]): Promise<{ status: number; stdout: string; stderr?: string }>;
@@ -63,7 +89,11 @@ export async function executeNextAction(action: NextAction, deps: ActionDeps): P
     deps.observe('task-agent.action', { taskId: action.taskId, kind: action.kind, result, reason });
     return result;
   };
-  if (deps.mode !== 'live') return record('shadow', `would ${action.kind}${action.variant ? `:${action.variant}` : ''}: ${action.rationale}`);
+  if (deps.mode !== 'live') {
+    const destination = action.delivery && action.kind === 'deliver'
+      ? ` → ${join(action.delivery.projectTarget, 'elanous-out', action.taskId)}/${action.delivery.files.join(', ')}` : '';
+    return record('shadow', `would ${action.kind}${action.variant ? `:${action.variant}` : ''}: ${action.rationale}${destination}`);
+  }
   const card = async (reason: string) => {
     const evidence = JSON.stringify({ runId: action.runId, pr: action.pr, mustFix: action.mustFix ?? [], history: action.history ?? [], selected: action.kind, reason });
     const result = await deps.command(['decisions', 'raise', '--title', `${action.taskId}: ${reason}`, '--category', action.risk === 'money' ? 'money' : action.risk === 'security' ? 'security' : action.risk === 'irreversible-publication' ? 'publish' : 'other', '--s', `Task ${action.taskId} needs a decision.`, '--c', reason, '--ref', evidence, '--q', 'Which action should be taken?', '--option', 'h=Keep on hold:no automatic execution', '--option', 'p=Approve action:execute after approval', '--skip-recommend', 'requires human decision', '--no-xcheck', 'automated escalation']);
@@ -87,6 +117,37 @@ export async function executeNextAction(action: NextAction, deps: ActionDeps): P
     if (deps.reserveLanding ? !deps.reserveLanding(day, limit) : (deps.landingsToday ?? 0) >= limit) return card('daily landing limit');
   }
   if (action.kind === 'decision') return card(action.rationale);
+  if (action.kind === 'deliver') {
+    const delivery = action.delivery;
+    if (!delivery?.files.length) return record('waiting', '전달 후보 없음');
+    if (!/^[a-zA-Z0-9_-]+$/.test(action.taskId)) return record('failed', 'invalid delivery taskId');
+    const output = join(delivery.projectTarget, 'elanous-out', action.taskId);
+    const copied: string[] = [];
+    try {
+      mkdirSync(output, { recursive: true });
+      // 경로 비교는 «실경로끼리» 한다 — macOS 의 /var→/private/var 처럼 조상 링크가 있으면 resolve() 와 realpath 가 늘 갈린다.
+      const outputReal = realpathSync(output);
+      if (outputReal !== join(realpathSync(delivery.projectTarget), 'elanous-out', action.taskId)) throw new Error('delivery output points outside target');
+      const root = realpathSync(delivery.worktreePath) + sep;
+      for (const name of delivery.files) {
+        const source = resolve(root, name);
+        if (!source.startsWith(root) || !lstatSync(source).isFile() || !realpathSync(source).startsWith(root)) throw new Error(`invalid delivery file: ${name}`);
+        const destination = resolve(output, name);
+        if (!destination.startsWith(resolve(output) + sep)) throw new Error(`invalid destination: ${name}`);
+        mkdirSync(join(destination, '..'), { recursive: true });
+        const parent = realpathSync(join(destination, '..'));
+        if (parent !== outputReal && !parent.startsWith(outputReal + sep)) throw new Error(`invalid destination parent: ${name}`);
+        try { if (!lstatSync(destination).isFile()) throw new Error(`invalid destination: ${name}`); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+        copyFileSync(source, destination);
+        copied.push(destination);
+      }
+    } catch (error) { return record('failed', `delivery copy failed: ${String(error)}`); }
+    const evidence = readDeliveryEvidence(delivery.kind, resolve(output), copied);
+    debug.log('task-agent', 'deliver', { taskId: action.taskId, kind: delivery.kind, files: copied, evidenceOk: evidence.ok });
+    const judgement = judgeNextMove({ deliveryEvidence: evidence });
+    return record(judgement.move === 'propose-green' ? 'done' : 'waiting', `${judgement.move}: ${judgement.reason}`);
+  }
   if (action.kind === 'green') return card('green requires a verified landing in this execution');
   // G1 — 기다림은 발사가 아니다: 대기 표지만 남기고 다음 틱이 다시 판단한다(카드로 올리지 않는다).
   if (action.kind === 'retry' && action.variant === 'wait') return record('waiting', `wait marker: ${action.rationale}`);

package/src/task-agent/board.ts

@@ -0,0 +1,132 @@
+/**
+ * 보드 일반형 — 프로젝트 › 목표 › 이정표 › 과제 (RFC-loop-agent-map §A4b①).
+ *
+ * «판(0.2.x)·칸» 체크리스트는 이 보드의 한 사례(내부 팩)다. 어댑터 둘은 «읽기»만 한다:
+ * - `cardsBoard(statePath)` — task-agent-actions.json 의 과제 카드(project.id · goal · milestone)를 트리로.
+ * - `releasePackBoard(version)` — 릴리스 체크리스트를 project=elanous · milestone=판 · task=칸 으로 사상. 원장은 쓰지 않는다.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { releaseLedgerRoot } from '../instance/resolve.js';
+import { listChecklist, type ChecklistStatus } from '../release-loop/checklist.js';
+import { readTaskAgentState, type CompletionKind, type TaskCard } from './task-hand.js';
+
+export type BoardLevel = 'project' | 'goal' | 'milestone' | 'task';
+export type BoardStatus = 'open' | 'done' | 'blocked';
+
+export interface BoardNode {
+  level: BoardLevel;
+  id: string;
+  title: string;
+  status: BoardStatus;
+  /** 과제 노드만 — 카드의 종결 종류(비면 code-pr 로 읽는다 · 칸은 싣지 않는다). */
+  completion?: CompletionKind;
+  /** 부모 노드 id(프로젝트는 없다). */
+  parent?: string;
+  /** 프로젝트 노드만 — 프로젝트 없는 카드의 자리(id 는 빈 문자열이라 실제 프로젝트 id 와 겹치지 않는다). */
+  unassigned?: true;
+  children?: BoardNode[];
+}
+
+/** 프로젝트가 없는 카드가 모이는 자리의 id — 빈 문자열(실제 프로젝트 id 는 비지 않는다 · `handTask` 가 빈 id 를 거부). */
+export const UNASSIGNED_PROJECT = '';
+/** 내부 팩(릴리스 체크리스트)의 프로젝트 id. */
+export const INTERNAL_PACK_PROJECT = 'elanous';
+
+function branch(level: BoardLevel, id: string, title: string, parent?: string): BoardNode {
+  // 무소속 프로젝트의 id 는 '' — 빈 문자열도 부모 id 로 보존한다.
+  return { level, id, title, status: 'open', ...(parent !== undefined ? { parent } : {}), children: [] };
+}
+
+function child(parent: BoardNode, level: BoardLevel, id: string, title = id): BoardNode {
+  let node = parent.children!.find((candidate) => candidate.level === level && candidate.id === id);
+  if (!node) {
+    node = branch(level, id, title, parent.id);
+    parent.children!.push(node);
+  }
+  return node;
+}
+
+/** 자식이 있는 노드의 상태 = 막힘 하나라도 → blocked · 전부 done → done · 그 밖 open. */
+function aggregate(node: BoardNode): void {
+  if (!node.children?.length) return;
+  for (const next of node.children) aggregate(next);
+  node.status = node.children.some((next) => next.status === 'blocked') ? 'blocked'
+    : node.children.every((next) => next.status === 'done') ? 'done' : 'open';
+}
+
+function cardStatus(card: TaskCard): BoardStatus {
+  if (card.status === 'launch-failed' || card.status === 'failed') return 'blocked';
+  return card.greenProposal ? 'done' : 'open';
+}
+
+/** 과제 카드 → 프로젝트 트리. 프로젝트 없는 카드는 «무소속»(`unassigned: true` · id '') 아래 — 어떤 프로젝트 id 로도 걸러지지 않는다. */
+export function cardsBoard(statePath: string): BoardNode[] {
+  const projects: BoardNode[] = [];
+  const cards = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(statePath).tasks ?? {};
+  for (const card of Object.values(cards)) {
+    const projectId = card.project?.id?.trim() || UNASSIGNED_PROJECT;
+    const unassigned = projectId === UNASSIGNED_PROJECT;
+    let project = projects.find((node) => node.id === projectId && (node.unassigned === true) === unassigned);
+    if (!project) {
+      project = unassigned ? { ...branch('project', UNASSIGNED_PROJECT, '무소속'), unassigned: true } : branch('project', projectId, projectId);
+      projects.push(project);
+    }
+    const goal = card.goal ? child(project, 'goal', card.goal) : project;
+    const milestone = card.milestone ? child(goal, 'milestone', card.milestone) : goal;
+    milestone.children!.push({
+      level: 'task', id: card.id, title: card.text, status: cardStatus(card),
+      ...(card.completion ? { completion: card.completion } : {}),
+      parent: milestone.id,
+    });
+  }
+  for (const project of projects) aggregate(project);
+  return projects;
+}
+
+function releaseStatus(status: ChecklistStatus): BoardStatus {
+  return status === 'green' || status === 'done' ? 'done' : status === 'red' ? 'blocked' : 'open';
+}
+
+/**
+ * 릴리스 체크리스트 → 내부 팩 보드(읽기 사상). 원장이 없으면 빈 보드 — 만들지 않는다.
+ * root 를 명시해 넘겨 옛 JSON 가져오기(쓰기)를 건너뛴다: 이 어댑터는 원장을 바꾸지 않는다.
+ */
+export function releasePackBoard(version: string, root = releaseLedgerRoot()): BoardNode[] {
+  if (!existsSync(join(root, 'release', 'features.sqlite'))) return [];
+  const checklist = listChecklist(version, root);
+  const project = branch('project', INTERNAL_PACK_PROJECT, 'elanous (내부 팩)');
+  const milestone = child(project, 'milestone', checklist.version, `판 ${checklist.version}`);
+  for (const item of checklist.items) {
+    milestone.children!.push({ level: 'task', id: item.id, title: item.title, status: releaseStatus(item.status), parent: milestone.id });
+  }
+  aggregate(project);
+  return [project];
+}
+
+function cloneNode(node: BoardNode): BoardNode {
+  return { ...node, ...(node.children ? { children: node.children.map(cloneNode) } : {}) };
+}
+
+/** 같은 수준·id 의 프로젝트·목표·이정표는 한 노드로 합친다(과제는 그대로 잇는다 — 다른 원천의 과제를 숨기지 않는다). */
+function mergeInto(target: BoardNode[], incoming: readonly BoardNode[]): void {
+  for (const node of incoming) {
+    const existing = node.level === 'task' ? undefined
+      : target.find((candidate) => candidate.level === node.level && candidate.id === node.id && candidate.unassigned === node.unassigned);
+    if (existing) mergeInto(existing.children ??= [], node.children ?? []);
+    else target.push(cloneNode(node));
+  }
+}
+
+/** 두 어댑터를 합친다 — 같은 수준·id 의 노드는 한 노드로(예: 카드의 이정표 0.2.19 ⊕ 체크리스트의 판 0.2.19) · 상태를 다시 모은다. 입력은 바꾸지 않는다. */
+export function mergeBoards(...boards: readonly BoardNode[][]): BoardNode[] {
+  const merged: BoardNode[] = [];
+  for (const board of boards) mergeInto(merged, board);
+  for (const project of merged) aggregate(project);
+  return merged;
+}
+
+/** 트리 안의 과제 노드 수. */
+export function countBoardTasks(nodes: readonly BoardNode[]): number {
+  return nodes.reduce((count, node) => count + (node.level === 'task' ? 1 : 0) + countBoardTasks(node.children ?? []), 0);
+}