polydeukes 0.6.1 → 0.7.1

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

@@ -2,85 +2,82 @@
 
 [English](./init.md) · **한국어**
 
-프로젝트를 세션 표면에 연결합니다. `claude-code`와 `grok` 두 형식 모두 대상 프로젝트에서
-설치된 패키지를 찾을 수 있는지 먼저 검사합니다. 그 검사가 끝나기 전에는 파일을 쓰지 않습니다.
+`pdks init`은 에이전트와 무관한 초기 파일을 만듭니다. 설정 파일과 텔레메트리 제외 항목
+둘입니다. 이 명령은 어느 에이전트도 알지 못합니다. 세션 표면 등록은 그 에이전트의 어댑터가
+맡는 별도 명령입니다. Claude Code는 `pdks-claude-code init`, Grok는 `pdks-grok init`입니다.
 
 <a id="init-syntax"></a>
 ## 구문
 
 ```sh
-pdks init claude-code
-pdks init grok
+pdks init
 ```
 
-두 형식 모두 다시 실행할 수 있습니다. 이미 있는 산출물은 보존하고 `skipped`로 보고합니다.
-사전 검사에 실패하면 파일을 쓰지 않고 종료 코드 `2`를 반환합니다.
+다른 인자를 주면 사용법을 출력하고 종료 코드 `2`를 반환합니다. 이미 있는 산출물은 보존하고
+`skipped`로 보고하며, 사전 검사에 실패하면 파일을 쓰지 않고 종료 코드 `2`를 반환합니다.
 
 <a id="init-common"></a>
-## 공통 사전 검사와 초기 파일
+## `pdks init` — 초기 파일
 
-설치 순서는 다음과 같습니다.
+이 명령의 순서는 다음과 같습니다.
 
 1. 대상 프로젝트에서 `polydeukes`를 찾을 수 있는지 확인합니다.
 2. 공통 설정과 텔레메트리 제외 항목을 만듭니다.
-3. 표면별 등록 파일을 추가합니다.
 
-두 설치기가 공통으로 만드는 것은 `polydeukes.config.yaml`과 `.gitignore`의 `.polydeukes/`
-항목입니다. 설정 파일에는 언어 블록, 보호 목록, 증인 블록, 주석으로 된 규율 예제가 있습니다.
-완성된 정책이 아니라 프로젝트에 맞춰 고칠 출발점입니다.
+어느 표면이든 여기서 출발합니다.
+
+- `polydeukes.config.yaml`
+- `.gitignore`의 `.polydeukes/` 항목
+
+설정 파일에는 언어 블록, 보호 목록, 증인(witness) 블록, 주석으로 된 규율(discipline) 예제가
+있습니다. 완성된 정책이 아니라 프로젝트에 맞춰 고칠 출발점입니다.
 
 <a id="init-claude-code"></a>
