@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/coordinate-next.js

@@ -0,0 +1,998 @@
+'use strict';
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync: realExecFileSync } = require('node:child_process');
+const coordinator = require("./coordinator");
+const schema = require("./schema");
+const reviewRepairState = require("./review-repair-state");
+const { hasReviewRepairDecision, reviewRoundExists } = reviewRepairState;
+const { COORDINATE_FAILURE_HINTS } = coordinator;
+const coordinatorLedger = require("./coordinator-ledger");
+const { assertLeaseShape, loadLedgerBytes, projectCheckpoint } = coordinatorLedger;
+const coordinatorWorker = require("./coordinator-worker");
+const { ensureIntegrationCwd, isBlueprintReviewModeAt, reviewContractAt, taskBriefHashOf, readBouncerBlock, reportPathFor, workerCommitEvidence, workerScopeDirtyPaths, } = coordinatorWorker;
+const coordinatorGit = require("./coordinator-git");
+const { registeredIntegration, initialWorktreeState } = coordinatorGit;
+const runtime = require("./runtime-state");
+const { coordinatorPathsFor, runtimePaths } = runtime;
+const configMod = require("./config");
+const driveMetrics = require("./drive-metrics");
+const plugin_root_1 = require("./plugin-root");
+const execution_contracts_1 = require("./execution-contracts");
+// 계약 카드를 싣는 action. 판단(judge)이나 worker 위임이 필요한 행동만 카드를 받는다.
+// argv만 실행하면 끝나는 prepare·drive_tasks·integrate·verification_node·commit·done·none은
+// 카드가 없다 — 응답을 키우지 않고, 그 행동의 규칙은 argv 자체가 담는다.
+const CARD_IDS = [
+    'dispatch', 'implement', 'verify', 'review', 'report', 'revise', 'record', 'final_review', 'supplement',
+    'blocked',
+];
+const NEXT_FAILURE_HINTS = {
+    'worker-commit-stamp-mismatch': {
+        cause: 'The commit_sha stamp in the worker tasks.md differs from the first 8 chars of HEAD and no in-scope ' +
+            'change is left to commit.',
+        next: 'Do not rerun commit (nothing is left to commit). Report the stale stamp to the user, or `bouncer ' +
+            'coordinate revoke` and `prepare` the task again.',
+    },
+    'partial-closed': {
+        cause: 'This drive was partial-closed after the repair-wave limit.',
+        next: 'Report the preserved drive to the user; do not retry coordinate mutations on this blueprint.',
+    },
+    'terminal-verification-failed': {
+        cause: 'Terminal verification failed and that verification task is still verifying.',
+        next: 'Inspect the failure. If it was environmental, fix it and run ' +
+            '`bouncer coordinate reverify --task <terminal>`; ' +
+            'otherwise `bouncer coordinate repair`, or report the block to the user.',
+    },
+    'no-ready-task': {
+        cause: 'No prepared, recorded, ready, or integrable work remains, and the blueprint is not done.',
+        next: 'Run `bouncer coordinate status` and report the unexpected ledger combination; do not invent an action.',
+    },
+    'final-review-blocked': {
+        cause: 'The blueprint final review already recorded its one discovery round and the root review is not accepted.',
+        next: 'Show the open findings to the user and wait for their decision (note + deferred, or '
+            + 'accepted-risk consent); do not run a delta round or repair.',
+    },
+    'review-contract-invalid': {
+        cause: 'The blueprint index `review_contract` value is not an allowed marker, so the final review path is closed.',
+        next: 'Report to the user and fix `review_contract` through `/bouncer-plan`; do not run the final review.',
+    },
+    'critical-recovery-open': {
+        cause: 'This prepared task has an open critical-recovery record with no outcome yet.',
+        next: 'Close it with `bouncer coordinate critical-recovery` outcome resolved or blocked before driving the task.',
+    },
+    'task-reported-blocked': {
+        cause: 'The worker reported outcome blocked, so the coordinator must stop this task.',
+        next: 'Report the block to the user; do not dispatch or record this attempt.',
+    },
+    'commit-evidence-mismatch': {
+        cause: 'Worker HEAD, commit_sha, or porcelain does not match a commit that, beyond the paths already dirty '
+            + 'at dispatch, only dirtied this task tasks.md.',
+        next: 'Restore the worker to the recorded commit evidence, or redo commit so only that tasks.md is dirty.',
+    },
+    'verification-task-uses-blueprint-next': {
+        cause: 'Verification tasks are driven with blueprint-scope next, not --task.',
+        next: 'Omit --task and run `bouncer coordinate next --blueprint <dir>` so verification_node can be selected.',
+    },
+    'coordinator-card-missing': {
+        cause: 'The contract card for this action is missing or unreadable in plugin references/coordinator-cards/.',
+        next: 'Reinstall the Bouncer plugin so references/coordinator-cards/ ships every card, then call next again.',
+    },
+};
+/**
+ * reason에 맞는 cause·next를 고른다. next가 만든 reason은 NEXT_FAILURE_HINTS,
+ * 기존 coordinate reason은 COORDINATE_FAILURE_HINTS만 본다 — 같은 키를 두 표에
+ * 두면 안내가 갈라진다.
+ *
+ * @param {string} reason - 실패 또는 blocked reason
+ * @returns {{ cause: string, next: string }} 안내 문구
+ */
+function hintFor(reason) {
+    return NEXT_FAILURE_HINTS[reason] || COORDINATE_FAILURE_HINTS[reason] || {
+        cause: reason,
+        next: 'Run `bouncer coordinate status` and continue from its checkpoint.',
+    };
+}
+/**
+ * ok:false 결과에 힌트를 붙인다.
+ *
+ * @param {string} reason - 거절 코드
+ * @returns {NextErr} exit 1 대상
+ */
+function fail(reason) {
+    const hint = hintFor(reason);
+    return { ok: false, reason, cause: hint.cause, next: hint.next };
+}
+/**
+ * 플러그인 자산 루트(`resolvePluginAssetRoot`)의 계약 카드 한 장을 UTF-8
+ * 그대로 읽는다. cwd·`--repo`·소비 저장소는 보지 않는다 —
+ * 카드는 플러그인이 배포하는 계약이지 사용자 저장소 문서가 아니다.
+ * 루트 해석 실패는 resolver의 Error를, 파일이 없거나 읽기에 실패하면 fs 오류를 그대로
+ * 던진다. 호출부 `attachCard`가 둘을 같은 `coordinator-card-missing`으로 흡수한다.
+ *
+ * @param {CardId} id - 카드 id. 호출부가 CARD_IDS 안의 값만 넘긴다
+ * @returns {string} 카드 파일 본문
+ */
+function readPluginCard(id) {
+    return fs.readFileSync(path.join((0, plugin_root_1.resolvePluginAssetRoot)(), 'references', 'coordinator-cards', `${id}.md`), 'utf8');
+}
+/**
+ * 성공 응답의 action이 카드 대상이면 `card: { id, body }`를 붙인다.
+ * 카드를 못 읽으면 카드 없는 성공 응답으로 내보내지 않고
+ * `coordinator-card-missing`으로 거절한다 — 규칙 없이 행동만 받은 coordinator가
+ * 예전처럼 reference를 뒤지거나 규칙을 추측하지 않게 하려는 것이다.
+ *
+ * @param {NextOk | NextErr} result - blueprintNext/taskNext 판정
+ * @param {(id: CardId) => string} readCard - 카드 읽기. 기본은 readPluginCard
+ * @returns {NextOk | NextErr} 카드를 붙인 성공 응답, 비대상 응답 그대로, 또는 거절
+ */
+function attachCard(result, readCard) {
+    if (!result.ok)
+        return result;
+    const id = CARD_IDS.find((candidate) => candidate === result.action);
+    if (id === undefined)
+        return result;
+    let body;
+    try {
+        body = readCard(id);
+    }
+    catch (error) {
+        // 카드 읽기의 모든 실패(ENOENT·EACCES·EISDIR, 주입 seam의 throw)를 같은 거절로 흡수한다.
+        // 어느 경우든 이 action의 계약을 줄 수 없다는 결과는 같고, 원장·worktree는 이
+        // 함수가 건드리지 않으므로 흡수해도 상태가 어긋나지 않는다. 안내는 hint가 맡는다.
+        if (error instanceof Error && 'code' in error
+            && error.code === 'BOUNCER_PLUGIN_VERSION_MISMATCH') {
+            return {
+                ...fail('coordinator-card-missing'),
+                cause: error.message,
+                next: 'Install a compatible npm runtime version or repair BOUNCER_HOME to a compatible plugin install.',
+            };
+        }
+        return fail('coordinator-card-missing');
+    }
+    return { ...result, card: { id, body } };
+}
+/**
+ * 증거 파일의 sha256을 계산한다. 읽기 실패는 null miss로 돌려 throw하지 않는다 —
+ * 없는 파일을 이유로 판단 응답 전체를 거절하면 카드·report 요약까지 잃는다.
+ *
+ * @param {string} filePath - 절대 또는 해석 가능한 증거 경로
+ * @returns {{ sha256: string } | null} 해시 또는 읽기 실패 시 null
+ */
+function readEvidenceFile(filePath) {
+    try {
+        const bytes = fs.readFileSync(filePath);
+        return { sha256: crypto.createHash('sha256').update(bytes).digest('hex') };
+    }
+    catch (_error) {
+        // ENOENT·EACCES·EISDIR 등 모든 읽기 실패를 같은 miss로 흡수한다. 항목만
+        // evidence에서 빠지며 ok:false로 올리지 않는 계약이다.
+        return null;
+    }
+}
+/**
+ * 후보 경로가 지정한 루트 안(또는 루트 자체)인지 본다. 밖으로 나가면 포인터에
+ * 넣지 않는다 — 증거 포인터는 읽기 지침일 뿐 판단 범위를 넓히지 않는다.
+ *
+ * @param {string} candidatePath - 후보 절대/상대 경로
+ * @param {string} rootPath - 허용할 worker 또는 integration 루트
+ * @returns {boolean} 지정한 루트 안이면 true
+ */
+function isInsideRootPath(candidatePath, rootPath) {
+    const resolved = path.resolve(candidatePath);
+    const root = path.resolve(rootPath);
+    return resolved === root || resolved.startsWith(`${root}${path.sep}`);
+}
+/**
+ * 판단·worker 응답에 `payload.report`와 `payload.evidence`를 붙인다.
+ * `judge`도 worker 위임(`implement`)도 아니면 그대로 돌려 prepare·integrate·
+ * commit·done 등이 판단 문맥을 받지 않게 한다. 직전 report가 없으면 `report`
+ * 키를 만들지 않고, 읽기 실패·worker 밖 후보는 evidence에서만 뺀다.
+ *
+ * @param {NextOk} result - 카드 첨부 전·후의 성공 응답
+ * @param {JudgeContext} ctx - 직전 report·worker 루트·후보·읽기 seam
+ * @returns {NextOk} report/evidence가 병합된 응답, 또는 비대상 응답 그대로
+ */
+function attachJudgeContext(result, ctx) {
+    // 1. 판단(judge 필드)과 worker 위임(implement)만 대상. 그 밖은 payload를 건드리지 않는다.
+    const isJudge = result.judge !== undefined && result.judge !== null;
+    const isWorker = result.action === 'implement';
+    if (!isJudge && !isWorker)
+        return result;
+    const payload = { ...(result.payload || {}) };
+    // previous_outcome은 report로 대체한다. 옛 키를 남기면 클라이언트가 둘을 섞어 읽는다.
+    delete payload.previous_outcome;
+    // 2. 원장 마지막 kind:report만 요약으로 싣는다. 원문 outcome/summary는 자르지 않는다.
+    if (ctx.lastReport) {
+        payload.report = {
+            outcome: ctx.lastReport.outcome,
+            summary: ctx.lastReport.summary,
+            attempt: ctx.lastReport.attempt,
+        };
+    }
+    // 3. worker 안 후보만 읽고, null miss는 항목 생략. 빈 배열이면 evidence 키 자체를 빼
+    // "없음"과 빈 목록을 구분하지 않고 응답을 작게 유지한다.
+    const evidence = [];
+    for (const candidate of ctx.candidates) {
+        if (!isInsideRootPath(candidate.path, ctx.workerPath))
+            continue;
+        const read = ctx.readEvidence(candidate.path);
+        if (!read)
+            continue;
+        evidence.push({ kind: candidate.kind, path: candidate.path, sha256: read.sha256 });
+    }
+    if (evidence.length > 0)
+        payload.evidence = evidence;
+    else
+        delete payload.evidence;
+    if (!ctx.lastReport)
+        delete payload.report;
+    // payload가 비고 기존에도 없었으면 키 자체를 생략해 응답을 키우지 않는다.
+    if (Object.keys(payload).length === 0 && result.payload === undefined) {
+        const { payload: _dropped, ...rest } = result;
+        void _dropped;
+        return rest;
+    }
+    return { ...result, payload };
+}
+/**
+ * 실패한 terminal verification 문서를 integration 루트 안에서만 증거 포인터로 싣는다.
+ * 원장 본문이나 로그를 복사하지 않고, 현재 파일의 경로와 바이트 SHA256만 제공한다.
+ *
+ * @param {NextOk} result - terminal 실패 응답
+ * @param {string} integrationPath - 할당된 integration 루트
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {string} taskId - 실패한 verification task id
+ * @param {ReadEvidence} readEvidence - 증거 파일 SHA256 reader
+ * @returns {NextOk} 해시 포인터가 추가된 응답, 읽기 실패 시 원래 응답
+ */
+function attachTerminalVerificationEvidence(result, integrationPath, blueprint, taskId, readEvidence) {
+    if (result.action !== 'blocked' || result.reason !== 'terminal-verification-failed')
+        return result;
+    const verificationPath = path.resolve(integrationPath, blueprint.replaceAll('\\', '/'), 'tasks', taskId, 'verification.md');
+    if (!isInsideRootPath(verificationPath, integrationPath))
+        return result;
+    const file = readEvidence(verificationPath);
+    if (!file)
+        return result;
+    return {
+        ...result,
+        payload: {
+            ...(result.payload || {}),
+            evidence: [{ kind: 'verification', path: verificationPath, sha256: file.sha256 }],
+        },
+    };
+}
+/**
+ * worker task 디렉터리의 기본 증거 후보. report.md는 선택 산출물이라 없어도
+ * miss로 빠지고, verification.md·review.md는 게이트 문서 경로다.
+ *
+ * @param {string} workerPath - 할당 worker 절대 경로
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {string} taskId - 세 자리 task id
+ * @param {number | undefined} attempt - 활성 dispatch attempt. 없으면 보고 후보를 만들지 않는다
+ * @returns {EvidenceCandidate[]} kind·path 후보
+ */
+function defaultEvidenceCandidates(workerPath, blueprint, taskId, attempt) {
+    const taskDir = path.join(workerPath, blueprint.replaceAll('\\', '/'), 'tasks', taskId);
+    return [
+        // 보고 파일은 `coordinate report`가 읽는 reportPathFor 경로와 같아야 한다.
+        ...(attempt === undefined ? []
+            : [{ kind: 'report', path: reportPathFor(workerPath, taskId, attempt) }]),
+        { kind: 'verification', path: path.join(taskDir, 'verification.md') },
+        { kind: 'review', path: path.join(taskDir, 'review.md') },
+    ];
+}
+/**
+ * Git 한 번. trim은 rev-parse 비교용이고 porcelain은 별도 헬퍼가 원문을 지킨다.
+ *
+ * @param {Exec} exec - 주입 실행기
+ * @param {string} cwd - 작업 디렉터리
+ * @param {string[]} args - git argv
+ * @returns {string} stdout trim
+ */
+function git(exec, cwd, args) {
+    return String(exec('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })).trim();
+}
+/**
+ * fence 쌍. next가 읽은 bytes의 path·hash만 넣어야 argv 실행이 stale로 거절되지 않는다.
+ *
+ * @param {LedgerRef} ledger - checkpoint.ledger
+ * @returns {string[]} --ledger-path/--ledger-hash 토큰
+ */
+function fenceArgs(ledger) {
+    return ['--ledger-path', ledger.path, '--ledger-hash', ledger.sha256];
+}
+/**
+ * 원장 lease가 있을 때만 플래그를 붙인다. verification은 lease가 없어 꾸며내지 않는다.
+ *
+ * @param {LedgerTask} [item] - 대상 task
+ * @returns {string[]} lease 플래그 또는 빈 배열
+ */
+function leaseArgs(item) {
+    if (!item || !item.lease || typeof item.lease.id !== 'string')
+        return [];
+    if (!Number.isInteger(item.lease.generation))
+        return [];
+    return ['--lease-id', item.lease.id, '--generation', String(item.lease.generation)];
+}
+/**
+ * `bouncer coordinate <sub>` 뒤에 blueprint와 fence를 고정 순서로 붙인다.
+ * 표가 이 순서를 요구하므로 플래그를 명령마다 다르게 섞지 않는다.
+ *
+ * @param {string} sub - coordinate 서브커맨드
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {LedgerRef} ledger - fence
+ * @param {{ task?: string, item?: LedgerTask }} [taskOpts] - task 대상이면 id와 lease
+ * @param {string[]} [extra] - attempt 등 이미 채운 플래그
+ * @returns {string[]} argv
+ */
+function coordinateArgv(sub, blueprint, ledger, taskOpts, extra = []) {
+    const argv = ['bouncer', 'coordinate', sub, '--blueprint', blueprint, ...fenceArgs(ledger)];
+    if (taskOpts && taskOpts.task) {
+        argv.push('--task', taskOpts.task, ...leaseArgs(taskOpts.item));
+    }
+    argv.push(...extra);
+    return argv;
+}
+/**
+ * porcelain v1 경로. rename은 양쪽을 모두 dirty로 본다 — tasks.md만 남긴
+ * commit 직후 상태를 다른 경로가 가리면 report가 되면 안 된다.
+ *
+ * @param {string} text - `git status --porcelain=v1` 원문
+ * @returns {string[]} 상대 경로
+ */
+function dirtyPaths(text) {
+    const paths = [];
+    for (const line of text.split('\n')) {
+        if (!line)
+            continue;
+        const rest = line.slice(3);
+        const parts = rest.includes(' -> ') ? rest.split(' -> ') : [rest];
+        for (const part of parts) {
+            const trimmed = part.trim();
+            if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+                try {
+                    paths.push(JSON.parse(trimmed));
+                }
+                catch (_error) {
+                    // 잘못된 따옴표는 원문 그대로 비교한다. 경로를 추측해 지우면 mismatch를 놓친다.
+                    paths.push(trimmed);
+                }
+            }
+            else {
+                paths.push(trimmed.replaceAll('\\', '/'));
+            }
+        }
+    }
+    return paths;
+}
+/**
+ * 이 task의 tasks.md만 dirty인지. commit이 SHA를 그 파일에만 쓰므로 그 한
+ * 경로의 변경은 report의 정상 잔여물이다.
+ *
+ * @param {string[]} paths - porcelain 경로
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {string} taskId - 세 자리 id
+ * @returns {boolean} tasks.md 외 dirty가 있으면 false
+ */
+function onlyTaskBriefDirty(paths, blueprint, taskId) {
+    const allowed = `${blueprint.replaceAll('\\', '/')}/tasks/${taskId}/tasks.md`;
+    return paths.every((rel) => rel.replaceAll('\\', '/') === allowed);
+}
+/**
+ * 문서 bouncer.status. 파일 부재는 미완으로 본다 — 없는 증적을 통과로 꾸미지 않는다.
+ *
+ * @param {string} root - worker 또는 integration
+ * @param {string} rel - 문서 상대 경로
+ * @returns {unknown} status 또는 undefined
+ */
+function bouncerStatus(root, rel) {
+    const block = readBouncerBlock(path.join(root, rel));
+    return block ? block.status : undefined;
+}
+/**
+ * root review.md에 주어진 mode의 라운드가 있는지 tolerant 정책으로 읽는다. 문서 부재·frontmatter
+ * 없음·깨진 YAML·`rounds`가 배열이 아니면 없음으로 본다 — 판독 불가를 예외로 올리면 final_review
+ * 분기가 막히고, 있음으로 꾸미면 delta를 잘못 연다. 표식 blueprint는 delta 한 번으로 끝나므로
+ * delta 뒤 미accepted를 blocked로 가르는 기준이기도 하다.
+ *
+ * @param {string} integrationPath - integration worktree
+ * @param {string} blueprint - blueprint 상대 경로
+ * @param {'discovery' | 'delta'} mode - 찾을 라운드 mode
+ * @returns {boolean} 해당 mode 라운드가 있으면 true
+ */
+function rootReviewHasRoundTolerant(integrationPath, blueprint, mode) {
+    return reviewRoundExists({ file: path.join(integrationPath, blueprint, 'review.md'), error_policy: 'tolerant' }, mode);
+}
+const rootReviewHasDiscoveryRound = (integrationPath, blueprint) => (rootReviewHasRoundTolerant(integrationPath, blueprint, 'discovery'));
+const rootReviewHasDeltaRound = (integrationPath, blueprint) => (rootReviewHasRoundTolerant(integrationPath, blueprint, 'delta'));
+/**
+ * checkpoint.ledger를 붙이고 blocked면 힌트를 채운다.
+ *
+ * @param {Built} body - action 판정
+ * @param {string} cwd - argv 실행 cwd
+ * @param {LedgerRef} ledgerRef - 읽기 bytes의 fence
+ * @returns {NextOk} 성공 응답
+ */
+function succeed(body, cwd, ledgerRef) {
+    const result = { ok: true, checkpoint: { ledger: ledgerRef }, ...body, cwd };
+    if (result.action === 'blocked' && typeof result.reason === 'string') {
+        const hint = hintFor(result.reason);
+        // 호출자가 상황별 문구를 실어 보내면(brief 표식의 final-review-blocked) 그대로 둔다.
+        result.cause = result.cause ?? hint.cause;
+        result.next = result.next ?? hint.next;
+    }
+    return result;
+}
+/**
+ * 원장과 worker 문서를 읽어 다음에 실행할 행동 하나와 채운 argv를 돌려준다.
+ * 잠금·원장 쓰기·worktree 쓰기는 하지 않는다. status와 같이 integration cwd에서
+ * 읽고, 응답 cwd만 worker일 수 있다. 판단·worker action이면 플러그인 계약 카드를 `card`로 함께 싣는다.
+ *
+ * @param {object} opts - 판정 입력
+ * @param {string} opts.repoRoot - 메인 체크아웃
+ * @param {string} opts.blueprint - blueprint 상대 경로
+ * @param {string} opts.cwd - 호출 cwd. integration worktree여야 한다
+ * @param {string} [opts.task] - 있으면 task 범위
+ * @param {{ execFileSync?: Exec, readCard?: (id: CardId) => string, readEvidence?: ReadEvidence }} [opts.deps]
+ *   git·카드·증거 읽기 주입(테스트 seam)
+ * @returns {NextOk | NextErr} 결정(카드 대상이면 card 포함) 또는 즉시 거절
+ */
+function coordinateNext(opts) {
+    const readCard = (opts.deps && opts.deps.readCard) || readPluginCard;
+    return attachCard(decideNext(opts), readCard);
+}
+/**
+ * 원장과 worker 문서를 읽어 다음 행동 하나를 정한다. 카드 첨부 전 단계다.
+ *
+ * @param {object} opts - coordinateNext와 같은 입력
+ * @param {string} opts.repoRoot - 메인 체크아웃
+ * @param {string} opts.blueprint - blueprint 상대 경로
+ * @param {string} opts.cwd - 호출 cwd. integration worktree여야 한다
+ * @param {string} [opts.task] - 있으면 task 범위
+ * @param {{ execFileSync?: Exec, readEvidence?: ReadEvidence }} [opts.deps] - git·증거 읽기 주입
+ * @returns {NextOk | NextErr} 결정 또는 즉시 거절
+ */
+function decideNext(opts) {
+    const { repoRoot, blueprint, cwd, task } = opts;
+    const exec = (opts.deps && opts.deps.execFileSync) || realExecFileSync;
+    const readEvidence = (opts.deps && opts.deps.readEvidence) || readEvidenceFile;
+    // 1. status와 같은 원장 읽기 순서. 쓰기는 이 함수에 없다.
+    const main = runtimePaths({ repoRoot, execFileSync: exec });
+    if (main.unavailable)
+        return fail('non-git-root');
+    const integration = coordinatorPathsFor({ repoRoot, blueprint });
+    if (!registeredIntegration(exec, repoRoot, integration.integrationPath)) {
+        return fail('unassigned-integration-worktree');
+    }
+    const loaded = loadLedgerBytes(integration.ledgerFile);
+    if (!loaded)
+        return fail('missing-ledger');
+    const leaseShape = assertLeaseShape(loaded.ledger);
+    if (!leaseShape.ok)
+        return fail(leaseShape.reason);
+    ensureIntegrationCwd(repoRoot, blueprint, cwd);
+    const ledger = loaded.ledger;
+    // 분리된 실행은 다음 행동을 정하지 않는다(task 범위 포함). finalize 또는 새 계획으로 안내한다.
+    if (ledger.status === 'detached')
+        return fail('run-detached');
+    const checkpoint = projectCheckpoint(loaded.ledger, integration.ledgerFile, loaded.bytes);
+    const ledgerRef = checkpoint.ledger;
+    const integrationCwd = integration.integrationPath;
+    if (task !== undefined && task !== '') {
+        return taskNext({
+            repoRoot, blueprint, task, exec, ledger, ledgerRef, checkpoint, integrationCwd, integration,
+            readEvidence,
+        });
+    }
+    return blueprintNext({
+        blueprint, exec, ledger, ledgerRef, checkpoint, integrationCwd, readEvidence,
+    });
+}
+/**
+ * prepare를 내기 직전에, 이 coordinator 세션을 여기서 끊어야 하는지 원장 기록으로 판정한다.
+ * 한 세션이 직렬·무예외 wave를 이어 처리해 재기동 고정비를 줄이되, 상한에 닿았거나 예외·
+ * 병렬 wave가 끼면 새 세션(깨끗한 컨텍스트)에서 판단하게 하려는 경계다.
+ *
+ * 세션 경계는 `coordinate session-open`이 남긴 마지막 `session` 결정이고, 없으면 원장
+ * 처음부터를 한 세션으로 본다. wave 수는 그 뒤의 `fanin` 결정 수다(원장에 wave id가 없다).
+ * 읽기 전용이다.
+ *
+ * @param {Ledger} ledger - 원장 스냅샷
+ * @param {string[]} ready - checkpoint.ready(pending 후보 wave)
+ * @param {string} integrationCwd - 설정을 읽을 integration 절대 경로
+ * @returns {YieldReason | null} 끊어야 하는 사유. 이어 가도 되면 null
+ */
+function sessionYieldReason(ledger, ready, integrationCwd) {
+    // 1. verification 노드만 남은 wave는 세션 상한과 무관하게 이어 간다. 이 노드는 새 commit
+    //    wave가 아니라 마감 검증이라, 여기서 끊으면 세션만 하나 더 늘어난다.
+    const commitReady = ready.filter((id) => {
+        const item = ledger.tasks.find((candidate) => candidate.id === id);
+        return item !== undefined && item.execution_kind !== 'verification';
+    });
+    if (commitReady.length === 0)
+        return null;
+    const decisions = ledger.decisions || [];
+    let sessionAt = -1;
+    decisions.forEach((entry, index) => {
+        if (entry && entry.kind === 'session')
+            sessionAt = index;
+    });
+    const faninAt = [];
+    decisions.forEach((entry, index) => {
+        if (index > sessionAt && entry && entry.kind === 'fanin')
+            faninAt.push(index);
+    });
+    // 2. 이번 세션에서 아직 wave를 하나도 못 돌렸으면 끊을 이유가 없다. 끊으면 새 세션도
+    //    같은 자리에서 다시 yield해 진행이 멈춘다.
+    if (faninAt.length === 0)
+        return null;
+    // 3. 설정이 invalid면 상한 1로 접는다. 잘못된 설정이 세션을 늘리지 못하게 하고, 거절은
+    //    worktree를 만들기 전 prepare가 맡는다.
+    const policy = configMod.readWavesPerSession(integrationCwd);
+    const cap = policy.ok ? policy.cap : 1;
+    if (faninAt.length >= cap)
+        return 'session-wave-cap';
+    // 4. 예외 창은 직전 wave의 fanin(없으면 세션 시작) 뒤 전부다. 이번 wave 안에서 생긴 repair·
+    //    revoke·비수락 report가 새 세션의 깨끗한 판단을 받게 한다. 그 이전 wave의 예외는 이미
+    //    처리된 것이라 세지 않는다.
+    const windowStart = faninAt.length >= 2 ? faninAt[faninAt.length - 2] + 1 : sessionAt + 1;
+    if (decisions.slice(windowStart).some((entry) => driveMetrics.isException(entry))) {
+        return 'wave-exception';
+    }
+    // 5. 병렬 wave는 worker 여럿의 보고가 한꺼번에 와서 컨텍스트가 빠르게 찬다.
+    if (commitReady.length >= 2)
+        return 'parallel-wave';
+    return null;
+}
+/**
+ * blueprint 범위 표. 위에서 처음 맞는 행만 쓴다.
+ *
+ * @param {object} ctx - 읽기 스냅샷
+ * @param {string} ctx.blueprint - blueprint 경로
+ * @param {Exec} ctx.exec - git
+ * @param {Ledger} ctx.ledger - 원장
+ * @param {LedgerRef} ctx.ledgerRef - fence
+ * @param {{ ready: string[] }} ctx.checkpoint - status checkpoint의 ready wave
+ * @param {string} ctx.integrationCwd - integration 절대 경로
+ * @param {ReadEvidence} ctx.readEvidence - 증거 파일 읽기 seam
+ * @returns {NextOk | NextErr} 판정
+ */
+function blueprintNext(ctx) {
+    const { blueprint, exec, ledger, ledgerRef, checkpoint, integrationCwd, readEvidence } = ctx;
+    const ok = (body) => succeed(body, body.cwd, ledgerRef);
+    if (ledger.status === 'partial_closed') {
+        return ok({
+            scope: 'blueprint', action: 'blocked', reason: 'partial-closed', cwd: integrationCwd,
+        });
+    }
+    // light 승격 정지는 repair 한도와 별개다. prepare/drive로 내려가기 전에 막아
+    // 정지 뒤 inline implement가 다시 열리지 않게 한다. hint는 COORDINATE_FAILURE_HINTS.
+    if (ledger.status === 'promotion_stopped') {
+        return ok({
+            scope: 'blueprint', action: 'blocked', reason: 'promotion-stopped', cwd: integrationCwd,
+        });
+    }
+    if (ledger.status === 'awaiting_confirmation') {
+        return ok({
+            scope: 'blueprint', action: 'blocked', reason: 'repair-wave-limit', cwd: integrationCwd,
+        });
+    }
+    const failedId = ledger.terminalFailure && ledger.terminalFailure.task;
+    if (failedId) {
+        const failed = ledger.tasks.find((item) => item.id === failedId);
+        // 입증된 범위 밖 분류가 있으면 terminal 실패는 blocked가 아니라 아래 완료 판정으로 넘어간다.
+        // 분류가 없거나 stale이면(소스 변경·identity 불일치·미완성) 기존 blocked를 그대로 유지한다.
+        if (failed && failed.execution_kind === 'verification' && failed.status === 'verifying'
+            && (0, execution_contracts_1.validOutsideScope)(ledger, failed.id) === null) {
+            const blocked = ok({
+                scope: 'blueprint', action: 'blocked', reason: 'terminal-verification-failed',
+                cwd: integrationCwd,
+            });
+            return attachTerminalVerificationEvidence(blocked, integrationCwd, blueprint, failed.id, readEvidence);
+        }
+    }
+    if (ledger.fanin != null) {
+        return ok({
+            scope: 'blueprint', action: 'integrate', cwd: integrationCwd,
+            argv: coordinateArgv('integrate', blueprint, ledgerRef),
+        });
+    }
+    const prepared = ledger.tasks.filter((item) => item.status === 'prepared'
+        && item.execution_kind !== 'verification');
+    if (prepared.length > 0) {
+        return ok({
+            scope: 'blueprint', action: 'drive_tasks', cwd: integrationCwd,
+            task_ids: prepared.map((item) => item.id),
+        });
+    }
+    const recorded = ledger.tasks.some((item) => item.status === 'recorded'
+        && item.execution_kind !== 'verification');
+    if (recorded) {
+        return ok({
+            scope: 'blueprint', action: 'integrate', cwd: integrationCwd,
+            argv: coordinateArgv('integrate', blueprint, ledgerRef),
+        });
+    }
+    // checkpoint.ready는 pending 후보다. verification node는 prepare가 status를
+    // ready로 올린 뒤에만 integrate가 받아 주므로, 여기를 status ready/verifying으로
+    // 본다. pending verification은 아래 prepare 행이 연다.
+    const verificationLive = ledger.tasks.find((item) => item.execution_kind === 'verification'
+        && (item.status === 'ready'
+            || (item.status === 'verifying'
+                && !(ledger.terminalFailure && ledger.terminalFailure.task === item.id))));
+    if (verificationLive) {
+        return ok({
+            scope: 'blueprint', action: 'verification_node', cwd: integrationCwd, task: verificationLive.id,
+            argv: coordinateArgv('integrate', blueprint, ledgerRef, {
+                task: verificationLive.id, item: verificationLive,
+            }),
+        });
+    }
+    if (checkpoint.ready.length > 0) {
+        const yieldReason = sessionYieldReason(ledger, checkpoint.ready, integrationCwd);
+        if (yieldReason !== null) {
+            return ok({
+                scope: 'blueprint', action: 'yield', reason: yieldReason, cwd: integrationCwd,
+            });
+        }
+        return ok({
+            scope: 'blueprint', action: 'prepare', cwd: integrationCwd,
+            argv: coordinateArgv('prepare', blueprint, ledgerRef),
+        });
+    }
+    // 완료는 전부 integrated이거나, 남은 하나가 입증된 범위 밖 terminal 실패일 때다. 후자는 성공으로
+    // 바꾸지 않고 payload.outside_scope로 실패 사실을 흘려 보낸다(passed·integrated로 취급하지 않는다).
+    const outsideScope = ledger.tasks
+        .map((item) => (item.status === 'integrated' ? null : (0, execution_contracts_1.validOutsideScope)(ledger, item.id)))
+        .find((entry) => entry !== null) ?? null;
+    const allIntegrated = ledger.tasks.length > 0
+        && ledger.tasks.every((item) => item.status === 'integrated'
+            || (outsideScope !== null && (0, execution_contracts_1.validOutsideScope)(ledger, item.id) !== null));
+    const completionPayload = outsideScope !== null
+        ? { payload: { outside_scope: outsideScope, failed_task: ledger.terminalFailure?.task } }
+        : {};
+    if (allIntegrated && isBlueprintReviewModeAt(integrationCwd, blueprint)) {
+        const rootReview = bouncerStatus(integrationCwd, `${blueprint.replaceAll('\\', '/')}/review.md`);
+        if (rootReview !== 'accepted') {
+            const head = typeof ledger.integrationHead === 'string'
+                ? ledger.integrationHead
+                : git(exec, integrationCwd, ['rev-parse', 'HEAD']);
+            const base = typeof ledger.base === 'string' ? ledger.base : head;
+            // 최종 리뷰는 discovery 한 라운드로 끝난다. discovery가 저장됐는데 accepted가 아니면
+            // delta·repair·supplement로 되돌리지 않고 사용자 결정까지 멈춘다. 새 review status를
+            // 만들지 않으려고 기존 신호(문서 status requested, open finding)를 그대로 blocked로
+            // 읽는다. 저장된 과거 delta 이력은 읽기만 하고 여기서 새 delta를 만들지 않는다.
+            const contract = reviewContractAt(integrationCwd, blueprint);
+            if (contract === null) {
+                return ok({
+                    scope: 'blueprint', action: 'blocked', reason: schema.REVIEW_CONTRACT_INVALID_REASON, cwd: integrationCwd,
+                });
+            }
+            if (rootReviewHasDiscoveryRound(integrationCwd, blueprint)) {
+                if (contract !== 'brief') {
+                    return ok({
+                        scope: 'blueprint', action: 'blocked', reason: 'final-review-blocked', cwd: integrationCwd,
+                    });
+                }
+                // brief 표식은 discovery 뒤 리뷰 원인 repair 한 번과 그 뒤 delta 한 번을 허용한다. repair와
+                // terminal 재검증이 끝나(allIntegrated) 여기 도달했고 delta가 아직 없으면 delta를 연다.
+                const repaired = hasReviewRepairDecision(ledger.decisions);
+                if (repaired && !rootReviewHasDeltaRound(integrationCwd, blueprint)) {
+                    return ok({
+                        scope: 'blueprint', action: 'final_review', cwd: integrationCwd,
+                        argv: [
+                            'bouncer', 'review-dispatch', 'execute', '--blueprint', blueprint,
+                            '--base', base, '--head', head, '--mode', 'delta',
+                        ],
+                        judge: { kind: 'review-round', fields: [] },
+                        ...completionPayload,
+                    });
+                }
+                return ok({
+                    scope: 'blueprint', action: 'blocked', reason: 'final-review-blocked', cwd: integrationCwd,
+                    cause: repaired
+                        ? 'The blueprint final review used its discovery round, the one review repair, and the delta round, '
+                            + 'and the root review is not accepted.'
+                        : 'The blueprint final review recorded its discovery round, the root review is not accepted, '
+                            + 'and no review repair has been opened yet.',
+                    next: repaired
+                        ? 'Stop: the one review repair and delta are used. Show the open findings to the user and wait for their '
+                            + 'decision (note + deferred, or accepted-risk consent); do not open another repair or round.'
+                        : 'If an open must_fix is a brief violation, open the one repair with `bouncer coordinate repair '
+                            + '--review-finding`; otherwise show the open findings to the user and wait for their decision '
+                            + '(note + deferred, or accepted-risk consent).',
+                });
+            }
+            // discovery 전 최신 supplement 결정이 이 분기를 좌우한다. pending이면 implementer가
+            // 테스트를 보완해야 하고, verified면 보완 뒤 한 번뿐인 discovery 라운드로 간다.
+            const supplement = [...(ledger.decisions || [])].reverse()
+                .find((entry) => entry && entry.kind === 'supplement');
+            if (supplement && supplement.outcome === 'pending') {
+                return ok({
+                    scope: 'blueprint', action: 'supplement', cwd: integrationCwd,
+                    payload: { paths: supplement.paths || [], findings: supplement.findings || [] },
+                });
+            }
+            return ok({
+                scope: 'blueprint', action: 'final_review', cwd: integrationCwd,
+                argv: [
+                    'bouncer', 'review-dispatch', 'execute', '--blueprint', blueprint,
+                    '--base', base, '--head', head,
+                ],
+                judge: { kind: 'review-round', fields: [] },
+                ...completionPayload,
+            });
+        }
+    }
+    if (allIntegrated) {
+        return ok({ scope: 'blueprint', action: 'done', cwd: integrationCwd, ...completionPayload });
+    }
+    return ok({
+        scope: 'blueprint', action: 'blocked', reason: 'no-ready-task', cwd: integrationCwd,
+    });
+}
+/**
+ * 현재 attempt의 implementer 보고 파일이 이미 있는지 읽기만으로 판정한다.
+ * 파일이 있고 비어 있지 않으며 `## Brief revision`의 `attempt:` 줄이 현재 attempt와 같을 때만 참이다.
+ * 기준(HEAD·porcelain)은 dirty 경로 목록이라 내용 변화를 못 보므로, rework 재시도가 같은
+ * 기준에서 끝나도 implement가 반복되지 않게 하는 보조 신호다.
+ *
+ * @param {string} workerPath - 보고 파일 경로 계산에 쓰는 worker cwd
+ * @param {string} task - task 번호(3자리)
+ * @param {number} attempt - 원장 dispatch의 현재 attempt
+ * @returns {boolean} 현재 attempt 보고가 있으면 true. 없음·빈 파일·읽기 오류·attempt 불일치는 false
+ */
+function currentAttemptReportExists(workerPath, task, attempt) {
+    let text;
+    try {
+        text = fs.readFileSync(reportPathFor(workerPath, task, attempt), 'utf8');
+    }
+    catch (_error) {
+        // 읽기 오류는 모두 "보고 없음"으로 접는다. 판정을 못 하면 implement로 남는 쪽이
+        // 보수적이고(보고를 건너뛰어 미완성 구현을 verify로 넘기지 않는다), next는 읽기 전용이라
+        // 오류를 숨겨도 상태가 바뀌지 않는다.
+        return false;
+    }
+    const match = /^attempt:\s*(\d+)\s*$/m.exec(text);
+    return Boolean(match) && Number(match[1]) === attempt;
+}
+/**
+ * task 범위. verification --task는 즉시 거절하고, prepared가 아닌 상태는 none이다.
+ * reported `scope_revision`은 brief hash가 보고 때와 같으면 revise, 다르면
+ * 개정이 반영된 것으로 보고 재디스패치한다. 판단·worker 행동에는
+ * `attachJudgeContext`로 `payload.report`·`evidence`를 붙인다.
+ *
+ * @param {object} ctx - 읽기 스냅샷
+ * @param {string} ctx.repoRoot - 메인 루트
+ * @param {string} ctx.blueprint - blueprint 경로
+ * @param {string} ctx.task - --task 값
+ * @param {Exec} ctx.exec - git
+ * @param {Ledger} ctx.ledger - 원장
+ * @param {LedgerRef} ctx.ledgerRef - fence
+ * @param {{ ready: string[] }} ctx.checkpoint - unused, 시그니처 대칭
+ * @param {string} ctx.integrationCwd - integration
+ * @param {{ workerPath?: string }} ctx.integration - coordinatorPaths는 호출부에서 다시 계산
+ * @param {ReadEvidence} ctx.readEvidence - 증거 파일 읽기 seam
+ * @returns {NextOk | NextErr} 판정
+ */
+function taskNext(ctx) {
+    const { repoRoot, blueprint, task, exec, ledger, ledgerRef, integrationCwd, readEvidence } = ctx;
+    if (!/^\d{3}$/.test(task))
+        return fail('task-required');
+    const item = ledger.tasks.find((entry) => entry.id === task);
+    if (!item)
+        return fail('task-outside-blueprint');
+    if (item.execution_kind === 'verification')
+        return fail('verification-task-uses-blueprint-next');
+    const worker = coordinatorPathsFor({ repoRoot, blueprint, task }).workerPath;
+    const cwd = item.workerPath || worker;
+    const judgeCtx = {
+        lastReport: lastReportedOutcome(item),
+        workerPath: cwd,
+        candidates: defaultEvidenceCandidates(cwd, blueprint, task, item.dispatch?.attempt),
+        readEvidence,
+    };
+    // 성공 응답을 만든 뒤 판단·worker 행동에만 report/evidence를 붙인다. blocked·none·
+    // commit·verify는 judge/implement가 아니라서 attachJudgeContext가 no-op이다.
+    const ok = (body) => attachJudgeContext(succeed({ ...body, task }, body.cwd, ledgerRef), judgeCtx);
+    const status = item.status || 'pending';
+    if (status === 'recorded' || status === 'integrated' || status === 'pending' || status === 'ready') {
+        return ok({
+            scope: 'task', action: 'none', reason: status, cwd,
+        });
+    }
+    if (status !== 'prepared') {
+        return ok({
+            scope: 'task', action: 'blocked', reason: 'commit-evidence-mismatch', cwd,
+        });
+    }
+    if (item.criticalRecovery && item.criticalRecovery.outcome === null) {
+        return ok({
+            scope: 'task', action: 'blocked', reason: 'critical-recovery-open', cwd,
+        });
+    }
+    if (!item.dispatch) {
+        return ok({
+            scope: 'task', action: 'dispatch', cwd,
+            argv: coordinateArgv('dispatch', blueprint, ledgerRef, { task, item }),
+            judge: { kind: 'intent-symbols', fields: [] },
+        });
+    }
+    if (item.dispatch.status === 'reported' && item.dispatch.outcome === 'accepted') {
+        return ok({
+            scope: 'task', action: 'record', cwd,
+            argv: coordinateArgv('record', blueprint, ledgerRef, { task, item }),
+            judge: { kind: 'record-decision', fields: ['--decision'] },
+        });
+    }
+    if (item.dispatch.status === 'reported' && item.dispatch.outcome === 'scope_revision') {
+        let currentHash;
+        try {
+            currentHash = taskBriefHashOf(cwd, blueprint, task);
+        }
+        catch (error) {
+            // 문서 부재(ENOENT)만 흡수한다. hash를 못 읽으면 같은 brief라고 단정하지 않는다.
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (currentHash === item.dispatch.task_brief_hash) {
+            return ok({
+                scope: 'task', action: 'revise', cwd,
+                argv: coordinateArgv('revise', blueprint, ledgerRef, { task, item }),
+                judge: { kind: 'scope-revision', fields: ['--paths', '--reason'] },
+            });
+        }
+        // hash가 보고 때와 다르면 이미 개정이 반영된 상태다. 표의 말단
+        // commit-evidence-mismatch로 접으면 재디스패치가 막히므로 아래 reported
+        // 분기로 떨어뜨린다.
+    }
+    if (item.dispatch.status === 'reported' && item.dispatch.outcome === 'blocked') {
+        return ok({
+            scope: 'task', action: 'blocked', reason: 'task-reported-blocked', cwd,
+        });
+    }
+    if (item.dispatch.status === 'reported') {
+        return ok({
+            scope: 'task', action: 'dispatch', cwd,
+            argv: coordinateArgv('dispatch', blueprint, ledgerRef, { task, item }),
+            judge: { kind: 'intent-symbols', fields: [] },
+        });
+    }
+    if (item.dispatch.status !== 'active') {
+        return ok({
+            scope: 'task', action: 'blocked', reason: 'commit-evidence-mismatch', cwd,
+        });
+    }
+    const workerHead = git(exec, cwd, ['rev-parse', 'HEAD']);
+    const porcelainText = initialWorktreeState(exec, cwd);
+    // 현재 attempt 보고가 있으면 기준이 같아도 구현이 끝난 것으로 보고 아래 판정으로 내려간다.
+    const reportDone = currentAttemptReportExists(cwd, task, item.dispatch.attempt);
+    if (!reportDone && workerHead === item.dispatch.base_head
+        && porcelainText === item.dispatch.initial_worktree_state) {
+        // dispatch metadata만 싣는다. 직전 보고는 attachJudgeContext가 payload.report로 붙인다
+        // (옛 previous_outcome 키는 쓰지 않는다). light는 run 세션이 같은
+        // integration cwd에서 직접 구현하도록 inline을 켠다 — worker 위임이 아니다.
+        const payload = {
+            attempt: item.dispatch.attempt,
+            task_brief_hash: item.dispatch.task_brief_hash,
+            base_head: item.dispatch.base_head,
+            initial_worktree_state: item.dispatch.initial_worktree_state,
+            // dispatch가 발급한 것과 같은 경로: 원장 dispatch에서 다시 계산한다.
+            report_path: reportPathFor(item.workerPath || cwd, task, item.dispatch.attempt),
+        };
+        if (ledger.mode === 'light')
+            payload.inline = true;
+        // patch는 실행 권한을 넓히지 않는다. implementer는 현재 brief의 affected_paths 안에서만 재사용한다.
+        if (ledger.promoted_from?.patch)
+            payload.promoted_patch = ledger.promoted_from.patch;
+        return ok({ scope: 'task', action: 'implement', cwd, payload });
+    }
+    const tasksRel = `${blueprint.replaceAll('\\', '/')}/tasks/${task}/tasks.md`;
+    const verifyRel = `${blueprint.replaceAll('\\', '/')}/tasks/${task}/verification.md`;
+    const reviewRel = `${blueprint.replaceAll('\\', '/')}/tasks/${task}/review.md`;
+    const tasksBlock = readBouncerBlock(path.join(cwd, tasksRel));
+    const tasksStatus = tasksBlock ? tasksBlock.status : undefined;
+    const verifyStatus = bouncerStatus(cwd, verifyRel);
+    if (tasksStatus !== 'verified' || verifyStatus !== 'passed') {
+        return ok({
+            scope: 'task', action: 'verify', cwd,
+            argv: ['bouncer', 'validate', '--blueprint', blueprint, '--gate', 'execute'],
+        });
+    }
+    if (!isBlueprintReviewModeAt(integrationCwd, blueprint)
+        && bouncerStatus(cwd, reviewRel) !== 'accepted') {
+        let mergeBase;
+        try {
+            const integrationHead = typeof ledger.integrationHead === 'string'
+                ? ledger.integrationHead
+                : git(exec, integrationCwd, ['rev-parse', 'HEAD']);
+            mergeBase = git(exec, cwd, ['merge-base', integrationHead, workerHead]);
+        }
+        catch (_error) {
+            // merge-base 실패는 추측한 base를 넣지 않고 표의 말단 blocked로 접는다.
+            return ok({
+                scope: 'task', action: 'blocked', reason: 'commit-evidence-mismatch', cwd,
+            });
+        }
+        return ok({
+            scope: 'task', action: 'review', cwd,
+            argv: [
+                'bouncer', 'review-dispatch', 'execute', '--blueprint', blueprint, '--task', task,
+                '--base', mergeBase, '--head', workerHead,
+            ],
+            judge: { kind: 'review-round', fields: [] },
+        });
+    }
+    const stamped = tasksBlock ? tasksBlock.commit_sha : undefined;
+    if (stamped === undefined || stamped === null || stamped === '') {
+        return ok({
+            scope: 'task', action: 'commit', cwd,
+            argv: ['bouncer', 'commit', '--blueprint', blueprint, '--yes'],
+        });
+    }
+    // dispatch 때 이미 dirty였던 경로(커밋 전 plan 문서의 seed)는 이 attempt가 만든 변경이 아니다.
+    const baseline = new Set(dirtyPaths(item.dispatch.initial_worktree_state));
+    const extras = dirtyPaths(porcelainText).filter((rel) => !baseline.has(rel));
+    // stamp 규칙은 report·record가 거절에 쓰는 workerCommitEvidence와 같은 함수 하나를 쓴다.
+    // 그래야 next가 report를 권한 상태를 CLI가 거절하는 어긋남이 생기지 않는다.
+    const taskItem = item;
+    const evidence = workerCommitEvidence(exec, cwd, blueprint, taskItem, ledger);
+    if (evidence.ok && onlyTaskBriefDirty(extras, blueprint, task)) {
+        return ok({
+            scope: 'task', action: 'report', cwd,
+            argv: coordinateArgv('report', blueprint, ledgerRef, { task, item }, [
+                '--attempt', String(item.dispatch.attempt),
+                '--task-brief-hash', item.dispatch.task_brief_hash,
+            ]),
+            judge: {
+                kind: 'report-outcome',
+                fields: ['--outcome', '--summary'],
+                allowed: ['accepted', 'rework', 'scope_revision', 'task_change', 'blocked'],
+            },
+        });
+    }
+    if (!evidence.ok) {
+        // report·record는 이 두 거절에서 advance의 commit을 안내한다. 커밋할 scope 변경이 실제로
+        // 있을 때만 commit을 골라야 한다 — 변경이 없으면 `bouncer commit --yes`가 committed:false로
+        // 끝나 stamp를 못 고치므로 advance가 같은 commit 단계를 무한 반복한다.
+        const hasCommittable = evidence.reason === 'worker-scope-dirty'
+            || (evidence.reason === 'worker-commit-stamp-mismatch'
+                && workerScopeDirtyPaths(exec, cwd, blueprint, taskItem).length > 0);
+        if (hasCommittable) {
+            return ok({
+                scope: 'task', action: 'commit', cwd,
+                argv: ['bouncer', 'commit', '--blueprint', blueprint, '--yes'],
+            });
+        }
+        // 커밋으로 풀리지 않는 낡은 stamp는 원인 코드를 그대로 드러낸다.
+        if (evidence.reason === 'worker-commit-stamp-mismatch') {
+            return ok({
+                scope: 'task', action: 'blocked', reason: 'worker-commit-stamp-mismatch', cwd,
+            });
+        }
+    }
+    return ok({
+        scope: 'task', action: 'blocked', reason: 'commit-evidence-mismatch', cwd,
+    });
+}
+/**
+ * 원장 decisions의 마지막 kind:report를 복구한다. dispatch 객체는 재디스패치 때
+ * attempt·outcome을 덮어쓰므로, 판단 요약은 decisions 쪽만 믿을 수 있다.
+ *
+ * @param {LedgerTask} item - prepared task
+ * @returns {LastReport | undefined} 있으면 payload.report 후보
+ */
+function lastReportedOutcome(item) {
+    const decisions = Array.isArray(item.decisions) ? item.decisions : [];
+    for (let i = decisions.length - 1; i >= 0; i -= 1) {
+        const entry = decisions[i];
+        if (entry && entry.kind === 'report' && typeof entry.outcome === 'string'
+            && typeof entry.summary === 'string' && Number.isInteger(entry.attempt)) {
+            return { outcome: entry.outcome, summary: entry.summary, attempt: entry.attempt };
+        }
+    }
+    return undefined;
+}
+module.exports = { coordinateNext, NEXT_FAILURE_HINTS, attachJudgeContext };