polydeukes 0.6.1 → 0.8.0

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

@@ -2,61 +2,63 @@
 
 [English](./polydeukes.md) · **한국어**
 
-일반 사용자는 통합 패키지인 `polydeukes` 하나만 설치하면 됩니다. CLI 실행 파일, 설정 로더, 커밋 표면 실행기, 세션 표면 실행기 서브패스, 동봉된 스키마 자산을
-모두 이 패키지가 맡습니다.
+일반 사용자는 통합 패키지인 `polydeukes` 하나만 설치하면 됩니다. `pdks` 실행 파일, 판정기,
+두 표면의 조립 루트, 세션 표면 실행기 서브패스, 동봉된 스키마 자산을 모두 이 패키지가
+맡습니다.
 
 <a id="polydeukes-entry-points"></a>
 ## 진입점
 
-| 지정자 | 내보내는 것 |
+| 지정자 | 무엇인가 |
 |---|---|
-| `polydeukes` | `loadConfig`, `runCovenantCheck`, `ResolvedConfig` |
-| `polydeukes/claude-code` | `runClaudeCodeHook`과 입력·결과 타입 |
+| `pdks` / `polydeukes` | 실행 파일입니다. `bin`에 이름 둘로 등록된 같은 CLI입니다 |
 | `polydeukes/schema.json` | 동봉된 설정 JSON Schema |
 
-같은 CLI를 `pdks`와 별칭 `polydeukes`로 실행할 수 있습니다.
+`.` 진입점은 없습니다. `import 'polydeukes'`는 `ERR_PACKAGE_PATH_NOT_EXPORTED`로 실패합니다.
+사용자가 닿는 것은 실행 파일과 스키마 파일입니다. 세션 표면도 셸과 같은 방법으로 이
+패키지에 닿습니다. 즉 `pdks covenant check`를 스폰하므로, 에이전트 어댑터는 이 패키지를
+import하지 않고 peer 의존으로 선언합니다.
 
 <a id="polydeukes-bin"></a>
 ## CLI 명령
 
 | 명령 | 목적 |
 |---|---|
-| `pdks covenant check` | 스테이징한 변경, 작업 트리, 리비전 범위를 판정 |
-| `pdks init claude-code` | Claude Code 세션 표면 설치 |
-| `pdks init grok` | Grok 세션 표면 설치 |
+| `pdks covenant check` | 표준 입력의 입력 IR(기본, 세션 표면) 또는 통합 diff(`--diff`, 변경 집합 표면)를 판정 |
+| `pdks init` | 프로젝트 초기 파일 생성. 설정 파일과 텔레메트리 제외 항목 |
 | `pdks explain` | 조립된 등록표를 판정 없이 표시 |
 | `pdks docs [topic]` | 동봉된 주제를 읽음 |
 | `pdks docs search <query>` | 동봉된 문서를 검색 |
 | `pdks docs show <document-id>` | 동봉된 문서 또는 절을 표시 |
 
-`pdks docs`는 오프라인입니다. 네트워크가 아니라 설치된 패키지를 읽습니다. 플래그, JSON,
-종료 코드는 [`pdks docs`](../cli/docs.ko.md)에 있습니다.
+세션 표면 설치기는 어댑터에 있습니다. `pdks-claude-code init`, `pdks-grok init`,
+`pdks-codex init`입니다.
 
-<a id="polydeukes-export-map"></a>
-## 공개 심볼
+<a id="surface-from-input-mode"></a>
+### 입력 방식이 곧 표면이다
 
-<a id="root-export"></a>
-### `.` 루트 진입점
+`covenant check`는 입력이 어떻게 도착했는지로 표면을 정하며, 입력 자신의 키로 정하지
+않습니다. 표준 입력의 IR은 호스트가 실행 전에 관측한 호출 하나이므로 그 실행은 **세션
+표면(session surface)**이고, `--diff`는 어떤 생산자가 끝낸 변경 집합이므로 그 실행은
+**변경 집합 표면(change-set surface)**입니다. 표면마다 공용 목록에 자기 목록을 더해
+컴파일합니다.
 
