polydeukes 0.6.1 → 0.8.0

package/dist/docs/how-to/configure-project.md

@@ -36,8 +36,9 @@ monorepo sub-package whose dependencies installed at the workspace root, count t
 # yaml-language-server: $schema=../../node_modules/polydeukes/dist/schema/polydeukes.schema.json
 ```
 
-`pdks init claude-code` adds the schema line only when the default path resolves relative to the
-generated config. If the line is absent, add a relative path to the installed schema yourself.
+`pdks init` — which `pdks-claude-code init` runs for you — adds the schema line only when the
+default path resolves relative to the generated config. If the line is absent, add a relative path
+to the installed schema yourself.
 An unresolvable `$schema` can disable editor validation without displaying an error.
 
 If you installed `@polydeukes/core` directly rather than the umbrella, name its copy:
@@ -72,24 +73,26 @@ Loading this setting does not itself run the command.
 
 | Setting | Effect on a violation |
 |---|---|
-| `adapters.git.enforce: advise` | Record advice and let the commit continue, without a witness prompt. |
-| `adapters.git.enforce: block` | Refuse a blocking judgment; the staged path can offer a TTY witness prompt. |
+| `enforce: advise` on an entry (or absent) | Record advice and let the call proceed, exit 0. |
+| `enforce: block` on an entry | Refuse the judged call, exit 2. |
 
-An ordinary discipline also has its own level, defaulting to `advise`. **The lenient level wins.**
-Setting only the adapter to `block` does not promote an ordinary entry. Protection of configured
-paths is separate from that per-entry default. Assembly errors still exit 2 at either level.
+**Absent means `advise`.** There is no surface-level enforcement key in the config: each entry
+carries its own level and nothing promotes an absent one. Protection of configured paths is
+separate from that per-entry default — it blocks on the session surface, and on the change-set
+surface it lands `advised` unless the command is run with `--enforce block`. Assembly errors
+still exit 2.
 
-Top-level `protectedPaths` applies to both surfaces. `adapters.git.protectedPaths` adds commit-only
-paths. Use the latter for files that may be edited in a session but need protection when committed.
+`protectedPaths` is a single top-level list that applies to both surfaces. On the change-set
+surface the judge only emits the exit code; whether the commit stops is your hook wiring.
 See [surface connection and witnesses](./connect-surfaces.md#witness-and-recovery).
 
 <a id="confirm-the-project"></a>
 ## Confirm the project
 
 - `pdks explain` loads the configuration and shows registrations without judging a change.
-- `pdks covenant check --worktree` compares HEAD with disk, including untracked, non-ignored files.
-- `pdks covenant check` observes staged changes. A blocking result can prompt only when a TTY is
-  available; the command does not prompt merely because the adapter is set to `block`.
+- `git diff HEAD | pdks covenant check --diff` judges everything not yet committed.
+- `git diff --cached | pdks covenant check --diff` observes staged changes — the pre-commit shape.
+  The command never prompts; it exits 0 or 2 and your hook wiring decides the commit's fate.
 
 Check stderr and telemetry as well as the exit code. Advice and some skipped observations exit 0.
 If assembly fails, diagnose the named configuration or missing package before testing a discipline.

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

@@ -2,19 +2,21 @@
 
 [English](../how-to/connect-surfaces.md) · **한국어**
 
-> 작업에 맞는 표면을 고릅니다. Claude Code와 Grok는 세션 표면을 배선하고, git은 커밋 표면을 배선합니다.
+> 작업에 맞는 표면을 고릅니다. Claude Code와 Grok, Codex는 세션 표면을 배선하고, git은 변경 집합 표면을 배선합니다.
 
 두 표면은 같은 설정 어휘를 쓰지만 판정 시점이 다릅니다. AI 파트너가 편집할 때는 세션 표면을,
-변경을 이력으로 기록하기 전에는 커밋 표면을 사용합니다.
+변경을 이력으로 기록하기 전에는 변경 집합 표면을 사용합니다.
 
 <a id="claude-code"></a>
 ## Claude Code 세션 표면
 
 Claude Code에서 AI 파트너와 함께 개발할 때 씁니다.
 
-1. 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes`. 일회성 `npx` 실행만으로는
-   부족합니다. 두 표면 모두 프로젝트에 설치된 패키지에서 판정기를 불러옵니다.
-2. 프로젝트를 배선합니다. `pnpm exec pdks init claude-code`.
+1. 세 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes
+   @polydeukes/core @polydeukes/adapter-claude-code`. 일회성 `npx` 실행만으로는 부족합니다. 두 표면 모두
+   프로젝트에 설치된 패키지에서 판정기를 불러옵니다.
+2. 프로젝트 루트에서 배선합니다. `pnpm exec pdks-claude-code init`. 이 실행 파일은 어댑터가
+   제공하며, 먼저 `pdks init`으로 초기 파일을 만든 뒤 Claude Code 등록 산출물을 씁니다.
 3. 생성된 훅, 병합된 설정, 초기 설정 파일, 문서 안내와 `discipline-draft` 스킬을 확인합니다.
 4. 훅이 바뀌면 프로젝트를 다시 엽니다. 생성된 훅은 패키지에 판정을 위임하므로 패키지를
    갱신할 때 훅 파일까지 다시 쓸 필요는 없습니다.
@@ -29,54 +31,83 @@ Claude Code에서 AI 파트너와 함께 개발할 때 씁니다.
 
 Grok에서 개발할 때 씁니다.
 
-1. 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes`.
-2. 프로젝트를 배선합니다. `pnpm exec pdks init 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 파일이 생깁니다. Claude 훅이 이미 있으면
-Grok의 `command`도 그 파일을 가리킵니다. `.claude/settings.json`도 있다면 같은 `command`를
-등록한 Claude 항목에 맞춰 Grok의 `matcher`를 설정합니다. 두 값이 모두 같아야 Grok가 중복 등록을
-하나로 처리해 판정기를 두 번 실행하지 않기 때문입니다.
-새 등록의 제한 시간은 60초입니다. Grok 호스트의 기본값은 5초이며, 훅 실행이 시간 초과로
-끝나면 해당 호출을 차단하지 않습니다(fail-open).
+Grok 프로젝트에는 `.grok/hooks/` 아래에 훅 JSON과 위임자가 생깁니다. 새 등록의 제한 시간은
+60초입니다. Grok 호스트의 기본값은 5초이며, 훅 실행이 시간 초과로 끝나면 해당 호출을
+차단하지 않습니다(fail-open). 세션 어댑터를 한 프로젝트에 둘 이상 설치하면 호출마다
+판정기가 두 번 실행될 수 있습니다.
 
-Grok는 세션 증인 밸브에 필요한 Claude 형식의 인간 메시지를 공급하지 않습니다. 대화 기록은
-Claude JSONL이 아니라 ACP `updates.jsonl`입니다.
-의도한 편집이 차단되면 자신의 터미널에서 수행하세요. 커밋 표면의 증인 프롬프트는 해당
-커밋에만 적용되며, 차단된 Grok 도구 호출을 허용하지는 않습니다.
+Grok는 세션 증인(witness) 밸브에 필요한 Claude 형식의 인간 메시지를 공급하지 않습니다. 대화
+기록은 Claude JSONL이 아니라 ACP `updates.jsonl`입니다.
+의도한 편집이 차단되면 자신의 터미널에서 수행하세요. 변경 집합 표면에는 증인 프롬프트가 없으므로
+차단된 Grok 도구 호출을 커밋 쪽에서 허용할 방법도 없습니다.
 
-<a id="commit-surface"></a>
-## 커밋 표면
+<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>
+## 변경 집합 표면
 
 스테이징한 변경을 이력으로 기록하기 전에 Git에서 판정하려면 이 표면을 사용합니다.
 
 1. 프로젝트 루트에 `polydeukes.config.yaml`을 만듭니다.
 2. pre-commit 훅을 추가합니다.
-3. 필요할 때는 `pnpm exec pdks covenant check`를 직접 돌려 같은 판정을 봅니다.
+3. 필요할 때는 `git diff HEAD | pnpm exec pdks covenant check --diff`를 직접 돌려 같은
+   판정을 봅니다.
 
-lefthook 예시는 다음과 같습니다.
+lefthook 예시는 다음과 같습니다. `git diff`의 플래그는 판정기가 받는 것을 고정합니다. 색 코드
+없음, 외부 diff 드라이버 없음, textconv 변환 없음, 번역기가 벗기는 `a/`·`b/` 접두입니다. 사용자의
+git 설정이 관측을 바꾸지 못합니다(CLI 레퍼런스 참고).
 
 ```yaml
 pre-commit:
   commands:
     covenant:
       priority: 1
