@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/validate.js

@@ -0,0 +1,417 @@
+'use strict';
+const guards = require("./guards");
+const { catchMessage } = guards;
+const fs = require('node:fs');
+const path = require('node:path');
+const schema = require("./schema");
+const { detectLegacyFormat, isValidAuthoredLineList } = schema;
+const layout = require("./layout");
+const { CONTEXT_ROOT, isCanonicalBlueprintDir, blueprintPathProblem } = layout;
+const contextIds = require("./context-ids");
+const { validateSlug } = contextIds;
+const paths = require("./paths");
+const { toPosix } = paths;
+const verification = require("./verification");
+const { runVerification } = verification;
+const verificationTarget = require("./verification-target");
+const { resolveVerificationTarget } = verificationTarget;
+const epicIndex = require("./epic-index");
+const epicRegistry = require("./epic-registry");
+const { checkEpicIndexConsistency } = epicIndex;
+const validateDocs = require("./validate-docs");
+const { loadBlueprintDocs, resolveTaskUnit, blueprintDocsExist, statusOf, requiredTaskLeaves, isBlueprintReviewMode, } = validateDocs;
+const validateStructural = require("./validate-structural");
+const { checkStructural, checkSlugBlueprint } = validateStructural;
+const config = require("./config");
+const { readVerifyPolicy } = config;
+const validateGates = require("./validate-gates");
+const { checkGate, checkPlanDraft } = validateGates;
+const validateGatesPlan = require("./validate-gates-plan");
+const { PREREQUISITE_NEXT } = validateGatesPlan;
+const validateSections = require("./validate-sections");
+const { parseTasksSections, parseSections, extractPathCandidates, } = validateSections;
+const templates = require("./templates");
+const compositeGates = require("./composite-gates");
+const { summarizeCompositeGates } = compositeGates;
+const { parseIntentBody, normalizeAuthoredLines } = templates;
+// 복구가 메시지에 없는 코드만 여기를 본다. 같은 G 코드라도 이미 다음 행동을
+// 말하는 메시지(G13 body sections 등)에는 next를 붙이지
+// 않아야 에이전트가 표 밖의 경로를 발명하지 않는다. match는 메시지 문자열을
+// 바꾸지 않고 고르는 필터다.
+const GATE_FAILURE_HINTS = Object.freeze([
+    {
+        code: 'G13',
+        match: /missing harness verify ledger record|does not match verify ledger/,
+        next: 'Rerun this checkout\'s active-task `bouncer verify --blueprint <dir>`, then rerun the gate.',
+    },
+    {
+        code: 'G20',
+        match: /Touch must not declare source changes/,
+        next: 'Set Touch to `Source 변경 경로 없음.` and keep the command only in frontmatter `verify`.',
+    },
+    {
+        code: 'G23',
+        match: /verification evidence is stale/,
+        next: 'Rerun this checkout\'s active-task `bouncer verify --blueprint <dir>`, then rerun the commit gate.',
+    },
+    {
+        code: 'G24',
+        match: /approved scope changed after activation/,
+        next: 'If the change is intended, get the user\'s explicit approval, then run '
+            + '`bouncer current --set <dir> --reapprove` and rerun the gate.',
+    },
+    {
+        code: 'G32',
+        next: PREREQUISITE_NEXT,
+    },
+    {
+        code: 'S32',
+        match: /must be a YAML list/,
+        next: 'Rewrite the field as a YAML list of 1-2 Korean terminal sentences '
+            + '(each item on its own `- ` line), then rerun the plan gate.',
+    },
+    {
+        code: 'S33',
+        match: /blueprint Intent invalid/,
+        // Intent에 다이어그램·코드 펜스를 두면 문장 검사에 걸려 finalize가
+        // 스택으로 터지던 경로다. 문장만 남기고 펜스는 다른 ## 절로 옮기라고 안내한다.
+        next: 'Keep only 1-2 Korean terminal sentences under `## Intent`, move code '
+            + 'fences and diagrams under a separate `##` heading, then rerun the gate.',
+    },
+    {
+        code: 'S34',
+        match: /^(commit_intent|commit_summary) invalid: /,
+        // hint 표는 정적이라 필드 이름을 못 끼운다. 어느 필드가 틀렸는지는 메시지가
+        // 말하므로 next는 두 필드 공통 문구로 둔다.
+        next: 'Rewrite each failing commit_intent/commit_summary item as one Korean '
+            + 'terminal sentence (e.g. …함, …임, …됨, …다), then rerun the plan gate.',
+    },
+    {
+        code: 'S35',
+        next: 'Fix the `.bouncer/epics.json` format, or recreate it with `bouncer init`.',
+    },
+    {
+        code: 'S36',
+        next: 'Set blueprint `area` to a lowercase slug and `attribution` to a non-empty single line, '
+            + 'or remove the key, then rerun the gate.',
+    },
+    {
+        code: 'S37',
+        next: 'Give a slug blueprint a unique positive integer `order`, keep its slug unique in the epic, and use '
+            + 'the same format (numbered or slug) for the epic and blueprint directories, then rerun the gate.',
+    },
+]);
+/**
+ * validate 실패 항목에 hint 표의 next를 붙인 사본을 만든다.
+ * 판정(ok·순서·warnings)은 바꾸지 않고, match가 맞는 항목에만 next 키를 넣는다.
+ * G 실패가 하나 이상이면 복합 gate 요약 `gates`를 함께 싣는다.
+ *
+ * @param {ValidateResult} result - validateBlueprint가 만들 원본 결과
+ * @returns {ValidateResult} failures에 next가 병합된 사본. 맞는 hint가 없으면 그 항목은 그대로다
+ */
+function withGateFailureHints(result) {
+    const failures = result.failures.map((entry) => {
+        const hint = GATE_FAILURE_HINTS.find((row) => (row.code === entry.code && (!row.match || row.match.test(entry.message))));
+        if (!hint)
+            return entry;
+        return { ...entry, next: hint.next };
+    });
+    // gates는 hint 병합 뒤에 요약해야 gate의 next가 첫 실패 항목의 hint를 따른다.
+    // G 실패가 없으면 키 자체를 싣지 않는다(warnings와 같은 방식) — 성공 결과 전체를
+    // deepStrictEqual로 고정한 기존 테스트가 깨지지 않게 하기 위함이다.
+    const gates = summarizeCompositeGates(failures);
+    return gates.length > 0 ? { ...result, failures, gates } : { ...result, failures };
+}
+/**
+ * blueprint 문서를 로드해 structural(S) 검사와 선택한 gate 또는 plan draft 검사를 돌린다.
+ * `gate: 'execute'`는 검사 전에 verify 명령을 실행해 증적을 새로 쓰고,
+ * 통과하면 lease·pointer commit task를 `ready`에서 `verified`로 올린다(부작용).
+ * `planDraft: true`는 structural·S18 실패가 없을 때만 checkPlanDraft를 돌린다 —
+ * S 실패 위에 G 코드를 쌓으면 review-dispatch가 원인을 structural로 분류하지 못한다.
+ *
+ * @param {object} opts - 검증 옵션
+ * @param {string} opts.repoRoot - 저장소 루트 절대 경로
+ * @param {string} opts.blueprintDir - `.bouncer/context/epics/...` 아래 blueprint 상대 경로
+ * @param {string} [opts.gate] - plan | execute | commit | finalize | partial-close. 없으면 S 검사만
+ * @param {boolean} [opts.planDraft] - true면 gate 대신 status 무관 plan draft 검사를 돌린다
+ * @param {GateDeps} [opts.deps] - gate 검사에 주입할 의존성(테스트용)
+ * @returns {{ ok: boolean, failures: FailureEntry[], warnings?: FailureEntry[] }}
+ *   failures가 비면 ok:true. 경고(task-split·dag-*·review-risk-missing 등)가 있을 때만 warnings 키를 싣는다
+ * @throws {Error} planDraft와 gate를 함께 주면 'planDraft cannot be combined with gate'
+ */
+function validateBlueprint({ repoRoot, blueprintDir, gate, planDraft, deps, }) {
+    // 둘 다 주면 어느 판정이 ok를 결정하는지 모호하다. 호출 계약 오류이므로
+    // 문서 결과로 접지 않고 파일을 읽기 전에 던진다.
+    if (planDraft && gate) {
+        throw new Error('planDraft cannot be combined with gate');
+    }
+    if (!isCanonicalBlueprintDir(blueprintDir)) {
+        // slug 체계를 쓰는 epic 아래의 경로 오류(형식 혼용·slug 규칙 위반)는 일반 경로 오류 S10 대신
+        // 어디를 고쳐야 하는지 알려 주는 S37로 보고한다. 그 밖의 비정본 경로는 S10 그대로다.
+        const problem = blueprintPathProblem(blueprintDir);
+        if (problem !== null) {
+            const leaf = toPosix(blueprintDir).split('/').pop();
+            const detail = problem === 'format-mixed'
+                ? 'the epic and blueprint directories must both be numbered (ddd-name) or both be slugs'
+                : `blueprint directory name is not a valid slug: ${validateSlug(leaf)}`;
+            return withGateFailureHints({
+                ok: false,
+                failures: [{ code: 'S37', message: `${problem}: ${detail}`, file: toPosix(blueprintDir) }],
+            });
+        }
+        return withGateFailureHints({
+            ok: false,
+            failures: [{
+                    code: 'S10',
+                    message: `blueprintDir must be under ${CONTEXT_ROOT}/epics`,
+                    file: toPosix(blueprintDir),
+                }],
+        });
+    }
+    const legacyRepo = detectLegacyFormat({ repoRoot });
+    if (legacyRepo.legacy) {
+        return withGateFailureHints({
+            ok: false,
+            failures: [{ code: 'S2', message: legacyRepo.reason, file: '.sdd' }],
+        });
+    }
+    // blueprint 문서가 하나도 없으면 문서 문제가 아니라 잘못된 경로를 의미함.
+    // 이를 먼저 보고하면 빈 문서 집합이 만드는 gate 실패 연쇄를 쫓지 않게 하고,
+    // 존재하지 않는 경로에 대해 `execute`가 verify 명령을 실행하는 것을 막음.
+    // epic index는 의도적으로 제외: 해당 epic 아래 모든 blueprint에 존재하므로,
+    // 오타 난 blueprint 이름이 이 검사를 통과해 버릴 수 있음.
+    if (!blueprintDocsExist({ repoRoot, blueprintDir })) {
+        return withGateFailureHints({
+            ok: false,
+            failures: [{
+                    code: 'S11',
+                    message: 'blueprint documents not found — check the blueprint path',
+                    file: toPosix(blueprintDir),
+                }],
+        });
+    }
+    const executionFailures = [];
+    if (gate === 'execute') {
+        // G13 file은 포인터 대상 묶음의 verification 경로. 루트 고정 경로를 쓰면
+        // tasks/<NNN>/ 레이아웃에서 실패 위치가 엉킨다.
+        let verificationFile = `${toPosix(blueprintDir)}/verification.md`;
+        try {
+            const { effectiveTask, entries } = resolveVerificationTarget({ repoRoot, blueprintDir });
+            if (entries[0] && entries[0].verification && entries[0].verification.rel) {
+                verificationFile = entries[0].verification.rel;
+            }
+            const verification = runVerification({
+                repoRoot, blueprintDir, effectiveTask, markTaskVerified: true,
+            });
+            if (!verification.ok) {
+                executionFailures.push({
+                    code: 'G13',
+                    message: `configured verify command failed with exit code ${verification.exitCode}`,
+                    file: verificationFile,
+                });
+            }
+        }
+        catch (error) {
+            executionFailures.push({
+                code: 'G13',
+                message: catchMessage(error),
+                file: verificationFile,
+            });
+        }
+    }
+    // execute gate가 방금 기록한 증적을 읽도록 verification 이후에 로드.
+    const { docs, rels, parseErrors, tasksListing } = loadBlueprintDocs({ repoRoot, blueprintDir });
+    const failures = [...executionFailures, ...parseErrors];
+    // 한 blueprint에 레거시 tasks.md와 번호 문서가 섞이면 어느 규칙을
+    // 적용할지 모호해지므로 구조 단계에서 거절한다.
+    if (tasksListing && tasksListing.legacyFiles && tasksListing.legacyFiles.length) {
+        failures.push({
+            code: 'S15',
+            message: `legacy task layout remains: ${tasksListing.legacyFiles.join(', ')}; run bouncer migrate task-layout`,
+            file: toPosix(blueprintDir),
+        });
+    }
+    for (const name of (tasksListing && tasksListing.invalidDirs) || []) {
+        failures.push({
+            code: 'S16',
+            message: `non-canonical task directory: tasks/${name}`,
+            file: `${toPosix(blueprintDir)}/tasks/${name}`,
+        });
+    }
+    // closed는 finalize가 남긴 축약 레이아웃(task leaf 없음)을 허용하고,
+    // 열린 blueprint는 기존처럼 세 leaf를 모두 요구한다. 모드에서는 review
+    // leaf를 빼므로 구형 루트 review.md 존재만으로 S17이 바뀌지 않는다.
+    const requiredLeaves = requiredTaskLeaves(statusOf(docs.blueprintIndex), undefined, isBlueprintReviewMode(docs.blueprintIndex));
+    for (const entry of (tasksListing && tasksListing.entries) || []) {
+        for (const leaf of requiredLeaves) {
+            const rel = entry[leaf].rel;
+            if (!fs.existsSync(path.join(repoRoot, rel))) {
+                failures.push({
+                    code: 'S17',
+                    message: `task unit ${entry.number} missing ${path.posix.basename(rel)}`,
+                    file: rel,
+                });
+            }
+        }
+    }
+    const anyLeaf = (docs.tasksDocs && docs.tasksDocs.length > 0)
+        || (docs.taskUnits && docs.taskUnits.length > 0)
+        || ['verification', 'review', 'explain'].some((k) => docs[k]);
+    if (anyLeaf && !docs.blueprintIndex) {
+        failures.push({ code: 'S8', message: 'blueprint index.md absent', file: rels.blueprintIndex });
+    }
+    if (docs.blueprintIndex && !docs.epicIndex) {
+        failures.push({ code: 'S8', message: 'epic index.md absent', file: rels.epicIndex });
+    }
+    // S33: plan·finalize만. draft와 Intent 헤딩 부재는 기존 fixture·scaffold를
+    // 보존하려고 건너뛴다 — 헤딩이 없으면 finalize prepare도 intent:[]로 통과한다.
+    // 오류 메시지 원문은 parseIntentBody throw를 그대로 붙인다(계약 문자열 유지).
+    if ((gate === 'plan' || gate === 'finalize') && docs.blueprintIndex
+        && statusOf(docs.blueprintIndex) !== 'draft') {
+        const bpBody = typeof docs.blueprintIndex.body === 'string'
+            ? docs.blueprintIndex.body
+            : '';
+        const hasIntentHeading = /^##\s+Intent\s*$/im.test(bpBody.replace(/<!--[\s\S]*?-->/g, ''));
+        if (hasIntentHeading) {
+            try {
+                parseIntentBody(bpBody);
+            }
+            catch (error) {
+                failures.push({
+                    code: 'S33',
+                    message: `blueprint Intent invalid: ${catchMessage(error)}`,
+                    file: rels.blueprintIndex || docs.blueprintIndex.rel,
+                });
+            }
+        }
+    }
+    // S34: plan gate만. S32(목록 형태)는 checkStructural이 gate를 몰라 그대로 두고,
+    // 종결어미 판정은 `bouncer commit`이 쓰는 normalizeAuthoredLines를 그대로 불러
+    // 두 시점의 답이 갈라지지 않게 한다. 형태 오류는 S32 소관이라 건너뛰고, 부재·[]는
+    // 작성 전 scaffold라 통과시킨다. 필드당 한 번만 보고한다.
+    if (gate === 'plan') {
+        const hasTaskUnitsForS34 = Array.isArray(docs.taskUnits) && docs.taskUnits.length > 0;
+        const taskLeaves = hasTaskUnitsForS34
+            ? (docs.taskUnits || []).flatMap((unit) => (unit.tasks ? [unit.tasks] : []))
+            : (docs.tasksDocs || (docs.tasks ? [docs.tasks] : []));
+        for (const leaf of taskLeaves) {
+            const data = leaf.data;
+            const bouncerFm = (data && data.bouncer) || {};
+            for (const field of ['commit_intent', 'commit_summary']) {
+                const value = bouncerFm[field];
+                if (!isValidAuthoredLineList(value) || value === undefined)
+                    continue;
+                if (Array.isArray(value) && value.length === 0)
+                    continue;
+                try {
+                    normalizeAuthoredLines(value, field);
+                }
+                catch (error) {
+                    failures.push({
+                        code: 'S34',
+                        message: `${field} invalid: ${catchMessage(error)}`,
+                        file: leaf.rel,
+                    });
+                }
+            }
+        }
+    }
+    // 구조 검사를 돌기 전에 정책을 한 번만 읽는다. 문서마다 config를 다시
+    // 열면 같은 blueprint에서 S12 답이 갈라질 수 있고, 파손된 파일을
+    // 기본 목록으로 접으면 runtime VERIFY_CONFIG_INVALID와 어긋난다.
+    const verifyPolicy = readVerifyPolicy(repoRoot);
+    if (verifyPolicy.ok === false) {
+        failures.push({
+            code: 'S12',
+            message: `verification config is invalid: ${path.join(repoRoot, '.bouncer', 'config.json')}`,
+            file: '.bouncer/config.json',
+        });
+    }
+    const verifyAllowlist = verifyPolicy.ok === true
+        ? verifyPolicy.allowlist
+        : [];
+    const hasTaskUnits = Array.isArray(docs.taskUnits) && docs.taskUnits.length > 0;
+    // 번호 tasks가 루트 verification/review를 공유하면 같은 rel을 두 번
+    // 검사하지 않는다. unit leaf에서 못 본 루트 파일은 그대로 검사한다
+    // (task-dir 레이아웃에 남은 고아 루트 증적/리뷰).
+    const unitSeenRels = new Set();
+    for (const key of Object.keys(docs)) {
+        if (key === 'taskUnits') {
+            for (const unit of docs.taskUnits || []) {
+                for (const leaf of ['tasks', 'verification', 'review']) {
+                    const leafDoc = unit[leaf];
+                    if (!leafDoc || unitSeenRels.has(leafDoc.rel))
+                        continue;
+                    unitSeenRels.add(leafDoc.rel);
+                    checkStructural(leafDoc, failures, verifyAllowlist);
+                }
+            }
+            continue;
+        }
+        if (key === 'tasksDocs') {
+            // taskUnits가 있으면 tasks leaf는 그쪽에서 이미 검사함.
+            if (hasTaskUnits)
+                continue;
+            for (const td of docs.tasksDocs || [])
+                checkStructural(td, failures, verifyAllowlist);
+            continue;
+        }
+        // tasksDocs/taskUnits가 있으면 docs.tasks는 그 첫 항목이라 중복 검사하지 않는다.
+        if (key === 'tasks' && (docs.tasksDocs || hasTaskUnits))
+            continue;
+        if ((key === 'verification' || key === 'review')
+            && docs[key]
+            && unitSeenRels.has(docs[key].rel)) {
+            continue;
+        }
+        checkStructural(docs[key], failures, verifyAllowlist);
+    }
+    // S37: slug 형식 blueprint의 order·slug 판정은 형제 문서를 읽어야 해서 문서 하나만 보는 checkStructural
+    // 밖에서, blueprint index 하나에 대해 한 번만 돈다. 번호 형식 경로는 아무것도 내지 않는다.
+    failures.push(...checkSlugBlueprint({ repoRoot, blueprintDir, blueprintIndex: docs.blueprintIndex }));
+    failures.push(...checkEpicIndexConsistency({ repoRoot }));
+    // 등록부가 있을 때만 형식을 본다. 부재는 이 BP에서 차단하지 않아 기존 결과가 그대로다.
+    failures.push(...epicRegistry.checkEpicRegistry({ repoRoot }));
+    // imported blueprint는 게이트·작업 대상이 아니다. 구조·에픽목록 검사는 유지하되
+    // checkGate를 건너뛰고 S18 하나로 거절한다 — ok:true/gateSkipped로 통과시키면
+    // cmdCurrent --set이 plan 통과로 포인터를 잡아버린다. epic-only imported는
+    // 판정하지 않는다(기준은 blueprint status). S14는 결번이므로 재사용하지 않는다.
+    if (statusOf(docs.blueprintIndex) === 'imported') {
+        failures.push({
+            code: 'S18',
+            message: 'imported document is out of gate scope',
+            file: rels.blueprintIndex,
+        });
+        return withGateFailureHints({ ok: false, failures });
+    }
+    // plan task 분해 경고는 failures와 분리한다. ok는 실패만 본다.
+    const warnings = [];
+    if (planDraft) {
+        // 이 시점 failures는 S 코드뿐이다(S18은 위에서 이미 반환). S가 있으면 draft
+        // 검사를 건너뛰어 한 결과에 S와 G가 섞이지 않게 한다.
+        if (failures.length > 0)
+            return withGateFailureHints({ ok: false, failures });
+        checkPlanDraft(docs, rels, failures, { warnings, repoRoot, blueprintDir, deps });
+    }
+    else if (gate) {
+        // execute·commit 모두 포인터 task 단위만 본다(G6–G8).
+        const taskUnit = (gate === 'execute' || gate === 'commit')
+            ? resolveTaskUnit(docs, { repoRoot, blueprintDir })
+            : undefined;
+        // parseErrors는 이미 failures에 합쳐졌지만, gate 문맥에는 문서별 파싱 실패를
+        // 구분할 수 있도록 원본 목록을 그대로 넘긴다.
+        checkGate(gate, docs, rels, failures, {
+            repoRoot, blueprintDir, deps, taskUnit, parseErrors, warnings,
+        });
+    }
+    // 기존 소비자는 warnings 부재를 허용한다 — 비어 있으면 키를 넣지 않는다.
+    if (warnings.length > 0) {
+        return withGateFailureHints({ ok: failures.length === 0, failures, warnings });
+    }
+    return withGateFailureHints({ ok: failures.length === 0, failures });
+}
+module.exports = {
+    loadBlueprintDocs, resolveTaskUnit, checkStructural, checkGate, validateBlueprint,
+    parseTasksSections, parseSections, extractPathCandidates,
+    GATE_FAILURE_HINTS, withGateFailureHints,
+};

