polydeukes 0.6.1 → 0.7.1

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

@@ -56,64 +56,35 @@ rejected by that adapter's validator, with the full field path in the error.
 
 ```yaml
 adapters:
-  git:
-    enforce: advise
-    protectedPaths:
-      - 'packages/core/src'
+  example:
+    someKey: 'a value the example adapter defines'
 ```
 
-<a id="adapters-git"></a>
-### `adapters.git` — the git commit adapter
-
-| Key | Values | Default | Meaning |
-|---|---|---|---|
-| `enforce` | `block` \| `advise` | `block` | Enforcement level of the commit surface |
-| `protectedPaths` | string array | `[]` | Additive protection scope judged by the commit surface only |
-
-- **`block`** — a staged change that breaks a covenant judged at block level blocks the
-  commit (exit 2): a protected path, or an entry promoted with `enforce: block`. An ordinary
-  entry keeps its own default `advise` under this setting (see `enforce` below). The
-  only way through is the witness valve: a human answering the TTY prompt with the full
-  token. The prompt names what it asks the human to witness — the broken registration,
-  the matched entry, and the fact that the one answer covers the whole commit. An absent
-  namespace, an absent `adapters` map, or an absent `enforce` key all mean `block` — not
-  writing the key selects the strictest level.
-- **`advise`** — the commit surface becomes a backstop without a block: a verdict on a
-  staged change is recorded as an `advised` telemetry event and the commit proceeds
-  (exit 0) with one advisory line on stderr. No TTY prompt fires. The judgment criteria stay
-  the same; violations no longer block. A run that cannot judge (missing or invalid config,
-  an unresolvable judge body) still fails closed at exit 2, at either level.
-
-**`protectedPaths` here is an additive scope.** The commit surface judges the union of the
-top-level `protectedPaths` and this list — concatenated (common first) and normalized as one,
-so spelling and dedupe rules are identical for both. The session surface never reads it: the
-list exists for paths whose edit is legitimate work during a session but must pass a judged
-checkpoint when it is promoted into repository history — a judgment chain's own sources are
-the canonical tenant. As the enforcement level is the observer's setting, so is the
-additional scope. There is no subtractive vocabulary: a config line can widen a surface's
-scope, never quietly strip one.
-
-The session surface (the editor-time hook) has no level setting here. What it blocks is the
+**`protectedPaths` is one list for both surfaces.** There is no additive change-set-only scope
+and no surface-level enforcement key in the config. The change-set surface judges the same
+normalized list the session surface does. A violation exits 2 on the session surface; on the
+change-set surface it lands `advised` at exit 0 unless the check runs with `--enforce block`. The
+judge emits only that exit code: whether a commit stops is the user's hook wiring, so a
+telemetry row records the verdict, not the commit's fate — a `blocked` row can sit beside a
+commit that proceeded because the wiring ignored the exit code.
+
+The session surface (the editor-time hook) has no level setting either. What it blocks is the
 judging chain's own protection — `protectedPaths` mutations and mentions on the tool and
 shell axes, the session transcript, an assembly that cannot judge (missing or invalid
 config, unbuilt judge, unparseable payload, a routing that could not answer) — plus any
 entry promoted with `enforce: block`. Every other discipline entry lands `advised` there.
 
