@su-record/vibe 3.2.61 → 3.2.64

package/dist/tools/contract/agentContract.js

@@ -0,0 +1,140 @@
+/**
+ * 에이전트 계약 — 런타임 축을 **빌드타임에** 잡는다.
+ *
+ * vibe 는 빌드타임만 다룬다. 그런데 사용자가 만드는 것이 에이전트 제품일 때, 그 에이전트가
+ * 사용자 앞에서 내리는 판단은 vibe 의 어떤 게이트도 보지 않는다. 그렇다고 vibe 를 런타임에
+ * 넣으면 loop-contract 의 push·release·배포 금지를 정면으로 깬다. 그래서 vibe 가 런타임에
+ * 들어가는 대신 **런타임 게이트를 빌드타임에 생성**한다.
+ *
+ * **판정 대상이 도구 호출 로그인 것이 핵심이다.** LLM 이 에이전트의 출력을 채점하는 형태였다면
+ * 그것은 Model Judge 이고 완료 권한이 없다 (loop-contract Judge 권한 경계). "금지된 도구를
+ * 불렀는가" 는 관측된 사실이라 차단할 수 있다.
+ *
+ * 그래서 이 모듈은 `reverseDrift.ts` 와 **반대 방향의 결정**을 한다. 거기서는 `blocking: false`
+ * 가 리터럴 타입이라 차단하는 분류를 만들 수 없다 — 판정 주체가 LLM 추출이기 때문이다.
+ * 여기서는 차단이 정당하다 — 판정 주체가 로그이기 때문이다. 두 파일의 차이가 곧 권한 경계의
+ * 예시다.
+ *
+ * 판정할 수 없는 것은 게이트로 만들지 않는다: 에스컬레이션 조건("결제가 임계를 넘으면 사람에게
+ * 묻는다")은 조건 충족 여부가 로그에 없다. 선언은 받되 advisory 로 낸다 — 억지로 게이트에
+ * 넣으면 통과 의식이 되고, 그건 없는 게이트보다 나쁘다.
+ */
+const SECTION = /^#{1,4}\s*(?:\d+\.\s*)?Agent Contract\s*$/im;
+const FIELD_PATTERNS = [
+    ['allowedTools', /^\s*[-*]\s*\*{0,2}Allowed(?:\s+tools)?\*{0,2}\s*[:：]\s*(.+)$/gim],
+    ['forbiddenTools', /^\s*[-*]\s*\*{0,2}Forbidden(?:\s+tools)?\*{0,2}\s*[:：]\s*(.+)$/gim],
+    ['irreversibleOps', /^\s*[-*]\s*\*{0,2}Irreversible\*{0,2}\s*[:：]\s*(.+)$/gim],
+    ['escalations', /^\s*[-*]\s*\*{0,2}Escalate\*{0,2}\s*[:：]\s*(.+)$/gim],
+];
+/** 백틱·쉼표 표기를 견딘다. 글롭은 지원하지 않는다 — 정확히 일치만 인정한다 */
+function splitList(raw) {
+    return raw
+        .split(',')
+        .map((part) => part.replace(/`/g, '').trim())
+        .filter((part) => part.length > 0);
+}
+/** `## Agent Contract` 부터 다음 같은 수준 이상 헤딩 전까지 */
+function sectionBody(content) {
+    const match = content.match(SECTION);
+    if (!match || match.index === undefined)
+        return null;
+    const after = content.slice(match.index + match[0].length);
+    const next = after.search(/^#{1,4}\s+\S/m);
+    return next === -1 ? after : after.slice(0, next);
+}
+/**
+ * SPEC 에서 에이전트 계약을 뽑는다.
+ *
+ * 섹션이 없으면 `null` — 모든 기능에 에이전트가 있는 것은 아니다. 섹션 존재가 곧 스위치인
+ * 관례는 `## API Contract` 와 같다 (spec-template).
+ */
+export function parseAgentContract(specContent) {
+    const body = sectionBody(specContent);
+    if (body === null)
+        return null;
+    const contract = {
+        allowedTools: [], forbiddenTools: [], irreversibleOps: [], escalations: [],
+    };
+    for (const [key, pattern] of FIELD_PATTERNS) {
+        for (const line of body.matchAll(pattern)) {
+            contract[key].push(...splitList(line[1]));
+        }
+    }
+    // Escalate 는 자유 문장이라 쉼표로 쪼개면 문장이 잘린다 — 원문 줄을 그대로 쓴다
+    contract.escalations = [...body.matchAll(FIELD_PATTERNS[3][1])].map((m) => m[1].trim());
+    return contract;
+}
+/**
+ * 계약 정의 자체의 오류를 잡는다 (노드 가드).
+ *
+ * Allowed 와 Forbidden 이 겹칠 때 우선순위 규칙을 두지 않는 이유: 규칙을 기억해야 판정을
+ * 예측할 수 있고, 기억이 필요한 규칙은 틀린다. 정의 단계에서 막는다.
+ */
+export function validateAgentContract(contract) {
+    const findings = [];
+    const forbidden = new Set(contract.forbiddenTools);
+    const both = contract.allowedTools.filter((tool) => forbidden.has(tool));
+    if (both.length > 0) {
+        findings.push({
+            severity: 'P1',
+            code: 'tool-in-both-lists',
+            message: `Allowed 와 Forbidden 에 동시에 있는 도구: ${both.join(', ')} — 어느 쪽이 이기는지 정하지 않는다.`,
+        });
+    }
+    const declared = contract.allowedTools.length + contract.forbiddenTools.length
+        + contract.irreversibleOps.length + contract.escalations.length;
+    if (declared === 0) {
+        findings.push({
+            severity: 'P1',
+            code: 'empty-agent-contract',
+            message: 'Agent Contract 섹션이 비어 있다 — 섹션 존재가 검사 스위치인데 검사할 것이 없다.',
+        });
+    }
+    const orphanIrreversible = contract.irreversibleOps.filter((tool) => forbidden.has(tool));
+    if (orphanIrreversible.length > 0) {
+        findings.push({
+            severity: 'P2',
+            code: 'irreversible-also-forbidden',
+            message: `금지된 도구가 Irreversible 에도 있다: ${orphanIrreversible.join(', ')} — 승인 규칙이 사문이 된다.`,
+        });
+    }
+    return { valid: !findings.some((f) => f.severity === 'P1'), findings };
+}
+function violationOf(call, index, contract) {
+    if (contract.forbiddenTools.includes(call.tool)) {
+        return { kind: 'forbidden-tool', tool: call.tool, index, detail: '계약이 금지한 도구를 호출했다.' };
+    }
+    if (contract.irreversibleOps.includes(call.tool) && call.approved !== true) {
+        return {
+            kind: 'unapproved-irreversible',
+            tool: call.tool,
+            index,
+            detail: '되돌릴 수 없는 작업을 승인 기록 없이 호출했다.',
+        };
+    }
+    // allowlist 미선언(빈 목록)을 "아무것도 허용 안 함" 으로 읽으면 선언하지 않은 프로젝트가 전부 위반이 된다
+    if (contract.allowedTools.length > 0 && !contract.allowedTools.includes(call.tool)) {
+        return { kind: 'unlisted-tool', tool: call.tool, index, detail: 'allowlist 에 없는 도구를 호출했다.' };
+    }
+    return null;
+}
+/**
+ * 도구 호출 로그에 대해 계약을 단언한다.
+ *
+ * 로그가 없으면 `checked: false` — **위반 0건으로 적지 않는다.** 안 본 것과 봤는데 깨끗한 것은
+ * 다르다 (회전 비용 계측 축과 같은 규약).
+ */
+export function checkAgentToolLog(contract, log) {
+    const advisory = contract.escalations.map((condition) => `에스컬레이션 조건은 도구 로그로 판정할 수 없다 — 사람이 확인한다: ${condition}`);
+    if (!log) {
+        return { checked: false, violations: [], advisory, blocking: false };
+    }
+    const violations = [];
+    log.forEach((call, index) => {
+        const violation = violationOf(call, index, contract);
+        if (violation)
+            violations.push(violation);
+    });
+    return { checked: true, violations, advisory, blocking: violations.length > 0 };
+}
+//# sourceMappingURL=agentContract.js.map

package/dist/tools/contract/agentContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentContract.js","sourceRoot":"","sources":["../../../src/tools/contract/agentContract.ts"],"names":[],"mappings":"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"}

package/dist/tools/contract/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Contract Tools — 계약 드리프트 판정의 귀결을 고정하는 순수 함수 모음.
+ */
+export { REVERSE_DRIFT_KINDS, isReverseDriftKind, classifyReverseDrift, summarizeReverseDrift, formatReverseReport, formatReverseInboxLines, } from './reverseDrift.js';
+export type { ReverseDriftKind, ReverseDriftSeverity, ReverseDriftClassification, ReverseDriftFinding, ReverseDriftSummary, ReverseReportInput, } from './reverseDrift.js';
+export { parseAgentContract, validateAgentContract, checkAgentToolLog, } from './agentContract.js';
+export type { AgentContract, AgentContractCheck, AgentContractFinding, AgentContractFindingSeverity, AgentContractValidation, AgentToolCall, AgentViolation, AgentViolationKind, } from './agentContract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/contract/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACvB,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC"}

package/dist/tools/contract/index.js

@@ -0,0 +1,6 @@
+/**
+ * Contract Tools — 계약 드리프트 판정의 귀결을 고정하는 순수 함수 모음.
+ */
+export { REVERSE_DRIFT_KINDS, isReverseDriftKind, classifyReverseDrift, summarizeReverseDrift, formatReverseReport, formatReverseInboxLines, } from './reverseDrift.js';
+export { parseAgentContract, validateAgentContract, checkAgentToolLog, } from './agentContract.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/contract/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAU3B,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/dist/tools/contract/reverseDrift.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 역방향 계약 드리프트 — 구현에만 있고 SPEC 에 없는 표면의 분류·기록.
+ *
+ * 배경: `vibe.contract` 의 `check` 는 **SPEC → 구현** 한 방향만 본다. 구현이 SPEC 에 없는
+ * 엔드포인트·필드·상태 코드를 갖게 되어도 아무도 모르고, SPEC 은 승인 시점에 얼어붙는다.
+ *
+ * 방향만 뒤집는 것이 아니라 **등급 매핑을 뒤집는다.** 구현에만 있는 표면은 코드 실패가
+ * 아니라 SPEC 결손이다. 그리고 판정 주체가 LLM 추출이므로 loop-contract 의 Judge 권한
+ * 경계상 "판정된 P1" 이며 — 단독으로 루프를 차단할 권한이 없다.
+ *
+ * 그래서 이 모듈이 결정론으로 고정하는 것은 *판정* 이 아니라 **판정의 귀결**이다:
+ * 등급에 P1 이 없고(`ReverseDriftSeverity`), 차단이 타입 수준에서 불가능하며
+ * (`blocking: false` 리터럴), 목적지가 인박스로 고정된다. 규칙을 산문으로 적어두면
+ * 다음 사람이 P1 을 하나 추가하는 것으로 조용히 깨진다.
+ */
+/** 역방향 드리프트 종류 — `구현 ⊃ SPEC` 인 경우만. 구현이 SPEC 보다 좁은 것은 `check` 의 관할이다. */
+export type ReverseDriftKind = 'unspecified-endpoint' | 'unspecified-field' | 'unspecified-status-code' | 'unspecified-parameter';
+/** 분류기가 다루는 종류 전부 — 테스트가 순회 기준으로 읽는 SSOT */
+export declare const REVERSE_DRIFT_KINDS: readonly ReverseDriftKind[];
+/**
+ * 역방향 등급에는 P1 이 없다 — 타입 수준에서 없앤다.
+ * P1 이 존재하면 차단 권한 없는 판정이 차단하게 된다 (loop-contract Judge 권한 경계).
+ */
+export type ReverseDriftSeverity = 'P2' | 'P3';
+export interface ReverseDriftClassification {
+    severity: ReverseDriftSeverity;
+    /** 리터럴 `false` — 차단하는 분류를 만들 수 없다 */
+    blocking: false;
+    /** 리터럴 `'inbox'` — 게이트는 답을 기다리는 질문이고, SPEC 결손은 답을 기다리지 않는다 */
+    destination: 'inbox';
+    reason: string;
+}
+export declare function isReverseDriftKind(value: unknown): value is ReverseDriftKind;
+export declare function classifyReverseDrift(kind: ReverseDriftKind): ReverseDriftClassification;
+export interface ReverseDriftFinding {
+    kind: ReverseDriftKind;
+    /** 구현에서 발견한 표면 식별자 — 예: `GET /users/:id`, `get-user-by-id.response.200.phoneNumber` */
+    surface: string;
+    /** 구현 위치 `file:line` — 확인하지 못했으면 생략한다 (추측해 채우지 않는다) */
+    location?: string;
+    /** 한 줄 부연 */
+    note?: string;
+}
+export interface ReverseDriftSummary {
+    total: number;
+    byKind: Record<ReverseDriftKind, number>;
+    bySeverity: Record<ReverseDriftSeverity, number>;
+}
+export declare function summarizeReverseDrift(findings: readonly ReverseDriftFinding[]): ReverseDriftSummary;
+export interface ReverseReportInput {
+    feature: string;
+    /** 대조 기준이 된 SPEC 경로 */
+    specPath: string;
+    /** ISO-8601 */
+    comparedAt: string;
+    findings: readonly ReverseDriftFinding[];
+}
+/**
+ * `.vibe/contracts/<feature>.reverse.md` 본문.
+ *
+ * 발견 0건이어도 파일을 낸다 — "대조했고 결손이 없었다" 는 증거이고, 파일이 없는 것과
+ * 구분되어야 한다 (아직 안 돌린 것 vs 돌렸는데 깨끗한 것).
+ */
+export declare function formatReverseReport(input: ReverseReportInput): string;
+/**
+ * `loop-ledger.js inbox <name> ok <line...>` 에 넘길 줄들.
+ *
+ * 발견 0건이면 **빈 배열** — 인박스에 빈 블록을 남기지 않는다.
+ */
+export declare function formatReverseInboxLines(feature: string, findings: readonly ReverseDriftFinding[]): string[];
+//# sourceMappingURL=reverseDrift.d.ts.map

package/dist/tools/contract/reverseDrift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reverseDrift.d.ts","sourceRoot":"","sources":["../../../src/tools/contract/reverseDrift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GACxB,sBAAsB,GACtB,mBAAmB,GACnB,yBAAyB,GACzB,uBAAuB,CAAC;AAE5B,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB,EAAE,SAAS,gBAAgB,EAK1D,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,qCAAqC;IACrC,QAAQ,EAAE,KAAK,CAAC;IAChB,8DAA8D;IAC9D,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAgBD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,0BAA0B,CAUvF;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,gBAAgB,CAAC;IACvB,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;CAClD;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,GAAG,mBAAmB,CAcnG;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC1C;AAsCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAgBrE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,mBAAmB,EAAE,GACvC,MAAM,EAAE,CAUV"}

package/dist/tools/contract/reverseDrift.js

@@ -0,0 +1,136 @@
+/**
+ * 역방향 계약 드리프트 — 구현에만 있고 SPEC 에 없는 표면의 분류·기록.
+ *
+ * 배경: `vibe.contract` 의 `check` 는 **SPEC → 구현** 한 방향만 본다. 구현이 SPEC 에 없는
+ * 엔드포인트·필드·상태 코드를 갖게 되어도 아무도 모르고, SPEC 은 승인 시점에 얼어붙는다.
+ *
+ * 방향만 뒤집는 것이 아니라 **등급 매핑을 뒤집는다.** 구현에만 있는 표면은 코드 실패가
+ * 아니라 SPEC 결손이다. 그리고 판정 주체가 LLM 추출이므로 loop-contract 의 Judge 권한
+ * 경계상 "판정된 P1" 이며 — 단독으로 루프를 차단할 권한이 없다.
+ *
+ * 그래서 이 모듈이 결정론으로 고정하는 것은 *판정* 이 아니라 **판정의 귀결**이다:
+ * 등급에 P1 이 없고(`ReverseDriftSeverity`), 차단이 타입 수준에서 불가능하며
+ * (`blocking: false` 리터럴), 목적지가 인박스로 고정된다. 규칙을 산문으로 적어두면
+ * 다음 사람이 P1 을 하나 추가하는 것으로 조용히 깨진다.
+ */
+/** 분류기가 다루는 종류 전부 — 테스트가 순회 기준으로 읽는 SSOT */
+export const REVERSE_DRIFT_KINDS = [
+    'unspecified-endpoint',
+    'unspecified-field',
+    'unspecified-status-code',
+    'unspecified-parameter',
+];
+const KIND_SEVERITY = {
+    'unspecified-endpoint': 'P2',
+    'unspecified-field': 'P3',
+    'unspecified-status-code': 'P3',
+    'unspecified-parameter': 'P3',
+};
+const KIND_REASON = {
+    'unspecified-endpoint': 'SPEC 이 통째로 모르는 외부 표면 — 계약 리뷰 대상이 아니었다',
+    'unspecified-field': '응답/요청 필드가 SPEC 에 없다 — 소비자가 의존하기 시작하면 계약이 된다',
+    'unspecified-status-code': 'SPEC 에 없는 상태 코드 — 클라이언트가 처리 대상을 모른다',
+    'unspecified-parameter': 'SPEC 에 없는 파라미터 — 문서화되지 않은 입력 표면',
+};
+export function isReverseDriftKind(value) {
+    return typeof value === 'string' && REVERSE_DRIFT_KINDS.includes(value);
+}
+export function classifyReverseDrift(kind) {
+    if (!isReverseDriftKind(kind)) {
+        throw new Error(`[reverse-drift] 알 수 없는 종류: ${String(kind)}`);
+    }
+    return {
+        severity: KIND_SEVERITY[kind],
+        blocking: false,
+        destination: 'inbox',
+        reason: KIND_REASON[kind],
+    };
+}
+export function summarizeReverseDrift(findings) {
+    const byKind = {
+        'unspecified-endpoint': 0,
+        'unspecified-field': 0,
+        'unspecified-status-code': 0,
+        'unspecified-parameter': 0,
+    };
+    const bySeverity = { P2: 0, P3: 0 };
+    for (const finding of findings) {
+        byKind[finding.kind] += 1;
+        bySeverity[classifyReverseDrift(finding.kind).severity] += 1;
+    }
+    return { total: findings.length, byKind, bySeverity };
+}
+function formatFrontmatter(input, summary) {
+    const counts = REVERSE_DRIFT_KINDS.map((kind) => `  ${kind}: ${summary.byKind[kind]}`);
+    return [
+        '---',
+        `feature: ${input.feature}`,
+        `spec: ${input.specPath}`,
+        `compared-at: ${input.comparedAt}`,
+        'direction: implementation-to-spec',
+        'blocking: false',
+        `total: ${summary.total}`,
+        'kind-counts:',
+        ...counts,
+        '---',
+    ];
+}
+function formatFindingLine(finding) {
+    const location = finding.location ? ` — ${finding.location}` : '';
+    const note = finding.note ? ` (${finding.note})` : '';
+    return `- \`${finding.surface}\`${location}${note}`;
+}
+function formatKindSection(kind, findings) {
+    const matched = findings.filter((f) => f.kind === kind);
+    if (matched.length === 0)
+        return [];
+    const { severity, reason } = classifyReverseDrift(kind);
+    return [
+        '',
+        `## ${severity} — ${kind} (${matched.length})`,
+        '',
+        reason,
+        '',
+        ...matched.map(formatFindingLine),
+    ];
+}
+/**
+ * `.vibe/contracts/<feature>.reverse.md` 본문.
+ *
+ * 발견 0건이어도 파일을 낸다 — "대조했고 결손이 없었다" 는 증거이고, 파일이 없는 것과
+ * 구분되어야 한다 (아직 안 돌린 것 vs 돌렸는데 깨끗한 것).
+ */
+export function formatReverseReport(input) {
+    const summary = summarizeReverseDrift(input.findings);
+    const body = summary.total === 0
+        ? ['', '결손 없음 — 구현에서 발견한 모든 표면이 SPEC 에 존재한다.']
+        : REVERSE_DRIFT_KINDS.flatMap((kind) => formatKindSection(kind, input.findings));
+    return [
+        ...formatFrontmatter(input, summary),
+        '',
+        `# Reverse contract drift — ${input.feature}`,
+        '',
+        '> 구현에만 있고 SPEC 에 없는 표면. **루프를 차단하지 않는다** — 코드 실패가 아니라',
+        '> SPEC 결손이므로 인박스(사람 리뷰 큐)로 간다. SPEC 갱신 여부는 사람이 정한다.',
+        ...body,
+        '',
+    ].join('\n');
+}
+/**
+ * `loop-ledger.js inbox <name> ok <line...>` 에 넘길 줄들.
+ *
+ * 발견 0건이면 **빈 배열** — 인박스에 빈 블록을 남기지 않는다.
+ */
+export function formatReverseInboxLines(feature, findings) {
+    if (findings.length === 0)
+        return [];
+    const summary = summarizeReverseDrift(findings);
+    const head = `SPEC 결손 ${summary.total}건 (P2 ${summary.bySeverity.P2} · P3 ${summary.bySeverity.P3})`
+        + ` — 구현에만 있는 표면. 차단 아님, SPEC 갱신 여부는 사람이 정한다.`;
+    const items = findings.map((f) => {
+        const location = f.location ? ` @ ${f.location}` : '';
+        return `${classifyReverseDrift(f.kind).severity} ${f.kind}: ${f.surface}${location}`;
+    });
+    return [head, `근거: .vibe/contracts/${feature}.reverse.md`, ...items];
+}
+//# sourceMappingURL=reverseDrift.js.map

package/dist/tools/contract/reverseDrift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reverseDrift.js","sourceRoot":"","sources":["../../../src/tools/contract/reverseDrift.ts"],"names":[],"mappings":"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"}

package/dist/tools/docs/agentsMd.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `CLAUDE.md` → `AGENTS.md` 결정론 생성.
+ *
+ * ## 왜 생성인가
+ *
+ * 두 파일은 같은 사실의 두 집이다. `CLAUDE.md` 는 "AGENTS.md 는 재생성된다" 고 선언만 하고
+ * 검증하는 명령이 없었고, 그 결과 한 파일 안에서 **과잉 번역과 미번역이 공존**했다
+ * (실측 2026-09-02: `pnpm lint:ratchet` 이 `$vibe lint:ratchet` 으로 잘못 번역된 줄 1건,
+ * Dual-Harness Doctrine 절의 `/vibe` 디스패처가 번역 안 된 줄 1건).
+ *
+ * 사람이 두 벌을 손으로 맞추는 한 이 드리프트는 반복된다. 그래서 번역 규칙을 데이터로 꺼내고
+ * (`scripts/agents-md-rules.json`) 생성 결과와 저장소 파일을 `--check` 로 비교한다.
+ *
+ * ## 왜 단순 치환으로는 안 되는가
+ *
+ * `/vibe` → `$vibe` 를 그냥 돌리면 `@su-record/vibe`·`plugins/vibe/`·`.claude/vibe/` 가 함께 깨진다.
+ * 그래서 3단이다: **보호 → 치환 → 복원**. 그 뒤에 두 하네스가 의도적으로 다른 문단
+ * (파일 매핑 안내문, Codex 진입점 설명, Git include/exclude)을 `overrides` 로 갈아끼운다.
+ *
+ * `overrides` 는 **치환 이후** 텍스트에 적용된다 — 즉 `find` 는 번역된 형태(`$vibe`)로 쓴다.
+ * 각 override 는 정확히 한 번 매치돼야 한다: 0번이면 대상을 잃은 규칙이고(원문이 바뀌었는데
+ * 규칙이 안 따라왔다), 2번 이상이면 의도하지 않은 곳까지 갈아끼운다. 둘 다 게이트가 막는다.
+ */
+export interface AgentsMdRules {
+    /** 치환에서 제외할 리터럴 — `/vibe` 를 품고 있지만 슬래시 명령이 아닌 것들 */
+    protect: string[];
+    substitutions: {
+        find: string;
+        replace: string;
+        why: string;
+    }[];
+    /** 두 하네스가 의도적으로 다른 문단. 치환 이후 텍스트에 적용된다 */
+    overrides: {
+        find: string;
+        replace: string;
+        why: string;
+    }[];
+}
+export interface GenerateResult {
+    output: string;
+    /** 규칙 자체의 고장 — 대상을 잃었거나 너무 많이 잡는 규칙 */
+    findings: string[];
+}
+export declare function generateAgentsMd(source: string, rules: AgentsMdRules): GenerateResult;
+//# sourceMappingURL=agentsMd.d.ts.map

package/dist/tools/docs/agentsMd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentsMd.d.ts","sourceRoot":"","sources":["../../../src/tools/docs/agentsMd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAChE,0CAA0C;IAC1C,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7D;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAQD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,cAAc,CA4BrF"}

package/dist/tools/docs/agentsMd.js

@@ -0,0 +1,51 @@
+/**
+ * `CLAUDE.md` → `AGENTS.md` 결정론 생성.
+ *
+ * ## 왜 생성인가
+ *
+ * 두 파일은 같은 사실의 두 집이다. `CLAUDE.md` 는 "AGENTS.md 는 재생성된다" 고 선언만 하고
+ * 검증하는 명령이 없었고, 그 결과 한 파일 안에서 **과잉 번역과 미번역이 공존**했다
+ * (실측 2026-09-02: `pnpm lint:ratchet` 이 `$vibe lint:ratchet` 으로 잘못 번역된 줄 1건,
+ * Dual-Harness Doctrine 절의 `/vibe` 디스패처가 번역 안 된 줄 1건).
+ *
+ * 사람이 두 벌을 손으로 맞추는 한 이 드리프트는 반복된다. 그래서 번역 규칙을 데이터로 꺼내고
+ * (`scripts/agents-md-rules.json`) 생성 결과와 저장소 파일을 `--check` 로 비교한다.
+ *
+ * ## 왜 단순 치환으로는 안 되는가
+ *
+ * `/vibe` → `$vibe` 를 그냥 돌리면 `@su-record/vibe`·`plugins/vibe/`·`.claude/vibe/` 가 함께 깨진다.
+ * 그래서 3단이다: **보호 → 치환 → 복원**. 그 뒤에 두 하네스가 의도적으로 다른 문단
+ * (파일 매핑 안내문, Codex 진입점 설명, Git include/exclude)을 `overrides` 로 갈아끼운다.
+ *
+ * `overrides` 는 **치환 이후** 텍스트에 적용된다 — 즉 `find` 는 번역된 형태(`$vibe`)로 쓴다.
+ * 각 override 는 정확히 한 번 매치돼야 한다: 0번이면 대상을 잃은 규칙이고(원문이 바뀌었는데
+ * 규칙이 안 따라왔다), 2번 이상이면 의도하지 않은 곳까지 갈아끼운다. 둘 다 게이트가 막는다.
+ */
+const SENTINEL = String.fromCharCode(0);
+function splitAll(haystack, needle, replacement) {
+    return haystack.split(needle).join(replacement);
+}
+export function generateAgentsMd(source, rules) {
+    const findings = [];
+    // 긴 리터럴부터 보호한다 — `@su-record/vibe` 가 `su-record/vibe` 보다 먼저 잡혀야 한다
+    const protect = [...rules.protect].sort((a, b) => b.length - a.length);
+    let text = source;
+    protect.forEach((token, i) => {
+        text = splitAll(text, token, SENTINEL + i + SENTINEL);
+    });
+    for (const s of rules.substitutions)
+        text = splitAll(text, s.find, s.replace);
+    protect.forEach((token, i) => {
+        text = splitAll(text, SENTINEL + i + SENTINEL, token);
+    });
+    for (const o of rules.overrides) {
+        const hits = text.split(o.find).length - 1;
+        if (hits !== 1) {
+            findings.push(`override 가 ${hits}번 매치됐다 (정확히 1번이어야 한다): ${JSON.stringify(o.find.slice(0, 60))}`);
+            continue;
+        }
+        text = splitAll(text, o.find, o.replace);
+    }
+    return { output: text, findings };
+}
+//# sourceMappingURL=agentsMd.js.map

package/dist/tools/docs/agentsMd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentsMd.js","sourceRoot":"","sources":["../../../src/tools/docs/agentsMd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAgBH,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAExC,SAAS,QAAQ,CAAC,QAAgB,EAAE,MAAc,EAAE,WAAmB;IACrE,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,KAAoB;IACnE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,mEAAmE;IACnE,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACvE,IAAI,IAAI,GAAG,MAAM,CAAC;IAClB,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC3B,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,aAAa;QAAE,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAE9E,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC3B,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;YACf,QAAQ,CAAC,IAAI,CACX,cAAc,IAAI,0BAA0B,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAClF,CAAC;YACF,SAAS;QACX,CAAC;QACD,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACpC,CAAC"}

package/dist/tools/docs/cacheSurface.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 프리픽스 캐시 표면 문서(`vibe/rules/prefix-cache-surface.md`)의 판정 로직.
+ *
+ * 문서가 자산을 나열하는 순간 그것은 **두 번째 집**이 된다 — 실물이 움직이면 조용히 어긋난다.
+ * dsh 가 정확히 그렇게 무너졌다: 게이트가 걸린 `packages/README.md` 는 50개 전부 맞았고,
+ * 게이트 없는 루트 문서의 레이아웃 트리는 존재하지 않는 그룹 2개를 나열하고 17개를 빠뜨렸다.
+ * 그래서 나열은 허용하되 **양방향으로** 검사한다: 문서에 없는 실물도, 실물이 없는 문서 항목도 실패다.
+ *
+ * 파일시스템 수집은 여기서 하지 않는다 — 이 모듈은 순수 함수로 두고
+ * `scripts/validate-cache-surface.ts` 가 실물을 모아 넘긴다.
+ */
+/** 자산 문서라면 반드시 답해야 하는 두 질문 */
+export declare const REQUIRED_SUBSECTIONS: readonly ["Model Experience", "KV Cache effect"];
+export interface SurfaceSection {
+    id: string;
+    /** 마커 아래 본문 (다음 마커 직전까지) */
+    body: string;
+    /** 본문의 표에서 뽑은 백틱 경로 */
+    entries: string[];
+}
+export interface SurfaceFinding {
+    code: string;
+    message: string;
+}
+/** 문서를 절 단위로 쪼갠다 */
+export declare function parseSurfaceDoc(content: string): SurfaceSection[];
+/** 모든 절이 두 질문에 답했는가 */
+export declare function checkRequiredSubsections(sections: SurfaceSection[]): SurfaceFinding[];
+/**
+ * 나열된 절과 실물을 양방향으로 맞춘다.
+ *
+ * @param sections 문서에서 파싱한 절
+ * @param actual   절 id → 실제 존재하는 자산 경로. 여기 없는 절은 집계 절로 보고 건너뛴다
+ */
+export declare function checkEnumeratedSurfaces(sections: SurfaceSection[], actual: Record<string, readonly string[]>): SurfaceFinding[];
+export declare function checkCacheSurfaceDoc(content: string, actual: Record<string, readonly string[]>): SurfaceFinding[];
+//# sourceMappingURL=cacheSurface.d.ts.map

package/dist/tools/docs/cacheSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheSurface.d.ts","sourceRoot":"","sources":["../../../src/tools/docs/cacheSurface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,8BAA8B;AAC9B,eAAO,MAAM,oBAAoB,kDAAmD,CAAC;AAErF,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAsBD,oBAAoB;AACpB,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAQjE;AAED,uBAAuB;AACvB,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAarF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,EAAE,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,GACxC,cAAc,EAAE,CAsBlB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,GACxC,cAAc,EAAE,CAMlB"}

package/dist/tools/docs/cacheSurface.js

@@ -0,0 +1,98 @@
+/**
+ * 프리픽스 캐시 표면 문서(`vibe/rules/prefix-cache-surface.md`)의 판정 로직.
+ *
+ * 문서가 자산을 나열하는 순간 그것은 **두 번째 집**이 된다 — 실물이 움직이면 조용히 어긋난다.
+ * dsh 가 정확히 그렇게 무너졌다: 게이트가 걸린 `packages/README.md` 는 50개 전부 맞았고,
+ * 게이트 없는 루트 문서의 레이아웃 트리는 존재하지 않는 그룹 2개를 나열하고 17개를 빠뜨렸다.
+ * 그래서 나열은 허용하되 **양방향으로** 검사한다: 문서에 없는 실물도, 실물이 없는 문서 항목도 실패다.
+ *
+ * 파일시스템 수집은 여기서 하지 않는다 — 이 모듈은 순수 함수로 두고
+ * `scripts/validate-cache-surface.ts` 가 실물을 모아 넘긴다.
+ */
+/** 절을 식별하는 기계 마커 — 헤딩 문구가 바뀌어도 판정이 흔들리지 않게 */
+const SURFACE_MARKER = /<!--\s*surface:\s*([a-z0-9-]+)\s*-->/gi;
+/** 자산 문서라면 반드시 답해야 하는 두 질문 */
+export const REQUIRED_SUBSECTIONS = ['Model Experience', 'KV Cache effect'];
+/** `- **Model Experience**: …` 형태로 내용이 있는가 (헤딩만 있고 빈 절은 통과시키지 않는다) */
+function hasSubsection(body, label) {
+    const re = new RegExp(String.raw `^\s*[-*#]+\s*\*{0,2}` + label + String.raw `\*{0,2}\s*[:：]?\s*(.*)$`, 'im');
+    const m = body.match(re);
+    if (!m)
+        return false;
+    return m[1].trim().length > 0 || /\n\s*\S/.test(body.slice((m.index ?? 0) + m[0].length));
+}
+function tableEntries(body) {
+    const out = [];
+    for (const line of body.split('\n')) {
+        if (!line.trimStart().startsWith('|'))
+            continue;
+        for (const m of line.matchAll(/`([^`\n]+)`/g)) {
+            const v = m[1].trim();
+            if (/\.(md|js|ts|json)$/.test(v))
+                out.push(v);
+        }
+    }
+    return out;
+}
+/** 문서를 절 단위로 쪼갠다 */
+export function parseSurfaceDoc(content) {
+    const marks = [...content.matchAll(SURFACE_MARKER)];
+    return marks.map((m, i) => {
+        const start = (m.index ?? 0) + m[0].length;
+        const end = i + 1 < marks.length ? marks[i + 1].index ?? content.length : content.length;
+        const body = content.slice(start, end);
+        return { id: m[1], body, entries: tableEntries(body) };
+    });
+}
+/** 모든 절이 두 질문에 답했는가 */
+export function checkRequiredSubsections(sections) {
+    const out = [];
+    for (const s of sections) {
+        for (const label of REQUIRED_SUBSECTIONS) {
+            if (!hasSubsection(s.body, label)) {
+                out.push({
+                    code: 'missing-subsection',
+                    message: `표면 "${s.id}" 에 "${label}" 절이 없거나 비어 있다.`,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * 나열된 절과 실물을 양방향으로 맞춘다.
+ *
+ * @param sections 문서에서 파싱한 절
+ * @param actual   절 id → 실제 존재하는 자산 경로. 여기 없는 절은 집계 절로 보고 건너뛴다
+ */
+export function checkEnumeratedSurfaces(sections, actual) {
+    const out = [];
+    for (const [id, paths] of Object.entries(actual)) {
+        const section = sections.find((s) => s.id === id);
+        if (!section) {
+            out.push({ code: 'missing-surface', message: `표면 절 "${id}" 이 문서에 없다.` });
+            continue;
+        }
+        const documented = new Set(section.entries);
+        const real = new Set(paths);
+        for (const p of real) {
+            if (!documented.has(p)) {
+                out.push({ code: 'undocumented-asset', message: `${id}: 실물이 문서에 없다 — ${p}` });
+            }
+        }
+        for (const p of documented) {
+            if (!real.has(p)) {
+                out.push({ code: 'phantom-asset', message: `${id}: 문서에만 있고 실물이 없다 — ${p}` });
+            }
+        }
+    }
+    return out;
+}
+export function checkCacheSurfaceDoc(content, actual) {
+    const sections = parseSurfaceDoc(content);
+    if (sections.length === 0) {
+        return [{ code: 'no-surfaces', message: '표면 마커(<!-- surface: id -->)가 하나도 없다.' }];
+    }
+    return [...checkRequiredSubsections(sections), ...checkEnumeratedSurfaces(sections, actual)];
+}
+//# sourceMappingURL=cacheSurface.js.map