npm - polydeukes - Versions diffs - 0.6.0 → 0.7.1 - Mend

polydeukes 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (117) hide show

package/README.ko.md +30 -70
package/README.md +31 -84
package/dist/baseline.d.ts +37 -1
package/dist/baseline.js +68 -1
package/dist/bin.d.ts +3 -4
package/dist/bin.js +79 -93
package/dist/covenant/bash-line.d.ts +130 -0
package/dist/covenant/bash-line.js +566 -0
package/dist/covenant/declaration-engine.d.ts +108 -0
package/dist/covenant/declaration-engine.js +415 -0
package/dist/covenant/discipline.d.ts +103 -0
package/dist/covenant/discipline.js +667 -0
package/dist/covenant/dispatch.d.ts +153 -0
package/dist/covenant/dispatch.js +237 -0
package/dist/covenant/extract-steps.d.ts +122 -0
package/dist/covenant/extract-steps.js +0 -0
package/dist/covenant/mention.d.ts +117 -0
package/dist/covenant/mention.js +209 -0
package/dist/covenant/module.d.ts +25 -0
package/dist/covenant/module.js +23 -0
package/dist/covenant/mutation-rules.d.ts +40 -0
package/dist/covenant/mutation-rules.js +146 -0
package/dist/covenant/relations.d.ts +46 -0
package/dist/covenant/relations.js +68 -0
package/dist/covenant/run-covenant.d.ts +95 -0
package/dist/covenant/run-covenant.js +164 -0
package/dist/covenant/self-mod.d.ts +55 -0
package/dist/covenant/self-mod.js +84 -0
package/dist/covenant/shell-evidence.d.ts +38 -0
package/dist/covenant/shell-evidence.js +247 -0
package/dist/covenant/shell-mod.d.ts +84 -0
package/dist/covenant/shell-mod.js +213 -0
package/dist/covenant/supply.d.ts +54 -0
package/dist/covenant/supply.js +50 -0
package/dist/covenant/transcript-mod.d.ts +60 -0
package/dist/covenant/transcript-mod.js +254 -0
package/dist/covenant/ttl-witness.d.ts +47 -0
package/dist/covenant/ttl-witness.js +80 -0
package/dist/covenant-check.d.ts +72 -39
package/dist/covenant-check.js +260 -121
package/dist/diff-ir.d.ts +28 -0
package/dist/diff-ir.js +310 -0
package/dist/docs/README.ko.md +60 -0
package/dist/docs/README.md +64 -0
package/dist/docs/catalog.json +480 -0
package/dist/docs/concepts/judgment.ko.md +113 -0
package/dist/docs/concepts/judgment.md +113 -0
package/dist/docs/how-to/configure-project.ko.md +99 -0
package/dist/docs/how-to/configure-project.md +98 -0
package/dist/docs/how-to/connect-surfaces.ko.md +120 -0
package/dist/docs/how-to/connect-surfaces.md +121 -0
package/dist/docs/how-to/write-disciplines.ko.md +179 -0
package/dist/docs/how-to/write-disciplines.md +181 -0
package/dist/docs/index.json +2280 -0
package/dist/docs/reference/cli/covenant-check.ko.md +148 -0
package/dist/docs/reference/cli/covenant-check.md +153 -0
package/dist/docs/reference/cli/docs.ko.md +97 -0
package/dist/docs/reference/cli/docs.md +95 -0
package/dist/docs/reference/cli/explain.ko.md +84 -0
package/dist/docs/reference/cli/explain.md +89 -0
package/dist/docs/reference/cli/init.ko.md +119 -0
package/dist/docs/reference/cli/init.md +119 -0
package/dist/docs/reference/configuration/index.ko.md +553 -0
package/dist/docs/reference/{configuration.md → configuration/index.md} +215 -90
package/dist/docs/reference/packages/adapter-claude-code.ko.md +110 -0
package/dist/docs/reference/{adapter-claude-code.md → packages/adapter-claude-code.md} +47 -19
package/dist/docs/reference/packages/adapter-grok.ko.md +77 -0
package/dist/docs/reference/packages/adapter-grok.md +79 -0
package/dist/docs/reference/packages/core.ko.md +174 -0
package/dist/docs/reference/{core.md → packages/core.md} +74 -12
package/dist/docs/reference/packages/polydeukes.ko.md +195 -0
package/dist/docs/reference/packages/polydeukes.md +204 -0
package/dist/docs/reference/packages/sdk-ts.ko.md +161 -0
package/dist/docs/reference/packages/sdk-ts.md +164 -0
package/dist/docs/troubleshooting.ko.md +144 -0
package/dist/docs/troubleshooting.md +103 -151
package/dist/docs/tutorials/first-judgment.ko.md +82 -0
package/dist/docs/tutorials/first-judgment.md +81 -0
package/dist/docs-catalog.d.ts +25 -0
package/dist/docs-catalog.js +450 -0
package/dist/docs-library.d.ts +23 -0
package/dist/docs-library.js +347 -0
package/dist/docs-markdown.d.ts +32 -0
package/dist/docs-markdown.js +150 -0
package/dist/docs-query.d.ts +11 -40
package/dist/docs-query.js +28 -122
package/dist/docs-types.d.ts +105 -0
package/dist/docs-types.js +2 -0
package/dist/explain.d.ts +1 -1
package/dist/explain.js +37 -22
package/dist/load-config.d.ts +1 -1
package/dist/load-config.js +1 -1
package/dist/pre-state-reader.d.ts +1 -1
package/dist/pre-state-reader.js +1 -1
package/dist/scaffold-project.d.ts +2 -2
package/dist/scaffold-project.js +9 -3
package/dist/schema/polydeukes.schema.json +12 -0
package/dist/worktree-reader.d.ts +19 -0
package/dist/worktree-reader.js +30 -0
package/package.json +3 -17
package/dist/claude-code-hook.d.ts +0 -79
package/dist/claude-code-hook.js +0 -372
package/dist/claude-code.d.ts +0 -6
package/dist/claude-code.js +0 -6
package/dist/covenant-module.d.ts +0 -25
package/dist/covenant-module.js +0 -42
package/dist/docs/configuration.md +0 -103
package/dist/docs/installation.md +0 -241
package/dist/docs/reference/adapter-git.md +0 -100
package/dist/docs/reference/covenant.md +0 -116
package/dist/docs/reference/polydeukes.md +0 -315
package/dist/index.d.ts +0 -22
package/dist/index.js +0 -21
package/dist/init-claude-code.d.ts +0 -52
package/dist/init-claude-code.js +0 -469
package/dist/init-grok.d.ts +0 -51
package/dist/init-grok.js +0 -242

