@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/review-policy.js

@@ -0,0 +1,28 @@
+'use strict';
+// 리뷰 정책 값의 단일 정본. 위험도 enum과 execute 관점 목록은 검증 층(validate-*)과
+// 분류기(review-dispatch), 코디네이터가 모두 읽는다. 예전에는 파일마다 사본을 두고
+// 주석으로 "함께 고쳐라"만 적었는데, 한쪽만 고치면 컴파일러가 잡지 못해 S30과
+// Execute 경로의 허용 목록이 어긋날 수 있었다. 값만 담는 순수 모듈이라 다른 lib을
+// 가져오지 않는다 — 소비자 → 정본 방향의 간선만 허용해 순환을 만들지 않는다.
+// S30(validate-structural)과 review-dispatch Execute 경로가 같은 목록으로 거절한다.
+// 값과 순서를 바꾸면 기존 tasks 문서의 review_risk 판정이 바뀐다.
+const REVIEW_RISK_ENUM = [
+    'public_interface',
+    'authentication',
+    'authorization',
+    'credential',
+];
+// adaptive Execute는 combined를 추가하고, legacy 네 이름은 기존 round를 계속
+// 통과시킨다. security는 위험 flag가 있을 때만 별도 call로 붙는다.
+// Plan 쪽 CONTEXT_REVIEW_PERSPECTIVE와는 이름을 섞지 않아야 하므로 병합하지 않는다.
+const REVIEW_PERSPECTIVE = [
+    'combined',
+    'spec_scope',
+    'correctness_tests',
+    'minimality_maintainability',
+    'security',
+];
+module.exports = {
+    REVIEW_RISK_ENUM,
+    REVIEW_PERSPECTIVE,
+};

package/dist/review-record.js

