polydeukes 0.6.1 → 0.8.0

package/dist/docs/reference/packages/sdk-ts.ko.md

@@ -0,0 +1,164 @@
+# `@polydeukes/sdk-ts`
+
+[English](sdk-ts.md) · **한국어**
+
+> **TypeScript에서 판정기로 가는 동사 하나**입니다. 약속(covenant) 입력 IR을
+> `pdks covenant check`에 건네고 판정 결과를 값으로 돌려받습니다.
+>
+> 베타입니다. `polydeukes` · `@polydeukes/core`와 함께 설치하며, 둘 다 이 패키지의
+> `peerDependencies`입니다.
+
+<a id="ownership"></a>
+## 담당하는 기능
+
+스폰과, 종료 상태를 값으로 옮기는 일이 전부입니다. 판정받는 프로젝트의 `polydeukes` 설치를
+찾고, 그 실행 파일에 입력을 표준 입력으로 넣어 돌린 뒤, 자식이 답한 것을 돌려줍니다. 판정
+코드는 여기에 없습니다. 분기는 우산 패키지를 찾았는지와 자식이 어떤 상태로 끝났는지뿐입니다.
+
+| 단위 | 하는 일 |
+|---|---|
+| `checkCovenant` | 판정받는 프로젝트에서 `pdks covenant check`를 스폰하고 판정 결과를 돌려줍니다 |
+| 우산 해소 | `repoRoot`의 설치 그래프에서 `polydeukes`를 찾아 `pdks` 실행 파일을 읽습니다 |
+| 판정 결과 변환 | 종료 코드 `0`은 `upheld`, `2`는 `blocked`, 그 밖은 모두 `unjudged`입니다 |
+
+이 패키지는 텔레메트리 행을 쓰지 않습니다. 실행이 남기는 행은 모두 판정이 일어난 자식
+프로세스가 쓰므로, 호출 하나에 행 하나는 그대로입니다.
+
+<a id="install"></a>
+## 설치
+
+```sh
+pnpm add @polydeukes/sdk-ts polydeukes @polydeukes/core
+```
+
+실행 파일도 설치 단계도 없습니다. 우산 패키지가 SDK가 스폰할 판정기를 공급하고, 코어가
+호출자가 채우는 `CovenantInput` 타입을 공급합니다.
+
+<a id="verb"></a>
+## 동사
+
+이 패키지는 ESM 전용입니다(`"type": "module"`, `import` 조건만 있고 `require`는 없음).
+호출하는 파일이 `.mjs`이거나 그 `package.json`이 `"type": "module"`을 선언해야 합니다.
+
+```ts
+import { checkCovenant } from '@polydeukes/sdk-ts';
+
+const verdict = await checkCovenant({
+  repoRoot: '/path/to/the/project',
+  input: {
+    toolCalls: [
+      {
+        name: 'writeFile',
+        args: { path: 'src/index.ts', content: 'export const answer = 42;\n' },
+        fileChange: {
+          kind: 'modify',
+          path: 'src/index.ts',
+          pre: 'export const answer = 41;\n',
+          post: 'export const answer = 42;\n',
+        },
+      },
+    ],
+    subagentSpawns: [],
+    userMessages: [],
+    tools: { mutating: ['writeFile', 'rm'], shell: ['exec'], commandArgs: ['command'] },
+  },
+});
+```
+
+IR은 호출자의 것입니다. 이 패키지는 IR을 읽지도 채우지도 않습니다. `session`도 `actor`도
+자기 명부도 더하지 않으며, 위의 `tools` 값도 호출자 자신의 도구 이름입니다. `subagentSpawns`와
+`userMessages`는 필수 배열이므로 둘 다 없는 호출자는 빈 배열을 보냅니다. `world` 키는 판정기가
+거부합니다. 러너가 세계를 디스크의 프로젝트에서 읽으며, 클라이언트가 세계를 고르면 무엇을
+판정할지를 고르는 것이 되기 때문입니다.
+
+<a id="spec"></a>
+## 스펙
+
+```ts
+type CheckCovenantSpec = {
+  repoRoot: string;
+  input: CovenantInput;
+  enforce?: 'advise' | 'block';
+  spawn?: (spec: CheckCovenantSpawnSpec) => Promise<{ status: number | null; stderr: string }>;
+};
+
+type CheckCovenantSpawnSpec = { command: string; args: string[]; cwd: string; stdin: string };
+```
+
+| 필드 | 무엇인가 |
+|---|---|
+| `repoRoot` | 판정받는 프로젝트입니다. 설정 발견, 세계 축, 자식의 cwd, 우산 패키지를 찾는 설치 그래프가 모두 여기 걸립니다 |
+| `input` | 호출자 자신의 IR이며 자식의 표준 입력으로 원문 그대로 갑니다 |
+| `enforce` | 실행 전체에 대한 관측자의 기본 자세입니다. **적지 않으면 `block`입니다** |
+| `spawn` | 주입하는 스폰 이음매입니다. 없으면 이 프로세스의 node 실행 파일로 자식을 띄웁니다 |
+
+**`enforce`의 기본값은 `block`입니다.** 이것은 표면의 강제 수준이지 항목의 것이 아닙니다.
+보호 경로와 `enforce: block`을 단 항목이 호출을 멈추고, 나머지 위반은 종료 코드 0에
+`advised`로 기록됩니다. 항목 자신의 강제 수준은 다른 표면에서와 같이 느슨한 쪽이 이기도록
+조합됩니다. `@polydeukes/adapter-claude-code`, `@polydeukes/adapter-grok`,
+`@polydeukes/adapter-codex`도 같은 수준으로 판정기를 스폰합니다.
+
+기본 스폰은 파일 서술자를 하나도 상속하지 않습니다. 호출자가 자기 서술자를 갖지 않을 수 있고,
+상속한 stdout이 닫혀 있으면 자식이 답하기 전에 EPIPE로 죽기 때문입니다. stderr는 모아서
+돌려주고, 판정기가 stdout에는 판정 결과를 쓰지 않으므로 stdout은 흘려보내고 버립니다.
+
+<a id="verdicts"></a>
+## 판정 결과 셋
+
+```ts
+type CheckCovenantVerdict =
+  | { verdict: 'upheld'; advisories: string }
+  | { verdict: 'blocked'; reason: string }
+  | { verdict: 'unjudged'; reason: string };
+```
+
+| 판정 결과 | 자식의 상태 | 호출자에게 뜻하는 것 |
+|---|---|---|
+| `upheld` | `0` | 호출이 판정을 받았고 아무것도 막지 않았습니다. `advisories`는 자식의 stderr 원문이며 그 실행이 낸 권고 줄을 싣습니다. 진행하면 됩니다 |
+| `blocked` | `2` | 호출이 판정을 받았고 무언가 막았습니다. `reason`은 자식의 stderr 원문입니다. 진행하지 않습니다 |
+| `unjudged` | 그 밖의 상태이거나 우산 패키지가 없음 | 판정이 일어나지 않았습니다. `reason`이 어느 쪽인지 말합니다. 이것을 통과로 읽으면 판정기가 설치되지 않은 프로젝트에서 모든 호출이 지나갑니다 |
+
+**밸브가 없고 그 자리를 사유가 대신합니다.** 무인 실시간 호출자에게는 TTY도 사람의 턴도
+없으므로, 이 패키지는 증인 인자를 받지 않고 세션을 지어내지도 않습니다. 대신
+`blocked.reason`과 `upheld.advisories`가 데이터로 돌아오고, 그 텍스트를 이슈나 로그에 적을지
+모델에게 돌려줄지는 소비자가 정합니다. 설정 저자와 소비자를 위한 기본 자세 규칙은
+[규율 작성하기](../../how-to/write-disciplines.ko.md#posture)에 있습니다.
+
+<a id="failure"></a>
+## 실패 예제
+
+프로젝트에 `polydeukes`가 설치돼 있지 않으면 스폰할 것이 없고, 동사는 `upheld`로 답하는 대신
+그 사실을 말합니다.
+
+```ts
+const verdict = await checkCovenant({ repoRoot: '/tmp/project-without-polydeukes', input });
+
+// {
+//   verdict: 'unjudged',
+//   reason: 'no polydeukes in the install graph of /tmp/project-without-polydeukes:
+//            install it to have this input judged',
+// }
+```
+
+자식 프로세스는 돌지 않고 텔레메트리 로그에도 아무것도 더해지지 않습니다. 행은 판정이
+일어나는 자리에 쓰이는데, 판정이 일어나지 않았기 때문입니다.
+
+<a id="limits"></a>
+## 선언된 한계
+
+- **IR은 호출자가 만듭니다.** 도구 명부와 변경 전 상태와 봉투는 호스트가 아는 사실이므로,
+  그것을 아는 소비자가 채웁니다. 이 패키지는 그중 무엇도 공급하지 않습니다.
+- **SDK가 여는 것은 세션 표면뿐입니다.** 입력이 표준 입력의 IR로 가고, 그것이 이 실행을 세션
+  표면 판정으로 만듭니다. 끝난 변경 집합을 가진 호출자는 대신 셸에서
+  `pdks covenant check --diff`에 통합 diff를 파이프합니다.
+- **여기서는 텔레메트리 행을 쓰지 않습니다.** 행은 모두 자식이 씁니다.
+- **`unjudged`는 통과가 아닙니다.** 판정기가 답하지 않았다는 사실을 기록하며, 판정기가 없는
+  프로젝트에서 무엇을 허용할지는 소비자가 정합니다.
+
+<a id="see-also"></a>
+## 함께 보기
+
+- [`pdks covenant check`](../cli/covenant-check.ko.md)
+- [`polydeukes`](polydeukes.ko.md)
+- [`@polydeukes/core`](core.ko.md)
+- [설정 참조](../configuration/index.ko.md)

package/dist/docs/reference/packages/sdk-ts.md

@@ -0,0 +1,167 @@
+# `@polydeukes/sdk-ts`
+
+**English** · [한국어](sdk-ts.ko.md)
+
+> **One verb from TypeScript to the judge** — hand a covenant input IR to
+> `pdks covenant check` and read the verdict back as a value.
+>
+> Beta. Install it next to `polydeukes` and `@polydeukes/core`, which it names as
+> `peerDependencies`.
+
+<a id="ownership"></a>
+## What this package owns
+
+The spawn and the translation of an exit status into a value, and nothing else. It locates the
+`polydeukes` install of the project being judged, runs its bin with the input on stdin, and
+returns what the child answered. No judgment logic lives here: the branches are whether the
+umbrella resolved and what status the child left with.
+
+| Unit | What it does |
+|---|---|
+| `checkCovenant` | Spawns `pdks covenant check` in the judged project and returns the verdict |
+| Umbrella resolution | Finds `polydeukes` in the install graph of `repoRoot` and reads its `pdks` bin |
+| Verdict translation | Exit `0` is `upheld`, exit `2` is `blocked`, everything else is `unjudged` |
+
+This package writes no telemetry row. Every row a run leaves is written by the child process,
+where the judgment happened, so one call still leaves one row.
+
+<a id="install"></a>
+## Install
+
+```sh
+pnpm add @polydeukes/sdk-ts polydeukes @polydeukes/core
+```
+
+There is no bin and no install step. The umbrella supplies the judge the SDK spawns, and the
+core supplies the `CovenantInput` type the caller fills in.
+
+<a id="verb"></a>
+## The verb
+
+The package is ESM only (`"type": "module"`, an `import` condition and no `require`): the calling
+file is a `.mjs`, or its `package.json` declares `"type": "module"`.
+
+```ts
+import { checkCovenant } from '@polydeukes/sdk-ts';
+
+const verdict = await checkCovenant({
+  repoRoot: '/path/to/the/project',
+  input: {
+    toolCalls: [
+      {
+        name: 'writeFile',
+        args: { path: 'src/index.ts', content: 'export const answer = 42;\n' },
+        fileChange: {
+          kind: 'modify',
+          path: 'src/index.ts',
+          pre: 'export const answer = 41;\n',
+          post: 'export const answer = 42;\n',
+        },
+      },
+    ],
+    subagentSpawns: [],
+    userMessages: [],
+    tools: { mutating: ['writeFile', 'rm'], shell: ['exec'], commandArgs: ['command'] },
+  },
+});
+```
+
+The IR is the caller's. This package neither reads it nor completes it: it adds no `session`,
+no `actor`, and no roster of its own, and the `tools` values above are the caller's own tool
+names. `subagentSpawns` and `userMessages` are required collections, so a caller with neither
+sends the empty arrays. A `world` key is refused by the judge — the runner reads the world from
+the project on disk, and a client choosing the world would be choosing what is judged.
+
+<a id="spec"></a>
+## The spec
+
+```ts
+type CheckCovenantSpec = {
+  repoRoot: string;
+  input: CovenantInput;
+  enforce?: 'advise' | 'block';
+  spawn?: (spec: CheckCovenantSpawnSpec) => Promise<{ status: number | null; stderr: string }>;
+};
+
+type CheckCovenantSpawnSpec = { command: string; args: string[]; cwd: string; stdin: string };
+```
+
+| Field | What it is |
+|---|---|
+| `repoRoot` | The project being judged: config discovery, the world axis, the child's cwd, and the install graph the umbrella is found in |
+| `input` | The caller's own IR, sent verbatim as the child's stdin |
+| `enforce` | The observer's posture for the whole run. **Absent is `block`** |
+| `spawn` | An injected spawn seam. Absent, the child runs under this process's node executable |
+
+**`enforce` defaults to `block`.** That is the surface's level, not an entry's: protected paths
+and entries carrying `enforce: block` stop the call, and every other break is recorded
+`advised` at exit 0. An entry's own level composes with it lenient-side-wins, as on every other
+surface. `@polydeukes/adapter-claude-code`, `@polydeukes/adapter-grok`, and
+`@polydeukes/adapter-codex` spawn the judge at the same level.
+
+The default spawn inherits no file descriptor. A caller may hold none of its own, and an
+inherited stdout that is closed would kill the child with EPIPE before it answered. stderr is
+collected and returned; stdout is drained and dropped, because the judge writes no verdict
+there.
+
+<a id="verdicts"></a>
+## The three verdicts
+
+```ts
+type CheckCovenantVerdict =
+  | { verdict: 'upheld'; advisories: string }
+  | { verdict: 'blocked'; reason: string }
+  | { verdict: 'unjudged'; reason: string };
+```
+
+| Verdict | Child status | What it means for the caller |
+|---|---|---|
+| `upheld` | `0` | The call was judged and nothing blocked it. `advisories` is the child's stderr verbatim, carrying any advisory lines the run produced. Proceed |
+| `blocked` | `2` | The call was judged and something blocked it. `reason` is the child's stderr verbatim. Do not proceed |
+| `unjudged` | anything else, or no umbrella | No judgment happened. `reason` says which. Reading it as an uphold would let an uninstalled judge pass every call |
+
+**There is no valve, and the reason is the substitute.** An unattended real-time caller has no
+TTY and no human turn, so this package takes no witness argument and invents no session.
+`blocked.reason` and `upheld.advisories` come back as data instead, and the consumer decides
+where the text goes — an issue, a log, or back to the model. The posture rules for a config
+author and for a consumer are in [write disciplines](../../how-to/write-disciplines.md#posture).
+
+<a id="failure"></a>
+## A failure example
+
+When the project has no `polydeukes` installed there is nothing to spawn, and the verb says so
+rather than answering `upheld`:
+
+```ts
+const verdict = await checkCovenant({ repoRoot: '/tmp/project-without-polydeukes', input });
+
+// {
+//   verdict: 'unjudged',
+//   reason: 'no polydeukes in the install graph of /tmp/project-without-polydeukes:
+//            install it to have this input judged',
+// }
+```
+
+No child process runs, and the telemetry log gains nothing: the row is written where the
+judgment happens, and no judgment happened.
+
+<a id="limits"></a>
+## Declared limits
+
+- **The caller builds the IR.** The tool roster, the pre-state, and the envelope are the
+  host's facts, so a consumer that knows them fills them in. This package supplies none of
+  them.
+- **The SDK exposes the session surface only.** The input travels as an IR on stdin, which is
+  what makes the run a session-surface judgment. A caller that has a finished change set pipes
+  a unified diff to `pdks covenant check --diff` from its shell instead.
+- **No telemetry row is written here.** Every row comes from the child.
+- **An `unjudged` verdict is not a pass.** It records that the judge did not answer, and the
+  consumer decides what a project without a judge is allowed to do.
+
+<a id="see-also"></a>
+## See also
+
+- [`pdks covenant check`](../cli/covenant-check.md)
+- [`polydeukes`](polydeukes.md)
+- [`@polydeukes/core`](core.md)
+- [Configuration reference](../configuration/index.md)

package/dist/docs/troubleshooting.ko.md

@@ -11,9 +11,9 @@
 
 프로젝트 루트 바로 아래에 `polydeukes.config.yaml`, `polydeukes.config.yml`,
 `polydeukes.config.json` 중 하나도 없으면 설정이 필요한 명령은 종료 코드 2를 반환합니다.
-Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init claude-code` 또는
-`pdks init grok`로 만들 수 있습니다. 이후 `pdks explain`을 실행합니다. 설정이 없다고
-기본 정책으로 대신 실행하지는 않습니다.
+Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init`, `pdks-claude-code init`,
+`pdks-grok init`, `pdks-codex init`로 만들 수 있습니다. 이후 `pdks explain`을 실행합니다.
+설정이 없다고 기본 정책으로 대신 실행하지는 않습니다.
 
 <a id="multiple-config"></a>
 ## 설정 파일이 여러 개일 때
@@ -31,15 +31,25 @@ Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init cl
 설정은 실행할 코드가 아니라 데이터이기 때문입니다.
 
 `protectedPath:`나 `adaptors:` 같은 오타는 거부합니다. 다만 어댑터 이름에는 확장 가능성을
-남겨 두었습니다. `adapters.gti:`도 설정으로 읽히지만 Git 어댑터는 사용하지 않습니다.
-올바른 키는 `adapters.git`입니다. 수정한 뒤 `pdks explain`에서 실제 등록 내용을 확인하세요.
+남겨 두었습니다. 아무도 구현하지 않은 네임스페이스도 설정으로 읽히지만 읽는 쪽이 없습니다.
+수정한 뒤 `pdks explain`에서 실제 등록 내용을 확인하세요.
+
+세션 안에서는 수정 자체가 막히지 않습니다. 설정이 로드되지 않는 동안 모든 호출은 차단되지만
+하나는 예외입니다. 대상이 설정 파일 하나뿐이고, 시작 텍스트가 디스크에 있는 파일 그대로이며,
+그 결과가 로드되는 Edit 또는 Write는 종료 코드 0으로 통과하며, `covenant-check` 라벨의
+`advised` 행 하나를 고쳐진 설정 자신의 `telemetry.logPath`에 남기고 stderr에 고친 오류를
+알립니다. 이 통과는 `--enforce` 기본 자세를 읽지 않습니다. 세션 훅은 항상 `--enforce block`으로
+실행되므로, 그 아래에서 차단되는 수정은 어디에서도 실행되지 못하기 때문입니다. 결과가 여전히
+로드되지 않는 수정은 다른 호출처럼 차단되고, 설정 파일과 다른 파일을 함께 건드리는 호출이나
+디스크의 바이트에서 시작하지 않는 증거를 실은 호출도 차단됩니다. 변경 집합 표면에는 이런 경로가
+없습니다. 설정을 고치는 커밋은 오류를 볼 수 있는 터미널에서 사람이 만드는 커밋이기 때문입니다.
 
 <a id="grok-witness"></a>
 ## Grok 증인
 
 훅을 아직 읽지 않은 문제와 증인(witness) 밸브를 사용할 수 없는 문제는 구별해야 합니다.
 
-- `pdks init grok` 실행 뒤 Hooks 탭을 다시 불러오거나 새 세션을 시작하세요. 실제 도구를
+- `pdks-grok init` 실행 뒤 Hooks 탭을 다시 불러오거나 새 세션을 시작하세요. 실제 도구를
   호출하고 텔레메트리를 확인합니다. 설치기가 성공했다고 해서 열린 세션에 훅이 적용됐다는
   뜻은 아닙니다.
 - Grok의 ACP 대화 기록에는 현재 세션 증인 밸브가 요구하는 Claude 형식의 인간 메시지가
@@ -48,6 +58,21 @@ Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init cl
 
 커밋 증인은 해당 스테이징 검사만 허용합니다. 차단된 Grok 도구 호출까지 허용하지 않습니다.
 
+<a id="codex-witness"></a>
+## Codex 증인
+
+여기서도 두 문제는 구별해야 하며, 첫 번째는 원인이 다릅니다.
+
+- `pdks-codex init` 실행 뒤 훅 신뢰는 훅 정의의 해시에 묶입니다. `.codex/hooks.json`이
+  바뀌면 `/hooks`에서 승인하기 전까지 신뢰하지 않으므로, 설치기가 성공해도 실행되는 훅이
+  없을 수 있습니다. 실제 도구를 호출하고 텔레메트리를 확인하세요.
+- Codex는 대화 기록 경로를 알려 주지만 그 형식을 안정된 것으로 문서화하지 않으므로 어떤
+  판정도 읽지 않고, IR은 `session`과 `actor`를 생략합니다. 따라서 세션 증인(witness)
+  밸브가 쓸 인간 메시지 증거가 없으며, 훅을 다시 승인해도 이 기능이 생기지는 않습니다.
+  복구가 필요하면 본인의 터미널에서 작업하세요.
+
+커밋 증인은 차단된 Codex 도구 호출도 허용하지 않습니다.
+
 <a id="config-fault"></a>
 ## 선언을 판정으로 구성하지 못할 때
 
@@ -64,16 +89,21 @@ Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init cl
 판정기를 별도로 복사해 가지고 있지 않습니다. 복구 뒤 실제 호출로 다시 확인합니다.
 텔레메트리를 불러오기 전에 실패했다면 기록이 전혀 남지 않을 수도 있습니다.
 
-세션 훅은 메시지 앞에 `covenant hook failed closed:`를, 커밋 검사는
-`covenant check failed closed:`를 붙입니다. 실제로 보게 되는 두 형태는 다음과 같습니다.
+판정기 자신이 거부하는 실패(설정 없음 · 잘못된 설정 · 빌드되지 않은 판정기)는 두 표면 모두
+`covenant check failed closed:`를 붙입니다. 훅이 `pdks covenant check`에 판정을 맡기고 그 메시지를
+그대로 전달하기 때문입니다. 판정기를 스폰하기 *전에* 실패한 경우 — 어댑터가 `polydeukes`를
+찾지 못하거나 자식이 판정 없이 종료한 경우 — 만 `covenant hook failed closed:`를 붙입니다.
+실제로 보게 되는 두 형태는 다음과 같습니다.
 
 ```text
 covenant hook failed closed: Cannot find package 'polydeukes' imported from …
 covenant check failed closed: the covenant judges could not be loaded from … — run 'pnpm build' to rebuild them: Cannot find module './self-mod.js' …
+covenant check failed closed: invalid config in polydeukes.config.yaml: … — fix polydeukes.config.yaml in one Edit or Write whose result loads; every other call stays blocked until it does
 ```
 
 첫째는 설치된 패키지가 없는 경우이고, 둘째는 소스 체크아웃에서 판정기 빌드 산출물이 없거나
-일부만 있는 경우입니다.
+일부만 있는 경우이며, 셋째는 세션 표면에서 설정이 로드되지 않는 경우로 그 줄이 설정을 고칠
+호출 하나를 알려 줍니다.
 
 <a id="reading-verdict"></a>
 ## 판정 결과 읽기
@@ -105,19 +135,21 @@ covenant check failed closed: the covenant judges could not be loaded from …
 <a id="blocked-commit"></a>
 ## 커밋이 차단됐을 때
 
-본인의 터미널에서 커밋을 실행하고 TTY 프롬프트에 설정된 토큰 전체를 입력하세요.
-비대화형 스테이징 검사는 이 응답을 받을 수 없습니다. 검사가 작업을 거부하면 종료 코드 2를
-반환합니다. Git은 커밋 실패를 다른 0이 아닌 코드로 알릴 수도 있습니다.
+변경 집합 표면은 사람에게 묻지 않습니다. 기본값에서는 모든 판정에 종료 코드 0을 내고 위반을
+`advised`로 기록합니다. 종료 코드 2는 검사를 `--enforce block`으로 실행했을 때(보호 경로나
+`enforce: block` 항목의 위반) 또는 판정 자체가 불가능할 때만 냅니다. 커밋을 멈출지는 훅
+배선이 정합니다. 종료 코드를 따르는 훅은 커밋을 멈추고, 무시하는 훅은 멈추지 않습니다. Git은
+커밋 실패를 다른 0이 아닌 코드로 알릴 수도 있습니다.
 
-일반 규율 항목은 자체 수준과 어댑터 수준이 모두 차단을 허용해야 작업을 멈춥니다.
-`adapters.git.enforce: block`만 설정해도 기본값 `advise`인 항목이 자동 승격되지는 않습니다.
-수준 변경은 정책을 바꾸는 결정이지 필수 복구 절차가 아닙니다. 커밋 프롬프트와 세션 메시지는
-서로 별개의 증인 입력 경로입니다.
+일반 규율 항목은 자신이 `enforce: block`을 적고 검사가 `--enforce block`으로 실행될 때만
+작업을 멈춥니다. 설정에는 기본값 `advise`인 항목을 승격하는 것이 없습니다. 수준 변경은
+정책을 바꾸는 결정이지 필수 복구 절차가 아닙니다. 판정된 위반을 통과시키려면 설정이 아니라
+훅 명령에서 `--enforce block`을 빼세요. 행은 그대로 남습니다.
 
-<a id="skipped-rows-on-the-commit-surface"></a>
-## 커밋 표면의 미판정 기록
+<a id="skipped-rows-on-the-change-set-surface"></a>
+## 변경 집합 표면의 미판정 기록
 
-대화 기록을 읽는 선언에 `supply: { session: 'pass' }`가 있으면 세션이 없는 커밋 표면에서는
+대화 기록을 읽는 선언에 `supply: { session: 'pass' }`가 있으면 세션이 없는 변경 집합 표면에서는
 `supply-pass`를 기록합니다. 이 약속은 세션 표면에서 확인하세요. 미판정은 과거 작업을
 검증했다는 뜻이 아닙니다. 다른 채널을 공급할 수 없으면 `no-observation`이 나올 수도
 있습니다. 모든 자료 부재를 같은 실패로 취급하지 말고 등록 내용과 사유를 확인하세요.

package/dist/docs/troubleshooting.md

@@ -11,8 +11,9 @@ or the judging packages, provided its own installed documentation bundle is inta
 
 Commands that need configuration exit 2 when none of `polydeukes.config.yaml`,
 `polydeukes.config.yml`, or `polydeukes.config.json` exists directly at the project root.
-Restore the intended file from Git, or use `pdks init claude-code` / `pdks init grok` for a new
-project. Then run `pdks explain`. No configuration means no silent default policy.
+Restore the intended file from Git, or use `pdks init` / `pdks-claude-code init` /
+`pdks-grok init` / `pdks-codex init` for a new project. Then run `pdks explain`. No
+configuration means no silent default policy.
 
 <a id="multiple-config"></a>
 ## More than one config file
@@ -28,15 +29,27 @@ field. Repair invalid YAML, custom tags, unknown fields, or an empty `languages`
 Custom YAML tags are rejected even if the parser cannot execute them: configuration is data.
 
 Typos such as `protectedPath:` or `adaptors:` are refused. Adapter namespace names are deliberately
-open, however: `adapters.gti:` can load but is not read by the Git adapter. Its actual key is
-`adapters.git`. After repair, run `pdks explain` and check the assembled registrations.
+open, however: a namespace nobody implements loads without being read by anything. After repair,
+run `pdks explain` and check the assembled registrations.
+
+Inside a session the repair itself is not locked out. While the config does not load, every
+call fails closed except one: an Edit or Write whose only target is the config file, whose
+starting text is the file as it is on disk, and whose result loads. That call passes with exit
+0 and one `advised` row under the `covenant-check` label, written to the repaired config's own
+`telemetry.logPath`, and the stderr line names the fault it repaired. The pass does not read
+the `--enforce` posture: the session hook always runs with `--enforce block`, and a repair that
+blocked under it would never run anywhere. A rewrite that still does not load is blocked like
+any other call, and so is a call that touches the config together with another file, or one
+whose evidence does not start from the bytes on disk. The change-set surface has no such path:
+a commit that repairs the config is a human's commit, made from a terminal that can see the
+error.
 
 <a id="grok-witness"></a>
 ## Grok witness
 
 A hook not yet loaded and an unavailable witness valve are different problems:
 
-- After `pdks init grok`, reload the Hooks tab or start a new session. Verify an actual call and
+- After `pdks-grok init`, reload the Hooks tab or start a new session. Verify an actual call and
   its telemetry; a successful installer run does not prove the open host loaded the hook.
 - Grok's ACP history does not supply the Claude-format human message required by the current
   session witness valve. Reloading does not add that capability. Perform a necessary repair
@@ -44,6 +57,21 @@ A hook not yet loaded and an unavailable witness valve are different problems:
 
 A commit witness authorizes its staged check only. It cannot release a blocked Grok tool call.
 
+<a id="codex-witness"></a>
+## Codex witness
+
+The same two problems are distinct here, and the first has its own cause:
+
+- After `pdks-codex init`, hook trust is bound to the hash of the hook definition. A changed
+  `.codex/hooks.json` is not trusted until you approve it through `/hooks`, so an installer that
+  succeeded can still leave no hook running. Verify an actual call and its telemetry.
+- Codex names a transcript path but documents the format as unstable, so no judgment reads it
+  and the IR omits `session` and `actor`. The session witness valve therefore has no
+  human-message evidence to work from, and approving the hook again does not add that
+  capability. Perform a necessary repair from your own terminal.
+
+A commit witness cannot release a blocked Codex tool call either.
+
 <a id="config-fault"></a>
 ## Config-fault
 
@@ -60,16 +88,21 @@ workspace build from your own terminal. The generated hook delegates to the inst
 it is not an independent copy of the judge. Verify another real call after repair. A failure
 before telemetry can load may leave no row at all.
 
-The session hook prefixes the message with `covenant hook failed closed:` and the commit check
-with `covenant check failed closed:`. The two shapes you will see:
+A failure the judge itself refuses — a missing or invalid config, an unbuilt judge — carries
+`covenant check failed closed:` on both surfaces, because the hook delegates to
+`pdks covenant check` and passes its message through. Only a failure *before* the judge could be
+spawned — the adapter cannot find `polydeukes`, or the child exited without a verdict — carries
+`covenant hook failed closed:`. The two shapes you will see:
 
 ```text
 covenant hook failed closed: Cannot find package 'polydeukes' imported from …
 covenant check failed closed: the covenant judges could not be loaded from … — run 'pnpm build' to rebuild them: Cannot find module './self-mod.js' …
+covenant check failed closed: invalid config in polydeukes.config.yaml: … — fix polydeukes.config.yaml in one Edit or Write whose result loads; every other call stays blocked until it does
 ```
 
 The first is the installed package missing; the second is a source checkout whose judge
-build output is missing or partial.
+build output is missing or partial; the third is a config that does not load, on the session
+surface, where the line names the one call that would repair it.
 
 <a id="reading-verdict"></a>
 ## Reading a verdict
@@ -101,19 +134,22 @@ A witness cannot repair missing modules or other failures that prevent judgment
 <a id="blocked-commit"></a>
 ## A blocked commit
 
-Run the commit from your own terminal and answer its TTY prompt with the complete configured
-token. A non-interactive staged check cannot obtain that answer. The check exits 2 when it refuses;
-Git may report a different nonzero exit code for the failed commit.
+The change-set surface does not prompt. By default it exits 0 on every verdict and records the
+break as `advised`; it exits 2 only when the check runs with `--enforce block` (a protected
+path or an entry set to `enforce: block` broke) or when it could not judge at all. Whether the
+commit stops is your hook wiring — a hook that honours the exit code stops it, one that ignores
+it does not. Git may report a different nonzero exit code for the failed commit.
 
-A normal entry blocks only when its own level and the adapter's level both permit blocking.
-Setting only `adapters.git.enforce: block` does not promote default-`advise` entries. Changing a
-level is a policy decision, not a required repair. The prompt is separate from a session message.
+A normal entry blocks only when it declares `enforce: block` and the check runs with
+`--enforce block`; nothing in the config promotes a default-`advise` entry. Changing a level is
+a policy decision, not a required repair. To let a judged break through, drop `--enforce block`
+from the hook command rather than editing the config — the row is still written.
 
-<a id="skipped-rows-on-the-commit-surface"></a>
-## `skipped` rows on the commit surface
+<a id="skipped-rows-on-the-change-set-surface"></a>
+## `skipped` rows on the change-set surface
 
 A transcript-reading declaration with `supply: { session: 'pass' }` records `supply-pass` when the
-commit surface has no session. Use the session surface for that promise; a skip does not verify
+change-set surface has no session. Use the session surface for that promise; a skip does not verify
 history. Other unavailable channels can produce `no-observation`. Inspect the registration and
 reason instead of treating every missing source as the same failure.
 

package/dist/docs/tutorials/first-judgment.ko.md

@@ -17,12 +17,13 @@ mkdir pdks-example
 cd pdks-example
 git init
 printf '{"name":"pdks-example","private":true}\n' > package.json
-pnpm add -D polydeukes   # 프로젝트 의존성. 일회성 npx 실행이 아님
-pnpm exec pdks init claude-code
+pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-claude-code   # 프로젝트 의존성. 일회성 npx 실행이 아님
+pnpm exec pdks-claude-code init
 ```
 
 설치기는 각 파일을 만들었으면 `created`, 이미 있어서 보존했으면 `skipped`로 보고합니다.
-초기 설정, 훅 위임 파일, Claude Code 등록 설정, 문서 조회 안내, `discipline-draft` 스킬과
+초기 설정, 훅 위임 파일(`.claude/hooks/covenant-pretooluse.mjs`), Claude Code 등록 설정
+(`.claude/settings.json`), 문서 조회 안내(`.claude/rules/polydeukes.md`), `discipline-draft` 스킬과
 텔레메트리 제외 항목을 만듭니다. 기존 사용자 파일은 보존하고, 설정은 통째로 덮지 않고
 병합합니다.
 
@@ -73,7 +74,8 @@ tail -n 5 .polydeukes/roi.log
 
 - [프로젝트 설정](../how-to/configure-project.ko.md)에서 임시 언어 이름과 테스트 명령을
   바꿉니다.
-- Grok이나 git pre-commit 훅은 [관측 표면 연결](../how-to/connect-surfaces.ko.md)을 참고합니다.
+- Grok, Codex, git pre-commit 훅은 [관측 표면 연결](../how-to/connect-surfaces.ko.md)을
+  참고합니다.
 - [규율 작성](../how-to/write-disciplines.ko.md) 예제를 실행하고, 권고 결과를 확인한 뒤 차단
   여부를 결정합니다.
 

package/dist/docs/tutorials/first-judgment.md

@@ -17,12 +17,13 @@ mkdir pdks-example
 cd pdks-example
 git init
 printf '{"name":"pdks-example","private":true}\n' > package.json
-pnpm add -D polydeukes   # a project dependency, not a one-off npx run
-pnpm exec pdks init claude-code
+pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-claude-code   # project dependencies, not a one-off npx run
+pnpm exec pdks-claude-code init
 ```
 
 The installer reports `created` or `skipped` for each artifact. It creates a starter config,
-the hook delegator, the Claude Code registration, a documentation discovery file, the
+the hook delegator (`.claude/hooks/covenant-pretooluse.mjs`), the Claude Code registration
+(`.claude/settings.json`), a documentation discovery file (`.claude/rules/polydeukes.md`), the
 `discipline-draft` skill, and a telemetry ignore entry. Existing user files are preserved;
 settings are merged rather than replaced.
 
@@ -73,7 +74,8 @@ valve is assembled. See [configuration errors](../troubleshooting.md#invalid-con
 
 - [Configure the project](../how-to/configure-project.md) to replace the placeholder language
   and test command.
-- [Connect the surfaces](../how-to/connect-surfaces.md) for Grok or a git pre-commit hook.
+- [Connect the surfaces](../how-to/connect-surfaces.md) for Grok, Codex, or a git pre-commit
+  hook.
 - [Write a discipline](../how-to/write-disciplines.md) and observe an advisory before choosing
   whether it should block.
 

package/dist/explain.d.ts

@@ -17,7 +17,7 @@ export type ExplainSpec = {
  * Read the config at `repoRoot`, assemble both surfaces, and render them.
  *
  * The session assembly is given a transcript path, so its `transcript-mod` registration
- * exists here exactly as it does under a normal hook payload — the path is never read,
+ * exists here exactly as it does under a normal call payload — the path is never read,
  * because the injected transcript is the no-op one.
  */
 export declare function explain(spec: ExplainSpec): Promise<{