-      interactive: true
-      run: ./node_modules/.bin/pdks covenant check
+      run: git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff
 ```
 
 husky 예시는 다음과 같습니다.
 
 ```sh
 # .husky/pre-commit
-./node_modules/.bin/pdks covenant check
+git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff
 ```
 
 일반 git 훅으로 연결해도 됩니다.
 
 ```sh
 #!/bin/sh
-./node_modules/.bin/pdks covenant check
+git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff
 ```
 
 일반 훅은 `.git/hooks/pre-commit`으로 저장한 뒤 `chmod +x .git/hooks/pre-commit`으로
@@ -84,12 +115,13 @@ husky 예시는 다음과 같습니다.
 관리자로 설치하고 YAML을 저장한 뒤 훅 설치 명령을 실행합니다. husky는 git이 찾을 수 있도록
 husky 설치기로 `.husky/pre-commit`을 저장하세요.
 
-`adapters.git.enforce: advise`이면 위반을 `advised`로 기록하고 stderr에 알린 뒤 커밋을
-허용합니다. `block`이면 보호 경로 위반과 `enforce: block`으로 지정한 항목의 위반을
-차단할 수 있습니다. 일반 항목의 기본값은 여전히 `advise`이며 표면 설정이 이를 승격하지
-않습니다. 증인이 설정돼 있고 터미널에 연결된 경우, 스테이징 검사에서 `/dev/tty` 프롬프트를
-제공합니다. `--worktree`와 `--range`는 프롬프트 없이 보고합니다. 조립 실패는 어느 강제
-수준에서도 종료 코드 2를 반환합니다.
+판정기는 종료 코드 0 또는 2만 내고 사람에게 묻지 않습니다. 기본값에서는 `protectedPaths`
+위반을 포함한 이 표면의 모든 위반이 stderr에 진단 한 줄을 남기고 행으로 기록되며 종료
+코드 0입니다. 스테이징된 관문 파일 변경은 이미 세션 표면에서 판정을 받았거나 사람이 직접
+한 것이고, 이 표면에는 사람이 답할 밸브가 없기 때문입니다. `protectedPaths` 위반이나
+`enforce: block` 항목의 위반을 종료 코드 2로 받으려면 명령에 `--enforce block`을 붙입니다.
+커밋을 멈출지는 훅 배선이 정합니다. 위 예시는 종료 코드를 그대로 따릅니다. 조립 실패는
+언제나 종료 코드 2입니다.
 
 <a id="witness-and-recovery"></a>
 ## 증인과 회복
@@ -97,7 +129,8 @@ husky 설치기로 `.husky/pre-commit`을 저장하세요.
 증인 토큰은 두 표면에서 같은 뜻이지만 전달 방식은 다릅니다.
 
 - 세션 표면에서는 대화 메시지 첫 줄에 토큰만 단독으로 넣습니다.
-- 커밋 표면에서는 TTY 프롬프트에 전체 토큰을 입력합니다.
+- 변경 집합 표면에는 프롬프트가 없습니다. 판정은 종료 코드로 전달되고, 그것으로 무엇을 할지는
+  훅 배선이 정합니다.
 
 밸브는 판정 결과가 차단일 때 확인합니다. 의도한 편집 전에 토큰을 입력해도 되며, 먼저
 실패하는 요청을 보낼 필요는 없습니다. 정상 판정은 바꾸지 않고, 현재 Grok 대화 기록
@@ -111,5 +144,5 @@ Grok가 훅을 아직 읽지 못했다면 Hooks 탭을 다시 불러오거나
 
 - `pdks explain`은 각 표면이 어떤 등록을 조립했는지 보여 줍니다.
 - `.polydeukes/roi.log`는 표면이 남긴 행을 기록합니다.
-- `pdks covenant check --worktree`는 작업 뒤에 쓰기 좋은 즉시 확인 명령입니다.
-- `pdks covenant check --range <base>..<head>`는 PR 전에 쓰기 좋은 형태입니다.
+- `git diff HEAD | pdks covenant check --diff`는 작업 뒤에 쓰기 좋은 즉시 확인 명령입니다.
+- `git diff <base>..<head> | pdks covenant check --diff`는 PR 전에 쓰기 좋은 형태입니다.

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

@@ -2,21 +2,23 @@
 
 **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 commit 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 commit surface when history is about
-to be written.
+session surface when an AI partner is making edits, and use the change-set surface when history
+is about to be written.
 
 <a id="claude-code"></a>
 ## Claude Code session surface
 
 Use this when the project is developed alongside an AI partner in Claude Code.
 
-1. Install the package as a project dependency: `pnpm add -D polydeukes`. A one-off `npx` run is
-   not enough — both surfaces load the judge from the project's own installed package.
-2. Wire the project: `pnpm exec pdks init claude-code`.
+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
 discipline-draft skill.
 4. Reopen the project when the hook changes. The generated hook is a delegator, so upgrading the
@@ -32,54 +34,84 @@ described problem into either a judged entry or a draft entry.
 
 Use this when the project is developed in Grok.
 
-1. Install the package as a project dependency: `pnpm add -D polydeukes`.
-2. Wire the project: `pnpm exec pdks init 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 under `.grok/hooks/`. When a Claude hook already exists, the Grok
-command points at that file so the host does not spawn two judges. If the tree also has
-`.claude/settings.json`, the Grok matcher follows the Claude registration that names the same
-command, because Grok collapses the two registrations only when command and matcher match.
-Generated registrations use a timeout of 60 seconds. The Grok host default is 5 seconds, and a
-timed-out hook fails open.
+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 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. A commit-surface prompt witnesses only
-that commit; it cannot authorize a blocked Grok tool call.
+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="commit-surface"></a>
-## Commit surface
+<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
 
 Use this when you want git to judge staged changes before they become history.
 
 1. Create `polydeukes.config.yaml` at the project root.
 2. Add the pre-commit hook.
