polydeukes 0.6.0 → 0.7.1

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

@@ -0,0 +1,195 @@
+# `polydeukes`
+
+[English](./polydeukes.md) · **한국어**
+
+일반 사용자는 통합 패키지인 `polydeukes` 하나만 설치하면 됩니다. `pdks` 실행 파일, 판정기,
+두 표면의 조립 루트, 세션 표면 실행기 서브패스, 동봉된 스키마 자산을 모두 이 패키지가
+맡습니다.
+
+<a id="polydeukes-entry-points"></a>
+## 진입점
+
+| 지정자 | 무엇인가 |
+|---|---|
+| `pdks` / `polydeukes` | 실행 파일입니다. `bin`에 이름 둘로 등록된 같은 CLI입니다 |
+| `polydeukes/schema.json` | 동봉된 설정 JSON Schema |
+
+`.` 진입점은 없습니다. `import 'polydeukes'`는 `ERR_PACKAGE_PATH_NOT_EXPORTED`로 실패합니다.
+사용자가 닿는 것은 실행 파일과 스키마 파일입니다. 세션 표면도 셸과 같은 방법으로 이
+패키지에 닿습니다. 즉 `pdks covenant check`를 스폰하므로, 에이전트 어댑터는 이 패키지를
+import하지 않고 peer 의존으로 선언합니다.
+
+<a id="polydeukes-bin"></a>
+## CLI 명령
+
+| 명령 | 목적 |
+|---|---|
+| `pdks covenant check` | 표준 입력의 입력 IR(기본, 세션 표면) 또는 통합 diff(`--diff`, 변경 집합 표면)를 판정 |
+| `pdks init` | 프로젝트 초기 파일 생성. 설정 파일과 텔레메트리 제외 항목 |
+| `pdks explain` | 조립된 등록표를 판정 없이 표시 |
+| `pdks docs [topic]` | 동봉된 주제를 읽음 |
+| `pdks docs search <query>` | 동봉된 문서를 검색 |
+| `pdks docs show <document-id>` | 동봉된 문서 또는 절을 표시 |
+
+세션 표면 설치기는 어댑터에 있습니다. `pdks-claude-code init`과 `pdks-grok init`입니다.
+
+<a id="surface-from-input-mode"></a>
+### 입력 방식이 곧 표면이다
+
+`covenant check`는 입력이 어떻게 도착했는지로 표면을 정하며, 입력 자신의 키로 정하지
+않습니다. 표준 입력의 IR은 호스트가 실행 전에 관측한 호출 하나이므로 그 실행은 **세션
+표면(session surface)**이고, `--diff`는 어떤 생산자가 끝낸 변경 집합이므로 그 실행은
+**변경 집합 표면(change-set surface)**입니다. 표면마다 공용 목록에 자기 목록을 더해
+컴파일합니다.
+
+| 입력 | 표면 | 컴파일하는 목록 |
+|---|---|---|
+| 표준 입력의 입력 IR | `session` | `disciplines` 다음 `sessionDisciplines` |
+| `--diff`와 함께 오는 표준 입력의 통합 diff | `changeSet` | `disciplines` 다음 `changeSetDisciplines` |
+
+IR의 `session` 키는 다른 것을 말합니다. 호스트가 그 호출에 대해 증명한 사실, 곧 증인 밸브가
+읽는 사람의 턴과 대화 기록(transcript) 축, 그리고 셸 쓰기 증거에 필요한 변경 전 상태
+통로입니다. 세션을 싣지 않는 호스트(Grok 어댑터)도 여전히 세션 표면에서 판정되며, 그 호스트에
+없는 것은 표면이 아니라 그 셋이 읽는 증거입니다. `pdks explain`은 표면마다 목록 이름 둘과 그
+개수를 함께 출력합니다.
+
+`pdks docs`는 오프라인입니다. 네트워크가 아니라 설치된 패키지를 읽습니다. 플래그, JSON,
+종료 코드는 [`pdks docs`](../cli/docs.ko.md)에 있습니다.
+
+<a id="polydeukes-export-map"></a>
+## 공개 심볼
+
+<a id="schema-export"></a>
+### `./schema.json`
+
+| 자산 | 메모 |
+|---|---|
+| `polydeukes.schema.json` | 통합 패키지에 동봉한 설정 스키마 사본입니다. |
+
+<a id="covenant-module"></a>
+## 판정기(`covenant` 모듈)
+
+판정기는 통합 패키지의 `src/covenant/` 모듈입니다. 선언된 약속(covenant)을 평가해 판정
+결과를 내는 기능을 모두 여기서 구현하며, 두 조립 루트와 `pdks explain`이 이 모듈을 바로
+가져옵니다. 따로 설치할 것도, 불러올 것도, 충족할 peer 의존도 없습니다. 사용자는 설정의
+`disciplines:` 블록과 `.polydeukes/roi.log`의 기록을 통해 동작을 확인합니다.
+
+<a id="ownership"></a>
+### 모듈이 담당하는 기능
+
+| 단위 | 하는 일 |
+|---|---|
+| `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 | 대화 기록 | 라이브 세션 대화 기록에 대한 쓰기입니다. 전체 경로 **등가**로 판정하고 보호 조상으로는 결코 보지 않습니다 |
+
+**낱말 여섯**이 텔레메트리 계약입니다. 판정 결과 다섯과 관측 하나입니다. `.polydeukes/roi.log`의
+한 행은 이 중 정확히 하나를 담고, CLI와 문서와 테스트가 같은 사건에 같은 낱말을 씁니다.
+행을 읽는 법은 [문제 해결](../../troubleshooting.ko.md#reading-verdict)에 있습니다.
+
+| 판정 결과 | 뜻 |
+|---|---|
+| `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>
+## 실패 경계
+
+- `runCovenantCheck()`는 예외를 던지지 않고 `{ exitCode: 0 \| 2 }`를 반환합니다.
+- 숫자 코드는 `@polydeukes/core`의 `EXIT_UPHOLD`(`0`), `EXIT_BREAK_NON_BLOCKING`(`1`),
+  `EXIT_BREAK_BLOCKING`(`2`)입니다. 우산 실행기는 `0` 또는 `2`만 노출하며 `1`을 반환하지 않습니다.
+- `pdks covenant check`는 사람에게 묻지 않습니다. 표준 입력을 읽고 종료 코드 0 또는 2를 내며, 그 종료 코드의 뜻은 호출한 쪽이 정합니다.
+- `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,204 @@
+# `polydeukes`
+
+**English** · [한국어](./polydeukes.ko.md)
+
+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 is |
+|---|---|
+| `pdks` / `polydeukes` | The executable. One CLI under two names in `bin` |
+| `polydeukes/schema.json` | The bundled config JSON Schema |
+
+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 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 |
+
+Session-surface installers live on the adapters: `pdks-claude-code init` and `pdks-grok init`.
+
+<a id="surface-from-input-mode"></a>
+### The input mode is the surface
+
+`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:
+
+| Input | Surface | Lists compiled |
+|---|---|---|
+| an input IR on stdin | `session` | `disciplines`, then `sessionDisciplines` |
+| a unified diff on stdin under `--diff` | `changeSet` | `disciplines`, then `changeSetDisciplines` |
+
+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.
+
+`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="schema-export"></a>
+### `./schema.json`
+
+| Artifact | Notes |
+|---|---|
+| `polydeukes.schema.json` | The config schema copy that ships with the umbrella package. |
+
+<a id="covenant-module"></a>
+## The judge (`covenant` module)
+
+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`.
+
+<a id="ownership"></a>
+### What the module owns
+
+| 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 |
+
+**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).
+
+| 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
+
+- `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` 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>
+## 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/reference/packages/sdk-ts.ko.md

