polydeukes 0.6.0 → 0.6.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 (55) hide show
  1. package/README.ko.md +54 -80
  2. package/README.md +55 -94
  3. package/dist/bin.js +8 -5
  4. package/dist/docs/README.ko.md +60 -0
  5. package/dist/docs/README.md +64 -0
  6. package/dist/docs/catalog.json +464 -0
  7. package/dist/docs/concepts/judgment.ko.md +113 -0
  8. package/dist/docs/concepts/judgment.md +113 -0
  9. package/dist/docs/how-to/configure-project.ko.md +99 -0
  10. package/dist/docs/how-to/configure-project.md +95 -0
  11. package/dist/docs/how-to/connect-surfaces.ko.md +115 -0
  12. package/dist/docs/how-to/connect-surfaces.md +118 -0
  13. package/dist/docs/how-to/write-disciplines.ko.md +124 -0
  14. package/dist/docs/how-to/write-disciplines.md +125 -0
  15. package/dist/docs/index.json +2046 -0
  16. package/dist/docs/reference/cli/covenant-check.ko.md +101 -0
  17. package/dist/docs/reference/cli/covenant-check.md +98 -0
  18. package/dist/docs/reference/cli/docs.ko.md +97 -0
  19. package/dist/docs/reference/cli/docs.md +95 -0
  20. package/dist/docs/reference/cli/explain.ko.md +79 -0
  21. package/dist/docs/reference/cli/explain.md +84 -0
  22. package/dist/docs/reference/cli/init.ko.md +119 -0
  23. package/dist/docs/reference/cli/init.md +131 -0
  24. package/dist/docs/reference/configuration/index.ko.md +448 -0
  25. package/dist/docs/reference/{configuration.md → configuration/index.md} +48 -30
  26. package/dist/docs/reference/packages/adapter-claude-code.ko.md +83 -0
  27. package/dist/docs/reference/{adapter-claude-code.md → packages/adapter-claude-code.md} +10 -6
  28. package/dist/docs/reference/packages/adapter-git.ko.md +101 -0
  29. package/dist/docs/reference/{adapter-git.md → packages/adapter-git.md} +20 -12
  30. package/dist/docs/reference/packages/core.ko.md +128 -0
  31. package/dist/docs/reference/{core.md → packages/core.md} +21 -8
  32. package/dist/docs/reference/packages/covenant.ko.md +115 -0
  33. package/dist/docs/reference/{covenant.md → packages/covenant.md} +18 -11
  34. package/dist/docs/reference/packages/polydeukes.ko.md +134 -0
  35. package/dist/docs/reference/packages/polydeukes.md +139 -0
  36. package/dist/docs/troubleshooting.ko.md +142 -0
  37. package/dist/docs/troubleshooting.md +98 -150
  38. package/dist/docs/tutorials/first-judgment.ko.md +82 -0
  39. package/dist/docs/tutorials/first-judgment.md +81 -0
  40. package/dist/docs-catalog.d.ts +25 -0
  41. package/dist/docs-catalog.js +450 -0
  42. package/dist/docs-library.d.ts +23 -0
  43. package/dist/docs-library.js +347 -0
  44. package/dist/docs-markdown.d.ts +32 -0
  45. package/dist/docs-markdown.js +150 -0
  46. package/dist/docs-query.d.ts +11 -40
  47. package/dist/docs-query.js +28 -122
  48. package/dist/docs-types.d.ts +105 -0
  49. package/dist/docs-types.js +2 -0
  50. package/dist/init-claude-code.d.ts +1 -1
  51. package/dist/init-claude-code.js +159 -42
  52. package/package.json +5 -5
  53. package/dist/docs/configuration.md +0 -103
  54. package/dist/docs/installation.md +0 -241
  55. package/dist/docs/reference/polydeukes.md +0 -315
