@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/layout.js

@@ -0,0 +1,131 @@
+'use strict';
+const paths = require("./paths");
+const { toPosix } = paths;
+const contextIds = require("./context-ids");
+const { parseContextPath } = contextIds;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const fs = require('node:fs');
+const path = require('node:path');
+const CONTEXT_ROOT = '.bouncer/context';
+// Codex는 플러그인 `agents/*.md`를 named role로 읽지 않는다. 프로젝트
+// `.codex/agents/*.toml`만 스캔하므로 init이 여기에 심는다.
+const CODEX_AGENTS_DIR = '.codex/agents';
+// context 디렉터리의 위치(모양)만 정규식으로 본다. 세그먼트가 번호 형식(`ddd-slug`)인지 slug 형식인지는
+// 숫자 정규식을 여기 새로 두지 않고 context-ids.parseContextPath 한 곳에 맡긴다 — 호출부마다 정규식이
+// 있으면 두 형식의 경계가 갈라진다.
+const EPIC_DIR_SHAPE = /^\.bouncer\/context\/epics\/[^/]+$/;
+const BLUEPRINT_DIR_SHAPE = /^\.bouncer\/context\/epics\/[^/]+\/blueprints\/[^/]+$/;
+function normalizeRepoPath(value) {
+    return toPosix(value);
+}
+/**
+ * 정본 epic 디렉터리인지 본다. 번호(`ddd-slug`)와 slug 두 형식 모두 정본이다.
+ *
+ * @param {unknown} value - 저장소 상대 경로(백슬래시 허용)
+ * @returns {boolean} 위치가 `.bouncer/context/epics/<세그먼트>`이고 세그먼트가 해석되면 true
+ */
+function isCanonicalEpicDir(value) {
+    const norm = normalizeRepoPath(value);
+    return EPIC_DIR_SHAPE.test(norm) && parseContextPath(norm) !== null;
+}
+/**
+ * 정본 blueprint 디렉터리인지 본다. epic과 blueprint 세그먼트가 같은 형식이어야 한다 —
+ * 형식이 섞이면 parseContextPath가 null을 주므로 정본이 아니다.
+ *
+ * @param {unknown} value - 저장소 상대 경로(백슬래시 허용)
+ * @returns {boolean} 정본 blueprint 경로면 true
+ */
+function isCanonicalBlueprintDir(value) {
+    const norm = normalizeRepoPath(value);
+    return BLUEPRINT_DIR_SHAPE.test(norm) && parseContextPath(norm) !== null;
+}
+/**
+ * blueprint 경로가 정본이 아닌 이유가 slug 체계 위반인지 가린다. validate가 S10(일반 경로 오류)
+ * 대신 S37로 구체적인 사유를 내려 한다. 위치 모양이 맞지 않으면 null이다.
+ *
+ * - `format-mixed`: epic은 slug인데 blueprint는 번호 접두이거나 그 반대
+ * - `slug-invalid`: epic은 slug인데 blueprint 세그먼트가 slug 규칙(길이·문자)을 어김
+ * epic 세그먼트 자체가 해석되지 않는 경로(구형 `EPIC-` 접두 등)는 null로 두어 S10을 유지한다.
+ *
+ * @param {unknown} value - 저장소 상대 경로(백슬래시 허용)
+ * @returns {'format-mixed' | 'slug-invalid' | null} 위반 종류. 해당 없으면 null
+ */
+function blueprintPathProblem(value) {
+    const norm = normalizeRepoPath(value);
+    if (!BLUEPRINT_DIR_SHAPE.test(norm) || parseContextPath(norm) !== null)
+        return null;
+    const marker = '/blueprints/';
+    const cut = norm.lastIndexOf(marker);
+    const epic = parseContextPath(norm.slice(0, cut));
+    if (epic === null)
+        return null;
+    // blueprint 세그먼트를 epic 자리에 끼워 읽으면 같은 규칙으로 형식을 얻는다(규칙 사본을 두지 않기 위함).
+    const blueprint = parseContextPath(`${CONTEXT_ROOT}/epics/${norm.slice(cut + marker.length)}`);
+    if (blueprint !== null)
+        return blueprint.format === epic.format ? null : 'format-mixed';
+    return epic.format === 'slug' ? 'slug-invalid' : null;
+}
+/**
+ * blueprint `order`가 쓸 수 있는 값(양의 정수)인지 본다. scaffold·inspect·S37이 같은 판정을 쓰게 한 곳에 둔다.
+ *
+ * @param {unknown} value - frontmatter `bouncer.order` 값
+ * @returns {boolean} 양의 정수면 true
+ */
+function isValidBlueprintOrder(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+/**
+ * epic 아래 blueprint 디렉터리마다 index.md의 `order`·`id`를 읽어 돌려준다. 읽기 전용이다.
+ * 이름순으로 돌려줘 호출자의 판정(중복 검사 등)이 파일 시스템 열거 순서에 기대지 않게 한다.
+ * `blueprints/`가 없으면(ENOENT) 빈 목록이다. 개별 index.md를 읽거나 파싱하지 못하면 그 항목만
+ * order/id를 undefined로 둔다 — 문서 자체의 오류는 구조 검사(S1·S2·S37)가 따로 보고하므로,
+ * 형제 하나의 손상이 다른 blueprint의 order 판정을 막으면 안 된다.
+ *
+ * @param {string} repoRoot - 저장소 루트 절대 경로
+ * @param {string} epicDirRel - 저장소 상대 epic 디렉터리
+ * @returns {BlueprintOrderEntry[]} 이름순 blueprint 목록
+ * @throws {Error} `blueprints/`를 ENOENT 외 이유로 읽지 못할 때
+ */
+function listBlueprintOrders(repoRoot, epicDirRel) {
+    const epicRel = normalizeRepoPath(epicDirRel);
+    let names;
+    try {
+        names = fs.readdirSync(path.join(repoRoot, epicRel, 'blueprints'), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    names.sort();
+    return names.map((name) => {
+        const rel = `${epicRel}/blueprints/${name}`;
+        let order;
+        let id;
+        try {
+            const data = readDoc(path.join(repoRoot, rel, 'index.md')).data;
+            const bouncer = data && typeof data === 'object' ? data.bouncer : undefined;
+            if (bouncer && typeof bouncer === 'object') {
+                order = bouncer.order;
+                id = bouncer.id;
+            }
+        }
+        catch (_error) {
+            // 부재·YAML 오류는 "읽을 수 있는 order 없음"으로만 접는다(위 docstring 사유).
+        }
+        return { name, rel, order, id };
+    });
+}
+module.exports = {
+    CONTEXT_ROOT,
+    CODEX_AGENTS_DIR,
+    normalizeRepoPath,
+    isCanonicalEpicDir,
+    isCanonicalBlueprintDir,
+    blueprintPathProblem,
+    isValidBlueprintOrder,
+    listBlueprintOrders,
+};

package/dist/lease.js

@@ -0,0 +1,145 @@
+'use strict';
+/**
+ * task에 새 active lease를 발급한다. ledger.leaseSeq를 1 올리고 generation은
+ * 직전 lease(없으면 0)에서 1 증가시킨다 — revoke 후 재배정이 같은 id를 쓰지
+ * 않게 하고, scope 충돌 시 seq로 후발을 고르기 위함이다.
+ *
+ * @param {LeaseLedger} ledger - leaseSeq를 올리는 원장
+ * @param {LeaseTask} task - lease를 받을 task
+ * @param {() => string} makeId - lease id 생성기(테스트 seam은 고정값)
+ * @returns {Lease} 발급된 active lease
+ */
+function issueLease(ledger, task, makeId) {
+    const previousGeneration = task.lease && Number.isInteger(task.lease.generation)
+        ? task.lease.generation
+        : 0;
+    const nextSeq = (Number.isInteger(ledger.leaseSeq) ? ledger.leaseSeq : 0) + 1;
+    ledger.leaseSeq = nextSeq;
+    const lease = {
+        id: makeId(),
+        generation: previousGeneration + 1,
+        seq: nextSeq,
+        status: 'active',
+    };
+    task.lease = lease;
+    return lease;
+}
+/**
+ * 배정을 무효화한다. lease가 있으면 revoked로 표시하고, 없으면 legacy로 남겨
+ * 새 lease를 만들지 않는다. dispatch·sha를 비우고 status를 pending으로 돌린다.
+ *
+ * @param {LeaseLedger} ledger - decision을 append할 원장
+ * @param {LeaseTask} task - revoke 대상
+ * @param {{ reason: string, previousHead: string | null }} opts - 감사 필드
+ * @returns {RevokeDecision} 원장·task decisions에 붙인 revoke 기록
+ */
+function revokeLease(ledger, task, opts) {
+    const previousStatus = task.status || 'pending';
+    const hadLease = task.lease !== undefined && task.lease !== null;
+    // legacy(lease 없음)는 필드를 새로 만들지 않는다 — 재개 경로가 lease 검사
+    // 없이 attempt·brief hash만 보게 하려는 보존 계약이다.
+    const leaseId = hadLease ? task.lease.id : null;
+    const generation = hadLease ? task.lease.generation : null;
+    if (hadLease) {
+        task.lease.status = 'revoked';
+    }
+    delete task.dispatch;
+    delete task.sha;
+    task.status = 'pending';
+    const decision = {
+        task: task.id,
+        kind: 'revoke',
+        lease_id: leaseId,
+        generation,
+        reason: opts.reason,
+        previous_status: previousStatus,
+        previous_head: opts.previousHead,
+    };
+    task.decisions = [...(task.decisions || []), decision];
+    ledger.decisions = [...(Array.isArray(ledger.decisions) ? ledger.decisions : []), decision];
+    return decision;
+}
+/**
+ * 호출자가 보낸 lease_id·generation을 활성 lease와 맞는지 본다.
+ * 둘 다 없으면 검사를 건너뛴다(레거시·플래그 생략 경로). 하나만 있으면
+ * lease-required. 값이 다르거나 lease가 revoked면 stale-lease.
+ *
+ * @param {LeaseTask} task - 원장 task(lease 없으면 항상 ok)
+ * @param {LeaseReceived} received - 호출자 플래그
+ * @returns {LeaseCheckOk | LeaseCheckFail} 통과 또는 거절 reason
+ */
+function checkLease(task, received) {
+    const hasId = received.lease_id !== undefined;
+    const hasGeneration = received.generation !== undefined;
+    // 1. 둘 다 생략 — lease 검사 없이 기존 attempt·상태 검사로 넘긴다.
+    if (!hasId && !hasGeneration)
+        return { ok: true };
+    // 2. 하나만 주면 짝이 안 맞는다. 부분 플래그는 활성 lease와 비교하지 않는다.
+    if (hasId !== hasGeneration) {
+        return {
+            ok: false,
+            reason: 'lease-required',
+            expected: task.lease
+                ? { lease_id: task.lease.id, generation: task.lease.generation }
+                : null,
+            received: {
+                ...(hasId ? { lease_id: received.lease_id } : {}),
+                ...(hasGeneration ? { generation: received.generation } : {}),
+            },
+        };
+    }
+    // 3. lease 필드가 없는 legacy task는 플래그가 있어도 검사하지 않는다.
+    if (!task.lease)
+        return { ok: true };
+    const expected = { lease_id: task.lease.id, generation: task.lease.generation };
+    const got = {
+        lease_id: received.lease_id,
+        generation: received.generation,
+    };
+    // revoked이거나 id/generation 불일치면 상태 전이 없이 stale로만 거절한다.
+    if (task.lease.status === 'revoked'
+        || got.lease_id !== expected.lease_id
+        || got.generation !== expected.generation) {
+        return { ok: false, reason: 'stale-lease', expected, received: got };
+    }
+    return { ok: true };
+}
+/**
+ * 원장·task에 실린 lease / leaseSeq shape가 유효한지 본다.
+ * 손상된 lease가 재개·fence 기준으로 쓰이지 않게 validateCoordinatorLedger가 호출한다.
+ *
+ * @param {unknown} lease - task.lease 후보
+ * @returns {boolean} Lease shape이면 true
+ */
+function isValidLease(lease) {
+    if (!lease || typeof lease !== 'object' || Array.isArray(lease))
+        return false;
+    const value = lease;
+    if (typeof value.id !== 'string' || value.id === '')
+        return false;
+    if (!Number.isInteger(value.generation) || value.generation < 1)
+        return false;
+    if (!Number.isInteger(value.seq) || value.seq < 1)
+        return false;
+    if (value.status !== 'active' && value.status !== 'revoked')
+        return false;
+    return true;
+}
+/**
+ * ledger.leaseSeq가 0 이상 정수인지 본다. 필드 부재는 legacy로 허용한다.
+ *
+ * @param {unknown} leaseSeq - 원장 leaseSeq 후보
+ * @returns {boolean} 유효하거나 부재면 true
+ */
+function isValidLeaseSeq(leaseSeq) {
+    if (leaseSeq === undefined)
+        return true;
+    return Number.isInteger(leaseSeq) && leaseSeq >= 0;
+}
+module.exports = {
+    issueLease,
+    revokeLease,
+    checkLease,
+    isValidLease,
+    isValidLeaseSeq,
+};

package/dist/legacy-comments.js

@@ -0,0 +1,71 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const templates = require("./templates");
+const { findLegacyScaffoldComments } = templates;
+const paths = require("./paths");
+const { epicDirOf, toPosix } = paths;
+/**
+ * blueprint 디렉터리 아래 .md를 재귀로 모은다.
+ * 디렉터리가 없으면 빈 목록을 돌려 판정을 만들지 않는다 — 그 부재는 G2·G3이 판정한다.
+ *
+ * @param {string} absDir - 절대 경로 디렉터리
+ * @param {string} repoRoot - 저장소 루트 절대 경로
+ * @returns {string[]} 저장소 상대 POSIX .md 경로
+ */
+function collectBlueprintMarkdown(absDir, repoRoot) {
+    if (!fs.existsSync(absDir))
+        return [];
+    const found = [];
+    const stack = [absDir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        // 권한 오류 등은 삼키지 않는다. plan gate·bootstrap이 잡지 않아 CLI가 기존 예외 경로로 끝난다.
+        const entries = fs.readdirSync(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const abs = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(abs);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                found.push(toPosix(path.relative(repoRoot, abs)));
+            }
+        }
+    }
+    return found;
+}
+/**
+ * epic index와 blueprint 트리의 .md에서 옛 스캐폴드 안내 주석이 남은 경로를 모은다.
+ * 판정은 findLegacyScaffoldComments에 맡기고, 저자 주석만 있는 파일은 빠진다.
+ * 존재하지 않는 파일은 조용히 제외하고, 존재하지만 읽기에 실패한 파일은 예외를 그대로 올린다.
+ *
+ * @param {{ repoRoot: string, blueprintDir: string }} opts - 스캔 범위
+ * @param {string} opts.repoRoot - 저장소 루트 절대 경로
+ * @param {string} opts.blueprintDir - blueprint 디렉터리의 저장소 상대 POSIX 경로
+ * @returns {string[]} 옛 주석이 있는 파일의 정렬된 저장소 상대 POSIX 경로
+ */
+function scanLegacyScaffoldComments({ repoRoot, blueprintDir }) {
+    const leftover = [];
+    const epicIndexRel = `${toPosix(epicDirOf(blueprintDir))}/index.md`;
+    const candidates = [
+        epicIndexRel,
+        ...collectBlueprintMarkdown(path.join(repoRoot, blueprintDir), repoRoot),
+    ];
+    // 같은 파일이 두 번 나오지 않게 한다. epic index는 blueprint 트리 밖이지만
+    // 잘못된 blueprintDir가 epic 자신을 가리키면 겹칠 수 있다.
+    const seen = new Set();
+    for (const rel of candidates) {
+        if (seen.has(rel))
+            continue;
+        seen.add(rel);
+        const abs = path.join(repoRoot, rel);
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile())
+            continue;
+        const body = fs.readFileSync(abs, 'utf8');
+        if (findLegacyScaffoldComments(body).length > 0)
+            leftover.push(rel);
+    }
+    leftover.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return leftover;
+}
+module.exports = { scanLegacyScaffoldComments };

package/dist/migrate-context-slugs.js

@@ -0,0 +1,262 @@
+'use strict';
+const nodeFs = require('node:fs');
+const path = require('node:path');
+const guards = require("./guards");
+const { catchMessage } = guards;
+const layout = require("./layout");
+const { CONTEXT_ROOT } = layout;
+const contextIds = require("./context-ids");
+const { parseContextPath, validateSlug } = contextIds;
+const epicRegistry = require("./epic-registry");
+const { readEpicRegistry, parseEpicRegistry, REGISTRY_REL } = epicRegistry;
+const rewriteModule = require("./context-migration-rewrite");
+const { defaultRunGit, defaultListInProgress, computeRewrites, writeRegistryAtomically, } = rewriteModule;
+const validate = require("./validate");
+const { validateBlueprint } = validate;
+const RESTORE_NEXT = 'git restore --staged --worktree .bouncer && git clean -fd .bouncer/context';
+function failure(code, message, next, extra = {}) {
+    return { ok: false, code, message, next, ...extra };
+}
+/**
+ * slug 이관 계획을 문서 재작성 공용 모듈의 이동 맥락 목록으로 바꾼다. epic마다 직속 문서용 맥락 하나와
+ * blueprint마다 맥락 하나를 내며, `order`는 번호에서 온 값을 frontmatter에 없을 때만 채운다(`fill-missing`).
+ *
+ * @param {MigrationPlan} plan - 충돌 없는 이동 계획
+ * @returns 공용 모듈 `computeRewrites`의 `plan.contexts`
+ */
+function rewriteContextsOf(plan) {
+    return plan.epics.flatMap((epic) => {
+        const base = {
+            fromEpicDir: epic.from, toEpicDir: epic.to, epicSlug: epic.slug, orderMode: 'fill-missing',
+        };
+        return [
+            { ...base, blueprint: null },
+            ...epic.blueprints.map((bp) => ({
+                ...base, blueprint: { from: bp.from, to: bp.to, slug: bp.slug, order: bp.order },
+            })),
+        ];
+    });
+}
+/** 등록부 항목을 v2 모양(`id` 제거, 옛 번호는 `legacy_id`)으로 복사한다. 키 순서를 고정한다. */
+function toV2Epic(epic) {
+    const legacyId = epic.legacy_id ?? epic.id;
+    return {
+        slug: epic.slug,
+        ...(legacyId === undefined ? {} : { legacy_id: legacyId }),
+        kind: epic.kind,
+        active: epic.active,
+        ...(epic.approval === undefined ? {} : { approval: epic.approval }),
+        ...(epic.blueprint_aliases === undefined ? {} : { blueprint_aliases: { ...epic.blueprint_aliases } }),
+    };
+}
+/**
+ * 번호 형식 epic·blueprint 디렉터리를 slug 형식으로 옮기는 계획을 만든다. 파일을 쓰지 않는다.
+ * 겹침·규칙 위반은 `conflicts`에 모으고 계획은 계속 만든다(호출자가 한 번에 보고하도록).
+ *
+ * @param {object} opts - 입력
+ * @param {string} opts.repoRoot - 저장소 루트 절대 경로
+ * @param {EpicRegistry | null} opts.registry - 현재 등록부. 없으면 `nextRegistry`는 null이다
+ * @param {Partial<Deps>} [opts.deps] - `fs` 주입(읽기)
+ * @returns {MigrationPlan} 이동 목록·충돌·다음 등록부·별칭 표
+ */
+function planContextSlugMigration({ repoRoot, registry, deps }) {
+    const fsApi = deps?.fs ?? nodeFs;
+    const epicsRel = `${CONTEXT_ROOT}/epics`;
+    const conflicts = [];
+    const epics = [];
+    const epicNames = fsApi.existsSync(path.join(repoRoot, epicsRel))
+        ? fsApi.readdirSync(path.join(repoRoot, epicsRel)).sort() : [];
+    const claimedEpicSlugs = new Set();
+    for (const name of epicNames) {
+        const ids = parseContextPath(`epics/${name}`);
+        // 이미 slug인 디렉터리와 해석되지 않는 이름은 건너뛴다(재실행·비정본 이름은 이관 대상이 아니다).
+        if (!ids || ids.format !== 'numeric')
+            continue;
+        if (!fsApi.statSync(path.join(repoRoot, epicsRel, name)).isDirectory())
+            continue;
+        const slugViolation = validateSlug(ids.epicSlug);
+        if (slugViolation !== null)
+            conflicts.push(`${epicsRel}/${name}: ${slugViolation}`);
+        if (claimedEpicSlugs.has(ids.epicSlug)) {
+            conflicts.push(`${epicsRel}/${name}: epic slug is also claimed by another numbered epic: ${ids.epicSlug}`);
+        }
+        claimedEpicSlugs.add(ids.epicSlug);
+        if (fsApi.existsSync(path.join(repoRoot, epicsRel, ids.epicSlug))) {
+            conflicts.push(`${epicsRel}/${name}: ${epicsRel}/${ids.epicSlug} already exists`);
+        }
+        const move = {
+            from: `${epicsRel}/${name}`,
+            to: `${epicsRel}/${ids.epicSlug}`,
+            legacyId: ids.epicKey,
+            slug: ids.epicSlug,
+            blueprints: [],
+        };
+        const bpRoot = path.join(repoRoot, move.from, 'blueprints');
+        const bpNames = fsApi.existsSync(bpRoot) ? fsApi.readdirSync(bpRoot).sort() : [];
+        const seen = new Set();
+        for (const bpName of bpNames) {
+            if (!fsApi.statSync(path.join(bpRoot, bpName)).isDirectory())
+                continue;
+            const bpIds = parseContextPath(`epics/${name}/blueprints/${bpName}`);
+            if (!bpIds || bpIds.format !== 'numeric' || bpIds.blueprintKey === null || bpIds.blueprintSlug === null) {
+                conflicts.push(`${move.from}/blueprints/${bpName}: blueprint directory is not numbered (ddd-slug)`);
+                continue;
+            }
+            const bpViolation = validateSlug(bpIds.blueprintSlug);
+            if (bpViolation !== null)
+                conflicts.push(`${move.from}/blueprints/${bpName}: ${bpViolation}`);
+            if (seen.has(bpIds.blueprintSlug)) {
+                conflicts.push(`${move.from}/blueprints/${bpName}: blueprint slug repeats in this epic: `
+                    + `${bpIds.blueprintSlug}`);
+            }
+            seen.add(bpIds.blueprintSlug);
+            move.blueprints.push({
+                from: `${move.from}/blueprints/${bpName}`,
+                to: `${move.to}/blueprints/${bpIds.blueprintSlug}`,
+                number: bpIds.blueprintKey,
+                slug: bpIds.blueprintSlug,
+                order: Number(bpIds.blueprintKey),
+            });
+        }
+        epics.push(move);
+    }
+    // 등록부: v1 항목은 `id`를 `legacy_id`로 옮기고, 번호 디렉터리를 가졌던 epic은 legacy 여부와 관계없이
+    // `legacy_id`·`blueprint_aliases`를 가진다. 이미 기록된 같은 별칭은 건너뛰고 다른 값이면 충돌이다.
+    const aliases = {};
+    let nextRegistry = null;
+    if (registry !== null) {
+        const nextEpics = registry.epics.map(toV2Epic);
+        for (const move of epics) {
+            let entry = nextEpics.find((e) => e.slug === move.slug);
+            if (entry === undefined) {
+                // 등록부에 없는 번호 epic은 init의 planRegistry와 같이 legacy로 기록한다(번호 별칭을 잃지 않기 위함).
+                entry = { slug: move.slug, legacy_id: move.legacyId, kind: 'legacy', active: true };
+                nextEpics.push(entry);
+            }
+            else if (entry.legacy_id !== move.legacyId) {
+                conflicts.push(`${move.from}: registry records legacy id ${String(entry.legacy_id)} for ${move.slug}`);
+            }
+            const table = { ...entry.blueprint_aliases };
+            for (const bp of move.blueprints) {
+                if (table[bp.number] !== undefined && table[bp.number] !== bp.slug) {
+                    conflicts.push(`${move.slug}: alias ${bp.number} already points to ${table[bp.number]}, not ${bp.slug}`);
+                }
+                table[bp.number] = bp.slug;
+            }
+            entry.blueprint_aliases = Object.fromEntries(Object.entries(table).sort(([a], [b]) => a.localeCompare(b)));
+            aliases[move.slug] = {
+                legacy_id: move.legacyId, blueprint_aliases: entry.blueprint_aliases,
+            };
+        }
+        const candidate = {
+            version: 2,
+            profile: registry.profile,
+            domainEpicLimit: registry.domainEpicLimit,
+            areas: registry.areas,
+            ...(registry.areaPromotionThreshold === undefined
+                ? {} : { areaPromotionThreshold: registry.areaPromotionThreshold }),
+            epics: nextEpics,
+        };
+        const parsed = parseEpicRegistry(candidate);
+        if (parsed.ok)
+            nextRegistry = parsed.registry;
+        else
+            conflicts.push(`${REGISTRY_REL}: migrated registry would be invalid: ${parsed.message}`);
+    }
+    else {
+        for (const move of epics) {
+            aliases[move.slug] = {
+                legacy_id: move.legacyId,
+                blueprint_aliases: Object.fromEntries(move.blueprints.map((bp) => [bp.number, bp.slug])),
+            };
+        }
+    }
+    const moved = [
+        ...epics.map((e) => ({ from: e.from, to: e.to })),
+        ...epics.flatMap((e) => e.blueprints.map((bp) => ({ from: bp.from, to: bp.to }))),
+    ];
+    return { epics, moved, conflicts, nextRegistry, aliases };
+}
+/**
+ * 번호 형식 epic·blueprint를 slug 형식으로 이관한다. `yes`가 없으면 계획만 돌려준다(dry-run).
+ * 거절(dirty 트리·진행 중 상태·slug 충돌·등록부 문제)은 어떤 쓰기·`git mv` 전에 끝난다.
+ * 쓰기 단계의 예외는 자동 롤백 없이 되돌리는 명령을 `next`에 담아 돌려준다.
+ *
+ * @param {object} opts - 입력
+ * @param {string} opts.repoRoot - 저장소 루트 절대 경로
+ * @param {boolean} [opts.yes] - true면 실제로 옮긴다
+ * @param {Partial<Deps>} [opts.deps] - 테스트 seam. `runGit`·`fs`·`listInProgress`
+ * @returns {MigrationResult} 성공(moved·rewritten·aliases·validate) 또는 거절(code·message·next·blockers)
+ */
+function migrateContextSlugs({ repoRoot, yes = false, deps }) {
+    const fsApi = deps?.fs ?? nodeFs;
+    const runGit = deps?.runGit ?? defaultRunGit(repoRoot);
+    const read = readEpicRegistry(repoRoot);
+    if (read.status === 'invalid') {
+        return failure('S35', `epic registry is invalid: ${read.message}`, `fix ${REGISTRY_REL}, then retry`);
+    }
+    const registry = read.status === 'ok' ? read.registry : null;
+    const plan = planContextSlugMigration({ repoRoot, registry, deps: { fs: fsApi } });
+    // 옮길 번호 디렉터리가 없으면 거절 검사 없이 성공이다. 이관 직후(작업 트리가 더러운 상태)의 재실행이
+    // dirty 거절에 걸리면 "두 번째 실행은 moved: []인 성공"이라는 멱등 계약이 깨진다.
+    if (plan.epics.length === 0) {
+        return { ok: true, dryRun: !yes, moved: [], rewritten: [], aliases: {}, validate: [] };
+    }
+    if (registry === null) {
+        return failure('migrate-registry-missing', `${REGISTRY_REL} is missing; the registry records the aliases the migration must write`, 'run bouncer init to create the registry, then retry');
+    }
+    if (runGit(['status', '--porcelain']).stdout.trim() !== '') {
+        return failure('migrate-dirty-tree', 'the working tree has uncommitted changes', 'commit or stash every change (git status --porcelain must be empty), then retry');
+    }
+    const inProgress = (deps?.listInProgress ?? (() => defaultListInProgress({ repoRoot, runGit, fsApi })))();
+    if (inProgress.length > 0) {
+        return failure('migrate-in-progress', `${inProgress.length} in-progress runtime item(s) hold the old path keys`, 'finish or discard the pointer, approvals, coordinator ledger and linked worktrees listed in blockers, '
+            + 'then retry', { blockers: inProgress });
+    }
+    if (plan.conflicts.length > 0) {
+        return failure('migrate-slug-conflict', plan.conflicts.join('; '), 'rename the conflicting directories, then retry');
+    }
+    // 모든 문서 변경을 쓰기 전에 계산한다. 여기서 던지면(깨진 YAML 등) 디스크는 그대로다.
+    const rewrites = computeRewrites({
+        repoRoot,
+        plan: { moved: plan.moved, nextRegistry: plan.nextRegistry, contexts: rewriteContextsOf(plan) },
+        runGit,
+        fsApi,
+    });
+    const changed = rewrites.filter((r) => r.text !== r.original);
+    const rewritten = changed.map((r) => r.newRel).sort();
+    if (!yes) {
+        return { ok: true, dryRun: true, moved: plan.moved, rewritten, aliases: plan.aliases, validate: [] };
+    }
+    try {
+        // 1. epic 디렉터리를 먼저 옮기고, 그 안의 blueprint를 옮긴다(epic 이동 뒤의 경로 기준).
+        for (const epic of plan.epics)
+            runGit(['mv', epic.from, epic.to]);
+        for (const epic of plan.epics) {
+            for (const bp of epic.blueprints)
+                runGit(['mv', `${epic.to}/blueprints/${path.posix.basename(bp.from)}`, bp.to]);
+        }
+        // 2. 문서 내용. git mv는 내용을 바꾸지 않으므로 이동한 자리(newRel)에 새 내용을 쓴다.
+        for (const r of changed)
+            fsApi.writeFileSync(path.join(repoRoot, r.newRel), r.text);
+        // 3. 등록부(v2)는 문서 뒤에 쓴다 — 실패하면 문서만 새 형식인 상태가 남지만 restore 한 줄로 되돌린다.
+        if (plan.nextRegistry !== null)
+            writeRegistryAtomically(fsApi, repoRoot, plan.nextRegistry);
+    }
+    catch (error) {
+        // 자동 롤백은 하지 않는다(답변 16). 어느 단계에서 던졌든 일부만 적용된 상태이므로, 모든 예외를
+        // 같은 복구 안내로 접는다. 원인은 message에 그대로 싣는다.
+        return failure('migrate-failed', catchMessage(error), RESTORE_NEXT, { moved: plan.moved, rewritten });
+    }
+    const validation = plan.epics.flatMap((e) => e.blueprints).map((bp) => {
+        const result = validateBlueprint({ repoRoot, blueprintDir: bp.to });
+        return { blueprint: bp.to, ok: result.ok, failures: result.failures };
+    });
+    const summary = { moved: plan.moved, rewritten, aliases: plan.aliases, validate: validation };
+    if (validation.some((v) => !v.ok)) {
+        return failure('migrate-validate-failed', 'bouncer validate reported failures for migrated blueprints; the moved files are kept', 'fix the failures listed in validate (or restore with: git restore --staged --worktree .bouncer '
+            + '&& git clean -fd .bouncer/context)', summary);
+    }
+    return { ok: true, dryRun: false, ...summary };
+}
+module.exports = { planContextSlugMigration, migrateContextSlugs, defaultListInProgress };