-3. Run `pnpm exec pdks covenant check` when you want the same judgment on demand.
+3. Run `git diff HEAD | pnpm exec pdks covenant check --diff` when you want the same judgment
+   on demand.
 
-A minimal lefthook entry looks like this:
+A minimal lefthook entry looks like this. The `git diff` flags pin what the judge receives:
+no color codes, no external diff driver, no textconv rewrite, and the `a/`/`b/` prefixes the
+translator strips — a user's git config cannot change the observation (see the CLI reference).
 
 ```yaml
 pre-commit:
   commands:
     covenant:
       priority: 1
-      interactive: true
-      run: ./node_modules/.bin/pdks covenant check
+      run: git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff
 ```
 
 A husky hook looks like this:
 
 ```sh
 # .husky/pre-commit
-./node_modules/.bin/pdks covenant check
+git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff
 ```
 
 A plain git hook works too:
 
 ```sh
 #!/bin/sh
-./node_modules/.bin/pdks covenant check
+git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff
 ```
 
 If you use the plain hook, save it as `.git/hooks/pre-commit` and make it executable with
@@ -87,12 +119,12 @@ If you use the plain hook, save it as `.git/hooks/pre-commit` and make it execut
 For lefthook, install it with your package manager and run its hook installer after saving the YAML.
 For husky, save `.husky/pre-commit` through husky's own installer so git can find it.
 
