@wooojin/forgen 0.5.5 → 0.5.6

package/dist/host/codex-hook-alive.js

@@ -0,0 +1,51 @@
+/**
+ * Codex 훅 생존 마커 — ADR-016 D1
+ *
+ * Codex 는 미승인(untrusted)/변경된(modified) 훅을 조용히 skip 한다. "forgen 훅이 실제로 실행되고 있는가"
+ * 를 관측하는 유일한 choke point 는 codex-adapter 다 (Codex 가 forgen 훅을 실행하면 반드시 거친다).
+ * 어댑터가 턴 경계 이벤트에서 전역 마커를 갱신하고, notify 폴백(codex-notify)이 그 신선도를 본다.
+ *
+ * 훅 신뢰 상태는 hooks.json 단위로 모든 세션이 공유하므로 마커는 세션별이 아니라 전역 1개다.
+ * 어댑터가 매 훅마다 import 하므로 의존성은 node 내장 + paths 만 둔다.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { STATE_DIR } from '../core/paths.js';
+export const CODEX_HOOK_ALIVE_PATH = path.join(STATE_DIR, 'codex-hook-alive.json');
+/** notify 는 Stop 훅 직후 발화한다. Stop 훅 타임아웃(10s) 대비 넉넉한 창. */
+export const CODEX_HOOK_ALIVE_WINDOW_MS = 120_000;
+/** 턴 경계 이벤트만 기록 — PreToolUse/PostToolUse 마다 쓰지 않는다. */
+const ALIVE_EVENTS = new Set(['Stop', 'SubagentStop', 'UserPromptSubmit']);
+/** 어댑터 입력(stdin JSON)으로 마커 갱신. 대상 이벤트가 아니면 no-op. 실패는 삼킨다 (fail-open). */
+export function markCodexHookAlive(input, now = Date.now()) {
+    try {
+        const i = (input ?? {});
+        const event = typeof i.hook_event_name === 'string' ? i.hook_event_name
+            : typeof i.hookEventName === 'string' ? i.hookEventName : '';
+        if (!ALIVE_EVENTS.has(event))
+            return false;
+        const marker = { at: now, event };
+        if (typeof i.session_id === 'string')
+            marker.sessionId = i.session_id;
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+        fs.writeFileSync(CODEX_HOOK_ALIVE_PATH, JSON.stringify(marker));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readCodexHookAlive() {
+    try {
+        const m = JSON.parse(fs.readFileSync(CODEX_HOOK_ALIVE_PATH, 'utf-8'));
+        return typeof m.at === 'number' && Number.isFinite(m.at) ? m : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 최근 window 안에 forgen 훅이 Codex 에서 실행됐는가. */
+export function isCodexHookAlive(now = Date.now(), windowMs = CODEX_HOOK_ALIVE_WINDOW_MS) {
+    const m = readCodexHookAlive();
+    return m !== null && now - m.at >= 0 && now - m.at < windowMs;
+}

package/dist/host/codex-notify.d.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Codex `notify` 폴백 — ADR-016 D1
+ *
+ * Codex 는 config.toml 의 top-level `notify = [argv…]` 프로그램을 **턴 완료마다**(Stop 훅 뒤) detached 로
+ * 실행하고, JSON 페이로드를 마지막 argv 로 넘긴다. 훅과 달리 **신뢰(trust) 승인과 무관**하게 돈다.
+ * forgen 은 이것을 "훅이 조용히 skip 되는 동안의 안전망" 으로만 쓴다:
+ *
+ *   1. forgen 훅이 살아 있으면(codex-adapter 가 방금 alive 마커를 갱신) 아무것도 하지 않는다 —
+ *      auto-compound 는 Stop 훅(context-guard) 소관이다.
+ *   2. 훅이 돌지 않았으면 silent 플래그를 남기고(`forgen doctor` 가 노출), 세션이 충분히 길면 Stop 훅과
+ *      같은 디바운스 경로로 auto-compound 를 띄운다.
+ *
+ * 페이로드 (codex-rs/hooks/src/legacy_notify.rs, 0.153.4):
+ *   { "type":"agent-turn-complete", "thread-id", "turn-id", "cwd", "client"?, "input-messages":[…],
+ *     "last-assistant-message" }  — transcript 경로는 없다. `thread-id` 로 rollout 파일을 찾는다.
+ *
+ * argv: `codex-notify.js [-- <chain program> <args…>] <payload JSON>`
+ *   `--` 뒤는 사용자가 수동으로 체인한 자기 notifier (단일 argv 제약 우회). 페이로드를 붙여 먼저 전달한다.
+ *
+ * 실패 정책: 모든 단계 fail-open. stdout/stderr 는 Codex 가 /dev/null 로 버린다.
+ */
+export declare const CODEX_HOOKS_SILENT_PATH: string;
+export interface CodexNotifyPayload {
+    type?: string;
+    'thread-id'?: string;
+    'turn-id'?: string;
+    cwd?: string;
+    client?: string;
+}
+export interface CodexHooksSilent {
+    detectedAt: string;
+    sessionId: string;
+    cwd: string;
+    /** 연속으로 관측된 silent 턴 수 */
+    count: number;
+}
+export type NotifyOutcome = 'nested-run' | 'no-payload' | 'ignored-event' | 'hooks-alive' | 'silent-recorded' | 'silent-compound-spawned';
+/** argv(스크립트 뒤) → 체인 프로그램 + 페이로드. 페이로드는 항상 마지막 argv. */
+export declare function parseNotifyArgv(argv: string[]): {
+    chain: string[];
+    payloadRaw: string | null;
+    payload: CodexNotifyPayload | null;
+};
+/** doctor 용 — 유효(24h 이내)한 silent 관측만 반환. */
+export declare function readCodexHooksSilent(now?: number): CodexHooksSilent | null;
+export interface NotifyDeps {
+    now?: number;
+    env?: NodeJS.ProcessEnv;
+    /** 테스트 주입: auto-compound 디바운스 트리거 */
+    spawnCompound?: (sessionId: string, transcriptPath: string, promptCount: number, cwd: string) => Promise<boolean>;
+    /** 테스트 주입: forgen hook-config 조회 */
+    isHookEnabled?: (name: string) => boolean;
+}
+export declare function handleNotify(argv: string[], deps?: NotifyDeps): Promise<NotifyOutcome>;

package/dist/host/codex-notify.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Codex `notify` 폴백 — ADR-016 D1
+ *
+ * Codex 는 config.toml 의 top-level `notify = [argv…]` 프로그램을 **턴 완료마다**(Stop 훅 뒤) detached 로
+ * 실행하고, JSON 페이로드를 마지막 argv 로 넘긴다. 훅과 달리 **신뢰(trust) 승인과 무관**하게 돈다.
+ * forgen 은 이것을 "훅이 조용히 skip 되는 동안의 안전망" 으로만 쓴다:
+ *
+ *   1. forgen 훅이 살아 있으면(codex-adapter 가 방금 alive 마커를 갱신) 아무것도 하지 않는다 —
+ *      auto-compound 는 Stop 훅(context-guard) 소관이다.
+ *   2. 훅이 돌지 않았으면 silent 플래그를 남기고(`forgen doctor` 가 노출), 세션이 충분히 길면 Stop 훅과
+ *      같은 디바운스 경로로 auto-compound 를 띄운다.
+ *
+ * 페이로드 (codex-rs/hooks/src/legacy_notify.rs, 0.153.4):
+ *   { "type":"agent-turn-complete", "thread-id", "turn-id", "cwd", "client"?, "input-messages":[…],
+ *     "last-assistant-message" }  — transcript 경로는 없다. `thread-id` 로 rollout 파일을 찾는다.
+ *
+ * argv: `codex-notify.js [-- <chain program> <args…>] <payload JSON>`
+ *   `--` 뒤는 사용자가 수동으로 체인한 자기 notifier (단일 argv 제약 우회). 페이로드를 붙여 먼저 전달한다.
+ *
+ * 실패 정책: 모든 단계 fail-open. stdout/stderr 는 Codex 가 /dev/null 로 버린다.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { STATE_DIR } from '../core/paths.js';
+import { isCodexHookAlive } from './codex-hook-alive.js';
+import { countCodexUserPrompts, findCodexRollout } from './codex-rollout.js';
+export const CODEX_HOOKS_SILENT_PATH = path.join(STATE_DIR, 'codex-hooks-silent.json');
+/** silent 플래그 유효기간 — 이보다 오래된 관측은 doctor 가 무시한다. */
+const SILENT_TTL_MS = 24 * 60 * 60 * 1000;
+/** Stop 훅 경로와 같은 "의미 있는 세션" 임계. */
+const MIN_USER_PROMPTS = 10;
+/** argv(스크립트 뒤) → 체인 프로그램 + 페이로드. 페이로드는 항상 마지막 argv. */
+export function parseNotifyArgv(argv) {
+    if (argv.length === 0)
+        return { chain: [], payloadRaw: null, payload: null };
+    const payloadRaw = argv[argv.length - 1];
+    const chain = argv[0] === '--' ? argv.slice(1, -1) : [];
+    let payload = null;
+    try {
+        const parsed = JSON.parse(payloadRaw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            payload = parsed;
+    }
+    catch { /* 페이로드 아님 */ }
+    return { chain, payloadRaw, payload };
+}
+/** doctor 용 — 유효(24h 이내)한 silent 관측만 반환. */
+export function readCodexHooksSilent(now = Date.now()) {
+    try {
+        const s = JSON.parse(fs.readFileSync(CODEX_HOOKS_SILENT_PATH, 'utf-8'));
+        const at = Date.parse(s.detectedAt);
+        if (!Number.isFinite(at) || now - at > SILENT_TTL_MS)
+            return null;
+        if (typeof s.sessionId !== 'string' || typeof s.count !== 'number')
+            return null;
+        return s;
+    }
+    catch {
+        return null;
+    }
+}
+function recordSilent(sessionId, cwd, now) {
+    const prev = readCodexHooksSilent(now);
+    const next = {
+        detectedAt: new Date(now).toISOString(),
+        sessionId,
+        cwd,
+        count: (prev?.count ?? 0) + 1,
+    };
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(CODEX_HOOKS_SILENT_PATH, JSON.stringify(next));
+}
+function clearSilent() {
+    try {
+        fs.rmSync(CODEX_HOOKS_SILENT_PATH, { force: true });
+    }
+    catch { /* noop */ }
+}
+function runChain(chain, payloadRaw) {
+    if (chain.length === 0)
+        return;
+    try {
+        const child = spawn(chain[0], [...chain.slice(1), payloadRaw], { detached: true, stdio: 'ignore' });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch { /* fail-open */ }
+}
+/** Stop 경로는 context-guard 훅이 auto-compound 를 띄운다 — 사용자가 그 훅을 껐으면 폴백도 띄우지 않는다. */
+async function contextGuardEnabled(deps) {
+    try {
+        const isEnabled = deps.isHookEnabled ?? (await import('../hooks/hook-config.js')).isHookEnabled;
+        return isEnabled('context-guard');
+    }
+    catch {
+        return true; // 설정을 못 읽으면 기본값(활성)
+    }
+}
+export async function handleNotify(argv, deps = {}) {
+    const env = deps.env ?? process.env;
+    const now = deps.now ?? Date.now();
+    // forgen 자신의 추출용 `codex exec` — 재귀/오탐 방지 (env 는 Codex 세션 시작 시점 스냅샷으로 상속된다).
+    if (env.FORGEN_NESTED_RUN === '1')
+        return 'nested-run';
+    const { chain, payloadRaw, payload } = parseNotifyArgv(argv);
+    if (payloadRaw !== null)
+        runChain(chain, payloadRaw);
+    if (!payload)
+        return 'no-payload';
+    if (payload.type !== 'agent-turn-complete')
+        return 'ignored-event';
+    if (isCodexHookAlive(now)) {
+        clearSilent();
+        return 'hooks-alive';
+    }
+    const sessionId = typeof payload['thread-id'] === 'string' ? payload['thread-id'] : 'unknown';
+    const cwd = typeof payload.cwd === 'string' && payload.cwd.length > 0 ? payload.cwd : process.cwd();
+    try {
+        recordSilent(sessionId, cwd, now);
+    }
+    catch { /* fail-open */ }
+    // 훅이 돌지 않으므로 Stop 트리거 auto-compound 도 없다 → 같은 디바운스 경로로 대신 띄운다.
+    // (프롬프트 수는 rollout 전체 기준이라 resume 된 세션에서는 Stop 경로의 훅 카운터보다 클 수 있다.)
+    try {
+        if (!(await contextGuardEnabled(deps)))
+            return 'silent-recorded';
+        const codexHome = env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+        const rollout = findCodexRollout(codexHome, sessionId);
+        if (!rollout)
+            return 'silent-recorded';
+        const prompts = countCodexUserPrompts(rollout);
+        if (prompts < MIN_USER_PROMPTS)
+            return 'silent-recorded';
+        const spawnCompound = deps.spawnCompound ?? (async (sid, transcript, count, dir) => {
+            // 훅 경로에선 codex-adapter 가 주입하는 값 — 러너의 evidence/timing 이 rt:"codex" 로 태깅된다.
+            // (추출에 쓸 LLM host 는 이것과 무관하게 profile.default_host 로 정해진다 — Stop 경로와 동일.)
+            process.env.FORGEN_RUNTIME = 'codex';
+            const { maybeSpawnAutoCompound } = await import('../hooks/context-guard.js');
+            return maybeSpawnAutoCompound(sid, transcript, count, dir);
+        });
+        return (await spawnCompound(sessionId, rollout, prompts, cwd)) ? 'silent-compound-spawned' : 'silent-recorded';
+    }
+    catch {
+        return 'silent-recorded';
+    }
+}
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
+    handleNotify(process.argv.slice(2)).catch(() => { });
+}

package/dist/host/codex-rollout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Codex rollout 파일 헬퍼 — ADR-016 (SessionEnd 훅 + notify 폴백 공용)
+ *
+ * rollout: `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-<local ts>-<thread id>.jsonl` (compact JSONL).
+ */
+/**
+ * thread id(= 훅의 session_id = notify 의 `thread-id`) 로 rollout 파일을 찾는다 (최근 날짜부터).
+ * id 는 UUID 형태만 허용한다.
+ */
+export declare function findCodexRollout(codexHome: string, threadId: string): string | null;
+/** 스캔 상한. SessionEnd 훅은 3s 예산이라 전체 스트리밍(239MB ≈ 3s) 대신 raw 바이트 스캔 + 상한을 쓴다. */
+export declare const CODEX_PROMPT_SCAN_MAX_BYTES: number;
+/**
+ * Codex rollout 의 *실제 사용자 프롬프트* 수 — `event_msg` / `payload.type:"user_message"` 레코드.
+ *
+ * `response_item` role=user 는 AGENTS.md·환경 컨텍스트 주입까지 포함해 실측 ~1.8배 과대계수이고
+ * (51 vs 91), 줄당 수십 KB 인 tool 출력 때문에 "앞 200KB 만 JSON.parse" 로는 프롬프트 1~2개밖에 못 본다.
+ * 그래서 JSON 을 파싱하지 않고 구조 수준의 바이트 패턴을 센다 — 문자열 값 안의 같은 텍스트는 따옴표가
+ * `\"` 로 이스케이프되므로 매치되지 않는다. maxBytes 까지만 읽는다 (하한 추정).
+ */
+export declare function countCodexUserPrompts(rolloutPath: string, maxBytes?: number): number;

package/dist/host/codex-rollout.js

@@ -0,0 +1,82 @@
+/**
+ * Codex rollout 파일 헬퍼 — ADR-016 (SessionEnd 훅 + notify 폴백 공용)
+ *
+ * rollout: `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-<local ts>-<thread id>.jsonl` (compact JSONL).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** rollout 탐색 시 최근 일자 디렉토리만 본다 (resume 된 오래된 세션 대비 여유). */
+const MAX_DAY_DIRS = 45;
+function sortedDesc(dir) {
+    try {
+        return fs.readdirSync(dir).sort().reverse();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * thread id(= 훅의 session_id = notify 의 `thread-id`) 로 rollout 파일을 찾는다 (최근 날짜부터).
+ * id 는 UUID 형태만 허용한다.
+ */
+export function findCodexRollout(codexHome, threadId) {
+    if (!/^[A-Za-z0-9-]{8,64}$/.test(threadId))
+        return null;
+    const root = path.join(codexHome, 'sessions');
+    let scanned = 0;
+    for (const y of sortedDesc(root)) {
+        for (const m of sortedDesc(path.join(root, y))) {
+            for (const d of sortedDesc(path.join(root, y, m))) {
+                if (scanned >= MAX_DAY_DIRS)
+                    return null;
+                scanned += 1;
+                const dayDir = path.join(root, y, m, d);
+                const hit = sortedDesc(dayDir).find((f) => f.startsWith('rollout-') && f.endsWith('.jsonl') && f.includes(`-${threadId}`));
+                if (hit)
+                    return path.join(dayDir, hit);
+            }
+        }
+    }
+    return null;
+}
+const USER_PROMPT_NEEDLE = Buffer.from('"type":"user_message"');
+const CHUNK_BYTES = 1024 * 1024;
+/** 스캔 상한. SessionEnd 훅은 3s 예산이라 전체 스트리밍(239MB ≈ 3s) 대신 raw 바이트 스캔 + 상한을 쓴다. */
+export const CODEX_PROMPT_SCAN_MAX_BYTES = 64 * 1024 * 1024;
+/**
+ * Codex rollout 의 *실제 사용자 프롬프트* 수 — `event_msg` / `payload.type:"user_message"` 레코드.
+ *
+ * `response_item` role=user 는 AGENTS.md·환경 컨텍스트 주입까지 포함해 실측 ~1.8배 과대계수이고
+ * (51 vs 91), 줄당 수십 KB 인 tool 출력 때문에 "앞 200KB 만 JSON.parse" 로는 프롬프트 1~2개밖에 못 본다.
+ * 그래서 JSON 을 파싱하지 않고 구조 수준의 바이트 패턴을 센다 — 문자열 값 안의 같은 텍스트는 따옴표가
+ * `\"` 로 이스케이프되므로 매치되지 않는다. maxBytes 까지만 읽는다 (하한 추정).
+ */
+export function countCodexUserPrompts(rolloutPath, maxBytes = CODEX_PROMPT_SCAN_MAX_BYTES) {
+    const fd = fs.openSync(rolloutPath, 'r');
+    try {
+        const overlap = USER_PROMPT_NEEDLE.length - 1;
+        const buf = Buffer.alloc(CHUNK_BYTES + overlap);
+        let carry = 0;
+        let pos = 0;
+        let count = 0;
+        while (pos < maxBytes) {
+            const read = fs.readSync(fd, buf, carry, Math.min(CHUNK_BYTES, maxBytes - pos), pos);
+            if (read <= 0)
+                break;
+            const view = buf.subarray(0, carry + read);
+            let idx = view.indexOf(USER_PROMPT_NEEDLE);
+            while (idx !== -1) {
+                count += 1;
+                idx = view.indexOf(USER_PROMPT_NEEDLE, idx + USER_PROMPT_NEEDLE.length);
+            }
+            // 청크 경계에 걸친 패턴 대비: 끝 overlap 바이트를 다음 청크 앞에 붙인다 (needle 보다 짧아 이중계수 없음).
+            carry = Math.min(overlap, view.length);
+            view.copy(buf, 0, view.length - carry, view.length);
+            pos += read;
+        }
+        return count;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}

package/dist/host/exec-host.js

@@ -82,7 +82,11 @@ export function execHost(opts) {
         '--skip-git-repo-check',
         opts.prompt,
     ];
-    const stdout = execFileSync('codex', args, baseOpts);
+    // ADR-016 (critic m2): Codex 추출 run 에도 중첩 표식을 준다. `--ephemeral` 은 rollout 만 안 남길 뿐
+    // 사용자 config(훅·notify)는 그대로 로드한다 — 표식이 없으면 forgen 훅이 추출 세션에서 발화하고
+    // notify 폴백이 그 세션을 "훅 미발화" 로 오기록한다.
+    const codexEnv = (opts.nestedRun ?? true) ? { ...(baseOpts.env ?? {}), ...NESTED_RUN_ENV } : baseOpts.env;
+    const stdout = execFileSync('codex', args, { ...baseOpts, env: codexEnv });
     const parsed = parseCodexJsonlOutput(stdout.toString());
     return {
         message: parsed.message,

package/dist/host/install-claude.d.ts

@@ -10,6 +10,7 @@
  *   3. Settings hooks injection: ~/.claude/settings.json 의 hooks 머지 (forgen entry idempotent)
  *   4. MCP register: ~/.claude.json 에 mcpServers.forgen-compound 추가
  *   5. Dev-guide skills: ~/.claude/skills/forgen-<stack>-<skill>/ 설치 (forgen-managed only)
+ *   6. verify skill: ~/.claude/skills/verify/ 설치 (ADR-016 D3 — 사용자 소유면 보존)
  *
  * 사용자 비-forgen 자산 보존 + 재실행 idempotent.
  */
@@ -21,7 +22,17 @@ export interface ClaudeInstallOptions {
     dryRun?: boolean;
     /** MCP forgen-compound 등록 여부 (default true). */
     registerMcp?: boolean;
+    /** ADR-016 D3: user-level `verify` 스킬 설치 여부 (default true). */
+    installVerifySkill?: boolean;
 }
+/** ADR-016 D3 — `~/.claude/skills/verify` 설치 결과. */
+export type VerifySkillStatus = 
+/** forgen-managed 스킬을 새로 썼거나 갱신함 */
+'installed'
+/** 사용자가 직접 만든 `verify` 스킬이 있어 건드리지 않음 */
+ | 'user-owned'
+/** --no-verify-skill 또는 자산 부재 */
+ | 'skipped';
 export interface ClaudeInstallResult {
     homeDir: string;
     pluginCachePath: string;
@@ -35,5 +46,8 @@ export interface ClaudeInstallResult {
     skillsPath: string;
     skillsInstalled: number;
     skillsRemoved: number;
+    verifySkill: VerifySkillStatus;
 }
+/** `<skillsDir>/verify` 가 사용자 소유인가 (심링크 / 마커 없는 SKILL.md / SKILL.md 없이 다른 파일만 있음). */
+export declare function isUserOwnedVerifySkill(skillsDir: string): boolean;
 export declare function planClaudeInstall(opts: ClaudeInstallOptions): ClaudeInstallResult;

package/dist/host/install-claude.js

@@ -10,6 +10,7 @@
  *   3. Settings hooks injection: ~/.claude/settings.json 의 hooks 머지 (forgen entry idempotent)
  *   4. MCP register: ~/.claude.json 에 mcpServers.forgen-compound 추가
  *   5. Dev-guide skills: ~/.claude/skills/forgen-<stack>-<skill>/ 설치 (forgen-managed only)
+ *   6. verify skill: ~/.claude/skills/verify/ 설치 (ADR-016 D3 — 사용자 소유면 보존)
  *
  * 사용자 비-forgen 자산 보존 + 재실행 idempotent.
  */
@@ -301,6 +302,54 @@ function installDevGuideSkills(opts) {
     }
     return { skillsPath: skillsDir, skillsInstalled: installed, skillsRemoved: removed };
 }
+// ── 6. verify skill (ADR-016 D3) ───────────────────────────────────────
+/** frontmatter 직후에 forgen-managed 마커가 있는 SKILL.md 만 forgen 소유로 본다. */
+const MANAGED_SKILL_RE = /^---\n[\s\S]*?\n---\n\s*<!-- forgen-managed -->/;
+/** `<skillsDir>/verify` 가 사용자 소유인가 (심링크 / 마커 없는 SKILL.md / SKILL.md 없이 다른 파일만 있음). */
+export function isUserOwnedVerifySkill(skillsDir) {
+    const dir = path.join(skillsDir, 'verify');
+    try {
+        if (fs.lstatSync(dir).isSymbolicLink())
+            return true;
+    }
+    catch {
+        return false; // 없음
+    }
+    const file = path.join(dir, 'SKILL.md');
+    try {
+        if (fs.lstatSync(file).isSymbolicLink())
+            return true;
+        return !MANAGED_SKILL_RE.test(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        // SKILL.md 없음 — 디렉토리에 다른 것이 있으면 사용자가 만들던 것
+        try {
+            return fs.readdirSync(dir).length > 0;
+        }
+        catch {
+            return true;
+        }
+    }
+}
+/**
+ * Claude Code 2.1.286+ 는 project/user 스킬에 `verify` 가 있으면 커밋 직전에 실행하라고 모델에 안내한다
+ * (플러그인 스킬 `forgen:verify` 는 해당 없음). 그래서 user 레벨에 un-namespaced 로 설치한다.
+ * 사용자 소유 스킬은 절대 덮어쓰지 않는다.
+ */
+function installVerifySkill(opts) {
+    const src = path.join(opts.pkgRoot, 'assets', 'claude', 'skills', 'verify', 'SKILL.md');
+    if (!fs.existsSync(src))
+        return 'skipped';
+    if (isUserOwnedVerifySkill(opts.skillsDir))
+        return 'user-owned';
+    if (opts.dryRun)
+        return 'installed';
+    const dir = path.join(opts.skillsDir, 'verify');
+    fs.mkdirSync(dir, { recursive: true });
+    // 심링크가 아니라 복사 — 마커로 소유를 판정하고, npm 경로가 바뀌어도 깨지지 않게.
+    fs.copyFileSync(src, path.join(dir, 'SKILL.md'));
+    return 'installed';
+}
 // ── public ─────────────────────────────────────────────────────────────
 export function planClaudeInstall(opts) {
     if (!opts.pkgRoot || !fs.existsSync(opts.pkgRoot)) {
@@ -324,6 +373,9 @@ export function planClaudeInstall(opts) {
         ? registerMcpInClaudeJson({ pkgRoot: opts.pkgRoot, claudeJsonPath, dryRun })
         : { registered: false, alreadyPresent: false };
     const skills = installDevGuideSkills({ pkgRoot: opts.pkgRoot, skillsDir, dryRun });
+    const verifySkill = (opts.installVerifySkill ?? true)
+        ? installVerifySkill({ pkgRoot: opts.pkgRoot, skillsDir, dryRun })
+        : 'skipped';
     return {
         homeDir,
         pluginCachePath: cacheDir,
@@ -337,5 +389,6 @@ export function planClaudeInstall(opts) {
         skillsPath: skills.skillsPath,
         skillsInstalled: skills.skillsInstalled,
         skillsRemoved: skills.skillsRemoved,
+        verifySkill,
     };
 }

package/dist/host/install-codex.d.ts

@@ -24,7 +24,23 @@ export interface CodexInstallOptions {
     releaseMode?: boolean;
     /** AGENTS.md 위치 override (default: pkgRoot 기준 자동 resolve). 격리 테스트용. */
     agentsMdPath?: string;
+    /** ADR-016 D1: config.toml 에 forgen notify 폴백 등록 여부 (default true). */
+    registerNotify?: boolean;
 }
+/** ADR-016 D1 — config.toml `notify` 등록 결과. */
+export type CodexNotifyStatus = 
+/** forgen 블록을 새로 썼거나 갱신함 */
+'installed'
+/** 이미 동일한 forgen 블록이 있음 */
+ | 'already-present'
+/** 사용자가 직접 정의한 `notify` 가 있어 건드리지 않음 (단일 argv 라 병합 불가) */
+ | 'user-defined'
+/** forgen 블록의 notify 줄이 손으로 고쳐져(여러 줄 배열 등) 안전하게 다시 쓸 수 없어 그대로 둠 */
+ | 'custom-block'
+/** --no-notify: 블록이 없었음 */
+ | 'skipped'
+/** --no-notify: 기존 forgen 블록을 제거함 */
+ | 'removed';
 export interface CodexInstallResult {
     codexHome: string;
     hooksPath: string;
@@ -52,19 +68,47 @@ export interface CodexInstallResult {
     hookTrust: CodexHookTrustAudit;
     /** ADR-014 D2: config.toml `[features] multi_agent = true` 여부 (false 면 ch-* 에이전트 spawn 불가 → 안내) */
     multiAgentEnabled: boolean;
+    /** ADR-016 D1: config.toml `notify` 폴백 등록 결과 */
+    notify: CodexNotifyStatus;
 }
 export interface CodexHookTrustAudit {
     /** hooks.json 의 forgen hook 명령 수 (Codex 가 지원하는 이벤트만) */
     total: number;
     /** Codex 가 모르는 이벤트라 조용히 무시되는 forgen 엔트리 (`<event>:<i>:<j>`) — trust 대상이 아님 */
     ignoredByCodex: string[];
-    /** config.toml `[hooks.state."<hooks.json>:<event>:<i>:<j>"]` 에 trusted_hash 가 있는 수 */
+    /** trusted_hash 가 현재 핸들러의 해시와 일치하고 꺼져 있지 않은 수 (Codex 가 실제로 실행하는 훅) */
     trusted: number;
     /** 신뢰 기록이 없는 hook 키 (`<event>:<i>:<j>`) */
     untrusted: string[];
+    /**
+     * ADR-016 D2: 신뢰 기록은 있으나 핸들러가 바뀌어 해시가 어긋난 hook 키. Codex 는 `/hooks` 재승인
+     * 전까지 이 훅도 skip 한다 (이전엔 키 존재만 봐서 "trusted" 로 오표시).
+     */
+    modified: string[];
+    /** 승인돼 있고 해시도 맞지만 사용자가 `/hooks` 에서 끈 훅 (`enabled = false`) — Codex 가 실행하지 않는다 */
+    disabled: string[];
     /** config.toml 자체가 없거나 hooks.state 가 전혀 없으면 true (Codex 가 아직 한 번도 훅을 review 안 함) */
     noStateRecorded: boolean;
 }
+/**
+ * config.toml 에 forgen notify 블록을 upsert.
+ *
+ * - Codex 의 `notify` 는 top-level 단일 argv 다. 사용자가 이미 정의했으면 **건드리지 않는다** — 그리고
+ *   forgen 블록이 남아 있으면 제거한다 (중복 키 = config.toml 파싱 실패 → Codex 기동 불가).
+ * - top-level 키는 첫 테이블 헤더 앞에 와야 하므로 블록은 항상 파일 최상단(BOM 뒤)에 둔다.
+ * - 사용자가 forgen 블록의 argv 뒤에 `"--", "<prog>", …` 로 자기 notifier 를 체인해 뒀으면 그 꼬리를 보존.
+ *   블록의 notify 줄을 한 줄 JSON 으로 읽을 수 없으면(여러 줄 배열 등 손편집) 아무것도 바꾸지 않는다.
+ * - 블록 사이에 Codex 가 끼워 넣은 줄(root 키)은 블록 바로 뒤로 옮겨 보존한다.
+ */
+export declare function upsertNotifyBlock(currentToml: string, pkgRoot: string): {
+    content: string;
+    status: CodexNotifyStatus;
+};
+/** forgen notify 블록 제거 (`--no-notify`, uninstall). 블록 사이에 끼어든 다른 줄은 보존. */
+export declare function removeNotifyBlock(currentToml: string): {
+    content: string;
+    removed: boolean;
+};
 interface HooksFile {
     description?: string;
     hooks: Record<string, Array<unknown>>;
@@ -80,10 +124,28 @@ export declare const CODEX_SUPPORTED_HOOK_EVENTS: ReadonlySet<string>;
 /** Codex 는 hooks.state 키에 이벤트명을 snake_case 로 쓴다 (PreToolUse → pre_tool_use). */
 export declare function codexHookEventKey(event: string): string;
 /**
- * hooks.json 의 forgen 엔트리 각각에 대해 config.toml 의
- * `[hooks.state."<hooksPath>:<event>:<groupIdx>:<hookIdx>"]` 섹션(trusted_hash) 존재를 대조한다.
- * trusted_hash 자체는 검증하지 않는다 — Codex 가 변경된 훅을 review 전까지 skip 하는 정책을
- * forgen 이 우회하지 않기 위해, *기록 유무* 만 가시화한다 (ADR-014 D4).
+ * ADR-016 D2 — Codex 0.153.4 의 hook trust 해시 재현 (`hook_hash`, discovery.rs).
+ *
+ * 해시는 *핸들러 단위*: `{event_name, matcher?, hooks:[정규화된 핸들러 1개]}` 의 canonical JSON sha256.
+ * 정규화: timeout 은 기본값/clamp 적용 후 항상 포함, async 항상 포함, statusMessage 는 있을 때만,
+ * additionalContextLimit 은 허용 이벤트에서 기본값(2500)이 아닐 때만. 파일 경로·인덱스·미지 필드는 불포함.
+ * `type:"command"` 가 아니면 null (forgen 은 command 훅만 쓴다).
+ */
+export declare function codexHookTrustHash(event: string, matcher: unknown, handler: {
+    type?: unknown;
+    command?: unknown;
+    timeout?: unknown;
+    async?: unknown;
+    statusMessage?: unknown;
+    additionalContextLimit?: unknown;
+}): string | null;
+/**
+ * hooks.json 의 forgen 엔트리 각각을 config.toml 의
+ * `[hooks.state."<hooksPath>:<event>:<groupIdx>:<hookIdx>"] trusted_hash` 와 대조한다 (ADR-014 D4).
+ *
+ * ADR-016 D2: 이전엔 *기록 유무* 만 봤다 — 그래서 핸들러가 바뀌어 Codex 가 `modified` 로 skip 하는 훅을
+ * "trusted" 로 오표시했다. 이제 Codex 와 같은 해시를 계산해 trusted / modified / untrusted 를 구분한다.
+ * 읽기 전용 대조이며 trusted_hash 를 쓰지 않는다 — Codex 의 review 정책을 우회하지 않는다.
  */
 export declare function auditCodexHookTrust(opts: {
     hooksPath: string;