@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/coordinator-verification.js

@@ -0,0 +1,42 @@
+'use strict';
+const seed = require("./seed-worktree");
+const verification = require("./verification");
+/**
+ * npm 설치 출력이 coordinator의 stdout 계약을 오염시키지 않도록 stderr로 보낸다.
+ *
+ * @param {Exec} exec - execFileSync 호환 함수
+ * @returns {Exec} 설치 출력을 stderr로 보내는 실행기
+ */
+function withInstallStdioToStderr(exec) {
+    return (file, args, options) => exec(file, args, { ...options, stdio: ['ignore', 2, 2] });
+}
+/**
+ * 검증 직전 의존성을 준비한다. 호출자는 준비 결과를 중간 판정 뒤에 해석한다.
+ *
+ * @param {string} repoRoot - 준비할 checkout
+ * @param {Exec} exec - 주입 가능한 실행기
+ * @returns {ReturnType<typeof seed.prepareDependencies>} 성공 여부와 설치 오류 정보
+ */
+function prepareVerificationDependencies(repoRoot, exec) {
+    return seed.prepareDependencies(repoRoot, { execFileSync: withInstallStdioToStderr(exec) });
+}
+/**
+ * 주입된 runner를 사용하고, 없으면 기본 verification runner를 고른다.
+ *
+ * @param {VerificationRunner | undefined} injected - 테스트 seam 또는 명시 주입
+ * @returns {VerificationRunner} 선택한 runner
+ */
+function selectVerificationRunner(injected) {
+    return injected || verification.runVerification;
+}
+/**
+ * 명시된 task·wave·terminal 대상에 기존 runner를 호출한다.
+ *
+ * @param {VerificationRunner} runner - 선택된 verification runner
+ * @param {Parameters<VerificationRunner>[0]} target - repo, blueprint, task 및 scope
+ * @returns {ReturnType<VerificationRunner>} 기존 evidence shape를 포함한 결과
+ */
+function runTargetVerification(runner, target) {
+    return runner(target);
+}
+module.exports = { withInstallStdioToStderr, prepareVerificationDependencies, selectVerificationRunner, runTargetVerification };

package/dist/coordinator-worker.js

