@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/validate-docs.js

@@ -0,0 +1,302 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultStagedFiles = defaultStagedFiles;
+exports.readOptionalLeaf = readOptionalLeaf;
+exports.loadBlueprintDocs = loadBlueprintDocs;
+exports.resolveTaskUnit = resolveTaskUnit;
+exports.unitLeafRel = unitLeafRel;
+exports.blueprintDocsExist = blueprintDocsExist;
+exports.statusOf = statusOf;
+exports.requiredTaskLeaves = requiredTaskLeaves;
+exports.isBlueprintReviewMode = isBlueprintReviewMode;
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const paths = require("./paths");
+const { epicDirOf, toPosix } = paths;
+const verificationTarget = require("./verification-target");
+const { resolveVerificationTarget } = verificationTarget;
+const tasksDocs = require("./tasks-docs");
+const { listTasksDocs, TASK_UNIT_BASENAMES, taskExecutionKind, } = tasksDocs;
+function errorMessage(error) {
+    // catch 값은 unknown이다. 예전 e.message 접근을 유지해 primitive throw의
+    // 메시지는 undefined, null throw는 TypeError가 나게 둔다.
+    return error.message;
+}
+/**
+ * commit 게이트 G17용 스테이징 목록. throw하지 않는다 —
+ * git 실패·비저장소는 { ok:false }로 올려 게이트가 G17로 보고하게 한다.
+ */
+function defaultStagedFiles({ repoRoot }) {
+    try {
+        const out = execFileSync('git', ['diff', '--cached', '--name-only'], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+        });
+        return { ok: true, files: String(out).split('\n').filter(Boolean) };
+    }
+    catch (e) {
+        const reason = typeof e === 'object' && e !== null && 'message' in e && e.message
+            ? String(e.message)
+            : 'git-failed';
+        return { ok: false, reason };
+    }
+}
+// 묶음 leaf는 없어도 된다(S17이 따로 보고). 없으면 undefined를 돌려
+// 호출자가 대체 묶음으로 채우지 못하게 한다. 파싱 실패만 S0으로 남긴다.
+function readOptionalLeaf(repoRoot, rel, parseErrors) {
+    if (!rel)
+        return undefined;
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs))
+        return undefined;
+    try {
+        const { data, body } = readDoc(abs);
+        return { data, body, rel };
+    }
+    catch (e) {
+        parseErrors.push({ code: 'S0', message: errorMessage(e), file: rel });
+        return undefined;
+    }
+}
+/**
+ * context-review frontmatter의 closure_target_digest 모양을 검사한다. 부재(과거 문서)는 유효하고,
+ * 있으면 64 lowercase hex 문자열이어야 한다.
+ *
+ * @param {unknown} data - context-review.md frontmatter
+ * @returns {boolean} 부재이거나 올바른 hex이면 true
+ */
+function isValidClosureDigestField(data) {
+    const bouncer = data?.bouncer;
+    const meta = bouncer?.context_review;
+    if (meta === null || typeof meta !== 'object')
+        return true;
+    const digest = meta.closure_target_digest;
+    return digest === undefined || (typeof digest === 'string' && /^[0-9a-f]{64}$/.test(digest));
+}
+function loadBlueprintDocs({ repoRoot, blueprintDir }) {
+    const bp = toPosix(blueprintDir);
+    const tasksListing = listTasksDocs({ repoRoot, blueprintDir });
+    const rels = {
+        epicIndex: `${epicDirOf(bp)}/index.md`,
+        blueprintIndex: `${bp}/index.md`,
+        // finalize · execute G6 호환용 대표 경로(첫 task 문서).
+        // 묶음이 없을 때도 정본 레이아웃을 가리킨다 — 레거시 루트 basename은
+        // migrate task-layout 입력이고, validate는 S15로 거절한다(보고 경로로 쓰지 않음).
+        tasks: tasksListing.entries[0]
+            ? tasksListing.entries[0].rel
+            : `${bp}/tasks/001/tasks.md`,
+        verification: `${bp}/verification.md`,
+        review: `${bp}/review.md`,
+        explain: `${bp}/explain.md`,
+        // BP 단위 슬롯. context review 기록 검사가 이 문서를 판정한다. 슬롯이 없으면
+        // 문서가 로드되지 않아 checkStructural/S19가 이 파일을 보지 못한다.
+        contextReview: `${bp}/context-review.md`,
+    };
+    const docs = {};
+    const parseErrors = [];
+    const optionalKeys = [
+        'epicIndex', 'blueprintIndex', 'verification', 'review', 'explain', 'contextReview',
+    ];
+    for (const key of optionalKeys) {
+        const rel = rels[key];
+        const abs = path.join(repoRoot, rel);
+        if (fs.existsSync(abs)) {
+            try {
+                const { data, body } = readDoc(abs);
+                docs[key] = { data, body, rel };
+                // context_review.closure_target_digest는 64 lowercase hex만 구조상 유효하다. 틀린 값은
+                // 현재 내용으로 대체 인증하지 않고 구조 오류로 남겨 stale 값이 통과하지 못하게 한다.
+                if (key === 'contextReview' && !isValidClosureDigestField(data)) {
+                    parseErrors.push({
+                        code: 'S0',
+                        message: 'bouncer.context_review.closure_target_digest must be 64 lowercase hex',
+                        file: rel,
+                    });
+                }
+            }
+            catch (e) {
+                parseErrors.push({ code: 'S0', message: errorMessage(e), file: rel });
+            }
+        }
+    }
+    const tasksDocs = [];
+    for (const entry of tasksListing.entries) {
+        const abs = path.join(repoRoot, entry.rel);
+        if (!fs.existsSync(abs))
+            continue;
+        try {
+            const { data, body } = readDoc(abs);
+            tasksDocs.push({ data, body, rel: entry.rel });
+        }
+        catch (e) {
+            parseErrors.push({ code: 'S0', message: errorMessage(e), file: entry.rel });
+        }
+    }
+    if (tasksDocs.length > 0) {
+        // docs.tasks = 첫 문서 호환 필드. execute 게이트는 taskUnit만 본다.
+        docs.tasks = tasksDocs[0];
+        docs.tasksDocs = tasksDocs;
+    }
+    // 묶음별 파싱. 파일이 없으면 해당 leaf는 undefined — 대체 묶음으로 채우지 않는다.
+    const taskUnits = tasksListing.entries.map((entry) => ({
+        number: entry.number,
+        dir: entry.dir,
+        tasks: readOptionalLeaf(repoRoot, entry.tasks.rel, parseErrors),
+        verification: readOptionalLeaf(repoRoot, entry.verification.rel, parseErrors),
+        // verification node는 review 단계가 없다. listing의 review 경로는 S17이
+        // 열린 일반 bundle 완전성을 검사할 때만 쓰고, resolver payload에는
+        // verification.md를 review로 alias하지 않는다.
+        review: entry.executionKind === 'verification'
+            ? undefined
+            : readOptionalLeaf(repoRoot, entry.review?.rel, parseErrors),
+    }));
+    docs.taskUnits = taskUnits;
+    // validate.ts의 공통 S17 순회는 모든 종류에 존재하는 tasks/verification만
+    // 맡는다. commit 전용 review 누락은 execution kind를 아는 이 loader에서
+    // 추가해, verification entry에 가짜 review 경로를 싣지 않아도 기존 완전성
+    // 검사가 유지되게 한다. blueprint 리뷰 모드는 task review leaf를 요구하지
+    // 않는다 — 판정 근거는 루트 review.md 하나다.
+    const blueprintStatus = statusOf(docs.blueprintIndex);
+    const reviewMode = isBlueprintReviewMode(docs.blueprintIndex);
+    for (const entry of tasksListing.entries) {
+        for (const leaf of requiredTaskLeaves(blueprintStatus, entry.executionKind, reviewMode)) {
+            if (leaf !== 'review')
+                continue;
+            const rel = entry.review?.rel;
+            if (rel && !fs.existsSync(path.join(repoRoot, rel))) {
+                parseErrors.push({
+                    code: 'S17',
+                    message: `task unit ${entry.number} missing ${path.posix.basename(rel)}`,
+                    file: rel,
+                });
+            }
+        }
+    }
+    return { docs, rels, parseErrors, tasksListing };
+}
+/**
+ * execute / finalize 가 쓸 대상 묶음.
+ * verification-target과 같은 effective-task 해석: 매칭되면 그 엔트리만, 아니면
+ * 번호 순 첫 묶음. worker에서 lease를 확인하지 못하면 null — gate가 task
+ * 문서 부재로 실패하게 한다. 단위 테스트처럼 repoRoot가 없으면
+ * docs.tasks·verification·review 평탄 필드로 합성.
+ */
+function resolveTaskUnit(docs, { repoRoot, blueprintDir } = {}) {
+    if (repoRoot && blueprintDir) {
+        const { effectiveTask: effective, entries } = resolveVerificationTarget({ repoRoot, blueprintDir });
+        // worker fail-closed: 빈 entries로 flat docs에 떨어지면 G6 부재를 숨긴다.
+        if (effective && effective.source === null)
+            return null;
+        const entry = entries[0];
+        if (entry) {
+            const units = Array.isArray(docs.taskUnits) ? docs.taskUnits : [];
+            const match = units.find((u) => ((entry.dir && u.dir === entry.dir)
+                || (entry.number != null && u.number === entry.number)
+                || (u.tasks && entry.tasks && u.tasks.rel === entry.tasks.rel)));
+            if (match)
+                return match;
+            // listing에는 있으나 파싱 누락 — 빈 leaf로라도 경로를 유지해 G6 file을 살린다.
+            return {
+                number: entry.number ?? null,
+                dir: entry.dir ?? null,
+                tasks: undefined,
+                verification: undefined,
+                review: undefined,
+            };
+        }
+    }
+    if (docs.tasks || docs.verification || docs.review) {
+        const executionKind = docs.tasks ? taskExecutionKind(docs.tasks.data) : null;
+        return {
+            number: null,
+            dir: null,
+            tasks: docs.tasks,
+            verification: docs.verification,
+            review: executionKind === 'verification' ? undefined : docs.review,
+        };
+    }
+    return null;
+}
+/** 파일이 없을 때도 실패 file 경로를 묶음 안으로 고정한다. */
+function unitLeafRel(unit, leaf, fallbackRel) {
+    if (unit && leaf in unit) {
+        const leafDoc = unit[leaf];
+        if (leafDoc && leafDoc.rel)
+            return leafDoc.rel;
+    }
+    if (unit && unit.dir) {
+        const idx = ['tasks', 'verification', 'review'].indexOf(leaf);
+        if (idx >= 0)
+            return `${unit.dir}/${TASK_UNIT_BASENAMES[idx]}`;
+    }
+    return fallbackRel;
+}
+/**
+ * blueprint index가 blueprint 리뷰 모드인지 판정한다.
+ * 모드는 `bouncer.review_scope === 'blueprint'`일 때만 켠다. 필드 부재는
+ * 구형 계약(task별 리뷰)을 유지해야 하므로 모드가 아니다. 잘못된 값은
+ * 여기서 true로 접지 않는다 — 구조 층이 S31로 거절한다.
+ *
+ * @param {DocLeaf | undefined} blueprintIndex - blueprint `index.md` 문서. 없으면 모드가 아니다
+ * @returns {boolean} 모드이면 true, 아니면 false
+ */
+function isBlueprintReviewMode(blueprintIndex) {
+    if (!blueprintIndex)
+        return false;
+    const data = blueprintIndex.data;
+    const bouncer = data && data.bouncer;
+    return Boolean(bouncer && bouncer.review_scope === 'blueprint');
+}
+/**
+ * blueprint 상태에 따라 task 묶음에서 필수인 leaf를 돌려준다.
+ * closed는 finalize가 task leaf 전체를 지운 축약 레이아웃(필수 leaf 없음)을
+ * 허용한다. 실행 종류가 주어지지 않은 호출은 공통 leaf만 받고, commit
+ * 묶음만 review를 추가한다. verification 묶음에는 review leaf가 없다.
+ * blueprint 리뷰 모드에서는 commit 묶음도 review leaf를 요구하지 않는다.
+ *
+ * @param {unknown} status - blueprint index의 bouncer.status
+ * @param {'commit'|'verification'|null} [executionKind] task 실행 종류
+ * @param {boolean} [reviewMode] blueprint 리뷰 모드. true면 review leaf를 빼 준다
+ * @returns {Array<'tasks'|'verification'|'review'>} 필수 leaf 이름
+ */
+function requiredTaskLeaves(status, executionKind, reviewMode) {
+    // closed는 finalize가 일회성·검증 문서를 지운 뒤의 단말 상태다.
+    // 재개·task 추가가 없으므로 task leaf 부재를 구조 실패로 보지 않는다.
+    if (status === 'closed')
+        return [];
+    const common = ['tasks', 'verification'];
+    // 모드에서는 루트 review.md가 유일한 판정 근거다. task 묶음에 파일이
+    // 남아 있어도 S17로 요구하지 않는다.
+    if (reviewMode)
+        return common;
+    return executionKind === undefined || executionKind === 'verification'
+        ? common
+        : [...common, 'review'];
+}
+// 존재 여부만 확인: 가볍고 파싱하지 않아야 함. execute gate가 verification을
+// 다시 실행(verification.md를 다시 씀)하기 전에 호출되기 때문.
+function blueprintDocsExist({ repoRoot, blueprintDir }) {
+    const bp = toPosix(blueprintDir);
+    const tasksListing = listTasksDocs({ repoRoot, blueprintDir });
+    // tasks/<NNN>/가 있으면(축약으로 leaf가 비어도) 존재로 본다.
+    if (tasksListing.entries.length > 0)
+        return true;
+    // index.md만 있어도 존재로 본다 — imported exhibit처럼 task leaf가 없는
+    // blueprint도 S11이 아니라 이후 상태 검사(S18 등)로 보내야 한다.
+    // closed 축약은 index+explain만 남기므로 여기에도 걸린다.
+    // 루트 review.md는 존재 신호로 쓰지 않는다.
+    return ['index.md', 'explain.md']
+        .some((name) => fs.existsSync(path.join(repoRoot, bp, name)));
+}
+// 문서·bouncer 부재는 throw가 아니라 undefined. 호출자가 enum 문자열과
+// 비교하므로, 없는 문서는 자연히 status 검사에서 실패한다.
+function statusOf(doc) {
+    if (!doc)
+        return undefined;
+    const data = doc.data;
+    const bouncer = data && data.bouncer;
+    return bouncer ? bouncer.status : undefined;
+}