package/dist/docs/reference/cli/covenant-check.ko.md ADDED
@@ -0,0 +1,101 @@
1
+ # `pdks covenant check`
2
+
3
+ [English](./covenant-check.md) · **한국어**
4
+
5
+ `pdks covenant check`는 설치된 패키지로 커밋 표면의 판정을 실행합니다. 작업 디렉터리에서
6
+ 설정을 읽고 저장소의 변경을 관측해 약속(covenant) 입력 IR로 변환합니다.
7
+ 이 입력을 세션 훅에서도 사용하는 판정 본체에 전달합니다.
8
+
9
+ <a id="covenant-check-syntax"></a>
10
+ ## 구문
11
+
12
+ ```sh
13
+ pdks covenant check
14
+ pdks covenant check --worktree
15
+ pdks covenant check --range <base>..<head>
16
+ pdks covenant check --range <base>...<head>
17
+ ```
18
+
19
+ 기본 형식은 스테이징한 변경을, `--worktree`는 작업 트리의 변경을 판정합니다.
20
+ `--range`는 두 참조 사이의 변경을 비교하며, `...` 형식은 두 참조의 공통 조상인
21
+ 병합 기준점(merge-base)부터 비교합니다.
22
+
23
+ <a id="covenant-check-boundaries"></a>
24
+ ## 관측 경계
25
+
26
+ 이 명령은 무엇을 관측하는지 분명히 나눕니다.
27
+
28
+ | 형식 | 관측 집합 | `pre` → `post` | 메모 |
29
+ |---|---|---|---|
30
+ | `pdks covenant check` | staged 변경만 | HEAD blob → staged blob | pre-commit 관문입니다. |
31
+ | `pdks covenant check --worktree` | 작업 트리 변경 | HEAD blob → 디스크의 바이트 | 무시되지 않은 미추적 파일을 포함합니다. |
32
+ | `pdks covenant check --range <base>..<head>` | 두 ref 사이의 변경 집합 | base blob → head blob | ref를 해소할 수 없으면 실패합니다. |
33
+ | `pdks covenant check --range <base>...<head>` | 두 ref의 merge-base 읽기 | merge-base blob → head blob | ref의 공통 조상을 씁니다. |
34
+
35
+ `--worktree`에는 무시 대상이 아닌 미추적 파일도 포함됩니다. 추적하지 않는 파일이
36
+ 무시 대상이면 관측하지 않습니다. 이미 추적 중인 파일은 나중에 `.gitignore` 패턴에
37
+ 해당하더라도 계속 관측합니다.
38
+ `--worktree`와 `--range`는 진단용이므로 증인 토큰을
39
+ 묻지 않습니다.
40
+
41
+ <a id="worktree"></a>
42
+ ## `--worktree`로 작업 트리 검사
43
+
44
+ 유효한 Polydeukes 설정이 있는 git 저장소에서 `pdks covenant check --worktree`를 실행합니다.
45
+ HEAD와 현재 디스크의 바이트를 비교하며 스테이징한 내용과 비교하지 않습니다. 추적하지
46
+ 않더라도 무시 대상이 아닌 파일은 추가로 포함하고, 디스크에서 사라진 추적 파일은 삭제로
47
+ 포함합니다. 첫 커밋 전에는 존재하는 추적 파일과 무시 대상이 아닌 미추적 파일에 `pre` 값이
48
+ 없습니다.
49
+
50
+ 커밋을 만들거나 증인 토큰을 묻지는 않습니다. 설정된 강제 수준은 그대로 적용하므로
51
+ exit 0에 권고나 미판정이 포함될 수 있고, 증언되지 않은 차단이나 조립 실패는 exit 2입니다.
52
+ 관측한 변경이 없다는 결과는 다른 파일이나 세션의 대화 기록까지 판정했다는 증거가 아닙니다.
53
+ 판정의 텔레메트리를 기록하므로 `pdks docs`처럼 읽기만 하는 조회 명령은 아닙니다.
54
+
55
+ <a id="covenant-check-results"></a>
56
+ ## 결과와 종료 코드
57
+
58
+ | 상황 | 결과 |
59
+ |---|---|
60
+ | covenant를 깨지 않음 | 종료 `0` |
61
+ | `enforce: advise` 아래의 위반 | 종료 `0`, stderr와 텔레메트리에 `advised` 한 줄 |
62
+ | 증인 블록이 설정된 상태에서 `enforce: block`인 staged 위반 | `/dev/tty`로 한 번 묻습니다. 토큰이 맞으면 차단을 열고, 답이 없거나 틀리면 종료 `2` |
63
+ | 증인 블록이 없는 상태에서 `enforce: block`인 staged 위반 | 묻지 않고 종료 `2` |
64
+ | `enforce: block`인 위반이 `--worktree`나 `--range`에서 발생 | 묻지 않고 종료 `2` |
65
+ | 관측 집합이 비어 있음 | 종료 `0` |
66
+ | 플래그 구문이 잘못됨 | stderr에 usage 줄, 종료 `2` |
67
+ | 설정이 없거나 둘 이상이거나 무효 | 종료 `2` |
68
+ | range를 해소할 수 없거나 merge-base가 없음 | 종료 `2` |
69
+ | 판정 본체를 적재할 수 없음 | 종료 `2` |
70
+
71
+ 항목의 기본값은 `advise`이며 `adapters.git.enforce: block`만으로 승격되지는 않습니다.
72
+ 표면이 `block`일 때 보호 경로 위반과 명시적으로 `enforce: block`인 항목이 차단될 수
73
+ 있습니다. 증인 프롬프트에는 토큰 설정과 접근 가능한 터미널도 필요합니다.
74
+
75
+ `exit 0`은 정상 판정, 권고, 미판정 또는 관측한 변경이 없는 경우일 수 있습니다.
76
+ `exit 2`는 판정 불가로 작업을 차단했거나, 위반에 따른 차단이 증언으로 허용되지 않았다는 뜻입니다.
77
+
78
+ <a id="covenant-check-examples"></a>
79
+ ## 예제
80
+
81
+ ```sh
82
+ pdks covenant check
83
+ pdks covenant check --worktree
84
+ pdks covenant check --range main..HEAD
85
+ pdks covenant check --range main...feature
86
+ ```
87
+
88
+ ```ts
89
+ import { runCovenantCheck } from 'polydeukes';
90
+
91
+ const result = await runCovenantCheck({ repoRoot: process.cwd() });
92
+ // result는 { exitCode: 0 | 2 }
93
+ ```
94
+
95
+ <a id="covenant-check-see-also"></a>
96
+ ## 같이 보기
97
+
98
+ - [`pdks explain`](./explain.ko.md)
99
+ - [`@polydeukes/adapter-git`](../packages/adapter-git.ko.md)
100
+ - [`@polydeukes/covenant`](../packages/covenant.ko.md)
101
+ - [`설정 레퍼런스`](../configuration/index.ko.md#adapters-git)
package/dist/docs/reference/cli/covenant-check.md ADDED
@@ -0,0 +1,98 @@
1
+ # `pdks covenant check`
2
+
3
+ **English** · [한국어](./covenant-check.ko.md)
4
+
5
+ `pdks covenant check` runs the commit-surface judgment against the installed package. It reads the
6
+ config from the working directory, collects one repository observation, translates it into covenant
7
+ input IR, and dispatches the same judge bodies that the session hook uses.
8
+
9
+ <a id="covenant-check-syntax"></a>
10
+ ## Syntax
11
+
12
+ ```sh
13
+ pdks covenant check
14
+ pdks covenant check --worktree
15
+ pdks covenant check --range <base>..<head>
16
+ pdks covenant check --range <base>...<head>
17
+ ```
18
+
19
+ The default form judges the staged diff. `--worktree` judges the working tree. `--range` judges two
20
+ refs; the `...` form reads from their merge-base.
21
+
22
+ <a id="covenant-check-boundaries"></a>
23
+ ## Observation boundaries
24
+
25
+ The command is explicit about what it observes.
26
+
27
+ | Form | Observed set | `pre` → `post` | Notes |
28
+ |---|---|---|---|
29
+ | `pdks covenant check` | Staged changes only | HEAD blob → staged blob | This is the pre-commit gate. |
30
+ | `pdks covenant check --worktree` | Working tree changes | HEAD blob → bytes on disk | Includes untracked files that are not ignored. |
31
+ | `pdks covenant check --range <base>..<head>` | The change set between two refs | base blob → head blob | Fails if the refs cannot be resolved. |
32
+ | `pdks covenant check --range <base>...<head>` | The merge-base reading of two refs | merge-base blob → head blob | Uses the common ancestor of the refs. |
33
+
34
+ Untracked, non-ignored files are part of `--worktree`. Untracked ignored files are not
35
+ observed. A file git already tracks still appears even if it later matches `.gitignore`. The commit
36
+ surface never prompts for a witness token on `--worktree` or `--range` because those forms are
37
+ diagnostic only.
38
+
39
+ <a id="worktree"></a>
40
+ ## Inspect the working tree with `--worktree`
41
+
42
+ Run `pdks covenant check --worktree` from a git repository with a valid Polydeukes configuration.
43
+ It compares HEAD to the bytes currently on disk, not to the staged contents. Untracked,
44
+ non-ignored files are included as additions; tracked files missing from disk are deletions.
45
+ Before the first commit, existing tracked and non-ignored untracked files have no `pre` value.
46
+
47
+ This observation does not create a commit or ask for a witness token. It still applies the
48
+ configured enforcement: exit 0 can include advice or skips; an unwitnessed block or assembly
49
+ failure exits 2. A clean observation set does not prove that unrelated files or session history
50
+ were judged. It appends telemetry for judgments; it is not a read-only query like `pdks docs`.
51
+
52
+ <a id="covenant-check-results"></a>
53
+ ## Results and exit codes
54
+
55
+ | Situation | Result |
56
+ |---|---|
57
+ | No covenant breaks | exit `0` |
58
+ | A break under `enforce: advise` | exit `0`, one `advised` row on stderr and telemetry |
59
+ | A staged break under `enforce: block` with a configured witness block | Prompts once on `/dev/tty`; a correct token opens the block, a missing or wrong answer exits `2` |
60
+ | A staged break under `enforce: block` without a witness block | exit `2`, no prompt |
61
+ | A break on `--worktree` or `--range` under `enforce: block` | exit `2`, no prompt |
62
+ | Empty domain | exit `0` |
63
+ | Invalid flag syntax | exit `2` with the usage line on stderr |
64
+ | Missing, ambiguous, or invalid config | exit `2` |
65
+ | Unresolved range or missing merge-base | exit `2` |
66
+ | Judge body cannot load | exit `2` |
67
+
68
+ An entry defaults to `advise`; `adapters.git.enforce: block` does not promote it. Protected-path
69
+ violations and entries explicitly set to `enforce: block` can block when the surface is also at
70
+ `block`. A witness prompt additionally requires a configured token and an accessible terminal.
71
+
72
+ `exit 0` can mean passing, advising, skipping, or an empty observation set. `exit 2` means the run
73
+ was fail-closed or the witness token did not open the gate.
74
+
75
+ <a id="covenant-check-examples"></a>
76
+ ## Examples
77
+
78
+ ```sh
79
+ pdks covenant check
80
+ pdks covenant check --worktree
81
+ pdks covenant check --range main..HEAD
82
+ pdks covenant check --range main...feature
83
+ ```
84
+
85
+ ```ts
86
+ import { runCovenantCheck } from 'polydeukes';
87
+
88
+ const result = await runCovenantCheck({ repoRoot: process.cwd() });
89
+ // result is { exitCode: 0 | 2 }
90
+ ```
91
+
92
+ <a id="covenant-check-see-also"></a>
93
+ ## See also
94
+
95
+ - [`pdks explain`](./explain.md)
96
+ - [`@polydeukes/adapter-git`](../packages/adapter-git.md)
97
+ - [`@polydeukes/covenant`](../packages/covenant.md)
98
+ - [`Configuration reference`](../configuration/index.md#adapters-git)
package/dist/docs/reference/cli/docs.ko.md ADDED
@@ -0,0 +1,97 @@
1
+ # `pdks docs`
2
+
3
+ [English](./docs.md) · **한국어**
4
+
5
+ 설치된 패키지에 동봉된 문서를 읽습니다. 로컬 파일만 사용하며 프로젝트 설정을 읽거나,
6
+ 판정기를 호출하거나, 네트워크 서비스에 질의하지 않습니다.
7
+
8
+ <a id="syntax"></a>
9
+ ## 구문
10
+
11
+ ```sh
12
+ pdks docs
13
+ pdks docs <topic> [--lang en|ko]
14
+ pdks docs search <query> [--lang en|ko] [--limit N] [--json]
15
+ pdks docs show <document-id> [--lang en|ko] [--section <section-id>] [--json]
16
+ ```
17
+
18
+ `pdks docs --help`, `pdks docs search --help`, `pdks docs show --help`로 구문을 확인합니다.
19
+ 기본 언어는 영어입니다. 기존 주제인 `install`, `config`, `discipline`, `covenant`,
20
+ `witness`도 유지합니다. 주제별 조회와 검색은 같은 문서 목록을 사용합니다.
21
+
22
+ <a id="search"></a>
23
+ ## 검색
24
+
25
+ ```sh
26
+ pdks docs search 'locale key pairing'
27
+ pdks docs search '번역 키 짝 맞춤' --lang ko --limit 3
28
+ pdks docs search --worktree --json
29
+ ```
30
+
31
+ 검색어는 인수 하나입니다. 여러 단어로 검색할 때는 따옴표로 묶습니다. `--worktree` 같은
32
+ 식별자도 첫 번째 검색 인수로 사용할 수 있습니다. 그 뒤에 오는 알 수 없는 플래그는
33
+ 오류입니다. 결과 개수는 1부터 50까지의 정수이며 기본값은 5입니다. 선택한 언어의 절을
34
+ 대상으로 제목, 문서 메타데이터, Markdown 본문을 검색합니다. 공백으로 나눈 검색어가
35
+ 모두 일치해야 합니다. 같은 입력에는 같은 결과를 내는 결정론적 텍스트 검색이며,
36
+ 의미 해석이나 번역은 하지 않습니다.
37
+
38
+ 각 결과에는 문서와 절 ID, 제목, 원문 일부, 상대 소스 경로, 점수, 완전한 `pdks docs show`
39
+ 명령이 있습니다. 점수가 높은 결과부터 나열하고, 동점이면 문서 ID와 절 ID의 ASCII 순서를
40
+ 따릅니다. 점수는 순위를 정하는 값이지 답변의 신뢰도가 아닙니다.
41
+
42
+ <a id="show"></a>
43
+ ## 문서나 절 조회
44
+
45
+ ```sh
46
+ pdks docs show first-judgment
47
+ pdks docs show write-disciplines --lang ko --section locale-key-pairing
48
+ ```
49
+
50
+ `show`는 생성한 답변이 아니라 Markdown 원문을 반환합니다. 절은 명시한 앵커에서 시작해
51
+ 다음 같은 수준 또는 상위 수준의 제목과 그 앵커 직전에 끝납니다. 하위 절은 포함합니다.
52
+ 코드 블록 안의 제목은 경계가 아니라 본문입니다. 제목이 달라도 영어와 한국어의 ID는
53
+ 같습니다.
54
+
55
+ <a id="json"></a>
56
+ ## JSON 출력
57
+
58
+ 검색은 다음 구조의 객체를 반환합니다.
59
+
60
+ ```text
61
+ { schemaVersion, packageVersion, language, query, count, results }
62
+ ```
63
+
64
+ `schemaVersion`은 `1`이고 `packageVersion`은 설치된 패키지의 버전입니다. `count`는
65
+ 개수 제한을 적용한 뒤 반환하는 결과 수입니다. 각 결과에는 `documentId`, `sectionId`,
66
+ `title`, `excerpt`, `source`, `command`, 숫자형 `score`가 있습니다. `source`는 문서
67
+ 디렉터리 기준 상대 경로와 절 앵커이며, 빌드 머신의 절대 경로가 아닙니다.
68
+
69
+ 조회는 다음 구조를 반환합니다.
70
+
71
+ ```text
72
+ { schemaVersion, packageVersion, language, documentId, sectionId, source, markdown }
73
+ ```
74
+
75
+ 전체 문서를 조회하면 `sectionId`는 `null`입니다. `markdown`은 바꾸지 않은 본문입니다.
76
+ JSON 출력은 완전한 객체 하나와 뒤따르는 줄바꿈으로 이루어집니다. 오류가 발생하면
77
+ 불완전한 JSON 답변을 출력하지 않습니다.
78
+
79
+ <a id="failures"></a>
80
+ ## 종료 코드와 동봉 범위
81
+
82
+ | 조건 | 종료 코드 | 출력 |
83
+ |---|---|---|
84
+ | 정상 조회 | `0` | stdout에 답변 |
85
+ | 검색 결과 없음 | `0` | 빈 목록 표시. JSON은 `count: 0`, `results: []` |
86
+ | 잘못된 인수 또는 알 수 없는 ID | `2` | stderr에 진단, stdout은 비어 있음 |
87
+ | 동봉 파일이 없거나 서로 맞지 않음 | `2` | stderr에 진단, stdout은 비어 있음 |
88
+
89
+ 중복 플래그, 누락된 값, 불필요한 위치 인수, 지원하지 않는 언어, 빈 검색어, 경로 형태의
90
+ ID는 오류입니다. `show`는 등록한 ID를 읽으며 임의의 파일 경로를 읽지 않습니다.
91
+ 무결성 해시로 Markdown 변경을 탐지하고 메타데이터가 동봉 내용과 맞는지 확인합니다.
92
+ 동봉 문서가 불완전하거나 손상됐다면 패키지를 다시 설치하세요. 기여자는 전체 소스를
93
+ 갖춘 체크아웃에서 다시 빌드할 수도 있습니다.
94
+
95
+ 과거 게시물, 백서, 기여 안내, 이전 주소의 이동 안내는 동봉하거나 검색하지 않습니다.
96
+ 설치된 문서는 온라인 최신 버전이 아니라 해당 패키지 버전을 설명합니다. 전체 원본 문서
97
+ 목록은 [문서 홈](../../README.ko.md)에 있습니다.
package/dist/docs/reference/cli/docs.md ADDED
@@ -0,0 +1,95 @@
1
+ # `pdks docs`
2
+
3
+ **English** · [한국어](./docs.ko.md)
4
+
5
+ Read the documentation bundled with the installed package. This command reads local files only;
6
+ it does not load the project's configuration, invoke the judge, or query a network service.
7
+
8
+ <a id="syntax"></a>
9
+ ## Syntax
10
+
11
+ ```sh
12
+ pdks docs
13
+ pdks docs <topic> [--lang en|ko]
14
+ pdks docs search <query> [--lang en|ko] [--limit N] [--json]
15
+ pdks docs show <document-id> [--lang en|ko] [--section <section-id>] [--json]
16
+ ```
17
+
18
+ Use `pdks docs --help`, `pdks docs search --help`, or `pdks docs show --help` for syntax.
19
+ The default language is English. The five legacy topics remain `install`, `config`, `discipline`,
20
+ `covenant`, and `witness`; each is mapped by the same catalog that drives search and retrieval.
21
+
22
+ <a id="search"></a>
23
+ ## Search
24
+
25
+ ```sh
26
+ pdks docs search 'locale key pairing'
27
+ pdks docs search '번역 키 짝 맞춤' --lang ko --limit 3
28
+ pdks docs search --worktree --json
29
+ ```
30
+
31
+ The query is one argument. Quote multiword queries. A literal identifier such as `--worktree`
32
+ is accepted as the first search argument; subsequent unknown flags are errors. Limits are
33
+ integers from 1 to 50, defaulting to 5. Search selects sections in the requested language and
34
+ uses their titles, document metadata, and Markdown text. Every whitespace-separated query term
35
+ must match; this is a deterministic text search, not semantic interpretation or translation.
36
+
37
+ Each result includes the document and section IDs, a title, a raw-text excerpt, its relative
38
+ source path, a score, and a complete `pdks docs show` command. Higher scores come first; ties
39
+ use ASCII document ID and section ID order. Scores are ranking values, not confidence measures.
40
+
41
+ <a id="show"></a>
42
+ ## Show a document or section
43
+
44
+ ```sh
45
+ pdks docs show first-judgment
46
+ pdks docs show write-disciplines --lang ko --section locale-key-pairing
47
+ ```
48
+
49
+ `show` returns the original Markdown, not a generated answer. A section starts at its explicit
50
+ anchor and ends before the next same-level or higher-level heading and its anchor. Child
51
+ sections are included. Headings inside fenced code are content, not boundaries. IDs are stable
52
+ across English and Korean even when their titles differ.
53
+
54
+ <a id="json"></a>
55
+ ## JSON output
56
+
57
+ Search returns this object shape:
58
+
59
+ ```text
60
+ { schemaVersion, packageVersion, language, query, count, results }
61
+ ```
62
+
63
+ `schemaVersion` is `1`; `packageVersion` is the installed package's version. `count` is the number
64
+ of returned results after applying the limit. Each result has `documentId`, `sectionId`, `title`,
65
+ `excerpt`, `source`, `command`, and numeric `score`. `source` is relative to the docs directory
66
+ and includes the section anchor; it is not an absolute path on the build machine.
67
+
68
+ Show returns:
69
+
70
+ ```text
71
+ { schemaVersion, packageVersion, language, documentId, sectionId, source, markdown }
72
+ ```
73
+
74
+ `sectionId` is `null` for a full document. `markdown` contains its unchanged body. JSON output is
75
+ one complete object followed by a newline; errors never produce a partial JSON answer.
76
+
77
+ <a id="failures"></a>
78
+ ## Exit codes and bundle boundaries
79
+
80
+ | Condition | Exit | Output |
81
+ |---|---|---|
82
+ | A successful query | `0` | Answer on stdout |
83
+ | No search match | `0` | Explicit empty list; JSON has `count: 0`, `results: []` |
84
+ | Invalid arguments or an unknown ID | `2` | Diagnostic on stderr, empty stdout |
85
+ | Missing or inconsistent bundle files | `2` | Diagnostic on stderr, empty stdout |
86
+
87
+ Duplicate flags, missing values, positional extras, unsupported languages, empty queries, and
88
+ path-shaped IDs are errors. `show` reads registered IDs, not arbitrary filesystem paths.
89
+ Integrity hashes detect changed Markdown, and metadata is checked against the bundle contents.
90
+ Reinstall the package if its bundle is incomplete or damaged. Rebuilding from the complete source
91
+ checkout is another option for contributors.
92
+
93
+ Historical posts, the whitepaper, contribution instructions, and compatibility notices are not
94
+ bundled or searched. The installed docs describe that package version, not an online latest
95
+ version. See [the documentation home](../../README.md) for the full source collection.
package/dist/docs/reference/cli/explain.ko.md ADDED
@@ -0,0 +1,79 @@
1
+ # `pdks explain`
2
+
3
+ [English](./explain.md) · **한국어**
4
+
5
+ `pdks explain`은 등록된 항목을 판정 없이 보여 줍니다. 실제 세션·커밋 실행에 쓰는 조립 함수를 호출하므로, 별도로 추정한 결과가 아니라 실제 등록 내용을 확인할 수
6
+ 있습니다.
7
+
8
+ <a id="explain-syntax"></a>
9
+ ## 구문
10
+
11
+ ```sh
12
+ pdks explain
13
+ ```
14
+
15
+ 추가 인자는 허용하지 않습니다. 작업 디렉터리의 설정과 설치된 판정 패키지를 읽고, 두 표면을 조립한 뒤 결과를 출력합니다.
16
+
17
+ <a id="explain-what-it-shows"></a>
18
+ ## 무엇을 보여 주는가
19
+
20
+ 출력은 표면별로 나뉩니다. 각 표면의 등록 항목과 집계를 보여 주며, 등록 항목은 한 줄씩 표시합니다.
21
+
22
+ 행 종류는 다음과 같습니다.
23
+
24
+ - `meta` — 판정 사슬 자체를 지키는 등록
25
+ - `declare` — 컴파일된 규율 항목 하나
26
+ - `skip` — 판정할 수 없는 사유를 표시하는 등록
27
+ - `draft` — 아직 판정 대상으로 전환하지 않은 `draft: true` 항목
28
+
29
+ 이 명령은 판정기에 입력을 전달하지 않으며 텔레메트리나 대화 기록 파일도 읽고 쓰지 않습니다. 세션 표면에는 파일을 읽지 않는 대화 기록 대체물을 넘겨
30
+ `transcript-mod` 등록도 실제 훅을 조립할 때처럼 표시합니다.
31
+
32
+ <a id="explain-failure-conditions"></a>
33
+ ## 실패 조건
34
+
35
+ | 상황 | 결과 |
36
+ |---|---|
37
+ | 설정이 유효하고 판정 패키지를 찾을 수 있음 | 종료 `0` |
38
+ | 추가 인자 | 종료 `2`, stderr에 사용법 출력 |
39
+ | 설정이 없거나 여러 개이거나 유효하지 않음 | 종료 `2` |
40
+ | 판정 패키지를 불러올 수 없음 | 종료 `2` |
41
+ | 그 밖의 조립 실패 | 종료 `2` |
42
+
43
+ 실패 시 stdout은 0바이트로 남습니다. 중간 테이블을 출력하지 않습니다.
44
+
45
+ <a id="explain-example"></a>
46
+ ## 예제
47
+
48
+ ```sh
49
+ pdks explain
50
+ ```
51
+
52
+ 출력은 설정 파일 경로로 시작하고, 그다음 세션 표면 블록 하나와 커밋 표면 블록 하나가 나옵니다.
53
+ 추가 규율이 없는 시작 설정은 이런 모양입니다.
54
+
55
+ ```text
56
+ pdks explain — polydeukes.config.yaml
57
+
58
+ surface: session (claude-code hook) · disciplines: advise unless enforce: block · meta: block
59
+ registrations 3 · declare 0 · skip 0 · meta 3 · draft 0
60
+ meta self-mod paths N (common; includes the config file itself)
61
+ meta shell-mod paths N (common)
62
+ meta transcript-mod content predicate · conditional: transcript_path
63
+
64
+ surface: commit (git pre-commit) · enforce: block · disciplines: advise unless enforce: block
65
+ registrations 2 · declare 0 · skip 0 · meta 2 · draft 0
66
+ meta self-mod paths N (common ∪ adapters.git; deduped, includes the config file itself)
67
+ meta shell-mod paths N (common)
68
+ ```
69
+
70
+ `N`은 조립된 경로 개수입니다. `declare` 행의 라벨은 항목 `id`이고 설명은 카탈로그 좌표입니다.
71
+ `skip` 행은 건너뛴 이유를 적습니다. `draft` 행은 `unpromoted — no judgment`입니다.
72
+
73
+ <a id="explain-see-also"></a>
74
+ ## 함께 보기
75
+
76
+ - [`pdks covenant check`](./covenant-check.ko.md)
77
+ - [`pdks init`](./init.ko.md)
78
+ - [`@polydeukes/covenant`](../packages/covenant.ko.md)
79
+ - [설정 참조](../configuration/index.ko.md)
package/dist/docs/reference/cli/explain.md ADDED
@@ -0,0 +1,84 @@
1
+ # `pdks explain`
2
+
3
+ **English** · [한국어](./explain.ko.md)
4
+
5
+ `pdks explain` renders the assembled registration table without judging anything. It uses the same
6
+ assembly functions that the two runners use, so the output is a view of the real dispatch table, not
7
+ a second opinion.
8
+
9
+ <a id="explain-syntax"></a>
10
+ ## Syntax
11
+
12
+ ```sh
13
+ pdks explain
14
+ ```
15
+
16
+ Any extra argument is invalid. The command reads the config at the working directory, loads the
17
+ covenant distribution, assembles both surfaces, and prints the result.
18
+
19
+ <a id="explain-what-it-shows"></a>
20
+ ## What it shows
21
+
22
+ The output is a surface-by-surface summary. Each surface lists one line per registration, then a
23
+ tally line.
24
+
25
+ The row kinds are:
26
+
27
+ - `meta` — one of the registrations that protect the judging chain itself
28
+ - `declare` — one compiled discipline entry
29
+ - `skip` — a registration that could not be judged and records a skip reason
30
+ - `draft` — an unpromoted entry with `draft: true`
31
+
32
+ The command does not dispatch, does not write telemetry, and does not read a transcript file. The
33
+ session surface is rendered with a no-op transcript so the `transcript-mod` row appears exactly as
34
+ it would under a normal hook payload.
35
+
36
+ <a id="explain-failure-conditions"></a>
37
+ ## Failure conditions
38
+
39
+ | Situation | Result |
40
+ |---|---|
41
+ | Config loads and the covenant dist resolves | exit `0` |
42
+ | Any extra argument | exit `2`, usage line on stderr |
43
+ | Missing, ambiguous, or invalid config | exit `2` |
44
+ | The covenant distribution cannot load | exit `2` |
45
+ | Any assembly failure | exit `2` |
46
+
47
+ The command leaves stdout at zero bytes on failure. It never prints a partial table.
48
+
49
+ <a id="explain-example"></a>
50
+ ## Example
51
+
52
+ ```sh
53
+ pdks explain
54
+ ```
55
+
56
+ The output starts with the config file path, then one block for the session surface and one for the
57
+ commit surface. A starter config with no extra disciplines looks like this:
58
+
59
+ ```text
60
+ pdks explain — polydeukes.config.yaml
61
+
62
+ surface: session (claude-code hook) · disciplines: advise unless enforce: block · meta: block
63
+ registrations 3 · declare 0 · skip 0 · meta 3 · draft 0
64
+ meta self-mod paths N (common; includes the config file itself)
65
+ meta shell-mod paths N (common)
66
+ meta transcript-mod content predicate · conditional: transcript_path
67
+
68
+ surface: commit (git pre-commit) · enforce: block · disciplines: advise unless enforce: block
69
+ registrations 2 · declare 0 · skip 0 · meta 2 · draft 0
70
+ meta self-mod paths N (common ∪ adapters.git; deduped, includes the config file itself)
71
+ meta shell-mod paths N (common)
72
+ ```
73
+
74
+ `N` is the assembled path count. A `declare` row uses the entry `id` as its label and a
75
+ catalogue coordinate as its description. A `skip` row names a skip reason. A `draft` row is
76
+ `unpromoted — no judgment`.
77
+
78
+ <a id="explain-see-also"></a>
79
+ ## See also
80
+
81
+ - [`pdks covenant check`](./covenant-check.md)
82
+ - [`pdks init`](./init.md)
83
+ - [`@polydeukes/covenant`](../packages/covenant.md)
84
+ - [`Configuration reference`](../configuration/index.md)
package/dist/docs/reference/cli/init.ko.md ADDED
@@ -0,0 +1,119 @@
1
+ # `pdks init`
2
+
3
+ [English](./init.md) · **한국어**
4
+
5
+ 프로젝트를 세션 표면에 연결합니다. `claude-code`와 `grok` 두 형식 모두 대상 프로젝트에서
6
+ 설치된 패키지를 찾을 수 있는지 먼저 검사합니다. 그 검사가 끝나기 전에는 파일을 쓰지 않습니다.
7
+
8
+ <a id="init-syntax"></a>
9
+ ## 구문
10
+
11
+ ```sh
12
+ pdks init claude-code
13
+ pdks init grok
14
+ ```
15
+
16
+ 두 형식 모두 다시 실행할 수 있습니다. 이미 있는 산출물은 보존하고 `skipped`로 보고합니다.
17
+ 사전 검사에 실패하면 파일을 쓰지 않고 종료 코드 `2`를 반환합니다.
18
+
19
+ <a id="init-common"></a>
20
+ ## 공통 사전 검사와 초기 파일
21
+
22
+ 설치 순서는 다음과 같습니다.
23
+
24
+ 1. 대상 프로젝트에서 `polydeukes`를 찾을 수 있는지 확인합니다.
25
+ 2. 공통 설정과 텔레메트리 제외 항목을 만듭니다.
26
+ 3. 표면별 등록 파일을 추가합니다.
27
+
28
+ 두 설치기가 공통으로 만드는 것은 `polydeukes.config.yaml`과 `.gitignore`의 `.polydeukes/`
29
+ 항목입니다. 설정 파일에는 언어 블록, 보호 목록, 증인 블록, 주석으로 된 규율 예제가 있습니다.
30
+ 완성된 정책이 아니라 프로젝트에 맞춰 고칠 출발점입니다.
31
+
32
+ <a id="init-claude-code"></a>
33
+ ## `pdks init claude-code`
34
+
35
+ Claude Code 세션 표면에 필요한 파일은 다음과 같습니다.
36
+
37
+ - `.claude/hooks/covenant-pretooluse.mjs`
38
+ - `.claude/settings.json`
39
+ - `.claude/rules/polydeukes.md`
40
+ - `.claude/skills/discipline-draft/SKILL.md`
41
+ - `polydeukes.config.yaml`
42
+ - `.gitignore`
43
+
44
+ 훅은 `polydeukes/claude-code`에 판정을 맡깁니다. 설정에는 PreToolUse 등록을 병합하고,
45
+ 문서 안내 파일은 AI 파트너가 웹 검색 대신 `pdks docs`를 쓰도록 알려 줍니다.
46
+ 스킬은 설명된 규율 문제를 설정 항목으로 바꾸는 절차를 제공합니다.
47
+
48
+ 기존 훅, 설정 데이터, 문서 안내, 스킬 파일은 보존합니다. 호스트 설정에는 필요한 등록을
49
+ 병합하고 `.gitignore`에는 빠진 항목만 추가합니다. 아래 설명처럼 기존 Grok 등록을 조정할
50
+ 수도 있으므로 재실행이 언제나 아무것도 바꾸지 않는 것은 아닙니다.
51
+
52
+ 패키지 버전을 올려도 사용자가 수정한 스킬은 덮어쓰지 않습니다. 임시 프로젝트에서 새 사본을
53
+ 만들어 기존 파일과 비교한 뒤, 백업하고 필요한 부분만 반영하세요. 강제로 다시 만들려고
54
+ 작업 중인 프로젝트의 스킬을 지우지는 마세요.
55
+
56
+ <a id="init-grok"></a>
57
+ ## `pdks init grok`
58
+
59
+ Grok 전용 프로젝트에는 다음 파일을 만듭니다.
60
+
61
+ - `.grok/hooks/covenant-pretooluse.mjs`
62
+ - `.grok/hooks/covenant-pretooluse.json`
63
+ - `polydeukes.config.yaml`
64
+ - `.gitignore`
65
+
66
+ Claude Code 형식과의 차이는 다음과 같습니다.
67
+
68
+ - `.claude/` 파일을 만들지 않고 Grok 훅 JSON에 등록합니다.
69
+ - Claude 위임 훅이 이미 있으면 새 훅을 만들지 않고 Grok JSON에서 기존 파일을 지정합니다.
70
+ - 새 등록의 제한 시간은 60초입니다. Grok 호스트 기본값은 5초이며, 훅 실행이 시간 초과로
71
+ 끝나면 해당 호출을 차단하지 않습니다(fail-open). Claude 설정에 같은 명령이 등록돼 있으면
72
+ Grok의 매칭 조건도 맞춰
73
+ 명령과 조건이 모두 같게 만듭니다.
74
+ - 어느 설치기를 다시 실행하든, 설치기가 만든 Grok 훅 명령을 기존 Claude 파일로 바꾸고
75
+ 매칭 조건을 맞출 수 있습니다. 사용자가 다른 곳을 지정한 명령은 그대로 두며 기존 제한
76
+ 시간도 유지합니다.
77
+ - 나중에 Claude 설정을 제거했다면 Grok JSON을 다시 만들어 Grok 기본 매칭 조건을 복원하세요.
78
+ 사용자 설정부터 백업해야 합니다. 변경 뒤에는 Grok의 Hooks 탭을 다시 불러오거나 새 세션을
79
+ 시작합니다.
80
+
81
+ Grok는 Claude 세션 증인 밸브가 요구하는 인간 메시지 증거를 제공하지 않습니다.
82
+ 대화 기록은 Claude JSONL이 아니라 ACP `updates.jsonl`입니다.
83
+ [Grok 복구 안내](../../troubleshooting.ko.md#grok-witness)를 참고하세요.
84
+
85
+ <a id="init-results"></a>
86
+ ## 결과와 실패 조건
87
+
88
+ | 상황 | 결과 |
89
+ |---|---|
90
+ | 패키지를 찾고 대상 프로젝트의 초기 파일을 만들 수 있음 | 종료 `0` |
91
+ | 요청한 산출물이 이미 있음 | `skipped`로 보고하고 종료 `0` |
92
+ | 대상 프로젝트에서 패키지를 찾을 수 없음 | 종료 `2`, 파일을 쓰지 않음 |
93
+ | 설정 파일이 여러 개라 모호함 | 종료 `2`, 파일을 쓰지 않음 |
94
+ | 호스트 설정 파일을 읽거나 구문을 분석할 수 없음 | 종료 `2`, 파일을 쓰지 않음 |
95
+ | 그 밖의 사전 검사 또는 파일 쓰기 실패 | 종료 `2` |
96
+
97
+ 사전 검사는 파일을 쓰기 전에 끝납니다. 하지만 이후 파일 쓰기에서 실패하면 일부 파일이
98
+ 이미 만들어졌을 수 있습니다. 설치 전체를 한꺼번에 되돌리는 기능은 아닙니다. 오류를 확인하고
99
+ 파일시스템 문제를 고친 뒤 다시 실행하세요. 설치가 실패했으니 아무 파일도 없을 것이라고
100
+ 가정해서는 안 됩니다.
101
+
102
+ <a id="init-examples"></a>
103
+ ## 예제
104
+
105
+ ```sh
106
+ pdks init claude-code
107
+ pdks init grok
108
+ ```
109
+
110
+ 설치기는 CLI 명령입니다. `polydeukes`나 `polydeukes/claude-code` 계약의 공개 심볼이
111
+ 아닙니다.
112
+
113
+ <a id="init-see-also"></a>
114
+ ## 함께 보기
115
+
116
+ - [`pdks docs`](./docs.ko.md)
117
+ - [`pdks explain`](./explain.ko.md)
118
+ - [설정 참조](../configuration/index.ko.md)
119
+ - [`polydeukes`](../packages/polydeukes.ko.md)