polydeukes 0.7.1 → 0.9.0

package/dist/docs/reference/cli/explain.ko.md

@@ -49,21 +49,21 @@ pdks explain
 ```
 
 출력은 설정 파일 경로로 시작하고, 그다음 세션 표면 블록 하나와 변경 집합 표면 블록 하나가 나옵니다.
-추가 규율이 없는 시작 설정은 이런 모양입니다.
+추가 규율이 없는 시작 설정은 이런 모양입니다(`N`은 조립이 센 보호 경로 개수이고, `skip` 행 하나는 정상입니다. 쓰기 대상을 판정할 수 없는 셸 명령이 착지하는 자리입니다).
 
 ```text
 pdks explain — polydeukes.config.yaml
 
 input: call IR (one call, stdin) · disciplines 0 · sessionDisciplines 0 · disciplines: advise unless enforce: block · meta: block
-  registrations 3 · declare 0 · skip 0 · meta 3 · draft 0
-  meta     self-mod        paths N (common; includes the config file itself)
-  meta     shell-mod       paths N (common)
-  meta     transcript-mod  content predicate · conditional: session.evidencePath
+  registrations 3 · declare 0 · skip 1 · meta 2 · draft 0
+  meta     self-mod          paths N (common; includes the config file itself)
+  meta     transcript-mod    content predicate · conditional: session.evidencePath
+  skip     shell-unjudgeable a shell command whose write target this layer cannot determine
 
 input: --diff (change set, stdin) · disciplines 0 · changeSetDisciplines 0 · disciplines: advise unless enforce: block
-  registrations 2 · declare 0 · skip 0 · meta 2 · draft 0
-  meta     self-mod   paths N (common; includes the config file itself)
-  meta     shell-mod  paths N (common)
+  registrations 2 · declare 0 · skip 1 · meta 1 · draft 0
+  meta     self-mod          paths N (common; includes the config file itself)
+  skip     shell-unjudgeable a shell command whose write target this layer cannot determine
 ```
 
 **표면 머리줄은 그 표면이 컴파일하는 목록의 이름과 각 목록의 항목 수를 적습니다.** 세션

package/dist/docs/reference/cli/explain.md

@@ -53,21 +53,23 @@ pdks explain
 ```
 
 The output starts with the config file path, then one block for the session surface and one for the
-change-set surface. A starter config with no extra disciplines looks like this:
+change-set surface. A starter config with no extra disciplines looks like this (`N` stands for
+the number of protected paths the assembly counted; the one `skip` row is normal — it is where a
+shell command whose write target cannot be determined lands):
 
 ```text
 pdks explain — polydeukes.config.yaml
 
 input: call IR (one call, stdin) · disciplines 0 · sessionDisciplines 0 · disciplines: advise unless enforce: block · meta: block
-  registrations 3 · declare 0 · skip 0 · meta 3 · draft 0
-  meta     self-mod        paths N (common; includes the config file itself)
-  meta     shell-mod       paths N (common)
-  meta     transcript-mod  content predicate · conditional: session.evidencePath
+  registrations 3 · declare 0 · skip 1 · meta 2 · draft 0
+  meta     self-mod          paths N (common; includes the config file itself)
+  meta     transcript-mod    content predicate · conditional: session.evidencePath
+  skip     shell-unjudgeable a shell command whose write target this layer cannot determine
 
 input: --diff (change set, stdin) · disciplines 0 · changeSetDisciplines 0 · disciplines: advise unless enforce: block
-  registrations 2 · declare 0 · skip 0 · meta 2 · draft 0
-  meta     self-mod   paths N (common; includes the config file itself)
-  meta     shell-mod  paths N (common)
+  registrations 2 · declare 0 · skip 1 · meta 1 · draft 0
+  meta     self-mod          paths N (common; includes the config file itself)
+  skip     shell-unjudgeable a shell command whose write target this layer cannot determine
 ```
 
 **The surface header names the lists that surface compiles and how many entries each holds.**

package/dist/docs/reference/cli/init.ko.md

@@ -4,7 +4,8 @@
 
 `pdks init`은 에이전트와 무관한 초기 파일을 만듭니다. 설정 파일과 텔레메트리 제외 항목
 둘입니다. 이 명령은 어느 에이전트도 알지 못합니다. 세션 표면 등록은 그 에이전트의 어댑터가