-| 심볼 | 종류 | 메모 |
+| 입력 | 표면 | 컴파일하는 목록 |
 |---|---|---|
-| `loadConfig` | 함수 | `rootDir` 아래의 `polydeukes.config.*` 파일 하나를 찾아 읽습니다. 없거나, 둘 이상이거나, 파싱이나 검증에서 실패하면 예외를 던집니다. |
-| `runCovenantCheck` | 함수 | 커밋 표면을 실행하고 `{ exitCode: 0 \| 2 }`를 반환합니다. |
-| `ResolvedConfig` | 타입 | `@polydeukes/core`에서 다시 내보냅니다. |
-| `LoadConfigSpec`, `LoadedConfig` | 타입 | 설정 로더의 입력과 결과입니다. |
-| `CovenantCheckSpec`, `CovenantCheckOutcome`, `CheckDomain` | 타입 | 커밋 실행기의 입력, 결과, 관측 범위입니다. |
+| 표준 입력의 입력 IR | `session` | `disciplines` 다음 `sessionDisciplines` |
+| `--diff`와 함께 오는 표준 입력의 통합 diff | `changeSet` | `disciplines` 다음 `changeSetDisciplines` |
 
-<a id="session-export"></a>
-### `./claude-code`
+IR의 `session` 키는 다른 것을 말합니다. 호스트가 그 호출에 대해 증명한 사실, 곧 증인 밸브가
+읽는 사람의 턴과 대화 기록(transcript) 축, 그리고 셸 쓰기 증거에 필요한 변경 전 상태
+통로입니다. 세션을 싣지 않는 호스트(Grok 어댑터)도 여전히 세션 표면에서 판정되며, 그 호스트에
+없는 것은 표면이 아니라 그 셋이 읽는 증거입니다. `pdks explain`은 표면마다 목록 이름 둘과 그
+개수를 함께 출력합니다.
 
-| 심볼 | 종류 | 메모 |
-|---|---|---|
-| `runClaudeCodeHook` | 함수 | 세션 표면을 실행하고 `{ exitCode: 0 \| 2 }`를 반환합니다. |
-| `ClaudeCodeHookSpec` | 타입 | 세션 실행기 입력입니다. |
-| `ClaudeCodeHookOutcome` | 타입 | 세션 실행기 결과입니다. |
+`pdks docs`는 오프라인입니다. 네트워크가 아니라 설치된 패키지를 읽습니다. 플래그, JSON,
+종료 코드는 [`pdks docs`](../cli/docs.ko.md)에 있습니다.
 
-생성된 훅은 배럴 대신 이 서브패스를 가져옵니다. ESM의 정적 가져오기는 모듈을 즉시 평가하므로,
-배럴을 사용하면 세션 도구 호출에 필요 없는 커밋 표면 실행기와 Git 어댑터까지 매번 불러옵니다.
+<a id="polydeukes-export-map"></a>
+## 공개 심볼
 
 <a id="schema-export"></a>
 ### `./schema.json`
@@ -65,64 +67,124 @@
 |---|---|
 | `polydeukes.schema.json` | 통합 패키지에 동봉한 설정 스키마 사본입니다. |
 
-<a id="polydeukes-signatures"></a>
-## 시그니처와 예제
+<a id="covenant-module"></a>
+## 판정기(`covenant` 모듈)
 
