@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/migrate-task-layout.js

@@ -0,0 +1,194 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync: realExecFileSync } = require('node:child_process');
+const layout = require("./layout");
+const { CONTEXT_ROOT, isCanonicalBlueprintDir } = layout;
+const contextIds = require("./context-ids");
+const { parseContextPath } = contextIds;
+const paths = require("./paths");
+const { toPosix, parsePathIds } = paths;
+const frontmatter = require("./frontmatter");
+const { parseFrontmatter } = frontmatter;
+const render = require("./render");
+const { renderDoc } = render;
+const runtimeState = require("./runtime-state");
+const { readRuntimeCurrent, writeRuntimeCurrent, isWorktreeDirty } = runtimeState;
+const tasksDocs = require("./tasks-docs");
+const { expectedTaskDocIds } = tasksDocs;
+const NUMBERED = /^tasks-(\d{3})\.md$/;
+/** context 트리의 .md 절대 경로를 모은다. migrate-ids 제거 후 이 파일만 쓴다. */
+function walkMarkdownFiles(absDir, out = []) {
+    if (!fs.existsSync(absDir))
+        return out;
+    let entries;
+    try {
+        entries = fs.readdirSync(absDir);
+    }
+    catch (_e) {
+        return out;
+    }
+    for (const name of entries) {
+        const abs = path.join(absDir, name);
+        let st;
+        try {
+            st = fs.statSync(abs);
+        }
+        catch (_e) {
+            continue;
+        }
+        if (st.isDirectory())
+            walkMarkdownFiles(abs, out);
+        else if (name.endsWith('.md'))
+            out.push(abs);
+    }
+    return out;
+}
+function legacyUnits(repoRoot) {
+    const units = [];
+    for (const abs of walkMarkdownFiles(path.join(repoRoot, CONTEXT_ROOT))) {
+        const name = path.basename(abs);
+        const matched = NUMBERED.exec(name);
+        if (name !== 'tasks.md' && !matched)
+            continue;
+        const blueprint = toPosix(path.relative(repoRoot, path.dirname(abs)));
+        // 이 이관은 번호 형식(`ddd-slug`) blueprint의 구 레이아웃만 대상이다. slug 형식은 처음부터 새 레이아웃이라
+        // 이관할 것이 없으므로 범위 밖이다. 형식 판정은 context-ids 한 곳에 맡긴다.
+        if (!isCanonicalBlueprintDir(blueprint) || parseContextPath(blueprint)?.format !== 'numeric')
+            continue;
+        units.push({
+            blueprint,
+            number: name === 'tasks.md' ? '001' : matched[1],
+            tasks: toPosix(path.relative(repoRoot, abs)),
+        });
+    }
+    return units.sort((a, b) => a.tasks.localeCompare(b.tasks));
+}
+function planTaskLayout(repoRoot) {
+    const units = legacyUnits(repoRoot);
+    const plan = [];
+    for (const unit of units) {
+        plan.push({ from: unit.tasks, to: `${unit.blueprint}/tasks/${unit.number}/tasks.md` });
+    }
+    const grouped = new Map();
+    for (const unit of units) {
+        grouped.set(unit.blueprint, [...(grouped.get(unit.blueprint) || []), unit]);
+    }
+    for (const [bp, entries] of grouped) {
+        for (const leaf of ['verification.md', 'review.md']) {
+            const from = `${bp}/${leaf}`;
+            if (fs.existsSync(path.join(repoRoot, from))) {
+                plan.push({
+                    from,
+                    to: `${bp}/tasks/${entries.sort((a, b) => a.number.localeCompare(b.number))[0].number}/${leaf}`,
+                });
+            }
+        }
+    }
+    return { units, plan };
+}
+function validateTaskLayout(repoRoot, plan, deps) {
+    const reasons = [];
+    const d = deps || {};
+    if (plan.units.length && (d.isWorktreeDirty || isWorktreeDirty)(repoRoot, (d.execFileSync || realExecFileSync))) {
+        reasons.push('dirty-worktree: commit or stash changes before apply');
+    }
+    for (const unit of plan.units) {
+        if (fs.existsSync(path.join(repoRoot, unit.blueprint, 'tasks'))) {
+            reasons.push(`mixed-layout: ${unit.blueprint}`);
+        }
+    }
+    for (const step of plan.plan) {
+        if (fs.existsSync(path.join(repoRoot, step.to))) {
+            reasons.push(`collision: destination already exists: ${step.to}`);
+        }
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+function rewrite(rel, repoRoot, number) {
+    const abs = path.join(repoRoot, rel);
+    const { data, body } = parseFrontmatter(fs.readFileSync(abs, 'utf8'));
+    const doc = data;
+    doc.resource = rel;
+    // 묶음 안의 id는 디렉터리 번호에서 나온다. blueprint id를 쓰던 레거시 문서를
+    // 그대로 두면 옮긴 직후 S5로 스스로 거절당한다.
+    const ids = expectedTaskDocIds(number);
+    const byType = {
+        'bouncer.tasks': ids.tasks,
+        'bouncer.verification': ids.verification,
+        'bouncer.review': ids.review,
+    };
+    // data.type이 키일 때만 id를 쓴다. bouncer 부재 시 예전처럼 TypeError.
+    if (byType[doc.type]) {
+        doc.bouncer.id = byType[doc.type];
+    }
+    fs.writeFileSync(abs, renderDoc(doc, body));
+}
+function pending(repoRoot, bp, number, kind) {
+    const { epicId, blueprintId } = parsePathIds(bp);
+    const ids = expectedTaskDocIds(number);
+    const rel = `${bp}/tasks/${number}/${kind}.md`;
+    const data = {
+        type: `bouncer.${kind}`,
+        title: `${number} ${kind}`,
+        description: `${kind} for ${number}`,
+        resource: rel,
+        tags: ['bouncer', kind],
+        timestamp: new Date().toISOString(),
+        bouncer: {
+            id: kind === 'verification' ? ids.verification : ids.review,
+            epic_id: epicId,
+            blueprint_id: blueprintId,
+            status: 'pending',
+        },
+    };
+    if (kind === 'review')
+        data.bouncer.review = { required: true };
+    fs.writeFileSync(path.join(repoRoot, rel), renderDoc(data, `# ${kind}\n\n## ${kind === 'review' ? 'Findings' : 'Command'}\n`));
+    return rel;
+}
+function migrateTaskLayout({ repoRoot, dryRun = false, deps }) {
+    const plan = planTaskLayout(repoRoot);
+    const checked = validateTaskLayout(repoRoot, plan, deps);
+    if (dryRun || !checked.ok) {
+        return {
+            ok: checked.ok,
+            dryRun,
+            plan: plan.plan,
+            moved: [],
+            rewritten: [],
+            pointer: null,
+            warnings: checked.reasons,
+        };
+    }
+    const d = deps || {};
+    const move = d.move || ((from, to) => (d.execFileSync || realExecFileSync)('git', ['mv', from, to], { cwd: repoRoot, stdio: 'ignore' }));
+    for (const step of plan.plan) {
+        fs.mkdirSync(path.dirname(path.join(repoRoot, step.to)), { recursive: true });
+        move(step.from, step.to);
+    }
+    const rewritten = [];
+    for (const unit of plan.units) {
+        for (const kind of ['tasks', 'verification', 'review']) {
+            const rel = `${unit.blueprint}/tasks/${unit.number}/${kind}.md`;
+            if (fs.existsSync(path.join(repoRoot, rel))) {
+                rewrite(rel, repoRoot, unit.number);
+                rewritten.push(rel);
+            }
+            else
+                rewritten.push(pending(repoRoot, unit.blueprint, unit.number, kind));
+        }
+    }
+    let pointer = null;
+    const current = readRuntimeCurrent({ repoRoot });
+    const match = current && plan.units.find((u) => u.blueprint === current.blueprint && u.tasks === current.task);
+    if (match) {
+        const task = `${match.blueprint}/tasks/${match.number}/tasks.md`;
+        writeRuntimeCurrent({
+            repoRoot, blueprint: current.blueprint, base: current.base, task,
+        });
+        pointer = { from: current.task, to: task };
+    }
+    return { ok: true, plan: plan.plan, moved: plan.plan, rewritten, pointer, warnings: [] };
+}
+module.exports = { migrateTaskLayout, planTaskLayout, validateTaskLayout };

package/dist/path-overlap.js

@@ -0,0 +1,38 @@
+'use strict';
+// 경로 겹침 규칙의 정본. 문서 검증(validate-sections)이 소유하면 scope·dag-shape·
+// execution-dag 같은 하위 모듈이 규칙 하나 때문에 검증 계층을 가져와야 한다.
+// 그래서 I/O 없는 별도 모듈로 두고 validate-sections는 같은 이름으로 재export한다.
+/**
+ * 두 경로가 같거나 한쪽이 다른 쪽의 조상 디렉터리인지 판정한다.
+ * 디렉터리 prefix도 교차로 본다. `scripts/` 금지가 `scripts/lib/x.js`를
+ * 통과시키면 scope 충돌 판정이 파일 단위 affected_paths를 놓친다.
+ *
+ * @param {string} a - 한쪽 경로(`./`·trailing `/`는 호출자가 미리 정규화한다)
+ * @param {string} b - 다른 쪽 경로
+ * @returns {boolean} 같거나 조상·자손 관계이면 true
+ */
+function pathsOverlap(a, b) {
+    return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+/**
+ * pathsOverlap에 넘기기 전에 경로 표기만 맞추는 정규화의 정본. 비교 알고리즘은 바꾸지 않는다.
+ * 문서·Checklist·원장은 `src/`·`./src/a.ts`·Windows식 `src\\a.ts`처럼 표기가 갈리는데,
+ * pathsOverlap은 그 형태를 조상으로 보지 못하므로 호출 전에 같은 모양으로 벗겨야 한다.
+ * 경로 겹침(execution-dag)과 scope 비교(finalize-digest)가 따로 정규화하면 한쪽만 고쳐
+ * 판정이 갈라지므로 이 함수 하나만 쓴다. 이 모듈은 import가 없어야 해서
+ * 역슬래시 변환(posix-path의 toPosix와 같은 규칙)도 여기에 직접 둔다.
+ *
+ * @param {string} raw - affected_paths/scope.paths 항목 또는 변경 경로
+ * @returns {string} 역슬래시를 `/`로 바꾸고 선행 `./`·말미 `/`(단독 `/` 제외)를 제거한 경로
+ */
+function normalizeOverlapPath(raw) {
+    let p = raw.replace(/\\/g, '/');
+    // 1. 문서·lease가 상대경로를 `./foo`·`././foo`로 적는 경우 — 동일 경로를 놓치지 않게 접두만 반복 제거
+    while (p.startsWith('./'))
+        p = p.slice(2);
+    // 2. 디렉터리 표기 `src/` → `src`. bare `/`는 루트 의미가 있어 유지한다.
+    if (p.length > 1 && p.endsWith('/'))
+        p = p.slice(0, -1);
+    return p;
+}
+module.exports = { pathsOverlap, normalizeOverlapPath };

package/dist/paths.js

@@ -0,0 +1,45 @@
+'use strict';
+const tasksDocs = require("./tasks-docs");
+const posixPath = require("./posix-path");
+const contextIds = require("./context-ids");
+const { unitDocKind } = tasksDocs;
+// 기존 31개 import 호환을 위해 posix-path 정본을 그대로 re-export한다.
+const { toPosix } = posixPath;
+const { parseContextPath } = contextIds;
+const FILE_KIND = {
+    // verification.md / review.md / tasks.md 는 tasks-docs.unitDocKind 로만 판정.
+    // 문자열을 여기 두면 묶음 basename 정본이 갈라진다.
+    'explain.md': 'explain',
+    // BP 루트 문서. task 묶음 basename이 아니므로 tasks-docs에 넣지 않는다.
+    'context-review.md': 'context_review',
+};
+function isNumericContextId(id) {
+    return typeof id === 'string' && /^\d{3}$/.test(id);
+}
+function parsePathIds(resourcePath) {
+    const norm = toPosix(resourcePath);
+    // 세그먼트 해석은 context-ids 한 곳에서 한다. 번호 경로는 예전과 같은 key를,
+    // slug 경로는 slug key를 epicId/blueprintId 자리에 담는다.
+    const ids = parseContextPath(norm);
+    const epicId = ids ? ids.epicKey : null;
+    const blueprintId = ids ? ids.blueprintKey : null;
+    // pop()은 string | undefined라 인덱스에 바로 못 쓴다. split 결과는 항상
+    // 한 칸 이상이라 마지막 칸을 쓰면 런타임 값이 같고 타입만 닫힌다.
+    const segments = norm.split('/');
+    const base = segments[segments.length - 1];
+    let kind = FILE_KIND[base] || null;
+    // 루트·tasks/<NNN>/ 모두 basename 으로 kind 를 본다.
+    // tasks/002/tasks.md → tasks, …/verification.md → verification.
+    if (!kind)
+        kind = unitDocKind(base);
+    if (base === 'index.md') {
+        kind = blueprintId ? 'blueprint' : (epicId ? 'epic' : null);
+    }
+    return { epicId, blueprintId, kind };
+}
+function epicDirOf(blueprintDir) {
+    return toPosix(blueprintDir).split('/blueprints/')[0];
+}
+module.exports = {
+    parsePathIds, epicDirOf, toPosix, isNumericContextId,
+};

package/dist/plan-approve.js

@@ -0,0 +1,218 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const layout = require("./layout");
+const { isCanonicalBlueprintDir } = layout;
+const paths = require("./paths");
+const { toPosix, epicDirOf } = paths;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const render = require("./render");
+const { renderDoc } = render;
+const epicRegistry = require("./epic-registry");
+const { readEpicRegistry } = epicRegistry;
+const tasksDocs = require("./tasks-docs");
+const { listTasksDocs } = tasksDocs;
+const contextIds = require("./context-ids");
+const schema = require("./schema");
+const validateGatesPlan = require("./validate-gates-plan");
+const { planPrerequisiteFailures, PREREQUISITE_NEXT } = validateGatesPlan;
+const planPrerequisites = require("./plan-prerequisites");
+const { prerequisiteFormatIssues } = planPrerequisites;
+const { parseContextPath } = contextIds;
+function fail(reason, cause, next) {
+    return { ok: false, reason, cause, next };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 같은 디렉터리 임시 파일에 쓴 뒤 rename한다. 쓰기 도중 죽어도 대상 파일은
+ * 옛 바이트 또는 새 바이트 중 하나로만 남는다. 실패하면 임시 파일을 지우고 재던진다.
+ *
+ * @param {string} abs - 대상 파일 절대 경로
+ * @param {string} text - 새 파일 내용
+ * @returns {void}
+ */
+function atomicWriteFile(abs, text) {
+    // 임시 이름은 무작위 접미사 + 배타 생성('wx')이라 예측해 미리 심어 둔 파일이나
+    // 심볼릭 링크를 따라가 엉뚱한 곳에 쓰는 일이 없다(이미 있으면 EEXIST로 실패).
+    const tmp = path.join(path.dirname(abs), `.${path.basename(abs)}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+    // 대상의 기존 권한을 보존한다. 임시 파일은 umask 기본 모드로 생기므로 rename 전에 맞춘다.
+    // stat 실패(대상 부재 등)는 호출자가 이미 readDoc으로 걸러 이쪽이 던지면 그대로 실패시킨다.
+    const mode = fs.statSync(abs).mode & 0o7777;
+    try {
+        fs.writeFileSync(tmp, text, { flag: 'wx', mode });
+        // writeFileSync의 mode는 umask에 깎이므로 chmod로 정확한 값을 되돌린다.
+        fs.chmodSync(tmp, mode);
+        fs.renameSync(tmp, abs);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch (unlinkError) {
+            // ENOENT만 흡수: write가 실패했거나 rename이 이미 옮겨 임시 파일이 없다.
+            if (!isRecord(unlinkError) || unlinkError.code !== 'ENOENT')
+                throw unlinkError;
+        }
+        throw error;
+    }
+}
+/**
+ * 한 문서를 읽어 `bouncer.status` 전이 계획을 만든다. 파일은 쓰지 않는다.
+ *
+ * @param {string} repoRoot - 저장소 루트 절대 경로
+ * @param {string} rel - 저장소 상대 POSIX 경로
+ * @param {string} target - 목표 상태(`approved`/`ready`)
+ * @returns {Plan | ApproveFail} 계획, 읽기·형태 실패면 `plan-approve-target`, 전이 불가 상태면 `plan-approve-status`
+ */
+function planDoc(repoRoot, rel, target) {
+    const abs = path.join(repoRoot, rel);
+    let doc;
+    try {
+        doc = readDoc(abs);
+    }
+    catch (error) {
+        // 부재·권한·YAML 오류를 모두 "대상을 읽을 수 없음"으로 보고하되 원인 문구는 남긴다.
+        const detail = error instanceof Error ? error.message : String(error);
+        return fail('plan-approve-target', `${rel}: ${detail}`, 'create or repair the document, then retry');
+    }
+    const data = doc.data;
+    const bouncer = isRecord(data) ? data.bouncer : undefined;
+    if (!isRecord(data) || !isRecord(bouncer)) {
+        return fail('plan-approve-target', `${rel}: missing bouncer frontmatter`, 'repair the frontmatter, then retry');
+    }
+    const status = bouncer.status;
+    if (status !== 'draft' && status !== target) {
+        return fail('plan-approve-status', `${rel}: status is ${String(status)}, expected draft or ${target}`, 'only draft documents can be approved; resolve the status manually');
+    }
+    return { rel, abs, data, body: doc.body, target, needsWrite: status === 'draft' };
+}
+/**
+ * plan 승인 뒤 epic·blueprint·task의 `bouncer.status`를 한 번에 전이한다.
+ * 모든 대상을 먼저 읽고 판정한 뒤에만 쓰므로, 판정 거절에서는 파일이 바뀌지 않는다.
+ * 이미 목표 상태인 문서는 건드리지 않아 재실행이 멱등이다.
+ * 판정 뒤 쓰기 도중 I/O 실패는 `plan-approve-write`로 끝나며 이미 쓴 `changed`를 싣는다.
+ * 사용자 승인은 추론하지 않는다 — 호출 시점이 곧 plan 스킬의 승인 뒤라는 약속이다.
+ *
+ * @param {object} args - 인자 묶음
+ * @param {string} args.repoRoot - 저장소 루트 절대 경로
+ * @param {string} args.blueprintDir - 저장소 상대 blueprint 디렉터리
+ * @param {ApproveDeps} [args.deps] - 테스트 seam. `writeFile(abs, text)`는 한 파일의 원자 쓰기를 대신한다
+ * @returns {ApproveOk | ApproveFail} 성공이면 정렬된 changed·unchanged, 아니면 reason·cause·next
+ */
+function approvePlan({ repoRoot, blueprintDir, deps = {} }) {
+    const writeFile = deps.writeFile || atomicWriteFile;
+    // 1. 경로 검증: 저장소 안 정본 blueprint 경로만 받는다. `..`/절대 경로는
+    //    정본 정규식이 이미 걸러내지만, 의도를 분명히 하려고 먼저 거절한다.
+    const bp = toPosix(blueprintDir).replace(/\/+$/, '');
+    if (bp === '' || path.isAbsolute(bp) || bp.split('/').includes('..') || !isCanonicalBlueprintDir(bp)) {
+        return fail('plan-approve-target', `${blueprintDir}: not a canonical blueprint directory inside the repository`, 'pass --blueprint .bouncer/context/epics/<ddd-name>/blueprints/<ddd-name>');
+    }
+    // 2. task 열거: 레거시·잘못된 디렉터리·깨진 frontmatter는 승인 대상을 확정할 수 없다.
+    const listing = listTasksDocs({ repoRoot, blueprintDir: bp });
+    const listingProblems = [];
+    if (listing.legacy)
+        listingProblems.push(`${bp}: legacy root task files present`);
+    for (const dir of listing.invalidDirs)
+        listingProblems.push(`${bp}/tasks/${dir}: invalid task directory`);
+    for (const entry of listing.entries) {
+        if (entry.executionKind === null)
+            listingProblems.push(`${entry.tasks.rel}: unreadable tasks.md frontmatter`);
+    }
+    if (listingProblems.length > 0) {
+        return fail('plan-approve-target', listingProblems, 'repair the task layout, then retry');
+    }
+    if (listing.entries.length === 0) {
+        return fail('plan-approve-target', `${bp}: no tasks/<NNN>/tasks.md documents`, 'scaffold tasks before approving');
+    }
+    // 3. 문서별 계획. blueprint를 먼저 읽어야 scale을 알고 context-review 검사를 가른다.
+    const bpPlan = planDoc(repoRoot, `${bp}/index.md`, 'approved');
+    if ('ok' in bpPlan)
+        return bpPlan;
+    // legacy epic의 draft blueprint는 승인하지 않는다(쓰기 전 거절). 이미 approved인 blueprint의
+    // 재승인은 진행 중 실행을 막지 않으려고 통과시킨다. 등록부 부재·invalid·미등록 epic은 기존 동작.
+    if (bpPlan.needsWrite) {
+        const epicLeaf = epicDirOf(bp).split('/').pop() || '';
+        // 번호 epic은 옛 번호(v1 id, v2 legacy_id)로, slug epic은 slug로 등록부 항목을 찾는다.
+        // 경로가 해석되지 않으면(비정규 이름) 등록부 대조를 건너뛰는 기존 동작을 유지한다.
+        const ids = parseContextPath(bp);
+        const registryRead = readEpicRegistry(repoRoot);
+        if (ids && registryRead.status === 'ok'
+            && registryRead.registry.epics.some((e) => e.kind === 'legacy'
+                && (ids.format === 'slug' ? e.slug === ids.epicKey : (e.legacy_id ?? e.id) === ids.epicKey))) {
+            return fail('plan-approve-legacy-epic', `${epicLeaf}: legacy epic takes no new blueprints`, 'plan the new blueprint under a registry epic (common or domain in .bouncer/epics.json)');
+        }
+    }
+    const epicPlan = planDoc(repoRoot, `${epicDirOf(bp)}/index.md`, 'approved');
+    if ('ok' in epicPlan)
+        return epicPlan;
+    const taskPlans = [];
+    for (const entry of listing.entries) {
+        const plan = planDoc(repoRoot, entry.tasks.rel, 'ready');
+        if ('ok' in plan)
+            return plan;
+        taskPlans.push(plan);
+    }
+    // 4. full blueprint는 context review가 accepted여야 한다. 표식 없는 light만 건너뛴다
+    //    (부재는 full). 표식 light는 verifiability 리뷰를 받으므로 full과 같은 사유·next로 막는다.
+    //    잘못된 표식 값(null)은 S38이 이 gate 앞에서 이미 거절하므로 여기서는 legacy로 읽혀도 안전하다.
+    const bpBouncer = bpPlan.data.bouncer;
+    if (bpBouncer.scale !== 'light' || schema.planReviewContractOf(bpBouncer) === 'brief') {
+        const crRel = `${bp}/context-review.md`;
+        let crStatus;
+        try {
+            const crBouncer = readDoc(path.join(repoRoot, crRel)).data.bouncer;
+            crStatus = isRecord(crBouncer) ? crBouncer.status : undefined;
+        }
+        catch (_error) {
+            // 부재·파싱 실패는 "accepted 아님"으로만 접는다. 복구는 context-review 명령 소관이라
+            // 여기서는 거절 사유와 다음 행동만 알려준다.
+            crStatus = undefined;
+        }
+        if (crStatus !== 'accepted') {
+            return fail('plan-approve-context-review', `${crRel}: status is ${crStatus === undefined ? 'missing' : String(crStatus)}, expected accepted`, 'run bouncer context-review close until the review is accepted, then retry');
+        }
+    }
+    // 4b. 선언된 선행 blueprint가 현재 checkout에 병합돼 있어야 한다. draft·정식 plan gate와 같은
+    //     helper라 세 경로의 G32 답이 같다. 어떤 문서도 쓰기 전에 거절해 거절 뒤 바이트가 그대로다.
+    //     형식 오류(HEAD·짧은 SHA·추가 키·비정본 경로·중복·자기참조)는 G32 helper의 entries에서 빠져
+    //     통과해 버리므로, 같은 형식 판정(S39)을 여기서 먼저 적용해 쓰기 전에 거절한다.
+    const formatIssues = prerequisiteFormatIssues(bpBouncer.prerequisites, bp);
+    if (formatIssues.length > 0) {
+        return fail('plan-approve-prerequisite', formatIssues.map((m) => `S39 ${m}`), PREREQUISITE_NEXT);
+    }
+    const prerequisiteFailures = planPrerequisiteFailures({
+        repoRoot, blueprintDir: bp, file: `${bp}/index.md`, exec: deps.exec,
+    });
+    if (prerequisiteFailures.length > 0) {
+        return fail('plan-approve-prerequisite', prerequisiteFailures.map((f) => `${f.code} ${f.message}`), PREREQUISITE_NEXT);
+    }
+    // 5. 판정 통과 — 이제부터만 쓴다. 순서는 epic → blueprint → tasks.
+    const all = [epicPlan, bpPlan, ...taskPlans];
+    const unchanged = all.filter((p) => !p.needsWrite).map((p) => p.rel).sort();
+    const changed = [];
+    for (const plan of all) {
+        if (!plan.needsWrite)
+            continue;
+        // 키 순서와 본문을 보존하려고 status 값만 제자리에서 바꾼다.
+        plan.data.bouncer.status = plan.target;
+        try {
+            writeFile(plan.abs, renderDoc(plan.data, plan.body));
+        }
+        catch (error) {
+            // 모든 쓰기 실패를 plan-approve-write로 접는 것은 안전하다: 판정이 이미 끝났고
+            // 재실행이 이미 쓴 문서를 unchanged로 넘기며 이어 끝내기 때문이다.
+            const detail = error instanceof Error ? error.message : String(error);
+            return {
+                ...fail('plan-approve-write', `${plan.rel}: ${detail}`, 'fix the I/O problem and rerun the same command'),
+                changed: [...changed].sort(),
+            };
+        }
+        changed.push(plan.rel);
+    }
+    return { ok: true, changed: changed.sort(), unchanged };
+}
+module.exports = { approvePlan };