@@ -0,0 +1,447 @@
+'use strict';
+const guards = require("./guards");
+const { isRecord } = guards;
+const fs = require('node:fs');
+const path = require('node:path');
+const frontmatter = require("./frontmatter");
+const { parseFrontmatter } = frontmatter;
+const render = require("./render");
+const { renderDoc } = render;
+const paths = require("./paths");
+const { toPosix } = paths;
+const validateSections = require("./validate-sections");
+const { normalizeRoundFindings, collectFindingFailures, EXECUTE_REVIEW_STATUS, EXECUTE_ROUND_CONTRACT, BLUEPRINT_ROUND_CONTRACT, BRIEF_ROUND_CONTRACT, } = validateSections;
+const schema = require("./schema");
+const { reviewContractOf } = schema;
+const reviewSnapshot = require("./review-snapshot");
+const { loadReviewSnapshot, checkReviewSnapshotCurrent } = reviewSnapshot;
+/** review_contract가 허용 밖 값일 때의 공통 거절. record와 accept-risk가 같은 답을 낸다. */
+function contractInvalid() {
+    return fail(schema.REVIEW_CONTRACT_INVALID_REASON, schema.REVIEW_CONTRACT_INVALID_CAUSE, 'fix review_contract in the blueprint index.md (brief or omit it), then retry');
+}
+function fail(reason, cause, next) {
+    return { ok: false, reason, cause, next };
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * blueprint index.md의 review_scope·review_contract를 읽어 리뷰 범위를 정한다.
+ * scaffold.isBlueprintReviewScope와 같은 범위 판정이지만 그 헬퍼는 scaffold 공개 표면에 없어
+ * 여기 읽기만 복제한다 — scaffold.ts는 이 task의 Touch가 아니다. 계약 해석은 schema의
+ * reviewContractOf를 그대로 써서 S38·review-dispatch·G21과 같은 답을 낸다.
+ *
+ * @param {string} repoRoot - 저장소 루트
+ * @param {string} blueprintDirRel - blueprint 상대 경로
+ * @returns {ReviewScope} `review_scope !== 'blueprint'`면 'task'. blueprint 범위에서 review_contract가
+ *   brief면 'blueprint_brief', 키 부재면 'blueprint', 허용 밖 값이면 'contract_invalid'
+ */
+function reviewScopeAt(repoRoot, blueprintDirRel) {
+    const abs = path.join(repoRoot, blueprintDirRel, 'index.md');
+    let data;
+    try {
+        ({ data } = parseFrontmatter(fs.readFileSync(abs, 'utf8')));
+    }
+    catch {
+        // 파일 없음·프론트매터 파싱 실패는 구형(task) 계약으로 본다. blueprint로 접으면
+        // --task를 거절해 대상 파일을 영원히 못 고른다.
+        return 'task';
+    }
+    if (!isRecord(data) || !isRecord(data.bouncer))
+        return 'task';
+    if (data.bouncer.review_scope !== 'blueprint')
+        return 'task';
+    const contract = reviewContractOf(data.bouncer);
+    if (contract === null)
+        return 'contract_invalid';
+    return contract === 'brief' ? 'blueprint_brief' : 'blueprint';
+}
+/**
+ * 기록 뒤 mode 순서가 허용 완결 순서 중 하나의 앞부분인지 본다.
+ * collectFindingFailures는 완결 순서만 통과시켜 진행 중 원장을 막으므로,
+ * 여기만 접두를 허용한다 — 검사 규칙 복제가 아니라 예외 판정이다.
+ *
+ * @param {unknown[]} rounds - 병합 뒤 rounds
+ * @param {'task' | 'blueprint' | 'blueprint_brief'} scope - 범위에 맞는 계약의 sequences로 판정
+ * @returns {boolean} 허용 sequences 원소를 `,`로 나눈 배열의 길이 n 접두면 true
+ */
+function isAllowedSequencePrefix(rounds, scope) {
+    const modes = [];
+    for (const entry of rounds) {
+        if (isRecord(entry) && typeof entry.mode === 'string')
+            modes.push(entry.mode);
+    }
+    const joined = modes.join(',');
+    if (joined === '')
+        return false;
+    let contract = EXECUTE_ROUND_CONTRACT;
+    if (scope === 'blueprint')
+        contract = BLUEPRINT_ROUND_CONTRACT;
+    if (scope === 'blueprint_brief')
+        contract = BRIEF_ROUND_CONTRACT;
+    for (const sequence of contract.sequences) {
+        const parts = sequence.split(',');
+        for (let n = 1; n <= parts.length; n += 1) {
+            if (parts.slice(0, n).join(',') === joined)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * 새 라운드의 target.snapshot_id가 실제 동결 상태에 묶였는지, 그리고 acceptance라면 그 상태가
+ * 지금도 현재 작업 트리와 같은지 검사한다. 저장 문서 검증기(G14/G21)는 과거 기록을 위해
+ * id가 없는 기록도 받으므로, "새 입력에는 id 필수"와 "지금도 신선한가"는 쓰기 시점의
+ * 이 함수만 판정한다. 호출부가 쓰기 전에 부르므로 거절은 항상 파일을 건드리지 않는다.
+ *
+ * 이 라운드의 snapshot만 본다. delta 뒤에는 앞 discovery snapshot이 정상적으로 stale이므로
+ * 이전 라운드의 id로 acceptance를 막으면 수정 후 재승인이 영원히 불가능해진다.
+ *
+ * @param {object} args - 검사 입력
+ * @param {string} args.repoRoot - 저장소 루트
+ * @param {string} args.blueprintDir - blueprint 상대 경로
+ * @param {string | null} args.task - task 리뷰면 세 자리 id, blueprint 모드면 null
+ * @param {Record<string, unknown>} args.round - 이번에 추가할 round 객체
+ * @param {boolean} args.accepted - 기록 뒤 effective status가 accepted인지(상속 포함)
+ * @returns {RecordReviewFail | null} 거절 사유, 통과하면 null
+ */
+function checkSnapshotBinding(args) {
+    const { repoRoot, blueprintDir, task, round, accepted } = args;
+    const target = isRecord(round.target) ? round.target : {};
+    const snapshotId = target.snapshot_id;
+    if (snapshotId === undefined || snapshotId === null || snapshotId === '') {
+        return fail('review-snapshot-required', 'round.target.snapshot_id is required for a new round', 'run review-dispatch execute for this scope and put its snapshot_id in round.target');
+    }
+    // 형식·존재·손상은 loader가 한 번에 가린다. 형식 검사 없이 경로에 쓰면 입력이 runtime 밖을 가리킨다.
+    const loaded = loadReviewSnapshot({ repoRoot, snapshotId: snapshotId });
+    if (!loaded.ok) {
+        return fail('review-snapshot-invalid', `${loaded.reason}: ${loaded.cause}`, loaded.next);
+    }
+    const stored = loaded.snapshot;
+    const scopeTask = task || null;
+    if (stored.scope.blueprint !== blueprintDir || stored.scope.task !== scopeTask) {
+        return fail('review-snapshot-mismatch', `snapshot scope ${JSON.stringify(stored.scope)} differs from this review`, 'run review-dispatch execute for this blueprint/task and use its snapshot_id');
+    }
+    if (target.base !== stored.target.base || target.head !== stored.target.head) {
+        return fail('review-snapshot-mismatch', 'round.target base/head differ from the snapshot target', 'copy target.base and target.head from the same review-dispatch execute output as snapshot_id');
+    }
+    if (!accepted)
+        return null;
+    const current = checkReviewSnapshotCurrent({
+        repoRoot,
+        blueprintDir,
+        taskId: scopeTask,
+        base: stored.target.base,
+        head: stored.target.head,
+        snapshotId: snapshotId,
+    });
+    if (current.ok)
+        return null;
+    // HEAD가 움직인 것도 "리뷰한 상태와 지금이 다르다"이므로 stale로 안내한다.
+    // 범위·target 차이는 위에서 이미 걸렀으므로 여기 남는 건 stale 계열과 수집 실패다.
+    if (current.reason === 'snapshot-stale' || current.reason === 'head-mismatch') {
+        return fail('review-snapshot-stale', `${current.reason}: ${current.cause}`, 'the worktree changed after the review snapshot; dispatch a new review on the current state '
+            + 'and re-review before accepting');
+    }
+    return fail('review-snapshot-invalid', `${current.reason}: ${current.cause}`, current.next);
+}
+/**
+ * 입력 finding을 정규화한 뒤 같은 id는 통째로 교체하고 새 id는 끝에 붙인다. fingerprint는
+ * 입력값과 무관하게 게이트와 같은 findingFingerprint로 덮어쓰고, `id` 키가 없으면
+ * `F-<8hex>` 자동 id를 채운다 — 작성자가 validator 공식을 몰라도 기록되게 한다.
+ * 기존 원장 finding은 고치지 않는다: 수기로 틀린 저장 기록은 G14/G21이 계속 거절해야 한다.
+ *
+ * @param {unknown[]} existing - 기존 findings
+ * @param {unknown[]} incoming - 입력 JSON findings
+ * @returns {{ok: true, merged: unknown[], incoming: unknown[], ids: string[]} | RecordReviewFail}
+ *   병합 결과, 정규화한 이번 입력, 이번 입력의 정규화 id(순서 유지·중복 제거), 또는 id 오류·충돌 거절
+ */
+function mergeFindings(existing, incoming) {
+    const normalized = normalizeRoundFindings(incoming, existing);
+    if (!normalized.ok) {
+        return fail('review-input-invalid', normalized.messages, 'give each finding a non-empty string id or omit the id key; resolve id collisions, then retry');
+    }
+    const merged = existing.map((item) => cloneJson(item));
+    for (const finding of normalized.findings) {
+        const id = isRecord(finding) ? finding.id : undefined;
+        const index = merged.findIndex((item) => isRecord(item) && item.id === id);
+        if (index >= 0)
+            merged[index] = finding;
+        else
+            merged.push(finding);
+    }
+    return { ok: true, merged, incoming: normalized.findings, ids: normalized.ids };
+}
+function readRoundInput(roundFile) {
+    let raw;
+    try {
+        raw = fs.readFileSync(roundFile, 'utf8');
+    }
+    catch (error) {
+        // ENOENT·EACCES를 파싱 실패와 같은 reason으로 묶는다. 입력 파일이 없으면
+        // 원장을 손대지 않아야 하고, 권한 오류를 target-missing으로 위장하면
+        // 없는 review.md를 만들라는 안내가 된다.
+        const cause = error && typeof error === 'object' && 'code' in error
+            ? String(error.code)
+            : String(error.message || error);
+        return fail('review-input-invalid', cause, 'fix --round JSON: object with round and findings array');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        // SyntaxError만 흡수. 그 외 throw는 JSON 파서가 아닌 호출부 버그다.
+        if (!(error instanceof SyntaxError))
+            throw error;
+        return fail('review-input-invalid', error.message, 'fix --round JSON: object with round and findings array');
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.round)) {
+        return fail('review-input-invalid', 'round object missing', 'fix --round JSON: object with round and findings array');
+    }
+    if (!Array.isArray(parsed.findings)) {
+        return fail('review-input-invalid', 'findings must be an array', 'fix --round JSON: object with round and findings array');
+    }
+    return { round: parsed.round, findings: parsed.findings };
+}
+/**
+ * review.md를 읽어 쓰기용 사본과 bouncer·review 블록을 돌려준다. recordReview와
+ * acceptReviewRisk가 같은 방식으로 문서를 열도록 한 곳에 둔다.
+ *
+ * @param {string} abs - review.md 절대 경로
+ * @returns {{ nextData: Record<string, unknown>, body: string, bouncer: Record<string, unknown>,
+ *   review: Record<string, unknown> }} 편집 가능한 front matter 사본과 본문
+ */
+function loadReviewDoc(abs) {
+    const { data, body } = parseFrontmatter(fs.readFileSync(abs, 'utf8'));
+    const nextData = isRecord(data) ? cloneJson(data) : {};
+    if (!isRecord(nextData.bouncer))
+        nextData.bouncer = {};
+    const bouncer = nextData.bouncer;
+    if (!isRecord(bouncer.review))
+        bouncer.review = {};
+    const review = bouncer.review;
+    return { nextData, body, bouncer, review };
+}
+/**
+ * 검증을 통과한 review.md 본문을 임시 파일로 쓴 뒤 rename으로 교체한다. renameSync는
+ * 같은 디렉터리라 원자적이고, 실패하면 tmp를 지워 재시도가 깨진 바이트를 읽지 않게 한다.
+ *
+ * @param {string} abs - review.md 절대 경로
+ * @param {string} text - 렌더링된 문서 전체
+ * @returns {void}
+ */
+function writeReviewDocAtomically(abs, text) {
+    const tmp = path.join(path.dirname(abs), `.review.md.${process.pid}.tmp`);
+    try {
+        fs.writeFileSync(tmp, text);
+        fs.renameSync(tmp, abs);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch (unlinkError) {
+            // ENOENT만 흡수: rename이 이미 옮겼거나 write가 실패해 파일이 없다.
+            if (!isRecord(unlinkError) || unlinkError.code !== 'ENOENT')
+                throw unlinkError;
+        }
+        throw error;
+    }
+}
+/**
+ * 라운드 하나와 finding 갱신을 review.md에 기록한다. 쓰기는 collectFindingFailures가
+ * G21·G14와 같은 인자로 통과한 뒤에만 같은 디렉터리 임시 파일 + rename이다.
+ *
+ * @param {RecordReviewInput} input - repoRoot, blueprintDir, optional task/status, roundFile
+ * @param {string} input.repoRoot - 저장소 루트 절대 경로
+ * @param {string} input.blueprintDir - blueprint 상대 경로
+ * @param {string|null} [input.task] - task 리뷰일 때 세 자리 id. blueprint 모드면 없어야 함
+ * @param {string} input.roundFile - round·findings JSON 경로
+ * @param {string|null} [input.status] - 문서 bouncer.status. 없으면 기존 값을 유지
+ * @returns {RecordReviewResult} 성공 시 path·round·status·findings 수, 실패 시 reason·cause·next
+ */
+function recordReview(input) {
+    const repoRoot = input.repoRoot;
+    const blueprintDir = toPosix(input.blueprintDir);
+    const task = input.task == null || input.task === '' ? null : String(input.task);
+    const status = input.status == null || input.status === '' ? null : String(input.status);
+    // 1. JSON을 먼저 거절한다. 대상 파일 판정보다 입력이 틀리면 경로 안내가 섞인다.
+    const parsedInput = readRoundInput(input.roundFile);
+    if ('reason' in parsedInput)
+        return parsedInput;
+    const scope = reviewScopeAt(repoRoot, blueprintDir);
+    // 허용 밖 review_contract는 legacy로 접지 않고 거절한다. 파일을 읽기 전이라 바이트가 그대로다.
+    if (scope === 'contract_invalid')
+        return contractInvalid();
+    const blueprintScope = scope !== 'task';
+    const briefScope = scope === 'blueprint_brief';
+    if (blueprintScope && task) {
+        return fail('review-task-not-allowed', '--task is not allowed when review_scope is blueprint', 'omit --task and record the blueprint-root review.md');
+    }
+    if (!blueprintScope && !task) {
+        return fail('review-task-required', '--task is required when review_scope is not blueprint', 'pass --task <ddd> for tasks/<ddd>/review.md');
+    }
+    // 표식 없는 최종 리뷰는 discovery 한 라운드로 끝난다. 새 root delta는 파일을 읽기 전에 거절해
+    // 저장 문서가 바뀌지 않게 한다. 이미 저장된 discovery,delta,delta 이력은 G21이 계속 읽는다.
+    // 표식(brief) blueprint는 저장된 delta 유무를 알아야 하므로 아래에서 파일을 읽은 뒤 판정한다.
+    if (scope === 'blueprint' && parsedInput.round.mode === 'delta') {
+        return fail('final-review-single-round', 'blueprint final review is a single discovery round; a new delta round is not accepted', 'record the discovery round only; defer must_fix findings with a note or report them as blocked');
+    }
+    const rel = blueprintScope
+        ? `${blueprintDir}/review.md`
+        : `${blueprintDir}/tasks/${task}/review.md`;
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs)) {
+        return fail('review-target-missing', rel, 'scaffold the review.md for this blueprint or task, then retry');
+    }
+    const { nextData, body, bouncer, review } = loadReviewDoc(abs);
+    const existingRounds = Array.isArray(review.rounds) ? cloneJson(review.rounds) : [];
+    // 표식 blueprint는 위반을 고친 뒤 delta 한 번만 인증에 쓴다. 이미 delta가 저장돼 있으면 두 번째를
+    // 쓰기 전에 거절한다 — 남은 위반은 blocked로 보고하고 accept-risk가 닫는다.
+    if (briefScope && parsedInput.round.mode === 'delta'
+        && existingRounds.some((entry) => isRecord(entry) && entry.mode === 'delta')) {
+        return fail('final-review-single-round', 'brief final review allows discovery and one delta round; a second delta round is not accepted', 'discovery and one delta are used; report remaining violations as blocked');
+    }
+    const expectedRound = existingRounds.length + 1;
+    if (parsedInput.round.round !== expectedRound) {
+        return fail('review-round-out-of-sequence', `expected ${expectedRound}, got ${String(parsedInput.round.round)}`, `set round.round to ${expectedRound}`);
+    }
+    // 2. 라운드는 끝에만 붙인다. 중간 삽입은 번호 계약을 깨 G21과 어긋난다.
+    const mergedRounds = [...existingRounds, cloneJson(parsedInput.round)];
+    const existingFindings = Array.isArray(review.findings) ? review.findings : [];
+    const mergeResult = mergeFindings(existingFindings, parsedInput.findings);
+    if (!mergeResult.ok)
+        return mergeResult;
+    const mergedFindings = mergeResult.merged;
+    review.rounds = mergedRounds;
+    review.findings = mergedFindings;
+    if (status)
+        bouncer.status = status;
+    // 2-1. 스냅샷 바인딩은 원장 검증 앞에서 본다. 뒤에 두면 잘못된 id가 저장 검증기의
+    //      형식 메시지(review-ledger-invalid)로 먼저 나가 reason이 뭉개진다. 어느 쪽이든
+    //      쓰기 전이라 거절은 파일을 건드리지 않는다. accepted는 이번 --status뿐 아니라
+    //      상속한 상태도 포함한다.
+    const snapshotFailure = checkSnapshotBinding({
+        repoRoot,
+        blueprintDir,
+        task,
+        round: parsedInput.round,
+        accepted: bouncer.status === 'accepted',
+    });
+    if (snapshotFailure)
+        return snapshotFailure;
+    const messages = collectFindingFailures({
+        body,
+        findings: mergedFindings,
+        rounds: mergedRounds,
+        sectionLabel: 'review.md',
+        findingLabel: 'review',
+        allowedStatuses: EXECUTE_REVIEW_STATUS,
+        reviewStatus: bouncer.status,
+        // G21과 같은 계약으로 판정해야 기록과 마감 게이트가 서로 다른 답을 내지 않는다.
+        roundScope: briefScope ? 'blueprint_brief' : (blueprintScope ? 'blueprint' : undefined),
+    });
+    const sequenceOnly = messages.length === 1 && messages[0] === 'review rounds sequence invalid';
+    const inProgressOk = sequenceOnly
+        && isAllowedSequencePrefix(mergedRounds, scope)
+        && bouncer.status !== 'accepted';
+    if (messages.length > 0 && !inProgressOk) {
+        return fail('review-ledger-invalid', messages, 'fix rounds and findings until collectFindingFailures is empty, then retry');
+    }
+    // 3. 검증 통과 뒤에만 임시 파일을 만든다. 실패 경로에 tmp를 남기면 재시도가
+    //    깨진 바이트를 읽을 수 있다. renameSync는 같은 디렉터리라 원자적이다.
+    writeReviewDocAtomically(abs, renderDoc(nextData, body));
+    // 경고는 이번 round 입력만 대상으로 하고(기존 원장은 제외) 기록에는 영향을 주지 않는다.
+    // 자동 id가 경고 ids에도 보이도록 정규화 뒤 입력을 쓴다.
+    const warnings = validateSections.findingMergeCandidates(mergeResult.incoming);
+    return {
+        ok: true,
+        path: rel,
+        round: expectedRound,
+        status: bouncer.status,
+        findings: mergedFindings.length,
+        finding_ids: mergeResult.ids,
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
+}
+/**
+ * blueprint 최종 리뷰의 open finding 하나를 사용자가 수용한 위험으로 닫는다. 최종 리뷰는
+ * discovery 한 라운드로 끝나 blocked finding이 open으로 남는데, round를 더할 수 없으므로
+ * (final-review-single-round) 이 경로가 round 없이 finding만 accepted + accepted_risk로 바꾼다.
+ * 남은 open이 0이면 문서도 accepted로 올리고, 아니면 기존 status를 유지한다.
+ * `yes`가 없으면 파일을 읽기 전에 거절한다 — 사용자 승인 경계다.
+ * 쓰기는 recordReview와 같은 temp+rename이며 collectFindingFailures 통과 뒤에만 한다.
+ *
+ * @param {AcceptRiskInput} input - 수용 입력
+ * @param {string} input.repoRoot - 저장소 루트 절대 경로
+ * @param {string} input.blueprintDir - blueprint 상대 경로
+ * @param {string} input.finding - 닫을 finding id
+ * @param {string} input.note - 수용 사유. 공백뿐이면 거절
+ * @param {boolean} input.yes - 사용자 명시 승인 여부
+ * @returns {AcceptRiskOk | RecordReviewFail} 성공 시 path·finding·status·open_remaining, 실패 시 reason·cause·next
+ */
+function acceptReviewRisk(input) {
+    const { repoRoot } = input;
+    const blueprintDir = toPosix(input.blueprintDir);
+    // 1. 승인 경계는 어떤 I/O보다 먼저 본다.
+    if (input.yes !== true) {
+        return fail('review-accept-risk-confirmation-required', '--yes is required to record an accepted risk', 'ask the user to explicitly approve accepting this risk, then rerun with --yes');
+    }
+    const scope = reviewScopeAt(repoRoot, blueprintDir);
+    if (scope === 'contract_invalid')
+        return contractInvalid();
+    if (scope === 'task') {
+        return fail('review-accept-risk-task-scope', 'accept-risk is only available when review_scope is blueprint', 'task reviews cannot accept risk; fix the finding or record it through review record');
+    }
+    const rel = `${blueprintDir}/review.md`;
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs)) {
+        return fail('review-target-missing', rel, 'scaffold the review.md for this blueprint, then retry');
+    }
+    const { nextData, body, bouncer, review } = loadReviewDoc(abs);
+    const findings = Array.isArray(review.findings) ? review.findings : [];
+    const target = findings.find((item) => isRecord(item) && item.id === input.finding);
+    if (!isRecord(target)) {
+        return fail('review-finding-missing', `finding ${input.finding} not found in ${rel}`, 'pass an existing --finding id');
+    }
+    if (target.status !== 'open') {
+        return fail('review-finding-not-open', `finding ${input.finding} status is ${String(target.status)}`, 'only an open finding can be accepted as a risk');
+    }
+    const note = typeof input.note === 'string' ? input.note.trim() : '';
+    if (note === '') {
+        return fail('review-note-required', '--note is empty', 'pass the reason the user accepted this risk');
+    }
+    // 2. 대상 finding만 바꾼다. rounds와 다른 finding은 손대지 않는다.
+    target.status = 'accepted';
+    target.accepted_risk = true;
+    target.note = note;
+    const openRemaining = findings.filter((item) => isRecord(item) && item.status === 'open').length;
+    if (openRemaining === 0)
+        bouncer.status = 'accepted';
+    const messages = collectFindingFailures({
+        body,
+        findings,
+        rounds: review.rounds,
+        sectionLabel: 'review.md',
+        findingLabel: 'review',
+        allowedStatuses: EXECUTE_REVIEW_STATUS,
+        reviewStatus: bouncer.status,
+        roundScope: scope === 'blueprint_brief' ? 'blueprint_brief' : 'blueprint',
+    });
+    // 남은 open이 있는 부분 수용은 문서가 requested라 정상이다. 완결 순서 검사만 접두 예외를 건다.
+    const sequenceOnly = messages.length === 1 && messages[0] === 'review rounds sequence invalid';
+    const inProgressOk = sequenceOnly
+        && Array.isArray(review.rounds)
+        && isAllowedSequencePrefix(review.rounds, scope)
+        && bouncer.status !== 'accepted';
+    if (messages.length > 0 && !inProgressOk) {
+        return fail('review-ledger-invalid', messages, 'fix rounds and findings until collectFindingFailures is empty, then retry');
+    }
+    // 3. 검증 통과 뒤에만 쓴다. recordReview와 같은 temp+rename.
+    writeReviewDocAtomically(abs, renderDoc(nextData, body));
+    return {
+        ok: true, path: rel, finding: input.finding, status: bouncer.status, open_remaining: openRemaining,
+    };
+}
+module.exports = { recordReview, acceptReviewRisk };

