polydeukes 0.7.1 → 0.8.0

package/README.ko.md

@@ -17,7 +17,9 @@ CLI 명령은 다음과 같습니다.
 
 - `pdks covenant check`
 - `pdks init`
+- `pdks-claude-code init` (`@polydeukes/adapter-claude-code`가 제공)
 - `pdks-grok init` (`@polydeukes/adapter-grok`가 제공)
+- `pdks-codex init` (`@polydeukes/adapter-codex`가 제공)
 - `pdks explain`
 - `pdks docs [topic]`
 

package/README.md

@@ -18,7 +18,9 @@ CLI commands:
 
 - `pdks covenant check`
 - `pdks init`
+- `pdks-claude-code init` (ships with `@polydeukes/adapter-claude-code`)
 - `pdks-grok init` (ships with `@polydeukes/adapter-grok`)
+- `pdks-codex init` (ships with `@polydeukes/adapter-codex`)
 - `pdks explain`
 - `pdks docs [topic]`
 

package/dist/covenant/discipline.d.ts

@@ -41,6 +41,12 @@ export type CompileDisciplinesSpec = {
     witness?: CovenantRegistration['witness'];
     transcript?: CanonicalTranscript;
 };
+/**
+ * Relativize a file-change path against the root for glob matching. A relative path passes
+ * through; an absolute path outside `rootDir` yields null (never matches — discipline scope
+ * is declared repo-relative).
+ */
+export declare function relativizeForScope(filePath: string, rootDir: string): string | null;
 /** One change as one world, under the repo-relative path the declaration's scope reads. */
 export type SuppliedWorld = {
     readonly path: string;

package/dist/covenant/discipline.js

@@ -18,7 +18,7 @@ import { deriveShellChanges } from './shell-evidence.js';
  * through; an absolute path outside `rootDir` yields null (never matches — discipline scope
  * is declared repo-relative).
  */
-function relativizeForScope(filePath, rootDir) {
+export function relativizeForScope(filePath, rootDir) {
     if (!isAbsolute(filePath)) {
         // A relative spelling normalizes before matching — `./x` and `a/../x` name x, and a
         // spelling that resolves out of the root matches nothing. Matching verbatim instead

package/dist/covenant/dispatch.d.ts

@@ -83,13 +83,16 @@ export type CovenantRegistration = {
  * Match registrations against a {@link CovenantInput} by path mention (pure).
  *
  * A registration matches when any of its `protectedPaths` is an ancestor/descendant/equal of
- * a path candidate extracted from any string value reachable at any depth inside
- * `input.toolCalls[].args`; candidates are quote-aware tokenizer words, so a quote-split
- * write still routes. An unread span with a non-empty `protectedPaths` routes fail-closed
- * (the registration matches on its first protected path) rather than silently miss.
- * `subagentSpawns` and `userMessages` never participate. `mentionedPath` is the first
- * protected path (in array order) that mentions. Result preserves registration order, at most
- * one entry per registration.
+ * a path candidate. Candidates come from two places: every string value reachable at any
+ * depth inside `input.toolCalls[].args`, read as quote-aware tokenizer words so a
+ * quote-split write still routes, and each call's proven `fileChange` path, taken whole
+ * because an adapter already resolved it. A call carrying only the latter is the ordinary
+ * shape where a host names its target in a form the adapter must parse — the patch text of
+ * one edit rather than a path argument. An unread span with a non-empty `protectedPaths`
+ * routes fail-closed (the registration matches on its first protected path) rather than
+ * silently miss. `subagentSpawns` and `userMessages` never participate. `mentionedPath` is
+ * the first protected path (in array order) that mentions. Result preserves registration
+ * order, at most one entry per registration.
  *
  * A registration carrying a `matches` predicate routes on it exclusively, path mention
  * skipped for it: non-null return → included with that string as `mentionedPath`; null →

package/dist/covenant/dispatch.js

@@ -9,7 +9,7 @@
  */
 import { appendRecordFailOpen, EXIT_BREAK_BLOCKING, EXIT_UPHOLD, noopTranscript, parseInput, } from '@polydeukes/core';
 import { tokenizeCommandLine } from './bash-line.js';
-import { pathCandidates, pathMatchesProtected } from './mention.js';
+import { pathCandidates, pathMatchesProtected, provenChangePath } from './mention.js';
 import { runCovenant } from './run-covenant.js';
 /**
  * Collect path candidates from every string value inside `value`. Each string is tokenized
@@ -55,13 +55,16 @@ function collectPathCandidates(value) {
  * Match registrations against a {@link CovenantInput} by path mention (pure).
  *
  * A registration matches when any of its `protectedPaths` is an ancestor/descendant/equal of
- * a path candidate extracted from any string value reachable at any depth inside
- * `input.toolCalls[].args`; candidates are quote-aware tokenizer words, so a quote-split
- * write still routes. An unread span with a non-empty `protectedPaths` routes fail-closed
- * (the registration matches on its first protected path) rather than silently miss.
- * `subagentSpawns` and `userMessages` never participate. `mentionedPath` is the first
- * protected path (in array order) that mentions. Result preserves registration order, at most
- * one entry per registration.
+ * a path candidate. Candidates come from two places: every string value reachable at any
+ * depth inside `input.toolCalls[].args`, read as quote-aware tokenizer words so a
+ * quote-split write still routes, and each call's proven `fileChange` path, taken whole
+ * because an adapter already resolved it. A call carrying only the latter is the ordinary
+ * shape where a host names its target in a form the adapter must parse — the patch text of
+ * one edit rather than a path argument. An unread span with a non-empty `protectedPaths`
+ * routes fail-closed (the registration matches on its first protected path) rather than
+ * silently miss. `subagentSpawns` and `userMessages` never participate. `mentionedPath` is
+ * the first protected path (in array order) that mentions. Result preserves registration
+ * order, at most one entry per registration.
  *
  * A registration carrying a `matches` predicate routes on it exclusively, path mention
  * skipped for it: non-null return → included with that string as `mentionedPath`; null →
@@ -70,6 +73,16 @@ function collectPathCandidates(value) {
  */
 export function matchRegistrations(input, registrations) {
     const { candidates, failed } = collectPathCandidates(input.toolCalls.map((call) => call.args));
+    // A proven change path joins the candidates directly, untokenized: it is a path the
+    // adapter already resolved, not a line to be read for one, and tokenizing it would split
+    // a path containing a space into words that name nothing. Without this a call whose only
+    // evidence is its `fileChange` routes nowhere — the judge bodies read that evidence, so
+    // the input would be refused before the layer that can settle it.
+    for (const call of input.toolCalls) {
+        const proven = provenChangePath(call);
+        if (proven !== null)
+            candidates.push(proven);
+    }
     const matches = [];
     for (const registration of registrations) {
         if (registration.matches !== undefined) {

package/dist/covenant-check.d.ts

@@ -13,7 +13,7 @@
 import { type CanonicalTranscript, type CovenantInput } from '@polydeukes/core';
 import type { CovenantRegistration } from './covenant/dispatch.ts';
 import { type CovenantModule } from './covenant/module.ts';
-import { loadConfig } from './load-config.ts';
+import { type LoadedConfig } from './load-config.ts';
 /** {@link runCovenantCheck} result — the exit code the check process leaves with. */
 export type CovenantCheckOutcome = {
     exitCode: 0 | 2;
@@ -57,7 +57,7 @@ export type CovenantCheckSpec = {
 };
 /** {@link assembleCheckRegistrations} input — what this runner's assembly needs. */
 export type CheckAssemblySpec = {
-    config: ReturnType<typeof loadConfig>['config'];
+    config: LoadedConfig['config'];
     rootDir: string;
     /**
      * The judge module the registrations are built from, so what judges a change and what

package/dist/covenant-check.js

@@ -10,14 +10,16 @@
  * own `world` exits 2 with one blocked record. An input with no toolCalls is an explicit pass
  * with no records.
  */
+import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, isPlainObject, normalizeProtectedPaths, transcriptFromSession, } from '@polydeukes/core';
 import { compareBaseline, updateBaseline } from './baseline.js';
+import { relativizeForScope } from './covenant/discipline.js';
 import { covenantModule } from './covenant/module.js';
 import { ttlWitness } from './covenant/ttl-witness.js';
 import { STAGED_DELETE, STAGED_WRITE } from './diff-ir.js';
-import { loadConfig } from './load-config.js';
+import { discoverConfigPath, parseConfigSource } from './load-config.js';
 import { sessionPreStateReader, unobservedPreStateReader } from './pre-state-reader.js';
 import { worktreeReader } from './worktree-reader.js';
 /**
@@ -115,21 +117,38 @@ export function assembleCheckRegistrations(spec) {
  * `surface: 'changeSet'` and neither IR key.
  */
 export const assembleChangeSetRegistrations = assembleCheckRegistrations;
-/** One stage's failure disposition: the stderr line, the recorded row, and exit 2. */
-function failClosed(telemetryPath, error) {
-    process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
+/** The message a thrown value carries, for a stderr line. */
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * One stage's failure disposition: the stderr line, the recorded row, and exit 2. `suffix`
+ * is appended to the message, for a caller that can name the one call which would clear the
+ * failure.
+ */
+function failClosed(telemetryPath, error, suffix) {
+    process.stderr.write(`covenant check failed closed: ${messageOf(error)}${suffix ?? ''}\n`);
     recordFailClosed(telemetryPath);
     return { exitCode: 2 };
 }
+/** The observation, from the caller's value or from the thunk that produces it. */
+function readInput(spec) {
+    return typeof spec.input === 'function' ? spec.input() : spec.input;
+}
 /**
  * Settle the telemetry path and load the config once, or fail closed. The provisional
  * path is settled before the load so a config that never loads still has somewhere to
  * write its blocked row; both terms use `resolve` so a relative `repoRoot` cannot send
  * them to different files. The provisional term sits inside the try because `resolve`
  * throws on a non-string `repoRoot`.
+ *
+ * The load runs as its three steps rather than through `loadConfig`, so a failure carries
+ * how far it got: which file was discovered, and the bytes that file held.
  */
 function settleConfig(spec) {
     let telemetryPath;
+    let configPath;
+    let source;
     try {
         // The environment variable sits between the caller's path and the config's, matching
         // what the baseline comparison in this same process already resolves — the two write
@@ -138,13 +157,21 @@ function settleConfig(spec) {
         const envPath = process.env.POLYDEUKES_TELEMETRY_PATH;
         telemetryPath =
             spec.telemetryPath ?? envPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
-        const { config } = loadConfig({ rootDir: spec.repoRoot });
+        configPath = discoverConfigPath({ rootDir: spec.repoRoot });
+        source = readFileSync(join(spec.repoRoot, configPath), 'utf-8');
+        const { config } = parseConfigSource({ source, configPath });
         telemetryPath =
             spec.telemetryPath ?? envPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
         return { settled: true, telemetryPath, config };
     }
     catch (error) {
-        return { settled: false, ...failClosed(telemetryPath, error) };
+        return {
+            settled: false,
+            telemetryPath,
+            error,
+            ...(configPath === undefined ? {} : { configPath }),
+            ...(source === undefined ? {} : { source }),
+        };
     }
 }
 /**
@@ -312,6 +339,83 @@ function assertJudgeableShape(input) {
         throw new Error('input carries a session.channels.sidecar that is not text');
     }
 }
+/**
+ * The disposition of a run whose config never loaded.
+ *
+ * While the one discovered file does not load there is no assembly to judge against, so the
+ * session surface admits exactly one shape: a single tool call whose file-change evidence
+ * modifies that file, starting from the bytes the loader read, and whose `post` is a text the
+ * loader accepts. That call is judged — its result loads — and lands as one `advised` row
+ * naming the config path, so the next call's baseline comparison reads the change as
+ * explained. Everything else fails closed, and where a single file was discovered the line
+ * says which call would repair it.
+ *
+ * This branch reads no posture: the session hook always spawns with `--enforce block`, so a
+ * repair that blocked under that posture would never run anywhere.
+ */
+function settleLoadFailure(spec, failure) {
+    const { telemetryPath, error, configPath } = failure;
+    if (configPath === undefined || spec.surface !== 'session') {
+        return failClosed(telemetryPath, error);
+    }
+    let input;
+    try {
+        input = readInput(spec);
+    }
+    catch (inputError) {
+        return failClosed(telemetryPath, inputError);
+    }
+    const loaded = repairs(input, failure, spec.repoRoot);
+    if (loaded !== null) {
+        // The repaired config's own log path, under the precedence `settleConfig` uses, so the
+        // next call's baseline comparison reads this row where it looks for it.
+        const rowPath = spec.telemetryPath ??
+            process.env.POLYDEUKES_TELEMETRY_PATH ??
+            resolve(spec.repoRoot, loaded.config.telemetry.logPath);
+        appendRecordFailOpen(rowPath, {
+            event: 'advised',
+            label: 'covenant-check',
+            subject: configPath,
+        });
+        process.stderr.write(`covenant check: ${configPath} does not load (${messageOf(error)}) — this call rewrites it into one that does; advised, not judged\n`);
+        return { exitCode: 0 };
+    }
+    return failClosed(telemetryPath, error, ` — fix ${configPath} in one Edit or Write whose result loads; every other call stays blocked until it does`);
+}
+/**
+ * The loaded config a single call would leave behind, or null when this observation is not
+ * that call: exactly one call carrying a plain object, its evidence a modification of the
+ * discovered config file (relativized against the root, since a host names its paths
+ * absolutely), starting from the bytes the loader read, and leaving a `post` the loader
+ * accepts. Requiring the pre to be those bytes keeps a partial view of the file — one
+ * notebook cell, or evidence a caller composed — out of the branch.
+ */
+function repairs(input, failure, repoRoot) {
+    const { configPath, source } = failure;
+    if (configPath === undefined || source === undefined)
+        return null;
+    if (!Array.isArray(input.toolCalls) || input.toolCalls.length !== 1)
+        return null;
+    const call = input.toolCalls[0];
+    if (!isPlainObject(call))
+        return null;
+    const { fileChange } = call;
+    if (fileChange === undefined || fileChange.kind !== 'modify')
+        return null;
+    if (relativizeForScope(fileChange.path, repoRoot) !== configPath)
+        return null;
+    if (fileChange.pre !== source)
+        return null;
+    const post = fileChange.post;
+    if (typeof post !== 'string')
+        return null;
+    try {
+        return parseConfigSource({ source: post, configPath });
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Judge one observation of `repoRoot` exactly as the session surface would, from the IR the
  * caller hands in. Async because the dispatcher spawns covenant bodies. An input with no
@@ -326,11 +430,11 @@ function assertJudgeableShape(input) {
 export async function runCovenantCheck(spec) {
     const settlement = settleConfig(spec);
     if (!settlement.settled)
-        return { exitCode: settlement.exitCode };
+        return settleLoadFailure(spec, settlement);
     const { telemetryPath, config } = settlement;
     let input;
     try {
-        input = typeof spec.input === 'function' ? spec.input() : spec.input;
+        input = readInput(spec);
         // The world axis is this root's to fill. An input that supplies its own would let a
         // caller choose the files the judge reads.
         if ('world' in input) {

package/dist/docs/README.ko.md

@@ -10,7 +10,7 @@
 | 하려는 것 | 읽을 문서 |
 |---|---|
 | 첫 눈에 보이는 판정을 보고 싶다 | [첫 판정](./tutorials/first-judgment.ko.md) — 설치하고 Claude Code를 배선한 뒤 보호된 편집이 판정되는 모습을 봅니다 |
-| Claude Code, Grok, git을 연결하고 싶다 | [표면 연결하기](./how-to/connect-surfaces.ko.md) — 세션과 커밋 배선, Grok 포함 |
+| Claude Code, Grok, Codex, git을 연결하고 싶다 | [표면 연결하기](./how-to/connect-surfaces.ko.md) — 세션과 커밋 배선, Grok와 Codex 포함 |
 | 프로젝트 설정을 다듬고 싶다 | [프로젝트 설정하기](./how-to/configure-project.ko.md) — 발견, IDE 지원, advise와 block의 선택 |
 | 실제 규율을 쓰고 싶다 | [규율 작성하기](./how-to/write-disciplines.ko.md) — 실전 선언 예제, 특히 locale key pairing |
 | 차단이나 건너뜀에서 회복하고 싶다 | [문제 해결](./troubleshooting.ko.md) — fail-closed 상태, 증인 밸브, 로그 |
@@ -29,6 +29,7 @@
 | [`@polydeukes/core`](./reference/packages/core.ko.md) | 프로토콜, 입력 IR, 설정 스키마, 텔레메트리 |
 | [`@polydeukes/adapter-claude-code`](./reference/packages/adapter-claude-code.ko.md) | Claude Code 세션 표면입니다. 훅 페이로드에서 입력 IR로 |
 | [`@polydeukes/adapter-grok`](./reference/packages/adapter-grok.ko.md) | Grok 세션 표면입니다. 훅 페이로드에서 입력 IR로 |
+| [`@polydeukes/adapter-codex`](./reference/packages/adapter-codex.ko.md) | Codex 세션 표면입니다. 훅 페이로드에서 입력 IR로, 패치가 건드리는 파일마다 원소 하나 |
 
 <a id="shape-of-the-thing"></a>
 ## 한 페이지로 보는 구조
@@ -52,7 +53,7 @@
 
 | 표면 | 판정 대상 | 배선 방법 | 대상 |
 |---|---|---|---|
-| **세션** | 도구 호출, 실행되기 전에 | `pdks-claude-code init` 또는 `pdks-grok init` | AI 파트너와 함께 개발하는 프로젝트 |
+| **세션** | 도구 호출, 실행되기 전에 | `pdks-claude-code init`, `pdks-grok init`, 또는 `pdks-codex init` | AI 파트너와 함께 개발하는 프로젝트 |
 | **커밋** | stdin의 unified diff — 스테이징 영역, 작업 트리, ref 범위 | `git diff --cached`를 파이프로 넘기는 pre-commit 훅, 또는 필요할 때 직접 실행 | 혼자 개발하는 사람, 그리고 CI |
 
 커밋 판정기는 필요할 때 직접 실행할 수도 있습니다. 작업 후에는 `git diff HEAD | pdks covenant check --diff`,

package/dist/docs/README.md

@@ -11,7 +11,7 @@ question is.
 | If you want to | Read |
 |---|---|
 | Get to a first visible judgment | [First judgment](./tutorials/first-judgment.md) — install, wire Claude Code, and watch one protected edit get judged |
-| Connect Claude Code, Grok, or git | [Connect the surfaces](./how-to/connect-surfaces.md) — session and commit setup, including Grok |
+| Connect Claude Code, Grok, Codex, or git | [Connect the surfaces](./how-to/connect-surfaces.md) — session and commit setup, including Grok and Codex |
 | Shape the project config | [Configure the project](./how-to/configure-project.md) — discovery, IDE support, and advise versus block |
 | Write a real discipline | [Write disciplines](./how-to/write-disciplines.md) — worked declarations, especially locale key pairing |
 | Recover from a block or skip | [Troubleshooting](./troubleshooting.md) — the fail-closed states, the witness valve, and the log |
@@ -31,6 +31,7 @@ is aspirational.
 | [`@polydeukes/core`](./reference/packages/core.md) | The protocol, the input IR, the config schema, telemetry |
 | [`@polydeukes/adapter-claude-code`](./reference/packages/adapter-claude-code.md) | Claude Code session surface — hook payloads become the input IR |
 | [`@polydeukes/adapter-grok`](./reference/packages/adapter-grok.md) | Grok session surface — hook payloads become the input IR |
+| [`@polydeukes/adapter-codex`](./reference/packages/adapter-codex.md) | Codex session surface — hook payloads become the input IR, one element per file the patch touches |
 
 <a id="shape-of-the-thing"></a>
 ## The shape of the thing, in one page
@@ -56,7 +57,7 @@ in the whitepaper, which were all found by counting rows rather than by reading
 
 | Surface | Judges | Wired by | For |
 |---|---|---|---|
-| **Session** | A tool call, before it runs | `pdks-claude-code init` or `pdks-grok init` | A project developed with an AI partner |
+| **Session** | A tool call, before it runs | `pdks-claude-code init`, `pdks-grok init`, or `pdks-codex init` | A project developed with an AI partner |
 | **Commit** | A unified diff on stdin — staged, the working tree, or a ref range | A pre-commit hook piping `git diff --cached`, or run on demand | A human developing alone, and CI |
 
 The commit judge also answers on demand: `git diff HEAD | pdks covenant check --diff` after a task,

package/dist/docs/catalog.json

@@ -266,6 +266,22 @@
         "summary": "Grok 세션 표면을 설치하고, 어댑터 패키지의 계약과 한계를 확인합니다."
       }
     },
+    {
+      "id": "package-adapter-codex",
+      "category": "reference",
+      "order": 17,
+      "bundled": true,
+      "en": {
+        "path": "reference/packages/adapter-codex.md",
+        "title": "`@polydeukes/adapter-codex`",
+        "summary": "Install the Codex session surface, and consult how patch text becomes file-change evidence."
+      },
+      "ko": {
+        "path": "reference/packages/adapter-codex.ko.md",
+        "title": "`@polydeukes/adapter-codex`",
+        "summary": "Codex 세션 표면을 설치하고, 패치 텍스트가 파일 변경 증거가 되는 방식을 확인합니다."
+      }
+    },
     {
       "id": "package-sdk-ts",
       "category": "reference",
@@ -425,6 +441,22 @@
         "title": "<!--",
         "summary": "당시의 개발 기록이며 현재 사용법을 설명하는 참조 문서는 아닙니다."
       }
+    },
+    {
+      "id": "post-8",
+      "category": "history",
+      "order": 25,
+      "bundled": false,
+      "en": {
+        "path": "build-in-public/2026-09-v0.7-entrypoint-reshape.md",
+        "title": "<!--",
+        "summary": "Historical development account; not a current usage reference."
+      },
+      "ko": {
+        "path": "build-in-public/2026-09-v0.7-entrypoint-reshape.ko.md",
+        "title": "<!--",
+        "summary": "당시의 개발 기록이며 현재 사용법을 설명하는 참조 문서는 아닙니다."
+      }
     }
   ],
   "topics": {

package/dist/docs/how-to/connect-surfaces.ko.md

@@ -2,7 +2,7 @@
 
 [English](../how-to/connect-surfaces.md) · **한국어**
 
-> 작업에 맞는 표면을 고릅니다. Claude Code와 Grok는 세션 표면을 배선하고, git은 변경 집합 표면을 배선합니다.
+> 작업에 맞는 표면을 고릅니다. Claude Code와 Grok, Codex는 세션 표면을 배선하고, git은 변경 집합 표면을 배선합니다.
 
 두 표면은 같은 설정 어휘를 쓰지만 판정 시점이 다릅니다. AI 파트너가 편집할 때는 세션 표면을,
 변경을 이력으로 기록하기 전에는 변경 집합 표면을 사용합니다.
@@ -12,8 +12,8 @@
 
 Claude Code에서 AI 파트너와 함께 개발할 때 씁니다.
 
-1. 두 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes
-   @polydeukes/adapter-claude-code`. 일회성 `npx` 실행만으로는 부족합니다. 두 표면 모두
+1. 세 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes
+   @polydeukes/core @polydeukes/adapter-claude-code`. 일회성 `npx` 실행만으로는 부족합니다. 두 표면 모두
    프로젝트에 설치된 패키지에서 판정기를 불러옵니다.
 2. 프로젝트 루트에서 배선합니다. `pnpm exec pdks-claude-code init`. 이 실행 파일은 어댑터가
    제공하며, 먼저 `pdks init`으로 초기 파일을 만든 뒤 Claude Code 등록 산출물을 씁니다.
@@ -31,14 +31,14 @@ Claude Code에서 AI 파트너와 함께 개발할 때 씁니다.
 
 Grok에서 개발할 때 씁니다.
 
-1. 두 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes @polydeukes/adapter-grok`.
+1. 세 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-grok`.
 2. 프로젝트 루트에서 배선합니다. `pnpm exec pdks-grok init`. 어댑터가 이 실행 파일을
    제공합니다. 먼저 `pdks init`으로 초기 파일을 만든 뒤 Grok 등록 산출물을 씁니다.
 3. 설치가 끝나면 Hooks 탭을 다시 불러오거나 새 세션을 엽니다.
 
 Grok 프로젝트에는 `.grok/hooks/` 아래에 훅 JSON과 위임자가 생깁니다. 새 등록의 제한 시간은
 60초입니다. Grok 호스트의 기본값은 5초이며, 훅 실행이 시간 초과로 끝나면 해당 호출을
-차단하지 않습니다(fail-open). 두 세션 어댑터를 한 프로젝트에 함께 설치하면 호출마다
+차단하지 않습니다(fail-open). 세션 어댑터를 한 프로젝트에 둘 이상 설치하면 호출마다
 판정기가 두 번 실행될 수 있습니다.
 
 Grok는 세션 증인(witness) 밸브에 필요한 Claude 형식의 인간 메시지를 공급하지 않습니다. 대화
@@ -46,6 +46,34 @@ Grok는 세션 증인(witness) 밸브에 필요한 Claude 형식의 인간 메
 의도한 편집이 차단되면 자신의 터미널에서 수행하세요. 변경 집합 표면에는 증인 프롬프트가 없으므로
 차단된 Grok 도구 호출을 커밋 쪽에서 허용할 방법도 없습니다.
 
+<a id="codex"></a>
+## Codex 세션 표면
+
+Codex에서 개발할 때 씁니다.
+
+1. 세 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-codex`.
+2. 프로젝트 루트에서 배선합니다. `pnpm exec pdks-codex init`. 어댑터가 이 실행 파일을
+   제공합니다. 먼저 `pdks init`으로 초기 파일을 만든 뒤 Codex 등록 산출물을 씁니다.
+3. Codex에서 `/hooks`로 생성된 훅을 승인합니다. 승인하기 전까지는 훅을 건너뜁니다.
+
+Codex 프로젝트에는 `.codex/hooks/covenant-pretooluse.mjs` 위임자와 `.codex/hooks.json`의 항목이
+생깁니다. 이 JSON은 덮어쓰지 않고 병합합니다. 다른 이벤트, 다른 matcher, 설치기가 모르는 키는
+그대로 둡니다. 초기 설정은 기본적으로 `.codex/hooks`를 보호합니다.
+
+**승인은 선택이 아닙니다.** Codex는 훅 정의의 해시로 신뢰를 기록하므로, 새로 쓴 훅은 검토
+대상으로 표시되고 누군가 승인하기 전까지 건너뛰어집니다. 그때까지는 아무것도 판정되지
+않습니다. `init`은 실행할 때마다 바이트가 같은 명령 문자열을 쓰므로, 다시 설치해도 이미 받은
+승인이 무효가 되지 않습니다.
+
+Codex는 모든 파일 편집을 `apply_patch` 하나로 정규화하고, 경로 인자가 아니라 패치 텍스트를
+보냅니다. `Edit`과 `Write`는 훅 파일에 적을 수 있는 matcher 별칭이며 도구 이름으로 도착하지
+않습니다. 패치 하나가 여러 파일을 건드리면 파일마다 IR 원소 하나가 실리고, 그중 하나라도
+차단되면 호출 전체가 차단됩니다.
+
+Codex에는 대화 기록 채널이 없어서 세션 증인(witness) 밸브가 읽을 사람 메시지가 없습니다.
+의도한 편집이 차단되면 자신의 터미널에서 수행하세요. 세션 어댑터를 한 프로젝트에 둘 이상
+설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.
+
 <a id="change-set-surface"></a>
 ## 변경 집합 표면
 

package/dist/docs/how-to/connect-surfaces.md

@@ -2,8 +2,8 @@
 
 **English** · [한국어](../how-to/connect-surfaces.ko.md)
 
-> Pick the surface that matches the job. Claude Code and Grok wire the session surface; git wires
-the change-set surface.
+> Pick the surface that matches the job. Claude Code, Grok, and Codex wire the session surface;
+git wires the change-set surface.
 
 The two surfaces share the same config vocabulary, but they answer different moments. Use the
 session surface when an AI partner is making edits, and use the change-set surface when history
@@ -14,9 +14,9 @@ is about to be written.
 
 Use this when the project is developed alongside an AI partner in Claude Code.
 
-1. Install both packages as project dependencies: `pnpm add -D polydeukes
-   @polydeukes/adapter-claude-code`. A one-off `npx` run is not enough — both surfaces load the
-   judge from the project's own installed package.
+1. Install the three packages as project dependencies: `pnpm add -D polydeukes
+   @polydeukes/core @polydeukes/adapter-claude-code`. A one-off `npx` run is not enough —
+   both surfaces load the judge from the project's own installed package.
 2. Wire the project from its root: `pnpm exec pdks-claude-code init`. The adapter ships this bin;
    it runs `pdks init` for the scaffold, then writes the Claude Code registration artifacts.
 3. Keep the generated hook file, settings merge, starter config, discovery rule, and
@@ -34,20 +34,50 @@ described problem into either a judged entry or a draft entry.
 
 Use this when the project is developed in Grok.
 
-1. Install both packages as project dependencies: `pnpm add -D polydeukes @polydeukes/adapter-grok`.
+1. Install the three packages as project dependencies: `pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-grok`.
 2. Wire the project from its root: `pnpm exec pdks-grok init`. The adapter ships this bin; it
    runs `pdks init` for the scaffold, then writes the Grok registration artifacts.
 3. Reload the Hooks tab or open a new session after the installer finishes.
 
 A Grok tree gets its own hook JSON and delegator under `.grok/hooks/`. Generated registrations
 use a timeout of 60 seconds. The Grok host default is 5 seconds, and a timed-out hook fails
-open. Installing both session adapters in one project can run the judge twice per call.
+open. Installing more than one session adapter in one project can run the judge twice per call.
 
 Grok does not supply the Claude-format human message needed by the session witness valve. The
 session log is ACP `updates.jsonl`, not Claude's JSONL.
 For an intentional blocked edit, use your own terminal. The change-set surface has no prompt, so
 there is no way to authorize a blocked Grok tool call from that side either.
 
+<a id="codex"></a>
+## Codex session surface
+
+Use this when the project is developed in Codex.
+
+1. Install the three packages as project dependencies: `pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-codex`.
+2. Wire the project from its root: `pnpm exec pdks-codex init`. The adapter ships this bin; it
+   runs `pdks init` for the scaffold, then writes the Codex registration artifacts.
+3. Approve the generated hook with `/hooks` in Codex. Until you do, it is skipped.
+
+A Codex tree gets a delegator at `.codex/hooks/covenant-pretooluse.mjs` and an entry in
+`.codex/hooks.json`. That JSON is merged, not overwritten: other events, other matchers, and
+keys the installer does not know stay where they are. The scaffold config protects
+`.codex/hooks` by default.
+
+**Approval is not optional.** Codex records trust against the hash of a hook's definition, so a
+newly written hook is listed for review and skipped until someone approves it — until then
+nothing is judged. `init` writes a byte-identical command string on every run, so a re-install
+does not invalidate an approval you already gave.
+
+Codex normalises every file edit into one tool, `apply_patch`, and sends the patch text rather
+than a path argument. `Edit` and `Write` are matcher aliases you may write in the hooks file;
+they never arrive as the tool name. One patch that touches several files carries one IR element
+per file, and any one of them blocking blocks the whole call.
+
+Codex supplies no transcript channel, so the session witness valve has no human message to read.
+For an intentional blocked edit, use your own terminal. Installing more than one session adapter
+in one project can run the judge twice per call.
+
+
 <a id="change-set-surface"></a>
 ## Change-set surface
 

package/dist/docs/how-to/write-disciplines.ko.md

@@ -11,7 +11,9 @@
 
 두 JSON 번역 파일의 키 집합을 비교합니다. 중첩된 키도 비교 대상입니다.
 아래 전체 YAML을 **예제 프로젝트**의 `polydeukes.config.yaml`로 저장합니다. 기존 프로젝트의
-설정을 덮어쓰지 마세요. 기존 설정에 추가할 때는 규율 항목만 복사합니다.
+설정을 덮어쓰지 마세요. 기존 설정에 추가할 때는 규율 항목만 복사합니다. 아래 YAML에는
+`protectedPaths`와 `witness` 블록이 없으므로, 생성된 설정 위에 그대로 저장하면 증인 밸브가
+사라집니다.
 설치 절차는 [첫 판정 튜토리얼](../tutorials/first-judgment.ko.md)에 있습니다.
 
 ```yaml

package/dist/docs/how-to/write-disciplines.md

@@ -11,7 +11,9 @@ at `advise` until you decide that the observed results justify blocking.
 
 This declaration compares the key sets of two JSON translation files, including nested keys.
 Save the complete YAML below as `polydeukes.config.yaml` in an **example project**, not over an
-existing project's configuration. In an existing project, copy only the discipline entry.
+existing project's configuration. In an existing project, copy only the discipline entry — the
+YAML below carries no `protectedPaths` and no `witness` block, so saving it over a generated
+config removes the witness valve.
 The [first-judgment tutorial](../tutorials/first-judgment.md) supplies installation steps.
 
 ```yaml