polydeukes 0.6.1 → 0.7.1

package/dist/docs/reference/packages/adapter-grok.md

@@ -0,0 +1,79 @@
+# `@polydeukes/adapter-grok`
+
+**English** · [한국어](adapter-grok.ko.md)
+
+> **The Grok install unit** — PreToolUse payloads become the covenant input IR, with the
+> file-change evidence the judge reads, and the package installs the session surface into a
+> project.
+>
+> Alpha. Install it next to `polydeukes`, which it names as a `peerDependency`.
+
+<a id="ownership"></a>
+## What this package owns
+
+The boundary where Grok's vocabulary is translated away. Agent and tool literals live *here*
+by design, so that they never reach the core.
+
+| Unit | What it does |
+|---|---|
+| `pdks-grok` bin | One subcommand, `pdks-grok init`, which registers the session surface in a project |
+| `runHook` | Translates one PreToolUse payload into the input IR and spawns the judge |
+| Payload up-translation | A raw PreToolUse payload becomes a `CovenantInput` |
+| Virtual post-state | Computes what a file *would* contain after a write or substitution applies, without touching disk |
+| File-change evidence | Pairs the disk pre-state with the virtual post-state into union evidence |
+
+`runHook({ repoRoot })` is what the generated hook delegator imports. It builds the IR — the
+`tools` roster included, with no `session` or `actor` key — then spawns
+`pdks covenant check --enforce block` in `repoRoot` and returns the child's exit code. The
+judging happens in that child process; this package carries no judgment logic.
+
+**This package writes no telemetry rows.** A failure before the spawn is sent to `pdks` on
+stdin as a plain line, and `pdks` records the fail-closed row, so one call still leaves one
+row. It never imports the judge: `polydeukes` and `@polydeukes/core` are both
+`peerDependencies`, so the vocabulary and the judge are shared rather than installed a second
+time here.
+
+The roster this adapter puts on the IR is Grok-native: `write` and `search_replace` mutate a
+file; `run_terminal_command` carries a shell line.
+
+<a id="consumer-contract"></a>
+## Where the consumer touches it
+
+Two lines install the Grok session surface, run from the project root:
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-grok
+npx pdks-grok init
+```
+
+`pdks-grok init` resolves `polydeukes` from the project, spawns `pdks init` for the
+agent-neutral scaffold, then writes the two Grok artifacts non-destructively. A re-run
+reports each existing artifact as skipped and overwrites nothing. The full artifact list is in
+[`pdks init`](../cli/init.md#init-grok).
+
+Installing both this adapter and `@polydeukes/adapter-claude-code` in one project can run the
+judge twice per call.
+
+- **The generated hook** imports `runHook` from this package. Upgrading the package upgrades
+  what runs; the hook file itself never changes.
+
+No configuration namespace of its own.
+
+<a id="limits"></a>
+## Declared limits
+
+- **A child process's writes are outside observation.** This surface judges *declared tool
+  calls*. A command that spawns a process which then writes files is judged on the command,
+  not on what the child did.
+- **Evidence exists only where a post-state can be computed.** `write` and `search_replace`
+  contribute one. A substitution that matches nothing, or that matches more than once without
+  `replace_all`, yields no evidence — the host tool refuses those calls.
+- **An evidence-free call falls back to the conservative judgment** — the call's arguments
+  are compared for a mention rather than a proven target.
+- **There is no transcript channel.** The IR omits `session` and `actor`. Grok's ACP history
+  does not supply the human-message evidence the session witness valve needs. For an
+  intentional blocked edit, use your own terminal.
+- **An unresolvable `polydeukes` leaves no row.** When the umbrella cannot be resolved from the
+  project there is no process to spawn and no log path to write to, so the hook exits `2` with
+  one line on stderr and the telemetry log gains nothing. Every other pre-spawn failure does
+  reach `pdks` and does leave a row.

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

@@ -28,7 +28,7 @@
 **값**이라서, 코어의 에이전트 중립성은 grep으로 확인되는 주장입니다. 다른 모든 패키지가
 이 패키지에 의존하고, 이 패키지는 그 어느 것에도 의존하지 않습니다.
 
-**판정기와 두 어댑터는 이 패키지를 `peerDependency`로 선언합니다.** 각각 설치하는 대신 같은 어휘를 공유합니다. `SOURCE_KINDS`와
+**세션 어댑터는 이 패키지를 `peerDependency`로 선언합니다.** 따로 설치하는 대신 우산과 같은 어휘를 공유합니다. `SOURCE_KINDS`와
 `parseInput`은 검증기와 엔진이
 같은 값을 참조해야 합니다. 서로 다른 사본을 사용하면 설치는 성공해도 동작이 달라질 수 있습니다.
 통합 패키지가 일반 의존성으로 core를 제공하므로 사용자는 패키지 하나만 설치하면 됩니다.
@@ -41,7 +41,10 @@
 `.polydeukes/roi.log`의 차단 기록도 이 판정 어휘를 사용합니다.
 
 `world`는 표면이 공급합니다(`files`, `changes`, `channels`). 판정기가 디스크에서 읽지
-않습니다.
+않습니다. `tools`와 `session`은 호스트가 공급합니다. 명부는 어댑터가 채우는 값이고, 세션은
+IR만으로는 증명하지 못하는 두 사실, 메시지의 신선도와 호출의 결과를 담은 증거입니다.
+`transcriptFromSession`은 그 키에서 증인이나 선행 조건 소비자가 읽는 대화 기록을 만들고,
+`transcriptFromInput`은 그 두 사실 없이 IR에서 같은 대화 기록을 만듭니다.
 
 ```ts
 type CovenantInput = {
@@ -54,6 +57,13 @@ type CovenantInput = {
     changes?: string[];
     channels?: { sidecar?: string };
   };
+  tools?: { mutating: string[]; shell: string[]; commandArgs: string[] };
+  session?: {
+    evidencePath?: string;
+    userMessages: { text: string; timestampMs?: number }[];
+    toolCalls: { name: string; args?: Record<string, unknown>; succeeded?: boolean }[];
+    channels?: { sidecar?: string };
+  };
 };
 
 type FileChange =
