@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/validate-gates-run.js

@@ -0,0 +1,420 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkExecuteGate = checkExecuteGate;
+exports.checkCommitGate = checkCommitGate;
+exports.defaultCoordinatorLedgerFor = defaultCoordinatorLedgerFor;
+const fs = require('node:fs');
+const { createHash } = require('node:crypto');
+const canonicalJsonMod = require("./canonical-json");
+const { sha256Canonical } = canonicalJsonMod;
+const guards = require("./guards");
+const { isRecord } = guards;
+const scope = require("./scope");
+const { makeAllowed, isRuntimeArtifact, readCoordinatorLedger } = scope;
+const validateDocs = require("./validate-docs");
+const { defaultStagedFiles, resolveTaskUnit, unitLeafRel, statusOf, isBlueprintReviewMode } = validateDocs;
+const runtimeState = require("./runtime-state");
+const { verifyLedgerPathFor, readApprovalSnapshot } = runtimeState;
+const validateSections = require("./validate-sections");
+const { VERIFY_SECTION_DEFS, parseSections, collectFindingFailures, EXECUTE_REVIEW_STATUS } = validateSections;
+const schema = require("./schema");
+const { executionKindOf } = schema;
+const verification = require("./verification");
+const { computeSourceDigest } = verification;
+const approvalSnapshot = require("./approval-snapshot");
+const { computeApprovalDigest, diffApprovalParts } = approvalSnapshot;
+const validate_gates_shared_1 = require("./validate-gates-shared");
+/**
+ * Git common dir의 verify 원장을 읽는다. evidenceId가 있으면 v2 경로를 쓰고,
+ * 없으면 legacy(rel-only) 경로를 연다 — 구 원장 miss와 v2 hit 경계를 같게 유지한다.
+ *
+ * @param {{ repoRoot?: string, verificationRel?: string, evidenceId?: string, deps?: GateDeps }} opts
+ * @returns {VerifyLedgerRecord | null} 파싱된 원장. 부재·파손은 null, 비-Git은 unavailable
+ */
+function defaultReadVerifyLedger({ repoRoot, verificationRel, evidenceId, deps, }) {
+    const paths = verifyLedgerPathFor({
+        repoRoot: repoRoot,
+        verificationRel,
+        evidenceId,
+        // 경로 해석만 위임한다. ledger 파일 읽기는 아래 fsApi가 담당하므로
+        // GateDeps.fs(부분 InjectedFs)를 RuntimeDeps로 억지 대입하지 않는다.
+        deps: deps
+            ? { execFileSync: deps.execFileSync, platform: deps.platform }
+            : undefined,
+    });
+    if (paths.unavailable) {
+        return { unavailable: true, reason: paths.reason };
+    }
+    const fsApi = (deps && deps.fs) || fs;
+    if (!paths.ledgerFile || !fsApi.existsSync(paths.ledgerFile))
+        return null;
+    try {
+        const parsed = JSON.parse(fsApi.readFileSync(paths.ledgerFile, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch (_error) {
+        return null;
+    }
+}
+/**
+ * execute/commit G13 — verification.md 하네스 메타와 common-dir 원장을 대조한다.
+ * v2는 evidence_id·scope·reused lineage까지 맞아야 통과하고, 손기록 변조를 거절한다.
+ *
+ * @param {DocLeaf | undefined | null} verificationDoc - verification.md 문서
+ * @param {(code: string, message: string, leaf: string) => void} addUnit - 실패 누적
+ * @param {GateContext} ctx - repoRoot·deps
+ * @returns {void}
+ */
+function checkG13(verificationDoc, addUnit, ctx) {
+    if (!verificationDoc)
+        return;
+    const vbody = typeof verificationDoc.body === 'string' ? verificationDoc.body : '';
+    const vs = parseSections(vbody, VERIFY_SECTION_DEFS);
+    const missingV = ['command', 'evidence'].filter((k) => !vs[k]);
+    if (missingV.length) {
+        addUnit('G13', `verification.md missing body sections: ${missingV.join(', ')}`, 'verification');
+    }
+    const vBouncer = verificationDoc.data.bouncer;
+    const evidence = vBouncer && vBouncer.verification;
+    const scope = evidence && evidence.scope;
+    const validEvidence = evidence
+        && typeof evidence.command === 'string'
+        && evidence.command.trim()
+        && typeof evidence.ran_at === 'string'
+        && evidence.ran_at.trim()
+        && evidence.exit_code === 0
+        && typeof evidence.output_tail === 'string'
+        && typeof evidence.evidence_id === 'string'
+        && /^[a-f0-9]{64}$/.test(evidence.evidence_id)
+        && isRecord(evidence.identity)
+        && isRecord(scope)
+        && (scope.kind === 'task' || scope.kind === 'wave' || scope.kind === 'terminal')
+        && typeof scope.key === 'string'
+        && scope.key.trim()
+        && typeof evidence.reused === 'boolean'
+        && (evidence.reused === false
+            || (typeof evidence.reused_from === 'string' && /^[a-f0-9]{64}$/.test(evidence.reused_from)));
+    if (!validEvidence) {
+        addUnit('G13', 'verification.md missing successful harness verification metadata', 'verification');
+        return;
+    }
+    // evidence_id는 identity의 content-addressed 해시여야 한다. 원장과 숫자만
+    // 맞추고 identity를 손기록하면 다른 입력의 성공을 위조할 수 있다.
+    const expectedEvidenceId = sha256Canonical(evidence.identity);
+    if (evidence.evidence_id !== expectedEvidenceId) {
+        addUnit('G13', 'verification.md evidence_id does not match canonical identity hash', 'verification');
+        return;
+    }
+    if (!vs.command.includes(`\`${evidence.command}\``)
+        || !vs.evidence.includes('Exit code: 0')) {
+        addUnit('G13', 'verification.md body does not match harness verification metadata', 'verification');
+    }
+    // 프론트매터만 맞으면 에이전트 Write로 통과하던 구멍. 원장은 git common dir
+    // 아래 하네스 전용이라, 문서와 대조하지 않으면 `/bouncer-commit` 직접 호출도
+    // status: passed 손기록으로 열린다.
+    const deps = ctx && ctx.deps;
+    const reader = (deps && deps.readVerifyLedger) || defaultReadVerifyLedger;
+    const record = reader({
+        repoRoot: ctx && ctx.repoRoot,
+        verificationRel: verificationDoc.rel,
+        evidenceId: evidence.evidence_id,
+        deps,
+    });
+    if (record && record.unavailable) {
+        addUnit('G13', `verification.md verify ledger unavailable (${record.reason || 'Git common directory unavailable'})`, 'verification');
+        return;
+    }
+    if (!record) {
+        addUnit('G13', 'verification.md missing harness verify ledger record', 'verification');
+        return;
+    }
+    if (record.command !== evidence.command
+        || record.ran_at !== evidence.ran_at
+        || record.exit_code !== evidence.exit_code
+        || record.evidence_id !== evidence.evidence_id
+        || record.reused !== evidence.reused
+        || !(0, validate_gates_shared_1.sameCanonical)(record.identity, evidence.identity)
+        || !(0, validate_gates_shared_1.sameCanonical)(record.scope, evidence.scope)
+        || (evidence.reused
+            ? record.reused_from !== evidence.reused_from
+            : record.reused_from !== undefined && record.reused_from !== null)) {
+        addUnit('G13', 'verification.md harness metadata does not match verify ledger', 'verification');
+        return;
+    }
+    const outputSha = createHash('sha256').update(String(evidence.output_tail), 'utf8').digest('hex');
+    if (record.output_sha !== outputSha) {
+        addUnit('G13', 'verification.md output_tail does not match verify ledger output_sha', 'verification');
+    }
+}
+/**
+ * commit G23 — G13이 통과한 원장의 source_digest·identity.head를 현재
+ * checkout과 대조한다. 필드가 없는 구 원장과 repoRoot 비문자열은 건너뛰어
+ * 이 변경 전 증거가 execute 경로를 막지 않게 한다.
+ *
+ * @param {DocLeaf | undefined | null} verificationDoc - verification.md 문서
+ * @param {(code: string, message: string, leaf: string) => void} addUnit - 실패 누적
+ * @param {GateContext} ctx - repoRoot·deps
+ * @param {FailureEntry[]} failures - G13이 이미 있으면 대조하지 않는다
+ * @returns {void}
+ */
+function checkG23(verificationDoc, addUnit, ctx, failures) {
+    if (!verificationDoc)
+        return;
+    if (failures.some((entry) => entry.code === 'G13'))
+        return;
+    const repoRoot = ctx && ctx.repoRoot;
+    if (typeof repoRoot !== 'string')
+        return;
+    const deps = ctx && ctx.deps;
+    const reader = (deps && deps.readVerifyLedger) || defaultReadVerifyLedger;
+    const vBouncer = verificationDoc.data.bouncer;
+    const evidence = vBouncer && vBouncer.verification;
+    const record = reader({
+        repoRoot,
+        verificationRel: verificationDoc.rel,
+        evidenceId: evidence && typeof evidence.evidence_id === 'string' ? evidence.evidence_id : undefined,
+        deps,
+    });
+    if (!record || record.unavailable)
+        return;
+    if (typeof record.source_digest !== 'string')
+        return;
+    const identity = isRecord(record.identity) ? record.identity : undefined;
+    const recordedHead = identity && typeof identity.head === 'string' ? identity.head : '';
+    try {
+        const headResult = (0, validate_gates_shared_1.gitExec)(repoRoot, ['rev-parse', 'HEAD'], deps && deps.exec);
+        if (headResult.status !== 0) {
+            addUnit('G23', `verification freshness check failed (${(0, validate_gates_shared_1.firstStderrLine)(headResult.stderr) || 'git rev-parse HEAD failed'})`, 'verification');
+        }
+        else if (headResult.stdout.trim() !== recordedHead) {
+            addUnit('G23', 'verification evidence is stale: HEAD moved after verify', 'verification');
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        addUnit('G23', `verification freshness check failed (${message.split(/\r?\n/)[0] || 'HEAD check failed'})`, 'verification');
+    }
+    try {
+        const digestFn = (deps && typeof deps.sourceDigest === 'function')
+            ? deps.sourceDigest
+            : computeSourceDigest;
+        const currentDigest = digestFn(repoRoot);
+        if (currentDigest !== record.source_digest) {
+            addUnit('G23', 'verification evidence is stale: sources changed after verify', 'verification');
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        addUnit('G23', `verification freshness check failed (${message.split(/\r?\n/)[0] || 'source digest failed'})`, 'verification');
+    }
+}
+function defaultReadApprovalSnapshot({ repoRoot, blueprintDir }) {
+    return readApprovalSnapshot({ repoRoot, blueprintDir });
+}
+function defaultCoordinatorLedgerFor({ repoRoot, blueprint }) {
+    const result = readCoordinatorLedger({ repoRoot, blueprint });
+    if (result && result.ok === true)
+        return result.ledger;
+    return null;
+}
+/**
+ * execute·commit G24 — 활성화 시점 승인 digest와 현재 digest를 대조한다.
+ * 승인 파일이 없거나 coordinator 원장이 있으면 건너뛴다. 이 변경 전 활성화와
+ * coordinator가 `reviseTaskScope`로 범위를 고치는 경로를 G24로 막지 않기 위함이다.
+ *
+ * @param {FailureEntry[]} failures - G24를 누적할 배열
+ * @param {GateContext} ctx - repoRoot·blueprintDir·deps
+ * @param {BlueprintRels} rels - 실패 file 경로 (blueprint 단위라 blueprintIndex)
+ * @returns {void}
+ */
+function checkG24(failures, ctx, rels) {
+    const repoRoot = ctx && ctx.repoRoot;
+    if (typeof repoRoot !== 'string')
+        return;
+    const blueprintDir = ctx && ctx.blueprintDir;
+    if (typeof blueprintDir !== 'string')
+        return;
+    const deps = ctx && ctx.deps;
+    const ledgerFn = (deps && deps.coordinatorLedgerFor) || defaultCoordinatorLedgerFor;
+    const ledger = ledgerFn({ repoRoot, blueprint: blueprintDir });
+    if (ledger && typeof ledger === 'object')
+        return;
+    const reader = (deps && deps.readApprovalSnapshot) || defaultReadApprovalSnapshot;
+    const approval = reader({ repoRoot, blueprintDir });
+    if (approval == null)
+        return;
+    const file = rels.blueprintIndex;
+    if (approval.ok === false) {
+        failures.push({
+            code: 'G24',
+            message: `approval snapshot is unreadable (${approval.path})`,
+            file,
+        });
+        return;
+    }
+    const current = computeApprovalDigest({ repoRoot, blueprintDir });
+    if (current.digest === approval.snapshot.digest)
+        return;
+    const names = diffApprovalParts(approval.snapshot.parts, current.parts);
+    failures.push({
+        code: 'G24',
+        message: `approved scope changed after activation: ${names.join(', ')}`,
+        file,
+    });
+}
+/**
+ * execute gate 판정. G 코드·메시지·순서는 분리 전과 같다.
+ *
+ * @param {GateStageCtx} stage - add 클로저와 문서 묶음
+ * @returns {void}
+ */
+function checkExecuteGate(stage) {
+    const { docs, rels, failures } = stage;
+    const ctx = (0, validate_gates_shared_1.toGateContext)(stage);
+    // docs.tasks(첫 문서 호환 필드)는 쓰지 않는다 — 포인터 대상 묶음만 판정.
+    // ctx.taskUnit이 없으면 단위 테스트용으로 평탄 docs에서 합성.
+    const taskUnit = (ctx && ctx.taskUnit) || resolveTaskUnit(docs, {});
+    const tasksDoc = taskUnit && taskUnit.tasks;
+    const verificationDoc = taskUnit && taskUnit.verification;
+    const reviewDoc = taskUnit && taskUnit.review;
+    const tasksData = (0, validate_gates_shared_1.asData)(tasksDoc);
+    const tasksBouncer = tasksData && tasksData.bouncer;
+    const isVerificationTask = executionKindOf(tasksBouncer) === 'verification';
+    const addUnit = (code, message, leaf) => failures.push({
+        code,
+        message,
+        file: unitLeafRel(taskUnit, leaf, rels[leaf]),
+    });
+    const expectedTaskStatus = isVerificationTask ? 'integrated' : 'verified';
+    if (statusOf(tasksDoc) !== expectedTaskStatus) {
+        addUnit('G6', `tasks.status != ${expectedTaskStatus}`, 'tasks');
+    }
+    if (statusOf(verificationDoc) !== 'passed') {
+        addUnit('G7', 'verification.status != passed', 'verification');
+    }
+    const reviewBouncer = reviewDoc
+        ? reviewDoc.data.bouncer
+        : undefined;
+    const review = reviewBouncer ? reviewBouncer.review : undefined;
+    const reviewOk = statusOf(reviewDoc) === 'accepted' || (review && review.required === false);
+    const blueprintReviewMode = isBlueprintReviewMode(docs.blueprintIndex);
+    // 모드에서는 루트 리뷰만 본다. 남은 task review.md를 읽으면 G8/G14가
+    // 마감과 다른 문서를 근거로 실패한다.
+    if (!blueprintReviewMode && !isVerificationTask && !reviewOk) {
+        addUnit('G8', 'review not accepted and review.required != false', 'review');
+    }
+    checkG13(verificationDoc, addUnit, ctx);
+    const reviewMetaBouncer = reviewDoc
+        ? reviewDoc.data.bouncer
+        : undefined;
+    const reviewMeta = reviewMetaBouncer
+        ? reviewMetaBouncer.review
+        : undefined;
+    const reviewSkipped = reviewMeta && reviewMeta.required === false;
+    // G14는 execute status(deferred 포함)를 넘겨 실질 판정(열린 finding·must_fix, 깨진 enum)만 남긴다.
+    // 형식 위반은 review record·accept-risk가 기록 시점에 거절하므로 gate는 막지 않는다.
+    // G8의 accepted/required 판정은 그대로 둔다.
+    if (!blueprintReviewMode && !isVerificationTask && reviewDoc && !reviewSkipped) {
+        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),
+        }).filter(validate_gates_shared_1.isBlockingReviewFailure)) {
+            addUnit('G14', message, 'review');
+        }
+    }
+    checkG24(failures, ctx, rels);
+    return;
+}
+/**
+ * commit gate 판정. G 코드·메시지·순서는 분리 전과 같다.
+ *
+ * @param {GateStageCtx} stage - add 클로저와 문서 묶음
+ * @returns {void}
+ */
+function checkCommitGate(stage) {
+    const { 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);
+    // G9는 폐기됨 — 번호만 비워 둠.
+    // G15 (explain comprehension / diff_sha)는 폐기됨 — 번호만 비워 둠.
+    const taskUnit = (ctx && ctx.taskUnit) || resolveTaskUnit(docs, {
+        repoRoot, blueprintDir,
+    });
+    const tasksDoc = taskUnit && taskUnit.tasks;
+    const verificationDoc = taskUnit && taskUnit.verification;
+    const reviewDoc = taskUnit && taskUnit.review;
+    const addUnit = (code, message, leaf) => failures.push({
+        code,
+        message,
+        file: unitLeafRel(taskUnit, leaf, rels[leaf]),
+    });
+    if (statusOf(tasksDoc) !== 'verified') {
+        addUnit('G6', 'tasks.status != verified', 'tasks');
+    }
+    if (statusOf(verificationDoc) !== 'passed') {
+        addUnit('G7', 'verification.status != passed', 'verification');
+    }
+    const commitReviewBouncer = reviewDoc
+        ? reviewDoc.data.bouncer
+        : undefined;
+    const review = commitReviewBouncer
+        ? commitReviewBouncer.review
+        : undefined;
+    const reviewOk = statusOf(reviewDoc) === 'accepted' || (review && review.required === false);
+    if (!isBlueprintReviewMode(docs.blueprintIndex) && !reviewOk) {
+        addUnit('G8', 'review not accepted and review.required != false', 'review');
+    }
+    checkG13(verificationDoc, addUnit, ctx);
+    checkG23(verificationDoc, addUnit, ctx, failures);
+    checkG24(failures, ctx, rels);
+    // G17은 이미 스테이징된 경로만 본다. working-tree 변경의 out-of-scope는
+    // bouncer commit이 따로 막으며, 빈 스테이징은 통과(빈 커밋 방지는 명령 몫).
+    const stagedFn = (deps && deps.stagedFiles) || defaultStagedFiles;
+    if (typeof repoRoot !== 'string') {
+        failures.push({
+            code: 'G17',
+            message: 'could not read staged files (missing-repo)',
+            file: unitLeafRel(taskUnit, 'tasks', rels.tasks),
+        });
+        return;
+    }
+    const staged = stagedFn({ repoRoot });
+    if (!staged || staged.ok !== true) {
+        // `'reason' in`은 객체가 아니면 TypeError. 예전 `staged && staged.reason`은
+        // primitive도 git-failed로 G17에 남겼다.
+        const stagedFail = staged;
+        const reason = stagedFail && stagedFail.reason ? stagedFail.reason : 'git-failed';
+        failures.push({
+            code: 'G17',
+            message: `could not read staged files (${reason})`,
+            file: unitLeafRel(taskUnit, 'tasks', rels.tasks),
+        });
+        return;
+    }
+    const taskData = (0, validate_gates_shared_1.asData)(tasksDoc);
+    const affectedPaths = taskData && taskData.bouncer
+        ? taskData.bouncer.affected_paths
+        : [];
+    const allowed = makeAllowed({ affectedPaths, blueprintDir });
+    const files = Array.isArray(staged.files) ? staged.files : [];
+    const violations = files
+        .filter((f) => !isRuntimeArtifact(f))
+        .filter((f) => !allowed(f));
+    if (violations.length) {
+        failures.push({
+            code: 'G17',
+            message: `staged path outside affected_paths: ${violations.join(', ')}`,
+            file: unitLeafRel(taskUnit, 'tasks', rels.tasks),
+        });
+    }
+    return;
+}

package/dist/validate-gates-shared.js

@@ -0,0 +1,124 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toGateContext = toGateContext;
+exports.asData = asData;
+exports.gitExec = gitExec;
+exports.lastReviewHead = lastReviewHead;
+exports.firstStderrLine = firstStderrLine;
+exports.sameCanonical = sameCanonical;
+exports.isBlockingReviewFailure = isBlockingReviewFailure;
+const canonicalJsonMod = require("./canonical-json");
+const { canonicalJson } = canonicalJsonMod;
+const { spawnSync } = require('node:child_process');
+/**
+ * 단계 함수가 G13·G21처럼 GateContext를 받는 헬퍼를 그대로 부르게 한다.
+ * stage 필드를 빼먹으면 repoRoot·deps가 비어 기본 원장 읽기가 건너뛰어질 수 있다.
+ *
+ * @param {GateStageCtx} stage - runCheckGate가 만든 단계 문맥
+ * @returns {GateContext} 기존 헬퍼가 기대하는 문맥
+ */
+function toGateContext(stage) {
+    return {
+        repoRoot: stage.repoRoot,
+        blueprintDir: stage.blueprintDir,
+        deps: stage.deps,
+        taskUnit: stage.taskUnit,
+        parseErrors: stage.parseErrors,
+        warnings: stage.warnings,
+        partialClose: stage.partialClose,
+    };
+}
+/**
+ * 문서 YAML data를 레코드로 읽는다. data가 null이면 빈 객체로 바꾸지 않는다 —
+ * 예전 호출부가 `.bouncer` 접근에서 터지던 실패 형태를 유지해야 한다.
+ *
+ * @param {DocLeaf | undefined | null} doc - 로드된 문서 또는 부재
+ * @returns {Record<string, unknown> | undefined} data. 문서가 없으면 undefined
+ */
+function asData(doc) {
+    if (!doc)
+        return undefined;
+    // 호출부가 `doc.data.bouncer`로 바로 들어가던 곳은 그대로 두기 위해
+    // 여기서 data를 빈 객체로 바꾸지 않는다. null data는 예전처럼 접근 시 터진다.
+    return doc.data;
+}
+/**
+ * 주입된 git exec가 없으면 repoRoot에 바인딩한 spawnSync를 쓴다.
+ * merge-base --is-ancestor는 status 1이 정상 실패라 execFileSync를 쓰면 안 된다.
+ *
+ * @param {string} repoRoot - git cwd
+ * @param {string[]} args - `git` 뒤 argv
+ * @param {GateDeps['exec']} [injected] - 테스트 seam
+ * @returns {{ status: number, stdout: string, stderr: string }} git 결과
+ */
+function gitExec(repoRoot, args, injected) {
+    if (typeof injected === 'function')
+        return injected(args);
+    const r = spawnSync('git', args, {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    return {
+        status: typeof r.status === 'number' ? r.status : 1,
+        stdout: r.stdout || '',
+        stderr: r.stderr || '',
+    };
+}
+/**
+ * 마지막 라운드의 `target.head`. 없거나 빈 값이면 라운드 계약이 없다.
+ *
+ * @param {unknown} rounds - `bouncer.review.rounds`
+ * @returns {string | null} head 또는 null
+ */
+function lastReviewHead(rounds) {
+    if (!Array.isArray(rounds) || rounds.length === 0)
+        return null;
+    const last = rounds[rounds.length - 1];
+    if (!last || typeof last !== 'object')
+        return null;
+    const target = last.target;
+    if (!target || typeof target !== 'object')
+        return null;
+    const head = target.head;
+    return typeof head === 'string' && head.trim() !== '' ? head : null;
+}
+/**
+ * git stderr에서 첫 줄을 골라 G21 메시지에 붙인다. 여러 줄 전체를 넣으면
+ * gate 실패 문구가 한 줄 계약을 넘는다.
+ *
+ * @param {string} stderr - exec 결과 stderr
+ * @returns {string} 첫 줄(trim). 비어 있으면 빈 문자열
+ */
+function firstStderrLine(stderr) {
+    const line = String(stderr).split(/\r?\n/)[0] || '';
+    return line.trim();
+}
+/**
+ * 객체를 키 정렬 JSON으로 비교한다. G13 identity/scope 대조가 삽입 순서에
+ * 흔들리지 않게 한다.
+ *
+ * @param {unknown} left - 문서 값
+ * @param {unknown} right - 원장 값
+ * @returns {boolean} 동치면 true
+ */
+function sameCanonical(left, right) {
+    return canonicalJson(left) === canonicalJson(right);
+}
+/**
+ * `collectFindingFailures`가 돌려준 메시지 중 gate가 실패로 남길 실질 판정인지 가린다.
+ * 열린 finding·열린 must_fix는 리뷰가 승인될 수 없다는 뜻이고, findings 배열·status·actionability가
+ * 깨지면 위 두 판정을 내릴 수 없으므로 fail-closed로 같이 남긴다. 나머지(severity·note·fingerprint·
+ * rounds 순서 등) 형식 위반은 기록 시점(`review record`·`accept-risk`)이 이미 거절하므로 gate에서는 뺀다.
+ * id 자리는 `.+`다 — id 없는 finding은 `(no id)`(공백 포함)로 찍힌다.
+ *
+ * @param {string} message - `collectFindingFailures`의 메시지 한 건
+ * @returns {boolean} gate 실패로 남겨야 하면 true, 형식 메시지라 뺄 수 있으면 false
+ */
+function isBlockingReviewFailure(message) {
+    return /^\S+ finding .+ open in accepted review$/.test(message)
+        || /^\S+ accepted with open must_fix .+$/.test(message)
+        || /^\S+ findings must be an array$/.test(message)
+        || /^\S+ finding .+ status invalid: .*$/.test(message)
+        || /^\S+ finding .+ actionability (invalid|missing)$/.test(message);
+}

package/dist/validate-gates.js

@@ -0,0 +1,87 @@
+'use strict';
+// 게이트별 G 코드 층. 문서 로드(docs)·문서 하나 구조(S)·본문 파싱은 여기 두지
+// 않는다. 승인 범위는 G5가 판정한다(G4는 결번). validate.ts를
+// require하지 않는다(validate → gates → structural, 순환 금지).
+// 단계 본체는 plan·run·finalize 모듈에 두고, 이 파일은 호출 형태와 단계 선택만 맡는다.
+const validate_gates_plan_1 = require("./validate-gates-plan");
+const validate_gates_run_1 = require("./validate-gates-run");
+const validate_gates_finalize_1 = require("./validate-gates-finalize");
+/**
+ * 객체 옵션과 위치 인자 두 호출 형태를 받아 runCheckGate로 넘긴다.
+ * 기존 소비자는 warnings 부재를 허용한다 — 빈 배열이면 키를 생략한다.
+ *
+ * @param {string | CheckGateOpts} gate - gate 이름 또는 옵션 객체
+ * @param {BlueprintDocs} [docs] - 로드된 문서
+ * @param {BlueprintRels} [rels] - 실패 file 경로
+ * @param {FailureEntry[]} [failures] - 위치 인자 호출의 누적 배열
+ * @param {GateContext} [ctx] - 위치 인자 호출의 문맥
+ * @returns {{ failures: FailureEntry[]; warnings?: FailureEntry[] } | void} 객체 호출이면 결과, 아니면 void
+ */
+function checkGate(gate, docs, rels, failures, ctx) {
+    if (typeof gate === 'object' && gate !== null) {
+        const opts = gate;
+        const collected = [];
+        const warnings = [];
+        checkGate(opts.gate, opts.docs || {}, opts.rels, collected, {
+            repoRoot: opts.repoRoot,
+            blueprintDir: opts.blueprintDir,
+            deps: opts.deps,
+            taskUnit: opts.taskUnit,
+            parseErrors: opts.parseErrors,
+            partialClose: opts.partialClose,
+            warnings,
+        });
+        return warnings.length > 0
+            ? { failures: collected, warnings }
+            : { failures: collected };
+    }
+    return runCheckGate(gate, docs, rels, failures, ctx || {});
+}
+/**
+ * add 클로저를 만들고 gate 이름으로 단계 함수를 고른다. 알 수 없는 이름은 throw한다.
+ *
+ * @param {string} gate - plan | execute | finalize | commit | partial-close
+ * @param {BlueprintDocs} docs - 로드된 문서
+ * @param {BlueprintRels} rels - 실패 file 경로
+ * @param {FailureEntry[]} failures - 실패 누적 배열
+ * @param {GateContext} ctx - repoRoot·deps·taskUnit
+ * @returns {void}
+ */
+function runCheckGate(gate, docs, rels, failures, ctx) {
+    const add = (code, message, fileKey) => failures.push({ code, message, file: rels[fileKey] });
+    const stage = {
+        add,
+        docs,
+        rels,
+        failures,
+        repoRoot: ctx && ctx.repoRoot,
+        blueprintDir: ctx && ctx.blueprintDir,
+        deps: ctx && ctx.deps,
+        taskUnit: ctx && ctx.taskUnit,
+        parseErrors: ctx && ctx.parseErrors,
+        partialClose: ctx && ctx.partialClose,
+        warnings: ctx && ctx.warnings,
+    };
+    if (gate === 'partial-close') {
+        (0, validate_gates_finalize_1.checkPartialCloseGate)(stage);
+        return;
+    }
+    if (gate === 'plan') {
+        (0, validate_gates_plan_1.checkPlanGate)(stage);
+        return;
+    }
+    if (gate === 'execute') {
+        (0, validate_gates_run_1.checkExecuteGate)(stage);
+        return;
+    }
+    if (gate === 'finalize') {
+        (0, validate_gates_finalize_1.checkFinalizeGate)(stage);
+        return;
+    }
+    if (gate === 'commit') {
+        (0, validate_gates_run_1.checkCommitGate)(stage);
+        return;
+    }
+    throw new Error(`unknown gate: ${gate}`);
+}
+module.exports = { checkGate, checkPartialCloseEvidence: validate_gates_finalize_1.checkPartialCloseEvidence, checkPlanDraft: validate_gates_plan_1.checkPlanDraft, SECURITY_PATH_TOKENS: validate_gates_plan_1.SECURITY_PATH_TOKENS };