polydeukes 0.6.0 → 0.7.1

package/dist/docs/concepts/judgment.md

@@ -0,0 +1,113 @@
+# How a judgment works
+
+**English** · [한국어](./judgment.ko.md)
+
+Polydeukes checks a declared practice against evidence a connected surface supplies. It does not
+infer that a practice was followed merely because an agent says so. A passing result is bounded
+by the files, calls, and history actually observed.
+
+<a id="terms"></a>
+## Covenant, discipline, and surface
+
+A **covenant** is a shared promise about the work. A **discipline** is one practice registered
+in the project's configuration. The **judge** evaluates evidence; a **verdict** records the result.
+
+A **surface** determines when evidence is gathered:
+
+- The session surface observes a supported host's tool call before it runs.
+- The change-set surface observes staged changes, working-tree changes, or a revision range.
+
+Installing the package is not the same as connecting a surface. Instructions an agent reads are
+not automatic interception of its tools. Use a supported integration and verify an actual call.
+See [connect the surfaces](../how-to/connect-surfaces.md).
+
+<a id="declarations"></a>
+## Declarations and their limits
+
+A judged discipline has an `id` and a `declare` block. Its scope selects observations; its sources
+provide evidence; extraction steps transform that evidence; relations identify elements that
+break the promise. `why` explains the practice but is not executable logic.
+
+The fixed sources are `target.path`, `pre`, `post`, `state`, `changes`, `command`, and `actor`.
+Additional bindings can read a named file, a sidecar channel, or session history. A declaration
+can only use sources the surface supplies. The same declaration can therefore be judged on one
+surface and skipped, or not match its scope, on another.
+
+`state` pairs before and after values on a modification. It is not persistent state across runs,
+an assertion that a workflow advanced, or proof that a command succeeded. The `unchanged`
+relation consumes a paired extraction; other relations consume single extractions. Additions
+and deletions do not carry that modification pair. Missing evidence follows the declaration's
+`supply` policy, not a fabricated empty file.
+
+A `draft: true` entry records a practice that has not been promoted into a declaration. It does
+not judge or emit a telemetry row. Do not use a draft merely because a valid declaration needs
+more testing. Conversely, do not invent a step or mechanism when the grammar lacks the evidence
+or comparison you need. [Write disciplines](../how-to/write-disciplines.md) demonstrates a
+working locale key comparison and a genuinely unsupported promise.
+
+<a id="relations"></a>
+## Seven relations
+
+Relations return a list of elements for which the comparison fails. An empty list means the
+relation holds; it is not the same as the `empty` relation's requirement.
+
+| Relation | Requirement |
+|---|---|
+| `empty` | The extraction contains no items. |
+| `nonEmpty` | The extraction contains at least one item. |
+| `equal` | Both extracted collections agree. |
+| `subset` | Every item on the left is present on the right. |
+| `implies` | The left-hand key requirements have corresponding keys on the right. |
+| `ordered` | The extracted sequence satisfies the declared ordering. |
+| `unchanged` | Values at shared keys agree before and after a modification. |
+
+Keys and values have different roles. Keys identify items for keyed comparisons and combination;
+values are compared structurally. A comparison of translation keys does not compare translated
+text. Extraction decides which distinction a relation can see.
+
+<a id="mechanisms"></a>
+## Eighteen mechanism names
+
+A mechanism names the purpose and allowed shape of a declaration, not a new comparison operator.
+The compiler derives the evidence axes and relations from the syntax and checks that they fit
+the chosen mechanism.
+
+`pairing`, `companion`, `monotonic-order`, `fingerprint-sync`, `producer-owned`,
+`self-absolution-ban`, `actor-scope`, `precedent`, `phase-order`, `turn-locality`, `stated-ground`,
+`controlled-vocabulary`, `naming`, `added-only`, `one-way-marker`, `delegated-scope`,
+`scoped-valve`, and `forbidden-command` are the closed catalog.
+
+`delegated-scope` is **reserved**, not a usable declaration in this release. `scoped-valve`
+requires its own witness block; `naming` scopes on `target.path`; `forbidden-command` scopes on
+`command`. See the [configuration reference](../reference/configuration/index.md#disciplines)
+for syntax and extraction steps.
+
+<a id="verdicts"></a>
+## Interpret the result, not just the exit code
+
+| Record | Meaning |
+|---|---|
+| `passed` | The observed input was judged and upheld the covenant. |
+| `blocked` | The observed input broke the covenant and was refused. |
+| `witnessed` | A blocking judgment was allowed through its witness valve. |
+| `advised` | A violation was recorded without stopping the operation. |
+| `skipped` | The absence of a judgment was recorded. It is not a pass. |
+| `unattributed` | Baseline comparison found protected movement without an explaining judgment. |
+
+The final record is a comparison finding, not a judge's verdict. Telemetry uses the same event
+column to record it. An `advised` or `skipped` observation may exit 0; that does not establish
+that the practice was followed. An empty observation set establishes nothing about other files.
+
+<a id="enforcement-and-witness"></a>
+## Enforcement and witness
+
+Discipline entries default to `advise`. Promote an entry with `enforce: block` only after checking
+both its violating and valid cases. The change-set surface's level and an entry's level compose:
+**the lenient side wins**. Setting only the surface to `block` does not promote every entry.
+Protection of the judging chain is separate from ordinary discipline entries.
+
+The witness valve is consulted after a blocking judgment, never instead of judgment. Session
+and commit witnesses have different delivery mechanisms and evidence. A commit prompt cannot
+approve a pending session call. See [witness and
+recovery](../how-to/connect-surfaces.md#witness-and-recovery)
+and [troubleshooting](../troubleshooting.md).

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

@@ -0,0 +1,99 @@
+# 프로젝트 설정하기
+
+[English](./configure-project.md) · **한국어**
+
+프로젝트 루트에 설정 파일 하나를 두고, 제품 소스의 범위와 검증 명령을 정합니다.
+위반이 생겼을 때 작업을 계속할지 차단할지도 선택합니다. 아직 설치하지 않았다면
+[첫 판정 따라 하기](../tutorials/first-judgment.ko.md)부터 시작하세요.
+
+<a id="find-the-config"></a>
+## 설정 파일 찾기
+
+Polydeukes는 프로젝트 루트 바로 아래에서 `polydeukes.config.yaml`, `polydeukes.config.yml`,
+`polydeukes.config.json` 중 하나를 읽습니다. 상위 디렉터리까지 찾아 올라가지는 않습니다.
+
+- 파일이 없으면 설정이 필요한 명령은 실패합니다. 기본값으로 대신 실행하지 않습니다.
+- 파일이 여러 개면 필요한 내용을 합친 뒤 하나만 남깁니다.
+- 발견한 설정 파일은 자동으로 `protectedPaths`에 포함됩니다. 설정 자체를 바꾸는 작업도
+  보호 대상입니다.
+
+`pdks docs`는 프로젝트 설정 없이 사용할 수 있습니다. 필드별 제약은
+[설정 참조](../reference/configuration/index.ko.md)에서 확인하세요.
+
+<a id="add-ide-support"></a>
+## 편집기에서 스키마로 검사하기
+
+YAML 파일에는 다음 줄을 넣어 설치된 스키마를 편집기에서 사용합니다.
+
+```yaml
+# yaml-language-server: $schema=node_modules/polydeukes/dist/schema/polydeukes.schema.json
+```
+
+이 경로는 설정 파일을 기준으로 한 상대 경로이지 모듈 이름이 아닙니다. 설정 파일이 모노레포
+하위 패키지에 있고 의존성은 워크스페이스 루트에 설치된 경우, 올라가는 층수를 직접 셉니다.
+
+```yaml
+# yaml-language-server: $schema=../../node_modules/polydeukes/dist/schema/polydeukes.schema.json
+```
+
+`pdks init`은 생성한 설정 파일을 기준으로 기본 경로의 스키마를 찾을 수 있을 때만 스키마 줄을
+넣습니다. `pdks-claude-code init`이 이 명령을 대신 실행합니다. 이 줄이 없다면 스키마 위치에 맞춰 상대 경로를 직접 추가하세요.
+`$schema` 경로를 찾지 못하면 편집기에 오류가 표시되지 않은 채 스키마 검증이 중단될 수 있습니다.
+
+우산이 아니라 `@polydeukes/core`를 직접 설치했다면 그 사본을 가리킵니다.
+
+```yaml
+# yaml-language-server: $schema=node_modules/@polydeukes/core/schema/polydeukes.schema.json
+```
+
+편집기가 정적으로 읽는 파일 경로입니다. 런타임에 스키마를 읽는 코드는 exports 서브패스
+`@polydeukes/core/schema.json`을 씁니다. JSON 설정에는 `$schema` 속성을 쓸 수 있습니다.
+로더는 이 속성을 허용하되 실제 사용할 설정에서는 제외합니다.
+
+<a id="fill-the-language-block"></a>
+## 언어 블록 채우기
+
+`languages`에는 항목이 하나 이상 있어야 합니다. 각 항목에 제품 소스의 경로와 검증 명령을
+적습니다.
+
+```yaml
+languages:
+  typescript:
+    productionGlob: 'src/**'
+    testCmd: 'pnpm test'
+```
+
+언어 이름은 프로젝트에서 정하는 키입니다. 설치기가 만든 임시 값을 실제 경로와 명령으로
+바꾸세요. 블록을 지우거나 비워 두면 유효하지 않은 설정이 됩니다. 이 설정을 읽는 것만으로
+검증 명령이 실행되지는 않습니다.
+
+<a id="choose-advise-or-block"></a>
+## 권고와 차단 중 선택하기
+
+| 설정 | 위반 시 동작 |
+|---|---|
+| 항목의 `enforce: advise`(또는 적지 않음) | 권고를 기록하고 호출을 진행합니다. 종료 코드 0입니다. |
+| 항목의 `enforce: block` | 판정한 호출을 거부합니다. 종료 코드 2입니다. |
+
+**적지 않으면 `advise`입니다.** 설정에는 표면 단위의 강제 수준 키가 없습니다. 강제 수준은
+각 항목이 가지며 적지 않은 항목을 승격하는 설정도 없습니다. 설정된 경로의 보호는 이 항목별
+기본값과 별개입니다. 세션 표면에서는 차단하고, 변경 집합 표면에서는 명령을 `--enforce block`으로
+실행하지 않는 한 `advised`로 기록합니다. 조립 단계에서 오류가 나면 종료 코드 2를
+반환합니다.
+
+`protectedPaths`는 두 표면에 모두 적용하는 최상위 목록 하나입니다. 변경 집합 표면에서 판정기는
+종료 코드만 내므로, 커밋을 멈출지는 훅 배선이 정합니다.
+[표면 연결과 증인](./connect-surfaces.ko.md#witness-and-recovery)에서 자세히 설명합니다.
+
+<a id="confirm-the-project"></a>
+## 설정 확인하기
+
+- `pdks explain`은 설정을 읽고 등록된 항목을 보여 줍니다. 변경을 판정하지는 않습니다.
+- `git diff HEAD | pdks covenant check --diff`는 아직 커밋하지 않은 변경 전부를 판정합니다.
+- `git diff --cached | pdks covenant check --diff`는 스테이징한 변경을 관측합니다. pre-commit
+  훅이 쓰는 형태입니다. 이 명령은 사람에게 묻지 않고 종료 코드 0 또는 2만 내며, 커밋을
+  멈출지는 훅 배선이 정합니다.
+
+종료 코드와 함께 stderr와 텔레메트리도 확인하세요. 권고나 일부 미판정도 종료 코드 0을
+반환합니다. 조립에 실패했다면 규율을 시험하기 전에 오류가 지목한 설정이나 빠진 패키지부터
+확인하세요.

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

@@ -0,0 +1,98 @@
+# Configure the project
+
+**English** · [한국어](./configure-project.ko.md)
+
+Keep one configuration file at the project root, define the production files and verification
+command, and choose how violations should affect work. Start with the
+[first-judgment tutorial](../tutorials/first-judgment.md) if the package is not installed yet.
+
+<a id="find-the-config"></a>
+## Find the config file
+
+Polydeukes reads exactly one of `polydeukes.config.yaml`, `polydeukes.config.yml`, or
+`polydeukes.config.json` directly under the project root. It does not search parent directories.
+
+- With no file, commands that need configuration fail rather than silently use defaults.
+- With several files, merge the intended content and keep only one.
+- The discovered file automatically joins `protectedPaths`, so changing the configuration itself
+  is subject to protection.
+
+`pdks docs` does not need project configuration. Consult the
+[configuration reference](../reference/configuration/index.md) for exact field constraints.
+
+<a id="add-ide-support"></a>
+## Add IDE support
+
+For YAML, add this line so the editor can use the installed schema:
+
+```yaml
+# yaml-language-server: $schema=node_modules/polydeukes/dist/schema/polydeukes.schema.json
+```
+
+The path is relative to the configuration file, not a module specifier. When the config sits in a
+monorepo sub-package whose dependencies installed at the workspace root, count the levels up:
+
+```yaml
+# yaml-language-server: $schema=../../node_modules/polydeukes/dist/schema/polydeukes.schema.json
+```
+
+`pdks init` — which `pdks-claude-code init` runs for you — adds the schema line only when the
+default path resolves relative to the generated config. If the line is absent, add a relative path
+to the installed schema yourself.
+An unresolvable `$schema` can disable editor validation without displaying an error.
+
+If you installed `@polydeukes/core` directly rather than the umbrella, name its copy:
+
+```yaml
+# yaml-language-server: $schema=node_modules/@polydeukes/core/schema/polydeukes.schema.json
+```
+
+That is a file path an editor reads statically. Code that reads the schema at runtime uses the
+exports subpath `@polydeukes/core/schema.json` instead. JSON configurations can use a `$schema`
+property; the loader accepts it but leaves it out of the resolved configuration.
+
+<a id="fill-the-language-block"></a>
+## Fill the language block
+
+`languages` must contain at least one entry. Each entry specifies production paths and a
+verification command:
+
+```yaml
+languages:
+  typescript:
+    productionGlob: 'src/**'
+    testCmd: 'pnpm test'
+```
+
+Language names are project-defined keys. Replace the installer's placeholder with meaningful
+paths and a command; deleting the block or leaving it empty makes the configuration invalid.
+Loading this setting does not itself run the command.
+
+<a id="choose-advise-or-block"></a>
+## Choose advise or block
+
+| Setting | Effect on a violation |
+|---|---|
+| `enforce: advise` on an entry (or absent) | Record advice and let the call proceed, exit 0. |
+| `enforce: block` on an entry | Refuse the judged call, exit 2. |
+
+**Absent means `advise`.** There is no surface-level enforcement key in the config: each entry
+carries its own level and nothing promotes an absent one. Protection of configured paths is
+separate from that per-entry default — it blocks on the session surface, and on the change-set
+surface it lands `advised` unless the command is run with `--enforce block`. Assembly errors
+still exit 2.
+
+`protectedPaths` is a single top-level list that applies to both surfaces. On the change-set
+surface the judge only emits the exit code; whether the commit stops is your hook wiring.
+See [surface connection and witnesses](./connect-surfaces.md#witness-and-recovery).
+
+<a id="confirm-the-project"></a>
+## Confirm the project
+
+- `pdks explain` loads the configuration and shows registrations without judging a change.
+- `git diff HEAD | pdks covenant check --diff` judges everything not yet committed.
+- `git diff --cached | pdks covenant check --diff` observes staged changes — the pre-commit shape.
+  The command never prompts; it exits 0 or 2 and your hook wiring decides the commit's fate.
+
+Check stderr and telemetry as well as the exit code. Advice and some skipped observations exit 0.
+If assembly fails, diagnose the named configuration or missing package before testing a discipline.

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

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

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

@@ -0,0 +1,121 @@
+# Connect the surfaces
+
+**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 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 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 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
+package upgrades the judge without rewriting the hook file.
+
+The installer writes `.claude/settings.json` only by merging. Existing hooks and permissions stay in
+place. It also writes `.claude/rules/polydeukes.md`, which tells the agent to use `pdks docs`
+instead of searching the web, and `.claude/skills/discipline-draft/SKILL.md`, which turns a
+described problem into either a judged entry or a draft entry.
+
+<a id="grok"></a>
+## Grok session surface
+
+Use this when the project is developed in 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 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. 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="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 `git diff HEAD | pnpm exec pdks covenant check --diff` when you want the same judgment
+   on demand.
+
+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
+      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
+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
+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
+`chmod +x .git/hooks/pre-commit`. Integrate with an existing hook instead of overwriting it.
+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.
+
+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
+
+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.
+- 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
+and the session valve does not work with Grok's current transcript format.
+
+If the hook was not picked up in Grok, reload the Hooks tab or start a new session. If the judge
+cannot be loaded, reinstall the package or rebuild the workspace and try again.
+
+<a id="what-to-check"></a>
+## What to check after wiring
+
+- `pdks explain` shows which registrations each surface assembled.
+- `.polydeukes/roi.log` records the rows that the surfaces wrote.
+- `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.