@@ -0,0 +1,161 @@
+# `@polydeukes/sdk-ts`
+
+[English](sdk-ts.md) · **한국어**
+
+> **TypeScript에서 판정기로 가는 동사 하나**입니다. 약속(covenant) 입력 IR을
+> `pdks covenant check`에 건네고 판정 결과를 값으로 돌려받습니다.
+>
+> 알파입니다. `polydeukes` · `@polydeukes/core`와 함께 설치하며, 둘 다 이 패키지의
+> `peerDependencies`입니다.
+
+<a id="ownership"></a>
+## 담당하는 기능
+
+스폰과, 종료 상태를 값으로 옮기는 일이 전부입니다. 판정받는 프로젝트의 `polydeukes` 설치를
+찾고, 그 실행 파일에 입력을 표준 입력으로 넣어 돌린 뒤, 자식이 답한 것을 돌려줍니다. 판정
+코드는 여기에 없습니다. 분기는 우산 패키지를 찾았는지와 자식이 어떤 상태로 끝났는지뿐입니다.
+
+| 단위 | 하는 일 |
+|---|---|
+| `checkCovenant` | 판정받는 프로젝트에서 `pdks covenant check`를 스폰하고 판정 결과를 돌려줍니다 |
+| 우산 해소 | `repoRoot`의 설치 그래프에서 `polydeukes`를 찾아 `pdks` 실행 파일을 읽습니다 |
+| 판정 결과 변환 | 종료 코드 `0`은 `upheld`, `2`는 `blocked`, 그 밖은 모두 `unjudged`입니다 |
+
+이 패키지는 텔레메트리 행을 쓰지 않습니다. 실행이 남기는 행은 모두 판정이 일어난 자식
+프로세스가 쓰므로, 호출 하나에 행 하나는 그대로입니다.
+
+<a id="install"></a>
+## 설치
+
+```sh
+pnpm add @polydeukes/sdk-ts polydeukes @polydeukes/core
+```
+
+실행 파일도 설치 단계도 없습니다. 우산 패키지가 SDK가 스폰할 판정기를 공급하고, 코어가
+호출자가 채우는 `CovenantInput` 타입을 공급합니다.
+
+<a id="verb"></a>
+## 동사
+
+```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'] },
+  },
+});
+```
+
+IR은 호출자의 것입니다. 이 패키지는 IR을 읽지도 채우지도 않습니다. `session`도 `actor`도
+자기 명부도 더하지 않으며, 위의 `tools` 값도 호출자 자신의 도구 이름입니다. `subagentSpawns`와
+`userMessages`는 필수 배열이므로 둘 다 없는 호출자는 빈 배열을 보냅니다. `world` 키는 판정기가
+거부합니다. 러너가 세계를 디스크의 프로젝트에서 읽으며, 클라이언트가 세계를 고르면 무엇을
+판정할지를 고르는 것이 되기 때문입니다.
+
+<a id="spec"></a>
+## 스펙
+
+```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 };
+```
+
+| 필드 | 무엇인가 |
+|---|---|
+| `repoRoot` | 판정받는 프로젝트입니다. 설정 발견, 세계 축, 자식의 cwd, 우산 패키지를 찾는 설치 그래프가 모두 여기 걸립니다 |
+| `input` | 호출자 자신의 IR이며 자식의 표준 입력으로 원문 그대로 갑니다 |
+| `enforce` | 실행 전체에 대한 관측자의 기본 자세입니다. **적지 않으면 `block`입니다** |
+| `spawn` | 주입하는 스폰 이음매입니다. 없으면 이 프로세스의 node 실행 파일로 자식을 띄웁니다 |
+
+**`enforce`의 기본값은 `block`입니다.** 이것은 표면의 강제 수준이지 항목의 것이 아닙니다.
+보호 경로와 `enforce: block`을 단 항목이 호출을 멈추고, 나머지 위반은 종료 코드 0에
+`advised`로 기록됩니다. 항목 자신의 강제 수준은 다른 표면에서와 같이 느슨한 쪽이 이기도록
+조합됩니다. `@polydeukes/adapter-claude-code`와 `@polydeukes/adapter-grok`도 같은 수준으로
+판정기를 스폰합니다.
+
+기본 스폰은 파일 서술자를 하나도 상속하지 않습니다. 호출자가 자기 서술자를 갖지 않을 수 있고,
+상속한 stdout이 닫혀 있으면 자식이 답하기 전에 EPIPE로 죽기 때문입니다. stderr는 모아서
+돌려주고, 판정기가 stdout에는 판정 결과를 쓰지 않으므로 stdout은 흘려보내고 버립니다.
+
+<a id="verdicts"></a>
+## 판정 결과 셋
+
+```ts
+type CheckCovenantVerdict =
+  | { verdict: 'upheld'; advisories: string }
+  | { verdict: 'blocked'; reason: string }
+  | { verdict: 'unjudged'; reason: string };
+```
+
+| 판정 결과 | 자식의 상태 | 호출자에게 뜻하는 것 |
+|---|---|---|
+| `upheld` | `0` | 호출이 판정을 받았고 아무것도 막지 않았습니다. `advisories`는 자식의 stderr 원문이며 그 실행이 낸 권고 줄을 싣습니다. 진행하면 됩니다 |
+| `blocked` | `2` | 호출이 판정을 받았고 무언가 막았습니다. `reason`은 자식의 stderr 원문입니다. 진행하지 않습니다 |
+| `unjudged` | 그 밖의 상태이거나 우산 패키지가 없음 | 판정이 일어나지 않았습니다. `reason`이 어느 쪽인지 말합니다. 이것을 통과로 읽으면 판정기가 설치되지 않은 프로젝트에서 모든 호출이 지나갑니다 |
+
+**밸브가 없고 그 자리를 사유가 대신합니다.** 무인 실시간 호출자에게는 TTY도 사람의 턴도
+없으므로, 이 패키지는 증인 인자를 받지 않고 세션을 지어내지도 않습니다. 대신
+`blocked.reason`과 `upheld.advisories`가 데이터로 돌아오고, 그 텍스트를 이슈나 로그에 적을지
+모델에게 돌려줄지는 소비자가 정합니다. 설정 저자와 소비자를 위한 기본 자세 규칙은
+[규율 작성하기](../../how-to/write-disciplines.ko.md#posture)에 있습니다.
+
+<a id="failure"></a>
+## 실패 예제
+
+프로젝트에 `polydeukes`가 설치돼 있지 않으면 스폰할 것이 없고, 동사는 `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',
+// }
+```
+
+자식 프로세스는 돌지 않고 텔레메트리 로그에도 아무것도 더해지지 않습니다. 행은 판정이
+일어나는 자리에 쓰이는데, 판정이 일어나지 않았기 때문입니다.
+
+<a id="limits"></a>
+## 선언된 한계
+
+- **IR은 호출자가 만듭니다.** 도구 명부와 변경 전 상태와 봉투는 호스트가 아는 사실이므로,
+  그것을 아는 소비자가 채웁니다. 이 패키지는 그중 무엇도 공급하지 않습니다.
+- **SDK가 여는 것은 세션 표면뿐입니다.** 입력이 표준 입력의 IR로 가고, 그것이 이 실행을 세션
+  표면 판정으로 만듭니다. 끝난 변경 집합을 가진 호출자는 대신 셸에서
+  `pdks covenant check --diff`에 통합 diff를 파이프합니다.
+- **여기서는 텔레메트리 행을 쓰지 않습니다.** 행은 모두 자식이 씁니다.
+- **`unjudged`는 통과가 아닙니다.** 판정기가 답하지 않았다는 사실을 기록하며, 판정기가 없는
+  프로젝트에서 무엇을 허용할지는 소비자가 정합니다.
+
+<a id="see-also"></a>
+## 함께 보기
+
+- [`pdks covenant check`](../cli/covenant-check.ko.md)
+- [`polydeukes`](polydeukes.ko.md)
+- [`@polydeukes/core`](core.ko.md)
+- [설정 참조](../configuration/index.ko.md)