polydeukes 0.7.1 → 0.9.0

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,46 @@ 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`의
+`PreToolUse`, `UserPromptSubmit`, `PostToolUse`, `SessionEnd` 항목이 생깁니다. 이 JSON은
+덮어쓰지 않고 병합합니다. 사용자 항목, 같은 항목의 다른 handler, 다른 이벤트, 설치기가 모르는
+키는 그대로 둡니다. 초기 설정은 기본적으로 `.codex/hooks`를 보호합니다.
+
+**승인은 선택이 아닙니다.** Codex는 훅 정의의 해시로 신뢰를 기록하므로, 새로 쓴 훅은 검토
+대상으로 표시되고 누군가 승인하기 전까지 건너뛰어집니다. 그때까지는 아무것도 판정되지
+않습니다. `init`은 실행할 때마다 바이트가 같은 명령 문자열을 쓰므로, 다시 설치해도 이미 받은
+승인이 무효가 되지 않습니다.
+
+Codex는 훅에 도달하는 모든 파일 편집을 `apply_patch` 하나로 정규화하고, 경로 인자가 아니라 패치 텍스트를
+보냅니다. `Edit`과 `Write`는 훅 파일에 적을 수 있는 matcher 별칭이며 도구 이름으로 도착하지
+않습니다. 패치 하나가 여러 파일을 건드리면 파일마다 IR 원소 하나가 실리고, 그중 하나라도
+차단되면 호출 전체가 차단됩니다.
+
+**승인된 훅도 Code Mode는 덮지 못합니다.** codex-cli 0.154에서 Code Mode `exec` 호출과 그
+JavaScript 안에 중첩된 도구 호출은 `PreToolUse`에 도달하지 않으므로
+([openai/codex#23411](https://github.com/openai/codex/issues/23411)), 그 경로로 이루어진 편집은
+`/hooks`에 훅이 Active로 표시되는 동안에도 판정되지도 기록되지도 않습니다. `init`이 이 사실을
+`note:` 줄로 출력하고, [패키지 레퍼런스](../reference/packages/adapter-codex.ko.md#limits)가
+다른 선언된 한계와 함께 나열합니다.
+
+Codex의 대화 기록 형식은 계속 불안정하므로 해석하지 않습니다. 대신 `UserPromptSubmit`이
+시각을 붙인 사람 메시지를, `PostToolUse`가 완료된 도구 호출을 `.polydeukes/codex-sessions/`
+아래의 어댑터 소유 파일에 기록하고 `SessionEnd`가 지웁니다. 의도한 차단을 풀려면 설정된 증인
+토큰을 첫 줄에 단독으로 보낸 뒤 호출을 다시 시도합니다. 복구 메시지가
+`UserPromptSubmit` 증거가 없다고 알리면 재시도가 증인 밸브에 닿지 못하므로 자신의 터미널을
+사용합니다. 세션 어댑터를 한 프로젝트에 둘 이상 설치하면 호출마다 판정기가 두 번 실행될 수
+있습니다.
+
 <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,62 @@ 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 entries for
+`PreToolUse`, `UserPromptSubmit`, `PostToolUse`, and `SessionEnd` in `.codex/hooks.json`.
+That JSON is merged, not overwritten: user entries, sibling handlers, other events, 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 that reaches the hook 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.
+
+**An approved hook does not cover Code Mode.** In codex-cli 0.154 a Code Mode `exec` dispatch,
+and the tool calls nested in its JavaScript, do not reach `PreToolUse`
+([openai/codex#23411](https://github.com/openai/codex/issues/23411)), so an edit made that way
+is neither judged nor logged even while `/hooks` shows the hook Active. `init` prints this as a
+`note:` line; the [package reference](../reference/packages/adapter-codex.md#limits)
+lists it with the other declared limits.
+
+Codex's transcript format remains unstable and is never parsed. Instead, `UserPromptSubmit`
+records timestamped human messages and `PostToolUse` records completed tool calls in an
+adapter-owned file under `.polydeukes/codex-sessions/`; `SessionEnd` removes it. To release an
+intentional block, send the configured witness token alone on the first line, then retry the
+call. If the recovery message says no `UserPromptSubmit` evidence was recorded, use your own
+terminal because the retry cannot reach the witness valve. 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