polydeukes 0.5.0 → 0.6.1

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,10 +9,16 @@
 > 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.
 
+**This is the install unit for judgment.** An embedder that wants verdicts without the
+umbrella's surfaces installs this package and provides `@polydeukes/core` alongside it — core
+is a `peerDependency` here, so the vocabulary is shared rather than duplicated. The umbrella
+is what satisfies that peer for an ordinary consumer.
+
 | 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 |
@@ -22,22 +28,23 @@ The judge. Everything that turns a declared promise into a verdict lives here.
 | 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 belongs to exactly one family**, decided by which predicate key it
-carries. The family determines what evidence the judgment needs — which is also what
-determines whether it can be judged on a given surface.
+**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.
 
-| Family | Key | Judges | Evidence needed |
-|---|---|---|---|
-| delta | `forbid` | Added-direction content of a file change. Existing debt is forgiven; only new occurrences break | File change |
-| path | `immutable` | Any change to a file that already exists — modification or deletion alike. Creation passes | File change |
-| command | `forbidCommand` | The command line itself | None |
-| context | `requirePrecedent` | Session history — was a qualifying call actually executed *before* this one | A transcript |
+| Sources | Judges | Evidence needed |
+|---|---|---|
+| the fixed names `target.path` · `pre` · `post` · `state` · `changes` | The change itself | A file change |
+| the fixed name `command` | The shell call's command line | A shell call — an Edit carries none |
+| `{ transcript: true }` | Session history — was a qualifying call actually executed *before* this one | A session |
+| `{ file: … }` · `{ sidecar: true }` | Another file, or the spawn-record channel | The surface's reader for it |
 
-`when` is a trigger, not a family: it narrows a `requirePrecedent` entry and combines with
-nothing else. The writing guide for these entries — the four predicate forms, the two
-pitfalls — is [the configuration reference's `disciplines` section](./configuration.md#disciplines).
+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.
@@ -51,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 |
 |---|---|
@@ -69,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,
@@ -79,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
@@ -86,18 +95,24 @@ No import. The umbrella assembles this package for both surfaces.
   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.
-- **The context family cannot be judged without a session.** On the commit surface there is
-  none, so a matching `requirePrecedent` entry always records `skipped`. That is a permanent
-  condition of that surface.
-- **The command family is absent from the commit surface, and absent without a row.**
-  `forbidCommand` entries are filtered out before compilation there, since a staged diff
-  carries no command line to judge. Unlike the context family this leaves nothing in
-  `.polydeukes/roi.log`, so the log cannot separate a command discipline that never
-  triggered from one that was never registered on that surface.
-- **An unjudgeable entry compiles to a skip registration** — routing intact, no body. A
-  pattern that does not compile skips the same way. 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 declaration that reads the session cannot be judged without one.** On the commit
+  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 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)

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

@@ -0,0 +1,139 @@
+# `polydeukes`
+
+**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.
+
+<a id="polydeukes-entry-points"></a>
+## Entry points
+
+| Specifier | What it exports |
+|---|---|
+| `polydeukes` | `loadConfig`, `runCovenantCheck`, and `ResolvedConfig` |
+| `polydeukes/claude-code` | `runClaudeCodeHook` and its spec/outcome types |
+| `polydeukes/schema.json` | The bundled config JSON Schema |
+
+The package has one executable name in `bin`: `pdks`, with `polydeukes` as an alias.
+
+<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 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).
+
+<a id="polydeukes-export-map"></a>
+## Export map
+
+<a id="root-export"></a>
+### `.` root export
+
+| Symbol | Kind | Notes |
+|---|---|---|
+| `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. |
+
+<a id="session-export"></a>
+### `./claude-code`
+
+| 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. |
+
+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="schema-export"></a>
+### `./schema.json`
+
+| Artifact | Notes |
+|---|---|
+| `polydeukes.schema.json` | The config schema copy that ships with the umbrella package. |
+
+<a id="polydeukes-signatures"></a>
+## Signatures and examples
+
+```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'` 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.
+
+```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>
+## Failure boundaries
+
+- `loadConfig()` throws on missing, ambiguous, parse, or validation failure.
+- `runCovenantCheck()` and `runClaudeCodeHook()` never throw; they resolve 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 docs` and `pdks explain` print nothing partial on failure.
+
+<a id="polydeukes-see-also"></a>
+## See also
+
+- [`pdks covenant check`](../cli/covenant-check.md)
+- [`pdks init`](../cli/init.md)
+- [`pdks explain`](../cli/explain.md)
+- [`Configuration reference`](../configuration/index.md)

package/dist/docs/troubleshooting.ko.md

