polydeukes 0.6.0 → 0.7.1

package/dist/docs/reference/{adapter-claude-code.md → packages/adapter-claude-code.md}

@@ -1,14 +1,14 @@
 # `@polydeukes/adapter-claude-code`
 
-**English** · [한국어](./adapter-claude-code.ko.md)
+**English** · [한국어](adapter-claude-code.ko.md)
 
-> **The session surface's translator** — PreToolUse payloads become the covenant input IR,
-> with the file-change evidence and the transcript channel the judge reads.
+> **The Claude Code install unit** — PreToolUse payloads become the covenant input IR,
+> with the file-change evidence and the transcript channel the judge reads, and the
+> package installs the session surface into a project.
 >
-> Alpha. A transitive dependency of the umbrella: you do not install it and you do not
-> import it. The session surface reaches it through
-> [`polydeukes/claude-code`](./polydeukes.md#subpaths).
+> Alpha. Install it next to `polydeukes`, which it names as a `peerDependency`.
 
+<a id="ownership"></a>
 ## What this package owns
 
 The boundary where Claude Code's vocabulary is translated away. Agent and tool literals
@@ -17,17 +17,25 @@ agent-neutrality a claim a test can check rather than a slogan.
 
 | Unit | What it does |
 |---|---|
+| `pdks-claude-code` bin | One subcommand, `pdks-claude-code init`, which registers the session surface in a project |
+| `runHook` | Translates one PreToolUse payload into the input IR and spawns the judge |
 | Payload up-translation | A raw PreToolUse payload becomes a `CovenantInput` |
 | Virtual post-state | Computes what a file *would* contain after an edit applies, without touching disk |
 | File-change evidence | Pairs the disk pre-state with the virtual post-state into union evidence |
 | Transcript provider | Turns a session JSONL file into a `CanonicalTranscript` |
-| Telemetry wiring | Drives the full funnel so exactly one row lands per call |
 
-This package never imports the covenant package. The dispatch seam is *injected* by the
-umbrella, which keeps dependencies one-way, through the core alone. It names
-`@polydeukes/core` as a `peerDependency`: the vocabulary is shared with the judge, not
-installed a second time here.
+`runHook({ repoRoot })` is what the generated hook delegator imports. It builds the IR — the
+`tools` and `session` evidence included — then spawns `pdks covenant check --enforce block` in
+`repoRoot` and returns the child's exit code. The judging happens in that child process; this
+package carries no judgment logic.
 
+**This package writes no telemetry rows.** A failure before the spawn is sent to `pdks` on
+stdin as a plain line, and `pdks` records the fail-closed row, so one call still leaves one
+row. It never imports the judge: `polydeukes` and `@polydeukes/core` are both
+`peerDependencies`, so the vocabulary and the judge are shared rather than installed a second
+time here.
+
+<a id="translation"></a>
 ## Payload translation and the three axes
 
 **Three axes reach the judge**, and they differ in what evidence they can carry.
@@ -56,23 +64,37 @@ witness valve human-only: an AI cannot synthesize its own witness. A read failur
 judged, an unreadable one is no evidence channel at all and is skipped. Either way the
 valve turns off, never open.
 
-**The precedent evaluator judges two keys.** `subagent` is exact spawn-kind equality, since
-a kind is a value rather than a pattern; `tool` matches observed tool names as a regular
-expression. Any key outside this vocabulary returns `undefined` — the handshake that tells
-the compiler the evidence is unjudgeable, so the entry skips instead of judging on a guess.
+**Precedent is a declaration, not an adapter evaluator.** This adapter supplies the
+transcript snapshot. The declaration engine extracts succeeded `toolUses` and matches them;
+there is no separate precedent evaluator in this package. The grammar is in
+[Configuration — disciplines](../configuration/index.md#disciplines).
 
+<a id="consumer-contract"></a>
 ## Where the consumer touches it
 
-- **The generated hook**, which loads this adapter through the umbrella's `claude-code`
-  subpath. Upgrading the package upgrades what runs; the hook file itself never changes.
+Two lines install the Claude Code session surface, run from the project root:
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npx pdks-claude-code init
+```
+
+`pdks-claude-code init` resolves `polydeukes` from the project, spawns `pdks init` for the
+agent-neutral scaffold, then writes the four Claude Code artifacts non-destructively. A re-run
+reports each existing artifact as skipped and overwrites nothing. The full artifact list is in
+[`pdks init`](../cli/init.md#init-claude-code).
+
+- **The generated hook** imports `runHook` from this package. Upgrading the package upgrades
+  what runs; the hook file itself never changes.
 
-No import, and no configuration namespace of its own.
+No configuration namespace of its own.
 
+<a id="limits"></a>
 ## Declared limits
 
 - **A child process's writes are outside observation.** This surface judges *declared tool
   calls*. A command that spawns a process which then writes files — a test runner, a build
-  — is judged on the command, not on what the child did. The commit surface is the second
+  — is judged on the command, not on what the child did. The change-set surface is the second
   observation that covers the same ground for tracked files.
 - **Evidence exists only where a post-state can be computed.** All four mutating tools
   contribute one, notebooks included — a `NotebookEdit` yields cell-level `modify` evidence.
@@ -82,3 +104,9 @@ No import, and no configuration namespace of its own.
   are compared for a mention rather than a proven target.
 - **Out-of-repository ancestors stay out of scope.** A path above the project root is not
   observed here; the agent's own deny policy owns that ground.
+- **An unresolvable `polydeukes` leaves no row.** When the umbrella cannot be resolved from the
+  project there is no process to spawn and no log path to write to, so the hook exits `2` with
+  one line on stderr and the telemetry log gains nothing. Every other pre-spawn failure does
+  reach `pdks` and does leave a row.
+- **Grok installs through `@polydeukes/adapter-grok`.** That package writes its own delegator
+  and roster. Installing both session adapters in one project can run the judge twice per call.

package/dist/docs/reference/packages/adapter-grok.ko.md

@@ -0,0 +1,77 @@
+# `@polydeukes/adapter-grok`
+
+[English](adapter-grok.md) · **한국어**
+
+> **Grok의 설치 단위**입니다. PreToolUse 페이로드가 약속(covenant) 입력 IR이 되고,
+> 판정기가 읽는 파일 변경 증거가 함께 실립니다. 세션 표면을 프로젝트에 설치하는 것도 이
+> 패키지가 합니다.
+>
+> 알파입니다. `polydeukes`와 함께 설치하며, `polydeukes`는 이 패키지의 `peerDependency`입니다.
+
+<a id="ownership"></a>
+## 담당하는 기능
+
+Grok의 입력을 공통 형식으로 번역합니다. 에이전트와 도구의 구체적인 이름은 이 패키지에서
+처리하고 코어에는 넣지 않습니다.
+
+| 단위 | 하는 일 |
+|---|---|
+| `pdks-grok` 실행 파일 | 하위 명령 하나 `pdks-grok init`으로 프로젝트에 세션 표면을 등록합니다 |
+| `runHook` | PreToolUse 페이로드 하나를 입력 IR로 바꾸고 판정기를 스폰합니다 |
+| 페이로드 상향 번역 | 원본 PreToolUse 페이로드가 `CovenantInput`이 됩니다 |
+| 예상 변경 후 상태 | 쓰기나 치환이 적용되면 파일이 무엇을 담을지 디스크를 건드리지 않고 계산합니다 |
+| 파일 변경 증거 | 디스크의 변경 전 상태와 예상 변경 후 상태를 짝지어 변경 증거를 만듭니다 |
+
+생성된 훅 위임자가 불러오는 것이 `runHook({ repoRoot })`입니다. `tools` 명부를 실은 입력 IR을
+만든 뒤 — `session`과 `actor` 키는 없습니다 — `repoRoot`에서
+`pdks covenant check --enforce block`을 스폰하고 그 자식 프로세스의 종료 코드를 그대로
+돌려줍니다. 판정은 그 자식 프로세스가 하며, 이 패키지에는 판정 코드가 없습니다.
+
+**이 패키지는 텔레메트리 행을 쓰지 않습니다.** 스폰 전에 실패하면 그 사실을 한 줄로 만들어
+`pdks`의 표준 입력으로 보내고, `pdks`가 fail-closed 행을 기록합니다. 호출 하나에 행 하나는
+그대로입니다. 판정기를 불러오지도 않습니다. `polydeukes`와 `@polydeukes/core` 모두
+`peerDependencies`이므로 어휘와 판정기를 공유할 뿐 사본을 따로 설치하지 않습니다.
+
+이 어댑터가 IR에 실는 명부는 Grok 원어입니다. `write`와 `search_replace`는 파일을 바꾸고,
+`run_terminal_command`는 셸 한 줄을 실습니다.
+
+<a id="consumer-contract"></a>
+## 소비자가 닿는 곳
+
+프로젝트 루트에서 두 줄이면 Grok 세션 표면이 설치됩니다.
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-grok
+npx pdks-grok init
+```
+
+`pdks-grok init`은 프로젝트에서 `polydeukes`를 찾고, 에이전트와 무관한 초기 파일을 위해
+`pdks init`을 스폰한 뒤, Grok 산출물 둘을 덮어쓰지 않고 씁니다. 다시 실행하면 이미 있는
+산출물은 `skipped`로 보고하고 내용을 바꾸지 않습니다. 산출물 목록은
+[`pdks init`](../cli/init.ko.md#init-grok)에 있습니다.
+
+이 어댑터와 `@polydeukes/adapter-claude-code`를 한 프로젝트에 함께 설치하면 호출마다
+판정기가 두 번 실행될 수 있습니다.
+
+- **생성된 훅**은 이 패키지의 `runHook`을 불러옵니다. 패키지를 올리면 실행되는 코드가
+  올라가고, 훅 파일 자체는 바뀌지 않습니다.
+
+자체 설정 네임스페이스는 없습니다.
+
+<a id="limits"></a>
+## 선언된 한계
+
+- **자식 프로세스의 쓰기는 관측 밖입니다.** 이 표면은 *선언된 도구 호출*을 판정합니다. 파일을
+  쓰는 프로세스를 띄우는 명령은 그 명령 줄로 판정되며, 자식이 한 일로 판정되지 않습니다.
+- **증거는 변경 후 상태를 계산할 수 있을 때만 있습니다.** `write`와 `search_replace`가 하나를
+  만듭니다. 치환이 한 번도 맞지 않거나, `replace_all` 없이 두 번 이상 맞으면 증거가 없습니다.
+  호스트 도구가 그 호출을 거부하기 때문입니다.
+- **증거 없는 호출은 보수적으로 판정합니다.** 증명된 대상이 없으므로 호출 인자에 보호 경로가
+  언급됐는지 대조합니다.
+- **대화 기록(transcript) 통로가 없습니다.** IR은 `session`과 `actor`를 생략합니다. Grok의
+  ACP 대화 기록은 세션 증인(witness) 밸브가 필요로 하는 인간 메시지 증거를 공급하지 않습니다.
+  의도한 편집이 차단되면 본인 터미널에서 수행하세요.
+- **`polydeukes`를 찾지 못하면 행이 남지 않습니다.** 프로젝트에서 우산 패키지를 찾지 못하면
+  스폰할 프로세스도, 기록할 로그 경로도 없습니다. 훅은 stderr에 한 줄을 남기고 종료 코드
+  `2`를 내며 텔레메트리 로그에는 아무것도 추가되지 않습니다. 스폰 전 실패 가운데 이 경우만
+  그렇고, 나머지는 모두 `pdks`에 도달해 행을 남깁니다.

package/dist/docs/reference/packages/adapter-grok.md

@@ -0,0 +1,79 @@
+# `@polydeukes/adapter-grok`
+
+**English** · [한국어](adapter-grok.ko.md)
+
+> **The Grok install unit** — PreToolUse payloads become the covenant input IR, with the
+> file-change evidence the judge reads, and the package installs the session surface into a
+> project.
+>
+> Alpha. Install it next to `polydeukes`, which it names as a `peerDependency`.
+
+<a id="ownership"></a>
+## What this package owns
+
+The boundary where Grok's vocabulary is translated away. Agent and tool literals live *here*
+by design, so that they never reach the core.
+
+| Unit | What it does |
+|---|---|
+| `pdks-grok` bin | One subcommand, `pdks-grok init`, which registers the session surface in a project |
+| `runHook` | Translates one PreToolUse payload into the input IR and spawns the judge |
+| Payload up-translation | A raw PreToolUse payload becomes a `CovenantInput` |
+| Virtual post-state | Computes what a file *would* contain after a write or substitution applies, without touching disk |
+| File-change evidence | Pairs the disk pre-state with the virtual post-state into union evidence |
+
+`runHook({ repoRoot })` is what the generated hook delegator imports. It builds the IR — the
+`tools` roster included, with no `session` or `actor` key — then spawns
+`pdks covenant check --enforce block` in `repoRoot` and returns the child's exit code. The
+judging happens in that child process; this package carries no judgment logic.
+
+**This package writes no telemetry rows.** A failure before the spawn is sent to `pdks` on
+stdin as a plain line, and `pdks` records the fail-closed row, so one call still leaves one
+row. It never imports the judge: `polydeukes` and `@polydeukes/core` are both
+`peerDependencies`, so the vocabulary and the judge are shared rather than installed a second
+time here.
+
+The roster this adapter puts on the IR is Grok-native: `write` and `search_replace` mutate a
+file; `run_terminal_command` carries a shell line.
+
+<a id="consumer-contract"></a>
+## Where the consumer touches it
+
+Two lines install the Grok session surface, run from the project root:
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-grok
+npx pdks-grok init
+```
+
+`pdks-grok init` resolves `polydeukes` from the project, spawns `pdks init` for the
+agent-neutral scaffold, then writes the two Grok artifacts non-destructively. A re-run
+reports each existing artifact as skipped and overwrites nothing. The full artifact list is in
+[`pdks init`](../cli/init.md#init-grok).
+
+Installing both this adapter and `@polydeukes/adapter-claude-code` in one project can run the
+judge twice per call.
+
+- **The generated hook** imports `runHook` from this package. Upgrading the package upgrades
+  what runs; the hook file itself never changes.
+
+No configuration namespace of its own.
+
+<a id="limits"></a>
+## Declared limits
+
+- **A child process's writes are outside observation.** This surface judges *declared tool
+  calls*. A command that spawns a process which then writes files is judged on the command,
+  not on what the child did.
+- **Evidence exists only where a post-state can be computed.** `write` and `search_replace`
+  contribute one. A substitution that matches nothing, or that matches more than once without
+  `replace_all`, yields no evidence — the host tool refuses those calls.
+- **An evidence-free call falls back to the conservative judgment** — the call's arguments
+  are compared for a mention rather than a proven target.
+- **There is no transcript channel.** The IR omits `session` and `actor`. Grok's ACP history
+  does not supply the human-message evidence the session witness valve needs. For an
+  intentional blocked edit, use your own terminal.
+- **An unresolvable `polydeukes` leaves no row.** When the umbrella cannot be resolved from the
+  project there is no process to spawn and no log path to write to, so the hook exits `2` with
+  one line on stderr and the telemetry log gains nothing. Every other pre-spawn failure does
+  reach `pdks` and does leave a row.

package/dist/docs/reference/packages/core.ko.md

@@ -0,0 +1,174 @@
+# `@polydeukes/core`
+
+[English](core.md) · **한국어**
+
+> **모든 약속(covenant)이 말하는 프로토콜**입니다. 입력 IR과 판정 결과 형태, 설정 스키마,
+> 텔레메트리 수집기가 여기 있습니다.
+>
+> 알파입니다. 일반 사용자는 이 패키지를 따로 설치하거나 불러올 필요가 없습니다. 통합 패키지의 의존성으로 설치되며, 사용자 진입점은
+> [`polydeukes`](polydeukes.ko.md)입니다.
+
+<a id="ownership"></a>
+## 담당하는 기능
+
+모든 약속이 사용하는 공통 프로토콜을 정의합니다. 개별 약속이 무엇을 판정하는지는 다루지 않습니다.
+
+| 영역 | 무엇인가 |
+|---|---|
+| 약속 프로토콜 | 표준 입력 JSON 입력 IR, 판정 결과 형태, 종료 코드 계약 |
+| 설정 스키마 | `defineConfig()`가 파싱된 yaml·json 데이터를 검증합니다. 대응하는 JSON Schema도 별도 파일로 제공합니다 |
+| ROI 텔레메트리 | 모든 패키지가 공유하는 추가 전용 로그 기록기 |
+| 실패 정책 | 실패 종류마다 fail-open과 fail-closed를 가르는 표 하나 |
+| 보호 경로 정규화 | 선언된 목록이 디스패처가 대조하는 문자열이 됩니다 |
+| 대화 기록(transcript) 이음매 | 약속이 세션 이력을 묻는 질의 인터페이스 |
+
+이 패키지는 두 가지 제약을 따릅니다. **런타임 의존이 없습니다.** 검증은 손으로 짰고
+배포하는 JSON Schema는 런타임 코드에서 읽지 않는 별도 파일입니다. **에이전트나 도구, 언어의
+리터럴이 없습니다.** 편집기 도구 이름과 테스트 러너 이름은 설정과 어댑터가 채워 넣는
+**값**이라서, 코어의 에이전트 중립성은 grep으로 확인되는 주장입니다. 다른 모든 패키지가
+이 패키지에 의존하고, 이 패키지는 그 어느 것에도 의존하지 않습니다.
+
+**세션 어댑터는 이 패키지를 `peerDependency`로 선언합니다.** 따로 설치하는 대신 우산과 같은 어휘를 공유합니다. `SOURCE_KINDS`와
+`parseInput`은 검증기와 엔진이
+같은 값을 참조해야 합니다. 서로 다른 사본을 사용하면 설치는 성공해도 동작이 달라질 수 있습니다.
+통합 패키지가 일반 의존성으로 core를 제공하므로 사용자는 패키지 하나만 설치하면 됩니다.
+
+<a id="protocol"></a>
+## 판정 프로토콜
+
+현재 판정기는 표면이 디스패처에 전달한 표준 입력 JSON 페이로드를 한 번 파싱한
+`CovenantInput`을 받습니다. 판정 결과를 반환하면 래퍼가 종료 코드로 변환합니다.
+`.polydeukes/roi.log`의 차단 기록도 이 판정 어휘를 사용합니다.
+
+`world`는 표면이 공급합니다(`files`, `changes`, `channels`). 판정기가 디스크에서 읽지
+않습니다. `tools`와 `session`은 호스트가 공급합니다. 명부는 어댑터가 채우는 값이고, 세션은
+IR만으로는 증명하지 못하는 두 사실, 메시지의 신선도와 호출의 결과를 담은 증거입니다.
+`transcriptFromSession`은 그 키에서 증인이나 선행 조건 소비자가 읽는 대화 기록을 만들고,
+`transcriptFromInput`은 그 두 사실 없이 IR에서 같은 대화 기록을 만듭니다.
+
+```ts
+type CovenantInput = {
+  toolCalls: { name: string; args?: Record<string, unknown>; fileChange?: FileChange }[];
+  subagentSpawns: { kind: string }[];
+  userMessages: { text: string }[];
+  actor?: { agentType?: string };
+  world?: {
+    files?: Record<string, string>;
+    changes?: string[];
+    channels?: { sidecar?: string };
+  };
+  tools?: { mutating: string[]; shell: string[]; commandArgs: string[] };
+  session?: {
+    evidencePath?: string;
+    userMessages: { text: string; timestampMs?: number }[];
+    toolCalls: { name: string; args?: Record<string, unknown>; succeeded?: boolean }[];
+    channels?: { sidecar?: string };
+  };
+};
+
+type FileChange =
+  | { kind: 'create'; path: string; post: string }
+  | { kind: 'modify'; path: string; pre: string; post: string }
+  | { kind: 'delete'; path: string; pre?: string };
+
+type CovenantVerdict = { upheld: true } | { upheld: false; reason: string };
+```
+
+이 어휘에는 도구 이름도 에이전트 이름도 없습니다. 구체적인 도구 이름은 어댑터가 `name`에
+채우는 **값**이고, 스폰의 `kind`도 마찬가지입니다. `FileChange`가 판별 유니온인 이유는
+삭제를 표현할 수 없는 예외가 아니라 일급 증거로 두기 위해서입니다. 불가능한 상태는 아예
+적을 수 없습니다. 결과 내용을 든 삭제나 기준선을 든 생성이 그렇습니다. `delete.pre`는
+기준선이 바이너리 blob이었을 때 없습니다. 삭제를 판정하는 데는 내용이 필요 없기
+때문입니다. `actor`는 호스트 봉투가 증명하는 관측의 주체(actor)입니다. 서브에이전트 안에서는
+`agentType`, 주 세션에서는 `{}`이고, 표면이 주체를 증명하지 못하면 없습니다. 판정기는 기본값을
+채우지 않습니다.
+
+**증거는 해당 호출에만 속합니다.** `fileChange`가 없다는 것은 이
+호출이 증명되지 않았다는 뜻이고, 형제 호출의 증거가 그 자리를 대신하지 않습니다.
+
+```ts
+function parseInput(stdinJson: string):
+  | { ok: true; value: CovenantInput }
+  | { ok: false; exitCode: 2 };
+
+function verdictToExitCode(verdict: CovenantVerdict): 0 | 1;
+
+function allFileChanges(input: CovenantInput): FileChange[];
+```
+
+`parseInput`은 예외를 던지지 않습니다. 파싱되지 않는 JSON, 빈 페이로드, 객체가 아닌 값,
+필수 컬렉션 누락은 모두 `{ ok: false, exitCode: 2 }`로 반환합니다. 판정할 수 없는
+입력이 유효한 입력으로 오인될 길이 없습니다.
+
+`verdictToExitCode`는 `0`이나 `1`을 반환하고 `2`는 결코 반환하지 않습니다. 위반을 차단으로
+번역하는 것은 본체가 아니라 래퍼의 정책입니다. [종료 코드](polydeukes.ko.md#polydeukes-failure-boundaries)를
+보십시오. 내보내는 상수는 `EXIT_UPHOLD`(`0`), `EXIT_BREAK_NON_BLOCKING`(`1`),
+`EXIT_BREAK_BLOCKING`(`2`)입니다.
+
+`allFileChanges`는 귀속이 필요 없는 소비자를 위해 모든 호출의 증거를 호출 순서대로
+평탄화합니다. 증거 없는 호출은 건너뛰고 무엇으로도 대체하지 않습니다.
+
+<a id="discipline-lists"></a>
+## 규율 목록 셋과 통로 유도
+
+`defineConfig()`는 규율 목록 셋을 받고, 항목마다 그것이 맞는 목록에 적혔는지 판정합니다.
+
+| 키 | 타입 | 판정하는 표면 |
+|---|---|---|
+| `disciplines` | `(DisciplineEntry \| DisciplineDraft)[]` | 두 표면 모두 |
+| `sessionDisciplines` | `DisciplineEntry[]` | 세션 표면(session surface)만 |
+| `changeSetDisciplines` | `DisciplineEntry[]` | 변경 집합 표면(change-set surface)만 |
+
+`ResolvedConfig`도 같은 이름으로 셋을 싣되 판정 항목만 담고, 초안(draft)은 `drafts`로 갈라
+둡니다. 입력이 선언하지 않은 목록은 빈 배열이 되지 않고 없는 채로 남습니다.
+
+검증기와 우산 패키지가 함께 쓰는 유도는 내보내는 함수 하나입니다.
+
+```ts
+type DeclarationChannel = 'transcript' | 'channel' | 'command' | 'actor' | 'changes';
+
+function declarationChannels(body: Omit<AlgebraDeclaration, 'discipline'>): DeclarationChannel[];
+```
+
+순수하고 구문적인 함수라서 선언을 실행하지 않습니다. `transcript`는 `{ transcript: true }`
+바인딩에서, `channel`은 `{ sidecar: true }` 바인딩에서, `command`는
+`scope.source === 'command'`나 `{ op: 'source', of: 'command' }` 단계에서, `actor`는
+`{ op: 'source', of: 'actor' }` 단계에서, `changes`는
+`{ op: 'source', of: 'changes' }` 단계에서 나옵니다. `witness` 블록 자신의 `extract`도 본체와
+함께 훑습니다. 반환 목록은 위 표의 고정 순서를 따르므로, 통로 집합을 비교하는 두 호출자가 같은
+목록을 비교합니다.
+
+다섯 가운데 하나도 이름 짓지 않는 본체는 변경된 파일과 저장소 파일만 읽고 그 둘은 두 표면이
+모두 공급하므로 `disciplines`에 속합니다. 그 밖은 항목과 통로와 가야 할 목록을 대는
+`ConfigValidationError`이며, 메시지는
+[설정 참조](../configuration/index.ko.md#placement-rule)에 있습니다. 우산 패키지는 같은 질문을
+따로 답하지 않고 이 함수를 불러 씁니다.
+
+<a id="consumer-contract"></a>
+## 사용자와의 접점
+
+일반 사용자는 다음 세 경로로 이 패키지의 기능을 사용합니다.
+
+- **설정 파일.** 그 스키마가 여기서 정의됩니다. 어휘 레퍼런스는
+  [설정 레퍼런스](../configuration/index.ko.md)입니다.
+- **JSON Schema 자산.** `@polydeukes/core/schema.json` exports 서브패스입니다. 이 패키지를
+  직접 설치한 프로젝트가 쓰는 경로입니다. 우산을 설치한 소비자는 그쪽에 동봉된 사본을
+  가리킵니다. 두 철자 모두
+  [configuration.md의 IDE 절](../../how-to/configure-project.ko.md#add-ide-support)에 있습니다.
+- **위의 프로토콜.** `blocked` 행을 읽는다는 것은 본체가 답한 어휘를 읽는다는 뜻입니다.
+
+그 밖의 기능은 `polydeukes`를 통해 사용합니다.
+
+<a id="limits"></a>
+## 선언된 한계
+
+- **어댑터 네임스페이스는 이름이 아니라 형태로 검증합니다.** `defineConfig()`는 `adapters`가
+  평범한 객체의 맵인지, 각 네임스페이스 값이 객체인지를 봅니다. 네임스페이스 **이름**이
+  누군가 구현한 것인지는 보지 않고, 네임스페이스 안쪽은 들여다보지 않습니다.
+  네임스페이스 안의 미지 어휘는 해당 어댑터의 검증기가 자기 층위에서 거부합니다. 여기가
+  아닙니다.
+- **기본 대화 기록은 아무것도 하지 않습니다.** 실제 대화 기록을 주입하지 않은 소비자는
+  "아무 일도 없었다"는 결과를 받습니다. 이 상태에서는 증인 밸브가 작업을 허용하지 않으므로
+  차단을 유지합니다. 실제 대화 기록은 어댑터 뒤에 있습니다.
+- **fail-open은 텔레메트리 하나뿐입니다.** 기록이 실패해도 판정은 바뀌지 않습니다. 표에 든
+  다른 모든 실패 종류는 차단으로 처리합니다.

package/dist/docs/reference/{core.md → packages/core.md}

@@ -1,13 +1,14 @@
 # `@polydeukes/core`
 
-**English** · [한국어](./core.ko.md)
+**English** · [한국어](core.ko.md)
 
 > **The protocol every covenant speaks** — the input IR, the verdict shape, the config
 > schema, and the telemetry collector.
 >
 > Alpha. A transitive dependency of the umbrella: you do not install it and you do not import
-> it. The consumer entry point is [`polydeukes`](./polydeukes.md).
+> it. The consumer entry point is [`polydeukes`](polydeukes.md).
 
+<a id="ownership"></a>
 ## What this package owns
 
 The protocol every covenant speaks, and nothing that knows what a covenant is *about*.
@@ -27,20 +28,27 @@ hand-rolled and the published JSON Schema is a sibling artifact the source never
 *values* supplied by configs and adapters, so the core's agent-neutrality is a claim a grep
 can check. Every other package depends on this one; this one depends on none of them.
 
-**The judge and the two adapters name it as a `peerDependency`, not a dependency of their
-own.** They share the vocabulary rather than each installing a copy — `SOURCE_KINDS` and
+**The session adapter names it as a `peerDependency`, not a dependency of its
+own.** It shares the vocabulary with the umbrella rather than installing a copy — `SOURCE_KINDS` and
 `parseInput` have to be one set of values for the validator and the engine to agree, and two
 copies would disagree silently instead of failing at install time. The umbrella carries the
 ordinary dependency that satisfies that peer, which is why a consumer still installs one
 package and gets core transitively.
 
+<a id="protocol"></a>
 ## The judged protocol
 
 This is the contract the shipped judges speak: a judge receives a `CovenantInput` — parsed
 once from the stdin-JSON payload the surface hands the dispatcher — and answers with a
-verdict the wrapper translates into an exit code. Every row in `.polydeukes/roi.log` traces
-back to one
-of these verdicts, so this vocabulary is what a blocked row is written in.
+verdict the wrapper translates into an exit code. Blocked rows in `.polydeukes/roi.log`
+use this judgment vocabulary.
+
+`world` is supplied by the surface (`files`, `changes`, `channels`). The judge does not
+read it from disk. `tools` and `session` are supplied by the host: the roster is values the
+adapter fills in, and the session is the evidence a live agent session proves that a bare
+IR cannot — message freshness and call outcome. `transcriptFromSession` wraps that key as
+the transcript a witness or a precedent consumer reads, the way `transcriptFromInput` wraps
+the bare IR without those two facts.
 
 ```ts
 type CovenantInput = {
@@ -48,6 +56,18 @@ type CovenantInput = {
   subagentSpawns: { kind: string }[];
   userMessages: { text: string }[];
   actor?: { agentType?: string };
+  world?: {
+    files?: Record<string, string>;
+    changes?: string[];
+    channels?: { sidecar?: string };
+  };
+  tools?: { mutating: string[]; shell: string[]; commandArgs: string[] };
+  session?: {
+    evidencePath?: string;
+    userMessages: { text: string; timestampMs?: number }[];
+    toolCalls: { name: string; args?: Record<string, unknown>; succeeded?: boolean }[];
+    channels?: { sidecar?: string };
+  };
 };
 
 type FileChange =
@@ -85,33 +105,75 @@ required collection — each resolves to a blocking `{ ok: false, exitCode: 2 }`
 unjudgeable input can never be mistaken for a valid one.
 
 `verdictToExitCode` returns `0` or `1` and never `2`. Translating a break into a block is
-the wrapper's policy, not the body's — see [exit codes](./polydeukes.md#exit-codes).
+the wrapper's policy, not the body's — see [exit codes](polydeukes.md#polydeukes-failure-boundaries).
+The exported constants are `EXIT_UPHOLD` (`0`), `EXIT_BREAK_NON_BLOCKING` (`1`), and
+`EXIT_BREAK_BLOCKING` (`2`).
 
 `allFileChanges` flattens every call's evidence in call order for consumers that need no
 attribution. Calls without evidence are skipped, never substituted for.
 
+<a id="discipline-lists"></a>
+## The three discipline lists and the channel derivation
+
+`defineConfig()` accepts three discipline lists and decides, for each entry, whether it is
+written in the right one.
+
+| Key | Type | Judged on |
+|---|---|---|
+| `disciplines` | `(DisciplineEntry \| DisciplineDraft)[]` | both surfaces |
+| `sessionDisciplines` | `DisciplineEntry[]` | the session surface only |
+| `changeSetDisciplines` | `DisciplineEntry[]` | the change-set surface only |
+
+`ResolvedConfig` carries the three under the same names, holding judged entries only, with the
+drafts split out into `drafts`. A list the input did not declare stays absent rather than
+becoming an empty array.
+
+The derivation both the validator and the umbrella use is one exported function:
+
+```ts
+type DeclarationChannel = 'transcript' | 'channel' | 'command' | 'actor' | 'changes';
+
+function declarationChannels(body: Omit<AlgebraDeclaration, 'discipline'>): DeclarationChannel[];
+```
+
+It is pure and syntactic — the declaration is never run. `transcript` comes from a
+`{ transcript: true }` binding, `channel` from a `{ sidecar: true }` binding, `command` from
+`scope.source === 'command'` or a `{ op: 'source', of: 'command' }` step, `actor` from a
+`{ op: 'source', of: 'actor' }` step, and `changes` from a
+`{ op: 'source', of: 'changes' }` step. A `witness` block's own `extract` is walked with the
+body's. The returned list is in the fixed order above, so two callers comparing channel sets
+compare the same list.
+
+A body naming none of the five reads the changed file and repository files alone, which both
+surfaces supply, so it belongs in `disciplines`. Anything else is a `ConfigValidationError`
+naming the entry, its channels, and the list it belongs in; the messages are in [the
+configuration reference](../configuration/index.md#placement-rule). The umbrella imports this
+function rather than answering the same question a second time.
+
+<a id="consumer-contract"></a>
 ## Where the consumer touches it
 
 Three places, all of them indirect.
 
 - **The config file.** Its schema is defined here. The vocabulary reference is
-  [the configuration reference](./configuration.md).
+  [the configuration reference](../configuration/index.md).
 - **The JSON Schema artifact** — `@polydeukes/core/schema.json`, an exports subpath, for a
   project that installs this package directly. A consumer of the umbrella names the copy
   bundled there instead; both spellings are in
-  [configuration.md's IDE section](../configuration.md#ide-support).
+  [configuration.md's IDE section](../../how-to/configure-project.md#add-ide-support).
 - **The protocol above** — reading a `blocked` row means reading the vocabulary a body
   answered in.
 
 Everything else here is reached through `polydeukes`.
 
+<a id="limits"></a>
 ## Declared limits
 
 - **Adapter namespaces are validated by shape, not by name.** `defineConfig()` checks that
   `adapters` is a map of plain objects and that each namespace value is an object. It does
   not check that a namespace *name* is one anybody implements, and it does not look inside
-  the namespace at all. Unknown vocabulary inside `adapters.git` is rejected by the git
-  adapter's own validator, at its own layer — not here.
+  the namespace at all. Unknown vocabulary inside a namespace is rejected by that adapter's
+  own validator, at its own layer — not here.
 - **The default transcript is a noop.** A consumer that injects no real transcript
   converges on "nothing happened", which is the safe direction for a valve: it never opens.
   Real transcripts live behind adapters.