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/README.ko.md CHANGED
@@ -1,80 +1,54 @@
1
- # polydeukes
2
-
3
- **한국어** · [English](./README.md)
4
-
5
- > 스코프 없는 umbrella 패키지입니다. `pdks` CLI 진입점과 config 디스커버리 로더가 살고,
6
- > 프레임워크의 조각을 저장소가 실제로 돌리는 표면에 맞게 조립하는 유일한 자리입니다.
7
-
8
- **알파(alpha) 단계입니다.** 이 패키지는 스코프 없는 `polydeukes` 이름을 예약하고, 스코프
9
- 모듈(`@polydeukes/*`)을 조립할 수 있는 유일한 패키지로 그 위에 섭니다. 다른 모든 의존은 코어를
10
- 통해서만 단방향으로 흐릅니다.
11
-
12
- ## 여기 담긴 것
13
-
14
- - **`loadConfig({ rootDir })`.** config 디스커버리입니다. 주어진 루트 바로 아래에서 정확히 하나의
15
- 데이터 config(`polydeukes.config` 파일의 yaml·yml·json 형태)를 찾아, 안전 스키마로 해석하고
16
- (설정 데이터는 결코 실행되지 않습니다) 코어의 `defineConfig()`에 검증을 맡깁니다. 모든 실패
17
- 분기는 예외를 던집니다(throw). 조용한 기본값은 금지이고, 발견된 파일은 자기 자신을 보호
18
- 표면에 편입시킵니다.
19
- - **`pdks covenant check`.** `pdks` bin의 첫 실물 서브커맨드입니다(`polydeukes`는 별칭).
20
- pre-commit 판정 러너로, 스테이징 영역의 변경을 `@polydeukes/adapter-git`이 수집해
21
- 약속(covenant) 입력 IR로 번역하고, 세션 훅이 부르는 바로 그 in-process 판정기로 보냅니다.
22
- 판정기는 하나, 표면은 여럿입니다. `--worktree`와 `--range <base>..<head>`는 같은 판정을
23
- 작업 트리나 ref 범위에 진단 호출로 돌리며, 증인 프롬프트는 뜨지 않습니다. 세션을 읽는 선언(`precedent`와 다른 이력 기전)도 다른 규율과
24
- 똑같이 조립되지만, 읽을 세션이 없으므로 자기 `supply: pass`가 처분합니다. 스테이징 변경과 매치하면 자기
25
- id와 그 변경을 담은 `skipped` 이벤트를 남기고 커밋은 진행됩니다. 여기서 판정하면 걸리는
26
- 커밋마다 정당하게 통과할 길 없이 막히고, 아예 걸러내면 게이트가 물러섰다는 사실이 가려집니다.
27
- 세션 표면이 읽을 transcript를 갖지 못했을 때와 같은 처분입니다. 빈 스테이징은 명시적
28
- 통과이고, config가 없거나 불량이면 닫힌 실패(exit 2)입니다.
29
- - **`pdks init claude-code`.** 세션 표면 설치기입니다. 아무것도 쓰기 전에 대상 프로젝트에서
30
- `polydeukes`가 해소되는지부터 증명하고, 그다음 모든 배포 경로가 공유하는 것(데이터 config와
31
- `.polydeukes/` 무시 줄)과 이 경로가 지는 것(위임자 훅, 그 파일이 이미 담고 있던 것에 병합되는
32
- `.claude/settings.json` 등록, 그리고 AI 파트너를 `pdks docs`로 보내는 범위 한정 규율 파일)을
33
- 만듭니다. 기존 산출물은 덮어쓰지 않습니다. 이미 있는 것은 보고하고 그대로 두므로 재실행은
34
- 아무 일도 하지 않고, 사용자가 고친 내용이 살아남습니다. 생성된 config는 해소 경로를 보호
35
- 목록에 담고 증인(witness) 블록을 함께 갖습니다. 밸브가 없으면 첫 차단이 곧 프로젝트 정지인데,
36
- 방금 등록한 훅 자신이 보호 대상이기 때문입니다. config 철자 둘이 공존하는 트리, 파싱되지 않는
37
- settings 파일, 해소되지 않는 패키지는 전부 선행 조건 실패입니다. 반쯤 배선된 트리를 남기는
38
- 대신 파일을 하나도 만들지 않습니다.
39
- - **`pdks init grok`.** Grok 세션 표면 설치기입니다. 선행 검사와 공유 스캐폴드는 같고, 이 경로가
40
- 지는 것은 `.grok/hooks/`입니다(timeout 60인 JSON 등록, Claude 위임자가 없을 때만 위임자 파일).
41
- Claude 훅 파일이 이미 있으면 JSON command가 그 파일을 가리켜 판정기를 둘 스폰하지 않습니다.
42
- 나중에 어느 설치기를 다시 돌려도, 설치기가 심은 grok-mjs command는 같은 방식으로 재조준되고,
43
- JSON matcher는 그 command의 `.claude/settings.json` 항목을 따릅니다. Grok는 command와
44
- matcher가 모두 같을 때만 등록 둘을 하나로 접기 때문입니다. 이미 열린 Grok 세션은 시작 때 훅 스냅샷을 유지합니다. 증인 밸브는 Grok에서 열리지 않습니다.
45
- - **`pdks docs [topic]`.** 오프라인 문서 열람기입니다. 영어 가이드와 레퍼런스 층이 빌드 시점에
46
- `dist/docs`로 복사되므로, 소비자의 AI 파트너는 검색 엔진이 색인한 아무 판본이 아니라 판정을
47
- 수행하는 코드와 함께 실린 문서를 읽습니다. 인자 없이 부르면 토픽 다섯을 열거하는데, 에이전트가
48
- 무엇을 물을 수 있는지 아는 경로가 그 목록뿐입니다. 토픽을 주면 그 절을 원문 그대로 돌려주고
49
- 이어서 읽을 레퍼런스를 한 줄 덧붙입니다. 질의 정의역은 그 다섯 이름뿐입니다. 모르는 토픽, 없는
50
- 동봉 문서, 문서가 더는 담지 않는 표제는 각각 무엇이 없었는지 stderr에 이름을 적고 exit 2로
51
- 끝나며 stdout은 0바이트로 둡니다. 절반만 쓰인 답은 에이전트가 그것을 문서로 읽고 그대로
52
- 인용하므로, 그런 상태를 만드는 경로를 두지 않습니다.
53
- - **커밋 표면 증인(witness) 밸브.** `block` 수위(기본값)에서 스테이징 영역의 변경이 실제로
54
- 약속을 깨면 러너가 `/dev/tty`에서 증인 토큰 전문을 1회 묻습니다(부분 문자열은 거부합니다).
55
- 프롬프트는 깨진 등록과 걸린 항목, 그리고 이 한 번의 답이 커밋 전체를 덮는다는 사실을 적습니다.
56
- 깨끗한 커밋은 프롬프트를 보지 않습니다. TTY가 없으면, 즉 CI나 에이전트가 띄운 `git commit`
57
- 이면 프롬프트도 통과할 길도 없습니다. 밸브는 터미널 앞의 인간에게만 닿고, 어떤 상태도 남기지
58
- 않으며, 증언으로 통과한 판정은 모두 `witnessed`로 기록됩니다. 조용한 우회는 없습니다.
59
- - **시행 수위.** git 어댑터의 네임스페이스 설정 `adapters.git.enforce: block | advise`가 커밋
60
- 표면 판정의 처분을 고릅니다. `advise`에서는 밸브 자체가 조립되지 않습니다. 판정은 `advised`
61
- 이벤트로 기록되고, stderr에 권고 한 줄이 남으며, 커밋은 진행됩니다. 차단하는 대신 측정하는
62
- 백스톱입니다. 완화되는 것은 판정뿐이라, 판정 자체가 불가능한 실행(설정 없음·무효, 판정 본체
63
- 해석 불가)은 어느 수위에서든 exit 2로 닫힙니다.
64
-
65
- ## 전체 지도
66
-
67
- | 모듈 | 역할 |
68
- |---|---|
69
- | `@polydeukes/core` | 약속(covenant) 프로토콜, config 스키마, ROI 텔레메트리, 대화 기록 이음새 |
70
- | `@polydeukes/covenant` | 디스패처, 판정 본체, Bash 분석, 규율(discipline) 라이브러리 |
71
- | `@polydeukes/adapter-claude-code` | 세션 표면. PreToolUse 페이로드를 약속(covenant) 입력 IR로 번역 |
72
- | `@polydeukes/adapter-git` | 커밋 표면. `staged diff`를 약속(covenant) 입력 IR로 번역 |
73
- | `@polydeukes/ledger` · `@polydeukes/memory` · `@polydeukes/verify` | 청사진 단계 |
74
-
75
- 아키텍처 청사진과 설계 근거는
76
- [프로젝트 저장소](https://github.com/huskyhoochu/polydeukes)에 있습니다.
77
-
78
- ## 라이선스
79
-
80
- MIT
1
+ # `polydeukes`
2
+
3
+ [English](./README.md) · **한국어**
4
+
5
+ Polydeukes는 우산 패키지입니다. 이 패키지 하나에 `pdks` 실행 파일, 설정 로더,
6
+ 커밋 표면 실행기, 세션 표면 실행기 서브패스, 동봉 스키마가 모두 포함돼 있습니다.
7
+
8
+ <a id="overview"></a>
9
+ ## 개요
10
+
11
+ 공개 계약 심볼과 진입점은 다음과 같습니다.
12
+
13
+ - `loadConfig`
14
+ - `runCovenantCheck`
15
+ - `ResolvedConfig`
16
+ - `polydeukes/claude-code` → `runClaudeCodeHook`
17
+ - `polydeukes/schema.json`
18
+ - `pdks covenant check`
19
+ - `pdks init claude-code`
20
+ - `pdks init grok`
21
+ - `pdks explain`
22
+ - `pdks docs [topic]`
23
+
24
+ <a id="public-symbols"></a>
25
+ ## 공개 심볼
26
+
27
+ ```ts
28
+ import { loadConfig, runCovenantCheck } from 'polydeukes';
29
+ import { runClaudeCodeHook } from 'polydeukes/claude-code';
30
+ ```
31
+
32
+ ```ts
33
+ function loadConfig(spec: { rootDir: string }): {
34
+ config: import('@polydeukes/core').ResolvedConfig;
35
+ configPath: string;
36
+ };
37
+
38
+ function runCovenantCheck(spec: {
39
+ repoRoot: string;
40
+ telemetryPath?: string;
41
+ covenantDist?: string;
42
+ ttyPrompt?: (prompt: string) => string | null;
43
+ domain?: unknown;
44
+ }): Promise<{ exitCode: 0 | 2 }>;
45
+ ```
46
+
47
+ <a id="see-also"></a>
48
+ ## 같이 보기
49
+
50
+ - [`polydeukes` 패키지 레퍼런스](../../docs/reference/packages/polydeukes.ko.md)
51
+ - [`설정 레퍼런스`](../../docs/reference/configuration/index.ko.md)
52
+ - [`pdks covenant check`](../../docs/reference/cli/covenant-check.ko.md)
53
+ - [`pdks init`](../../docs/reference/cli/init.ko.md)
54
+ - [`pdks explain`](../../docs/reference/cli/explain.ko.md)
package/README.md CHANGED
@@ -1,94 +1,55 @@
1
- # polydeukes
2
-
3
- **English** · [한국어](https://github.com/huskyhoochu/polydeukes/blob/main/packages/polydeukes/README.ko.md)
4
-
5
- > The unscoped umbrella: the `pdks` CLI entry point and the config discovery loader — the one
6
- > place where the framework's pieces are assembled for the surfaces a repository actually runs.
7
-
8
- **Alpha.** This package reserves the unscoped `polydeukes` name and sits above the scoped
9
- `@polydeukes/*` modules as the only one allowed to assemble them — every other dependency stays
10
- one-way, through the core alone.
11
-
12
- ## What lives here
13
-
14
- - **`loadConfig({ rootDir })`** — config discovery. Exactly one root data config (a
15
- `polydeukes.config` file in yaml, yml, or json form) directly under the given root, parsed with
16
- a safe schema (config data is never executable) and validated by the core's `defineConfig()`.
17
- Every failure branch throws — silent defaults are forbidden — and the discovered file attaches
18
- itself to its own protection surface.
19
- - **`pdks covenant check`** — the first real subcommand of the `pdks` bin (`polydeukes` is an
20
- alias). A pre-commit judgment runner: staged changes are collected by `@polydeukes/adapter-git`,
21
- translated into the covenant input IR, and dispatched through the very in-process judges the
22
- session hook calls — one judge, every surface. `--worktree` and `--range <base>..<head>` run the same
23
- judgment over the working tree or a ref range as a diagnostic call, with no witness prompt.
24
- Declarations that read the session (`precedent` and the other history mechanisms) assemble
25
- here like any other, but with no session to read their `supply: pass` takes over: when one
26
- matches a staged change it records a `skipped` event carrying its id and that change, and the
27
- commit proceeds. Judging them would block every matching commit with no legitimate pass path;
28
- filtering them out would hide that a gate stood down. It is the same disposition the session
29
- surface uses when it has no transcript. An empty staging area is an explicit pass; a missing or
30
- invalid config fails closed.
31
- - **`pdks explain`** — the assembly reader. It assembles both surfaces' registration sets through
32
- the same functions the two runners call and prints them without judging: every registration
33
- with its kind (`meta` / `judge` / `skip` / `excluded`), the routing scope of each entry, whether
34
- it carries a `why`, and for each skip the compiler's reason — the one that otherwise reaches
35
- stderr only when the cause is a config fault. No judge thunk is called and no telemetry row is
36
- written. A config that cannot be loaded fails at exit `2` with stdout at zero bytes.
37
- - **`pdks init claude-code`** — the Claude Code session-surface installer. It proves `polydeukes` resolves
38
- from the target project before writing anything, then creates what every distribution path
39
- shares (the data config and its `.polydeukes/` ignore line) and what this path owns (a delegator
40
- hook, its `.claude/settings.json` registration merged into whatever that file already carries,
41
- and a scoped discipline file pointing an AI partner at `pdks docs`). Nothing existing is
42
- overwritten: an artifact already there is reported and left alone, so a re-run is a no-op and a
43
- consumer's edits survive. The generated config carries the resolution paths on its protection
44
- list and a witness block — without the valve the first block would freeze the project, since the
45
- hook it just registered is itself protected. Two coexisting config spellings, an unparseable
46
- settings file, and a package that cannot be resolved are all precondition failures: each leaves
47
- zero files rather than a half-wired tree.
48
- - **`pdks init grok`** — the Grok session-surface installer. Same preflight and shared scaffold;
49
- this path owns `.grok/hooks/` (JSON registration with timeout 60, and a delegator file only when
50
- no Claude delegator is on disk). If the Claude hook file already exists, the JSON command points
51
- at it so two judges are not spawned. A later run of either installer retargets an
52
- installer-generated grok-mjs command the same way, and the JSON matcher follows the
53
- `.claude/settings.json` entry for that command — Grok collapses two registrations only when
54
- command and matcher both match. An already-open Grok session keeps the hook snapshot from
55
- start. The witness valve does not open on Grok.
56
- - **`pdks docs [topic]`** — the offline documentation reader. The English guides and the reference
57
- layer are copied into `dist/docs` at build time, so a consumer's AI partner reads the
58
- documentation that shipped with the code doing the judging instead of whichever release a search
59
- engine indexed. With no argument it lists the five topics — that listing is how an agent
60
- discovers what it may ask at all; with one it returns that topic's section verbatim plus the
61
- reference to read next. The query domain is those five names and nothing else: an unknown topic,
62
- a bundled document that is missing, and a heading a document no longer carries each name what
63
- was missing on stderr and exit 2, leaving stdout at zero bytes. A partially written answer would
64
- be read as the document and quoted onward, so no path produces one.
65
- - **The commit-surface witness valve** — at the `block` level (the default), when a staged change
66
- actually breaks a covenant, the runner prompts once on `/dev/tty` for the full witness token (a
67
- substring is refused), naming the broken registration, the matched entry, and the commit-wide
68
- reach of the one answer. A clean commit never prompts. No TTY — CI, an agent-spawned
69
- `git commit` — means no prompt and no way through: the valve is reachable only by a human at a
70
- terminal, and nothing is ever persisted. Every witnessed pass is measured as `witnessed`, never
71
- silent.
72
- - **The enforcement level** — the git adapter's namespace setting
73
- `adapters.git.enforce: block | advise` selects what a commit-surface verdict does. Under
74
- `advise` the valve is structurally absent: a verdict is recorded as an `advised` event, one
75
- advisory line lands on stderr, and the commit proceeds — a backstop that measures instead of
76
- blocking. Only the verdict is relaxed: a run that cannot judge (missing or invalid config, an
77
- unresolvable judge body) fails closed at exit 2 at either level.
78
-
79
- ## The wider map
80
-
81
- | Module | Role |
82
- |---|---|
83
- | `@polydeukes/core` | Covenant protocol, config schema, ROI telemetry, transcript seam |
84
- | `@polydeukes/covenant` | Dispatcher, judge bodies, Bash analysis, discipline library |
85
- | `@polydeukes/adapter-claude-code` | Session surface — PreToolUse payloads → covenant input IR |
86
- | `@polydeukes/adapter-git` | Commit surface — staged diffs → covenant input IR |
87
- | `@polydeukes/ledger` · `@polydeukes/memory` · `@polydeukes/verify` | Blueprint stage |
88
-
89
- See the [project repository](https://github.com/huskyhoochu/polydeukes) for the architecture
90
- blueprint and design rationale.
91
-
92
- ## License
93
-
94
- MIT
1
+ # `polydeukes`
2
+
3
+ **English** · [한국어](./README.ko.md)
4
+
5
+ Polydeukes is the umbrella package. Install this package; it ships the `pdks` bin, the config
6
+ loader, the commit-surface runner, the session-surface runner subpath, and the bundled schema
7
+ artifact.
8
+
9
+ <a id="overview"></a>
10
+ ## Overview
11
+
12
+ Public contract symbols and entry points:
13
+
14
+ - `loadConfig`
15
+ - `runCovenantCheck`
16
+ - `ResolvedConfig`
17
+ - `polydeukes/claude-code` → `runClaudeCodeHook`
18
+ - `polydeukes/schema.json`
19
+ - `pdks covenant check`
20
+ - `pdks init claude-code`
21
+ - `pdks init grok`
22
+ - `pdks explain`
23
+ - `pdks docs [topic]`
24
+
25
+ <a id="public-symbols"></a>
26
+ ## Public symbols
27
+
28
+ ```ts
29
+ import { loadConfig, runCovenantCheck } from 'polydeukes';
30
+ import { runClaudeCodeHook } from 'polydeukes/claude-code';
31
+ ```
32
+
33
+ ```ts
34
+ function loadConfig(spec: { rootDir: string }): {
35
+ config: import('@polydeukes/core').ResolvedConfig;
36
+ configPath: string;
37
+ };
38
+
39
+ function runCovenantCheck(spec: {
40
+ repoRoot: string;
41
+ telemetryPath?: string;
42
+ covenantDist?: string;
43
+ ttyPrompt?: (prompt: string) => string | null;
44
+ domain?: unknown;
45
+ }): Promise<{ exitCode: 0 | 2 }>;
46
+ ```
47
+
48
+ <a id="see-also"></a>
49
+ ## See also
50
+
51
+ - [`polydeukes` package reference](../../docs/reference/packages/polydeukes.md)
52
+ - [`Configuration reference`](../../docs/reference/configuration/index.md)
53
+ - [`pdks covenant check`](../../docs/reference/cli/covenant-check.md)
54
+ - [`pdks init`](../../docs/reference/cli/init.md)
55
+ - [`pdks explain`](../../docs/reference/cli/explain.md)
package/dist/bin.js CHANGED
@@ -11,7 +11,7 @@
11
11
  * CI or by an agent-spawned shell — no controlling terminal), the seam stays absent and
12
12
  * the witness valve is structurally unreachable, so only a human at a terminal can arm it.
13
13
  */
14
- import { closeSync, openSync, readSync, writeSync } from 'node:fs';
14
+ import { closeSync, openSync, readFileSync, readSync, writeSync } from 'node:fs';
15
15
  import { dirname, join } from 'node:path';
16
16
  import { fileURLToPath } from 'node:url';
17
17
  /**
@@ -105,15 +105,18 @@ if (args.length === 2 && args[0] === 'init' && args[1] === 'grok') {
105
105
  process.exit(2);
106
106
  }
107
107
  }
108
- if (args[0] === 'docs' && args.length <= 2) {
108
+ if (args[0] === 'docs') {
109
109
  try {
110
110
  // Imported inside the try for the same reason `init` is: the query core and the
111
111
  // markdown behind it have no business on `covenant check`'s load path.
112
- const { queryDocs } = await import('./docs-query.js');
112
+ const { runDocs } = await import('./docs-library.js');
113
113
  // The bundle ships beside this file, so the docs root comes from the module's own
114
114
  // location — never from the working directory, which is whatever shell invoked us.
115
115
  const docsRoot = join(dirname(fileURLToPath(import.meta.url)), 'docs');
116
- const { text } = queryDocs({ docsRoot, topic: args[1] });
116
+ const manifest = JSON.parse(readFileSync(join(docsRoot, '../../package.json'), 'utf8'));
117
+ if (typeof manifest.version !== 'string')
118
+ throw new Error('missing package version');
119
+ const { text } = runDocs({ docsRoot, args: args.slice(1), version: manifest.version });
117
120
  await emitAndExit(text);
118
121
  }
119
122
  catch (error) {
@@ -166,7 +169,7 @@ function parseCheckDomain(flags) {
166
169
  }
167
170
  const domain = args[0] === 'covenant' && args[1] === 'check' ? parseCheckDomain(args.slice(2)) : null;
168
171
  if (domain === null) {
169
- process.stderr.write('usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain | pdks init claude-code | pdks init grok | pdks docs [topic]\n');
172
+ process.stderr.write('usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain | pdks init claude-code | pdks init grok | pdks docs [topic | search <query> | show <document-id>]\n');
170
173
  process.exit(2);
171
174
  }
172
175
  try {
package/dist/docs/README.ko.md ADDED
@@ -0,0 +1,60 @@
1
+ # 폴리데우케스 문서
2
+
3
+ [English](./README.md) · **한국어**
4
+
5
+ > AI 코딩 파트너와 함께 개발하기 위한 규율 프레임워크입니다. 궁금한 곳부터 읽으십시오.
6
+
7
+ <a id="start-here"></a>
8
+ ## 여기서 시작하십시오
9
+
10
+ | 하려는 것 | 읽을 문서 |
11
+ |---|---|
12
+ | 첫 눈에 보이는 판정을 보고 싶다 | [첫 판정](./tutorials/first-judgment.ko.md) — 설치하고 Claude Code를 배선한 뒤 보호된 편집이 판정되는 모습을 봅니다 |
13
+ | Claude Code, Grok, git을 연결하고 싶다 | [표면 연결하기](./how-to/connect-surfaces.ko.md) — 세션과 커밋 배선, Grok 포함 |
14
+ | 프로젝트 설정을 다듬고 싶다 | [프로젝트 설정하기](./how-to/configure-project.ko.md) — 발견, IDE 지원, advise와 block의 선택 |
15
+ | 실제 규율을 쓰고 싶다 | [규율 작성하기](./how-to/write-disciplines.ko.md) — 실전 선언 예제, 특히 locale key pairing |
16
+ | 차단이나 건너뜀에서 회복하고 싶다 | [문제 해결](./troubleshooting.ko.md) — fail-closed 상태, 증인 밸브, 로그 |
17
+ | 이 프레임워크가 왜 있는지 알고 싶다 | [왜 폴리데우케스인가?](./why-polydeukes.ko.md) — 설계 백서 |
18
+ | 이 문서에 기여하고 싶다 | [문서에 기여하기](./contributing.ko.md) — 영한 쌍, 안정 ID, 카탈로그, 검사 |
19
+
20
+ <a id="reference"></a>
21
+ ## 레퍼런스
22
+
23
+ 설정 키, 하위 명령, 종료 코드를 설명합니다. 계획이 아니라 현재 동작을 기준으로 서술합니다.
24
+
25
+ | 문서 | 답하는 것 |
26
+ |---|---|
27
+ | [설정 레퍼런스](./reference/configuration/index.ko.md) | `polydeukes.config.yaml`에 무엇을 넣을 수 있고 각 키가 무엇을 하는지 |
28
+ | [`polydeukes` (`pdks` CLI)](./reference/packages/polydeukes.ko.md) | 패키지 계약. 서브커맨드는 [`reference/cli/`](./reference/cli/covenant-check.ko.md) |
29
+ | [`@polydeukes/core`](./reference/packages/core.ko.md) | 프로토콜, 입력 IR, 설정 스키마, 텔레메트리 |
30
+ | [`@polydeukes/covenant`](./reference/packages/covenant.ko.md) | 판정기입니다. 디스패처와 규율 라이브러리, 메타 약속, 밸브 |
31
+ | [`@polydeukes/adapter-claude-code`](./reference/packages/adapter-claude-code.ko.md) | 세션 표면입니다. 훅 페이로드에서 입력 IR로 |
32
+ | [`@polydeukes/adapter-git`](./reference/packages/adapter-git.ko.md) | 커밋 표면입니다. 스테이징·작업 트리·범위 diff에서 입력 IR로 |
33
+
34
+ <a id="shape-of-the-thing"></a>
35
+ ## 한 페이지로 보는 구조
36
+
37
+ 폴리데우케스는 개발자나 AI 에이전트가 하려는 일을 판정하고 결과를 기록합니다.
38
+ 기본값으로는 작업을 차단하지 않습니다. 설계의 바탕은 다음 세 가지입니다.
39
+
40
+ **약속은 가두기 위한 울타리가 아닙니다.** 여기서 확인하는 규율은 개발자가 이미 스스로 지켜 온 것들입니다. AI에게만큼 사람에게도 똑같이 적용되고, 프레임워크를 만든
41
+ 사람도 매일 그 판정을 받습니다.
42
+
43
+ **판정과 차단은 별개의 결정입니다.** 선언된 규율은 적용 범위에 해당하는 호출마다 판정합니다.
44
+ 위반했을 때 호출을 차단할지는 별도로 정합니다. 기본값으로는 사유를 기록하고 호출을 계속합니다.
45
+ 작성자는 `enforce: block`으로 차단을 선택할 수 있습니다. 별도 선택 없이 차단하는 것은
46
+ 프레임워크 자체를 보호하는 경우뿐입니다.
47
+
48
+ **모든 판정은 행 하나를 남깁니다.** `.polydeukes/roi.log`가 판정 결과마다 한 줄씩, 낱말 여섯 개짜리 어휘로 담습니다. 이 프로젝트가 자기 결함을 찾는
49
+ 방법이 그 기록입니다. 백서에 적힌 결함들도 전부 코드를 읽어서가 아니라 행을 세어서 나왔습니다.
50
+
51
+ <a id="two-surfaces"></a>
52
+ ## 두 표면
53
+
54
+ | 표면 | 판정 대상 | 배선 방법 | 대상 |
55
+ |---|---|---|---|
56
+ | **세션** | 도구 호출, 실행되기 전에 | `pdks init claude-code` 또는 `pdks init grok` | AI 파트너와 함께 개발하는 프로젝트 |
57
+ | **커밋** | diff — 스테이징 영역, 작업 트리, ref 범위 | pre-commit 훅, 또는 필요할 때 직접 실행 | 혼자 개발하는 사람, 그리고 CI |
58
+
59
+ 커밋 판정기는 필요할 때 직접 실행할 수도 있습니다. 작업 후에는 `pdks covenant check --worktree`,
60
+ PR 전에는 `--range`를 사용합니다. 같은 판정 기준으로 결과를 보고하며 증인 입력은 요청하지 않습니다.
package/dist/docs/README.md ADDED
@@ -0,0 +1,64 @@
1
+ # Polydeukes documentation
2
+
3
+ **English** · [한국어](./README.ko.md)
4
+
5
+ > A development discipline framework for building alongside an AI coding partner. Start where your
6
+ question is.
7
+
8
+ <a id="start-here"></a>
9
+ ## Start here
10
+
11
+ | If you want to | Read |
12
+ |---|---|
13
+ | Get to a first visible judgment | [First judgment](./tutorials/first-judgment.md) — install, wire Claude Code, and watch one protected edit get judged |
14
+ | Connect Claude Code, Grok, or git | [Connect the surfaces](./how-to/connect-surfaces.md) — session and commit setup, including Grok |
15
+ | Shape the project config | [Configure the project](./how-to/configure-project.md) — discovery, IDE support, and advise versus block |
16
+ | Write a real discipline | [Write disciplines](./how-to/write-disciplines.md) — worked declarations, especially locale key pairing |
17
+ | Recover from a block or skip | [Troubleshooting](./troubleshooting.md) — the fail-closed states, the witness valve, and the log |
18
+ | Understand why the framework exists | [Why Polydeukes?](./why-polydeukes.md) — the design whitepaper |
19
+ | Contribute to these docs | [Contributing](./contributing.md) — bilingual pairs, stable IDs, catalog, and checks |
20
+
21
+ <a id="reference"></a>
22
+ ## Reference
23
+
24
+ Every key, every subcommand, every exit code. These describe the present state only — nothing here
25
+ is aspirational.
26
+
27
+ | Document | Answers |
28
+ |---|---|
29
+ | [Configuration reference](./reference/configuration/index.md) | What may go in `polydeukes.config.yaml`, and what each key does |
30
+ | [`polydeukes` (the `pdks` CLI)](./reference/packages/polydeukes.md) | Package contract; subcommands live under [`reference/cli/`](./reference/cli/covenant-check.md) |
31
+ | [`@polydeukes/core`](./reference/packages/core.md) | The protocol, the input IR, the config schema, telemetry |
32
+ | [`@polydeukes/covenant`](./reference/packages/covenant.md) | The judge — dispatcher, discipline library, meta-covenants, the valve |
33
+ | [`@polydeukes/adapter-claude-code`](./reference/packages/adapter-claude-code.md) | Session surface — hook payloads become the input IR |
34
+ | [`@polydeukes/adapter-git`](./reference/packages/adapter-git.md) | Commit surface — staged, worktree, and range diffs become the input IR |
35
+
36
+ <a id="shape-of-the-thing"></a>
37
+ ## The shape of the thing, in one page
38
+
39
+ Polydeukes judges what a developer or an AI agent is about to do, records the verdict, and by
40
+ default lets the work proceed. Three ideas carry the rest.
41
+
42
+ **A covenant is a promise, not a fence.** The disciplines it enforces are the ones a good developer
43
+ already imposes on themselves. They bind the human exactly as much as the AI, and the framework's
44
+ own authors get judged by them daily.
45
+
46
+ **Judging and stopping are separate decisions.** Every declared discipline is judged on every
47
+ matching call. What a break then does is a second question: by default it is recorded with its
48
+ reason and the call continues. `enforce: block` is a promotion the author chooses. The only things
49
+ that stop a call unasked are the framework's own protections.
50
+
51
+ **Every judgment leaves a row.** `.polydeukes/roi.log` holds one line per verdict, in a vocabulary
52
+ of six words. That record is how this project finds its own defects — including the ones described
53
+ in the whitepaper, which were all found by counting rows rather than by reading code.
54
+
55
+ <a id="two-surfaces"></a>
56
+ ## Two surfaces
57
+
58
+ | Surface | Judges | Wired by | For |
59
+ |---|---|---|---|
60
+ | **Session** | A tool call, before it runs | `pdks init claude-code` or `pdks init grok` | A project developed with an AI partner |
61
+ | **Commit** | A diff — staged, the working tree, or a ref range | A pre-commit hook, or run on demand | A human developing alone, and CI |
62
+
63
+ The commit judge also answers on demand: `pdks covenant check --worktree` after a task, `--range`
64
+ before a PR. Same verdict a commit would receive, delivered as a report with no prompt and no gate.