@@ -0,0 +1,388 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const runtime = require("./runtime-state");
+const { coordinatorPathsFor } = runtime;
+const frontmatter = require("./frontmatter");
+const { parseFrontmatter, readDoc } = frontmatter;
+const commitShaMod = require("./commit-sha");
+const { normalizeCommitSha } = commitShaMod;
+const taskBriefHashMod = require("./task-brief-hash");
+const { taskBriefHash } = taskBriefHashMod;
+const executionDag = require("./execution-dag");
+const { normalizeOverlapPath } = executionDag;
+const coordinatorGit = require("./coordinator-git");
+const { git } = coordinatorGit;
+const contextIdsMod = require("./context-ids");
+const { parseContextPath, formatStableIntentId } = contextIdsMod;
+const schema = require("./schema");
+// worker·dispatch 조회 helper의 정본이다. 원장 I/O(coordinator-ledger)와 명령 구현
+// (coordinator-commands)이 모두 이 모듈을 가져오고, 이 모듈은 둘 다 가져오지 않아 순환이 없다.
+/**
+ * blueprint 경로를 canonical stable intent ID로 바꾼다.
+ *
+ * @param {string} blueprint - blueprint 상대 경로
+ * @returns {string} stable intent ID
+ * @throws epic 또는 blueprint 식별자를 해석할 수 없으면 Error
+ */
+function intentIdFor(blueprint) {
+    const ids = parseContextPath(blueprint);
+    if (!ids || ids.blueprintKey === null) {
+        throw new Error(`Cannot derive epic/blueprint ids from blueprint path: ${blueprint}`);
+    }
+    return formatStableIntentId({ format: ids.format, epicKey: ids.epicKey, blueprintKey: ids.blueprintKey });
+}
+/**
+ * blueprint index의 verification 정책을 읽는다. 알 수 없는 값은 legacy로 접지 않는다.
+ *
+ * @param {string} root - 문서를 읽을 checkout
+ * @param {string} blueprint - blueprint 상대 경로
+ * @returns {'scoped_terminal' | 'legacy' | null} 허용 정책 또는 invalid 표시
+ */
+function verificationPolicyAt(root, blueprint) {
+    const bouncer = readBouncerBlock(path.join(root, blueprint, 'index.md'));
+    return schema.verificationPolicyOf(bouncer);
+}
+/**
+ * implementer attempt의 최종 보고 파일 경로를 계산한다.
+ * dispatch 반환과 checkpoint 투영이 같은 경로를 쓰도록 계산을 이 한 곳에 둔다.
+ * `.bouncer/runtime/`은 gitignore라서 worker HEAD·porcelain 비교에 보이지 않는다.
+ *
+ * @param {string} workerPath - attempt를 수행하는 worker checkout 절대 경로
+ * @param {string} task - task 번호(예: '002')
+ * @param {number} attempt - dispatch attempt 번호
+ * @returns {string} `<workerPath>/.bouncer/runtime/reports/<task>-<attempt>.md` 절대 경로
+ */
+function reportPathFor(workerPath, task, attempt) {
+    return path.join(workerPath, '.bouncer', 'runtime', 'reports', `${task}-${attempt}.md`);
+}
+/**
+ * canonical tasks.md의 SHA-256. 파일을 읽은 뒤 taskBriefHash에 맡겨 dispatch·record가
+ * 같은 정규형 계약을 쓰게 한다 — intent-bundle의 task_brief_hash와 맞춘다.
+ *
+ * @param {string} workerRoot - 할당된 worker worktree
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {string} taskId - 세 자리 task id
+ * @returns {string} 64자리 소문자 hex
+ */
+function taskBriefHashOf(workerRoot, blueprint, taskId) {
+    const markdown = fs.readFileSync(path.join(workerRoot, blueprint, 'tasks', taskId, 'tasks.md'), 'utf8');
+    return taskBriefHash(markdown);
+}
+/**
+ * checkout의 blueprint index가 리뷰 모드인지 읽는다. 인덱스가 없거나 YAML이
+ * 깨지면 구형 계약(task 리뷰 요구)을 유지한다.
+ *
+ * @param {string} root - 문서를 읽을 checkout
+ * @param {string} blueprint - blueprint 상대 경로
+ * @returns {boolean} 모드이면 true
+ */
+function isBlueprintReviewModeAt(root, blueprint) {
+    const abs = path.join(root, blueprint, 'index.md');
+    try {
+        const { data } = readDoc(abs);
+        const rec = data;
+        const bouncer = rec && rec.bouncer;
+        // validate-docs.isBlueprintReviewMode와 같은 조건식이다. coordinator가
+        // validate-docs를 require하면 current→coordinator 순환이 생긴다.
+        return Boolean(bouncer && bouncer.review_scope === 'blueprint');
+    }
+    catch (error) {
+        // 인덱스 부재와 YAML 파싱 실패만 흡수한다. 모드가 아닌 쪽으로 접어야
+        // 구형 drive의 증적 요구가 풀리지 않는다.
+        if (error.code === 'ENOENT')
+            return false;
+        if (error.name === 'YAMLException')
+            return false;
+        throw error;
+    }
+}
+/**
+ * checkout의 blueprint index에서 리뷰 계약 표식을 읽는다. `isBlueprintReviewModeAt`과
+ * 같은 이유로 index 부재·YAML 파손은 구형(`legacy`)으로 접고, 리뷰 모드가 아니면
+ * 표식이 있어도 적용하지 않는다(S38이 `review_scope: blueprint` 없는 표식을 plan gate에서
+ * 거절하므로 dispatch와 coordinator가 같은 blueprint를 다르게 읽는 경우는 없다).
+ *
+ * @param {string} root - 문서를 읽을 checkout
+ * @param {string} blueprint - blueprint 상대 경로
+ * @returns {'brief' | 'legacy' | null} 허용 밖의 표식 값이면 null — 호출자가 거절한다
+ */
+function reviewContractAt(root, blueprint) {
+    const abs = path.join(root, blueprint, 'index.md');
+    let data;
+    try {
+        data = readDoc(abs).data;
+    }
+    catch (error) {
+        // 인덱스 부재와 YAML 파싱 실패만 흡수한다(isBlueprintReviewModeAt과 같은 기준).
+        if (error.code === 'ENOENT')
+            return 'legacy';
+        if (error.name === 'YAMLException')
+            return 'legacy';
+        throw error;
+    }
+    const bouncer = data?.bouncer;
+    if (!bouncer || bouncer.review_scope !== 'blueprint')
+        return 'legacy';
+    return schema.reviewContractOf(bouncer);
+}
+// frontmatter.ts의 FRONTMATTER_RE에서 뒤쪽 `\n?([\s\S]*)$`(항상 맞는 부분)를 뺀
+// 앞부분과 같다. 이 검사를 통과한 문서는 parseFrontmatter가 블록 부재로 throw할 수
+// 없으므로, 블록 부재를 오류 문구 비교 없이 구조로 판정한다.
+const FRONTMATTER_FENCE_RE = /^---\n[\s\S]*?\n---/;
+/**
+ * 문서의 bouncer 블록을 읽는다. 문서가 없거나 frontmatter 블록이 없거나 YAML이
+ * 깨졌으면 null — 호출자는 셋 다 "상태를 읽을 수 없다"로 판정한다. integrate의
+ * worker 증적 판정과 finalize의 원장·문서 대조가 이 한 구현을 같이 쓴다.
+ *
+ * @param {string} file - 문서 절대 경로
+ * @returns {Record<string, unknown> | null} bouncer 블록 또는 null
+ * @example
+ * readBouncerBlock('/wt/.bouncer/.../tasks/001/tasks.md'); // { id: 'TASKS-001', status: 'verified', ... }
+ * readBouncerBlock('/wt/.bouncer/.../tasks/001/missing.md'); // null
+ */
+function readBouncerBlock(file) {
+    let source;
+    try {
+        source = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        // 파일 부재(ENOENT)만 흡수한다. 아직 쓰이지 않은 문서는 상태를 읽을 수 없는 것으로
+        // 판정하면 되지만, 권한 오류 같은 다른 실패를 "문서 없음"으로 접으면 원인이 가려진다.
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!FRONTMATTER_FENCE_RE.test(source))
+        return null;
+    let data;
+    try {
+        data = parseFrontmatter(source).data;
+    }
+    catch (error) {
+        // YAML 파싱 오류만 흡수한다. 블록 부재는 위 구조 검사가 이미 걸렀으므로 여기 오는
+        // 것은 깨진 YAML뿐이고, 상태를 읽을 수 없는 문서라 null로 접어도 판정이 안전하다.
+        if (error.name === 'YAMLException')
+            return null;
+        throw error;
+    }
+    const bouncer = data && typeof data === 'object' ? data.bouncer : null;
+    return bouncer && typeof bouncer === 'object' ? bouncer : null;
+}
+const EVIDENCE_FILES = [
+    ['tasks.md', 'verified'], ['verification.md', 'passed'], ['review.md', 'accepted'],
+];
+/**
+ * fan-in이 요구하는 worker 증적 파일과 terminal 상태 쌍을 고른다.
+ * blueprint review 모드에서는 루트 리뷰가 정본이므로 task `review.md`를 뺀다.
+ *
+ * @param {boolean} reviewMode - integration blueprint index의 리뷰 모드
+ * @returns {ReadonlyArray<readonly [string, string]>} 파일명과 기대 status
+ */
+function evidenceFiles(reviewMode) {
+    return reviewMode ? EVIDENCE_FILES.filter(([name]) => name !== 'review.md') : EVIDENCE_FILES;
+}
+/**
+ * worker task bundle이 fan-in할 terminal 증적인지 판정한다. 요구 모드는 integration
+ * index만 읽어 worker가 review_scope를 바꾸어 검사 항목을 줄이지 못하게 한다.
+ *
+ * @param {string} workerPath - 배정된 worker worktree
+ * @param {string} integrationPath - review 모드의 정본 checkout
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {string} taskId - 세 자리 task 번호
+ * @param {string} sha - 원장에 기록된 worker SHA
+ * @returns {{ ok: true } | { ok: false; reason: string; files: string[] }} 판정
+ */
+function checkWorkerEvidence(workerPath, integrationPath, blueprint, taskId, sha) {
+    const relOf = (name) => `${blueprint.replaceAll('\\', '/')}/tasks/${taskId}/${name}`;
+    const open = [];
+    let stamped;
+    const reviewMode = isBlueprintReviewModeAt(integrationPath, blueprint);
+    for (const [name, terminal] of evidenceFiles(reviewMode)) {
+        const bouncer = readBouncerBlock(path.join(workerPath, blueprint, 'tasks', taskId, name));
+        if (!bouncer || bouncer.status !== terminal)
+            open.push(relOf(name));
+        if (name === 'tasks.md' && bouncer)
+            stamped = bouncer.commit_sha;
+    }
+    if (open.length > 0)
+        return { ok: false, reason: 'worker-evidence-not-terminal', files: open };
+    if (normalizeCommitSha(stamped) !== sha.slice(0, 8).toLowerCase()) {
+        return { ok: false, reason: 'worker-evidence-sha-mismatch', files: [relOf('tasks.md')] };
+    }
+    return { ok: true };
+}
+/**
+ * worker terminal bundle을 integration에 복사하고, 실패 시 복사 전 바이트를 복원한다.
+ *
+ * @param {string} workerPath - 배정된 worker worktree
+ * @param {string} integrationPath - integration checkout 및 모드 정본
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {string} taskId - 세 자리 task 번호
+ * @returns {() => void} 성공 후 rollback 함수
+ */
+function copyEvidenceBundle(workerPath, integrationPath, blueprint, taskId) {
+    const targetDir = path.join(integrationPath, blueprint, 'tasks', taskId);
+    const dirExisted = fs.existsSync(targetDir);
+    const entries = evidenceFiles(isBlueprintReviewModeAt(integrationPath, blueprint)).map(([name]) => {
+        const target = path.join(targetDir, name);
+        return {
+            source: path.join(workerPath, blueprint, 'tasks', taskId, name), target,
+            before: fs.existsSync(target) ? fs.readFileSync(target) : null,
+        };
+    });
+    const restore = () => {
+        if (!dirExisted) {
+            fs.rmSync(targetDir, { recursive: true, force: true });
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.before === null)
+                fs.rmSync(entry.target, { force: true });
+            else
+                fs.writeFileSync(entry.target, entry.before);
+        }
+    };
+    try {
+        fs.mkdirSync(targetDir, { recursive: true });
+        for (const entry of entries)
+            fs.copyFileSync(entry.source, entry.target);
+    }
+    catch (error) {
+        // 일부만 복사된 bundle은 fan-in 기준이 될 수 없으므로 되돌린 뒤 같은 오류를 전달한다.
+        restore();
+        throw error;
+    }
+    return restore;
+}
+/**
+ * supplement 경로 표기를 맞춘다. 역슬래시·`./` 접두를 정리해 포함 비교가 표기
+ * 차이로 어긋나지 않게 한다.
+ *
+ * @param {string} raw - `--paths` 항목 또는 task 경로
+ * @returns {string} posix 정규형(말미 `/` 제거)
+ */
+function normalizeSupplementPath(raw) {
+    return normalizeOverlapPath(path.posix.normalize(raw.replaceAll('\\', '/').trim()));
+}
+/**
+ * worktree의 커밋되지 않은 변경 경로를 필터 없이 모은다(추적·미추적 모두, rename은 양쪽).
+ * `-z`를 쓰므로 한국어·따옴표가 든 이름도 C-quote 없이 원문 그대로 나온다.
+ *
+ * @param {Exec} exec - 주입 가능한 Git 실행기
+ * @param {string} cwd - 검사할 worktree
+ * @returns {string[]} 정규형 변경 경로
+ */
+function porcelainPaths(exec, cwd) {
+    const raw = String(exec('git', ['status', '--porcelain', '-z', '-uall'], {
+        cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    }));
+    const tokens = raw.split('\0').filter((token) => token !== '');
+    const out = [];
+    for (let i = 0; i < tokens.length; i += 1) {
+        const status = tokens[i].slice(0, 2);
+        out.push(normalizeSupplementPath(tokens[i].slice(3)));
+        // rename·copy는 다음 토큰이 원래 경로다.
+        if (/[RC]/.test(status) && i + 1 < tokens.length) {
+            i += 1;
+            out.push(normalizeSupplementPath(tokens[i]));
+        }
+    }
+    return out;
+}
+/**
+ * task의 현재 승인 scope. scope_revision으로 갱신된 ledger scope가 있으면 그것이 정본이고,
+ * 없으면 계획의 affected_paths다. 의존성 공유 여부를 가르는 seed가 이 값을 받는다.
+ *
+ * @param {Task} task - ledger task
+ * @returns {string[]} 현재 승인 경로
+ */
+function currentScopePaths(task) {
+    return task.scope && Array.isArray(task.scope.paths) ? [...task.scope.paths] : [...(task.affected_paths || [])];
+}
+/**
+ * worker porcelain 경로 가운데 task 현재 scope 안에 있고 tasks.md가 아닌 "커밋할 scope 변경"을 모은다.
+ * tasks.md는 `bouncer commit`이 stamp를 쓰는 파일이라 정상 잔여물이므로 뺀다. dispatch 기준선은
+ * 면제하지 않는다. `workerCommitEvidence`의 scope dirty 판정과 `coordinate next`의 commit 선택이
+ * 같은 집합을 보게 하려고 한 곳에 둔다. 읽기만 한다.
+ *
+ * @param {Exec} exec - 주입 가능한 Git 실행기
+ * @param {string} workerPath - worker(light는 integration) checkout
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {Task} task - ledger task(현재 scope 경로의 출처)
+ * @returns {string[]} 중복을 없애 정렬한 repo 상대 경로. 없으면 빈 배열
+ */
+function workerScopeDirtyPaths(exec, workerPath, blueprint, task) {
+    const briefRel = `${blueprint.replaceAll('\\', '/')}/tasks/${task.id}/tasks.md`;
+    const scope = currentScopePaths(task).map((entry) => normalizeSupplementPath(entry).replace(/\/+$/, ''));
+    const dirty = porcelainPaths(exec, workerPath).filter((rel) => rel !== briefRel
+        && scope.some((entry) => entry !== '' && (rel === entry || rel.startsWith(`${entry}/`))));
+    return [...new Set(dirty)].sort();
+}
+/**
+ * worker가 report(accepted)·record 전에 task commit을 확정했는지 읽기 전용으로 판정한다.
+ * 검사 순서는 원인이 겹칠 때 보이는 코드를 정한다: 커밋 부재 → stamp 불일치 → scope 안 dirty.
+ * 비교 기준은 `ledger.integrationHead`다. wave에서 다른 worker가 먼저 통합돼 live HEAD가
+ * 움직여도 남은 worker를 오판하지 않기 위해서다. `coordinate-next`의 report 선택과 같은
+ * stamp 규칙(`commit_sha` 앞 8자 == HEAD 앞 8자)을 쓰도록 이 함수가 단일 정본이다.
+ *
+ * @param {Exec} exec - 주입 가능한 Git 실행기
+ * @param {string} workerPath - worker(light는 integration) checkout
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {Task} task - ledger task(현재 scope 경로의 출처)
+ * @param {{ integrationHead?: unknown }} ledger - integrationHead를 읽을 원장
+ * @returns {{ ok: true } | { ok: false; reason: string; head: string; integration_head: string | null;
+ *   stamp: string | null; dirty_paths: string[] }} 판정
+ */
+function workerCommitEvidence(exec, workerPath, blueprint, task, ledger) {
+    const head = git(exec, workerPath, ['rev-parse', 'HEAD']);
+    const integrationHead = typeof ledger.integrationHead === 'string' ? ledger.integrationHead : null;
+    const block = readBouncerBlock(path.join(workerPath, blueprint, 'tasks', task.id, 'tasks.md'));
+    const stampRaw = block ? normalizeCommitSha(block.commit_sha) : '';
+    const stamp = stampRaw === '' ? null : stampRaw;
+    const refuse = (reason, dirty = []) => ({
+        ok: false, reason, head, integration_head: integrationHead, stamp, dirty_paths: dirty,
+    });
+    // 1. HEAD가 integrationHead와 같거나 그 조상이면 worker가 만든 커밋이 없다.
+    //    is-ancestor는 같은 커밋도 성공(exit 0)으로 답한다. exit 1(비조상)만 "커밋 있음"이고,
+    //    object 조회 실패 같은 다른 오류는 추측하지 않고 그대로 올린다.
+    if (integrationHead !== null) {
+        let ancestor;
+        try {
+            git(exec, workerPath, ['merge-base', '--is-ancestor', head, integrationHead]);
+            ancestor = true;
+        }
+        catch (error) {
+            if (error.status !== 1)
+                throw error;
+            ancestor = false;
+        }
+        if (ancestor)
+            return refuse('worker-commit-missing');
+    }
+    // 2. stamp는 `bouncer commit`이 찍는 HEAD 앞 8자와 같아야 한다.
+    if (stamp !== head.slice(0, 8).toLowerCase())
+        return refuse('worker-commit-stamp-mismatch');
+    // 3. scope 안 dirty는 dispatch 기준선에 있어도 거절한다 — 재dispatch 때 앞 attempt의
+    //    미커밋 수정이 기준선에 흡수되므로 기준선 면제는 커밋 누락을 숨긴다.
+    //    tasks.md 제외 규칙은 workerScopeDirtyPaths가 갖는다(next와 같은 집합을 쓰기 위해 추출).
+    const dirty = workerScopeDirtyPaths(exec, workerPath, blueprint, task);
+    if (dirty.length > 0)
+        return refuse('worker-scope-dirty', dirty);
+    return { ok: true };
+}
+function ensureIntegrationCwd(repoRoot, blueprint, cwd, task) {
+    const paths = coordinatorPathsFor({ repoRoot, blueprint, task });
+    const actual = fs.realpathSync(cwd);
+    const allowed = fs.realpathSync(task ? paths.workerPath : paths.integrationPath);
+    if (actual !== allowed)
+        throw new Error('coordinate command must run in its assigned worktree');
+    return paths;
+}
+module.exports = {
+    reportPathFor, taskBriefHashOf, isBlueprintReviewModeAt, reviewContractAt, readBouncerBlock,
+    evidenceFiles, checkWorkerEvidence, copyEvidenceBundle,
+    workerCommitEvidence, workerScopeDirtyPaths, ensureIntegrationCwd,
+    // coordinator-commands가 같은 경로 정규형과 scope 규칙을 쓰도록 함께 내보낸다.
+    currentScopePaths, normalizeSupplementPath, porcelainPaths, intentIdFor, verificationPolicyAt,
+};

