polydeukes 0.5.0 → 0.6.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 commit 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 commit 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 claude-code`는 생성한 설정 파일을 기준으로 기본 경로의 스키마를 찾을 수 있을 때만
+스키마 줄을 넣습니다. 이 줄이 없다면 스키마 위치에 맞춰 상대 경로를 직접 추가하세요.
+`$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>
+## 권고와 차단 중 선택하기
+
+| 설정 | 위반 시 동작 |
+|---|---|
+| `adapters.git.enforce: advise` | 권고를 기록하고 커밋을 계속합니다. 증인 입력은 요청하지 않습니다. |
+| `adapters.git.enforce: block` | 차단 판정을 받은 작업을 거부합니다. 스테이징 검사에서는 TTY로 증인 입력을 받을 수 있습니다. |
+
+일반 규율(discipline) 항목에도 자체 강제 수준이 있으며 기본값은 `advise`입니다.
+**두 수준 중 더 관대한 쪽을 따릅니다.** 어댑터만 `block`으로 설정해도 일반 항목이 자동으로
+차단 수준으로 바뀌지는 않습니다. 설정된 경로의 보호는 이 항목별 기본값과 별개입니다.
+조립 단계에서 오류가 나면 어느 수준에서든 종료 코드 2를 반환합니다.
+
+최상위 `protectedPaths`는 두 표면에 모두 적용합니다. `adapters.git.protectedPaths`에는
+커밋할 때만 보호할 경로를 추가합니다. 세션 중에는 편집을 허용하되 커밋할 때 보호하려는
+파일에 사용하세요. [표면 연결과 증인](./connect-surfaces.ko.md#witness-and-recovery)에서
+자세히 설명합니다.
+
+<a id="confirm-the-project"></a>
+## 설정 확인하기
+
+- `pdks explain`은 설정을 읽고 등록된 항목을 보여 줍니다. 변경을 판정하지는 않습니다.
+- `pdks covenant check --worktree`는 HEAD와 디스크를 비교합니다. 아직 Git에 등록하지 않은
+  파일도 무시 대상이 아니면 포함합니다.
+- `pdks covenant check`는 스테이징한 변경을 관측합니다. 차단 결과가 나고 TTY를 사용할 수
+  있을 때 증인 입력을 요청할 수 있습니다. 어댑터가 `block`이라는 이유만으로 묻지는 않습니다.
+
+종료 코드와 함께 stderr와 텔레메트리도 확인하세요. 권고나 일부 미판정도 종료 코드 0을
+반환합니다. 조립에 실패했다면 규율을 시험하기 전에 오류가 지목한 설정이나 빠진 패키지부터
+확인하세요.

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

@@ -0,0 +1,95 @@
+# 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 claude-code` 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 |
+|---|---|
+| `adapters.git.enforce: advise` | Record advice and let the commit continue, without a witness prompt. |
+| `adapters.git.enforce: block` | Refuse a blocking judgment; the staged path can offer a TTY witness prompt. |
+
+An ordinary discipline also has its own level, defaulting to `advise`. **The lenient level wins.**
+Setting only the adapter to `block` does not promote an ordinary entry. Protection of configured
+paths is separate from that per-entry default. Assembly errors still exit 2 at either level.
+
+Top-level `protectedPaths` applies to both surfaces. `adapters.git.protectedPaths` adds commit-only
+paths. Use the latter for files that may be edited in a session but need protection when committed.
+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.
+- `pdks covenant check --worktree` compares HEAD with disk, including untracked, non-ignored files.
+- `pdks covenant check` observes staged changes. A blocking result can prompt only when a TTY is
+  available; the command does not prompt merely because the adapter is set to `block`.
+
+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,115 @@
+# 표면 연결하기
+
+[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`. 일회성 `npx` 실행만으로는
+   부족합니다. 두 표면 모두 프로젝트에 설치된 패키지에서 판정기를 불러옵니다.
+2. 프로젝트를 배선합니다. `pnpm exec 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`.
+2. 프로젝트를 배선합니다. `pnpm exec pdks init grok`.
+3. 설치가 끝나면 Hooks 탭을 다시 불러오거나 새 세션을 엽니다.
+
+Grok 프로젝트에는 `.grok/hooks/` 아래에 훅 JSON 파일이 생깁니다. Claude 훅이 이미 있으면
+Grok의 `command`도 그 파일을 가리킵니다. `.claude/settings.json`도 있다면 같은 `command`를
+등록한 Claude 항목에 맞춰 Grok의 `matcher`를 설정합니다. 두 값이 모두 같아야 Grok가 중복 등록을
+하나로 처리해 판정기를 두 번 실행하지 않기 때문입니다.
+새 등록의 제한 시간은 60초입니다. Grok 호스트의 기본값은 5초이며, 훅 실행이 시간 초과로
+끝나면 해당 호출을 차단하지 않습니다(fail-open).
+
+Grok는 세션 증인 밸브에 필요한 Claude 형식의 인간 메시지를 공급하지 않습니다. 대화 기록은
+Claude JSONL이 아니라 ACP `updates.jsonl`입니다.
+의도한 편집이 차단되면 자신의 터미널에서 수행하세요. 커밋 표면의 증인 프롬프트는 해당
+커밋에만 적용되며, 차단된 Grok 도구 호출을 허용하지는 않습니다.
+
+<a id="commit-surface"></a>
+## 커밋 표면
+
+스테이징한 변경을 이력으로 기록하기 전에 Git에서 판정하려면 이 표면을 사용합니다.
+
+1. 프로젝트 루트에 `polydeukes.config.yaml`을 만듭니다.
+2. pre-commit 훅을 추가합니다.
+3. 필요할 때는 `pnpm exec pdks covenant check`를 직접 돌려 같은 판정을 봅니다.
+
+lefthook 예시는 다음과 같습니다.
+
+```yaml
+pre-commit:
+  commands:
+    covenant:
+      priority: 1
+      interactive: true
+      run: ./node_modules/.bin/pdks covenant check
+```
+
+husky 예시는 다음과 같습니다.
+
+```sh
+# .husky/pre-commit
+./node_modules/.bin/pdks covenant check
+```
+
+일반 git 훅으로 연결해도 됩니다.
+
+```sh
+#!/bin/sh
+./node_modules/.bin/pdks covenant check
+```
+
+일반 훅은 `.git/hooks/pre-commit`으로 저장한 뒤 `chmod +x .git/hooks/pre-commit`으로
+실행 권한을 줍니다. 기존 훅이 있다면 덮어쓰지 말고 호출을 추가하세요. lefthook은 패키지
+관리자로 설치하고 YAML을 저장한 뒤 훅 설치 명령을 실행합니다. husky는 git이 찾을 수 있도록
+husky 설치기로 `.husky/pre-commit`을 저장하세요.
+
+`adapters.git.enforce: advise`이면 위반을 `advised`로 기록하고 stderr에 알린 뒤 커밋을
+허용합니다. `block`이면 보호 경로 위반과 `enforce: block`으로 지정한 항목의 위반을
+차단할 수 있습니다. 일반 항목의 기본값은 여전히 `advise`이며 표면 설정이 이를 승격하지
+않습니다. 증인이 설정돼 있고 터미널에 연결된 경우, 스테이징 검사에서 `/dev/tty` 프롬프트를
+제공합니다. `--worktree`와 `--range`는 프롬프트 없이 보고합니다. 조립 실패는 어느 강제
+수준에서도 종료 코드 2를 반환합니다.
+
+<a id="witness-and-recovery"></a>
+## 증인과 회복
+
+증인 토큰은 두 표면에서 같은 뜻이지만 전달 방식은 다릅니다.
+
+- 세션 표면에서는 대화 메시지 첫 줄에 토큰만 단독으로 넣습니다.
+- 커밋 표면에서는 TTY 프롬프트에 전체 토큰을 입력합니다.
+
+밸브는 판정 결과가 차단일 때 확인합니다. 의도한 편집 전에 토큰을 입력해도 되며, 먼저
+실패하는 요청을 보낼 필요는 없습니다. 정상 판정은 바꾸지 않고, 현재 Grok 대화 기록
+형식에서는 세션 밸브를 사용할 수 없습니다.
+
+Grok가 훅을 아직 읽지 못했다면 Hooks 탭을 다시 불러오거나 새 세션을 여세요. 판정기를 적재할 수 없다면 패키지를 다시 설치하거나 워크스페이스를 다시 빌드한 뒤
+시도하세요.
+
+<a id="what-to-check"></a>
+## 배선한 뒤 확인할 것
+
+- `pdks explain`은 각 표면이 어떤 등록을 조립했는지 보여 줍니다.
+- `.polydeukes/roi.log`는 표면이 남긴 행을 기록합니다.
+- `pdks covenant check --worktree`는 작업 뒤에 쓰기 좋은 즉시 확인 명령입니다.
+- `pdks covenant check --range <base>..<head>`는 PR 전에 쓰기 좋은 형태입니다.

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

@@ -0,0 +1,118 @@
+# 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 commit surface.
+
+The two surfaces share the same config vocabulary, but they answer different moments. Use the
+session surface when an AI partner is making edits, and use the commit surface when history is about
+to be written.
+
+<a id="claude-code"></a>
+## Claude Code session surface
+
+Use this when the project is developed alongside an AI partner in Claude Code.
+
+1. Install the package as a project dependency: `pnpm add -D polydeukes`. A one-off `npx` run is
+   not enough — both surfaces load the judge from the project's own installed package.
+2. Wire the project: `pnpm exec pdks init claude-code`.
+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 the package as a project dependency: `pnpm add -D polydeukes`.
+2. Wire the project: `pnpm exec pdks init grok`.
+3. Reload the Hooks tab or open a new session after the installer finishes.
+
+A Grok tree gets its own hook JSON under `.grok/hooks/`. When a Claude hook already exists, the Grok
+command points at that file so the host does not spawn two judges. If the tree also has
+`.claude/settings.json`, the Grok matcher follows the Claude registration that names the same
+command, because Grok collapses the two registrations only when command and matcher match.
+Generated registrations use a timeout of 60 seconds. The Grok host default is 5 seconds, and a
+timed-out hook fails open.
+
+Grok does not supply the Claude-format human message needed by the session witness valve. The
+session log is ACP `updates.jsonl`, not Claude's JSONL.
+For an intentional blocked edit, use your own terminal. A commit-surface prompt witnesses only
+that commit; it cannot authorize a blocked Grok tool call.
+
+<a id="commit-surface"></a>
+## Commit surface
+
+Use this when you want git to judge staged changes before they become history.
+
+1. Create `polydeukes.config.yaml` at the project root.
+2. Add the pre-commit hook.
+3. Run `pnpm exec pdks covenant check` when you want the same judgment on demand.
+
+A minimal lefthook entry looks like this:
+
+```yaml
+pre-commit:
+  commands:
+    covenant:
+      priority: 1
+      interactive: true
+      run: ./node_modules/.bin/pdks covenant check
+```
+
+A husky hook looks like this:
+
+```sh
+# .husky/pre-commit
+./node_modules/.bin/pdks covenant check
+```
+
+A plain git hook works too:
+
+```sh
+#!/bin/sh
+./node_modules/.bin/pdks covenant check
+```
+
+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.
+
+`adapters.git.enforce: advise` records violations as `advised`, writes diagnostics to stderr,
+and lets the commit continue. With `block`, protected-path violations and entries explicitly set
+to `enforce: block` can stop the commit. An ordinary entry still defaults to `advise`; the surface
+does not promote it. When configured and attached to a terminal, the staged path offers a witness
+prompt on `/dev/tty`. `--worktree` and `--range` report without prompting. Assembly errors remain
+exit 2 at either level.
+
+<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.
+- On the commit surface, type the full token into the TTY prompt.
+
+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.
+- `pdks covenant check --worktree` is a good on-demand check after a task.
+- `pdks covenant check --range <base>..<head>` is the shape to use before a PR.

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

@@ -0,0 +1,124 @@
+# 규율 작성하기
+
+[English](../how-to/write-disciplines.md) · **한국어**
+
+규율(discipline)은 확인하고 싶은 개발 관행을 선언한 항목입니다. 관측할 파일이나 세션의
+증거를 고르고, 추출 과정과 관계를 적은 다음 위반과 정상 사례를 각각 실행합니다.
+관측 결과를 보고 차단이 필요하다고 판단하기 전까지는 기본 강제 수준인 `advise`를 유지합니다.
+
+<a id="locale-key-pairing"></a>
+## 번역 키 짝 맞춤
+
+두 JSON 번역 파일의 키 집합을 비교합니다. 중첩된 키도 비교 대상입니다.
+아래 전체 YAML을 **예제 프로젝트**의 `polydeukes.config.yaml`로 저장합니다. 기존 프로젝트의
+설정을 덮어쓰지 마세요. 기존 설정에 추가할 때는 규율 항목만 복사합니다.
+설치 절차는 [첫 판정 튜토리얼](../tutorials/first-judgment.ko.md)에 있습니다.
+
+```yaml
+languages:
+  json:
+    productionGlob: 'locales/**/*.json'
+    testCmd: 'pnpm test'
+telemetry:
+  logPath: '.polydeukes/roi.log'
+disciplines:
+  - id: 'locale-key-parity'
+    why: 'the ko and en locales must carry the same keys'
+    declare:
+      mechanism: 'pairing'
+      sources:
+        ko: { file: 'locales/ko.json' }
+        en: { file: 'locales/en.json' }
+      supply: { ko: 'error', en: 'error' }
+      scope: { source: 'target.path', include: ['^locales/(ko|en)\.json$'] }
+      extract:
+        koKeys:
+          - { op: 'source', of: 'ko' }
+          - { op: 'json' }
+          - { op: 'flattenKeys' }
+        enKeys:
+          - { op: 'source', of: 'en' }
+          - { op: 'json' }
+          - { op: 'flattenKeys' }
+      relate:
+        - id: 'parity'
+          relation: { op: 'equal', of: ['koKeys', 'enKeys'] }
+          messageBySide:
+            left: '{key} is in ko only'
+            right: '{key} is in en only'
+```
+
+`flattenKeys`는 번역 값이 아니라 키를 추출합니다. `equal`은 양방향으로 비교하고,
+`messageBySide`는 어느 파일에 짝이 없는 키가 있는지 알려 줍니다. 기본 강제 수준은
+`advise`입니다. 소스 파일 둘 다 존재하고 올바른 JSON이어야 합니다. 커밋 표면은 선택한
+관측 범위에서 파일을 읽고, 세션 편집에서는 바뀌는 파일의 편집 후 내용을 사용합니다.
+
+예제 프로젝트 루트에서 키가 같은 파일을 만들고 git 추적 대상으로 등록합니다.
+아래 커밋에는 평소 사용하는 git 작성자 설정이 필요합니다. 이 커밋이 작업 트리 비교의
+기준이 됩니다.
+
+```sh
+mkdir -p locales
+printf '{"home":"Home"}\n' > locales/en.json
+printf '{"home":"홈"}\n' > locales/ko.json
+git add locales/en.json locales/ko.json
+git commit -m 'docs: prepare locale example'
+printf '{"home":"Home","settings":"Settings"}\n' > locales/en.json
+pnpm exec pdks covenant check --worktree
+```
+
+`locale-key-parity`의 `advised` 진단에 영어에만 있는 `settings` 키가 나와야 합니다.
+권고이므로 명령은 종료 코드 0으로 끝납니다. 한국어 파일에 빠진 키를 추가하고 같은 검사를 반복합니다.
+
+```sh
+printf '{"home":"홈","settings":"설정"}\n' > locales/ko.json
+pnpm exec pdks covenant check --worktree
+```
+
+이제 키 비교 진단이 없어야 합니다. 번역 값은 서로 다르지만 키는 같습니다.
+확인이 끝나면 두 예제 파일을 커밋한 기준 상태로 되돌립니다.
+
+```sh
+git restore -- locales/en.json locales/ko.json
+```
+
+`--worktree`는 git이 추적하지 않더라도 무시 대상이 아닌 파일을 추가된 파일로 포함합니다.
+이 예제는 수정 사례를 검사하고 쉽게 원상 복구하기 위해 기준 상태를 커밋합니다.
+소스 파일이 존재한다는 이유만으로 선언이 실행되지는 않습니다. 관측된 변경 중 하나
+이상이 해당 선언의 적용 범위와 일치해야 합니다.
+
+<a id="when-to-draft"></a>
+## 선언 대신 초안으로 남길 때
+
+필요한 약속이지만 현재 문법으로 표현할 수 없다면 `draft`로 등록합니다.
+
+```yaml
+languages:
+  json:
+    productionGlob: 'locales/**/*.json'
+    testCmd: 'pnpm test'
+disciplines:
+  - id: 'benchmark-supports-performance-claim'
+    why: 'a performance claim must be supported by a fresh benchmark run during judgment.'
+    draft: true
+```
+
+`draft: true`인 항목은 판정 결과나 텔레메트리 행을 남기지 않습니다. 설정에는 등록돼
+있으므로 `pdks explain`에서 확인할 수 있습니다.
+
+<a id="proof-runs"></a>
+## 한 번은 실제로 판정해 보기
+
+설정을 저장한 뒤에는 필요한 증거를 공급할 수 있는 판정 경로로 위반과 정상 사례를 모두
+검사합니다. `pdks covenant check --worktree`는 현재 작업 트리의 변경을 판정하고,
+`pdks explain`은 선언과 초안의 등록 상태를 보여 줍니다. 위 번역 예제처럼 한쪽 파일만
+바꾼 경우와 양쪽 키를 맞춘 경우를 비교하세요.
+
+판정 결과가 나타나지 않으면 먼저 관측 조건을 확인합니다. 무시 대상이 아닌 관측 파일인지,
+선택한 비교에서 실제로 바뀌었는지, 적용 범위가 맞는지, 해당 표면이 증거를 공급할 수 있는지
+차례로 살펴봅니다. `pdks explain`과 로그에서 `config-fault`, `no-observation`,
+`supply-pass`도 확인합니다. 진단이 없다는 사실만으로 선언이 작동한다고 판단하지 마세요.
+
+위 초안은 키 비교와 다른 요구입니다. 현재 엔진은 판정 도중 새 벤치마크를 실행하지 않습니다.
+이미 공급된 증거를 비교하는 것과 판정 도중 새 벤치마크를 실행하는 것은 다른 요구입니다.
+[선언과 관측 한계](../concepts/judgment.ko.md#declarations)를 참고하세요.