package/dist/verification-contracts.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verificationError = verificationError;
+exports.errorCode = errorCode;
+/**
+ * 기존 검증 오류 code를 유지하여 호출자가 실행 실패와 사전 거절을 구분하게 한다.
+ * @param {string} code - 기계 판독 오류 코드
+ * @param {string} message - 오류 설명
+ * @returns {CodedError} code를 보유한 오류 객체
+ */
+function verificationError(code, message) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+/**
+ * 알 수 없는 예외에서 code만 안전하게 읽는다.
+ * @param {unknown} error - 외부 의존성이 던진 값
+ * @returns {unknown} code가 없으면 undefined
+ */
+function errorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        return error.code;
+    }
+    return undefined;
+}

package/dist/verification-evidence.js

@@ -0,0 +1,233 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const canonicalJsonMod = require("./canonical-json");
+const { canonicalJson } = canonicalJsonMod;
+const guards = require("./guards");
+const { isRecord } = guards;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const render = require("./render");
+const { renderDoc } = render;
+const paths = require("./paths");
+const { toPosix } = paths;
+const runtimeState = require("./runtime-state");
+const { verifyLedgerPathFor } = runtimeState;
+const tasksDocs = require("./tasks-docs");
+const { listTasksDocs } = tasksDocs;
+const identityModule = require("./verification-identity");
+const { resolveDefaultTaskScope, computeEvidenceIdentity, computeSourceDigest } = identityModule;
+const verification_contracts_1 = require("./verification-contracts");
+/**
+ * v2 성공 원장만 reuse hit로 인정한다. v1·실패·필드 누락·identity/scope 불일치는 miss.
+ *
+ * @param {unknown} record - 디스크 원장
+ * @param {EvidenceIdentity} identity - 현재 입력 identity
+ * @param {string} evidenceId - 현재 evidence_id
+ * @returns {record is VerifyLedgerRecordV2} hit이면 true
+ */
+function isReuseHit(record, identity, evidenceId) {
+    if (!isRecord(record))
+        return false;
+    // v1은 evidence_id가 없다. 읽을 수는 있어도 hit로 승격하지 않는다.
+    if (typeof record.evidence_id !== 'string' || !record.evidence_id)
+        return false;
+    if (record.evidence_id !== evidenceId)
+        return false;
+    if (record.exit_code !== 0)
+        return false;
+    if (typeof record.ran_at !== 'string' || !record.ran_at)
+        return false;
+    if (typeof record.output_sha !== 'string' || !record.output_sha)
+        return false;
+    if (typeof record.command !== 'string')
+        return false;
+    // reused는 성공 hit의 필수 boolean. 누락·문자열·숫자는 손상으로 miss.
+    if (typeof record.reused !== 'boolean')
+        return false;
+    if (!isRecord(record.identity) || !isRecord(record.scope))
+        return false;
+    if (canonicalJson(record.identity) !== canonicalJson(identity))
+        return false;
+    if (canonicalJson(record.scope) !== canonicalJson(identity.scope))
+        return false;
+    return true;
+}
+/**
+ * 원장 파일을 읽어 파싱한다. 부재·파손은 null(정상 miss).
+ *
+ * @param {string} ledgerFile - 절대 경로
+ * @returns {unknown | null}
+ */
+function readLedgerFile(ledgerFile) {
+    if (!fs.existsSync(ledgerFile))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(ledgerFile, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch (_error) {
+        return null;
+    }
+}
+/**
+ * verification.md와 common-dir 원장에 한 번 실행(또는 reuse)의 증적을 쓴다.
+ * source_digest는 기록 시각의 checkout에서 다시 계산한다 — reuse hit여도
+ * 그 시점 값을 남겨 commit G23이 verify 이후 소스 변경을 거절할 수 있다.
+ *
+ * @param {object} opts - 기록 입력
+ * @param {string} opts.repoRoot - 저장소 루트
+ * @param {string} [opts.verificationRel] - verification.md 상대 경로
+ * @param {string} [opts.blueprintDir] - 구 호출 호환용 blueprint 상대 경로
+ * @param {string} opts.command - 실행한 검증 명령
+ * @param {string} opts.ranAt - 실행 시각(KST ISO)
+ * @param {number} opts.exitCode - 프로세스 종료 코드
+ * @param {string} opts.output - output_tail 원본
+ * @param {string} [opts.evidenceId] - 생략 시 현재 identity에서 계산
+ * @param {EvidenceIdentity} [opts.identity] - 생략 시 현재 checkout에서 계산
+ * @param {VerificationScope} [opts.scope] - 생략 시 포인터/경로에서 유도
+ * @param {boolean} [opts.reused] - reuse hit이면 true
+ * @param {string} [opts.reusedFrom] - hit의 원본 evidence_id
+ * @param {object} [opts.deps] - git/원장 경로 주입
+ * @returns {void}
+ */
+function recordVerificationResult({ repoRoot, verificationRel, blueprintDir, command, ranAt, exitCode, output, evidenceId, identity, scope, reused = false, reusedFrom, deps, }) {
+    // verificationRel이 정식 인자. blueprintDir은 구 호출 호환(루트 verification.md).
+    const rel = verificationRel
+        || (blueprintDir ? `${toPosix(blueprintDir)}/verification.md` : null);
+    if (!rel) {
+        throw (0, verification_contracts_1.verificationError)('VERIFY_DOCUMENT_MISSING', 'verification document path missing');
+    }
+    // 직접 호출 테스트는 evidence를 생략한다. 그 경우 현재 checkout identity를
+    // 채워 v2 원장·G13 계약과 맞춘다 — runVerification 경로와 키 공간을 공유한다.
+    let resolvedScope = scope;
+    let resolvedIdentity = identity;
+    let resolvedEvidenceId = evidenceId;
+    if (!resolvedScope || !resolvedIdentity || !resolvedEvidenceId) {
+        const blueprintGuess = blueprintDir
+            || rel.replace(/\/tasks\/\d{3}\/verification\.md$/, '')
+            || rel.replace(/\/verification\.md$/, '');
+        resolvedScope = resolvedScope || resolveDefaultTaskScope(repoRoot, blueprintGuess, null, listTasksDocs({ repoRoot, blueprintDir: blueprintGuess }).entries);
+        const computed = computeEvidenceIdentity({
+            repoRoot,
+            command,
+            scope: resolvedScope,
+            deps,
+        });
+        resolvedIdentity = resolvedIdentity || computed.identity;
+        resolvedEvidenceId = resolvedEvidenceId || computed.evidenceId;
+    }
+    const verificationPath = path.join(repoRoot, rel);
+    let document;
+    try {
+        document = readDoc(verificationPath);
+    }
+    catch (error) {
+        if ((0, verification_contracts_1.errorCode)(error) === 'ENOENT') {
+            throw (0, verification_contracts_1.verificationError)('VERIFY_DOCUMENT_MISSING', `verification document missing: ${verificationPath}`);
+        }
+        throw error;
+    }
+    const data = document.data;
+    // 증적은 파싱 객체에 in-place로 붙인다. 빈 객체로 바꾸면 스칼라 YAML의
+    // TypeError가 사라져 실패 형태가 바뀐다.
+    const bouncer = (data.bouncer || {});
+    data.bouncer = bouncer;
+    bouncer.status = exitCode === 0 ? 'passed' : 'failed';
+    // identity와 별도로 둔다. dirty_digest는 .bouncer를 포함해 G13 재사용 키를
+    // 바꾸지 못하게 하고, 이 필드는 commit 신선도만 본다.
+    const sourceDigest = computeSourceDigest(repoRoot, deps);
+    const verificationMeta = {
+        command,
+        ran_at: ranAt,
+        exit_code: exitCode,
+        output_tail: output,
+        evidence_id: resolvedEvidenceId,
+        identity: resolvedIdentity,
+        scope: resolvedScope,
+        reused,
+        source_digest: sourceDigest,
+    };
+    // reused_from은 hit일 때만 기록한다. false인데 키가 있으면 G13이 손기록을 통과시킨다.
+    if (reused && reusedFrom) {
+        verificationMeta.reused_from = reusedFrom;
+    }
+    bouncer.verification = verificationMeta;
+    const evidence = exitCode === 0
+        ? ''
+        : `\n\`\`\`\n${output}\n\`\`\`\n`;
+    const body = `# Verification
+
+## Command
+\`${command}\`
+
+## Evidence
+Ran at: ${ranAt}
+Exit code: ${exitCode}
+${evidence}`;
+    fs.writeFileSync(verificationPath, renderDoc(data, body));
+    // 게이트는 디스크에서 다시 읽은 output_tail을 해싱한다. js-yaml dump/load가
+    // 개행·후행 공백을 정규화해도, 기록 쪽이 같은 왕복을 거치면 해시가 갈라지지 않는다.
+    const reread = readDoc(verificationPath);
+    const rereadBouncer = reread.data.bouncer;
+    const rereadEvidence = rereadBouncer && rereadBouncer.verification
+        ? rereadBouncer.verification
+        : {};
+    const outputTail = typeof rereadEvidence.output_tail === 'string' ? rereadEvidence.output_tail : '';
+    const outputSha = createHash('sha256').update(outputTail, 'utf8').digest('hex');
+    const ledgerPaths = verifyLedgerPathFor({
+        repoRoot,
+        verificationRel: rel,
+        evidenceId: resolvedEvidenceId,
+        deps,
+    });
+    if (ledgerPaths.unavailable || !ledgerPaths.ledgerFile) {
+        // 원장 없이 문서만 남기면 에이전트 Write와 구분이 안 된다. Git을 못 쓰면
+        // verify 자체를 실패시켜 복구 경로(저장소에서 재실행)만 남긴다.
+        throw new Error(ledgerPaths.reason || 'Bouncer requires a Git repository for an active blueprint');
+    }
+    fs.mkdirSync(path.dirname(ledgerPaths.ledgerFile), { recursive: true });
+    const record = {
+        rel: toPosix(rel),
+        command,
+        ran_at: ranAt,
+        exit_code: exitCode,
+        output_sha: outputSha,
+        evidence_id: resolvedEvidenceId,
+        identity: resolvedIdentity,
+        scope: resolvedScope,
+        reused,
+        source_digest: sourceDigest,
+    };
+    if (reused && reusedFrom) {
+        record.reused_from = reusedFrom;
+    }
+    // reuse hit가 문서 output_tail을 다시 쓸 수 있게 성공 원장에만 본문을 남긴다.
+    if (exitCode === 0) {
+        record.output_tail = outputTail;
+    }
+    fs.writeFileSync(ledgerPaths.ledgerFile, `${JSON.stringify(record, null, 2)}\n`);
+}
+/**
+ * runner와 recorder의 경로 주입 비대칭을 유지하며 성공 증적만 반환한다.
+ * 출력 SHA가 맞지 않거나 원장이 없고 손상된 경우는 실행할 정상 miss다.
+ * @param {string} repoRoot - 저장소 루트
+ * @param {string} verificationRel - 증적 문서 상대 경로
+ * @param {EvidenceIdentity} identity - 현재 검증 identity
+ * @param {string} evidenceId - 현재 identity의 해시
+ * @returns {VerifyLedgerRecordV2 | null} 재사용 가능한 원장 또는 정상 miss
+ */
+function findReusableEvidence(repoRoot, verificationRel, identity, evidenceId) {
+    const paths = verifyLedgerPathFor({ repoRoot, verificationRel, evidenceId });
+    if (paths.unavailable || !paths.ledgerFile)
+        return null;
+    const record = readLedgerFile(paths.ledgerFile);
+    if (!isReuseHit(record, identity, evidenceId))
+        return null;
+    const output = typeof record.output_tail === 'string' ? record.output_tail : '';
+    return createHash('sha256').update(output, 'utf8').digest('hex') === record.output_sha ? record : null;
+}
+module.exports = { recordVerificationResult, findReusableEvidence };