package/dist/validate-gates-finalize.js

@@ -0,0 +1,303 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkPartialCloseEvidence = checkPartialCloseEvidence;
+exports.checkPartialCloseGate = checkPartialCloseGate;
+exports.checkFinalizeGate = checkFinalizeGate;
+const fs = require('node:fs');
+const path = require('node:path');
+const paths = require("./paths");
+const { toPosix } = paths;
+const runtimeState = require("./runtime-state");
+const comprehension = require("./comprehension");
+const { computeDiffSha, EXPLAIN_SECTION_DEFS, resolveComprehensionEntry } = comprehension;
+const validateDocs = require("./validate-docs");
+const { statusOf, isBlueprintReviewMode } = validateDocs;
+const validateSections = require("./validate-sections");
+const { parseExplainSections, collectFindingFailures, EXECUTE_REVIEW_STATUS } = validateSections;
+const schema = require("./schema");
+const { executionKindOf, reviewContractOf } = schema;
+const execution_contracts_1 = require("./execution-contracts");
+const validate_gates_run_1 = require("./validate-gates-run");
+const validate_gates_shared_1 = require("./validate-gates-shared");
+/**
+ * partial close의 네 증적을 한 경계에서 판정한다. 일반 finalize와 섞지 않아
+ * 실패한 drive가 `closed` 성공 조건을 빌려 통과하지 못하게 한다.
+ *
+ * @param {object} input - 원장, main-worktree handoff reference, 사용자 확인
+ * @returns {{ok: true} | {ok: false, reason: string}} gate 결과
+ */
+function checkPartialCloseEvidence(input) {
+    if (!input.ledger || typeof input.ledger !== 'object'
+        || input.ledger.status !== 'awaiting_confirmation') {
+        return { ok: false, reason: 'partial-close-awaiting-confirmation-required' };
+    }
+    const checked = runtimeState.validateCoordinatorLedger({
+        ...(input.ledger && typeof input.ledger === 'object' ? input.ledger : {}),
+        status: 'partial_closed', userConfirmed: input.userConfirmed,
+    });
+    if (!checked.ok)
+        return checked;
+    const ledgerHandoff = input.ledger.handoff;
+    if (!input.handoff || JSON.stringify(input.handoff) !== JSON.stringify(ledgerHandoff)) {
+        return { ok: false, reason: 'partial-close-handoff-reference-required' };
+    }
+    return { ok: true };
+}
+/**
+ * checkout의 coordinator 원장에서 blueprint 경로만 읽는다. 파일이 없거나
+ * blueprint 문자열이 없으면 drive가 아니다. JSON 파손도 drive로 보지 않아
+ * stale git을 돌리지 않는다.
+ *
+ * @param {{ repoRoot: string }} opts - gate를 실행한 checkout 루트
+ * @returns {{ blueprint: string } | null} 원장 blueprint 또는 null
+ */
+function defaultReadCoordinatorLedger({ repoRoot }) {
+    const file = path.join(repoRoot, '.bouncer', 'runtime', 'coordinator.json');
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        // 원장 부재(ENOENT)만 흡수한다. 권한 오류를 "drive 아님"으로 접으면
+        // stale 검사를 건너뛰어 잘못된 마감을 통과시킬 수 있다.
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.blueprint !== 'string' || parsed.blueprint === '')
+            return null;
+        return { blueprint: parsed.blueprint };
+    }
+    catch (error) {
+        // JSON SyntaxError만 흡수한다. 원장을 읽을 수 없으면 drive 판정을
+        // 할 수 없고, 그 상태를 stale git 실패로 바꾸면 원인 코드가 갈라진다.
+        if (error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+/**
+ * finalize G21 — blueprint 루트 review.md만 판정한다. task 묶음 review는
+ * 읽지 않는다. 폐기된 G4/G9/G15를 재사용하지 않는다.
+ *
+ * @param {BlueprintDocs} docs - 로드된 문서
+ * @param {BlueprintRels} rels - 실패 file 경로
+ * @param {FailureEntry[]} failures - G21을 누적할 배열
+ * @param {GateContext} ctx - repoRoot·deps
+ * @returns {void}
+ */
+function checkG21(docs, rels, failures, ctx) {
+    const add = (message) => failures.push({
+        code: 'G21', message, file: rels.review,
+    });
+    const reviewDoc = docs.review;
+    if (!reviewDoc) {
+        add('blueprint review missing');
+        return;
+    }
+    const reviewBouncer = reviewDoc.data
+        && reviewDoc.data.bouncer;
+    const reviewMeta = reviewBouncer
+        ? reviewBouncer.review
+        : undefined;
+    // 루트 리뷰는 review.required: false로 면제하지 않는다. task G8과 달리
+    // blueprint 마감의 유일한 리뷰 증적이기 때문이다.
+    if (statusOf(reviewDoc) !== 'accepted') {
+        add('blueprint review not accepted');
+    }
+    const head = (0, validate_gates_shared_1.lastReviewHead)(reviewMeta && reviewMeta.rounds);
+    if (!head) {
+        add('blueprint review has no rounds');
+    }
+    // review_contract가 brief면 record와 같은 blueprint_brief 계약으로 판정한다. 허용 밖 값은 legacy로
+    // 접지 않고 collectFindingFailures 필터를 거치지 않는 직접 실패로 남겨, 마감이 조용히 통과하지 않게 한다.
+    const blueprintBouncer = docs.blueprintIndex && docs.blueprintIndex.data
+        ? docs.blueprintIndex.data.bouncer
+        : undefined;
+    const reviewContract = reviewContractOf(blueprintBouncer);
+    if (reviewContract === null)
+        add(schema.REVIEW_CONTRACT_INVALID_MESSAGE);
+    for (const message of collectFindingFailures({
+        body: reviewDoc.body,
+        findings: reviewMeta && reviewMeta.findings,
+        rounds: reviewMeta && reviewMeta.rounds,
+        sectionLabel: 'review.md',
+        findingLabel: 'review',
+        allowedStatuses: EXECUTE_REVIEW_STATUS,
+        reviewStatus: statusOf(reviewDoc),
+        // blueprint 최종 리뷰는 repair wave마다 delta를 기록하므로 전용 순서 계약을 쓴다.
+        roundScope: reviewContract === 'brief' ? 'blueprint_brief' : 'blueprint',
+    }).filter(validate_gates_shared_1.isBlockingReviewFailure)) {
+        // 형식 위반은 기록 시점이 거절하므로 실질 판정만 G21로 남긴다.
+        add(message);
+    }
+    if (!head)
+        return;
+    const repoRoot = ctx.repoRoot;
+    const deps = ctx.deps;
+    const readLedger = (deps && deps.readCoordinatorLedger) || defaultReadCoordinatorLedger;
+    if (typeof repoRoot !== 'string')
+        return;
+    const ledger = readLedger({ repoRoot });
+    if (!ledger)
+        return;
+    // 원장의 blueprint가 이 gate 대상과 같을 때만 drive다. 다른 drive의
+    // 원장이 checkout에 남아 있어도 stale git을 돌리지 않는다.
+    if (toPosix(ledger.blueprint) !== toPosix(ctx.blueprintDir || ''))
+        return;
+    const ancestor = (0, validate_gates_shared_1.gitExec)(repoRoot, ['merge-base', '--is-ancestor', head, 'HEAD'], deps && deps.exec);
+    if (ancestor.status !== 0 && ancestor.status !== 1) {
+        add(`blueprint review stale check failed (${(0, validate_gates_shared_1.firstStderrLine)(ancestor.stderr)})`);
+        return;
+    }
+    if (ancestor.status === 1) {
+        add('blueprint review is stale');
+        return;
+    }
+    const diff = (0, validate_gates_shared_1.gitExec)(repoRoot, ['diff', '--name-only', head, 'HEAD'], deps && deps.exec);
+    if (diff.status !== 0) {
+        add(`blueprint review stale check failed (${(0, validate_gates_shared_1.firstStderrLine)(diff.stderr)})`);
+        return;
+    }
+    const dirty = String(diff.stdout).split('\n').filter(Boolean)
+        .some((rel) => !toPosix(rel).startsWith('.bouncer/'));
+    if (dirty)
+        add('blueprint review is stale');
+}
+/**
+ * partial-close gate 판정. 실패 코드 G20과 reason 문자열은 분리 전과 같다.
+ *
+ * @param {GateStageCtx} stage - add 클로저와 partialClose 입력
+ * @returns {void}
+ */
+function checkPartialCloseGate(stage) {
+    const result = checkPartialCloseEvidence(stage.partialClose || {});
+    if (!result.ok)
+        stage.add('G20', result.reason, 'blueprintIndex');
+}
+/**
+ * finalize gate 판정. G 코드·메시지·순서는 분리 전과 같다.
+ *
+ * @param {GateStageCtx} stage - add 클로저와 문서 묶음
+ * @returns {void}
+ */
+function checkFinalizeGate(stage) {
+    const { add, docs, rels, failures } = stage;
+    const repoRoot = stage.repoRoot;
+    const blueprintDir = stage.blueprintDir;
+    const deps = stage.deps;
+    const ctx = (0, validate_gates_shared_1.toGateContext)(stage);
+    const tasksList = Array.isArray(docs.tasksDocs) && docs.tasksDocs.length > 0
+        ? docs.tasksDocs
+        : (docs.tasks ? [docs.tasks] : []);
+    const openIds = [];
+    // 입증된 범위 밖 terminal 실패는 integrated가 아니어도 닫힌 것으로 본다. 판정은 next·digest·
+    // finalize와 같은 validOutsideScope 하나를 쓰고, 문서가 verifying일 때만 적용해 pending/ready 같은
+    // 재작업 대기 문서가 분류 하나로 닫히지 않게 한다. 원장이 없거나(비-drive) 분류가 stale이면 null이라
+    // 기존 open-task 실패가 그대로 나온다. 통과 시 실패 사실이 사라지지 않도록 경고를 남긴다.
+    const ledgerFn = (deps && deps.coordinatorLedgerFor) || validate_gates_run_1.defaultCoordinatorLedgerFor;
+    let ledgerCache;
+    const taskIsOpen = (tasksDoc) => {
+        const data = (0, validate_gates_shared_1.asData)(tasksDoc);
+        const taskBouncer = data && data.bouncer;
+        const isTerminal = executionKindOf(taskBouncer) === 'verification';
+        const status = statusOf(tasksDoc);
+        if (status === (isTerminal ? 'integrated' : 'verified'))
+            return false;
+        if (!isTerminal || status !== 'verifying' || typeof repoRoot !== 'string'
+            || typeof blueprintDir !== 'string' || typeof taskBouncer?.id !== 'string')
+            return true;
+        if (ledgerCache === undefined)
+            ledgerCache = ledgerFn({ repoRoot, blueprint: blueprintDir });
+        const accepted = (0, execution_contracts_1.validOutsideScope)(ledgerCache, taskBouncer.id);
+        if (!accepted)
+            return true;
+        if (ctx && Array.isArray(ctx.warnings)) {
+            ctx.warnings.push({
+                code: 'G16',
+                message: `terminal verification ${taskBouncer.id} failed and is classified outside_scope: ${accepted.reason}`,
+                file: tasksDoc.rel || rels.tasks,
+            });
+        }
+        return false;
+    };
+    const openDocs = [];
+    for (const tasksDoc of tasksList) {
+        if (!taskIsOpen(tasksDoc))
+            continue;
+        openDocs.push(tasksDoc);
+        const data = (0, validate_gates_shared_1.asData)(tasksDoc);
+        const id = data && data.bouncer
+            ? data.bouncer.id
+            : undefined;
+        openIds.push(typeof id === 'string' && id ? id : '(unknown)');
+    }
+    if (openIds.length) {
+        // 열린 task id를 메시지에 담아 어느 묶음이 남았는지 바로 보이게 한다.
+        // 경고가 아니라 hard fail — 사용자가 넘길 수 없다.
+        const openDoc = openDocs[0];
+        failures.push({
+            code: 'G16',
+            message: `open tasks remain (not verified): ${openIds.join(', ')}`,
+            file: (openDoc && openDoc.rel) || rels.tasks,
+        });
+        return;
+    }
+    // G16 open-tasks 다음, Explain 앞. 모드가 아니면 루트 review.md가 있어도
+    // 구형 fixture의 G16 판정을 바꾸지 않는다.
+    if (isBlueprintReviewMode(docs.blueprintIndex)) {
+        checkG21(docs, rels, failures, ctx);
+    }
+    if (!docs.explain) {
+        add('G16', 'explain.md missing', 'explain');
+        return;
+    }
+    if (statusOf(docs.explain) !== 'published') {
+        add('G16', 'explain.status != published', 'explain');
+    }
+    const explainBody = typeof docs.explain.body === 'string' ? docs.explain.body : '';
+    const sections = parseExplainSections(explainBody);
+    const missing = EXPLAIN_SECTION_DEFS.filter((k) => !sections[k]);
+    if (missing.length) {
+        add('G16', `explain missing written sections: ${missing.join(', ')}`, 'explain');
+        return;
+    }
+    const explainData = (0, validate_gates_shared_1.asData)(docs.explain);
+    const bouncer = explainData && explainData.bouncer
+        ? explainData.bouncer
+        : {};
+    const comp = bouncer.comprehension;
+    // BP당 엔트리 하나(배열 마지막). task 번호 루프는 쓰지 않는다 —
+    // 0.7 다중 엔트리는 마지막만 보면 읽기 호환이 된다.
+    const found = resolveComprehensionEntry(comp);
+    // 기본 tsc(strict 꺼짐)는 `!found.ok`로 실패 분기를 좁히지 못한다.
+    if (found.ok === false) {
+        add('G16', found.reason === 'not-a-list'
+            ? 'explain comprehension must be a list of task entries'
+            : 'explain comprehension record missing', 'explain');
+        return;
+    }
+    // 계산 실패와 해시 불일치는 서로 다른 문자열 — 원인 분류가 메시지에 드러나야 한다.
+    const shaFn = (deps && deps.computeDiffSha) || computeDiffSha;
+    if (typeof repoRoot !== 'string') {
+        add('G16', 'explain diff_sha could not be computed (missing-repo)', 'explain');
+        return;
+    }
+    const computed = shaFn({
+        repoRoot,
+        base: found.entry.range_from,
+        exec: deps && deps.exec,
+    });
+    if (!computed || computed.ok !== true) {
+        const reason = computed && computed.reason ? computed.reason : 'exec-failed';
+        add('G16', `explain diff_sha could not be computed (${reason})`, 'explain');
+        return;
+    }
+    if (computed.sha !== String(found.entry.diff_sha).trim()) {
+        // 메시지에 range_from을 쓰지 않는다 — 실패 사유는 불일치뿐; 범위는 엔트리에 있다.
+        add('G16', 'explain diff_sha does not match range_from..HEAD', 'explain');
+    }
+    return;
+}