package/dist/docs/reference/cli/covenant-check.ko.md ADDED Viewed

@@ -0,0 +1,148 @@
+# `pdks covenant check`
+[English](./covenant-check.md) · **한국어**
+`pdks covenant check`는 설치된 패키지로 변경 집합 표면의 판정을 실행합니다. 작업 디렉터리에서
+설정을 읽고 **stdin**에서 관측 하나를 받아, 세션 훅에서도 사용하는 판정 본체에 전달합니다.
+저장소를 열지 않고 `git`을 부르지도 않습니다. 관측은 호출자가 만들고, 이 명령은 그것을
+판정해 종료 코드로 답합니다.
+<a id="covenant-check-syntax"></a>
+## 구문
+```sh
+pdks covenant check [--diff] [--enforce advise|block]
+```
+`--diff`가 없으면 stdin은 약속(covenant) 입력 IR입니다. `@polydeukes/core`가 정의하는 JSON
+문서(`toolCalls` · `subagentSpawns` · `userMessages`, 그리고 호스트가 더하는 선택 키 둘,
+도구 명부 `tools`와 살아 있는 에이전트 세션의 증거 `session`)입니다. `--diff`를 주면 stdin은
+unified diff이고, 명령이 먼저 그것을 IR로 번역합니다. `--enforce`는 이 실행의 관측자 자세이며
+기본값은 `advise`입니다. 기본값에서는 모든 위반이 행으로 기록되고 종료 코드 0입니다. `--enforce block`을
+주면 보호 경로 위반과 `enforce: block` 항목의 위반이 종료 코드 2가 됩니다. 플래그는 각각 한
+번씩, 순서는 무관합니다. 그 밖의 인자는 사용법 오류입니다. stdin은 EOF까지 읽습니다.
+<a id="covenant-check-boundaries"></a>
+## 관측 경계
+이 명령은 stdin이 담은 것만 판정합니다. 어떤 diff를 파이프로 넘기느냐가 관측을 정합니다.
+| 파이프 | 관측 집합 |
+|---|---|
+| `git diff --cached \| pdks covenant check --diff` | 스테이징한 변경. pre-commit 형태 |
+| `git diff HEAD \| pdks covenant check --diff` | HEAD 대비 작업 트리 |
+| `git diff <base>..<head> \| pdks covenant check --diff` | 두 ref 사이의 변경 집합(`...`는 merge-base 기준) |
+| `pdks covenant check < input.json` | 호출자가 만든 IR 그대로 |
+diff 형식은 VCS 중립입니다. git · jj · hg · 손으로 쓴 `diff -u`가 모두 같은 형식을 냅니다.
+호스트가 만든 IR은 저장소 디스크에 없는 것을 담습니다. `tools`는 어느 도구 이름이 파일을
+바꾸고 어느 것이 명령줄을 담는지(`mutating` · `shell` · `commandArgs`)를 값으로 적습니다.
+어휘가 아니라 값이며, 이것이 없으면 명령은 diff가 만드는 staged 이름만 라우팅합니다.
+`session`은 타임스탬프가 있는 사람의 메시지(TTL 증인이 읽는 것), 이미 실행된 호출과 그
+결과(선행 조건 선언이 읽는 것), 증거를 읽어 온 파일의 절대 경로(이 실행 동안 동일성으로
+보호), 스폰 사이드카 텍스트를 담습니다. 선언이 지정한 파일은 명령이 작업 트리에서 직접
+읽고, 자체 `world` 키를 담은 IR은 거부합니다. 세션 입력은 이 명령이 관측하지 못하는 변경
+집합의 한 호출이므로 변경 집합 선언은 거기서 `skipped`로 기록됩니다. 판정 전후에는 세션
+표면과 같은 방식으로 보호 항목을 저장된 기준선과 비교합니다.
+<a id="diff-translation"></a>
+## diff가 IR이 되는 방식
+파일 블록 하나가 `toolCall` 하나가 되며 입력 순서를 지킵니다. 도구 이름은 생성·수정이
+`staged-write`, 삭제가 `staged-delete`입니다. `args.file_path`는 저장소 기준 상대 경로이며
+`a/` 또는 `b/` 접두 한 단계를 벗기고 따옴표 경로는 이스케이프를 풉니다.
+| diff 블록 | 증거 |
+|---|---|
+| `--- /dev/null` → `+++ b/P` | `create`, `post` = 모든 `+` 줄 |
+| `--- a/P` → `+++ /dev/null` | `delete`, `pre` = 모든 `-` 줄 |
+| `--- a/P` → `+++ b/P`, hunk 있음 | `modify`, `pre` = `-` 줄, `post` = `+` 줄 |
+| 같은 경로, hunk 없음(모드 변경) | `pre`와 `post`가 빈 `modify` |
+| `rename from O` / `rename to N` | `staged-delete` O, 그다음 hunk 줄을 `modify` 증거로 담은 `staged-write` N |
+| `Binary files … differ` / `GIT binary patch` | 경로만. 증거가 없으므로 경로 판정만 적용 |
+**수정의 `pre`와 `post`는 hunk 줄이지 파일 전체가 아닙니다.** 문맥 줄과
+`` 표시는 버립니다. 이 저장소가 배포하는 규율 가운데 `pre`·`post`를
+읽는 것은 모두 줄 단위로 키를 뽑아 비교하므로 파일 전체로 판정한 것과 같은 판정이 나옵니다.
+파일의 전체 텍스트가 필요한 선언은 그 파일을 `source`로 지정하고, 그것은 아래의 세계 축에서
+읽습니다. 생성과 삭제는 전체 텍스트를 담습니다.
+**세계 축은 작업 트리입니다.** 선언이 `source`로 지정한 파일은 작업 디렉터리의 디스크에서
+읽습니다. index도 ref도 아닙니다. index와 디스크가 다르면(부분 스테이징) 판정되는 텍스트는
+디스크의 것입니다. 변경 집합(`world.changes`)은 증거를 지닌 toolCall들의 경로 목록입니다.
+**주체는 없습니다.** diff는 작성자를 증명하지 못하므로 번역된 IR에는 `actor` 키가 없습니다.
+주체 범위의 규율은 이 표면에서 건너뜁니다.
+<a id="covenant-check-results"></a>
+## 결과와 종료 코드
+| 상황 | 결과 |
+|---|---|
+| 약속(covenant) 위반 없음 | exit `0`. 어느 등록에도 라우팅되지 않은 toolCall은 `covenant-check` 라벨의 `passed` 행 하나를 남깁니다 |
+| 규율 항목 위반(기본 `advise`) | exit `0`, `advised` 행 하나, stderr에 `why`와 권고 요약 한 줄 |
+| 보호 경로 위반 또는 `enforce: block` 항목 위반, 기본 자세 | exit `0`, `advised` 행 하나. 이 표면에는 사람이 답할 밸브가 없고, 스테이징된 관문 파일 변경은 이미 세션 표면에서 판정을 받은 것입니다 |
+| 같은 위반, `--enforce block` | exit `2`, `blocked` 행 하나 |
+| `--diff`에 0바이트 stdin | exit `0`, 행 없음. 스테이징이 없으면 판정할 것도 없습니다 |
+| `--diff` 없이 0바이트 stdin | exit `2`. 빈 페이로드는 IR이 아닙니다 |
+| JSON 파싱 실패 · 객체가 아님 · `toolCalls` 배열 부재 | exit `2`, `covenant-check`의 `blocked` 행 하나 |
+| IR이 자체 `world` 키를 담은 경우 | exit `2`. 세계 축은 이 명령이 채웁니다 |
+| `tools`의 목록이 빠졌거나 문자열 아닌 이름을 담은 경우, `session`에 `userMessages`·`toolCalls` 배열이 없는 경우 | exit `2`, `blocked` `covenant-check` 행 1건. 판정할 수 없는 형상은 기본값이 아니라 차단입니다 |
+| `session`의 토큰 메시지가 설정의 `witness` 안에서 신선한 경우 | 차단 판정이 `witnessed`로 기록되고 exit `0`. 세션 표면이 여는 것과 같은 밸브입니다 |
+| 병합 diff(`diff --cc`) · 짝이 맞지 않는 `---`/`+++` · 미지의 hunk 줄 | exit `2`, `covenant-check`의 `blocked` 행 하나 |
+| 다른 인자 | exit `2`, stderr에 사용법 줄. stdin은 읽지 않습니다 |
+| 설정 부재 · 중복 · 무효 | exit `2` |
+| 판정 본체 로드 실패 | exit `2` |
+자세는 설정이 아니라 명령줄에 있고, 프롬프트는 없습니다. 이 명령은 성공 또는 실패를 답하고,
+커밋을 진행할지는 이 명령을 스폰한 훅이 정합니다. 행은 판정만 기록하고, 커밋이 진행됐는지는
+기록하지 않습니다. 배선이 종료 코드를 무시해 커밋이 진행됐더라도 `blocked` 행은 그대로 남습니다.
+<a id="covenant-check-examples"></a>
+## 예제
+```sh
+git diff --cached | pdks covenant check --diff                    # pre-commit, 기록만
+git diff --cached | pdks covenant check --diff --enforce block    # pre-commit, 위반을 거부
+git diff HEAD | pdks covenant check --diff                        # 작업 뒤
+git diff main...HEAD | pdks covenant check --diff                 # PR 전
+pdks covenant check < input.json                                   # 다른 프로그램이 만든 IR
+```
+<a id="pin-the-producer"></a>
+## 생산자를 고정하기
+관측은 이 패키지 밖의 프로세스가 만들고, git 자체의 설정이 그 텍스트를 바꿀 수 있습니다.
+판정되는 텍스트가 스테이징한 텍스트이도록 훅에는 다음 플래그를 씁니다.
+| 플래그 | 막는 것 |
+|---|---|
+| `--no-color` | `color.ui=always`는 모든 줄을 이스케이프 코드로 감쌉니다. 번역기가 블록을 인식하지 못해 exit 2로 fail-closed됩니다 |
+| `--no-ext-diff` / `--no-textconv` | `diff.external`이나 `.gitattributes`의 textconv 드라이버는 디스크 어디에도 없는 텍스트를 내고, 규율은 그 텍스트를 판정하게 됩니다 |
+| `--src-prefix=a/ --dst-prefix=b/` | `diff.mnemonicPrefix`는 `c/`·`i/`·`w/`를 찍습니다. 번역기는 정확히 `a/`와 `b/`만 벗기므로 다른 접두는 판정 경로에 남습니다 |
+생산자가 도중에 죽으면 stdin은 0바이트가 되고, 그것은 빈 관측이라 exit 0입니다. 셸이
+지원하면 파이프 앞에 `set -o pipefail;`을 두어 git의 실패를 훅의 실패로 만듭니다.
+모든 판정을 기록하고 판정 불가일 때만 커밋을 멈추는 lefthook 명령입니다.
+```yaml
+pre-commit:
+  commands:
+    covenant:
+      run: git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff
+```
+보호 경로 위반에도 커밋을 멈추려면 그 줄에 `--enforce block`을 덧붙입니다.
+다른 프로그램에서 판정을 쓰려면 `pdks covenant check`를 실행하고 그 프로세스의 표준 입력에
+입력 IR이나 diff를 씁니다. 종료 코드가 판정 결과입니다.
+<a id="covenant-check-see-also"></a>
+## 같이 보기
+- [`pdks explain`](./explain.ko.md)
+- [`@polydeukes/core`](../packages/core.ko.md)
+- [판정기(`covenant` 모듈)](../packages/polydeukes.ko.md#covenant-module)
+- [설정 레퍼런스](../configuration/index.ko.md)

package/dist/docs/reference/cli/covenant-check.md ADDED Viewed

@@ -0,0 +1,153 @@
+# `pdks covenant check`
+**English** · [한국어](./covenant-check.ko.md)
+`pdks covenant check` runs the change-set-surface judgment against the installed package. It reads the
+config from the working directory, takes one observation from **stdin**, and dispatches the same
+judge bodies that the session hook uses. It never opens a repository and never calls `git`: the
+caller produces the observation, the command judges it and answers with an exit code.
+<a id="covenant-check-syntax"></a>
+## Syntax
+```sh
+pdks covenant check [--diff] [--enforce advise|block]
+```
+Without `--diff`, stdin is the covenant input IR — the JSON document `@polydeukes/core` defines
+(`toolCalls`, `subagentSpawns`, `userMessages`, and the two optional keys a host adds:
+`tools`, its tool roster, and `session`, the evidence a live agent session carries). With
+`--diff`, stdin is a unified diff and the command translates it into that IR first.
+`--enforce` is the observer's posture for the run and
+defaults to `advise`: every break lands as a row and exit 0. `--enforce block` makes a protected
+path or an entry set to `enforce: block` exit 2. Each flag at most once, in either order; any
+other argument is a usage error. stdin is read to EOF.
+<a id="covenant-check-boundaries"></a>
+## Observation boundaries
+The command judges exactly what stdin carries. Which diff you pipe decides the observation:
+| Pipe | Observed set |
+|---|---|
+| `git diff --cached \| pdks covenant check --diff` | Staged changes — the pre-commit shape |
+| `git diff HEAD \| pdks covenant check --diff` | The working tree against HEAD |
+| `git diff <base>..<head> \| pdks covenant check --diff` | The change set between two refs (`...` for the merge-base reading) |
+| `pdks covenant check < input.json` | Whatever IR the caller built |
+The diff format is VCS-neutral: git, jj, hg, and a hand-written `diff -u` all produce it.
+An IR built by a host carries what the repository's disk cannot show. `tools` names which tool
+names change a file and which carry a command line (`mutating`, `shell`, `commandArgs`) — values,
+never vocabulary — and without it only the staged names a diff produces are routed. `session`
+carries the human messages with their timestamps (what the TTL witness reads), the calls already
+made with their outcomes (what a precedent declaration reads), the absolute path the evidence was
+read from (protected by equality for the run), and the spawn sidecar text. The command reads the
+working tree itself for every file a declaration names; an IR that supplies its own `world` is
+refused. A session input is one call of a change set the command cannot see, so a change-set
+declaration records `skipped` there, and the protected entries are compared against the stored
+baseline around the judgment exactly as the session surface does.
+<a id="diff-translation"></a>
+## How a diff becomes the IR
+One `toolCall` per file block, in input order. The tool name is `staged-write` for a creation or
+modification and `staged-delete` for a deletion; `args.file_path` is the repo-relative path with
+one `a/` or `b/` prefix stripped and quoted paths unescaped.
+| Diff block | Evidence |
+|---|---|
+| `--- /dev/null` → `+++ b/P` | `create`, `post` = every `+` line |
+| `--- a/P` → `+++ /dev/null` | `delete`, `pre` = every `-` line |
+| `--- a/P` → `+++ b/P` with hunks | `modify`, `pre` = the `-` lines, `post` = the `+` lines |
+| Same path, no hunks (a mode change) | `modify` with empty `pre` and `post` |
+| `rename from O` / `rename to N` | `staged-delete` O, then `staged-write` N as `modify` over the hunks |
+| `Binary files … differ` / `GIT binary patch` | The path only — no evidence, so only path judgments apply |
+**A modification's `pre` and `post` are the hunk lines, not the whole file.** Context lines and
+the `` marker are dropped. Every shipped discipline that reads `pre`
+and `post` compares keyed lines, so the verdict is the one the whole file would give; a
+declaration that needs a file's full text names it as a `source`, and that is read from the
+world axis below. Creations and deletions carry the full text.
+**The world axis is the working tree.** A file a declaration names by `source` is read from disk
+under the working directory — not from the index, not from a ref. When the index and the disk
+differ (a partially staged file), the judged text is the disk's. The change set (`world.changes`)
+is the list of paths whose toolCalls carry evidence.
+**No actor.** A diff proves no author, so the translated IR carries no `actor` key; actor-scoped
+disciplines skip on this surface.
+<a id="covenant-check-results"></a>
+## Results and exit codes
+| Situation | Result |
+|---|---|
+| No covenant breaks | exit `0`; a toolCall no registration routed leaves one `passed` row under the `covenant-check` label |
+| A break on a discipline entry (default `advise`) | exit `0`, one `advised` row, the `why` and one advisory summary on stderr |
+| A break on a protected path or an entry set to `enforce: block`, default posture | exit `0`, one `advised` row — this surface has no valve a human could answer, and a staged gate-file change already passed the session surface |
+| The same break under `--enforce block` | exit `2`, one `blocked` row |
+| 0 bytes on stdin with `--diff` | exit `0`, no rows — nothing staged is nothing to judge |
+| 0 bytes on stdin without `--diff` | exit `2` — an empty payload is not an IR |
+| Unparseable JSON, a non-object, or a missing `toolCalls` array | exit `2`, one `blocked` `covenant-check` row |
+| An IR carrying its own `world` key | exit `2` — the world axis is the command's to fill |
+| A `tools` whose lists are missing or hold a non-string name, or a `session` without `userMessages` and `toolCalls` arrays | exit `2`, one `blocked` `covenant-check` row — a shape the command cannot judge is a block, never a default |
+| A `session` whose token message is fresh under the config's `witness` | the blocked verdict lands `witnessed`, exit `0` — the same valve the session surface opens |
+| A combined diff (`diff --cc`), an unmatched `---`/`+++`, or an unknown hunk line | exit `2`, one `blocked` `covenant-check` row |
+| Any other argument | exit `2` with the usage line on stderr, stdin unread |
+| Missing, ambiguous, or invalid config | exit `2` |
+| Judge body cannot load | exit `2` |
+The posture lives on the command line, not in the config, and there is no prompt. The command
+answers success or failure; whether a commit proceeds is decided by the hook that spawned it. A
+row records the verdict, not the commit's fate — a `blocked` row can sit beside a commit that
+landed because the wiring ignored the exit code.
+<a id="covenant-check-examples"></a>
+## Examples
+```sh
+git diff --cached | pdks covenant check --diff                    # pre-commit, record only
+git diff --cached | pdks covenant check --diff --enforce block    # pre-commit, refuse a break
+git diff HEAD | pdks covenant check --diff                        # after a task
+git diff main...HEAD | pdks covenant check --diff                 # before a PR
+pdks covenant check < input.json                                   # an IR another program built
+```
+<a id="pin-the-producer"></a>
+## Pin the producer
+The observation is produced by a process outside this package, and git's own configuration
+can change its text. Wire a hook with these flags so the judged text is the staged text:
+| Flag | What it prevents |
+|---|---|
+| `--no-color` | `color.ui=always` wraps every line in escape codes; the translator recognizes no block and the run fails closed (exit 2) |
+| `--no-ext-diff` / `--no-textconv` | `diff.external` or a `.gitattributes` textconv driver substitutes text that exists nowhere on disk, and the disciplines judge that text |
+| `--src-prefix=a/ --dst-prefix=b/` | `diff.mnemonicPrefix` prints `c/`, `i/`, `w/`; the translator strips exactly `a/` and `b/`, so any other prefix survives into the judged path |
+A producer that dies mid-stream leaves 0 bytes on stdin, which is the empty observation and
+exit 0. Where the shell supports it, `set -o pipefail;` in front of the pipeline makes git's
+failure the hook's failure.
+A lefthook command that records every verdict and stops the commit only on a fail-closed run:
+```yaml
+pre-commit:
+  commands:
+    covenant:
+      run: git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff
+```
+Append `--enforce block` to that line to stop the commit on a protected-path break too.
+Another program embeds the judgment by spawning `pdks covenant check` and writing its input IR
+or diff to that process's stdin; the exit code is the verdict.
+<a id="covenant-check-see-also"></a>
+## See also
+- [`pdks explain`](./explain.md)
+- [`@polydeukes/core`](../packages/core.md)
+- [The judge (`covenant` module)](../packages/polydeukes.md#covenant-module)
+- [Configuration reference](../configuration/index.md)

package/dist/docs/reference/cli/docs.ko.md ADDED Viewed

@@ -0,0 +1,97 @@
+# `pdks docs`
+[English](./docs.md) · **한국어**
+설치된 패키지에 동봉된 문서를 읽습니다. 로컬 파일만 사용하며 프로젝트 설정을 읽거나,
+판정기를 호출하거나, 네트워크 서비스에 질의하지 않습니다.
+<a id="syntax"></a>
+## 구문
+```sh
+pdks docs
+pdks docs <topic> [--lang en|ko]
+pdks docs search <query> [--lang en|ko] [--limit N] [--json]
+pdks docs show <document-id> [--lang en|ko] [--section <section-id>] [--json]
+```
+`pdks docs --help`, `pdks docs search --help`, `pdks docs show --help`로 구문을 확인합니다.
+기본 언어는 영어입니다. 기존 주제인 `install`, `config`, `discipline`, `covenant`,
+`witness`도 유지합니다. 주제별 조회와 검색은 같은 문서 목록을 사용합니다.
+<a id="search"></a>
+## 검색
+```sh
+pdks docs search 'locale key pairing'
+pdks docs search '번역 키 짝 맞춤' --lang ko --limit 3
+pdks docs search --diff --json
+```
+검색어는 인수 하나입니다. 여러 단어로 검색할 때는 따옴표로 묶습니다. `--diff` 같은
+식별자도 첫 번째 검색 인수로 사용할 수 있습니다. 그 뒤에 오는 알 수 없는 플래그는
+오류입니다. 결과 개수는 1부터 50까지의 정수이며 기본값은 5입니다. 선택한 언어의 절을
+대상으로 제목, 문서 메타데이터, Markdown 본문을 검색합니다. 공백으로 나눈 검색어가
+모두 일치해야 합니다. 같은 입력에는 같은 결과를 내는 결정론적 텍스트 검색이며,
+의미 해석이나 번역은 하지 않습니다.
+각 결과에는 문서와 절 ID, 제목, 원문 일부, 상대 소스 경로, 점수, 완전한 `pdks docs show`
+명령이 있습니다. 점수가 높은 결과부터 나열하고, 동점이면 문서 ID와 절 ID의 ASCII 순서를
+따릅니다. 점수는 순위를 정하는 값이지 답변의 신뢰도가 아닙니다.
+<a id="show"></a>
+## 문서나 절 조회
+```sh
+pdks docs show first-judgment
+pdks docs show write-disciplines --lang ko --section locale-key-pairing
+```
+`show`는 생성한 답변이 아니라 Markdown 원문을 반환합니다. 절은 명시한 앵커에서 시작해
+다음 같은 수준 또는 상위 수준의 제목과 그 앵커 직전에 끝납니다. 하위 절은 포함합니다.
+코드 블록 안의 제목은 경계가 아니라 본문입니다. 제목이 달라도 영어와 한국어의 ID는
+같습니다.
+<a id="json"></a>
+## JSON 출력
+검색은 다음 구조의 객체를 반환합니다.
+```text
+{ schemaVersion, packageVersion, language, query, count, results }
+```
+`schemaVersion`은 `1`이고 `packageVersion`은 설치된 패키지의 버전입니다. `count`는
+개수 제한을 적용한 뒤 반환하는 결과 수입니다. 각 결과에는 `documentId`, `sectionId`,
+`title`, `excerpt`, `source`, `command`, 숫자형 `score`가 있습니다. `source`는 문서
+디렉터리 기준 상대 경로와 절 앵커이며, 빌드 머신의 절대 경로가 아닙니다.
+조회는 다음 구조를 반환합니다.
+```text
+{ schemaVersion, packageVersion, language, documentId, sectionId, source, markdown }
+```
+전체 문서를 조회하면 `sectionId`는 `null`입니다. `markdown`은 바꾸지 않은 본문입니다.
+JSON 출력은 완전한 객체 하나와 뒤따르는 줄바꿈으로 이루어집니다. 오류가 발생하면
+불완전한 JSON 답변을 출력하지 않습니다.
+<a id="failures"></a>
+## 종료 코드와 동봉 범위
+| 조건 | 종료 코드 | 출력 |
+|---|---|---|
+| 정상 조회 | `0` | stdout에 답변 |
+| 검색 결과 없음 | `0` | 빈 목록 표시. JSON은 `count: 0`, `results: []` |
+| 잘못된 인수 또는 알 수 없는 ID | `2` | stderr에 진단, stdout은 비어 있음 |
+| 동봉 파일이 없거나 서로 맞지 않음 | `2` | stderr에 진단, stdout은 비어 있음 |
+중복 플래그, 누락된 값, 불필요한 위치 인수, 지원하지 않는 언어, 빈 검색어, 경로 형태의
+ID는 오류입니다. `show`는 등록한 ID를 읽으며 임의의 파일 경로를 읽지 않습니다.
+무결성 해시로 Markdown 변경을 탐지하고 메타데이터가 동봉 내용과 맞는지 확인합니다.
+동봉 문서가 불완전하거나 손상됐다면 패키지를 다시 설치하세요. 기여자는 전체 소스를
+갖춘 체크아웃에서 다시 빌드할 수도 있습니다.
+과거 게시물, 백서, 기여 안내, 이전 주소의 이동 안내는 동봉하거나 검색하지 않습니다.
+설치된 문서는 온라인 최신 버전이 아니라 해당 패키지 버전을 설명합니다. 전체 원본 문서
+목록은 [문서 홈](../../README.ko.md)에 있습니다.

package/dist/docs/reference/cli/docs.md ADDED Viewed

@@ -0,0 +1,95 @@
+# `pdks docs`
+**English** · [한국어](./docs.ko.md)
+Read the documentation bundled with the installed package. This command reads local files only;
+it does not load the project's configuration, invoke the judge, or query a network service.
+<a id="syntax"></a>
+## Syntax
+```sh
+pdks docs
+pdks docs <topic> [--lang en|ko]
+pdks docs search <query> [--lang en|ko] [--limit N] [--json]
+pdks docs show <document-id> [--lang en|ko] [--section <section-id>] [--json]
+```
+Use `pdks docs --help`, `pdks docs search --help`, or `pdks docs show --help` for syntax.
+The default language is English. The five legacy topics remain `install`, `config`, `discipline`,
+`covenant`, and `witness`; each is mapped by the same catalog that drives search and retrieval.
+<a id="search"></a>
+## Search
+```sh
+pdks docs search 'locale key pairing'
+pdks docs search '번역 키 짝 맞춤' --lang ko --limit 3
+pdks docs search --diff --json
+```
+The query is one argument. Quote multiword queries. A literal identifier such as `--diff`
+is accepted as the first search argument; subsequent unknown flags are errors. Limits are
+integers from 1 to 50, defaulting to 5. Search selects sections in the requested language and
+uses their titles, document metadata, and Markdown text. Every whitespace-separated query term
+must match; this is a deterministic text search, not semantic interpretation or translation.
+Each result includes the document and section IDs, a title, a raw-text excerpt, its relative
+source path, a score, and a complete `pdks docs show` command. Higher scores come first; ties
+use ASCII document ID and section ID order. Scores are ranking values, not confidence measures.
+<a id="show"></a>
+## Show a document or section
+```sh
+pdks docs show first-judgment
+pdks docs show write-disciplines --lang ko --section locale-key-pairing
+```
+`show` returns the original Markdown, not a generated answer. A section starts at its explicit
+anchor and ends before the next same-level or higher-level heading and its anchor. Child
+sections are included. Headings inside fenced code are content, not boundaries. IDs are stable
+across English and Korean even when their titles differ.
+<a id="json"></a>
+## JSON output
+Search returns this object shape:
+```text
+{ schemaVersion, packageVersion, language, query, count, results }
+```
+`schemaVersion` is `1`; `packageVersion` is the installed package's version. `count` is the number
+of returned results after applying the limit. Each result has `documentId`, `sectionId`, `title`,
+`excerpt`, `source`, `command`, and numeric `score`. `source` is relative to the docs directory
+and includes the section anchor; it is not an absolute path on the build machine.
+Show returns:
+```text
+{ schemaVersion, packageVersion, language, documentId, sectionId, source, markdown }
+```
+`sectionId` is `null` for a full document. `markdown` contains its unchanged body. JSON output is
+one complete object followed by a newline; errors never produce a partial JSON answer.
+<a id="failures"></a>
+## Exit codes and bundle boundaries
+| Condition | Exit | Output |
+|---|---|---|
+| A successful query | `0` | Answer on stdout |
+| No search match | `0` | Explicit empty list; JSON has `count: 0`, `results: []` |
+| Invalid arguments or an unknown ID | `2` | Diagnostic on stderr, empty stdout |
+| Missing or inconsistent bundle files | `2` | Diagnostic on stderr, empty stdout |
+Duplicate flags, missing values, positional extras, unsupported languages, empty queries, and
+path-shaped IDs are errors. `show` reads registered IDs, not arbitrary filesystem paths.
+Integrity hashes detect changed Markdown, and metadata is checked against the bundle contents.
+Reinstall the package if its bundle is incomplete or damaged. Rebuilding from the complete source
+checkout is another option for contributors.
+Historical posts, the whitepaper, contribution instructions, and compatibility notices are not
+bundled or searched. The installed docs describe that package version, not an online latest
+version. See [the documentation home](../../README.md) for the full source collection.

package/dist/docs/reference/cli/explain.ko.md ADDED Viewed

@@ -0,0 +1,84 @@
+# `pdks explain`
+[English](./explain.md) · **한국어**
+`pdks explain`은 등록된 항목을 판정 없이 보여 줍니다. 실제 세션·커밋 실행에 쓰는 조립 함수를 호출하므로, 별도로 추정한 결과가 아니라 실제 등록 내용을 확인할 수
+있습니다.
+<a id="explain-syntax"></a>
+## 구문
+```sh
+pdks explain
+```
+추가 인자는 허용하지 않습니다. 작업 디렉터리의 설정을 읽고, 두 표면을 조립한 뒤 결과를 출력합니다.
+<a id="explain-what-it-shows"></a>
+## 무엇을 보여 주는가
+출력은 표면별로 나뉩니다. 각 표면의 등록 항목과 집계를 보여 주며, 등록 항목은 한 줄씩 표시합니다.
+행 종류는 다음과 같습니다.
+- `meta` — 판정 사슬 자체를 지키는 등록
+- `declare` — 컴파일된 규율 항목 하나
+- `skip` — 판정할 수 없는 사유를 표시하는 등록
+- `draft` — 아직 판정 대상으로 전환하지 않은 `draft: true` 항목
+이 명령은 판정기에 입력을 전달하지 않으며 텔레메트리나 대화 기록 파일도 읽고 쓰지 않습니다. 세션 표면에는 파일을 읽지 않는 대화 기록 대체물을 넘겨
+`transcript-mod` 등록도 실제 훅을 조립할 때처럼 표시합니다.
+<a id="explain-failure-conditions"></a>
+## 실패 조건
+| 상황 | 결과 |
+|---|---|
+| 설정이 유효하고 두 표면이 조립됨 | 종료 `0` |
+| 추가 인자 | 종료 `2`, stderr에 사용법 출력 |
+| 설정이 없거나 여러 개이거나 유효하지 않음 | 종료 `2` |
+| 그 밖의 조립 실패 | 종료 `2` |
+실패 시 stdout은 0바이트로 남습니다. 중간 테이블을 출력하지 않습니다.
+<a id="explain-example"></a>
+## 예제
+```sh
+pdks explain
+```
+출력은 설정 파일 경로로 시작하고, 그다음 세션 표면 블록 하나와 변경 집합 표면 블록 하나가 나옵니다.
+추가 규율이 없는 시작 설정은 이런 모양입니다.
+```text
+pdks explain — polydeukes.config.yaml
+input: call IR (one call, stdin) · disciplines 0 · sessionDisciplines 0 · disciplines: advise unless enforce: block · meta: block
+  registrations 3 · declare 0 · skip 0 · meta 3 · draft 0
+  meta     self-mod        paths N (common; includes the config file itself)
+  meta     shell-mod       paths N (common)
+  meta     transcript-mod  content predicate · conditional: session.evidencePath
+input: --diff (change set, stdin) · disciplines 0 · changeSetDisciplines 0 · disciplines: advise unless enforce: block
+  registrations 2 · declare 0 · skip 0 · meta 2 · draft 0
+  meta     self-mod   paths N (common; includes the config file itself)
+  meta     shell-mod  paths N (common)
+```
+**표면 머리줄은 그 표면이 컴파일하는 목록의 이름과 각 목록의 항목 수를 적습니다.** 세션
+머리줄은 `disciplines <n> · sessionDisciplines <n>`을, 변경 집합 머리줄은
+`disciplines <n> · changeSetDisciplines <n>`을 출력하며, 두 수 모두 조립 전에 설정에 적힌
+그대로 셉니다. 판정을 돌리지 않고 모든 항목의 배치를 확인하는 방법이 이 머리줄 둘을 읽는
+것입니다. 목록을 옮긴 항목은 두 머리줄에서 각각 수 하나를 움직입니다.
+`N`은 조립된 경로 개수입니다. `declare` 행의 라벨은 항목 `id`이고 설명은 카탈로그 좌표입니다.
+`skip` 행은 건너뛴 이유를 적습니다. `draft` 행은 `unpromoted — no judgment`입니다.
+<a id="explain-see-also"></a>
+## 함께 보기
+- [`pdks covenant check`](./covenant-check.ko.md)
+- [`pdks init`](./init.ko.md)
+- [판정기(`covenant` 모듈)](../packages/polydeukes.ko.md#covenant-module)
+- [설정 참조](../configuration/index.ko.md)

package/dist/docs/reference/cli/explain.md ADDED Viewed

@@ -0,0 +1,89 @@
+# `pdks explain`
+**English** · [한국어](./explain.ko.md)
+`pdks explain` renders the assembled registration table without judging anything. It uses the same
+assembly functions that the two runners use, so the output is a view of the real dispatch table, not
+a second opinion.
+<a id="explain-syntax"></a>
+## Syntax
+```sh
+pdks explain
+```
+Any extra argument is invalid. The command reads the config at the working directory, assembles
+both surfaces, and prints the result.
+<a id="explain-what-it-shows"></a>
+## What it shows
+The output is a surface-by-surface summary. Each surface lists one line per registration, then a
+tally line.
+The row kinds are:
+- `meta` — one of the registrations that protect the judging chain itself
+- `declare` — one compiled discipline entry
+- `skip` — a registration that could not be judged and records a skip reason
+- `draft` — an unpromoted entry with `draft: true`
+The command does not dispatch, does not write telemetry, and does not read a transcript file. The
+session surface is rendered with a no-op transcript so the `transcript-mod` row appears exactly as
+it would under a normal hook payload.
+<a id="explain-failure-conditions"></a>
+## Failure conditions
+| Situation | Result |
+|---|---|
+| Config loads and both surfaces assemble | exit `0` |
+| Any extra argument | exit `2`, usage line on stderr |
+| Missing, ambiguous, or invalid config | exit `2` |
+| Any assembly failure | exit `2` |
+The command leaves stdout at zero bytes on failure. It never prints a partial table.
+<a id="explain-example"></a>
+## Example
+```sh
+pdks explain
+```
+The output starts with the config file path, then one block for the session surface and one for the
+change-set surface. A starter config with no extra disciplines looks like this:
+```text
+pdks explain — polydeukes.config.yaml
+input: call IR (one call, stdin) · disciplines 0 · sessionDisciplines 0 · disciplines: advise unless enforce: block · meta: block
+  registrations 3 · declare 0 · skip 0 · meta 3 · draft 0
+  meta     self-mod        paths N (common; includes the config file itself)
+  meta     shell-mod       paths N (common)
+  meta     transcript-mod  content predicate · conditional: session.evidencePath
+input: --diff (change set, stdin) · disciplines 0 · changeSetDisciplines 0 · disciplines: advise unless enforce: block
+  registrations 2 · declare 0 · skip 0 · meta 2 · draft 0
+  meta     self-mod   paths N (common; includes the config file itself)
+  meta     shell-mod  paths N (common)
+```
+**The surface header names the lists that surface compiles and how many entries each holds.**
+The session header prints `disciplines <n> · sessionDisciplines <n>` and the change-set header
+prints `disciplines <n> · changeSetDisciplines <n>`, both counted from the config as written,
+before assembly. Reading the two headers is how the placement of every entry is checked without
+running a judgment: an entry that moved between lists moves one count in each header.
+`N` is the assembled path count. A `declare` row uses the entry `id` as its label and a
+catalogue coordinate as its description. A `skip` row names a skip reason. A `draft` row is
+`unpromoted — no judgment`.
+<a id="explain-see-also"></a>
+## See also
+- [`pdks covenant check`](./covenant-check.md)
+- [`pdks init`](./init.md)
+- [The judge (`covenant` module)](../packages/polydeukes.md#covenant-module)
+- [`Configuration reference`](../configuration/index.md)