-```ts
-function loadConfig(spec: LoadConfigSpec): LoadedConfig;
+판정기는 통합 패키지의 `src/covenant/` 모듈입니다. 선언된 약속(covenant)을 평가해 판정
+결과를 내는 기능을 모두 여기서 구현하며, 두 조립 루트와 `pdks explain`이 이 모듈을 바로
+가져옵니다. 따로 설치할 것도, 불러올 것도, 충족할 peer 의존도 없습니다. 사용자는 설정의
+`disciplines:` 블록과 `.polydeukes/roi.log`의 기록을 통해 동작을 확인합니다.
 
-type LoadConfigSpec = { rootDir: string };
+<a id="ownership"></a>
+### 모듈이 담당하는 기능
 
-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`에 있습니다.
+| 단위 | 하는 일 |
+|---|---|
+| `runCovenant` 래퍼 | 판정 본체를 실행하고, 비차단 `1`을 차단하는 `2`로 번역하고, 모든 호출을 기록합니다. 측정되지 않고 실행되는 약속은 없습니다 |
+| 경로 라우팅 디스패처 | 보호 경로에 약속을 등록하고 일치하는 항목을 **모두** 실행합니다. 하나가 실패했다고 뒤의 판정을 생략하지 않습니다 |
+| 메타 약속 | 판정 사슬 자신을 지키는 등록 셋 |
+| TTL 증인 | 유효 시간이 있는 인간의 증인 밸브입니다. 차단 판정 뒤에만 확인합니다 |
+| 델타 층 | 파일의 전후 쌍에 대한 신규 위반 전용 판정 |
+| 규율(discipline) 라이브러리 | 설정의 `disciplines:` 항목을 별도 사용자 코드 없이 판정합니다 |
+
+<a id="disciplines-and-meta-covenants"></a>
+### 규율 계열과 메타 약속
+
+**`disciplines:` 항목은 선언 하나입니다.** 관측한 증거를 입력으로 받아 `judge = relate ∘ extract`를 계산합니다. 선언의 소스가 무엇을 묶는지가
+판정에 필요한 증거를 정하고, 그것이 곧 어느 표면에서
+판정될 수 있는지를 정합니다.
+
+| 소스 | 판정 대상 | 필요한 증거 | 목록 |
+|---|---|---|---|
+| 고정 이름 `target.path` · `pre` · `post` · `state` | 변경 자체 | 파일 변경 | `disciplines` |
+| 고정 이름 `changes` | 관측의 변경 집합 전체 | 끝난 변경 집합 | `changeSetDisciplines` |
+| 고정 이름 `command` | 셸 호출의 명령줄 | 셸 호출입니다. Edit에는 없습니다 | `sessionDisciplines` |
+| 고정 이름 `actor` | 관측을 만든 주체 | 호스트가 증명한 주체 | `sessionDisciplines` |
+| `{ transcript: true }` | 세션 이력입니다. 이 호출 **앞에** 자격을 갖춘 호출이 실제로 실행됐는가 | 세션 | `sessionDisciplines` |
+| `{ file: … }` | 다른 파일 | 표면의 파일 리더 | `disciplines` |
+| `{ sidecar: true }` | 스폰 기록 채널 | 표면의 채널 리더 | `sessionDisciplines` |
+
+이 항목들을 쓰는 가이드는 [설정 레퍼런스의 `disciplines` 절](../configuration/index.ko.md#disciplines)에
+있습니다. 선언 문법은 코어의 `algebra-declaration.schema.json`입니다.
+
+**메타 약속 셋**이 판정 사슬을 지킵니다. 다른 약속과 똑같은 약속이고, 아래 어휘가 그대로
+적용됩니다.
+
+| 등록 | 축 | 판정 대상 |
+|---|---|---|
+| self-mod | 도구 | 편집 도구를 통한 보호 경로 변형입니다. 호출의 증명된 변형 대상만 대조하므로, 편집 **내용** 안의 보호 경로는 언급이고 통과합니다 |
+| shell-mod | 셸 | 같은 것을 명령줄로 합니다. 보호 경로를 언급하는 명령은 첫 낱말이 읽기 전용임을 증명할 때만 통과합니다 |
+| transcript-mod | 대화 기록 | 라이브 세션 대화 기록에 대한 쓰기입니다. 전체 경로 **등가**로 판정하고 보호 조상으로는 결코 보지 않습니다 |
 
-```ts
-import { loadConfig, runCovenantCheck } from 'polydeukes';
-import { runClaudeCodeHook } from 'polydeukes/claude-code';
+**낱말 여섯**이 텔레메트리 계약입니다. 판정 결과 다섯과 관측 하나입니다. `.polydeukes/roi.log`의
+한 행은 이 중 정확히 하나를 담고, CLI와 문서와 테스트가 같은 사건에 같은 낱말을 씁니다.
+행을 읽는 법은 [문제 해결](../../troubleshooting.ko.md#reading-verdict)에 있습니다.
 
-const { configPath } = loadConfig({ rootDir: process.cwd() });
-const check = await runCovenantCheck({ repoRoot: process.cwd() });
-const hook = await runClaudeCodeHook({ repoRoot: process.cwd(), rawPayload: '{}' });
-```
+| 판정 결과 | 뜻 |
+|---|---|
+| `passed` | 호출이 판정됐고 약속을 지켰습니다 |
+| `blocked` | 호출이 판정됐고 약속을 깼습니다 |
+| `witnessed` | **차단된** 작업을 인간의 증언으로 허용했습니다. 위반이 없었다는 뜻이 아니며 허용 사실을 기록합니다 |
+| `advised` | 호출을 멈추지 않고 위반을 기록했습니다. 항목이 `enforce: block`을 적지 않는 한 두 표면 모두에서 규율 항목의 기본 처분입니다 |
+| `skipped` | 적용 범위가 일치했지만 판정할 수 없었습니다. **정상 판정이 아니라** 판정하지 못했다는 기록입니다 |
+| `unattributed` | 보호 항목의 디스크 상태가 변했는데 그것을 설명하는 판정 기록이 없습니다. **판정이 아닙니다.** 이 행 때문에 차단되거나 통과하는 호출은 없으며, 세션 표면이 저장된 기준선과 상태를 대조한 뒤에 기록합니다 |
+
+`unattributed`는 나머지 다섯이 답할 수 없는 물음에 답합니다. 다섯은 전부 판정기가 건네받은
+호출에 관해 쓰는 낱말이라, 선언된 호출 없이 도착한 쓰기는 행을 하나도 남기지 않습니다.
+인터프리터 안의 쓰기, 테스트 러너 자식 프로세스의 쓰기, 대상 경로를 자기 인자에서 조립하는
+스크립트가 그런 경우입니다. 상태 대조는 철자가 아니라 결과를 관측하므로 그 쓰기를 사후에
+기록합니다. 차단하지는 않습니다. 이미 일어난 쓰기이고, 대조는 판정의 양쪽 모두에서
+fail-open입니다.
+
+<a id="consumer-contract"></a>
+### 사용자와의 접점
+
+- **설정의 `disciplines:` 블록.** 항목 하나가 등록 하나로 컴파일되고 자기 텔레메트리
+  라벨을 답니다.
+- **`protectedPaths`.** 경로 라우팅 디스패처가 여기에 대조합니다.
+- **`witness` 블록.** TTL 증인 밸브를 설정합니다.
+- **`.polydeukes/roi.log`.** 판정 기록을 추가하는 로그입니다.
+
+직접 불러올 필요는 없습니다. 통합 패키지가 두 표면에 필요한 구성을 조립합니다.
+
+<a id="limits"></a>
+### 선언된 한계
+
+- **셸 축은 `skipped` 행을 남기고, 그 행이 계약입니다.** 셸 명령의 대상을 텍스트에서
+  예측하는 일은 결정 불가능합니다. 그래서 이 축이 지키는 불변식은 "아무것도 빠져나가지
+  못한다"가 아니라 **기록 없이 통과하는 호출이 없다**입니다. 새로운 명령 형태가 `skipped`로 기록되면 판정하지 못한 한계를 확인할 수 있습니다. 행이 아예 없는
+  통과, 또는
+  판정하지 않고 `passed`로 기록된 통과가 결함입니다.
+- **세션을 증명하지 못하는 호스트에서 세션 전용 선언은 `skipped`를 남깁니다.** 그 항목은
+  세션 표면에 있으므로 컴파일되지만, 선언이 묶는 대화 기록이 없고, 항목 자신의
+  `supply: pass`가 그 부재를 사유 `supply-pass`의 `skipped` 행으로 처리합니다. 정책이 없으면
+  없는 세션은 판정 불가(exit 2)이지 자동 건너뛰기가 아닙니다.
+- **표면은 다른 표면의 목록을 등록하지 않습니다.** `command`나 대화 기록을 읽는 선언은 변경
+  집합에 대해 컴파일되지 않고, `changes`를 읽는 선언은 호출 하나에 대해 컴파일되지 않으므로,
+  관측하지 않는 표면에는 행도 남기지 않습니다. 표면이 어떤 항목을 지니는지는 텔레메트리
+  로그가 아니라 `pdks explain`과 설정 파일의 목록 이름에서 읽습니다.
+- **컴파일러가 해석하지 못하는 선언은 스킵 등록으로 컴파일됩니다.** 라우팅은 그대로 두고
+  본체를 두지 않습니다. 등재 표 밖의 단계, 단계의 키 밖의 인자, 컴파일되지 않는 패턴,
+  쌍/단일 불일치가 그 경우입니다. 그래서 조립은 예외를 던지지 않습니다. 해소되지 않는 항목
+  하나가 형제 항목과 메타 약속과 밸브까지 무너뜨리면, 그것을 일으킨 설정을 고칠 길이
+  사라지기 때문입니다. 예약 기전, 또는 카탈로그가 거부하는 축·관계는 다른 단계입니다.
+  설정을 읽는 단계에서 파일을 거부하고(exit 2) skip 행은 남지 않습니다. 판정 시점에 세계에 없는
+  소스는 세 번째 경우입니다. 선언 자신의 `supply` 정책이 처분하고, 정책이 없으면 본체가
+  판정 불가(exit 2)로 답합니다. 통과로 답하지 않습니다.
+- **완전 봉쇄는 목표가 아닙니다.** 여기에 차단 목록은 없습니다. 우회 철자를 열거하는 일은
+  언제나 한 걸음 뒤지므로 논리를 뒤집었습니다. 보호 경로를 언급하면 안전이 증명되지 않는
+  한 차단합니다. 간접 경로 계산 같은 잔여 벡터는 차단 대상이 아니라 텔레메트리 대상입니다.
+  마찰 밸브 둘, 곧 읽기 전용 허용 목록과 TTL 증인은 둘 다 측정 가능한 흔적을 남깁니다.
+- **밸브는 판정 뒤에 확인합니다.** 실제로 차단한 판정만 증언으로 열 수 있고, 문장 중간의 토큰
+  언급은 밸브를 무장시키지 않으며, AI는 자기 밸브를 결코 스스로 열 수 없습니다.
 
 <a id="polydeukes-failure-boundaries"></a>
 ## 실패 경계
 
-- `loadConfig()`는 설정이 없거나, 둘 이상이거나, 파싱이나 검증에서 실패하면 예외를 던집니다.
-- `runCovenantCheck()`와 `runClaudeCodeHook()`는 예외를 던지지 않고 `{ exitCode: 0 \| 2 }`를 반환합니다.
+- `runCovenantCheck()`는 예외를 던지지 않고 `{ 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 covenant check`는 사람에게 묻지 않습니다. 표준 입력을 읽고 종료 코드 0 또는 2를 내며, 그 종료 코드의 뜻은 호출한 쪽이 정합니다.
 - `pdks docs`와 `pdks explain`은 실패 시 중간 출력 없이 끝납니다.
 
 <a id="polydeukes-see-also"></a>

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

@@ -2,63 +2,62 @@
 
 **English** · [한국어](./polydeukes.ko.md)
 
-The umbrella package is the only package a consumer installs. It owns the CLI bin, the config
-loader, the commit-surface runner, the session-surface runner subpath, and the bundled schema
-artifact.
+The umbrella package is the only package a consumer installs. It ships the `pdks` bin, the
+judge, both surfaces' composition roots, the session-surface runner subpath, and the bundled
+schema artifact.
 
 <a id="polydeukes-entry-points"></a>
 ## Entry points
 
-| Specifier | What it exports |
+| Specifier | What it is |
 |---|---|
-| `polydeukes` | `loadConfig`, `runCovenantCheck`, and `ResolvedConfig` |
-| `polydeukes/claude-code` | `runClaudeCodeHook` and its spec/outcome types |
+| `pdks` / `polydeukes` | The executable. One CLI under two names in `bin` |
 | `polydeukes/schema.json` | The bundled config JSON Schema |
 
-The package has one executable name in `bin`: `pdks`, with `polydeukes` as an alias.
+There is no `.` entry point. `import 'polydeukes'` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`;
+what a consumer reaches is the bin and the schema file. A session surface reaches this
+package the same way a shell does — by spawning `pdks covenant check` — so an agent adapter
+takes it as a peer dependency rather than importing it.
 
 <a id="polydeukes-bin"></a>
 ## CLI surface
 
 | Command | Purpose |
 |---|---|
-| `pdks covenant check` | Judge the staged diff, the working tree, or a ref range |
-| `pdks init claude-code` | Install the Claude Code session surface |
-| `pdks init grok` | Install the Grok session surface |
+| `pdks covenant check` | Judge an input IR (default, the session surface) or a unified diff (`--diff`, the change-set surface) from stdin |
+| `pdks init` | Create the project scaffold: config file and telemetry ignore line |
 | `pdks explain` | Render the assembled registration table without judging |
 | `pdks docs [topic]` | Read a bundled topic |
 | `pdks docs search <query>` | Search the bundled docs |
 | `pdks docs show <document-id>` | Show one bundled document or section |
 
-`pdks docs` is offline. It reads the installed package, not the network. Flags, JSON, and
-exit codes are in [`pdks docs`](../cli/docs.md).
+Session-surface installers live on the adapters: `pdks-claude-code init`, `pdks-grok init`, and
+`pdks-codex init`.
 
-<a id="polydeukes-export-map"></a>
-## Export map
+<a id="surface-from-input-mode"></a>
+### The input mode is the surface
 
-<a id="root-export"></a>
-### `.` root export
+`covenant check` reads its surface off how the input arrived, never off the input's own keys.
+An IR on stdin is one call a host observed before it ran, so the run is the **session surface**;
+`--diff` is a finished change set from some producer, so the run is the **change-set surface**.
+Each surface compiles the shared list plus its own:
 
-| Symbol | Kind | Notes |
+| Input | Surface | Lists compiled |
 |---|---|---|
-| `loadConfig` | function | Discovers exactly one `polydeukes.config.*` file under `rootDir`; throws on missing, ambiguous, parse, or validation failure. |
-| `runCovenantCheck` | function | Runs the commit-surface runner and resolves to `{ exitCode: 0 \| 2 }`. |
-| `ResolvedConfig` | type | Re-export from `@polydeukes/core`. |
-| `LoadConfigSpec`, `LoadedConfig` | types | Configuration loader input and result. |
-| `CovenantCheckSpec`, `CovenantCheckOutcome`, `CheckDomain` | types | Commit runner input, result, and observation selection. |
+| an input IR on stdin | `session` | `disciplines`, then `sessionDisciplines` |
+| a unified diff on stdin under `--diff` | `changeSet` | `disciplines`, then `changeSetDisciplines` |
 
-<a id="session-export"></a>
-### `./claude-code`
+The IR's `session` key says something else: what the host proved about the call — the witness
+valve's human turns, the transcript axis, and the pre-state channel shell-write evidence needs.
+A host that carries no session (the Grok adapter) is still judged on the session surface, and
+what it lacks is the evidence those three read, not the surface. `pdks explain` prints each
+surface with its two list names and counts.
 
-| Symbol | Kind | Notes |
-|---|---|---|
-| `runClaudeCodeHook` | function | Runs the session-surface runner and resolves to `{ exitCode: 0 \| 2 }`. |
-| `ClaudeCodeHookSpec` | type | Input for the session runner. |
-| `ClaudeCodeHookOutcome` | type | Session runner result. |
+`pdks docs` is offline. It reads the installed package, not the network. Flags, JSON, and
+exit codes are in [`pdks docs`](../cli/docs.md).
 
-The generated hook imports this subpath, not the barrel. ESM imports are eager, so importing the
-barrel would load the commit-surface runner — and the git adapter behind it — on every session tool
-call that will never use them.
+<a id="polydeukes-export-map"></a>
+## Export map
 
 <a id="schema-export"></a>
 ### `./schema.json`
@@ -67,67 +66,134 @@ call that will never use them.
 |---|---|
 | `polydeukes.schema.json` | The config schema copy that ships with the umbrella package. |
 
-<a id="polydeukes-signatures"></a>
-## Signatures and examples
+<a id="covenant-module"></a>
+## The judge (`covenant` module)
 
-```ts
-function loadConfig(spec: LoadConfigSpec): LoadedConfig;
+The judge is the umbrella's `src/covenant/` module. Everything that turns a declared promise
+into a verdict lives there, and both composition roots plus `pdks explain` import it directly.
+There is nothing to install, nothing to import, and no peer to satisfy: what you reach is its
+behaviour, through the `disciplines:` block in your config and the rows it writes to
+`.polydeukes/roi.log`.
 
-type LoadConfigSpec = { rootDir: string };
+<a id="ownership"></a>
+### What the module owns
 
-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'` is the `<base>...<head>` reading. `rawPayload` absent means the hook reads
-fd 0. The hook types live on `polydeukes/claude-code`, not on the root barrel.
+| Unit | What it does |
+|---|---|
+| `runCovenant` wrapper | Runs a judge body, translates its non-blocking `1` into the blocking `2`, and logs every call. No covenant runs unmeasured |
+| Path-routing dispatcher | Registers covenants against protected paths and runs *every* matching one — no short-circuit, so the telemetry never under-counts |
+| Meta-covenants | Three registrations that protect the judging chain itself |
+| TTL witness | The time-boxed human valve, consulted only after a verdict blocked |
+| 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
+observation as a world. What the declaration's sources bind decides what evidence the
+judgment needs, which is also what decides whether it can be judged on a given surface.
+
+| Sources | Judges | Evidence needed | List |
+|---|---|---|---|
+| the fixed names `target.path` · `pre` · `post` · `state` | The change itself | A file change | `disciplines` |
+| the fixed name `changes` | The observation's whole change set | A finished change set | `changeSetDisciplines` |
+| the fixed name `command` | The shell call's command line | A shell call — an Edit carries none | `sessionDisciplines` |
+| the fixed name `actor` | Who made the observation | An actor the host proved | `sessionDisciplines` |
+| `{ transcript: true }` | Session history — was a qualifying call actually executed *before* this one | A session | `sessionDisciplines` |
+| `{ file: … }` | Another file | The surface's reader for it | `disciplines` |
+| `{ sidecar: true }` | The spawn-record channel | The surface's channel reader | `sessionDisciplines` |
+
+The writing guide for these entries is [the configuration reference's `disciplines`
+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
+vocabulary below applies to them unchanged.
+
+| Registration | Axis | Judges |
+|---|---|---|
+| self-mod | Tool | Mutations to protected paths through editing tools. Only the call's proven mutation target is compared — a protected path inside an edit's *content* is a mention and passes |
+| shell-mod | Shell | The same, through a command line. A command mentioning a protected path passes only if its leading word proves it read-only |
+| transcript-mod | Transcript | Writes to the live session transcript, judged by whole-path **equality** — never as a protected ancestor |
 
-```ts
-import { loadConfig, runCovenantCheck } from 'polydeukes';
-import { runClaudeCodeHook } from 'polydeukes/claude-code';
+**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).
 
-const { configPath } = loadConfig({ rootDir: process.cwd() });
-const check = await runCovenantCheck({ repoRoot: process.cwd() });
-const hook = await runClaudeCodeHook({ repoRoot: process.cwd(), rawPayload: '{}' });
-```
+| Verdict | Means |
+|---|---|
+| `passed` | The call was judged and upheld the covenant |
+| `blocked` | The call was judged and broke it |
+| `witnessed` | A **blocked** verdict a human opened in person. Never silent, never a clean call |
+| `advised` | A break recorded without stopping the call — the default for every discipline entry on both surfaces, unless the entry itself says `enforce: block` |
+| `skipped` | The call reached a registration that could not judge it. **Not a pass** — the recorded absence of a judgment |
+| `unattributed` | A protected entry's on-disk state moved and no judgment row explains it. **Not a verdict** — no call is blocked or passed by it; the session surface writes it after comparing state against a stored baseline |
+
+`unattributed` answers a question the other five cannot. They are all written by a judge
+about a call it was handed, so a write that arrives without a declared call — through an
+interpreter, a test runner's child process, a script that assembles the path from its own
+arguments — leaves no row at all. The comparison observes the result rather than the
+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,
+  carrying its own telemetry label.
+- **`protectedPaths`**, which the path-routing dispatcher matches against.
+- **The `witness` block**, which arms the TTL valve.
+- **`.polydeukes/roi.log`**, where every judgment lands as one row.
+
+No import. The umbrella assembles the module for both surfaces.
+
+<a id="limits"></a>
+### Declared limits
+
+- **The shell axis leaves `skipped` rows, and that row is the contract.** Predicting a
+  shell command's target from its text is undecidable, so the invariant this axis holds is
+  not "nothing gets through" — it is that **no call passes unrecorded**. A new spelling
+  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 session-only declaration on a host that proves no session records `skipped`.** The
+  entry is compiled — it is on the session surface — but the transcript the declaration binds
+  is absent, and the entry's own `supply: pass` disposes of that with a `skipped` row carrying
+  the reason `supply-pass`. With no policy the missing session is unjudgeable (exit 2), not an
+  automatic skip.
+- **A surface never registers the other surface's list.** A `command` or transcript
+  declaration is not compiled for a change set, and a `changes` declaration is not compiled for
+  one call, so neither leaves a row on the surface that does not observe it. Which entries a
+  surface carries is read from `pdks explain` and from the config's own list names, not from
+  the telemetry log.
+- **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 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: config loading 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
+  telemetry targets, not block targets. The two friction valves — the read-only allowlist
+  and the TTL witness — both leave a measurable trace.
+- **The valve stands after the verdict.** Only a judgment that actually blocked can be
+  witnessed open, a mid-sentence mention of the token does not arm it, and an AI can never
+  open the valve for itself.
 
 <a id="polydeukes-failure-boundaries"></a>
 ## Failure boundaries
 
-- `loadConfig()` throws on missing, ambiguous, parse, or validation failure.
-- `runCovenantCheck()` and `runClaudeCodeHook()` never throw; they resolve to `{ exitCode: 0 \| 2
-}`.
+- `runCovenantCheck()` never throws; it resolves to `{ exitCode: 0 \| 2 }`.
 - The numeric codes are `EXIT_UPHOLD` (`0`), `EXIT_BREAK_NON_BLOCKING` (`1`), and
   `EXIT_BREAK_BLOCKING` (`2`) from `@polydeukes/core`. The umbrella runners expose only `0` or
   `2`; they never return `1`.
-- `pdks covenant check` prompts for a witness token only for the staged domain, never for
-`--worktree` or `--range`.
+- `pdks covenant check` never prompts. It reads stdin and exits 0 or 2; the caller decides what
+that exit code means.
 - `pdks docs` and `pdks explain` print nothing partial on failure.
 
 <a id="polydeukes-see-also"></a>