polydeukes 0.6.0 → 0.7.1

package/dist/docs/reference/packages/sdk-ts.md

@@ -0,0 +1,164 @@
+# `@polydeukes/sdk-ts`
+
+**English** · [한국어](sdk-ts.ko.md)
+
+> **One verb from TypeScript to the judge** — hand a covenant input IR to
+> `pdks covenant check` and read the verdict back as a value.
+>
+> Alpha. Install it next to `polydeukes` and `@polydeukes/core`, which it names as
+> `peerDependencies`.
+
+<a id="ownership"></a>
+## What this package owns
+
+The spawn and the translation of an exit status into a value, and nothing else. It locates the
+`polydeukes` install of the project being judged, runs its bin with the input on stdin, and
+returns what the child answered. No judgment logic lives here: the branches are whether the
+umbrella resolved and what status the child left with.
+
+| Unit | What it does |
+|---|---|
+| `checkCovenant` | Spawns `pdks covenant check` in the judged project and returns the verdict |
+| Umbrella resolution | Finds `polydeukes` in the install graph of `repoRoot` and reads its `pdks` bin |
+| Verdict translation | Exit `0` is `upheld`, exit `2` is `blocked`, everything else is `unjudged` |
+
+This package writes no telemetry row. Every row a run leaves is written by the child process,
+where the judgment happened, so one call still leaves one row.
+
+<a id="install"></a>
+## Install
+
+```sh
+pnpm add @polydeukes/sdk-ts polydeukes @polydeukes/core
+```
+
+There is no bin and no install step. The umbrella supplies the judge the SDK spawns, and the
+core supplies the `CovenantInput` type the caller fills in.
+
+<a id="verb"></a>
+## The verb
+
+```ts
+import { checkCovenant } from '@polydeukes/sdk-ts';
+
+const verdict = await checkCovenant({
+  repoRoot: '/path/to/the/project',
+  input: {
+    toolCalls: [
+      {
+        name: 'writeFile',
+        args: { path: 'src/index.ts', content: 'export const answer = 42;\n' },
+        fileChange: {
+          kind: 'modify',
+          path: 'src/index.ts',
+          pre: 'export const answer = 41;\n',
+          post: 'export const answer = 42;\n',
+        },
+      },
+    ],
+    subagentSpawns: [],
+    userMessages: [],
+    tools: { mutating: ['writeFile', 'rm'], shell: ['exec'], commandArgs: ['command'] },
+  },
+});
+```
+
+The IR is the caller's. This package neither reads it nor completes it: it adds no `session`,
+no `actor`, and no roster of its own, and the `tools` values above are the caller's own tool
+names. `subagentSpawns` and `userMessages` are required collections, so a caller with neither
+sends the empty arrays. A `world` key is refused by the judge — the runner reads the world from
+the project on disk, and a client choosing the world would be choosing what is judged.
+
+<a id="spec"></a>
+## The spec
+
+```ts
+type CheckCovenantSpec = {
+  repoRoot: string;
+  input: CovenantInput;
+  enforce?: 'advise' | 'block';
+  spawn?: (spec: CheckCovenantSpawnSpec) => Promise<{ status: number | null; stderr: string }>;
+};
+
+type CheckCovenantSpawnSpec = { command: string; args: string[]; cwd: string; stdin: string };
+```
+
+| Field | What it is |
+|---|---|
+| `repoRoot` | The project being judged: config discovery, the world axis, the child's cwd, and the install graph the umbrella is found in |
+| `input` | The caller's own IR, sent verbatim as the child's stdin |
+| `enforce` | The observer's posture for the whole run. **Absent is `block`** |
+| `spawn` | An injected spawn seam. Absent, the child runs under this process's node executable |
+
+**`enforce` defaults to `block`.** That is the surface's level, not an entry's: protected paths
+and entries carrying `enforce: block` stop the call, and every other break is recorded
+`advised` at exit 0. An entry's own level composes with it lenient-side-wins, as on every other
+surface. `@polydeukes/adapter-claude-code` and `@polydeukes/adapter-grok` spawn the judge at
+the same level.
+
+The default spawn inherits no file descriptor. A caller may hold none of its own, and an
+inherited stdout that is closed would kill the child with EPIPE before it answered. stderr is
+collected and returned; stdout is drained and dropped, because the judge writes no verdict
+there.
+
+<a id="verdicts"></a>
+## The three verdicts
+
+```ts
+type CheckCovenantVerdict =
+  | { verdict: 'upheld'; advisories: string }
+  | { verdict: 'blocked'; reason: string }
+  | { verdict: 'unjudged'; reason: string };
+```
+
+| Verdict | Child status | What it means for the caller |
+|---|---|---|
+| `upheld` | `0` | The call was judged and nothing blocked it. `advisories` is the child's stderr verbatim, carrying any advisory lines the run produced. Proceed |
+| `blocked` | `2` | The call was judged and something blocked it. `reason` is the child's stderr verbatim. Do not proceed |
+| `unjudged` | anything else, or no umbrella | No judgment happened. `reason` says which. Reading it as an uphold would let an uninstalled judge pass every call |
+
+**There is no valve, and the reason is the substitute.** An unattended real-time caller has no
+TTY and no human turn, so this package takes no witness argument and invents no session.
+`blocked.reason` and `upheld.advisories` come back as data instead, and the consumer decides
+where the text goes — an issue, a log, or back to the model. The posture rules for a config
+author and for a consumer are in [write disciplines](../../how-to/write-disciplines.md#posture).
+
+<a id="failure"></a>
+## A failure example
+
+When the project has no `polydeukes` installed there is nothing to spawn, and the verb says so
+rather than answering `upheld`:
+
+```ts
+const verdict = await checkCovenant({ repoRoot: '/tmp/project-without-polydeukes', input });
+
+// {
+//   verdict: 'unjudged',
+//   reason: 'no polydeukes in the install graph of /tmp/project-without-polydeukes:
+//            install it to have this input judged',
+// }
+```
+
+No child process runs, and the telemetry log gains nothing: the row is written where the
+judgment happens, and no judgment happened.
+
+<a id="limits"></a>
+## Declared limits
+
+- **The caller builds the IR.** The tool roster, the pre-state, and the envelope are the
+  host's facts, so a consumer that knows them fills them in. This package supplies none of
+  them.
+- **The SDK exposes the session surface only.** The input travels as an IR on stdin, which is
+  what makes the run a session-surface judgment. A caller that has a finished change set pipes
+  a unified diff to `pdks covenant check --diff` from its shell instead.
+- **No telemetry row is written here.** Every row comes from the child.
+- **An `unjudged` verdict is not a pass.** It records that the judge did not answer, and the
+  consumer decides what a project without a judge is allowed to do.
+
+<a id="see-also"></a>
+## See also
+
+- [`pdks covenant check`](../cli/covenant-check.md)
+- [`polydeukes`](polydeukes.md)
+- [`@polydeukes/core`](core.md)
+- [Configuration reference](../configuration/index.md)

package/dist/docs/troubleshooting.ko.md

@@ -0,0 +1,144 @@
+# Polydeukes 문제 해결
+
+[English](./troubleshooting.md) · **한국어**
+
+정책을 바꾸기 전에 어느 단계에서 실패했는지 확인하세요. 세션이 복구 명령까지 차단한다면
+본인의 터미널에서 실행합니다. `pdks docs`는 동봉 문서가 온전하면 프로젝트 설정이나
+판정 관련 패키지가 없어도 사용할 수 있습니다.
+
+<a id="no-config"></a>
+## 설정 파일이 없을 때
+
+프로젝트 루트 바로 아래에 `polydeukes.config.yaml`, `polydeukes.config.yml`,
+`polydeukes.config.json` 중 하나도 없으면 설정이 필요한 명령은 종료 코드 2를 반환합니다.
+Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init`, `pdks-claude-code init`,
+`pdks-grok init`로 만들 수 있습니다. 이후 `pdks explain`을 실행합니다. 설정이 없다고
+기본 정책으로 대신 실행하지는 않습니다.
+
+<a id="multiple-config"></a>
+## 설정 파일이 여러 개일 때
+
+오류 메시지에 중복된 파일명이 나옵니다. 필요한 내용을 합친 뒤 허용되는 파일명 하나만
+남기세요. 로더는 어느 파일을 사용할지 임의로 선택하지 않습니다. 정리한 뒤
+`pdks explain`을 다시 실행합니다.
+
+<a id="invalid-config"></a>
+## 설정 오류
+
+구문이나 스키마 오류가 있으면 종료 코드 2와 함께 파일명을 알립니다. 스키마 오류는 문제가
+있는 필드도 알려 줍니다. 잘못된 YAML, 사용자 정의 태그, 알 수 없는 필드, 비어 있는
+`languages` 객체를 고치세요. YAML 태그는 파서가 실행할 수 없더라도 거부합니다.
+설정은 실행할 코드가 아니라 데이터이기 때문입니다.
+
+`protectedPath:`나 `adaptors:` 같은 오타는 거부합니다. 다만 어댑터 이름에는 확장 가능성을
+남겨 두었습니다. 아무도 구현하지 않은 네임스페이스도 설정으로 읽히지만 읽는 쪽이 없습니다.
+수정한 뒤 `pdks explain`에서 실제 등록 내용을 확인하세요.
+
+<a id="grok-witness"></a>
+## Grok 증인
+
+훅을 아직 읽지 않은 문제와 증인(witness) 밸브를 사용할 수 없는 문제는 구별해야 합니다.
+
+- `pdks-grok init` 실행 뒤 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>
+## 커밋이 차단됐을 때
+
+변경 집합 표면은 사람에게 묻지 않습니다. 기본값에서는 모든 판정에 종료 코드 0을 내고 위반을
+`advised`로 기록합니다. 종료 코드 2는 검사를 `--enforce block`으로 실행했을 때(보호 경로나
+`enforce: block` 항목의 위반) 또는 판정 자체가 불가능할 때만 냅니다. 커밋을 멈출지는 훅
+배선이 정합니다. 종료 코드를 따르는 훅은 커밋을 멈추고, 무시하는 훅은 멈추지 않습니다. Git은
+커밋 실패를 다른 0이 아닌 코드로 알릴 수도 있습니다.
+
+일반 규율 항목은 자신이 `enforce: block`을 적고 검사가 `--enforce block`으로 실행될 때만
+작업을 멈춥니다. 설정에는 기본값 `advise`인 항목을 승격하는 것이 없습니다. 수준 변경은
+정책을 바꾸는 결정이지 필수 복구 절차가 아닙니다. 판정된 위반을 통과시키려면 설정이 아니라
+훅 명령에서 `--enforce block`을 빼세요. 행은 그대로 남습니다.
+
+<a id="skipped-rows-on-the-change-set-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)

package/dist/docs/troubleshooting.md

@@ -2,188 +2,140 @@
 
 **English** · [한국어](./troubleshooting.ko.md)
 
-> Alpha. Nine states cover what ships today — five ways a fail-closed system refuses to
-> proceed, and four things worth knowing when a judgment surprises you. Each entry is
-> symptom → cause → recovery.
-
-This is the guide layer for recovery: the fail-closed states, reading verdicts, and the
-witness valve.
-
-The one principle behind half of this page: **a gate that cannot judge blocks rather than
-guesses.** A missing config, an ambiguous config, an invalid config, an installer that
-cannot prove resolution, and a judge that cannot be loaded all fail closed, because a dead
-gate that waves things through is the cheapest bypass of all. The recovery is never to
-disable the gate — it is to give it back what it needs to judge. And run that recovery
-**from your own terminal**: inside a session the repair commands are judged by the very
-gate they repair, and while no config is loaded there is no witness valve to open.
-
-## Every call is blocked and there is no config
-
-**Symptom.** On the session surface, every editing tool call and shell command exits 2;
-on the commit surface, every `pdks covenant check` run does. The error says no Polydeukes
-config was found and names the three candidate filenames.
-
-**Cause.** The surface is wired but config discovery found nothing at the project root.
-Discovery looks for exactly these, in this order: `polydeukes.config.yaml`,
-`polydeukes.config.yml`, `polydeukes.config.json`. A missing config never silently loads
-defaults — silent defaults would mean silently unprotected.
-
-**Recovery.** Restore the file from git. On the session path,
-`pnpm exec pdks init claude-code` or `pdks init grok` recreates files that
-are absent. An existing grok JSON is not rewritten except when its `command`
-still names the grok delegator and a Claude delegator is on disk — then that
-command is retargeted and the matcher follows the settings entry. On the commit path the
-config is hand-written — the [install guide](./installation.md)'s commit-surface section
-has a starting point.
+Diagnose the failed stage before changing policy. If a session blocks the repair command itself,
+run the repair from your own terminal. `pdks docs` remains usable without project configuration
+or the judging packages, provided its own installed documentation bundle is intact.
 
-## More than one config file
-
-**Symptom.** Every call exits 2 with an error naming two (or three) config files at once.
-
-**Cause.** Two spellings coexist — say a `polydeukes.config.yaml` created next to a
-project's existing `.yml`. Ambiguity never picks a winner.
+<a id="no-config"></a>
+## No config found
 
-**Recovery.** Keep exactly one file and delete the others. If both have content, merge by
-hand first — the loader will not choose for you.
+Commands that need configuration exit 2 when none of `polydeukes.config.yaml`,
+`polydeukes.config.yml`, or `polydeukes.config.json` exists directly at the project root.
+Restore the intended file from Git, or use `pdks init` / `pdks-claude-code init` /
+`pdks-grok init` for a new project. Then run `pdks explain`. No configuration means no silent
+default policy.
 
-## The config is invalid
+<a id="multiple-config"></a>
+## More than one config file
 
-**Symptom.** Every call exits 2 with an error naming the offending file — and, for schema
-violations, the exact key.
+An ambiguity error names the competing files. Merge their intended contents and retain exactly
+one accepted filename. The loader will not choose one on your behalf. Retry `pdks explain`.
 
-**Cause.** One of: a YAML parse error; a custom YAML tag (rejected even though the parser
-cannot execute it — config data stays uncomputable by contract); an unknown key (a typo
-like `protectedPath:` is rejected with the full field path — with one open ground: an
-adapter namespace's *name* is not validated, so `adapters.gti:` for `adapters.git:` loads
-clean and its entries are simply never read; that one spelling you check yourself); or an
-empty `languages` block, the schema's one required entry.
+<a id="invalid-config"></a>
+## Invalid config
 
-**Recovery.** Fix the named key in the named file. The error is specific on purpose — no
-rewrite-and-hope needed.
+Parsing or schema failures exit 2 and name the file; schema errors also identify the offending
+field. Repair invalid YAML, custom tags, unknown fields, or an empty `languages` object.
+Custom YAML tags are rejected even if the parser cannot execute them: configuration is data.
 
-## A Grok session does not pick up a newly installed hook
+Typos such as `protectedPath:` or `adaptors:` are refused. Adapter namespace names are deliberately
+open, however: a namespace nobody implements loads without being read by anything. After repair,
+run `pdks explain` and check the assembled registrations.
 
-**Symptom.** `pdks init grok` reported created files, but this session's tool calls still
-leave no telemetry row.
+<a id="grok-witness"></a>
+## Grok witness
 
-**Cause.** Grok loads hooks at session start. An already-open session keeps that snapshot.
+A hook not yet loaded and an unavailable witness valve are different problems:
 
-**Recovery.** Press `r` in the Hooks tab, or start a new session. The witness valve also
-does not open on Grok — a block is recovered from another terminal or the commit-surface TTY.
+- After `pdks-grok init`, reload the Hooks tab or start a new session. Verify an actual call and
+  its telemetry; a successful installer run does not prove the open host loaded the hook.
+- Grok's ACP history does not supply the Claude-format human message required by the current
+  session witness valve. Reloading does not add that capability. Perform a necessary repair
+  from your own terminal rather than trying to send a Claude witness token through Grok.
 
-## One Grok tool call leaves two telemetry rows
+A commit witness authorizes its staged check only. It cannot release a blocked Grok tool call.
 
-**Symptom.** In a tree wired for both Claude Code and Grok, every `write` or
-`run_terminal_command` in a Grok session appends two rows to `.polydeukes/roi.log`,
-milliseconds apart.
+<a id="config-fault"></a>
+## Config-fault
 
-**Cause.** Grok reads `.claude/settings.json` as well as `.grok/hooks/*.json` and collapses
-the two registrations only when `command` and `matcher` are both identical. A grok JSON
-whose matcher differs from the settings entry spawns the judge a second time.
+The configuration loaded, but an entry could not compile into a judgment. A matching registration
+records `skipped` with `config-fault`; `pdks explain` shows the fault. Check extraction step names,
+arguments, regex syntax, and paired versus single extraction use. Fix the named declaration and
+repeat the same observation. A skipped entry is not a passing one.
 
-**Recovery.** Make the grok JSON's `matcher` the same string as the settings entry that
-registers the same command. Re-running either installer does it: every grok entry that
-names the Claude hook takes the settings entry's matcher.
+<a id="judge-cannot-be-loaded"></a>
+## The judge cannot be loaded
 
-## `pdks init claude-code` refuses to run
+A missing package or judging module fails closed. Reinstall the package or run the complete
+workspace build from your own terminal. The generated hook delegates to the installed package;
+it is not an independent copy of the judge. Verify another real call after repair. A failure
+before telemetry can load may leave no row at all.
 
-**Symptom.** The installer prints an install command and exits 2 without creating anything.
+The session hook prefixes the message with `covenant hook failed closed:` and the commit check
+with `covenant check failed closed:`. The two shapes you will see:
 
-**Cause.** Preflight: before writing any file, the installer proves the `polydeukes`
-package resolves from the target project root. A hook generated without that would block
-every call through its own fail-closed catch — an uneditable tree. The usual trigger is
-running via a one-off `npx` without installing, or running in the wrong directory (it
-installs where it is invoked).
+```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' …
+```
 
-**Recovery.** `pnpm add -D polydeukes` in the project you meant, then re-run from that
-root. Zero files were written, so there is no partial state to clean up.
+The first is the installed package missing; the second is a source checkout whose judge
+build output is missing or partial.
 
-## The judge cannot be loaded
+<a id="reading-verdict"></a>
+## Reading a verdict
 
-**Symptom.** Every call exits 2 with `covenant hook failed closed: Cannot find package
-'polydeukes'` — or an error naming a judge-body file that does not exist.
+| Record | Meaning |
+|---|---|
+| `passed` | The observed input was judged and upheld the covenant. |
+| `blocked` | A violation stopped the operation. |
+| `witnessed` | A blocking result was allowed through its witness valve. |
+| `advised` | A violation was recorded without stopping the operation, on either surface. |
+| `skipped` | No judgment was possible for the matching registration. This is not a pass. |
+| `unattributed` | Baseline comparison found protected changes without an explaining judgment, or could not read a valid baseline. This is an observation, not a verdict. |
 
-**Cause.** The hook is wired but the package it delegates to is gone or incomplete: the
-dependency was removed, the tree is a fresh clone that was never installed, or (in a
-source clone of this repository) the judge's build output is missing. The installer's
-preflight prevents *wiring* a project into this state, but nothing prevents a wired
-project from entering it later.
+Judgments append telemetry at `.polydeukes/roi.log` unless `telemetry.logPath` changes the location.
+Logging is fail-open: a write failure does not alter the verdict. Exit 0 means the operation may
+continue, not that every discipline passed.
 
-**Recovery.** From your own terminal, reinstall the dependency (`pnpm install`, or
-`pnpm add -D polydeukes` if it was removed). In a source clone, run the build. The hook
-file itself needs no repair — it is a delegator, and it recovers the moment the package
-resolves again.
+<a id="opening-a-blocked-call"></a>
+## Opening a blocked call
 
-## Reading a verdict
+In a supported Claude Code session, type the configured witness token alone on the first line
+of a human message, then retry within its configured TTL. The message may also precede an
+intentional protected edit; no previous failed attempt is required. The token is not a secret.
+The valve checks human provenance and applies only to a blocking judgment. A successful retry
+appends a `witnessed` row; it does not rewrite the earlier blocked row.
 
-**Symptom.** Something was blocked (or passed) and you want to know what the record says.
+A witness cannot repair missing modules or other failures that prevent judgment assembly.
 
-**Cause.** Not a failure — this is the measurement working. Every judgment appends exactly
-one record to the telemetry log (`.polydeukes/roi.log` by default, `telemetry.logPath` to
-move it).
+<a id="blocked-commit"></a>
+## A blocked commit
 
-**Recovery.** Read the last lines and the six-word vocabulary:
+The change-set surface does not prompt. By default it exits 0 on every verdict and records the
+break as `advised`; it exits 2 only when the check runs with `--enforce block` (a protected
+path or an entry set to `enforce: block` broke) or when it could not judge at all. Whether the
+commit stops is your hook wiring — a hook that honours the exit code stops it, one that ignores
+it does not. Git may report a different nonzero exit code for the failed commit.
 
-| Word | Means |
-|---|---|
-| `passed` | Judged, upheld the covenant. |
-| `blocked` | Judged, broke it. The call did not run. |
-| `witnessed` | A blocked verdict a human opened in person. Never silent. |
-| `advised` | Commit surface at `advise` level: a break recorded without stopping the commit. |
-| `skipped` | A registration matched but could not judge — **the recorded absence of a judgment, not a pass.** |
-| `unattributed` | A protected entry changed on disk and no judgment explains it — **an observation, not a verdict.** Nothing was blocked; the write already happened. |
+A normal entry blocks only when it declares `enforce: block` and the check runs with
+`--enforce block`; nothing in the config promotes a default-`advise` entry. Changing a level is
+a policy decision, not a required repair. To let a judged break through, drop `--enforce block`
+from the hook command rather than editing the config — the row is still written.
 
-An `unattributed` row names the entry, not the file inside it. Rebuilding a protected `dist`
-without a judged call producing one is expected — it says a write reached that entry outside
-the session's view, which is exactly what the row is for.
+<a id="skipped-rows-on-the-change-set-surface"></a>
+## `skipped` rows on the change-set surface
 
-## Opening a blocked call — the witness
+A transcript-reading declaration with `supply: { session: 'pass' }` records `supply-pass` when the
+change-set surface has no session. Use the session surface for that promise; a skip does not verify
+history. Other unavailable channels can produce `no-observation`. Inspect the registration and
+reason instead of treating every missing source as the same failure.
 
-**Symptom.** A call you and your agent agree should proceed was blocked, and you want it
-through without editing the policy.
+A command-scoped declaration does not match a staged diff's absent command line and records no
+judgment there. Configuration, scope matching, supply, and the final comparison are separate steps.
 
-**Cause.** The valve exists for exactly this, and it sits *after* the verdict — only a
-judgment that actually blocked can be witnessed open.
+<a id="local-state"></a>
+## Moving a project between machines
 
-**Recovery.** Type the token from your config's `witness:` block so it stands **alone on
-the first line** of a conversation message. The window holds for `ttlMinutes`, then
-blocking resumes on its own. Three things that do not work, by design: quoting or
-mentioning the token mid-sentence (invocation is first-line-standalone only); witnessing a
-call that was never blocked (the valve is consulted only after a block); and the agent
-typing the token for itself (only human-authored messages count — the defence is
-provenance, not secrecy). Every allowance lands as one `witnessed` row.
+Telemetry and `.polydeukes/baseline.json` are local state, not a portable history supplied by Git.
+A clone without them does not reconstruct prior judgments. The session hook records an absent
+or invalid baseline and establishes one for subsequent comparisons; this is not proof that old
+changes were judged. Preserve needed logs separately when migrating, and check any custom
+`telemetry.logPath` rather than assuming `.polydeukes/` holds all records.
 
-## A blocked commit
+<a id="next-steps"></a>
+## Next steps
 
-**Symptom.** `git commit` stops at a prompt asking a human to witness a staged protected
-change — or, from an agent, the commit simply fails with exit 2.
-
-**Cause.** The commit surface at the default `block` level judges the staged diff, and its
-valve is a TTY prompt. An agent-spawned commit has no TTY, so for it the valve is not even
-assembled — a terminal-holding human is the pass condition, not a workaround.
-
-**Recovery.** Run the commit from your own terminal and answer the prompt with the full
-token — one answer covers that whole commit. If you want the commit surface to measure
-without stopping, set `adapters.git.enforce: advise`: verdicts are then recorded as
-`advised` and the commit proceeds with one advisory line on stderr. At either level a run
-that *cannot judge* (missing or invalid config, an unresolvable judge) still exits 2 —
-`advise` relaxes the verdict, never the gate's integrity.
-
-## `skipped` rows on the commit surface
-
-**Symptom.** A `precedent` declaration that judges normally in sessions always lands as
-`skipped` on commits.
-
-**Cause.** A declaration that reads the session judges *session history* — was the required
-step actually executed before this change. A commit has no session to read, so the
-declaration's own `supply: { session: 'pass' }` takes over: when its scope matches a staged
-change it records `skipped` with the reason `supply-pass` and the entry's id, and proceeds.
-
-**Recovery.** None needed — this is a declared condition of the surface, not a defect. The
-row is the point: a gate that did nothing says so in the data. `pdks explain` shows the
-same fact before any commit: the entry appears under the commit surface with its
-`transcript` source, which that surface never supplies. Such a declaration is
-really a session-surface tool — on a project that wires only the commit surface, such an
-entry only ever buys telemetry, so declare it where an AI partner's session exists to be
-judged. The row appears only when the entry's scope actually matched, so an unrelated
-commit records nothing.
+- [Connect the surfaces](./how-to/connect-surfaces.md)
+- [Configure the project](./how-to/configure-project.md)
+- [Write disciplines](./how-to/write-disciplines.md)