polydeukes 0.6.1 → 0.7.1

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는 세션 표면을 배선하고, 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/adapter-claude-code`. 일회성 `npx` 실행만으로는 부족합니다. 두 표면 모두
+   프로젝트에 설치된 패키지에서 판정기를 불러옵니다.
+2. 프로젝트 루트에서 배선합니다. `pnpm exec pdks-claude-code init`. 이 실행 파일은 어댑터가
+   제공하며, 먼저 `pdks init`으로 초기 파일을 만든 뒤 Claude Code 등록 산출물을 씁니다.
 3. 생성된 훅, 병합된 설정, 초기 설정 파일, 문서 안내와 `discipline-draft` 스킬을 확인합니다.
 4. 훅이 바뀌면 프로젝트를 다시 엽니다. 생성된 훅은 패키지에 판정을 위임하므로 패키지를
    갱신할 때 훅 파일까지 다시 쓸 필요는 없습니다.
@@ -29,54 +31,55 @@ Claude Code에서 AI 파트너와 함께 개발할 때 씁니다.
 
 Grok에서 개발할 때 씁니다.
 
-1. 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes`.
-2. 프로젝트를 배선합니다. `pnpm exec pdks init grok`.
+1. 두 패키지를 프로젝트 의존성으로 설치합니다. `pnpm add -D polydeukes @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="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 +87,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 +101,8 @@ husky 설치기로 `.husky/pre-commit`을 저장하세요.
 증인 토큰은 두 표면에서 같은 뜻이지만 전달 방식은 다릅니다.
 
 - 세션 표면에서는 대화 메시지 첫 줄에 토큰만 단독으로 넣습니다.
-- 커밋 표면에서는 TTY 프롬프트에 전체 토큰을 입력합니다.
+- 변경 집합 표면에는 프롬프트가 없습니다. 판정은 종료 코드로 전달되고, 그것으로 무엇을 할지는
+  훅 배선이 정합니다.
 
 밸브는 판정 결과가 차단일 때 확인합니다. 의도한 편집 전에 토큰을 입력해도 되며, 먼저
 실패하는 요청을 보낼 필요는 없습니다. 정상 판정은 바꾸지 않고, 현재 Grok 대화 기록
@@ -111,5 +116,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

@@ -3,20 +3,22 @@
 **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.
+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 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.
+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,54 @@ 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 both packages as project dependencies: `pnpm add -D polydeukes @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 both session adapters 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="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 +89,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 +102,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 +117,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

@@ -50,7 +50,7 @@ disciplines:
 
 `flattenKeys`는 번역 값이 아니라 키를 추출합니다. `equal`은 양방향으로 비교하고,
 `messageBySide`는 어느 파일에 짝이 없는 키가 있는지 알려 줍니다. 기본 강제 수준은
-`advise`입니다. 소스 파일 둘 다 존재하고 올바른 JSON이어야 합니다. 커밋 표면은 선택한
+`advise`입니다. 소스 파일 둘 다 존재하고 올바른 JSON이어야 합니다. 변경 집합 표면은 선택한
 관측 범위에서 파일을 읽고, 세션 편집에서는 바뀌는 파일의 편집 후 내용을 사용합니다.
 
 예제 프로젝트 루트에서 키가 같은 파일을 만들고 git 추적 대상으로 등록합니다.
@@ -64,7 +64,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 +72,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 +82,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 +165,7 @@ disciplines:
 ## 한 번은 실제로 판정해 보기
 
 설정을 저장한 뒤에는 필요한 증거를 공급할 수 있는 판정 경로로 위반과 정상 사례를 모두
-검사합니다. `pdks covenant check --worktree`는 현재 작업 트리의 변경을 판정하고,
+검사합니다. `git diff HEAD | pdks covenant check --diff`는 현재 작업 트리의 변경을 판정하고,
 `pdks explain`은 선언과 초안의 등록 상태를 보여 줍니다. 위 번역 예제처럼 한쪽 파일만
 바꾼 경우와 양쪽 키를 맞춘 경우를 비교하세요.
 

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

@@ -50,7 +50,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 +63,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 +71,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 +81,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 +165,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.