package/dist/review-repair-state.js

@@ -0,0 +1,52 @@
+'use strict';
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const coordinatorWorker = require("./coordinator-worker");
+const { readBouncerBlock } = coordinatorWorker;
+/**
+ * 원장 decisions에 리뷰 원인 repair(`kind: 'repair'`, `failure.command: 'review'`)가 이미 있는지
+ * 판정한다. 입력 배열만 읽고 바꾸지 않는 순수 predicate라 호출자가 같은 원장에서 같은 답을 얻는다.
+ *
+ * @param {readonly unknown[] | undefined} decisions - 원장 decisions(부재 허용)
+ * @returns {boolean} 리뷰 원인 repair decision이 있으면 true
+ */
+function hasReviewRepairDecision(decisions) {
+    return (decisions || []).some((entry) => {
+        const item = entry;
+        return item?.kind === 'repair' && item.failure?.command === 'review';
+    });
+}
+/**
+ * review.md의 `bouncer.review.rounds[]`에 주어진 mode의 라운드가 있는지 읽는다.
+ * 오류 의미는 호출자 정책으로 갈린다. 이 차이는 의도된 유지이며 통일하지 않는다.
+ * - strict: 문서 부재(ENOENT)만 false로 흡수한다. YAML 파손 같은 다른 실패를 없음으로 접으면
+ *   이미 끝난 리뷰에 repair·supplement가 다시 열리므로 그대로 던진다(repair 접수 경계용).
+ * - tolerant: 문서 부재·frontmatter 없음·깨진 YAML을 없음으로 본다. 판독 불가를 예외로 올리면
+ *   다음 작업 선택이 막히기 때문이다. 그 밖의 I/O 오류는 readBouncerBlock이 그대로 던진다.
+ *
+ * @param {{ file: string; error_policy: RoundErrorPolicy }} input - review.md 절대 경로와 오류 정책
+ * @param {'discovery' | 'delta'} mode - 찾을 라운드 mode
+ * @returns {boolean} 해당 mode 라운드가 있으면 true
+ */
+function reviewRoundExists(input, mode) {
+    let review;
+    if (input.error_policy === 'strict') {
+        let data;
+        try {
+            data = readDoc(input.file).data;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+        review = data?.bouncer?.review;
+    }
+    else {
+        review = readBouncerBlock(input.file)?.review;
+    }
+    const rounds = review?.rounds;
+    return Array.isArray(rounds)
+        && rounds.some((round) => round?.mode === mode);
+}
+module.exports = { hasReviewRepairDecision, reviewRoundExists };