@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/commit-hook.js

@@ -0,0 +1,470 @@
+// scripts/lib/commit-hook.js
+'use strict';
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const commitGuard = require("./commit-guard");
+const { checkCommitSafety } = commitGuard;
+const current = require("./current");
+const { readCurrent, resolveEffectiveTask } = current;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const tasksDocs = require("./tasks-docs");
+const { listTasksDocs } = tasksDocs;
+const paths = require("./paths");
+const { toPosix } = paths;
+const scope = require("./scope");
+const { coordinatorContext } = scope;
+const crossDrive = require("./cross-drive");
+const compositeGates = require("./composite-gates");
+const { otherDriveTasks } = crossDrive;
+const NO_COMMIT = { commit: false, all: false };
+// 판단 불가(중첩 셸·확장·깊이 초과)는 커밋으로 칠 뿐 아니라 all-flag도
+// 있는 것으로 친다. -a 없이 스테이징만 보면 PreToolUse 시점에 인덱스가
+// 비어 범위 밖 파일이 그대로 들어간다.
+const FAIL_CLOSED = { commit: true, all: true };
+// guard는 실수를 막습니다. 의도적 우회에 대한 방어는 아닙니다
+// fail-closed: 명령을 판단할 수 없는 경우 —
+// 중첩 셸, 셸 확장, alias — commit으로 보고하고 통과시키지 않아
+// scope 검사가 여전히 실행됩니다.
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'ash']);
+const GIT_VALUE_FLAGS = new Set([
+    '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--super-prefix',
+]);
+const SHELL_COMMAND_FLAG = /^-[A-Za-z]*c$/;
+const EXPANSION = /[$`]/;
+const MAX_DEPTH = 4;
+// 공백과 새 명령을 시작하는 연산자 모두에서 분리하되, 따옴표 밖에서만.
+// 인자 위치의 따옴표 토큰은 데이터다(`echo "git commit"`). 다만 세그먼트
+// 첫 토큰 값이 git이면 인용·부분인용도 명령으로 본다 — segmentIsGitCommit 참고.
+function tokenize(command) {
+    const tokens = [];
+    let value = '';
+    let started = false;
+    let quoted = false;
+    const push = () => {
+        if (started)
+            tokens.push({ value, quoted });
+        value = '';
+        started = false;
+        quoted = false;
+    };
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (ch === '\\' && i + 1 < command.length) {
+            value += command[i + 1];
+            started = true;
+            i += 1;
+        }
+        else if (ch === '"' || ch === "'") {
+            const end = command.indexOf(ch, i + 1);
+            const stop = end === -1 ? command.length : end;
+            value += command.slice(i + 1, stop);
+            started = true;
+            quoted = true;
+            i = stop;
+        }
+        else if (/\s/.test(ch)) {
+            push();
+            if (ch === '\n')
+                tokens.push({ separator: true });
+        }
+        else if (ch === ';' || ch === '&' || ch === '|') {
+            push();
+            tokens.push({ separator: true });
+        }
+        else {
+            value += ch;
+            started = true;
+        }
+    }
+    push();
+    return tokens;
+}
+function segments(tokens) {
+    const out = [[]];
+    for (const token of tokens) {
+        if (token.separator)
+            out.push([]);
+        else
+            out[out.length - 1].push(token);
+    }
+    return out.filter((seg) => seg.length);
+}
+function isWord(token, word) {
+    return !token.quoted && token.value === word;
+}
+// 명령어 위치(세그먼트 첫 토큰)의 git만 인용·부분인용을 허용한다.
+// `echo "git" commit`처럼 인자 자리의 "git"까지 열면 오탐이 난다.
+function isCommandPositionGit(token) {
+    return Boolean(token && token.value === 'git');
+}
+function orJudgment(a, b) {
+    return { commit: a.commit || b.commit, all: a.all || b.all };
+}
+function argvHasAllFlag(tokens, start) {
+    for (let i = start; i < tokens.length; i += 1) {
+        const t = tokens[i];
+        // 따옴표 토큰은 데이터다. `git commit -m "-a"`의 "-a"를 --all로 읽으면 안 된다.
+        if (t.quoted)
+            continue;
+        const v = t.value;
+        if (v === '--message' || v === '-m') {
+            i += 1;
+            continue;
+        }
+        if (v.startsWith('--message='))
+            continue;
+        // 롱 옵션은 이름 전체가 정확히 --all일 때만. --amend/--author=/--allow-empty는
+        // '-'로 시작하고 a를 포함하지만 all-flag가 아니다.
+        if (v === '--all')
+            return true;
+        if (v.startsWith('--'))
+            continue;
+        if (v.startsWith('-')) {
+            if (v.includes('a'))
+                return true;
+            // -nm 처럼 m이 묶음에 있으면 다음 토큰은 메시지 값이다.
+            if (v.includes('m'))
+                i += 1;
+        }
+    }
+    return false;
+}
+function aliasIsCommit(name, rest, resolveAlias, depth) {
+    if (typeof resolveAlias !== 'function')
+        return NO_COMMIT;
+    let expansion;
+    try {
+        expansion = (resolveAlias(name) || '').trim();
+    }
+    catch (_e) {
+        return NO_COMMIT;
+    }
+    if (!expansion)
+        return NO_COMMIT;
+    // `!` alias는 임의의 셸 명령을 실행합니다. 그 외는 git 자체 argv입니다.
+    const nested = expansion.startsWith('!')
+        ? detect(expansion.slice(1), resolveAlias, depth + 1)
+        : detect(`git ${expansion}`, resolveAlias, depth + 1);
+    // alias 뒤에 붙은 원래 argv(-am 등)는 확장 문자열에 안 들어 있다.
+    if (nested.commit && argvHasAllFlag(rest, 0)) {
+        return { commit: true, all: true };
+    }
+    return nested;
+}
+function segmentIsGitCommit(tokens, resolveAlias, depth) {
+    const shellIdx = tokens.findIndex((t) => !t.quoted && SHELLS.has(path.basename(t.value)));
+    if (shellIdx !== -1) {
+        for (let i = shellIdx + 1; i < tokens.length; i += 1) {
+            if (!tokens[i].quoted && SHELL_COMMAND_FLAG.test(tokens[i].value)) {
+                const script = tokens[i + 1];
+                // 읽을 `bash -c` 내용이 없으면 무해한 게 아니라 판단 불가입니다.
+                if (!script)
+                    return FAIL_CLOSED;
+                return detect(script.value, resolveAlias, depth + 1);
+            }
+        }
+    }
+    // 1. 따옴표 없는 git은 기존처럼 세그먼트 어디서든(예: env=… git commit).
+    // 2. 인용·부분인용(`"git"` / `g"it"`)은 첫 토큰일 때만 — 인자 오탐 방지.
+    let gitIdx = tokens.findIndex((t) => isWord(t, 'git'));
+    if (gitIdx === -1 && isCommandPositionGit(tokens[0]))
+        gitIdx = 0;
+    if (gitIdx === -1)
+        return NO_COMMIT;
+    let i = gitIdx + 1;
+    while (i < tokens.length) {
+        const t = tokens[i];
+        // 이 명령을 결정하는 단어는 런타임에 만들어집니다.
+        if (EXPANSION.test(t.value))
+            return FAIL_CLOSED;
+        if (t.value.startsWith('-')) {
+            i += GIT_VALUE_FLAGS.has(t.value) ? 2 : 1;
+            continue;
+        }
+        if (t.value === 'commit') {
+            return { commit: true, all: argvHasAllFlag(tokens, i + 1) };
+        }
+        return aliasIsCommit(t.value, tokens.slice(i + 1), resolveAlias, depth);
+    }
+    return NO_COMMIT;
+}
+function detect(command, resolveAlias, depth) {
+    if (typeof command !== 'string')
+        return NO_COMMIT;
+    if (depth >= MAX_DEPTH)
+        return FAIL_CLOSED;
+    return segments(tokenize(command))
+        .reduce((acc, seg) => orJudgment(acc, segmentIsGitCommit(seg, resolveAlias, depth)), NO_COMMIT);
+}
+// PreToolUse payload의 cwd는 일부 호스트에서 호출한 Bash 도구의 기본 checkout으로
+// 남는다. `git -C <worktree> commit`은 Git 자신이 커밋 대상을 명시하므로, 이 경우
+// scope 판정도 같은 worktree에서 해야 한다. 경로는 실행하지 않고 Git argv의 리터럴
+// `-C` 값만 누적해 해석한다.
+function commitWorktree(command, fallback) {
+    if (typeof command !== 'string')
+        return fallback;
+    let worktree = fallback;
+    for (const segment of segments(tokenize(command))) {
+        const gitIdx = segment.findIndex((token) => isWord(token, 'git'));
+        if (gitIdx === -1)
+            continue;
+        for (let i = gitIdx + 1; i < segment.length; i += 1) {
+            const token = segment[i];
+            if (token.value === 'commit') {
+                if (worktree === fallback)
+                    return fallback;
+                try {
+                    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+                        cwd: worktree, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+                    }).trim();
+                }
+                catch (_e) {
+                    // `-C` 대상이 Git worktree임을 증명할 수 없으면 host cwd 판정을 유지한다.
+                    return fallback;
+                }
+            }
+            if (token.quoted || EXPANSION.test(token.value))
+                continue;
+            let value;
+            if (token.value === '-C')
+                value = segment[++i];
+            else if (token.value.startsWith('-C') && token.value.length > 2) {
+                value = { value: token.value.slice(2), quoted: false };
+            }
+            if (value && !EXPANSION.test(value.value))
+                worktree = path.resolve(worktree, value.value);
+            else if (GIT_VALUE_FLAGS.has(token.value))
+                i += 1;
+        }
+    }
+    return fallback;
+}
+function realResolveAlias(cwd) {
+    return (name) => {
+        try {
+            return execFileSync('git', ['config', '--get', `alias.${name}`], {
+                cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+            });
+        }
+        catch (_e) {
+            return '';
+        }
+    };
+}
+function isGitCommit(command, { resolveAlias, cwd } = {}) {
+    const resolver = resolveAlias === undefined ? realResolveAlias(cwd) : resolveAlias;
+    return detect(command, resolver, 0).commit;
+}
+function pathsFromTaskDoc(repoRoot, entryRel) {
+    try {
+        const { data } = readDoc(path.join(repoRoot, entryRel));
+        const bouncer = data ? data.bouncer : data;
+        const ap = bouncer ? bouncer.affected_paths : undefined;
+        if (!Array.isArray(ap))
+            return [];
+        return ap.filter((p) => typeof p === 'string');
+    }
+    catch (_e) {
+        return [];
+    }
+}
+function readAffectedPaths({ repoRoot, blueprintDir }) {
+    // effective task가 있으면 그 문서의 affected_paths 만. 없으면 전체 합집합.
+    // worker에서 lease를 못 확인하면 빈 목록 — pointer로 폴백하지 않는다.
+    // 가리키던 문서가 사라진 경우에만 합집합으로 폴백한다.
+    try {
+        const listing = listTasksDocs({ repoRoot, blueprintDir });
+        if (listing.mixed || listing.entries.length === 0)
+            return [];
+        const effective = resolveEffectiveTask({ repoRoot });
+        if (effective && effective.source === null)
+            return [];
+        const bp = toPosix(blueprintDir);
+        if (effective
+            && typeof effective.path === 'string'
+            && toPosix(effective.blueprint) === bp) {
+            const match = listing.entries.find((e) => e.rel === toPosix(effective.path));
+            if (match)
+                return pathsFromTaskDoc(repoRoot, match.rel);
+        }
+        const out = [];
+        const seen = new Set();
+        for (const entry of listing.entries) {
+            for (const p of pathsFromTaskDoc(repoRoot, entry.rel)) {
+                if (!seen.has(p)) {
+                    seen.add(p);
+                    out.push(p);
+                }
+            }
+        }
+        return out;
+    }
+    catch (_e) {
+        return [];
+    }
+}
+function realStagedFiles({ repoRoot }) {
+    const out = execFileSync('git', ['diff', '--cached', '--name-only'], {
+        cwd: repoRoot, encoding: 'utf8',
+    });
+    return out.split('\n').filter(Boolean);
+}
+function realTrackedModified({ repoRoot }) {
+    // -a/--all 이 담는 것은 인덱스만이 아니라 HEAD 대비 추적 중 수정이다.
+    // 삭제된 경로가 섞이므로 이름을 쓸 뿐 파일 내용은 읽지 않는다.
+    // git 실패는 삼키지 않는다: 훅 어댑터가 throw를 fail-closed로 exit 2 한다.
+    const out = execFileSync('git', ['diff', 'HEAD', '--name-only'], {
+        cwd: repoRoot, encoding: 'utf8',
+    });
+    return out.split('\n').filter(Boolean);
+}
+// active pointer는 Git common directory에 있으므로 primary와 linked worktree
+// 모두 main working tree를 찾지 않고 같은 state를 resolve합니다.
+function realMainRepoCurrent({ repoRoot, deps }) {
+    return readCurrent({ repoRoot, deps });
+}
+function mergeCommitHookDeps(deps) {
+    return {
+        readCurrent,
+        readAffectedPaths,
+        stagedFiles: realStagedFiles,
+        trackedModified: realTrackedModified,
+        mainRepoCurrent: realMainRepoCurrent,
+        coordinatorContext,
+        otherDriveTasks,
+        ...(deps || {}),
+    };
+}
+/**
+ * hook 거절 줄 맨 앞에 붙일 복합 gate 라벨 접두를 만든다.
+ * 라벨은 줄 맨 앞에만 둔다 — `commit blocked: <code>:` 연속 문자열을 쪼개면 기존 정규식이 깨진다.
+ *
+ * @param {unknown} reason - 거절 code. 문자열이 아니거나 매핑이 없으면 접두 없음
+ * @returns {string} `[<label>] ` 또는 빈 문자열
+ */
+function gateLabelPrefix(reason) {
+    const gate = typeof reason === 'string' ? compositeGates.compositeGateForReason(reason) : null;
+    return gate ? `[${compositeGates.compositeGateLabel(gate)}] ` : '';
+}
+/**
+ * staged(또는 -a면 tracked 수정까지) 목록을 checkCommitSafety에 넘긴다.
+ * 명령 탐지는 호출부가 끝낸 뒤라, git pre-commit과 PreToolUse가 같은
+ * 이유 문자열을 내게 여기만 공유한다. coordinator scope를 통과하면 상대
+ * drive 원장도 검사해 두 경로가 같은 충돌 근거와 복구 안내를 낸다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - 커밋이 일어나는 checkout 절대 경로
+ * @param {CommitHookDeps | null} [opts.deps] - 테스트 seam
+ * @param {boolean} opts.all - true면 staged∪trackedModified (`git commit -a`)
+ * @returns {{ block: false } | { block: true, reason: string }}
+ */
+function evaluateIndex({ repoRoot, deps, all }) {
+    const d = mergeCommitHookDeps(deps);
+    // 1. pointer 조기 허용보다 effective task를 먼저 본다. worker에서
+    //    `if (!current) return {block:false}` 하면 lease fail-closed와
+    //    lease affected_paths가 통째로 건너뛴다.
+    const effective = resolveEffectiveTask({ repoRoot });
+    if (effective && effective.source === null) {
+        return { block: true, reason: effective.reason };
+    }
+    const current = d.readCurrent({ repoRoot }) || d.mainRepoCurrent({ repoRoot });
+    // lease가 blueprint를 주면 pointer 없이도 scope 판정. 둘 다 없으면
+    // standalone/no-blueprint와 같이 허용(기존 계약).
+    const blueprintDir = (effective && typeof effective.blueprint === 'string' && effective.blueprint)
+        || (current && typeof current.blueprint === 'string' ? current.blueprint : null);
+    if (!blueprintDir)
+        return { block: false };
+    const taskForScope = effective && typeof effective.path === 'string'
+        ? effective.path
+        : (current && current.task);
+    const affectedPaths = d.readAffectedPaths({ repoRoot, blueprintDir });
+    const files = all
+        ? [...new Set([...d.stagedFiles({ repoRoot }), ...d.trackedModified({ repoRoot })])]
+        : d.stagedFiles({ repoRoot });
+    // coordinator 실행이면 ledger가 현재 scope와 worktree 경계의 정본이다.
+    // 일반 execute에서는 active:false로 떨어져 예전 판정이 그대로 남는다.
+    const coordinator = d.coordinatorContext({
+        repoRoot, blueprint: blueprintDir, task: taskForScope,
+    });
+    const otherDrives = coordinator.active && !coordinator.reason
+        ? d.otherDriveTasks({ repoRoot, ownLedgerFile: coordinator.ledgerFile })
+        : undefined;
+    const { allow, violations, code, conflicts, ledgerFile } = checkCommitSafety({
+        files, affectedPaths, blueprintDir, coordinator, otherDrives,
+    });
+    if (allow)
+        return { block: false };
+    const detail = violations.join(', ');
+    if (code === 'cross-drive-conflict' && conflicts && conflicts.length > 0) {
+        const first = conflicts[0];
+        const target = first.paths[0] || `resource:${first.resources[0]}`;
+        const remaining = conflicts.length > 1 ? ` (+${conflicts.length - 1} more)` : '';
+        return {
+            block: true,
+            reason: `${gateLabelPrefix(code)}commit blocked: cross-drive-conflict: ${first.blueprint} ${first.task} ${target}`
+                + `${remaining} | next: 상대 drive가 끝나거나 detach될 때까지 기다리거나, 겹치지 않게 계획을 고친다`,
+        };
+    }
+    if (code === 'cross-drive-ledger-unreadable') {
+        return {
+            block: true,
+            reason: `${gateLabelPrefix(code)}commit blocked: cross-drive-ledger-unreadable: ${ledgerFile}`
+                + ' | next: `ledgerFile`의 원장을 복구하거나 그 drive를 detach한다',
+        };
+    }
+    if (code && code !== 'out-of-scope') {
+        // 경계 거절은 staged 목록이 비어도 성립한다 — 그때는 빈 콜론 대신
+        // 어느 checkout에서 무엇이 거절됐는지 남긴다. 원장 경로도 함께 남긴다:
+        // 손상된 원장 하나가 모든 checkout을 막으므로 어느 파일인지 보여야 한다.
+        const where = detail || `no staged path in ${repoRoot}`;
+        const ledger = coordinator && coordinator.ledgerFile ? ` (ledger: ${coordinator.ledgerFile})` : '';
+        // 메인 checkout 거절은 막다른 길로 보이지 않게 다음 행동을 덧붙인다(병합 뒤 분리 경로).
+        const next = code === 'main-worktree-source-write'
+            ? ` | next: ${scope.mainWorktreeNext(coordinator, blueprintDir)}`
+            : '';
+        return { block: true, reason: `${gateLabelPrefix(code)}commit blocked: ${code}: ${where}${ledger}${next}` };
+    }
+    return {
+        block: true,
+        reason: `${gateLabelPrefix('out-of-scope')}commit blocked: files outside affected_paths: ${detail}`,
+    };
+}
+/**
+ * `-a` 없는 `git commit`과 같은 staged 목록으로 scope를 판정한다.
+ * pre-commit hook은 명령 문자열이 없으므로 여기만 호출한다.
+ *
+ * @param {{ repoRoot: string, deps?: CommitHookDeps | null }} opts
+ * @param {string} opts.repoRoot - 커밋이 일어나는 checkout 절대 경로
+ * @param {CommitHookDeps | null} [opts.deps] - 테스트 seam(readCurrent·stagedFiles 등)
+ * @returns {{ block: false } | { block: true, reason: string }} allow면 block false,
+ *   worker lease 부재·원장 손상·out-of-scope면 block true와 reason
+ */
+function evaluateStaged({ repoRoot, deps }) {
+    return evaluateIndex({ repoRoot, deps, all: false });
+}
+/**
+ * PreToolUse 훅이 git commit 명령의 scope를 판정한다. worker cwd에서는
+ * pointer 유무보다 resolveEffectiveTask를 먼저 본다 — prepare 직후·--set 전
+ * 창에서도 lease affected_paths와 fail-closed가 적용돼야 한다.
+ * 커밋으로 탐지된 뒤에는 `evaluateStaged`와 같은 판정부를 쓴다(`-a`만 목록이 다름).
+ *
+ * @param {{ command: unknown, repoRoot: string, deps?: CommitHookDeps | null }} opts
+ * @param {unknown} opts.command - 탐지 대상 shell 명령 문자열
+ * @param {string} opts.repoRoot - 커밋이 일어나는 checkout 절대 경로
+ * @param {CommitHookDeps | null} [opts.deps] - 테스트 seam(readCurrent·stagedFiles 등)
+ * @returns {{ block: false } | { block: true, reason: string }} allow면 block false,
+ *   worker lease 부재·원장 손상·out-of-scope면 block true와 reason
+ */
+function evaluateCommit({ command, repoRoot, deps }) {
+    const d = mergeCommitHookDeps(deps);
+    const worktree = commitWorktree(command, repoRoot);
+    const judgment = detect(command, realResolveAlias(worktree), 0);
+    if (!judgment.commit)
+        return { block: false };
+    return evaluateIndex({ repoRoot: worktree, deps: d, all: judgment.all });
+}
+module.exports = {
+    isGitCommit, readAffectedPaths, evaluateCommit, evaluateStaged,
+    realStagedFiles, realTrackedModified, realMainRepoCurrent,
+};

package/dist/commit-message.js

@@ -0,0 +1,77 @@
+'use strict';
+const templates = require("./templates");
+const { normalizeAuthoredLines, parseIntentBody } = templates;
+const commitSha = require("./commit-sha");
+const { buildStableProvenance } = commitSha;
+function asRecord(value) {
+    return value;
+}
+// subject와 body는 프로젝트가 document field에 쓰는 commit convention을 따름;
+// 구조만 Bouncer 소유. identifier와 path는 제목·본문에 넣지 않음 — blueprint
+// 문서와 PR body에 있다. 기계가 읽는 식별자는 메시지 끝 Git trailer 두 줄로만
+// 붙인다. 본문에 섞으면 제목 규약과 충돌하고, trailer가 아니면 cherry-pick·
+// explain 소비자가 같은 키를 찾지 못한다.
+// Subject: 대상 task title (없으면 blueprint title). Body: task 문서가 저작한
+// 배경·의도와 변경 요약. verification title은 실행 증적이지 메시지 저작물이
+// 아니므로 사용하지 않는다. 새 필드가 없는 기존 task는 제목만으로 읽는다.
+// commit 경로(`bouncer commit`)가 이 빌더를 쓴다. finalize 마감 메시지는
+// buildFinalizeCommitMessage — task 문서 필드를 넣지 않는다.
+function authoredContainsBouncerTrailer(lines) {
+    // Git trailer는 줄 앞의 정확한 키다. 문장 한가운데 언급이 아니라 저작 필드가
+    // 이미 trailer 한 줄을 들고 있으면, 생성기가 같은 키를 또 붙여 중복이 된다.
+    return lines.some((line) => /^(?:Bouncer-Task|Bouncer-Intent)\s*:/.test(line));
+}
+function buildCommitMessage(docs, taskUnit) {
+    const bp = asRecord(docs.blueprintIndex && docs.blueprintIndex.data);
+    const bouncer = asRecord(bp.bouncer || {});
+    const type = bouncer.commit_type || 'feat';
+    const taskTitle = taskUnit && taskUnit.tasks && taskUnit.tasks.data
+        ? asRecord(taskUnit.tasks.data).title
+        : undefined;
+    // 대상 묶음이 없거나 title이 비면 blueprint로 떨어뜨려 빈 subject를 만들지 않음.
+    const subjectTitle = (typeof taskTitle === 'string' && taskTitle.trim())
+        ? taskTitle.trim()
+        : bp.title;
+    const taskData = taskUnit && taskUnit.tasks && taskUnit.tasks.data
+        ? asRecord(taskUnit.tasks.data)
+        : (docs.tasks && docs.tasks.data ? asRecord(docs.tasks.data) : {});
+    const taskBouncer = taskData && taskData.bouncer && typeof taskData.bouncer === 'object'
+        ? asRecord(taskData.bouncer)
+        : {};
+    const intent = normalizeAuthoredLines(taskBouncer.commit_intent, 'commit_intent');
+    const summary = normalizeAuthoredLines(taskBouncer.commit_summary, 'commit_summary');
+    const bodyLines = [...intent, ...summary];
+    // 저작 필드가 이미 Bouncer trailer를 들고 있으면 한 줄을 더 붙여 키가 두 번
+    // 나온다. Git trailer는 키당 한 줄이므로 중복을 지우지 않고 생성을 거절한다.
+    if (authoredContainsBouncerTrailer(bodyLines)) {
+        throw new Error('commit message authored fields already contain a Bouncer-Task or Bouncer-Intent trailer');
+    }
+    const provenance = buildStableProvenance({
+        epicId: taskBouncer.epic_id,
+        blueprintId: taskBouncer.blueprint_id,
+        taskId: taskBouncer.id,
+    });
+    const body = bodyLines.map((t) => `- ${t}`);
+    const lines = [`${type}: ${subjectTitle}`];
+    if (body.length)
+        lines.push('', ...body);
+    // trailer는 본문과 빈 줄로 구분한다. subject만 있어도 같은 구분자를 써서
+    // Git이 제목을 trailer 블록으로 붙이지 않게 한다.
+    lines.push('', ...provenance.trailers);
+    return lines.join('\n');
+}
+// finalize 마감 커밋: subject와 body 모두 blueprint에서 읽는다. Intent를
+// 파싱할 수 없으면 task 일부를 주워 메시지를 만드는 대신 즉시 실패시킨다.
+// task title·verification bullet을 넣으면 이미 남긴 task 커밋과 겹친다.
+function buildFinalizeCommitMessage(docs) {
+    const bp = asRecord(docs.blueprintIndex && docs.blueprintIndex.data);
+    const bouncer = asRecord(bp.bouncer || {});
+    const type = bouncer.commit_type || 'feat';
+    const intent = parseIntentBody(docs.blueprintIndex && docs.blueprintIndex.body);
+    const body = intent.map((t) => `- ${t}`);
+    const lines = [`${type}: ${bp.title}`];
+    if (body.length)
+        lines.push('', ...body);
+    return lines.join('\n');
+}
+module.exports = { buildCommitMessage, buildFinalizeCommitMessage };

package/dist/commit-sha.js

@@ -0,0 +1,107 @@
+'use strict';
+/**
+ * task 커밋·explain.task_commits에 쓰는 짧은 SHA 길이.
+ * 그래프 토큰·프론트매터 표기를 8자리로 통일한다. 이 저장소 규모에서
+ * 충돌 위험은 낮고, git의 가변 abbrev(7+)보다 계약이 단순하다.
+ */
+const COMMIT_SHA_LEN = 8;
+const contextIds = require("./context-ids");
+const { validateSlug, formatStableIntentId, formatStableTaskId } = contextIds;
+const THREE_DIGIT_ID = /^\d{3}$/;
+const TASKS_ID = /^TASKS-(\d{3})$/;
+/**
+ * git 객체 이름을 소문자 8자리 hex로 정규화한다.
+ * 7–40자리 hex만 받고, 그보다 짧거나 비hex면 null.
+ *
+ * @param {unknown} value - rev-parse 결과 또는 기존 필드
+ * @returns {string | null}
+ */
+function normalizeCommitSha(value) {
+    // YAML이 순수 숫자 sha를 number로 읽을 수 있어 문자열로 맞춘다.
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value) || value < 0)
+            return null;
+        value = String(value);
+    }
+    if (typeof value !== 'string')
+        return null;
+    const hex = value.trim().toLowerCase();
+    if (!/^[0-9a-f]{7,40}$/.test(hex))
+        return null;
+    if (hex.length < COMMIT_SHA_LEN)
+        return null;
+    return hex.slice(0, COMMIT_SHA_LEN);
+}
+/**
+ * epic·blueprint key 한 쌍의 형식(번호 / slug)을 키 모양으로 판정한다.
+ * 한 자리·네 자리·number는 패딩하거나 잘라 맞추지 않는다 — 잘못된 ID를
+ * 추측해 고치면 다른 Epic·Blueprint의 커밋이 같은 ref로 묶인다.
+ * 형식이 섞인 쌍(번호 epic + slug blueprint)은 한 문서가 두 체계에 걸치므로 거절한다.
+ *
+ * @param {unknown} epicId - epic_id (`ddd` 또는 epic slug)
+ * @param {unknown} blueprintId - blueprint_id (`ddd` 또는 blueprint slug)
+ * @returns {'numeric' | 'slug'} 판정한 형식
+ * @throws {Error} 어느 쪽 형식도 아니거나 두 key의 형식이 다를 때
+ */
+function detectKeyFormat(epicId, blueprintId) {
+    const isDigits = (v) => typeof v === 'string' && THREE_DIGIT_ID.test(v);
+    const isSlug = (v) => typeof v === 'string' && validateSlug(v) === null;
+    if (isDigits(epicId)) {
+        if (!isDigits(blueprintId))
+            throw new Error('blueprint_id must be a three-digit id');
+        return 'numeric';
+    }
+    if (isSlug(epicId)) {
+        if (!isSlug(blueprintId))
+            throw new Error('blueprint_id must be a slug');
+        return 'slug';
+    }
+    throw new Error('epic_id must be a three-digit id or a slug');
+}
+/**
+ * `TASKS-NNN`에서 숫자만 취한다. `TASKS-1`을 `001`로 만들거나 접두를
+ * 붙이지 않는다. 잘못된 값을 보정하면 다른 task의 trailer가 된다.
+ *
+ * @param {unknown} value - tasks.md `bouncer.id`
+ * @returns {string} 세 자리 task 번호
+ */
+function requireTasksDigits(value) {
+    if (typeof value !== 'string') {
+        throw new Error('task id must be TASKS-NNN');
+    }
+    const match = TASKS_ID.exec(value);
+    if (!match) {
+        throw new Error('task id must be TASKS-NNN');
+    }
+    return match[1];
+}
+/**
+ * Epic·Blueprint·Task 식별자로 stable Task/Intent ref와 Git trailer 두 줄을 만든다.
+ * 형식은 key 모양으로 판정한다(번호 `ddd` 또는 slug). 구형 입력의 출력은 이전과 바이트까지 같다.
+ * 입력이 정본 형식이 아니거나 형식이 섞이면 커밋 전에 거절한다.
+ *
+ * @param {object} ids - task frontmatter에서 읽은 식별자
+ * @param {unknown} ids.epicId - `bouncer.epic_id` (`ddd` 또는 epic slug)
+ * @param {unknown} ids.blueprintId - `bouncer.blueprint_id` (`ddd` 또는 blueprint slug)
+ * @param {unknown} ids.taskId - `bouncer.id` (`TASKS-NNN`)
+ * @returns {{task: string, intent: string, trailers: [string, string]}}
+ *   task는 `EPIC-ddd/BP-ddd/TASK-ddd` 또는 `<epic>/<bp>/ddd`, intent는 task와 같은 형식의 blueprint ID,
+ *   trailers는 `Bouncer-Task` 다음 `Bouncer-Intent` 한 줄씩
+ * @throws {Error} key 형식 위반·혼합, `TASKS-NNN`이 아닌 task id
+ */
+function buildStableProvenance({ epicId, blueprintId, taskId }) {
+    const format = detectKeyFormat(epicId, blueprintId);
+    const task = requireTasksDigits(taskId);
+    const keys = { format, epicKey: epicId, blueprintKey: blueprintId };
+    const intent = formatStableIntentId(keys);
+    const taskRef = formatStableTaskId({ ...keys, task });
+    return {
+        task: taskRef,
+        intent,
+        trailers: [
+            `Bouncer-Task: ${taskRef}`,
+            `Bouncer-Intent: ${intent}`,
+        ],
+    };
+}
+module.exports = { COMMIT_SHA_LEN, normalizeCommitSha, buildStableProvenance };