-`adapters.git.enforce: advise` records violations as `advised`, writes diagnostics to stderr,
-and lets the commit continue. With `block`, protected-path violations and entries explicitly set
-to `enforce: block` can stop the commit. An ordinary entry still defaults to `advise`; the surface
-does not promote it. When configured and attached to a terminal, the staged path offers a witness
-prompt on `/dev/tty`. `--worktree` and `--range` report without prompting. Assembly errors remain
-exit 2 at either level.
+The judge emits exit 0 or exit 2 and never prompts. By default every break on this surface — a
+`protectedPaths` violation included — lands as a row with a diagnostic on stderr and exit 0: a
+staged gate-file change has already passed the session surface or was made by a human, and
+this surface has no valve a human could answer. Add `--enforce block` to the command when you
+want a `protectedPaths` violation or an entry set to `enforce: block` to exit 2. Whether a commit
+stops is your hook wiring: the entries above honour the exit code. Assembly errors always exit 2.
 
 <a id="witness-and-recovery"></a>
 ## Witness and recovery
@@ -100,7 +132,8 @@ exit 2 at either level.
 The witness token is the same idea on both surfaces, but the delivery is different.
 
 - On the session surface, type the token on its own first line in a conversation message.
-- On the commit surface, type the full token into the TTY prompt.
+- The change-set surface has no prompt. Its judgment reaches you as an exit code, and your hook
+  wiring decides what to do with it.
 
 The valve is consulted after the judgment returns a block. You can supply the token before an
 intentional edit; a previous failed attempt is not required. It does not change a passing verdict