-맡는 별도 명령입니다. Claude Code는 `pdks-claude-code init`, Grok는 `pdks-grok init`입니다.
+맡는 별도 명령입니다. Claude Code는 `pdks-claude-code init`, Grok는 `pdks-grok init`,
+Codex는 `pdks-codex init`입니다.
 
 <a id="init-syntax"></a>
 ## 구문
@@ -40,7 +41,7 @@ Claude Code 세션 표면은
 어댑터에는 자체 실행 파일이 있습니다.
 
 ```sh
-npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-claude-code
 npx pdks-claude-code init
 ```
 
@@ -61,7 +62,7 @@ Grok 세션 표면은
 어댑터에는 자체 실행 파일이 있습니다.
 
 ```sh
-npm install --save-dev polydeukes @polydeukes/adapter-grok
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-grok
 npx pdks-grok init
 ```
 
@@ -72,13 +73,51 @@ npx pdks-grok init
 
 `.claude/` 파일을 만들거나 고치지 않습니다. 새 등록의 제한 시간은 60초입니다. Grok 호스트
 기본값은 5초이며, 훅 실행이 시간 초과로 끝나면 해당 호출을 차단하지 않습니다(fail-open).
-두 세션 어댑터를 한 프로젝트에 함께 설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.
+세션 어댑터를 한 프로젝트에 둘 이상 설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.
 
 Grok는 Claude 세션 증인(witness) 밸브가 요구하는 인간 메시지 증거를 제공하지 않습니다.
 대화 기록은 Claude JSONL이 아니라 ACP `updates.jsonl`입니다.
 [Grok 복구 안내](../../troubleshooting.ko.md#grok-witness)를 참고하세요. 산출물별 동작은
 [표면 연결하기](../../how-to/connect-surfaces.ko.md#grok)에 있습니다.
 
+<a id="init-codex"></a>
+## Codex — `pdks-codex init`
+
+Codex 세션 표면은
+[`@polydeukes/adapter-codex`](../packages/adapter-codex.ko.md)가 설치합니다. 이
+어댑터에는 자체 실행 파일이 있습니다.
+
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-codex
+npx pdks-codex init
+```
+
+이 명령은 먼저 `pdks init`으로 초기 파일을 만든 뒤 Codex 등록 산출물을 씁니다.
+
+- `.codex/hooks/covenant-pretooluse.mjs`
+- `.codex/hooks.json`
+
+`hooks.json`에는 `PreToolUse`, `UserPromptSubmit`, `PostToolUse`, `SessionEnd` 항목이
+생깁니다. 파일은 덮어쓰지 않고 병합합니다. 사용자 항목, 같은 항목의 다른 handler, 다른
+이벤트, 설치기가 모르는 키는 그대로 둡니다. 초기 설정은 기본적으로 `.codex/hooks`를
+보호하므로, 이 설치기가 만드는 등록 파일은 같은 설치가 만든 설정이 지킵니다.
+
+**훅 승인까지가 설치입니다.** Codex는 훅 정의의 해시로 신뢰를 기록하므로, 생성된 훅은 검토
+대상으로 표시되고 `/hooks`에서 승인하기 전까지 건너뛰어집니다. 누군가 승인하기 전까지는
+아무것도 판정되지 않습니다. `init`이 실행할 때마다 바이트가 같은 명령 문자열을 쓰는 이유가
+이것입니다. 문자열이 바뀌면 다시 승인해야 합니다.
+
+Codex는 훅에 도달하는 모든 파일 편집을 `apply_patch` 하나로 정규화하고, 경로 인자가 아니라 패치 텍스트를
+보냅니다. `Edit`과 `Write`는 `.codex/hooks.json`에 적을 수 있는 matcher 별칭이며 도구 이름으로
+도착하지 않습니다. 패치 하나가 여러 파일을 건드리면 파일마다 IR 원소 하나가 실리고, 그중
+하나라도 차단되면 호출 전체가 차단됩니다.
+
+불안정한 Codex 대화 기록은 해석하지 않습니다. `UserPromptSubmit`은 시각을 붙인 사람
+메시지를, `PostToolUse`는 완료된 도구 호출을 공급하고, `SessionEnd`는 어댑터 소유 증거
+파일을 정리합니다. 따라서 설정된 증인 토큰으로 다시 시도한 보호 호출을 허용할 수 있습니다.
+프롬프트 증거가 기록되지 않았다면 복구 메시지가 안내하는 사용자 터미널을 사용합니다.
+산출물별 동작은 [표면 연결하기](../../how-to/connect-surfaces.ko.md#codex)에 있습니다.
+
 <a id="init-results"></a>
 ## 결과와 실패 조건
 
@@ -103,6 +142,7 @@ Grok는 Claude 세션 증인(witness) 밸브가 요구하는 인간 메시지
 pdks init
 npx pdks-claude-code init
 npx pdks-grok init
+npx pdks-codex init
 ```
 
 설치기는 CLI 명령입니다. `polydeukes` 계약의 공개 심볼이 아닙니다.
@@ -113,6 +153,8 @@ npx pdks-grok init
 - [`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.ko.md) — Claude Code 설치
 단위와 그 실행 파일
 - [`@polydeukes/adapter-grok`](../packages/adapter-grok.ko.md) — Grok 설치 단위와 그 실행 파일
+- [`@polydeukes/adapter-codex`](../packages/adapter-codex.ko.md) — Codex 설치 단위와 그 실행
+파일
 - [`pdks docs`](./docs.ko.md)
 - [`pdks explain`](./explain.ko.md)
 - [설정 참조](../configuration/index.ko.md)

package/dist/docs/reference/cli/init.md

@@ -4,7 +4,8 @@
 
 `pdks init` creates the agent-neutral project scaffold: the config file and the telemetry ignore
 line. It knows no agent. Registering a session surface is a separate command owned by that
-agent's adapter — `pdks-claude-code init` for Claude Code, and `pdks-grok init` for Grok.
+agent's adapter — `pdks-claude-code init` for Claude Code, `pdks-grok init` for Grok, and
+`pdks-codex init` for Codex.
 
 <a id="init-syntax"></a>
 ## Syntax
@@ -39,7 +40,7 @@ The Claude Code session surface is installed by
 [`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.md), which ships its own bin:
 
 ```sh
-npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-claude-code
 npx pdks-claude-code init
 ```
 
@@ -61,7 +62,7 @@ The Grok session surface is installed by
 [`@polydeukes/adapter-grok`](../packages/adapter-grok.md), which ships its own bin:
 
 ```sh
-npm install --save-dev polydeukes @polydeukes/adapter-grok
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-grok
 npx pdks-grok init
 ```
 
@@ -71,14 +72,53 @@ That command runs `pdks init` for the scaffold, then writes the Grok registratio
 - `.grok/hooks/covenant-pretooluse.json`
 
 It does not create or rewrite `.claude/` files. 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.
+seconds. The Grok host default is 5 seconds, and a timed-out hook fails open. Installing more
+than one session adapter in one project can run the judge twice per call.
 
 Grok does not supply the human-message evidence required by the Claude session witness valve.
 The session log is ACP `updates.jsonl`, not Claude's JSONL.
 See [Grok recovery](../../troubleshooting.md#grok-witness). Details are in
 [Connect the surfaces](../../how-to/connect-surfaces.md#grok).
 
+<a id="init-codex"></a>
+## Codex — `pdks-codex init`
+
+The Codex session surface is installed by
+[`@polydeukes/adapter-codex`](../packages/adapter-codex.md), which ships its own bin:
+
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-codex
+npx pdks-codex init
+```
+
+That command runs `pdks init` for the scaffold, then writes the Codex registration artifacts:
+
+- `.codex/hooks/covenant-pretooluse.mjs`
+- `.codex/hooks.json`
+
+`hooks.json` receives entries for `PreToolUse`, `UserPromptSubmit`, `PostToolUse`, and
+`SessionEnd`. It is merged rather than overwritten: user entries, sibling handlers, other
+events, and keys the installer does not know are left in place. The scaffold config protects
+`.codex/hooks` by default, so the registration this installer writes is covered by the config
+it writes.
+
+**Approving the hook is part of the install.** Codex records trust against the hash of a hook's
+definition, so the generated hook is listed for review and skipped until you approve it with
+`/hooks`. Until someone does, nothing is judged. This is why `init` writes a byte-identical
+command string on every run — a changed string needs approving again.
+
+Codex normalises every file edit that reaches the hook into one tool, `apply_patch`, and
+delivers the patch text rather than a path argument. `Edit` and `Write` are matcher aliases
+you may write in `.codex/hooks.json`; 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.
+
+The unstable Codex transcript is never parsed. `UserPromptSubmit` supplies timestamped human
+messages, `PostToolUse` supplies completed tool calls, and `SessionEnd` cleans up the
+adapter-owned evidence file. A configured witness token can therefore release a retried
+protected call. If no prompt evidence was recorded, use the user terminal named by the recovery
+message. Details are in [Connect the surfaces](../../how-to/connect-surfaces.md#codex).
+
 <a id="init-results"></a>
 ## Results and failure conditions
 
@@ -102,6 +142,7 @@ filesystem problem, and rerun rather than assuming every failed installation lef
 pdks init
 npx pdks-claude-code init
 npx pdks-grok init
+npx pdks-codex init
 ```
 
 The installers are CLI commands. They are not symbols on the `polydeukes` contract.
@@ -112,6 +153,8 @@ The installers are CLI commands. They are not symbols on the `polydeukes` contra
 - [`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.md) — the Claude Code
 install unit and its bin.
 - [`@polydeukes/adapter-grok`](../packages/adapter-grok.md) — the Grok install unit and its bin.
+- [`@polydeukes/adapter-codex`](../packages/adapter-codex.md) — the Codex install unit and its
+bin.
 - [`pdks docs`](../packages/polydeukes.md#polydeukes-bin) — the installed documentation reader lives
 in the same package.
 - [`pdks explain`](./explain.md)

package/dist/docs/reference/configuration/index.ko.md

@@ -103,7 +103,7 @@ fail-open입니다. 기록 실패가 판정을 바꾸는 일은 없습니다.
 
 ```yaml
 witness:
-  token: 'covenant witness'   # 사람이 대화에 직접 입력하는 합의 문구
+  token: 'pdks witness'   # 사람이 대화에 직접 입력하는 합의 문구
   ttlMinutes: 10              # 그 메시지 시점부터의 유효 시간(분)
 ```
 
@@ -128,7 +128,7 @@ witness:
 발동하는 메시지입니다. 첫 줄에 토큰만 두고 나머지 줄은 자유롭게 씁니다.
 
 ```text
-covenant witness
+pdks witness
 
 이제 훅 파일을 고쳐줘
 ```
@@ -136,7 +136,7 @@ covenant witness
 언급일 뿐인 메시지입니다. 밸브는 닫힌 채입니다.
 
 ```text
-그런데 `covenant witness` 는 언제 만료되나요?
+그런데 `pdks witness` 는 언제 만료되나요?
 ```
 
 토큰 값 자체는 자유입니다. 어떤 문구든 쓸 수 있고, 접두사나 명령 형태를 검사하지 않습니다.
@@ -338,7 +338,11 @@ stderr에 쓰입니다. `block`을 지정하면 항목의 강제 수준을 차
 그 차이가 비어 있는지 판정합니다. 기존 일치 항목은 위반으로 세지 않으므로 선언을 도입해도
 기존 코드 전체를 차단하지 않습니다. `supply: empty`를 지정하면 파일 생성(`pre` 없음)은
 전체 내용을 추가한 것으로, 삭제(`post` 없음)는 아무것도 추가하지 않은 것으로 처리합니다.
-`scope` 블록에서는 `in`/`except` 대신 경로에 적용할 정규식을 사용합니다.
+`scope` 블록에서는 `in`/`except` 대신 경로에 적용할 정규식을 사용합니다. 목록은
+`include`와 `exclude` 둘입니다. 경로가 `include` 패턴 중 하나 이상에 일치하고(`include`가
+없으면 모든 경로가 대상입니다) `exclude` 패턴 중 어느 것에도 일치하지 않을 때 범위 안에
+듭니다. `excludeIgnoreCase: true`는 `exclude` 패턴의 대소문자 구분을 없애며, `include`는
+항상 대소문자를 구분합니다.
 
 ```yaml
 disciplines:
@@ -517,7 +521,9 @@ stdin으로 무엇을 하는지는 판정하지 않습니다. 해석기에 넘
 `sources: { session: { transcript: true } }`는 세션 자신의 대화 기록(transcript)을 이름
 붙입니다 — 표면이 읽는 사용자 턴과 도구 호출을, 항목마다 관측
 순번을 실은 스냅샷 하나로 선언에 건넵니다. 이력 단계(`toolUses` · `userTexts` · `first` ·
-`ageMs`)가 그것을 읽고, `agentType`은 파싱된 사이드카를 읽습니다. 이 저장소의 라이브
+`ageMs`)가 그것을 읽고, `agentType`은 파싱된 사이드카를 읽습니다. `agentType`은 남길
+에이전트 종류를 `is` 인자로 요구합니다(`{ op: 'agentType', is: 'tdd-test-writer' }`).
+`is`가 없으면 그 단계는 컴파일되지 않고 해당 항목은 skip 등록으로 남습니다. 이 저장소의 라이브
 설정은 그런 선언 하나를 싣습니다. `tests-before-implementation`은 서브에이전트 스폰 둘의 순번
 위의 `ordered`이고 `sessionDisciplines`에 적혀 있습니다. 일곱째 고정 이름
 `actor`는 관측의 주체(actor)입니다. 서브에이전트 안에서는 `{ agentType }`, 주 세션에서는

package/dist/docs/reference/configuration/index.md

@@ -108,7 +108,7 @@ Optional.
 
 ```yaml
 witness:
-  token: 'covenant witness'   # the phrase a human types in the conversation
+  token: 'pdks witness'   # the phrase a human types in the conversation
   ttlMinutes: 10              # validity window, in minutes, from that message
 ```
 
@@ -135,7 +135,7 @@ carrying the token alone does, with any following lines free for the work itself
 A message that invokes — the token alone on the first line, the rest free:
 
 ```text
-covenant witness
+pdks witness
 
 now fix the hook file
 ```
@@ -143,7 +143,7 @@ now fix the hook file
 A message that merely mentions — the valve stays shut:
 
 ```text
-so when does `covenant witness` expire?
+so when does `pdks witness` expire?
 ```
 
 The token's value is free — any phrase works, and it is never checked for a prefix or a
@@ -352,7 +352,10 @@ banned word, a stray `.only`, a citation that resolves nowhere — is written as
 verdict. Existing occurrences are forgiven, so adopting the discipline never blocks a legacy
 codebase. `supply: empty` is what lets a file creation (no `pre`) count as all-added and a
 deletion (no `post`) as adding nothing; the `scope` block replaces `in`/`except` with
-regular expressions over the path.
+regular expressions over the path. It takes two lists, `include` and `exclude`: a path is
+in scope when it matches at least one `include` pattern (an absent `include` admits every
+path) and matches no `exclude` pattern. `excludeIgnoreCase: true` makes the `exclude`
+patterns case-insensitive; `include` is always case-sensitive.
 
 ```yaml
 disciplines:
@@ -542,7 +545,9 @@ third kind, `sources: { session: { transcript: true } }`, names the session's ow
 conversation history — the user turns and tool calls the surface reads, handed to the
 declaration as one snapshot whose entries carry their
 observation ordinal; the history steps (`toolUses`, `userTexts`, `first`, `ageMs`) read it, and
-`agentType` reads the parsed sidecar. This repository's live config carries one —
+`agentType` reads the parsed sidecar and requires `is`, the agent type to keep
+(`{ op: 'agentType', is: 'tdd-test-writer' }`); without it the step does not compile and
+the entry lands as a skip registration. This repository's live config carries one —
 `tests-before-implementation`, an `ordered` over the ordinals of two subagent spawns, written
 in `sessionDisciplines`. The seventh fixed name, `actor`, is the
 observation's actor — `{ agentType }` inside a subagent, `{}` in the main session, absent

package/dist/docs/reference/packages/adapter-claude-code.ko.md

@@ -6,7 +6,7 @@
 > 판정기가 읽는 파일 변경 증거와 대화 기록(transcript) 통로가 함께 실립니다. 세션 표면을
 > 프로젝트에 설치하는 것도 이 패키지가 합니다.
 >
-> 알파입니다. `polydeukes`와 함께 설치하며, `polydeukes`는 이 패키지의 `peerDependency`입니다.
+> 베타입니다. `polydeukes`와 함께 설치하며, `polydeukes`는 이 패키지의 `peerDependency`입니다.
 
 <a id="ownership"></a>
 ## 담당하는 기능
@@ -72,7 +72,7 @@ Claude Code의 입력을 공통 형식으로 번역합니다. 에이전트와
 프로젝트 루트에서 두 줄이면 Claude Code 세션 표면이 섭니다.
 
 ```sh
-npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-claude-code
 npx pdks-claude-code init
 ```
 
@@ -105,6 +105,7 @@ npx pdks-claude-code init
   스폰할 프로세스도, 기록할 로그 경로도 없습니다. 훅은 stderr에 한 줄을 남기고 종료 코드
   `2`를 내며 텔레메트리 로그에는 아무것도 추가되지 않습니다. 스폰 전 실패 가운데 이 경우만
   그렇고, 나머지는 모두 `pdks`에 도달해 행을 남깁니다.
-- **Grok는 `@polydeukes/adapter-grok`로 설치합니다.** 그 패키지가 자기 위임자와 명부를
-  씁니다. 두 세션 어댑터를 한 프로젝트에 함께 설치하면 호출마다 판정기가 두 번 실행될 수
+- **다른 호스트는 각자의 어댑터로 설치합니다.** Grok는 `@polydeukes/adapter-grok`로,
+  Codex는 `@polydeukes/adapter-codex`로 설치합니다. 각 패키지가 자기 위임자와 명부를
+  씁니다. 한 프로젝트에 세션 어댑터를 둘 이상 설치하면 호출마다 판정기가 여러 번 실행될 수
   있습니다.

package/dist/docs/reference/packages/adapter-claude-code.md

@@ -6,7 +6,7 @@
 > with the file-change evidence and the transcript channel the judge reads, and the
 > package installs the session surface into a project.
 >
-> Alpha. Install it next to `polydeukes`, which it names as a `peerDependency`.
+> Beta. Install it next to `polydeukes`, which it names as a `peerDependency`.
 
 <a id="ownership"></a>
 ## What this package owns
@@ -75,7 +75,7 @@ there is no separate precedent evaluator in this package. The grammar is in
 Two lines install the Claude Code session surface, run from the project root:
 
 ```sh
-npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-claude-code
 npx pdks-claude-code init
 ```
 
@@ -108,5 +108,7 @@ No configuration namespace of its own.
   project there is no process to spawn and no log path to write to, so the hook exits `2` with
   one line on stderr and the telemetry log gains nothing. Every other pre-spawn failure does
   reach `pdks` and does leave a row.
-- **Grok installs through `@polydeukes/adapter-grok`.** That package writes its own delegator
-  and roster. Installing both session adapters in one project can run the judge twice per call.
+- **Other hosts install through their own adapters.** Grok through
+  `@polydeukes/adapter-grok`, Codex through `@polydeukes/adapter-codex`. Each package writes
+  its own delegator and roster. Installing more than one session adapter in a project can run
+  the judge more than once per call.

package/dist/docs/reference/packages/adapter-codex.ko.md

@@ -0,0 +1,116 @@
+# `@polydeukes/adapter-codex`
+
+[English](adapter-codex.md) · **한국어**
+
+> **Codex의 설치 단위**입니다. 생명주기 이벤트는 어댑터 소유 세션 증거가 되고,
+> `PreToolUse` 페이로드는 패치가 건드리는 파일마다 원소 하나를 실은 약속(covenant) 입력 IR이
+> 됩니다.
+>
+> 베타입니다. `polydeukes`와 함께 설치하며, `polydeukes`는 이 패키지의 `peerDependency`입니다.
+
+<a id="ownership"></a>
+## 담당하는 기능
+
+Codex의 입력을 공통 형식으로 번역합니다. 에이전트와 도구의 구체적인 이름은 이 패키지에서
+처리하고 코어에는 넣지 않습니다.
+
+| 단위 | 하는 일 |
+|---|---|
+| `pdks-codex` 실행 파일 | 하위 명령 하나 `pdks-codex init`으로 프로젝트에 세션 표면을 등록합니다 |
+| `runHook` | 생명주기 증거를 기록하거나, `PreToolUse` 페이로드 하나를 입력 IR로 바꾸고 판정기를 스폰합니다 |
+| 세션 증거 | 시각을 붙인 사람 메시지와 완료된 도구 호출을 SHA-256 세션 파일에 저장하고 `SessionEnd`에서 지웁니다 |
+| 페이로드 검증 | 호스트의 생성 스키마가 필수로 지정한 키를 모두 요구하며, 그 호스트가 보내는 한 가지 표기만 받습니다 |
+| 패치 해석 | `apply_patch` 호출의 원본 패치 텍스트를 건드리는 파일마다 변경 하나로 풉니다 |
+| 경로 기준 변환 | 패치 경로를 호출의 작업 디렉터리 기준으로 해석한 뒤 프로젝트 루트 기준으로 실습니다 |
+
+생성된 훅 위임자가 불러오는 것이 `runHook({ repoRoot })`입니다. `UserPromptSubmit`과
+`PostToolUse`는 `.polydeukes/codex-sessions/` 아래에 엄격한 JSONL 레코드를 추가하고,
+`SessionEnd`는 그 세션 파일만 지웁니다. `PreToolUse`는 `tools` 명부와 이 레코드에서 만든
+`session`을 싣되 `actor`나 `channels`를 합성하지 않은 뒤, `repoRoot`에서
+`pdks covenant check --enforce block`을 스폰하고 그 자식 프로세스의 종료 코드를 그대로
+돌려줍니다. 판정은 그 자식 프로세스가 하며, 이 패키지에는 판정 코드가 없습니다.
+
+**이 패키지는 텔레메트리 행을 쓰지 않습니다.** 스폰 전에 실패하면 그 사실을 한 줄로 만들어
+`pdks`의 stdin으로 보내므로, 그 호출이 남기는 행은 언제나 한 곳에서만 기록됩니다.
+
+<a id="apply-patch"></a>
+## 형제 어댑터는 인자를 읽는데 이 어댑터가 텍스트를 해석하는 이유
+
+Codex는 훅에 도달하는 모든 파일 편집을 `apply_patch`라는 이름 하나로 정규화하고, 패치 자체를
+`tool_input.command`에 담습니다. 셸 호출이 명령줄을 싣는 것과 같은 자리입니다. 읽을 경로
+인자가 없습니다. `Edit`과 `Write`는 `.codex/hooks.json`에 적을 수 있는 matcher 별칭이지만,
+페이로드는 언제나 도구 이름을 `apply_patch`로 보냅니다. 그래서 별칭을 기준으로 삼은 명부나
+분기는 실제로 도착하는 어떤 호출과도 일치하지 않습니다.
+
+패치 하나가 한 호출에서 파일을 만들고 고치고 지우고 이름을 바꿀 수 있습니다. 이 어댑터는
+각각을 IR 하나의 원소로 실어 한 번만 스폰합니다. 모든 파일이 판정되고, 그중 하나라도
+차단되면 호출 전체가 차단됩니다. 이름 변경은 원소를 둘 만듭니다. 떠나는 경로와 도착하는
+경로를 모두 바꾸기 때문입니다.
+
+<a id="consumer"></a>
+## 사용자가 다루는 부분
+
+프로젝트 루트에서 두 줄이면 Codex 세션 표면이 설치됩니다.
+
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-codex
+npx pdks-codex init
+```
+
+`pdks-codex init`은 프로젝트에서 `polydeukes`를 찾아 확인한 뒤, 에이전트 중립 초기 구성을
+위해 `pdks init`을 스폰하고, 위임자를 쓴 뒤 `PreToolUse`, `UserPromptSubmit`, `PostToolUse`,
+`SessionEnd` 항목을 `.codex/hooks.json`에 병합합니다.
+병합은 기존 내용을 지우지 않습니다. 다른 이벤트, 다른 matcher, 이 패키지가 모르는 키는 그대로
+둡니다. 다시 실행하면 이미 있는 산출물을 건너뛴 것으로 보고하고 아무것도 덮어쓰지 않습니다.
+전체 산출물 목록은 [`pdks init`](../cli/init.ko.md#init-codex)에 있습니다.
+
+**등록 파일을 쓰는 것으로 설치가 끝나지 않습니다.** Codex는 훅 정의의 해시로 신뢰를
+기록하므로, 생성된 훅은 검토 대상으로 표시되고 `/hooks`에서 승인하기 전까지 건너뛰어집니다.
+`init`이 실행할 때마다 바이트가 같은 명령 문자열을 쓰는 이유가 이것입니다. 문자열이 바뀌면
+다시 승인해야 하고, 누군가 승인하기 전까지는 아무것도 판정되지 않습니다.
+
+이 어댑터를 `@polydeukes/adapter-claude-code`나 `@polydeukes/adapter-grok`과 한 프로젝트에
+함께 설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.
+
+- **생성된 훅**은 이 패키지에서 `runHook`을 불러옵니다. 패키지를 올리면 실행되는 내용이
+  올라가며, 훅 파일 자체는 다시 만들 필요가 없습니다.
+
+자체 설정 이름 공간은 없습니다. `pdks init`이 쓰는 초기 설정은 기본적으로 `.codex/hooks`를
+보호하므로, 이 설치기가 만드는 등록 파일은 같은 설치가 만든 설정이 지킵니다.
+
+<a id="limits"></a>
+## 선언된 한계
+
+앞의 넷은 호스트 자신의 한계이고 어떤 어댑터도 이 범위를 좁힐 수 없습니다. 첫째는 문서가
+아니라 실제 측정으로 확인한 사항이고, 다음 셋은 호스트 훅 문서가 밝힌 사항입니다.
+
+- **Code Mode의 `exec` 호출은 관측되지 않습니다.** codex-cli 0.154는 Code Mode `exec` 호출에도,
+  그 JavaScript 안에 중첩된 `tools.apply_patch` · `tools.exec_command` 호출에도 `PreToolUse`를
+  발화하지 않습니다([openai/codex#23411](https://github.com/openai/codex/issues/23411),
+  [#38850](https://github.com/openai/codex/issues/38850)). `/hooks`에 Active로 표시된 훅도 그
+  표면에서는 아무것도 보지 못하고, 거기서 편집된 보호 경로는 telemetry 행을 남기지 않습니다.
+  `pdks-codex init`이 이 사실을 `note:` 줄로 출력합니다.
+- **무엇을 판정하는지는 matcher가 아니라 명부가 정합니다.** 어댑터는 `apply_patch`와 `Bash`만
+  번역하고, 그 밖의 이름(Code Mode 이름, MCP 도구, `write_stdin`)은 판정기를 띄우기 전에
+  exit 2와 `blocked` 러너 행으로 거부합니다. `.codex/hooks.json`의 matcher를 그런 이름까지
+  넓히면 그 아래의 모든 호출이 판정 대신 차단되고, 그 편집은 신뢰 해시를 바꾸므로 `/hooks`에서
+  다시 승인하기 전까지 훅이 건너뛰어집니다.
+- **`write_stdin`은 다시 판정되지 않습니다.** 이미 `PreToolUse`를 통과한 unified-exec 세션에
+  입력을 전달합니다. 입력을 받으려고 열어 둔 셸은 그것을 연 호출에서 한 번 판정됩니다.
+- **호스트가 제공하는 도구는 이 경로를 지나지 않습니다.** 웹 검색 같은 도구는 로컬 함수 도구
+  훅을 거치지 않으므로 어떤 약속에도 닿지 않습니다.
+- **호스트는 자기 도구 훅을 완전한 차단 경계가 아니라 보조 장치라고 밝힙니다.** 일부 특수한
+  도구 경로는 기본 훅 경로를 지나지 않을 수 있습니다.
+- **불안정한 대화 기록은 채널로 쓰지 않습니다.** 페이로드가 대화 기록 경로를 지목하지만
+  호스트가 그 형식을 안정된 인터페이스가 아니라고 밝혔으므로 어떤 판정도 그것을 읽지
+  않습니다. 대신 어댑터가 `UserPromptSubmit`과 `PostToolUse`로 `session`을 만듭니다. 설정된
+  토큰을 사람 메시지의 첫 줄에 단독으로 보내면 다시 시도한 보호 호출을 허용할 수 있습니다.
+  사람 증거가 기록되지 않았거나 저장에 실패했다면 복구 메시지가 사용자 터미널을 안내합니다.
+  `actor`, `channels`, 도구 성공 여부는 합성하지 않습니다.
+- **프로젝트 밖으로 해석되는 패치는 판정하지 않고 거부합니다.** 그런 경로는 프로젝트 기준
+  상대 경로가 없고, 그것을 실은 원소는 어떤 관측 범위에도 들어가지 않아 판정 없이 지나가게
+  됩니다.
+- **`polydeukes`를 찾지 못하면 행이 남지 않습니다.** 프로젝트에서 통합 패키지를 찾을 수 없으면
+  스폰할 프로세스도 기록할 로그 경로도 없으므로, 훅은 stderr에 한 줄을 남기고 `2`로 끝나며
+  텔레메트리 로그에는 아무것도 추가되지 않습니다. 그 밖의 모든 스폰 전 실패는 `pdks`에 도달해
+  행을 남깁니다.