-## `pdks init claude-code`
+## Claude Code — `pdks-claude-code init`
+
+Claude Code 세션 표면은
+[`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.ko.md)가 설치합니다. 이
+어댑터에는 자체 실행 파일이 있습니다.
 
-Claude Code 세션 표면에 필요한 파일은 다음과 같습니다.
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npx pdks-claude-code init
+```
+
+이 명령은 먼저 `pdks init`으로 초기 파일을 만든 뒤 Claude Code 등록 산출물을 씁니다.
 
 - `.claude/hooks/covenant-pretooluse.mjs`
 - `.claude/settings.json`
 - `.claude/rules/polydeukes.md`
 - `.claude/skills/discipline-draft/SKILL.md`
-- `polydeukes.config.yaml`
-- `.gitignore`
 
-훅은 `polydeukes/claude-code`에 판정을 맡깁니다. 설정에는 PreToolUse 등록을 병합하고,
-문서 안내 파일은 AI 파트너가 웹 검색 대신 `pdks docs`를 쓰도록 알려 줍니다.
-스킬은 설명된 규율 문제를 설정 항목으로 바꾸는 절차를 제공합니다.
+산출물별 동작은 [표면 연결하기](../../how-to/connect-surfaces.ko.md#claude-code)에 있습니다.
 
-기존 훅, 설정 데이터, 문서 안내, 스킬 파일은 보존합니다. 호스트 설정에는 필요한 등록을
-병합하고 `.gitignore`에는 빠진 항목만 추가합니다. 아래 설명처럼 기존 Grok 등록을 조정할
-수도 있으므로 재실행이 언제나 아무것도 바꾸지 않는 것은 아닙니다.
+<a id="init-grok"></a>
+## Grok — `pdks-grok init`
 
-패키지 버전을 올려도 사용자가 수정한 스킬은 덮어쓰지 않습니다. 임시 프로젝트에서 새 사본을
-만들어 기존 파일과 비교한 뒤, 백업하고 필요한 부분만 반영하세요. 강제로 다시 만들려고
-작업 중인 프로젝트의 스킬을 지우지는 마세요.
+Grok 세션 표면은
+[`@polydeukes/adapter-grok`](../packages/adapter-grok.ko.md)가 설치합니다. 이
+어댑터에는 자체 실행 파일이 있습니다.
 
-<a id="init-grok"></a>
-## `pdks init grok`
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-grok
+npx pdks-grok init
+```
 
-Grok 전용 프로젝트에는 다음 파일을 만듭니다.
+이 명령은 먼저 `pdks init`으로 초기 파일을 만든 뒤 Grok 등록 산출물을 씁니다.
 
 - `.grok/hooks/covenant-pretooluse.mjs`
 - `.grok/hooks/covenant-pretooluse.json`
-- `polydeukes.config.yaml`
-- `.gitignore`
-
-Claude Code 형식과의 차이는 다음과 같습니다.
-
-- `.claude/` 파일을 만들지 않고 Grok 훅 JSON에 등록합니다.
-- Claude 위임 훅이 이미 있으면 새 훅을 만들지 않고 Grok JSON에서 기존 파일을 지정합니다.
-- 새 등록의 제한 시간은 60초입니다. Grok 호스트 기본값은 5초이며, 훅 실행이 시간 초과로
-  끝나면 해당 호출을 차단하지 않습니다(fail-open). Claude 설정에 같은 명령이 등록돼 있으면
-  Grok의 매칭 조건도 맞춰
-  명령과 조건이 모두 같게 만듭니다.
-- 어느 설치기를 다시 실행하든, 설치기가 만든 Grok 훅 명령을 기존 Claude 파일로 바꾸고
-  매칭 조건을 맞출 수 있습니다. 사용자가 다른 곳을 지정한 명령은 그대로 두며 기존 제한
-  시간도 유지합니다.
-- 나중에 Claude 설정을 제거했다면 Grok JSON을 다시 만들어 Grok 기본 매칭 조건을 복원하세요.
-  사용자 설정부터 백업해야 합니다. 변경 뒤에는 Grok의 Hooks 탭을 다시 불러오거나 새 세션을
-  시작합니다.
-
-Grok는 Claude 세션 증인 밸브가 요구하는 인간 메시지 증거를 제공하지 않습니다.
+
+`.claude/` 파일을 만들거나 고치지 않습니다. 새 등록의 제한 시간은 60초입니다. Grok 호스트
+기본값은 5초이며, 훅 실행이 시간 초과로 끝나면 해당 호출을 차단하지 않습니다(fail-open).
+두 세션 어댑터를 한 프로젝트에 함께 설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.
+
+Grok는 Claude 세션 증인(witness) 밸브가 요구하는 인간 메시지 증거를 제공하지 않습니다.
 대화 기록은 Claude JSONL이 아니라 ACP `updates.jsonl`입니다.
-[Grok 복구 안내](../../troubleshooting.ko.md#grok-witness)를 참고하세요.
+[Grok 복구 안내](../../troubleshooting.ko.md#grok-witness)를 참고하세요. 산출물별 동작은
+[표면 연결하기](../../how-to/connect-surfaces.ko.md#grok)에 있습니다.
 
 <a id="init-results"></a>
 ## 결과와 실패 조건
@@ -103,16 +100,19 @@ Grok는 Claude 세션 증인 밸브가 요구하는 인간 메시지 증거를
 ## 예제
 
 ```sh
-pdks init claude-code
-pdks init grok
+pdks init
+npx pdks-claude-code init
+npx pdks-grok init
 ```
 
-설치기는 CLI 명령입니다. `polydeukes`나 `polydeukes/claude-code` 계약의 공개 심볼이
-아닙니다.
+설치기는 CLI 명령입니다. `polydeukes` 계약의 공개 심볼이 아닙니다.
 
 <a id="init-see-also"></a>
 ## 함께 보기
 
+- [`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.ko.md) — Claude Code 설치
+단위와 그 실행 파일
+- [`@polydeukes/adapter-grok`](../packages/adapter-grok.ko.md) — Grok 설치 단위와 그 실행 파일
 - [`pdks docs`](./docs.ko.md)
 - [`pdks explain`](./explain.ko.md)
 - [설정 참조](../configuration/index.ko.md)

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

@@ -2,31 +2,29 @@
 
 **English** · [한국어](./init.ko.md)
 
-`pdks init` wires a project into the session surface. The command has two forms: `claude-code` and
-`grok`. Both start with the same preflight: the package must resolve from the target project before
-anything is written.
+`pdks init` creates the agent-neutral project scaffold: the config file and the telemetry ignore
+line. It knows no agent. Registering a session surface is a separate command owned by that
+agent's adapter — `pdks-claude-code init` for Claude Code, and `pdks-grok init` for Grok.
 
 <a id="init-syntax"></a>
 ## Syntax
 
 ```sh
-pdks init claude-code
-pdks init grok
+pdks init
 ```
 
-Both forms are idempotent. Existing artifacts are left in place and reported as skipped. A preflight
-failure writes nothing and exits `2`.
+Any other argument prints usage and exits `2`. The command is idempotent: existing artifacts are
+left in place and reported as skipped, and a preflight failure writes nothing and exits `2`.
 
 <a id="init-common"></a>
-## Shared preflight and scaffold
+## `pdks init` — the scaffold
 
-The installer does three things in order:
+The command does two things in order:
 
 1. Resolve `polydeukes` from the target project.
 2. Create the shared project-side scaffold: config and telemetry ignore line.
-3. Add the surface-specific registration artifacts.
 
-The shared scaffold is the same for both installers:
+The scaffold is the same one every surface starts from:
 
 - `polydeukes.config.yaml`
 - `.gitignore` with `.polydeukes/`
@@ -35,64 +33,51 @@ The config file starts with the language block, a protection list, a witness blo
 discipline examples. It is a starter policy, not a complete project policy.
 
 <a id="init-claude-code"></a>
-## `pdks init claude-code`
+## Claude Code — `pdks-claude-code init`
 
-This form installs the Claude Code session surface.
+The Claude Code session surface is installed by
+[`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.md), which ships its own bin:
 
-Created artifacts:
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npx pdks-claude-code init
+```
+
+That command runs `pdks init` for the scaffold, then writes the Claude Code registration
+artifacts:
 
 - `.claude/hooks/covenant-pretooluse.mjs`
 - `.claude/settings.json`
 - `.claude/rules/polydeukes.md`
 - `.claude/skills/discipline-draft/SKILL.md`
-- `polydeukes.config.yaml`
-- `.gitignore`
-
-What each artifact does:
-
-- The hook file is a delegator that imports `polydeukes/claude-code`.
-- The settings file merges a PreToolUse registration instead of replacing the whole file.
-- The discovery file tells the AI partner to use `pdks docs` instead of web search.
-- The skill file turns a described discipline problem into a config entry.
-- The config and ignore line come from the shared scaffold.
 
-Existing hook, config, discovery, and skill files are preserved. Settings registrations are
-merged and the ignore entry is appended if absent. Re-running can also reconcile a generated
-Grok registration as described below; it is not an unconditional no-op.
-
-Package upgrades do not overwrite a customized skill. Generate a fresh copy in a disposable
-project, compare it with the existing file, and merge the selected changes after taking a backup.
-Do not delete the working project's skill merely to force regeneration.
+Details and the per-artifact behaviour are in
+[Connect the surfaces](../../how-to/connect-surfaces.md#claude-code).
 
 <a id="init-grok"></a>
-## `pdks init grok`
+## Grok — `pdks-grok init`
+
+The Grok session surface is installed by
+[`@polydeukes/adapter-grok`](../packages/adapter-grok.md), which ships its own bin:
 
-This form installs the Grok session surface.
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-grok
+npx pdks-grok init
+```
 
-Created artifacts:
+That command runs `pdks init` for the scaffold, then writes the Grok registration artifacts:
 
 - `.grok/hooks/covenant-pretooluse.mjs`
 - `.grok/hooks/covenant-pretooluse.json`
-- `polydeukes.config.yaml`
-- `.gitignore`
-
-What differs from the Claude Code form:
-
-- It does not create `.claude/` files.
-- It writes a Grok hook JSON registration instead of `.claude/settings.json`.
-- If a Claude delegator already exists, the Grok JSON names it instead of creating another
-delegator.
-- Generated registrations use a timeout of 60 seconds. The Grok host default is 5 seconds, and a
-  timed-out hook fails open. When Claude settings register the same command, the Grok matcher
-  follows that registration so command and matcher agree.
-- Re-running either installer can retarget a generated Grok-delegator command to the existing
-  Claude file and reconcile its matcher. A custom command is left alone; an existing timeout stays.
-- If you later remove Claude settings, regenerate the Grok JSON to restore the Grok-native matcher.
-  Back up custom settings first. Reload Grok's Hooks tab or start a new session after changes.
+
+It does not create or rewrite `.claude/` files. Generated registrations use a timeout of 60
+seconds. The Grok host default is 5 seconds, and a timed-out hook fails open. Installing both
+session adapters in one project can run the judge twice per call.
 
 Grok does not supply the human-message evidence required by the Claude session witness valve.
 The session log is ACP `updates.jsonl`, not Claude's JSONL.
-See [Grok recovery](../../troubleshooting.md#grok-witness).
+See [Grok recovery](../../troubleshooting.md#grok-witness). Details are in
+[Connect the surfaces](../../how-to/connect-surfaces.md#grok).
 
 <a id="init-results"></a>
 ## Results and failure conditions
@@ -114,16 +99,19 @@ filesystem problem, and rerun rather than assuming every failed installation lef
 ## Examples
 
 ```sh
-pdks init claude-code
-pdks init grok
+pdks init
+npx pdks-claude-code init
+npx pdks-grok init
 ```
 
-The installer is a CLI command. It is not a symbol on the `polydeukes` or
-`polydeukes/claude-code` contract.
+The installers are CLI commands. They are not symbols on the `polydeukes` contract.
 
 <a id="init-see-also"></a>
 ## See also
 
+- [`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.md) — the Claude Code
+install unit and its bin.
+- [`@polydeukes/adapter-grok`](../packages/adapter-grok.md) — the Grok install unit and its bin.
 - [`pdks docs`](../packages/polydeukes.md#polydeukes-bin) — the installed documentation reader lives
 in the same package.
 - [`pdks explain`](./explain.md)

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

@@ -53,61 +53,34 @@ protectedPaths:
 
 ```yaml
 adapters:
-  git:
-    enforce: advise
-    protectedPaths:
-      - 'packages/core/src'
+  example:
+    someKey: '예시 어댑터가 정의하는 값'
 ```
 
-<a id="adapters-git"></a>
-### `adapters.git`, git 커밋 어댑터
-
-| 키 | 값 | 기본값 | 의미 |
-|---|---|---|---|
-| `enforce` | `block` \| `advise` | `block` | 커밋 표면의 강제 수준 |
-| `protectedPaths` | 문자열 배열 | `[]` | 커밋 표면만 판정하는 가산 관측 범위 |
-
-- **`block`**은 차단 수준으로 판정하는 약속을 깨는 스테이징 변경이 있으면 커밋을
-  차단합니다(exit 2). 보호 경로와 `enforce: block`으로 승격한 항목이 여기에 해당합니다.
-  일반 항목은 이 설정 아래에서도 자체 기본값 `advise`를 유지합니다(아래 `enforce` 참조). 통과하는
-  길은 증인(witness) 밸브뿐입니다. 사람이 TTY 프롬프트에 토큰 전체를 입력해야 하고,
-  프롬프트는 무엇을 증언하는지 적습니다. 깨진 등록과 걸린 항목, 그리고 이 한 번의 답이
-  커밋 전체를 덮는다는 사실입니다.
-  네임스페이스가 없어도, `adapters` 맵이 없어도, `enforce` 키가 없어도 전부 `block`으로
-  동작합니다. 키를 적지 않는 것이 곧 가장 엄격한 강제 수준의 선택입니다.
-- **`advise`**는 커밋 표면에서 위반을 기록하되 작업을 차단하지 않게 합니다. 스테이징 변경에 내려진 판정은
-  `advised` 텔레메트리 이벤트로 기록되고 커밋은 진행되며(exit 0), stderr에 권고 한 줄이
-  남습니다. TTY 프롬프트는 표시하지 않습니다. 판정 기준은 유지하되 위반 시 차단하지 않는 것입니다. 판정 자체가
-  불가능한 실행(설정 없음·무효, 판정 본체 해석 불가)은 어느 강제 수준에서든 exit 2로
-  차단합니다.
-
-**여기의 `protectedPaths`는 가산 범위입니다.** 커밋 표면은 최상위 `protectedPaths`와 이
-목록의 합집합을 판정합니다. 공통 목록을 앞에 두고 이어 붙여 하나로 정규화하므로 철자와
-중복 제거 규칙이 양쪽에 동일하게 적용됩니다. 세션 표면은 이 목록을 읽지 않습니다. 이
-목록에는 세션에서 편집해도 되지만 커밋할 때는 보호해야 하는 경로를 적습니다. 판정기 소스를 여기에 둘 수 있습니다. 강제
-수준과 마찬가지로 추가 범위도 관측자가 정합니다. 공통 목록에서 경로를 빼는 설정은 없습니다.
-이 목록으로 보호 범위를 넓힐 수는 있지만 기존 범위를 줄일 수는 없습니다.
-
-세션 표면(편집 시점 훅)에는 강제 수준 설정이 없습니다. 그곳에서 차단하는 것은 판정 사슬
+**`protectedPaths`는 두 표면이 함께 쓰는 목록 하나입니다.** 변경 집합 표면에만 더해지는 목록도,
+설정의 표면 단위 강제 수준 키도 없습니다. 변경 집합 표면은 세션 표면과 같은 정규화 목록을
+판정합니다. 위반은 세션 표면에서 종료 코드 2이고, 변경 집합 표면에서는 검사를 `--enforce block`으로
+실행하지 않는 한 종료 코드 0에 `advised`로 기록됩니다. 판정기가 내는 것은 그 종료 코드뿐이며
+커밋을 멈출지는 사용자의 훅 배선이 정합니다. 그래서 텔레메트리 행은 판정 결과만 기록하고
+커밋이 진행됐는지는 기록하지 않습니다. 훅 배선이 종료 코드를 무시해 커밋이 진행돼도
+`blocked` 행은 그대로 남습니다.
+
+세션 표면(편집 시점 훅)에도 강제 수준 설정이 없습니다. 그곳에서 차단하는 것은 판정 사슬
 자신의 보호입니다. 도구 축과 셸 축의 `protectedPaths` 변경과 언급, 세션 대화 기록, 판정할
 수 없는 조립(설정 없음·무효, 빌드되지 않은 판정기, 파싱할 수 없는 페이로드, 답하지 못한
 라우팅), 그리고 `enforce: block`으로 승격한 항목입니다. 그 밖의 모든 규율 항목은
 위반 시 `advised`로 기록합니다.
 
-**세션을 읽는 선언은 공급 정책이 `pass`일 때 커밋 표면에서 판정을 건너뜁니다.** 커밋에는 들여다볼 세션이
-없으므로, `sources`가 대화 기록(transcript)을 묶는 선언 — `precedent` · `phase-order` ·
-`turn-locality` · `stated-ground` 항목 — 은 그곳에서 판정할 수 없습니다. 커밋이 지닐 수 없는
-증거를 요구하면 적용 범위에 해당하는 커밋이 모두 차단돼 정상 작업도 진행할 수 없습니다.
-선언에 `supply: { session: 'pass' }`를 지정하면 이 부재를 허용합니다. 스테이징한 변경이 적용
-범위에 해당하면 사유 `supply-pass`와 함께 `skipped`를 기록하고 이 선언으로 커밋을 차단하지 않습니다. 기록에는 항목의
-`id`와 판정했을 변경이 함께 담기므로 판정하지 못한 항목을 기록에서 구별할 수 있습니다.
-이 기록은 **변경이 항목의 적용 범위에 해당할 때만** 남습니다. `command`를 적용 범위의
-소스로 쓰는 선언은 기록을 남기지 않습니다. 스테이징한 변경에는 명령줄이 없어 그 선언의
-관측 대상이 되지 않기 때문입니다.
-
-세션 표면이 읽을 대화 기록을 갖지 못했을 때의 처분과 같습니다. 다만 그 선언의 `supply`가
-`pass`일 때입니다. 정책이 없으면 없는 소스는 판정 불가(exit 2)이지, 자동 건너뛰기가
-아닙니다.
+**선언은 자기 통로를 관측하는 표면에만 닿습니다.** 대화 기록(transcript)을 읽는 선언은
+`sessionDisciplines`에 적히고 변경 집합에 대해서는 컴파일되지 않으며, `changes`를 읽는 선언은
+`changeSetDisciplines`에 적히고 호출 하나에 대해서는 컴파일되지 않습니다. 세 목록과 항목을
+그중 하나에 놓는 규칙은 [규율 목록 셋](#three-lists)에 있습니다.
+
+표면이 등록은 하되 호스트가 증명하지 못하는 통로는 여전히 선언의 `supply` 정책이 처리합니다.
+세션을 싣지 않는 호스트(Grok 어댑터)에서는 `sources: { session: { transcript: true } }` 항목의
+소스가 없는 상태가 되고, `supply: { session: 'pass' }`가 사유 `supply-pass`와 함께 `skipped`를
+기록하며 호출을 지나가게 합니다. 이 정책이 없으면 없는 소스는 판정 불가(exit 2)이지 자동
+건너뛰기가 아닙니다.
 
 <a id="telemetry"></a>
 ## `telemetry`
@@ -174,10 +147,136 @@ covenant witness
 AI도 증언을 위조할 수 없습니다. 증언으로 통과한 판정은 조용히 사라지지 않고 `witnessed`로
 기록됩니다.
 
+<a id="three-lists"></a>
+## 규율 목록 셋
+
+규율은 세 목록 가운데 하나에 적으며, 어느 목록인지는 저자가 고르는 것이 아니라 선언 자체가
+정하는 사실입니다. 선언은 자기가 읽는 증거 통로(channel)를 문법 안에서 이름 짓고, 표면마다
+관측하는 통로가 다르므로, 목록은 그 통로에서 따라 나옵니다.
+
+| 목록 | 판정하는 표면 | 그 목록의 선언이 읽는 것 |
+|---|---|---|
+| `disciplines` | 두 표면 모두 | 변경된 파일 자신(`target.path` · `pre` · `post` · `state`)과 `file` 소스뿐입니다. 초안(draft)도 여기에 적습니다 |
+| `sessionDisciplines` | 세션 표면(session surface)만 | `command` · `transcript` · `sidecar` 통로 · `actor` 가운데 하나 이상을 읽고 `changes`는 읽지 않습니다 |
+| `changeSetDisciplines` | 변경 집합 표면(change-set surface)만 | `changes`를 읽고 세션 통로는 읽지 않습니다 |
+
+세션 표면은 호스트가 실행 전에 관측한 호출 하나입니다. 어댑터 훅이거나, 입력 IR로 SDK를
+부르는 프로그램입니다. 이 표면은 명령줄과 대화 기록(transcript), 스폰 기록 통로, 주체(actor)를
+싣고 끝난 변경 집합은 싣지 않습니다. 변경 집합 표면은 어떤 생산자가 끝낸 변경 집합을 판정하는
+`pdks covenant check --diff`입니다. 이 표면은 `changes`를 싣고 명령줄과 대화 기록과 주체는
+싣지 않습니다.
+
+<a id="channel-to-list"></a>
+### 통로와 목록의 대응
+
+통로마다 선언에 나타나는 구문 자리가 정해져 있고, 로더는 그 자리를 읽어 목록을 유도합니다.
+
+| 통로 | 선언에 나타나는 모양 | 목록 |
+|---|---|---|
+| `transcript` | `sources: { session: { transcript: true } }` | `sessionDisciplines` |
+| `channel` | `sources: { spawns: { sidecar: true } }` | `sessionDisciplines` |
+| `command` | `scope: { source: 'command' }`, 또는 어느 파이프라인의 `{ op: 'source', of: 'command' }` | `sessionDisciplines` |
+| `actor` | 어느 파이프라인의 `{ op: 'source', of: 'actor' }` | `sessionDisciplines` |
+| `changes` | 어느 파이프라인의 `{ op: 'source', of: 'changes' }` | `changeSetDisciplines` |
+| 다섯 가운데 없음 | 선언이 변경된 파일과 `file` 소스만 읽습니다 | `disciplines` |
+
+`witness` 블록 자신의 `extract`도 본체와 함께 훑으므로, 대화 기록을 읽는 밸브가 달린 항목은
+다른 대화 기록 독자와 마찬가지로 `sessionDisciplines`에 들어갑니다.
+
+<a id="placement-rule"></a>
+### 배치 규칙
+
+`disciplines`에는 다섯 통로를 하나도 묶지 않는 항목과 초안 전부가 들어갑니다.
+`sessionDisciplines`에는 세션 통로를 하나 이상 묶고 `changes`는 묶지 않는 항목이 들어갑니다.
+`changeSetDisciplines`에는 `changes`를 묶고 세션 통로는 묶지 않는 항목이 들어갑니다. 그 밖은
+로드 시점에 두 표면 모두에서 `ConfigValidationError`이고, 메시지가 항목과 그 항목이 읽는
+통로와 가야 할 목록을 함께 댑니다.
+
+```text
+disciplines[7] ('merge-is-the-users-call') reads transcript, command: it belongs in sessionDisciplines
+```
+
+댈 행선지가 없는 모양이 둘 있습니다. `changes`와 세션 통로를 함께 묶는 선언은 어느 표면도
+그 둘을 한 번에 관측하지 못하므로 그대로 거부됩니다.
+
+```text
+sessionDisciplines[2] ('pairs-across-a-session') reads transcript, changes: no surface observes both changes and a session channel
+```
+
+초안은 선언을 갖지 않아 아무 통로도 묶지 않으므로 `disciplines`에 속하고, 표면 목록 어느
+쪽에 적은 초안이든 `a draft belongs in disciplines`로 거부됩니다.
+
+항목 id는 세 목록과 메타 약속 라벨 셋(`self-mod` · `shell-mod` · `transcript-mod`)에 걸쳐
+유일합니다. 텔레메트리 라벨 공간이 하나이고, `pdks explain`을 비롯한 라벨 기준 판독기는
+라벨만으로 항목을 찾기 때문입니다.
+
+<a id="lists-in-practice"></a>
+### 표면마다 무엇을 컴파일하는가
+
+표준 입력으로 입력 IR을 읽는 `pdks covenant check`는 `disciplines` 다음에
+`sessionDisciplines`를 컴파일하고, 같은 명령에 `--diff`를 주면 `disciplines` 다음에
+`changeSetDisciplines`를 컴파일합니다. `pdks explain`은 두 표면을 모두 출력하며 표면
+머리줄에 각 목록의 이름과 개수를 적으므로, 판정을 돌리지 않고도 모든 항목의 배치를 읽을 수
+있습니다. 이 저장소의 실제 설정은 `disciplines`에 판정 항목 11개와 초안 1개,
+`sessionDisciplines`에 13개, `changeSetDisciplines`에 1개(`docs-stay-bilingual`)를 두므로,
+세션 표면에 등록 24개, 변경 집합 표면에 12개가 섭니다.
+
+```yaml
+disciplines:            # 두 표면 모두
+  - id: 'covenant-vocabulary'
+    declare:
+      mechanism: 'added-only'
+      scope: { source: 'target.path', include: ['^packages/'] }
+      supply: { pre: 'empty', post: 'empty' }
+      extract:
+        before: [{ op: 'source', of: 'pre' }, { op: 'lines' }]
+        after: [{ op: 'source', of: 'post' }, { op: 'lines' }]
+        added: [{ op: 'onlyIn', of: 'after', notIn: 'before' }]
+      relate:
+        - { id: 'nothing-added', relation: { op: 'empty', of: 'added' }, message: 'adds {value}' }
+
+sessionDisciplines:     # 세션 표면만. command를 읽습니다
+  - id: 'pnpm-only'
+    declare:
+      mechanism: 'forbidden-command'
+      scope: { source: 'command' }
+      extract:
+        hits:
+          - { op: 'source', of: 'command' }
+          - { op: 'lines' }
+          - { op: 'matches', re: '\bnpm install\b' }
+      relate:
+        - { id: 'no-npm', relation: { op: 'empty', of: 'hits' }, message: '{value}' }
+
+changeSetDisciplines:   # 변경 집합 표면만. changes를 읽습니다
+  - id: 'docs-stay-bilingual'
+    declare:
+      mechanism: 'companion'
+      scope: { source: 'target.path', include: ['\.md$'] }
+      extract:
+        en:
+          - { op: 'source', of: 'target.path' }
+          - { op: 'keyByPattern', re: '^(.+?)(?<!\.ko)\.md$' }
+        koChanged:
+          - { op: 'source', of: 'changes' }
+          - { op: 'items' }
+          - { op: 'keyByPattern', re: '^(.+)\.ko\.md$' }
+      relate:
+        - id: 'ko-follows'
+          relation: { op: 'implies', of: 'en', requires: 'koChanged' }
+          message: '{value} changed without {key}.ko.md'
+```
+
+항목을 다른 목록으로 옮기는 것이 편집의 전부입니다. 옮겨도 항목 본문은 그대로이고, 새 자리가
+맞는지는 로더가 답합니다.
+
 <a id="disciplines"></a>
 ## `disciplines`
 
-선택 항목입니다. 팀이 함께 지킬 규율을 항목마다 하나씩 데이터로 선언합니다.
+선택 항목입니다. 팀이 함께 지킬 규율을 항목마다 하나씩 데이터로 선언합니다. 이 절의 내용은
+세 목록 어디에 적힌 항목에도 그대로 적용되며, 항목을 어느 목록에 적는지는
+[배치 규칙](#placement-rule)이 정합니다. `sessionDisciplines`와 `changeSetDisciplines`는
+초안 형태를 뺀 나머지에서 `disciplines`와 같은 항목 모양을 받습니다.
 판정 항목은 `declare` 블록(유일한 판정 형태로, 범위(`scope`)를 블록 안에 지니는 선언)과
 `id`(텔레메트리 라벨)를 가지며, 선택적으로 `why`(에이전트가 읽는 차단 메시지에 함께 실리는
 이유)와 `enforce` 강제 수준을 가집니다. 닫힌 키 집합은 `id` · `why` · `enforce` · `declare`이고
@@ -208,10 +307,10 @@ disciplines:
 **`enforce`는 항목 자신의 강제 수준입니다.** 판정 항목에 선택적으로 쓸 수 있으며 값은
 `block` 또는 `advise`입니다. **적지 않으면 `advise`입니다.** `advise`에서는 위반이
 `advised` 텔레메트리 이벤트로 기록되고 호출은 진행되며(exit 0), 위반 메시지는 그대로
-stderr에 쓰입니다. `block`을 지정하면 항목의 강제 수준을 차단으로 승격합니다. 항목의 강제 수준은
-표면의 강제 수준(커밋 표면의 `adapters.git.enforce`, 세션 표면은 강제 수준 설정이 없음)과
-함께 적용하며 더 관대한 쪽을 따릅니다. 두 수준 중 하나라도 `advise`면 권고로 처리합니다.
-항목의 `block` 설정으로 표면의 `advise` 설정을 무시할 수는 없습니다.
+stderr에 쓰입니다. `block`을 지정하면 항목의 강제 수준을 차단으로 승격합니다. 설정에는
+표면 단위 강제 수준이 없으므로 항목이 선언한 수준이 설정 쪽 판단의 전부입니다. 적지 않거나 `advise`면
+두 표면에서 `advised`이고, `block`이면 세션 표면과 `--enforce block`으로 실행한 커밋 검사에서
+종료 코드 2입니다(변경 집합 표면의 기본 자세는 모든 판정에 대해 advise입니다).
 판정할 수 없는 본체(빌드되지 않음, 적재 불가)는 강제 수준과 무관하게 차단됩니다. 초안(draft)은 `enforce`를 갖지 않고, 그 밖의
 값은 로드 시점에 거부됩니다. `pdks explain`은 항목이 선언한 강제 수준(`enforce: block` 또는
 `enforce: advise`)를 두 표면 모두에 표시하고 적지 않은 항목은 표시하지 않습니다. 세션
@@ -297,7 +396,13 @@ disciplines:
 남긴 뒤, 결과가 `empty`이기를 요구합니다. 범위를 `command`에 걸어 셸 호출만 받아들이게
 합니다. Edit에는 명령줄이 없고, 세계에 없는 소스를 읽는 선언은 판정 불가이기 때문입니다.
 여러 줄 명령은 줄 단위로 판정하므로 `^`는 줄의 시작을 뜻하고, 줄 경계를 걸치는 패턴은
-일치하지 않습니다.
+일치하지 않습니다. heredoc 본문과 herestring 단어는 소스에 들어가지 않습니다. bash는 그
+바이트를 실행하지 않고 명령에 stdin 데이터로 넘기므로, 그 안에 인용된 금지 토큰은 일치하지
+않고, 그 데이터가 파일 쓰기가 되는지는 셸 증거 경로가 따로 판정합니다. bash가 먼저 확장하는
+텍스트는 소스에 남습니다. 인용하지 않은 구분자 아래에서 `$`나 백틱을 담은 본문, 치환을 담은
+herestring 단어가 그것이고, 토크나이저가 끝까지 읽지 못한 줄도 그대로 남습니다. 받는 명령이
+stdin으로 무엇을 하는지는 판정하지 않습니다. 해석기에 넘긴 스크립트는 bash에게는 데이터이고
+해석기에게는 프로그램입니다.
 
 ```yaml
   - id: 'hooks-stay-armed'
@@ -322,8 +427,9 @@ disciplines:
 `select`가 명령줄을 추출하고, `matches`가 요구된 명령을 찾습니다. 판정은 `nonEmpty`입니다.
 약속(covenant)이 차단한 호출, 사람이 거부한 호출, 그냥 실패한 호출은 선행 증거가 아닙니다.
 패턴은 명령줄의 어느 위치에서든 일치 여부를 찾으므로, 명령을 언급만 한 줄도 증거로 셉니다. 선언된
-한계입니다. `supply: { session: 'pass' }`가 커밋 표면에서 매치하는 커밋을 전부 막는 대신
-`skipped`를 기록하게 하는 값입니다.
+한계입니다. `supply: { session: 'pass' }`는 세션을 증명하지 못하는 호스트에서 없는 세션을 처리하는
+값입니다. 대화 기록을 읽는 항목은 `sessionDisciplines`에 적히므로 변경 집합은 그 항목을 아예
+컴파일하지 않습니다.
 
 ```yaml
   - id: 'dependency-needs-npm-view'
@@ -392,14 +498,13 @@ disciplines:
 관측 하나가 **세계(world)** 하나로 판정되며 소스 이름은 일곱입니다. `target.path`(저장소
 상대 경로), `pre`와 `post`(변경이 지닌 쪽의 파일 본문. 생성에는 `pre`가, 삭제에는 `post`가
 없습니다), `state`(`{ pre, post }`, 수정에만 있습니다), `changes`(이 관측이 바꾸는 경로 전부.
-세션 표면에서는 호출 하나, 커밋 표면에서는 staged 집합 전체), 그리고 `command`(셸 호출의
+세션 표면에서는 호출 하나, 변경 집합 표면에서는 staged 집합 전체), 그리고 `command`(셸 호출의
 명령줄. 셸 호출에만 있고, 파일을 바꾸지 않는 셸 호출은 자기 세계 하나가 되므로 `command`에
 범위를 건 선언은 그 호출을 보고 `target.path`에 범위를 건 선언은 보지 않습니다). `changes`를
-읽는 선언은 변경 집합 전체를 관측하는 표면에서만 판정됩니다. 세션 표면은 그 선언을
-`skipped`로 기록합니다 — 커밋 표면이 세션을 읽는 선언에 내리는 처분과 같으며, 호출 하나가 쌍의 나머지
-반쪽을 실을 수 없기 때문입니다. 이 저장소의 라이브 설정은 그런 선언 하나를 싣습니다 —
-`docs-stay-bilingual`, `.md`/`.ko.md` 쌍 위의 `implies`로, 한쪽만 staged된 커밋 표면에서
-advised로 남습니다. 대상 밖 파일이 필요한 선언은
+읽는 선언은 `changeSetDisciplines`에 적히고 변경 집합 전체를 관측하는 표면에서만
+컴파일됩니다. 호출 하나는 쌍의 나머지 반쪽을 실을 수 없기 때문입니다. 이 저장소의 라이브
+설정은 그런 선언 하나를 싣습니다. `docs-stay-bilingual`은 `.md`/`.ko.md` 쌍 위의 `implies`이고,
+한쪽만 staged된 변경 집합 표면에서 advised로 남습니다. 대상 밖 파일이 필요한 선언은
 `sources` 블록에 이름을 붙이고(`sources: { en: { file: 'locales/en.json' } }`) `{ op:
 'source', of: 'en' }`로 읽습니다. 경로는 저장소 상대(선두 `/` 없음, `..` 세그먼트 없음)이고
 이름은 일곱 고정 이름과 겹칠 수 없습니다. 파일은 표면이 트리를 관측하는 방식대로
@@ -408,15 +513,15 @@ advised로 남습니다. 대상 밖 파일이 필요한 선언은
 `sources: { spawns: { sidecar: true } }`는 경로가 아니라 세션의 스폰 기록 채널을 이름
 붙입니다 — 호스트가 대화 기록(transcript) 옆에 남기는 서브에이전트 기록을 JSON 배열
 하나로 공급받습니다. 채널이 어디 있는지는 표면이 아는 사실이라 값은 표지 `true`이고,
-세션이 없는 커밋 표면에서는 채널이 언제나 없습니다. 셋째 종류
+세션이 없는 변경 집합 표면에서는 채널이 언제나 없습니다. 셋째 종류
 `sources: { session: { transcript: true } }`는 세션 자신의 대화 기록(transcript)을 이름
 붙입니다 — 표면이 읽는 사용자 턴과 도구 호출을, 항목마다 관측
 순번을 실은 스냅샷 하나로 선언에 건넵니다. 이력 단계(`toolUses` · `userTexts` · `first` ·
 `ageMs`)가 그것을 읽고, `agentType`은 파싱된 사이드카를 읽습니다. 이 저장소의 라이브
-설정은 그런 선언 하나를 싣습니다 — `tests-before-implementation`, 서브에이전트 스폰 둘의
-순번 위의 `ordered`로, 세션이 없는 커밋 표면은 `skipped`로 기록합니다. 일곱째 고정 이름
+설정은 그런 선언 하나를 싣습니다. `tests-before-implementation`은 서브에이전트 스폰 둘의 순번
+위의 `ordered`이고 `sessionDisciplines`에 적혀 있습니다. 일곱째 고정 이름
 `actor`는 관측의 주체(actor)입니다. 서브에이전트 안에서는 `{ agentType }`, 주 세션에서는
-`{}`, 표면이 주체를 증명하지 못하면(커밋 표면) 없습니다. `{ op: 'source', of: 'actor' }` 뒤에
+`{}`, 표면이 주체를 증명하지 못하면(변경 집합 표면) 없습니다. `{ op: 'source', of: 'actor' }` 뒤에
 `agentType`을 `select`해 읽고, `producer-owned` · `actor-scope` 기전이 요구하는 `actor`
 축을 유도합니다. 이 저장소의 라이브 설정은 각 하나씩 싣습니다(`tests-are-the-writers`,
 `commits-come-from-the-main-session`). `supply`의 키는