@@ -98,6 +108,42 @@ function allFileChanges(input: CovenantInput): FileChange[];
 `allFileChanges`는 귀속이 필요 없는 소비자를 위해 모든 호출의 증거를 호출 순서대로
 평탄화합니다. 증거 없는 호출은 건너뛰고 무엇으로도 대체하지 않습니다.
 
+<a id="discipline-lists"></a>
+## 규율 목록 셋과 통로 유도
+
+`defineConfig()`는 규율 목록 셋을 받고, 항목마다 그것이 맞는 목록에 적혔는지 판정합니다.
+
+| 키 | 타입 | 판정하는 표면 |
+|---|---|---|
+| `disciplines` | `(DisciplineEntry \| DisciplineDraft)[]` | 두 표면 모두 |
+| `sessionDisciplines` | `DisciplineEntry[]` | 세션 표면(session surface)만 |
+| `changeSetDisciplines` | `DisciplineEntry[]` | 변경 집합 표면(change-set surface)만 |
+
+`ResolvedConfig`도 같은 이름으로 셋을 싣되 판정 항목만 담고, 초안(draft)은 `drafts`로 갈라
+둡니다. 입력이 선언하지 않은 목록은 빈 배열이 되지 않고 없는 채로 남습니다.
+
+검증기와 우산 패키지가 함께 쓰는 유도는 내보내는 함수 하나입니다.
+
+```ts
+type DeclarationChannel = 'transcript' | 'channel' | 'command' | 'actor' | 'changes';
+
+function declarationChannels(body: Omit<AlgebraDeclaration, 'discipline'>): DeclarationChannel[];
+```
+
+순수하고 구문적인 함수라서 선언을 실행하지 않습니다. `transcript`는 `{ transcript: true }`
+바인딩에서, `channel`은 `{ sidecar: true }` 바인딩에서, `command`는
+`scope.source === 'command'`나 `{ op: 'source', of: 'command' }` 단계에서, `actor`는
+`{ op: 'source', of: 'actor' }` 단계에서, `changes`는
+`{ op: 'source', of: 'changes' }` 단계에서 나옵니다. `witness` 블록 자신의 `extract`도 본체와
+함께 훑습니다. 반환 목록은 위 표의 고정 순서를 따르므로, 통로 집합을 비교하는 두 호출자가 같은
+목록을 비교합니다.
+
+다섯 가운데 하나도 이름 짓지 않는 본체는 변경된 파일과 저장소 파일만 읽고 그 둘은 두 표면이
+모두 공급하므로 `disciplines`에 속합니다. 그 밖은 항목과 통로와 가야 할 목록을 대는
+`ConfigValidationError`이며, 메시지는
+[설정 참조](../configuration/index.ko.md#placement-rule)에 있습니다. 우산 패키지는 같은 질문을
+따로 답하지 않고 이 함수를 불러 씁니다.
+
 <a id="consumer-contract"></a>
 ## 사용자와의 접점
 
@@ -119,7 +165,7 @@ function allFileChanges(input: CovenantInput): FileChange[];
 - **어댑터 네임스페이스는 이름이 아니라 형태로 검증합니다.** `defineConfig()`는 `adapters`가
   평범한 객체의 맵인지, 각 네임스페이스 값이 객체인지를 봅니다. 네임스페이스 **이름**이
   누군가 구현한 것인지는 보지 않고, 네임스페이스 안쪽은 들여다보지 않습니다.
-  `adapters.git` 안의 미지 어휘는 git 어댑터의 검증기가 자기 층위에서 거부합니다. 여기가
+  네임스페이스 안의 미지 어휘는 해당 어댑터의 검증기가 자기 층위에서 거부합니다. 여기가
   아닙니다.
 - **기본 대화 기록은 아무것도 하지 않습니다.** 실제 대화 기록을 주입하지 않은 소비자는
   "아무 일도 없었다"는 결과를 받습니다. 이 상태에서는 증인 밸브가 작업을 허용하지 않으므로

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

@@ -28,8 +28,8 @@ hand-rolled and the published JSON Schema is a sibling artifact the source never
 *values* supplied by configs and adapters, so the core's agent-neutrality is a claim a grep
 can check. Every other package depends on this one; this one depends on none of them.
 
-**The judge and the two adapters name it as a `peerDependency`, not a dependency of their
-own.** They share the vocabulary rather than each installing a copy — `SOURCE_KINDS` and
+**The session adapter names it as a `peerDependency`, not a dependency of its
+own.** It shares the vocabulary with the umbrella rather than installing a copy — `SOURCE_KINDS` and
 `parseInput` have to be one set of values for the validator and the engine to agree, and two
 copies would disagree silently instead of failing at install time. The umbrella carries the
 ordinary dependency that satisfies that peer, which is why a consumer still installs one
@@ -44,7 +44,11 @@ verdict the wrapper translates into an exit code. Blocked rows in `.polydeukes/r
 use this judgment vocabulary.
 
 `world` is supplied by the surface (`files`, `changes`, `channels`). The judge does not
-read it from disk.
+read it from disk. `tools` and `session` are supplied by the host: the roster is values the
+adapter fills in, and the session is the evidence a live agent session proves that a bare
+IR cannot — message freshness and call outcome. `transcriptFromSession` wraps that key as
+the transcript a witness or a precedent consumer reads, the way `transcriptFromInput` wraps
+the bare IR without those two facts.
 
 ```ts
 type CovenantInput = {
@@ -57,6 +61,13 @@ type CovenantInput = {
     changes?: string[];
     channels?: { sidecar?: string };
   };
+  tools?: { mutating: string[]; shell: string[]; commandArgs: string[] };
+  session?: {
+    evidencePath?: string;
+    userMessages: { text: string; timestampMs?: number }[];
+    toolCalls: { name: string; args?: Record<string, unknown>; succeeded?: boolean }[];
+    channels?: { sidecar?: string };
+  };
 };
 
 type FileChange =
@@ -101,6 +112,44 @@ The exported constants are `EXIT_UPHOLD` (`0`), `EXIT_BREAK_NON_BLOCKING` (`1`),
 `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="discipline-lists"></a>
+## The three discipline lists and the channel derivation
+
+`defineConfig()` accepts three discipline lists and decides, for each entry, whether it is
+written in the right one.
+
+| Key | Type | Judged on |
+|---|---|---|
+| `disciplines` | `(DisciplineEntry \| DisciplineDraft)[]` | both surfaces |
+| `sessionDisciplines` | `DisciplineEntry[]` | the session surface only |
+| `changeSetDisciplines` | `DisciplineEntry[]` | the change-set surface only |
+
+`ResolvedConfig` carries the three under the same names, holding judged entries only, with the
+drafts split out into `drafts`. A list the input did not declare stays absent rather than
+becoming an empty array.
+
+The derivation both the validator and the umbrella use is one exported function:
+
+```ts
+type DeclarationChannel = 'transcript' | 'channel' | 'command' | 'actor' | 'changes';
+
+function declarationChannels(body: Omit<AlgebraDeclaration, 'discipline'>): DeclarationChannel[];
+```
+
+It is pure and syntactic — the declaration is never run. `transcript` comes from a
+`{ transcript: true }` binding, `channel` from a `{ sidecar: true }` binding, `command` from
+`scope.source === 'command'` or a `{ op: 'source', of: 'command' }` step, `actor` from a
+`{ op: 'source', of: 'actor' }` step, and `changes` from a
+`{ op: 'source', of: 'changes' }` step. A `witness` block's own `extract` is walked with the
+body's. The returned list is in the fixed order above, so two callers comparing channel sets
+compare the same list.
+
+A body naming none of the five reads the changed file and repository files alone, which both
+surfaces supply, so it belongs in `disciplines`. Anything else is a `ConfigValidationError`
+naming the entry, its channels, and the list it belongs in; the messages are in [the
+configuration reference](../configuration/index.md#placement-rule). The umbrella imports this
+function rather than answering the same question a second time.
+
 <a id="consumer-contract"></a>
 ## Where the consumer touches it
 
@@ -123,8 +172,8 @@ Everything else here is reached through `polydeukes`.
 - **Adapter namespaces are validated by shape, not by name.** `defineConfig()` checks that
   `adapters` is a map of plain objects and that each namespace value is an object. It does
   not check that a namespace *name* is one anybody implements, and it does not look inside
-  the namespace at all. Unknown vocabulary inside `adapters.git` is rejected by the git
-  adapter's own validator, at its own layer — not here.
+  the namespace at all. Unknown vocabulary inside a namespace is rejected by that adapter's
+  own validator, at its own layer — not here.
 - **The default transcript is a noop.** A consumer that injects no real transcript
   converges on "nothing happened", which is the safe direction for a valve: it never opens.
   Real transcripts live behind adapters.

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

@@ -2,61 +2,62 @@
 
 [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`입니다.
 
-<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 +66,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>