-**Declarations that read the session skip on the commit surface when their supply policy is `pass`.**
-A commit has no session to look at, so a declaration whose `sources` bind the transcript — a `precedent`,
-`phase-order`, `turn-locality` or `stated-ground` entry — cannot be judged there; demanding
-evidence a commit cannot carry would block every matching commit with no legitimate way
-through. The declaration's own `supply: { session: 'pass' }` disposes of the absence: when
-its scope matches a staged change it records a `skipped` telemetry event carrying the reason
-token `supply-pass` and lets the commit proceed. The record carries the entry's `id` and the
-change it would have judged, so a gate that did nothing says so in the data — and it appears
-**only when the entry's scope actually matched**. A declaration scoped on the `command`
-source records nothing at all there: a staged diff carries no command line, so no world it
-observes is ever admitted.
-
-This is the same disposition the session surface uses whenever it has no transcript to
-read **and** the declaration's `supply` is `pass`. Without that policy a missing source is
-unjudgeable (exit 2), not an automatic skip.
+**A declaration reaches only the surface that observes its channels.** A transcript reader is
+written in `sessionDisciplines` and is never compiled for a change set; a `changes` reader is
+written in `changeSetDisciplines` and is never compiled for one call. The three lists and the
+rule that places an entry in one of them are in [the three discipline
+lists](#three-lists).
+
+A declaration's `supply` policy still governs a channel the surface registers but the host
+does not prove. A host that carries no session (the Grok adapter) leaves a
+`sources: { session: { transcript: true } }` entry's source absent, and `supply: { session: 'pass' }`
+records a `skipped` telemetry event carrying the reason token `supply-pass` and lets the call
+proceed. Without that policy a missing source is unjudgeable (exit 2), not an automatic skip.
 
 <a id="telemetry"></a>
 ## `telemetry`
@@ -183,12 +154,141 @@ when the token arrives in a message positively identified as human-typed in the
 transcript, so an AI that knows the token still cannot forge one. Witnessed judgments are
 recorded as `witnessed`, never silent.
 
+<a id="three-lists"></a>
+## The three discipline lists
+
+A discipline is written in one of three lists, and which one is a fact about the declaration
+rather than a choice the author makes. A declaration names the evidence channels it reads in
+its own syntax, and a surface observes some channels and not others, so the list follows from
+the channels.
+
+| List | Judged on | What its declarations read |
+|---|---|---|
+| `disciplines` | both surfaces | the changed file itself (`target.path` · `pre` · `post` · `state`) and `file` sources — nothing else. Drafts live here too |
+| `sessionDisciplines` | the session surface only | at least one of `command` · `transcript` · the `sidecar` channel · `actor`, and never `changes` |
+| `changeSetDisciplines` | the change-set surface only | `changes`, and no session channel |
+
+The session surface is one call a host observed before it ran — an adapter hook, or a program
+calling the SDK with an input IR. It carries the command line, the conversation history, the
+spawn-record channel, and the actor, and it does not carry the finished change set. The
+change-set surface is `pdks covenant check --diff` over a change set some producer finished.
+It carries `changes`, and it carries no command line, no history, and no actor.
+
+<a id="channel-to-list"></a>
+### Channel to list
+
+Each channel appears in a declaration in a fixed syntactic position, and the loader reads
+those positions to derive the list.
+
+| Channel | How it appears in a declaration | List |
+|---|---|---|
+| `transcript` | `sources: { session: { transcript: true } }` | `sessionDisciplines` |
+| `channel` | `sources: { spawns: { sidecar: true } }` | `sessionDisciplines` |
+| `command` | `scope: { source: 'command' }`, or `{ op: 'source', of: 'command' }` in any pipeline | `sessionDisciplines` |
+| `actor` | `{ op: 'source', of: 'actor' }` in any pipeline | `sessionDisciplines` |
+| `changes` | `{ op: 'source', of: 'changes' }` in any pipeline | `changeSetDisciplines` |
+| none of the five | the declaration reads the changed file and `file` sources alone | `disciplines` |
+
+A `witness` block's own `extract` is walked with the body's, so a valve reading the transcript
+puts its entry in `sessionDisciplines` like any other transcript reader.
+
+<a id="placement-rule"></a>
+### The placement rule
+
+`disciplines` takes an entry binding none of the five channels, plus every draft.
+`sessionDisciplines` takes an entry binding at least one session channel and not `changes`.
+`changeSetDisciplines` takes an entry binding `changes` and no session channel. Anything else
+is a `ConfigValidationError` at load time, on both surfaces, and the message names the entry,
+the channels it reads, and the list it belongs in:
+
+```text
+disciplines[7] ('merge-is-the-users-call') reads transcript, command: it belongs in sessionDisciplines
+```
+
+Two shapes have no destination to name. A declaration binding both `changes` and a session
+channel is refused outright, because no surface observes both at once:
+
+```text
+sessionDisciplines[2] ('pairs-across-a-session') reads transcript, changes: no surface observes both changes and a session channel
+```
+
+A draft binds nothing — it carries no declaration — so it belongs in `disciplines`, and a
+draft written in either surface list is refused with `a draft belongs in disciplines`.
+
+Ids are unique across all three lists and the three meta-covenant labels (`self-mod` ·
+`shell-mod` · `transcript-mod`): the telemetry label space is one space, and `pdks explain`
+and every label-keyed reader index by the label alone.
+
+<a id="lists-in-practice"></a>
+### What each surface compiles
+
+`pdks covenant check` reading an input IR on stdin compiles `disciplines` followed by
+`sessionDisciplines`; the same command with `--diff` compiles `disciplines` followed by
+`changeSetDisciplines`. `pdks explain` prints both surfaces with each list's name and count in
+the surface header, so the placement of every entry is readable without running a judgment.
+This repository's live config places 11 judged entries and 1 draft in `disciplines`, 13 in
+`sessionDisciplines`, and 1 (`docs-stay-bilingual`) in `changeSetDisciplines` — 24
+registrations on the session surface and 12 on the change-set surface.
+
+```yaml
+disciplines:            # both surfaces
+  - 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:     # the session surface only — reads 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:   # the change-set surface only — reads 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'
+```
+
+Moving an entry between lists is the whole edit: the entry's body is unchanged by the move,
+and the loader is what says whether the new place is the right one.
+
 <a id="disciplines"></a>
 ## `disciplines`
 
 Optional. Each entry is one discipline: a practice the team imposes on itself, declared as
-data. A judged entry carries a `declare` block — the one judged form, a declaration whose
-`scope` lives inside the block — an `id` (the telemetry label), and optionally a `why` (the
+data. Everything in this section applies to an entry in any of the three lists; which list an
+entry is written in is decided by [the placement rule](#placement-rule), and
+`sessionDisciplines` and `changeSetDisciplines` take the same entry shape as `disciplines`
+minus the draft form. A judged entry carries a `declare` block — the one judged form, a
+declaration whose `scope` lives inside the block — an `id` (the telemetry label), and
+optionally a `why` (the
 reason, which travels with the block message the agent reads) and an `enforce` level. The
 closed key set is `id` · `why` · `enforce` · `declare`; any other key is refused.
 
@@ -219,10 +319,10 @@ is one line.
 **`enforce` — the entry's own level.** Optional on any judged entry: `block` or `advise`.
 **Absent means `advise`.** Under `advise` a break is recorded as an `advised` telemetry
 event and the call proceeds (exit 0), with the break message still written to stderr;
-`block` is the promotion — it pins the entry at block. The entry's level composes with the
-surface's (`adapters.git.enforce` on the commit surface; the session surface has none) and
-the lenient side wins — an `advise` on either axis makes the entry advise, and an explicit
-`block` never raises a surface the observer set to advise. An unjudgeable body (never
+`block` is the promotion — it pins the entry at block. The config carries no surface-level
+enforcement key: absent or `advise` means `advised` on both surfaces, `block` means exit 2 on
+the session surface and on a change-set check run with `--enforce block` (the change-set
+surface's default posture is advise for every verdict). An unjudgeable body (never
 built, or one that cannot be loaded) still blocks whatever the level. A draft carries no
 `enforce`; any
 other value is rejected at load time. `pdks explain` prints the level an entry declares
@@ -312,7 +412,14 @@ declaration reads that source, cuts it into lines, keeps the lines a pattern mat
 requires the result to be `empty`. It scopes on `command` so that only shell calls are
 admitted: an Edit carries no command line, and a declaration reading a source its world
 lacks is unjudgeable. A multi-line command is judged line by line, so `^` means the start
-of a line; a pattern that would span a line boundary does not match.
+of a line; a pattern that would span a line boundary does not match. Heredoc bodies and
+herestring words are not part of the source: bash passes them to the command as stdin
+data rather than executing them, so a banned token quoted inside one is not a match, and
+whether that data becomes a file write is judged by the shell-evidence path instead. Text
+bash expands first stays in the source — a body under an unquoted delimiter that carries
+`$` or a backtick, and a herestring word holding a substitution — as does a line the
+tokenizer could not finish reading. What the receiving command does with its stdin is not
+judged: a script fed to an interpreter is data to bash and a program to the interpreter.
 
 ```yaml
   - id: 'hooks-stay-armed'
@@ -338,8 +445,9 @@ declaration the user turns and tool calls as one snapshot, `toolUses` picks the
 `matches` finds the required one; `nonEmpty` is the verdict. A call the covenant blocked,
 one a human refused, and one that simply failed are not precedent. The pattern is matched
 anywhere in a command line — a line that merely mentions the command counts, a declared
-limit. `supply: { session: 'pass' }` is what makes the commit surface record `skipped`
-instead of blocking every matching commit.
+limit. `supply: { session: 'pass' }` is what disposes of an absent session on a host that proves
+none; an entry reading the transcript is written in `sessionDisciplines`, so a change set never
+compiles it at all.
 
 ```yaml
   - id: 'dependency-needs-npm-view'
@@ -411,16 +519,15 @@ Each observation is judged as one **world** with seven source names: `target.pat
 repo-relative path), `pre` and `post` (the file's text on the side the change carries —
 a creation has no `pre`, a deletion no `post`), `state` (`{ pre, post }`, present only
 on a modification), and `changes` (every path the observation changes — the one call on the
-session surface, the whole staged set on the commit surface), and `command` (the shell
+session surface, the whole staged set on the change-set surface), and `command` (the shell
 call's command line — present on a shell call only, and a shell call that changes no file
 is one world of its own, so a declaration scoped on `command` sees it while one scoped on
 `target.path` does not), and `actor` (the observation's actor — described below). A
-declaration that reads `changes` is judged only where the whole change set is observed: the
-session surface records it `skipped`, the same disposition the commit surface gives a
-declaration that reads the session, because one call can never carry the other half of a
-pair. This repository's live config
-carries one — `docs-stay-bilingual`, an `implies` over the `.md`/`.ko.md` pair, advised
-on the commit surface when one side is staged without the other. A declaration that needs a
+declaration that reads `changes` is written in `changeSetDisciplines` and compiled only where
+the whole change set is observed, because one call never carries the other half of a pair.
+This repository's live config carries one — `docs-stay-bilingual`, an `implies` over the
+`.md`/`.ko.md` pair, advised on the change-set surface when one side is staged without the
+other. A declaration that needs a
 file outside the target names it in a `sources` block, `sources: { en: { file:
 'locales/en.json' } }`, and reads it as `{ op: 'source', of: 'en' }`; the path is
 repo-relative (no leading `/`, no `..` segment) and the name may not be one of the seven. The
@@ -430,16 +537,16 @@ touches is read from the change's `post`, so both surfaces judge the same text.
 kind, `sources: { spawns: { sidecar: true } }`, names the session's spawn-record channel
 instead of a path — the subagent records the host keeps beside the transcript, supplied as
 one JSON array; where the channel lives is the surface's fact, so the value is the marker
-`true`, and on the commit surface (which has no session) the channel is always absent. A
+`true`, and on the change-set surface (which has no session) the channel is always absent. A
 third kind, `sources: { session: { transcript: true } }`, names the session's own
 conversation history — the user turns and tool calls the surface reads, handed to the
 declaration as one snapshot whose entries carry their
 observation ordinal; the history steps (`toolUses`, `userTexts`, `first`, `ageMs`) read it, and
 `agentType` reads the parsed sidecar. This repository's live config carries one —
-`tests-before-implementation`, an `ordered` over the ordinals of two subagent spawns, which
-the commit surface (no session) records `skipped`. The seventh fixed name, `actor`, is the
+`tests-before-implementation`, an `ordered` over the ordinals of two subagent spawns, written
+in `sessionDisciplines`. The seventh fixed name, `actor`, is the
 observation's actor — `{ agentType }` inside a subagent, `{}` in the main session, absent
-where the surface proves none (the commit surface) — read as `{ op: 'source', of: 'actor' }`
+where the surface proves none (the change-set surface) — read as `{ op: 'source', of: 'actor' }`
 followed by `select` on `agentType`; it derives the `actor` axis the `producer-owned` and
 `actor-scope` mechanisms require, and this repository's live config carries one of each
 (`tests-are-the-writers`, `commits-come-from-the-main-session`). A `supply` key must name

package/dist/docs/reference/packages/adapter-claude-code.ko.md

@@ -2,11 +2,11 @@
 
 [English](adapter-claude-code.md) · **한국어**
 
-> **세션 표면의 번역기**입니다. PreToolUse 페이로드가 약속(covenant) 입력 IR이 되고,
-> 판정기가 읽는 파일 변경 증거와 대화 기록(transcript) 통로가 함께 실립니다.
+> **Claude Code의 설치 단위**입니다. PreToolUse 페이로드가 약속(covenant) 입력 IR이 되고,
+> 판정기가 읽는 파일 변경 증거와 대화 기록(transcript) 통로가 함께 실립니다. 세션 표면을
+> 프로젝트에 설치하는 것도 이 패키지가 합니다.
 >
-> 알파입니다. 통합 패키지의 의존성으로 설치되므로 일반 사용자가 따로 설치하거나 불러올 필요는 없습니다. 세션 표면은
-> [`polydeukes/claude-code`](polydeukes.ko.md#session-export)를 통해 닿습니다.
+> 알파입니다. `polydeukes`와 함께 설치하며, `polydeukes`는 이 패키지의 `peerDependency`입니다.
 
 <a id="ownership"></a>
 ## 담당하는 기능
@@ -16,15 +16,22 @@ Claude Code의 입력을 공통 형식으로 번역합니다. 에이전트와
 
 | 단위 | 하는 일 |
 |---|---|
+| `pdks-claude-code` 실행 파일 | 하위 명령 하나 `pdks-claude-code init`으로 프로젝트에 세션 표면을 등록합니다 |
+| `runHook` | PreToolUse 페이로드 하나를 입력 IR로 바꾸고 판정기를 스폰합니다 |
 | 페이로드 상향 번역 | 원본 PreToolUse 페이로드가 `CovenantInput`이 됩니다 |
 | 예상 변경 후 상태 | 편집이 적용되면 파일이 무엇을 담을지 디스크를 건드리지 않고 계산합니다 |
 | 파일 변경 증거 | 디스크의 변경 전 상태와 예상 변경 후 상태를 짝지어 변경 증거를 만듭니다 |
 | 대화 기록(transcript) 제공자 | 세션 JSONL 파일을 `CanonicalTranscript`로 바꿉니다 |
-| 텔레메트리 배선 | 전체 처리 경로에서 호출이 기록되도록 연결합니다 |
 
-이 패키지는 약속(covenant) 패키지를 결코 불러오지 않습니다. 판정 전달 함수는 통합 패키지가
-**주입**하고, 그래서 의존은 코어를 통해 한 방향으로만 흐릅니다. `@polydeukes/core`는
-`peerDependency`로 부릅니다. 판정기와 같은 어휘를 공유하며 별도 사본을 설치하지 않습니다.
+생성된 훅 위임자가 불러오는 것이 `runHook({ repoRoot })`입니다. `tools`와 `session` 증거를
+실은 입력 IR을 만든 뒤 `repoRoot`에서 `pdks covenant check --enforce block`을 스폰하고 그
+자식 프로세스의 종료 코드를 그대로 돌려줍니다. 판정은 그 자식 프로세스가 하며, 이 패키지에는
+판정 코드가 없습니다.
+
+**이 패키지는 텔레메트리 행을 쓰지 않습니다.** 스폰 전에 실패하면 그 사실을 한 줄로 만들어
+`pdks`의 표준 입력으로 보내고, `pdks`가 fail-closed 행을 기록합니다. 호출 하나에 행 하나는
+그대로입니다. 판정기를 불러오지도 않습니다. `polydeukes`와 `@polydeukes/core` 모두
+`peerDependencies`이므로 어휘와 판정기를 공유할 뿐 사본을 따로 설치하지 않습니다.
 
 <a id="translation"></a>
 ## 페이로드 번역과 세 축
@@ -62,9 +69,22 @@ Claude Code의 입력을 공통 형식으로 번역합니다. 에이전트와
 <a id="consumer-contract"></a>
 ## 사용자와의 접점
 
-- **생성된 훅.** 통합 패키지의 `claude-code` 서브패스를 통해 이 어댑터를 불러옵니다. 패키지를 갱신하면 실행할 구현도 바뀌지만 훅 파일은 그대로입니다.
+프로젝트 루트에서 두 줄이면 Claude Code 세션 표면이 섭니다.
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npx pdks-claude-code init
+```
+
+`pdks-claude-code init`은 프로젝트에서 `polydeukes`를 찾고, 에이전트와 무관한 초기 파일을
+만드는 `pdks init`을 스폰한 뒤, Claude Code 산출물 넷을 기존 파일을 덮지 않고 씁니다.
+다시 실행하면 이미 있는 산출물마다 `skipped`로 보고하고 아무것도 덮어쓰지 않습니다.
+산출물 전체 목록은 [`pdks init`](../cli/init.ko.md#init-claude-code)에 있습니다.
+
+- **생성된 훅.** 이 패키지의 `runHook`을 불러옵니다. 패키지를 갱신하면 실행할 구현도 바뀌지만
+  훅 파일은 그대로입니다.
 
-일반 사용자가 직접 불러올 필요는 없으며 별도 설정 네임스페이스도 없습니다.
+별도 설정 네임스페이스는 없습니다.
 
 <a id="limits"></a>
 ## 선언된 한계
@@ -72,7 +92,7 @@ Claude Code의 입력을 공통 형식으로 번역합니다. 에이전트와
 - **자식 프로세스의 쓰기는 관측 밖입니다.** 이 표면이 판정하는 것은 **선언된 도구
   호출**입니다. 프로세스를 띄우고 그 프로세스가 파일을 쓰는 명령은, 테스트 러너든 빌드든,
   명령에 대해 판정되지 자식이 한 일에 대해 판정되지 않습니다. 추적되는 파일에 대해서는
-  커밋 표면에서 결과를 별도로 관측할 수 있습니다.
+  변경 집합 표면에서 결과를 별도로 관측할 수 있습니다.
 - **증거는 후상태를 계산할 수 있는 곳에만 있습니다.** 변형 도구 넷이 전부 증거를 내고
   노트북도 그렇습니다. `NotebookEdit`는 셀 단위 `modify` 증거를 냅니다. 증거가 없는 것은
   이 어댑터가 해소하지 못하는 페이로드입니다. 읽을 수 없거나 파싱되지 않는 노트북, 이름을
@@ -81,3 +101,10 @@ Claude Code의 입력을 공통 형식으로 번역합니다. 에이전트와
   경로가 언급됐는지 대조합니다.
 - **저장소 밖 조상은 범위 밖입니다.** 프로젝트 루트 위의 경로는 여기서 관측하지 않습니다.
   그 범위는 에이전트 실행 환경의 권한 정책으로 제한해야 합니다.
+- **`polydeukes`를 찾지 못하면 행이 남지 않습니다.** 프로젝트에서 우산 패키지를 찾지 못하면
+  스폰할 프로세스도, 기록할 로그 경로도 없습니다. 훅은 stderr에 한 줄을 남기고 종료 코드
+  `2`를 내며 텔레메트리 로그에는 아무것도 추가되지 않습니다. 스폰 전 실패 가운데 이 경우만
+  그렇고, 나머지는 모두 `pdks`에 도달해 행을 남깁니다.
+- **Grok는 `@polydeukes/adapter-grok`로 설치합니다.** 그 패키지가 자기 위임자와 명부를
+  씁니다. 두 세션 어댑터를 한 프로젝트에 함께 설치하면 호출마다 판정기가 두 번 실행될 수
+  있습니다.

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

@@ -2,12 +2,11 @@
 
 **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#session-export).
+> Alpha. Install it next to `polydeukes`, which it names as a `peerDependency`.
 
 <a id="ownership"></a>
 ## What this package owns
@@ -18,16 +17,23 @@ 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
@@ -66,17 +72,29 @@ there is no separate precedent evaluator in this package. The grammar is in
 <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.
@@ -86,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`에 도달해 행을 남깁니다.