@@ -0,0 +1,142 @@
+# Polydeukes 문제 해결
+
+[English](./troubleshooting.md) · **한국어**
+
+정책을 바꾸기 전에 어느 단계에서 실패했는지 확인하세요. 세션이 복구 명령까지 차단한다면
+본인의 터미널에서 실행합니다. `pdks docs`는 동봉 문서가 온전하면 프로젝트 설정이나
+판정 관련 패키지가 없어도 사용할 수 있습니다.
+
+<a id="no-config"></a>
+## 설정 파일이 없을 때
+
+프로젝트 루트 바로 아래에 `polydeukes.config.yaml`, `polydeukes.config.yml`,
+`polydeukes.config.json` 중 하나도 없으면 설정이 필요한 명령은 종료 코드 2를 반환합니다.
+Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init claude-code` 또는
+`pdks init grok`로 만들 수 있습니다. 이후 `pdks explain`을 실행합니다. 설정이 없다고
+기본 정책으로 대신 실행하지는 않습니다.
+
+<a id="multiple-config"></a>
+## 설정 파일이 여러 개일 때
+
+오류 메시지에 중복된 파일명이 나옵니다. 필요한 내용을 합친 뒤 허용되는 파일명 하나만
+남기세요. 로더는 어느 파일을 사용할지 임의로 선택하지 않습니다. 정리한 뒤
+`pdks explain`을 다시 실행합니다.
+
+<a id="invalid-config"></a>
+## 설정 오류
+
+구문이나 스키마 오류가 있으면 종료 코드 2와 함께 파일명을 알립니다. 스키마 오류는 문제가
+있는 필드도 알려 줍니다. 잘못된 YAML, 사용자 정의 태그, 알 수 없는 필드, 비어 있는
+`languages` 객체를 고치세요. YAML 태그는 파서가 실행할 수 없더라도 거부합니다.
+설정은 실행할 코드가 아니라 데이터이기 때문입니다.
+
+`protectedPath:`나 `adaptors:` 같은 오타는 거부합니다. 다만 어댑터 이름에는 확장 가능성을
+남겨 두었습니다. `adapters.gti:`도 설정으로 읽히지만 Git 어댑터는 사용하지 않습니다.
+올바른 키는 `adapters.git`입니다. 수정한 뒤 `pdks explain`에서 실제 등록 내용을 확인하세요.
+
+<a id="grok-witness"></a>
+## Grok 증인
+
+훅을 아직 읽지 않은 문제와 증인(witness) 밸브를 사용할 수 없는 문제는 구별해야 합니다.
+
+- `pdks init grok` 실행 뒤 Hooks 탭을 다시 불러오거나 새 세션을 시작하세요. 실제 도구를
+  호출하고 텔레메트리를 확인합니다. 설치기가 성공했다고 해서 열린 세션에 훅이 적용됐다는
+  뜻은 아닙니다.
+- Grok의 ACP 대화 기록에는 현재 세션 증인 밸브가 요구하는 Claude 형식의 인간 메시지가
+  없습니다. 다시 불러와도 이 기능이 생기지는 않습니다. 복구가 필요하면 Grok에 Claude용
+  증인 토큰을 보내려 하지 말고 본인의 터미널에서 작업하세요.
+
+커밋 증인은 해당 스테이징 검사만 허용합니다. 차단된 Grok 도구 호출까지 허용하지 않습니다.
+
+<a id="config-fault"></a>
+## 선언을 판정으로 구성하지 못할 때
+
+설정은 읽었지만 어떤 항목을 판정할 수 있는 형태로 컴파일하지 못한 경우입니다. 적용 범위가
+일치하면 `skipped`와 사유 `config-fault`를 기록합니다. `pdks explain`에서도 원인을 볼 수
+있습니다. 추출 단계 이름, 인수, 정규식 문법, 쌍과 단일 추출 결과의 사용을 확인하세요.
+지목된 선언을 고친 뒤 같은 관측으로 다시 검사합니다. 미판정은 정상 판정이 아닙니다.
+
+<a id="judge-cannot-be-loaded"></a>
+## 판정기를 불러올 수 없을 때
+
+패키지나 판정 모듈이 빠져 있으면 작업을 차단합니다. 본인의 터미널에서 패키지를 다시
+설치하거나 워크스페이스 전체를 빌드하세요. 생성된 훅은 설치된 패키지에 판정을 맡기며,
+판정기를 별도로 복사해 가지고 있지 않습니다. 복구 뒤 실제 호출로 다시 확인합니다.
+텔레메트리를 불러오기 전에 실패했다면 기록이 전혀 남지 않을 수도 있습니다.
+
+세션 훅은 메시지 앞에 `covenant hook failed closed:`를, 커밋 검사는
+`covenant check failed closed:`를 붙입니다. 실제로 보게 되는 두 형태는 다음과 같습니다.
+
+```text
+covenant hook failed closed: Cannot find package 'polydeukes' imported from …
+covenant check failed closed: the covenant judges could not be loaded from … — run 'pnpm build' to rebuild them: Cannot find module './self-mod.js' …
+```
+
+첫째는 설치된 패키지가 없는 경우이고, 둘째는 소스 체크아웃에서 판정기 빌드 산출물이 없거나
+일부만 있는 경우입니다.
+
+<a id="reading-verdict"></a>
+## 판정 결과 읽기
+
+| 기록 | 의미 |
+|---|---|
+| `passed` | 관측한 입력을 판정했으며 약속(covenant)을 지켰습니다. |
+| `blocked` | 위반 때문에 작업을 멈췄습니다. |
+| `witnessed` | 차단 결과가 나왔지만 증인 밸브를 통해 작업을 허용했습니다. |
+| `advised` | 위반을 기록하되 작업을 멈추지 않았습니다. 두 표면 모두에서 나올 수 있습니다. |
+| `skipped` | 적용 범위가 일치한 등록을 판정할 수 없었습니다. 정상 판정이 아닙니다. |
+| `unattributed` | 기준 상태와 비교해 판정으로 설명되지 않는 보호 대상의 변경을 발견했거나, 유효한 기준 상태를 읽지 못했습니다. 판정 결과가 아니라 관측 기록입니다. |
+
+판정은 기본적으로 `.polydeukes/roi.log`에 추가됩니다. `telemetry.logPath`로 위치를 바꿀 수
+있습니다. 로그 쓰기에 실패하더라도 판정 결과는 바뀌지 않습니다. 종료 코드 0은 작업을
+계속해도 된다는 뜻이지 모든 규율을 지켰다는 뜻은 아닙니다.
+
+<a id="opening-a-blocked-call"></a>
+## 차단된 호출을 증언으로 허용하기
+
+지원되는 Claude Code 세션에서 설정된 증인 토큰을 인간 메시지의 첫 줄에 단독으로 입력한 뒤,
+유효 시간 안에 다시 시도합니다. 보호 대상을 의도적으로 편집하기 전에 입력해도 됩니다.
+먼저 한 번 차단돼야 하는 것은 아닙니다. 토큰은 비밀이 아니며, 밸브는 사람이 직접 입력했는지
+확인하고 차단 판정에만 적용됩니다. 증언으로 허용한 호출은 `witnessed` 행을 새로 남깁니다.
+앞서 기록한 `blocked` 행을 고치는 것이 아닙니다.
+
+모듈 누락처럼 판정기를 조립하지 못하게 하는 오류는 증인으로 해결할 수 없습니다.
+
+<a id="blocked-commit"></a>
+## 커밋이 차단됐을 때
+
+본인의 터미널에서 커밋을 실행하고 TTY 프롬프트에 설정된 토큰 전체를 입력하세요.
+비대화형 스테이징 검사는 이 응답을 받을 수 없습니다. 검사가 작업을 거부하면 종료 코드 2를
+반환합니다. Git은 커밋 실패를 다른 0이 아닌 코드로 알릴 수도 있습니다.
+
+일반 규율 항목은 자체 수준과 어댑터 수준이 모두 차단을 허용해야 작업을 멈춥니다.
+`adapters.git.enforce: block`만 설정해도 기본값 `advise`인 항목이 자동 승격되지는 않습니다.
+수준 변경은 정책을 바꾸는 결정이지 필수 복구 절차가 아닙니다. 커밋 프롬프트와 세션 메시지는
+서로 별개의 증인 입력 경로입니다.
+
+<a id="skipped-rows-on-the-commit-surface"></a>
+## 커밋 표면의 미판정 기록
+
+대화 기록을 읽는 선언에 `supply: { session: 'pass' }`가 있으면 세션이 없는 커밋 표면에서는
+`supply-pass`를 기록합니다. 이 약속은 세션 표면에서 확인하세요. 미판정은 과거 작업을
+검증했다는 뜻이 아닙니다. 다른 채널을 공급할 수 없으면 `no-observation`이 나올 수도
+있습니다. 모든 자료 부재를 같은 실패로 취급하지 말고 등록 내용과 사유를 확인하세요.
+
+스테이징한 변경에는 명령줄이 없으므로 명령 범위 선언은 적용되지 않으며 판정도 기록하지
+않습니다. 설정, 범위 일치, 자료 공급, 최종 비교는 각각 다른 단계입니다.
+
+<a id="local-state"></a>
+## 다른 컴퓨터로 프로젝트를 옮길 때
+
+텔레메트리와 `.polydeukes/baseline.json`은 로컬 상태이며 Git이 옮겨 주는 판정 이력이
+아닙니다. 이 파일 없이 저장소를 복제해도 과거 판정이 복원되지는 않습니다. 세션 훅은 기준
+상태가 없거나 유효하지 않으면 이를 기록하고 다음 비교에 쓸 기준을 만듭니다. 과거 변경을
+판정했다는 증거가 생기는 것은 아닙니다. 필요한 로그는 따로 보관해 옮기세요.
+`telemetry.logPath`를 바꿨다면 모든 기록이 `.polydeukes/`에 있다고 가정해서는 안 됩니다.
+
+<a id="next-steps"></a>
+## 다음 단계
+
+- [표면 연결하기](./how-to/connect-surfaces.ko.md)
+- [프로젝트 설정하기](./how-to/configure-project.ko.md)
+- [규율 작성하기](./how-to/write-disciplines.ko.md)