@@ -114,5 +147,5 @@ cannot be loaded, reinstall the package or rebuild the workspace and try again.
 
 - `pdks explain` shows which registrations each surface assembled.
 - `.polydeukes/roi.log` records the rows that the surfaces wrote.
-- `pdks covenant check --worktree` is a good on-demand check after a task.
-- `pdks covenant check --range <base>..<head>` is the shape to use before a PR.
+- `git diff HEAD | pdks covenant check --diff` is a good on-demand check after a task.
+- `git diff <base>..<head> | pdks covenant check --diff` is the shape to use before a PR.

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
@@ -50,7 +52,7 @@ disciplines:
 
 `flattenKeys`는 번역 값이 아니라 키를 추출합니다. `equal`은 양방향으로 비교하고,
 `messageBySide`는 어느 파일에 짝이 없는 키가 있는지 알려 줍니다. 기본 강제 수준은
-`advise`입니다. 소스 파일 둘 다 존재하고 올바른 JSON이어야 합니다. 커밋 표면은 선택한
+`advise`입니다. 소스 파일 둘 다 존재하고 올바른 JSON이어야 합니다. 변경 집합 표면은 선택한
 관측 범위에서 파일을 읽고, 세션 편집에서는 바뀌는 파일의 편집 후 내용을 사용합니다.
 
 예제 프로젝트 루트에서 키가 같은 파일을 만들고 git 추적 대상으로 등록합니다.
@@ -64,7 +66,7 @@ printf '{"home":"홈"}\n' > locales/ko.json
 git add locales/en.json locales/ko.json
 git commit -m 'docs: prepare locale example'
 printf '{"home":"Home","settings":"Settings"}\n' > locales/en.json
-pnpm exec pdks covenant check --worktree
+git diff HEAD | pnpm exec pdks covenant check --diff
 ```
 
 `locale-key-parity`의 `advised` 진단에 영어에만 있는 `settings` 키가 나와야 합니다.
@@ -72,7 +74,7 @@ pnpm exec pdks covenant check --worktree
 
 ```sh
 printf '{"home":"홈","settings":"설정"}\n' > locales/ko.json
-pnpm exec pdks covenant check --worktree
+git diff HEAD | pnpm exec pdks covenant check --diff
 ```
 
 이제 키 비교 진단이 없어야 합니다. 번역 값은 서로 다르지만 키는 같습니다.
@@ -82,11 +84,66 @@ pnpm exec pdks covenant check --worktree
 git restore -- locales/en.json locales/ko.json
 ```
 