package/dist/coordinator.js

@@ -0,0 +1,7 @@
+'use strict';
+const commands = require("./coordinator-commands");
+module.exports = {
+    coordinate: commands.coordinate,
+    COORDINATE_FAILURE_HINTS: commands.COORDINATE_FAILURE_HINTS,
+    withCoordinateFailureHints: commands.withCoordinateFailureHints,
+};

package/dist/cross-drive.js

@@ -0,0 +1,85 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const runtime = require("./runtime-state");
+const { runtimePaths, COORDINATOR_LEDGER_REL } = runtime;
+const executionDag = require("./execution-dag");
+const { taskConflictDetail } = executionDag;
+/**
+ * 저장소의 worktree 원장을 열거해 다른 활성 drive의 시작된 task만 돌려준다.
+ * 원장 경로가 존재하는데 읽을 수 없으면 충돌을 놓치지 않도록 해당 경로로 실패한다.
+ *
+ * @param {object} opts - 저장소와 현재 drive 원장
+ * @param {string} opts.repoRoot - main checkout 루트
+ * @param {string} opts.ownLedgerFile - 제외할 현재 원장 절대 경로
+ * @returns {object} 성공 시 drives, 실패 시 읽을 수 없는 ledgerFile이 포함된 거절
+ */
+function otherDriveTasks({ repoRoot, ownLedgerFile }) {
+    const roots = runtimePaths({ repoRoot });
+    if ('unavailable' in roots)
+        return { ok: true, drives: [] };
+    const worktreeRoot = roots.worktreeRoot;
+    const drives = [];
+    let epics;
+    try {
+        epics = fs.readdirSync(worktreeRoot);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { ok: true, drives };
+        throw error;
+    }
+    for (const epic of epics) {
+        const epicPath = path.join(worktreeRoot, epic);
+        if (!fs.statSync(epicPath).isDirectory())
+            continue;
+        for (const blueprint of fs.readdirSync(epicPath)) {
+            const integration = path.join(epicPath, blueprint, 'integration');
+            if (!fs.existsSync(integration) || !fs.statSync(integration).isDirectory())
+                continue;
+            const ledgerFile = path.join(integration, ...COORDINATOR_LEDGER_REL.split('/'));
+            if (path.resolve(ledgerFile) === path.resolve(ownLedgerFile) || !fs.existsSync(ledgerFile))
+                continue;
+            let ledger;
+            try {
+                ledger = JSON.parse(fs.readFileSync(ledgerFile, 'utf8'));
+            }
+            catch (_error) {
+                // JSON 파싱 오류만 원장 불가로 흡수한다. 충돌 가능성을 누락하지 않게 prepare를 막는다.
+                return { ok: false, reason: 'cross-drive-ledger-unreadable', ledgerFile };
+            }
+            if (!ledger || typeof ledger !== 'object') {
+                return { ok: false, reason: 'cross-drive-ledger-unreadable', ledgerFile };
+            }
+            if (ledger.status === 'detached')
+                continue;
+            const tasks = Array.isArray(ledger.tasks)
+                ? ledger.tasks.filter((task) => task && task.status !== 'pending') : [];
+            drives.push({ blueprint: typeof ledger.blueprint === 'string'
+                    ? ledger.blueprint : `${epic}/${blueprint}`, ledgerFile, tasks });
+        }
+    }
+    return { ok: true, drives };
+}
+/**
+ * 후보 task 각각을 모든 활성 drive task와 비교해 상대 원장 기준 충돌을 만든다.
+ *
+ * @param {Task[]} candidates - 이번 prepare wave 후보
+ * @param {DriveTasks[]} drives - 다른 원장에서 읽은 task 집합
+ * @returns {DriveConflict[]} 충돌 상대별 상세 목록
+ */
+function crossDriveConflicts(candidates, drives) {
+    const conflicts = [];
+    for (const candidate of candidates) {
+        for (const drive of drives) {
+            for (const task of drive.tasks) {
+                const detail = taskConflictDetail(candidate, task);
+                if (detail)
+                    conflicts.push({ blueprint: drive.blueprint, task: task.id,
+                        paths: detail.paths, resources: detail.resources, legacy: detail.legacy });
+            }
+        }
+    }
+    return conflicts;
+}
+module.exports = { otherDriveTasks, crossDriveConflicts };