polydeukes 0.6.0 → 0.6.1

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

@@ -0,0 +1,128 @@
+# `@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`). 판정기가 디스크에서 읽지
+않습니다.
+
+```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 };
+  };
+};
+
+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="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`가
+  평범한 객체의 맵인지, 각 네임스페이스 값이 객체인지를 봅니다. 네임스페이스 **이름**이
+  누군가 구현한 것인지는 보지 않고, 네임스페이스 안쪽은 들여다보지 않습니다.
+  `adapters.git` 안의 미지 어휘는 git 어댑터의 검증기가 자기 층위에서 거부합니다. 여기가
+  아닙니다.
+- **기본 대화 기록은 아무것도 하지 않습니다.** 실제 대화 기록을 주입하지 않은 소비자는
+  "아무 일도 없었다"는 결과를 받습니다. 이 상태에서는 증인 밸브가 작업을 허용하지 않으므로
+  차단을 유지합니다. 실제 대화 기록은 어댑터 뒤에 있습니다.
+- **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*.
@@ -34,13 +35,16 @@ copies would disagree silently instead of failing at install time. The umbrella
 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.
 
 ```ts
 type CovenantInput = {
@@ -48,6 +52,11 @@ type CovenantInput = {
   subagentSpawns: { kind: string }[];
   userMessages: { text: string }[];
   actor?: { agentType?: string };
+  world?: {
+    files?: Record<string, string>;
+    changes?: string[];
+    channels?: { sidecar?: string };
+  };
 };
 
 type FileChange =
@@ -85,26 +94,30 @@ 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="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

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

@@ -0,0 +1,115 @@
+# `@polydeukes/covenant`
+
+[English](covenant.md) · **한국어**
+
+> **판정기**입니다. 디스패처와 규율(discipline) 라이브러리, 메타 약속(covenant), TTL 증인
+> 밸브가 여기 있습니다.
+>
+> 알파입니다. 일반 사용자는 통합 패키지를 통해 설치하며 직접 불러올 필요가 없습니다.
+> 설정의 `disciplines:` 블록과 `.polydeukes/roi.log`의 기록을 통해 동작을 확인합니다.
+
+<a id="ownership"></a>
+## 담당하는 기능
+
+**판정 기능을 별도로 사용할 때 설치하는 패키지입니다.** 통합 패키지의 표면 없이 판정 기능만 연결하려면 이 패키지와 `@polydeukes/core`를 함께 제공합니다.
+core가 여기서 `peerDependency`라서 어휘가
+복제되지 않고 공유됩니다. 일반 사용자에게는 통합 패키지가 이 의존성을 제공합니다.
+
+선언된 약속(covenant)을 평가해 판정 결과를 내는 기능을 모두 이 패키지에서 구현합니다.
+
+| 단위 | 하는 일 |
+|---|---|
+| `runCovenant` 래퍼 | 판정 본체를 실행하고, 비차단 `1`을 차단하는 `2`로 번역하고, 모든 호출을 기록합니다. 측정되지 않고 실행되는 약속은 없습니다 |
+| 경로 라우팅 디스패처 | 보호 경로에 약속을 등록하고 일치하는 항목을 **모두** 실행합니다. 하나가 실패했다고 뒤의 판정을 생략하지 않습니다 |
+| 메타 약속 | 판정 사슬 자신을 지키는 등록 셋 |
+| TTL 증인 | 유효 시간이 있는 인간의 증인 밸브입니다. 차단 판정 뒤에만 확인합니다 |
+| 델타 층 | 파일의 전후 쌍에 대한 신규 위반 전용 판정 |
+| 규율(discipline) 라이브러리 | 설정의 `disciplines:` 항목을 별도 사용자 코드 없이 판정합니다 |
+
+<a id="disciplines-and-meta-covenants"></a>
+## 규율 계열과 메타 약속
+
+**`disciplines:` 항목은 선언 하나입니다.** 관측한 증거를 입력으로 받아 `judge = relate ∘ extract`를 계산합니다. 선언의 소스가 무엇을 묶는지가
+판정에 필요한 증거를 정하고, 그것이 곧 어느 표면에서
+판정될 수 있는지를 정합니다.
+
+| 소스 | 판정 대상 | 필요한 증거 |
+|---|---|---|
+| 고정 이름 `target.path` · `pre` · `post` · `state` · `changes` | 변경 자체 | 파일 변경 |
+| 고정 이름 `command` | 셸 호출의 명령줄 | 셸 호출입니다. Edit에는 없습니다 |
+| `{ transcript: true }` | 세션 이력입니다. 이 호출 **앞에** 자격을 갖춘 호출이 실제로 실행됐는가 | 세션 |
+| `{ file: … }` · `{ sidecar: true }` | 다른 파일, 또는 스폰 기록 채널 | 표면의 리더 |
+
+이 항목들을 쓰는 가이드는 [설정 레퍼런스의 `disciplines` 절](../configuration/index.ko.md#disciplines)에
+있습니다. 선언 문법은 코어의 `algebra-declaration.schema.json`입니다.
+
+**메타 약속 셋**이 판정 사슬을 지킵니다. 다른 약속과 똑같은 약속이고, 아래 어휘가 그대로
+적용됩니다.
+
+| 등록 | 축 | 판정 대상 |
+|---|---|---|
+| self-mod | 도구 | 편집 도구를 통한 보호 경로 변형입니다. 호출의 증명된 변형 대상만 대조하므로, 편집 **내용** 안의 보호 경로는 언급이고 통과합니다 |
+| shell-mod | 셸 | 같은 것을 명령줄로 합니다. 보호 경로를 언급하는 명령은 첫 낱말이 읽기 전용임을 증명할 때만 통과합니다 |
+| transcript-mod | 대화 기록 | 라이브 세션 대화 기록에 대한 쓰기입니다. 전체 경로 **등가**로 판정하고 보호 조상으로는 결코 보지 않습니다 |
+
+**낱말 여섯**이 텔레메트리 계약입니다. 판정 결과 다섯과 관측 하나입니다. `.polydeukes/roi.log`의
+한 행은 이 중 정확히 하나를 담고, CLI와 문서와 테스트가 같은 사건에 같은 낱말을 씁니다.
+행을 읽는 법은 [문제 해결](../../troubleshooting.ko.md#reading-verdict)에 있습니다.
+
+| 판정 결과 | 뜻 |
+|---|---|
+| `passed` | 호출이 판정됐고 약속을 지켰습니다 |
+| `blocked` | 호출이 판정됐고 약속을 깼습니다 |
+| `witnessed` | **차단된** 작업을 인간의 증언으로 허용했습니다. 위반이 없었다는 뜻이 아니며 허용 사실을 기록합니다 |
+| `advised` | 호출을 멈추지 않고 위반을 기록했습니다. 두 표면 모두에서 규율 항목의 기본 처분이고, `adapters.git.enforce: advise`인 커밋 표면의 결과이기도 합니다 |
+| `skipped` | 적용 범위가 일치했지만 판정할 수 없었습니다. **정상 판정이 아니라** 판정하지 못했다는 기록입니다 |
+| `unattributed` | 보호 항목의 디스크 상태가 변했는데 그것을 설명하는 판정 기록이 없습니다. **판정이 아닙니다.** 이 행 때문에 차단되거나 통과하는 호출은 없으며, 세션 표면이 저장된 기준선과 상태를 대조한 뒤에 기록합니다 |
+
+`unattributed`는 나머지 다섯이 답할 수 없는 물음에 답합니다. 다섯은 전부 판정기가 건네받은
+호출에 관해 쓰는 낱말이라, 선언된 호출 없이 도착한 쓰기는 행을 하나도 남기지 않습니다.
+인터프리터 안의 쓰기, 테스트 러너 자식 프로세스의 쓰기, 대상 경로를 자기 인자에서 조립하는
+스크립트가 그런 경우입니다. 상태 대조는 철자가 아니라 결과를 관측하므로 그 쓰기를 사후에
+기록합니다. 차단하지는 않습니다. 이미 일어난 쓰기이고, 대조는 판정의 양쪽 모두에서
+fail-open입니다.
+
+<a id="consumer-contract"></a>
+## 사용자와의 접점
+
+- **설정의 `disciplines:` 블록.** 항목 하나가 등록 하나로 컴파일되고 자기 텔레메트리
+  라벨을 답니다.
+- **`protectedPaths`.** 경로 라우팅 디스패처가 여기에 대조합니다.
+- **`witness` 블록.** TTL 증인 밸브를 설정합니다.
+- **`.polydeukes/roi.log`.** 판정 기록을 추가하는 로그입니다.
+
+일반 사용자가 직접 불러올 필요는 없습니다. 통합 패키지가 두 표면에 필요한 구성을 조립합니다.
+
+<a id="limits"></a>
+## 선언된 한계
+
+- **셸 축은 `skipped` 행을 남기고, 그 행이 계약입니다.** 셸 명령의 대상을 텍스트에서
+  예측하는 일은 결정 불가능합니다. 그래서 이 축이 지키는 불변식은 "아무것도 빠져나가지
+  못한다"가 아니라 **기록 없이 통과하는 호출이 없다**입니다. 새로운 명령 형태가 `skipped`로 기록되면 판정하지 못한 한계를 확인할 수 있습니다. 행이 아예 없는
+  통과, 또는
+  판정하지 않고 `passed`로 기록된 통과가 결함입니다.
+- **세션을 읽는 선언은 세션 없이 판정할 수 없습니다.** 커밋 표면에는 세션이 없습니다. 적용 범위가 일치한
+  `precedent`(그리고 대화 기록을 읽는 다른) 선언이 사유 `supply-pass`로 `skipped`를 남기는
+  것은 그 선언의 `supply`가 `pass`일 때뿐입니다. 정책이 없으면 없는 세션은 판정 불가(exit
+  2)로 처리하며 자동으로 건너뛰지 않습니다. 이 표면에서 세션 증거가 없다는 조건은 변하지 않습니다.
+- **`command`를 적용 범위의 소스로 쓰는 선언은 커밋 표면에서 실행되지 않으며 기록도 남기지
+  않습니다.** 스테이징한 변경에는 명령줄이 없으므로 그 선언의 관측 대상이 되지 않습니다.
+  `.polydeukes/roi.log`에 아무것도 남지 않아서, 발동한 적 없는 명령 규율과 명령을 관측한 적
+  없는 표면의 규율을 로그로 가를 수 없습니다.
+- **컴파일러가 해석하지 못하는 선언은 스킵 등록으로 컴파일됩니다.** 라우팅은 그대로 두고
+  본체를 두지 않습니다. 등재 표 밖의 단계, 단계의 키 밖의 인자, 컴파일되지 않는 패턴,
+  쌍/단일 불일치가 그 경우입니다. 그래서 조립은 예외를 던지지 않습니다. 해소되지 않는 항목
+  하나가 형제 항목과 메타 약속과 밸브까지 무너뜨리면, 그것을 일으킨 설정을 고칠 길이
+  사라지기 때문입니다. 예약 기전, 또는 카탈로그가 거부하는 축·관계는 다른 단계입니다.
+  `loadConfig`가 파일을 거부하고(exit 2) skip 행은 남지 않습니다. 판정 시점에 세계에 없는
+  소스는 세 번째 경우입니다. 선언 자신의 `supply` 정책이 처분하고, 정책이 없으면 본체가
+  판정 불가(exit 2)로 답합니다. 통과로 답하지 않습니다.
+- **완전 봉쇄는 목표가 아닙니다.** 여기에 차단 목록은 없습니다. 우회 철자를 열거하는 일은
+  언제나 한 걸음 뒤지므로 논리를 뒤집었습니다. 보호 경로를 언급하면 안전이 증명되지 않는
+  한 차단합니다. 간접 경로 계산 같은 잔여 벡터는 차단 대상이 아니라 텔레메트리 대상입니다.
+  마찰 밸브 둘, 곧 읽기 전용 허용 목록과 TTL 증인은 둘 다 측정 가능한 흔적을 남깁니다.
+- **밸브는 판정 뒤에 확인합니다.** 실제로 차단한 판정만 증언으로 열 수 있고, 문장 중간의 토큰
+  언급은 밸브를 무장시키지 않으며, AI는 자기 밸브를 결코 스스로 열 수 없습니다.

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

@@ -1,6 +1,6 @@
 # `@polydeukes/covenant`
 
-**English** · [한국어](./covenant.ko.md)
+**English** · [한국어](covenant.ko.md)
 
 > **The judge** — the dispatcher, the discipline library, the meta-covenants, and the TTL
 > witness valve.
@@ -9,6 +9,7 @@
 > import it. What you reach is its behaviour, through the `disciplines:` block in your config
 > and the rows it writes to `.polydeukes/roi.log`.
 
+<a id="ownership"></a>
 ## What this package owns
 
 The judge. Everything that turns a declared promise into a verdict lives here.
@@ -27,6 +28,7 @@ is what satisfies that peer for an ordinary consumer.
 | Delta layer | New-violation-only judgment over a file's before/after pair |
 | Discipline library | Config `disciplines:` entries become enforcement without a line of code |
 
+<a id="disciplines-and-meta-covenants"></a>
 ## Discipline families and meta-covenants
 
 **A `disciplines:` entry is one declaration** — `judge = relate ∘ extract` over the
@@ -41,7 +43,7 @@ judgment needs, which is also what decides whether it can be judged on a given s
 | `{ file: … }` · `{ sidecar: true }` | Another file, or the spawn-record channel | The surface's reader for it |
 
 The writing guide for these entries is [the configuration reference's `disciplines`
-section](./configuration.md#disciplines); the declaration grammar is the core's
+section](../configuration/index.md#disciplines); the declaration grammar is the core's
 `algebra-declaration.schema.json`.
 
 **Three meta-covenants** protect the judging chain. They are covenants like any other; the
@@ -56,7 +58,7 @@ vocabulary below applies to them unchanged.
 **Six words** are the telemetry contract — five verdicts and one observation. A row in
 `.polydeukes/roi.log` carries exactly one of them, and the CLI, the docs, and the tests use
 the same word for the same event. How to read a row is in
-[troubleshooting](../troubleshooting.md#reading-a-verdict).
+[troubleshooting](../../troubleshooting.md#reading-a-verdict).
 
 | Verdict | Means |
 |---|---|
@@ -74,6 +76,7 @@ arguments — leaves no row at all. The comparison observes the result rather th
 spelling, so it records that write after the fact. It never blocks: the write already
 happened, and the comparison fails open on both sides of the verdict.
 
+<a id="consumer-contract"></a>
 ## Where the consumer touches it
 
 - **The `disciplines:` block** in your config. One entry compiles into one registration,
@@ -84,6 +87,7 @@ happened, and the comparison fails open on both sides of the verdict.
 
 No import. The umbrella assembles this package for both surfaces.
 
+<a id="limits"></a>
 ## Declared limits
 
 - **The shell axis leaves `skipped` rows, and that row is the contract.** Predicting a
@@ -92,20 +96,23 @@ No import. The umbrella assembles this package for both surfaces.
   landing in `skipped` is the declared limit showing itself. A pass with no row at all, or
   one recorded `passed` without a judgment, is the defect class.
 - **A declaration that reads the session cannot be judged without one.** On the commit
-  surface there is none, so a matching `precedent` (or any other transcript-reading)
-  declaration records `skipped` with the reason `supply-pass`. That is a permanent
-  condition of that surface.
+  surface there is none. A matching `precedent` (or any other transcript-reading)
+  declaration records `skipped` with the reason `supply-pass` only when that declaration's
+  own `supply` is `pass`. With no policy the missing session is unjudgeable (exit 2), not
+  an automatic skip. That skip-with-pass is a permanent condition of that surface.
 - **A declaration scoped on `command` is absent from the commit surface, and absent without
   a row.** A staged diff carries no command line, so no world such a declaration observes is
   admitted there. This leaves nothing in `.polydeukes/roi.log`, so the log cannot separate a
   command discipline that never triggered from one whose surface never observed a command.
 - **A declaration the compiler cannot resolve compiles to a skip registration** — routing
   intact, no body: a step outside the registry, an argument outside a step's keys, a pattern
-  that does not compile, a mechanism whose shape the syntax does not fit. Assembly therefore
-  never throws: one unresolvable entry cannot take down its siblings, the meta-covenants, and
-  the valve, which would leave no way to fix the config that caused it. A source the world
-  lacks at judgment time is a different case — the declaration's own `supply` policy
-  disposes of it, and with no policy the body answers unjudgeable (exit 2), never upheld.
+  that does not compile, a paired/single mismatch. Assembly therefore never throws: one
+  unresolvable entry cannot take down its siblings, the meta-covenants, and the valve, which
+  would leave no way to fix the config that caused it. A reserved mechanism, or one whose
+  axes and relations the catalogue refuses, is a different stage: `loadConfig` rejects the
+  file (exit 2), and no skip row is written. A source the world lacks at judgment time is a
+  third case — the declaration's own `supply` policy disposes of it, and with no policy the
+  body answers unjudgeable (exit 2), never upheld.
 - **Complete containment is a non-goal.** There are no blocklists here — enumerating bypass
   spellings is always one step behind, so the logic is inverted: a mention of a protected
   path blocks unless proven safe. Residual vectors such as indirect path computation are

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

@@ -0,0 +1,134 @@
+# `polydeukes`
+
+[English](./polydeukes.md) · **한국어**
+
+일반 사용자는 통합 패키지인 `polydeukes` 하나만 설치하면 됩니다. CLI 실행 파일, 설정 로더, 커밋 표면 실행기, 세션 표면 실행기 서브패스, 동봉된 스키마 자산을
+모두 이 패키지가 맡습니다.
+
+<a id="polydeukes-entry-points"></a>
+## 진입점
+
+| 지정자 | 내보내는 것 |
+|---|---|
+| `polydeukes` | `loadConfig`, `runCovenantCheck`, `ResolvedConfig` |
+| `polydeukes/claude-code` | `runClaudeCodeHook`과 입력·결과 타입 |
+| `polydeukes/schema.json` | 동봉된 설정 JSON Schema |
+
+같은 CLI를 `pdks`와 별칭 `polydeukes`로 실행할 수 있습니다.
+
+<a id="polydeukes-bin"></a>
+## CLI 명령
+
+| 명령 | 목적 |
+|---|---|
+| `pdks covenant check` | 스테이징한 변경, 작업 트리, 리비전 범위를 판정 |
+| `pdks init claude-code` | Claude Code 세션 표면 설치 |
+| `pdks init grok` | Grok 세션 표면 설치 |
+| `pdks explain` | 조립된 등록표를 판정 없이 표시 |
+| `pdks docs [topic]` | 동봉된 주제를 읽음 |
+| `pdks docs search <query>` | 동봉된 문서를 검색 |
+| `pdks docs show <document-id>` | 동봉된 문서 또는 절을 표시 |
+
+`pdks docs`는 오프라인입니다. 네트워크가 아니라 설치된 패키지를 읽습니다. 플래그, JSON,
+종료 코드는 [`pdks docs`](../cli/docs.ko.md)에 있습니다.
+
+<a id="polydeukes-export-map"></a>
+## 공개 심볼
+
+<a id="root-export"></a>
+### `.` 루트 진입점
+
+| 심볼 | 종류 | 메모 |
+|---|---|---|
+| `loadConfig` | 함수 | `rootDir` 아래의 `polydeukes.config.*` 파일 하나를 찾아 읽습니다. 없거나, 둘 이상이거나, 파싱이나 검증에서 실패하면 예외를 던집니다. |
+| `runCovenantCheck` | 함수 | 커밋 표면을 실행하고 `{ exitCode: 0 \| 2 }`를 반환합니다. |
+| `ResolvedConfig` | 타입 | `@polydeukes/core`에서 다시 내보냅니다. |
+| `LoadConfigSpec`, `LoadedConfig` | 타입 | 설정 로더의 입력과 결과입니다. |
+| `CovenantCheckSpec`, `CovenantCheckOutcome`, `CheckDomain` | 타입 | 커밋 실행기의 입력, 결과, 관측 범위입니다. |
+
+<a id="session-export"></a>
+### `./claude-code`
+
+| 심볼 | 종류 | 메모 |
+|---|---|---|
+| `runClaudeCodeHook` | 함수 | 세션 표면을 실행하고 `{ exitCode: 0 \| 2 }`를 반환합니다. |
+| `ClaudeCodeHookSpec` | 타입 | 세션 실행기 입력입니다. |
+| `ClaudeCodeHookOutcome` | 타입 | 세션 실행기 결과입니다. |
+
+생성된 훅은 배럴 대신 이 서브패스를 가져옵니다. ESM의 정적 가져오기는 모듈을 즉시 평가하므로,
+배럴을 사용하면 세션 도구 호출에 필요 없는 커밋 표면 실행기와 Git 어댑터까지 매번 불러옵니다.
+
+<a id="schema-export"></a>
+### `./schema.json`
+
+| 자산 | 메모 |
+|---|---|
+| `polydeukes.schema.json` | 통합 패키지에 동봉한 설정 스키마 사본입니다. |
+
+<a id="polydeukes-signatures"></a>
+## 시그니처와 예제
+
+```ts
+function loadConfig(spec: LoadConfigSpec): LoadedConfig;
+
+type LoadConfigSpec = { rootDir: string };
+
+type LoadedConfig = {
+  config: ResolvedConfig;
+  configPath: string;
+};
+
+function runCovenantCheck(spec: CovenantCheckSpec): Promise<CovenantCheckOutcome>;
+
+type CovenantCheckSpec = {
+  repoRoot: string;
+  telemetryPath?: string;
+  covenantDist?: string;
+  ttyPrompt?: (prompt: string) => string | null;
+  domain?: CheckDomain;
+};
+
+type CheckDomain =
+  | { kind: 'staged' }
+  | { kind: 'worktree' }
+  | { kind: 'range'; base: string; head: string; ancestry?: 'merge-base' };
+
+function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<ClaudeCodeHookOutcome>;
+
+type ClaudeCodeHookSpec = {
+  repoRoot: string;
+  rawPayload?: string;
+  telemetryPath?: string;
+  covenantDist?: string;
+};
+```
+
+`ancestry: 'merge-base'`는 `<base>...<head>`와 같이 공통 조상을 기준으로 비교한다는 뜻입니다.
+`rawPayload`가 없으면 훅은 표준 입력인 파일 디스크립터 0을 읽습니다. 훅 타입은 루트 배럴이 아니라 `polydeukes/claude-code`에 있습니다.
+
+```ts
+import { loadConfig, runCovenantCheck } from 'polydeukes';
+import { runClaudeCodeHook } from 'polydeukes/claude-code';
+
+const { configPath } = loadConfig({ rootDir: process.cwd() });
+const check = await runCovenantCheck({ repoRoot: process.cwd() });
+const hook = await runClaudeCodeHook({ repoRoot: process.cwd(), rawPayload: '{}' });
+```
+
+<a id="polydeukes-failure-boundaries"></a>
+## 실패 경계
+
+- `loadConfig()`는 설정이 없거나, 둘 이상이거나, 파싱이나 검증에서 실패하면 예외를 던집니다.
+- `runCovenantCheck()`와 `runClaudeCodeHook()`는 예외를 던지지 않고 `{ exitCode: 0 \| 2 }`를 반환합니다.
+- 숫자 코드는 `@polydeukes/core`의 `EXIT_UPHOLD`(`0`), `EXIT_BREAK_NON_BLOCKING`(`1`),
+  `EXIT_BREAK_BLOCKING`(`2`)입니다. 우산 실행기는 `0` 또는 `2`만 노출하며 `1`을 반환하지 않습니다.
+- `pdks covenant check`가 증인 토큰을 요청하는 것은 스테이징한 변경을 검사할 때뿐입니다. `--worktree`와 `--range`에서는 묻지 않습니다.
+- `pdks docs`와 `pdks explain`은 실패 시 중간 출력 없이 끝납니다.
+
+<a id="polydeukes-see-also"></a>
+## 함께 보기
+
+- [`pdks covenant check`](../cli/covenant-check.ko.md)
+- [`pdks init`](../cli/init.ko.md)
+- [`pdks explain`](../cli/explain.ko.md)
+- [설정 참조](../configuration/index.ko.md)