-`--worktree`는 git이 추적하지 않더라도 무시 대상이 아닌 파일을 추가된 파일로 포함합니다.
-이 예제는 수정 사례를 검사하고 쉽게 원상 복구하기 위해 기준 상태를 커밋합니다.
+`git diff HEAD`는 마지막 커밋과의 차이를 냅니다. 아직 git이 추적하지 않는 파일은
+`git add -N`을 거쳐야 diff에 나타납니다. 이 예제는 수정 사례를 검사하고 쉽게 원상 복구하기
+위해 기준 상태를 커밋합니다.
 소스 파일이 존재한다는 이유만으로 선언이 실행되지는 않습니다. 관측된 변경 중 하나
 이상이 해당 선언의 적용 범위와 일치해야 합니다.
 
+<a id="which-list"></a>
+## 어느 목록에 적는가
+
+규율 목록은 셋이고, 항목이 어느 목록에 속하는지는 소스 축이 정합니다. 기전이 정하지도 않고
+관계가 정하지도 않습니다. 같은 `companion` 기전이라도 `file` 소스 위에 서면 `disciplines`에
+있고 `changes` 위에 서면 `changeSetDisciplines`에 있습니다. 선언의 소스를 읽으면 목록이
+따라 나옵니다.
+
+| 선언이 읽는 것 | 목록 | 예 |
+|---|---|---|
+| 변경된 파일과 `file` 소스만 | `disciplines` | 파일 형상 유형들. 신규분 한정, 비가역 표식, 자기사면 금지, 통제 어휘, 이름 규약, `file` 소스 위의 동반 의무, 지문 동기, 순서 불변 |
+| 대화 기록(transcript) | `sessionDisciplines` | 이력 4종. 선행 요구, 단계 순서, 턴 근접, 사전 언명 |
+| 주체(actor) | `sessionDisciplines` | 생산자 전속, 주체 한정 |
+| 명령줄 | `sessionDisciplines` | 명령줄 금지 |
+| 스폰 기록 통로(`sidecar`) | `sessionDisciplines` | `{ sidecar: true }`를 묶는 모든 선언 |
+| `changes` | `changeSetDisciplines` | 변경 집합 위의 짝 맞춤. 함께 움직여야 하는 경로 둘 사이의 `implies` |
+
+항목은 그 소스가 가리키는 목록에 적습니다. 자리를 잘못 잡은 항목은 로드 시점 오류이고,
+메시지가 항목과 그 항목이 읽는 통로와 가야 할 목록을 함께 대므로, 본문을 그대로 옮기면
+됩니다. 규칙 자체와 오류 모양은
+[설정 참조](../reference/configuration/index.ko.md#placement-rule)에 있습니다.
+
+표면이 공급해야 할 것을 본체가 읽지 않아도 실제로는 표면에 묶이는 항목이 있습니다. 대화
+기록을 읽는 밸브(`witness`)가 달린 항목은 밸브 자신의 `extract`가 대화 기록을 묶으므로 세션
+항목이 됩니다.
+
+<a id="posture"></a>
+## 무인 실시간 표면의 기본 자세
+
+무인 실시간 표면은 터미널 앞에 사람이 없는 어댑터 훅이나 SDK 호출자입니다. 사람이 지켜보는
+자리에는 적용되지 않는 규칙 둘이 이곳에 적용됩니다.
+
+**루프가 회차 안에서 스스로 고치지 못하는 항목을 `enforce: block`으로 올립니다.** 기준은
+"되돌릴 수 없는가"가 아닙니다. 실시간 차단의 비용은 초 단위입니다. 모델이 stderr의 사유를
+읽고 다시 시도하므로 위반이 그 회차 안에서 고쳐집니다. `advise`로 두면 같은 위반이 뒤의
+검사, 곧 테스트 실행이나 CI나 리뷰어에게까지 가서 회차 하나를 쓰며 최대 45분이 듭니다.
+"무인이니 전부 차단"이라는 뜻은 아닙니다. 차단은 회피를 낳고 회피는 텔레메트리 행을 남기지
+않으므로, 루프가 손댈 수 없는 항목은 위반이라도 기록되는 `advise`에 두는 편이 낫습니다. 이
+기준은 설정 저자의 것입니다.
+
+**밸브가 없으므로 사유가 값으로 돌아옵니다.** 실시간 무인 표면에는 증인 밸브가 없습니다.
+TTY도 사람의 턴도 없고, SDK는 증인 인자를 받지 않으며 세션을 지어내지도 않습니다. 그 자리를
+대신하는 것이 사유를 데이터로 돌려주는 일입니다. `checkCovenant`는
+`{ verdict: 'blocked', reason }`을 돌려주며 `reason`은 판정기 자신의 stderr이고,
+`{ verdict: 'upheld', advisories }`는 종료 코드 0인 실행의 권고 줄을 싣습니다. 소비자는 그
+텍스트를 사람이 나중에 읽는 자리, 곧 이슈나 로그에 적고 멈춥니다. 권고 텍스트를 모델에게
+보일지도 소비자가 정합니다. 무인 루프에는 stderr 한 줄을 읽을 사람이 없으므로, 호출자가
+전달해야 권고가 소비됩니다. 판정 결과의 모양은
+[`@polydeukes/sdk-ts` 참조](../reference/packages/sdk-ts.ko.md)에 있습니다.
+
+SDK 자신의 기본값은 실행 전체에 대한 `enforce: 'block'`이며, 이것은 표면의 강제 수준이지
+항목의 것이 아닙니다. 보호 경로와 `enforce: block` 항목이 호출을 멈추고, 나머지 위반은
+`advised`로 기록됩니다. 두 어댑터도 같은 방식으로 판정기를 스폰합니다.
+
 <a id="when-to-draft"></a>
 ## 선언 대신 초안으로 남길 때
 
@@ -110,7 +167,7 @@ disciplines:
 ## 한 번은 실제로 판정해 보기
 
 설정을 저장한 뒤에는 필요한 증거를 공급할 수 있는 판정 경로로 위반과 정상 사례를 모두
-검사합니다. `pdks covenant check --worktree`는 현재 작업 트리의 변경을 판정하고,
+검사합니다. `git diff HEAD | pdks covenant check --diff`는 현재 작업 트리의 변경을 판정하고,
 `pdks explain`은 선언과 초안의 등록 상태를 보여 줍니다. 위 번역 예제처럼 한쪽 파일만
 바꾼 경우와 양쪽 키를 맞춘 경우를 비교하세요.
 

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
@@ -50,7 +52,7 @@ disciplines:
 
 `flattenKeys` extracts keys, not translation values. `equal` compares both directions and
 `messageBySide` reports which file has an unmatched key. The default enforcement is `advise`.
-Both source files must exist and contain valid JSON. The commit surface reads them from the
+Both source files must exist and contain valid JSON. The change-set surface reads them from the
 chosen observation; a session edit uses that edit's proposed new contents for the file it changes.
 
 From the example project's root, prepare matching tracked files. The commit below requires your
@@ -63,7 +65,7 @@ printf '{"home":"홈"}\n' > locales/ko.json
 git add locales/en.json locales/ko.json
 git commit -m 'docs: prepare locale example'
 printf '{"home":"Home","settings":"Settings"}\n' > locales/en.json
-pnpm exec pdks covenant check --worktree
+git diff HEAD | pnpm exec pdks covenant check --diff
 ```
 
 Expect an `advised` diagnostic for `locale-key-parity` naming `settings` as present only in English.
@@ -71,7 +73,7 @@ The command still exits 0. Fix the mismatch and run the same observation again:
 
 ```sh
 printf '{"home":"홈","settings":"설정"}\n' > locales/ko.json
-pnpm exec pdks covenant check --worktree
+git diff HEAD | pnpm exec pdks covenant check --diff
 ```
 
 The parity diagnostic should disappear. The values differ intentionally; the keys now match.
@@ -81,10 +83,66 @@ Restore the two example files to their committed baseline when finished:
 git restore -- locales/en.json locales/ko.json
 ```
 
-`--worktree` also includes untracked, non-ignored files as additions. This example commits a
-baseline to exercise modifications and make cleanup predictable. A declaration does not run
+`git diff HEAD` reports changes against the last commit, so an untracked file needs `git add -N`
+before it appears in the diff. This example commits a baseline to exercise modifications and make
+cleanup predictable. A declaration does not run
 merely because its source exists: at least one observed change must match its scope.
 
+<a id="which-list"></a>
+## Which list does it go in
+
+There are three discipline lists, and the source axis decides which one an entry belongs to.
+The mechanism does not decide it and the relation does not decide it: the same `companion`
+mechanism sits in `disciplines` when it stands over `file` sources, and in
+`changeSetDisciplines` when it stands over `changes`. Read the declaration's sources and the
+list follows.
+
+| The declaration reads | List | Examples |
+|---|---|---|
+| the changed file and `file` sources only | `disciplines` | the file-shaped types — added-only, one-way markers, self-absolution bans, controlled vocabulary, naming, companion over a `file` source, fingerprint sync, monotonic order |
+| the transcript | `sessionDisciplines` | the four history types — precedent, phase order, turn locality, stated ground |
+| the actor | `sessionDisciplines` | producer-owned, actor scope |
+| the command line | `sessionDisciplines` | forbidden command |
+| the spawn-record channel (`sidecar`) | `sessionDisciplines` | any declaration binding `{ sidecar: true }` |
+| `changes` | `changeSetDisciplines` | pairing over a change set — `implies` between two paths that must move together |
+
+Write the entry in the list its sources point at. A misplaced entry is a load-time error that
+names the entry, the channels it reads, and the list it belongs in, so the fix is to move the
+body unchanged. The rule itself and the error shapes are in [the configuration
+reference](../reference/configuration/index.md#placement-rule).
+
+An entry can also read nothing a surface has to supply and still be surface-bound in practice:
+a valve (`witness`) that reads the transcript makes its entry a session entry, because the
+valve's own `extract` binds the transcript.
+
+<a id="posture"></a>
+## Posture on an unattended real-time surface
+
+An unattended real-time surface is an adapter hook or an SDK caller with no human at the
+terminal. Two rules apply there that do not apply where a person is watching.
+
+**Promote an entry to `enforce: block` when the loop cannot fix it inside the turn.** The
+criterion is not "is this irreversible". A real-time block costs seconds: the model reads the
+reason on stderr and retries, so the violation is corrected within the turn. Left at `advise`,
+the same violation travels to a later check — a test run, CI, a reviewer — and costs a whole
+turn, up to 45 minutes. This is not "block everything because nobody is watching": blocking
+produces avoidance, and avoidance leaves no telemetry row, so an entry the loop cannot act on
+belongs at `advise` where its break is at least recorded. The criterion is the config author's.
+
+**The reason comes back as a value, because there is no valve.** A real-time unattended
+surface has no witness valve: there is no TTY and no human turn, and the SDK takes no witness
+argument and invents no session. What stands in its place is the reason travelling as data.
+`checkCovenant` returns `{ verdict: 'blocked', reason }` where `reason` is the judge's own
+stderr, and `{ verdict: 'upheld', advisories }` carries the advisory lines of an exit-0 run.
+The consumer writes that text where a person reads it later — an issue, a log — and stops.
+Whether the model sees the advisory text is the consumer's decision too: an unattended loop has
+no reader for a stderr line, so advise is only consumed if the caller passes it on. The
+[`@polydeukes/sdk-ts` reference](../reference/packages/sdk-ts.md) has the verdict shapes.
+
+The SDK's own default is `enforce: 'block'` for the run, which is the surface's level, not an
+entry's: protected paths and `enforce: block` entries stop the call, and every other break is
+recorded as `advised`. Both adapters spawn the judge the same way.
+
 <a id="when-to-draft"></a>
 ## When to draft instead of declaring
 
@@ -109,7 +167,7 @@ verdict or telemetry. It is still part of the config, so the file remains loadab
 
 After you save the config, run the judgment path that can actually see it.
 
-- `pdks covenant check --worktree` shows the same entry against the current tree.
+- `git diff HEAD | pdks covenant check --diff` shows the same entry against the current tree.
 - `pdks explain` shows the registration and whether it is a declare or a draft.
 - A one-sided edit to `locales/en.json` or `locales/ko.json` is a good smoke test for the pairing
 example.