polydeukes 0.5.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 (79) hide show
  1. package/README.ko.md +54 -74
  2. package/README.md +55 -86
  3. package/dist/baseline.d.ts +82 -0
  4. package/dist/baseline.js +166 -0
  5. package/dist/bin.d.ts +1 -1
  6. package/dist/bin.js +26 -6
  7. package/dist/claude-code-hook.d.ts +7 -5
  8. package/dist/claude-code-hook.js +69 -17
  9. package/dist/claude-code.d.ts +6 -0
  10. package/dist/claude-code.js +6 -0
  11. package/dist/covenant-check.d.ts +10 -17
  12. package/dist/covenant-check.js +44 -12
  13. package/dist/covenant-module.d.ts +2 -2
  14. package/dist/covenant-module.js +9 -1
  15. package/dist/docs/README.ko.md +60 -0
  16. package/dist/docs/README.md +64 -0
  17. package/dist/docs/catalog.json +464 -0
  18. package/dist/docs/concepts/judgment.ko.md +113 -0
  19. package/dist/docs/concepts/judgment.md +113 -0
  20. package/dist/docs/how-to/configure-project.ko.md +99 -0
  21. package/dist/docs/how-to/configure-project.md +95 -0
  22. package/dist/docs/how-to/connect-surfaces.ko.md +115 -0
  23. package/dist/docs/how-to/connect-surfaces.md +118 -0
  24. package/dist/docs/how-to/write-disciplines.ko.md +124 -0
  25. package/dist/docs/how-to/write-disciplines.md +125 -0
  26. package/dist/docs/index.json +2046 -0
  27. package/dist/docs/reference/cli/covenant-check.ko.md +101 -0
  28. package/dist/docs/reference/cli/covenant-check.md +98 -0
  29. package/dist/docs/reference/cli/docs.ko.md +97 -0
  30. package/dist/docs/reference/cli/docs.md +95 -0
  31. package/dist/docs/reference/cli/explain.ko.md +79 -0
  32. package/dist/docs/reference/cli/explain.md +84 -0
  33. package/dist/docs/reference/cli/init.ko.md +119 -0
  34. package/dist/docs/reference/cli/init.md +131 -0
  35. package/dist/docs/reference/configuration/index.ko.md +448 -0
  36. package/dist/docs/reference/configuration/index.md +474 -0
  37. package/dist/docs/reference/packages/adapter-claude-code.ko.md +83 -0
  38. package/dist/docs/reference/{adapter-claude-code.md → packages/adapter-claude-code.md} +16 -10
  39. package/dist/docs/reference/packages/adapter-git.ko.md +101 -0
  40. package/dist/docs/reference/{adapter-git.md → packages/adapter-git.md} +25 -15
  41. package/dist/docs/reference/packages/core.ko.md +128 -0
  42. package/dist/docs/reference/{core.md → packages/core.md} +32 -13
  43. package/dist/docs/reference/packages/covenant.ko.md +115 -0
  44. package/dist/docs/reference/{covenant.md → packages/covenant.md} +41 -26
  45. package/dist/docs/reference/packages/polydeukes.ko.md +134 -0
  46. package/dist/docs/reference/packages/polydeukes.md +139 -0
  47. package/dist/docs/troubleshooting.ko.md +142 -0
  48. package/dist/docs/troubleshooting.md +97 -122
  49. package/dist/docs/tutorials/first-judgment.ko.md +82 -0
  50. package/dist/docs/tutorials/first-judgment.md +81 -0
  51. package/dist/docs-catalog.d.ts +25 -0
  52. package/dist/docs-catalog.js +450 -0
  53. package/dist/docs-library.d.ts +23 -0
  54. package/dist/docs-library.js +347 -0
  55. package/dist/docs-markdown.d.ts +32 -0
  56. package/dist/docs-markdown.js +150 -0
  57. package/dist/docs-query.d.ts +11 -40
  58. package/dist/docs-query.js +28 -122
  59. package/dist/docs-types.d.ts +105 -0
  60. package/dist/docs-types.js +2 -0
  61. package/dist/explain.d.ts +3 -5
  62. package/dist/explain.js +48 -47
  63. package/dist/index.d.ts +2 -3
  64. package/dist/index.js +1 -2
  65. package/dist/init-claude-code.d.ts +5 -3
  66. package/dist/init-claude-code.js +226 -63
  67. package/dist/init-grok.d.ts +51 -0
  68. package/dist/init-grok.js +242 -0
  69. package/dist/load-config.d.ts +5 -1
  70. package/dist/load-config.js +2 -1
  71. package/dist/pre-state-reader.d.ts +22 -0
  72. package/dist/pre-state-reader.js +32 -0
  73. package/dist/scaffold-project.js +48 -8
  74. package/dist/schema/polydeukes.schema.json +38 -91
  75. package/package.json +7 -7
  76. package/dist/docs/configuration.md +0 -103
  77. package/dist/docs/installation.md +0 -212
  78. package/dist/docs/reference/configuration.md +0 -338
  79. package/dist/docs/reference/polydeukes.md +0 -287
package/dist/docs/reference/polydeukes.md DELETED
@@ -1,287 +0,0 @@
1
- # `polydeukes` — the umbrella
2
-
3
- **English** · [한국어](./polydeukes.ko.md)
4
-
5
- > Alpha. Everything below is read from the shipped package — the `pdks` bin, the barrel, and
6
- > the exports map. For the procedures that use these, see [installation](../installation.md)
7
- > and [troubleshooting](../troubleshooting.md).
8
-
9
- The umbrella is the only package you install. It carries the core, the judge, and both
10
- adapters as its own dependencies, and it is the only package allowed to assemble them —
11
- every other dependency in this repository runs one way, through the core alone. That makes
12
- this page the consumer-facing surface: the four scoped packages are transitive dependencies
13
- you do not install and do not import.
14
-
15
- | Package | Reference | Owns |
16
- |---|---|---|
17
- | `@polydeukes/core` | [core](./core.md) | The protocol, the config schema, telemetry |
18
- | `@polydeukes/covenant` | [covenant](./covenant.md) | The judge — dispatcher, disciplines, meta-covenants, the valve |
19
- | `@polydeukes/adapter-claude-code` | [adapter-claude-code](./adapter-claude-code.md) | Session surface — PreToolUse payloads → input IR |
20
- | `@polydeukes/adapter-git` | [adapter-git](./adapter-git.md) | Commit surface — staged diffs → input IR |
21
-
22
- ## Subcommands
23
-
24
- The bin is `pdks`, with `polydeukes` as an alias. Every argument form is matched against a
25
- finite table: `covenant check` takes an optional domain flag, `init claude-code` is exact,
26
- `explain` takes one word, and `docs` takes an optional topic.
27
-
28
- ### `pdks covenant check`
29
-
30
- `pdks covenant check [--worktree | --range <base>..<head>]` — the commit-surface judgment
31
- runner. It discovers the config at the working directory,
32
- collects one observation of the repository through the git adapter, translates it into the
33
- covenant input IR, and dispatches it through the same in-process judges the session hook calls.
34
- Which observation is the domain flag's choice — the same violation receives the same verdict
35
- in all three:
36
-
37
- | Form | Domain | `pre` → `post` |
38
- |---|---|---|
39
- | `pdks covenant check` | The staging area — what a pre-commit hook judges | HEAD blob → staged blob |
40
- | `pdks covenant check --worktree` | The working tree, untracked (non-ignored) files included | HEAD blob → bytes on disk |
41
- | `pdks covenant check --range <base>..<head>` | Two refs; `<base>...<head>` reads from their merge-base, the PR reading | base blob → head blob |
42
-
43
- `--worktree` and `--range` are diagnostic calls — run them after a task, before a PR, or in
44
- CI. Only the staged form is a gate, so only it can prompt for the witness token; the other
45
- two report exit `2` without a prompt, since there is no commit for a human to open.
46
-
47
- | Situation | Result |
48
- |---|---|
49
- | The domain's changes break nothing | exit `0` |
50
- | A staged change breaks a covenant, `enforce: block`, config has a `witness` block | Prompts once on `/dev/tty` for the witness token; an unanswered or wrong answer exits `2` |
51
- | The same, with no `witness` block in the config | exit `2` with no prompt — the valve is built from that block, so without it nothing can open a block |
52
- | A worktree or range change breaks a covenant, `enforce: block` | exit `2`, never a prompt |
53
- | A change breaks a covenant, `enforce: advise` | One advisory line on stderr, exit `0`, recorded `advised` |
54
- | Empty domain (nothing staged, a clean tree, identical refs) | exit `0` — an explicit pass, not a skipped run |
55
- | A range naming a ref git cannot resolve, or two refs with no merge-base | exit `2`, one `blocked` row |
56
- | `--range` without an argument, an argument without `..`, both flags at once, or an unknown flag | The usage line on stderr, exit `2` |
57
- | No config, more than one config, or an invalid one | exit `2` |
58
- | A judge body that cannot be loaded | exit `2` |
59
-
60
- Context-family disciplines (`requirePrecedent`) assemble here like any other entry, but this
61
- surface has no session to read: a match records `skipped` and the commit proceeds. That is a
62
- permanent condition of the commit surface, not a fault.
63
-
64
- ### `pdks init claude-code`
65
-
66
- The session-surface installer. It proves that `polydeukes` resolves from the directory it
67
- was invoked in **before writing anything**, then creates six artifacts:
68
-
69
- | Artifact | Kind |
70
- |---|---|
71
- | `.claude/hooks/covenant-pretooluse.mjs` | Created — a delegator that loads the judge from the installed package |
72
- | `.claude/settings.json` | Merged — the PreToolUse registration is added to whatever the file already carries |
73
- | `polydeukes.config.yaml` | Created — the starter policy, with a placeholder `languages` block |
74
- | `.claude/rules/polydeukes.md` | Created — tells the AI partner to ask [`pdks docs`](#pdks-docs-topic) instead of searching the web |
75
- | `.claude/skills/discipline-draft/SKILL.md` | Created — the classification procedure: a described problem becomes a config entry (judged at advise, or `draft: true`), and advised rows are consulted in the telemetry log |
76
- | `.gitignore` | Appended — one line for `.polydeukes/` |
77
-
78
- Nothing existing is overwritten: an artifact already present is reported as skipped and left
79
- alone, so a re-run is a no-op. A precondition failure — the package not resolving, two
80
- coexisting config spellings, an unparseable settings file — writes zero files and exits `2`,
81
- never a half-wired tree.
82
-
83
- ### `pdks docs [topic]`
84
-
85
- The offline documentation reader. The guides and this reference layer ship inside the
86
- package, so the answer comes from the installed version rather than from the network.
87
-
88
- | Call | Result |
89
- |---|---|
90
- | `pdks docs` | The topic list on stdout, exit `0` |
91
- | `pdks docs <topic>` | That topic's section, followed by a `See also:` line, exit `0` |
92
- | `pdks docs <unknown>` | The known topics named on stderr, exit `2` |
93
- | `pdks docs a b` | The usage line on stderr, exit `2` |
94
-
95
- | Topic | Answers from |
96
- |---|---|
97
- | `install` | [installation](../installation.md), in full |
98
- | `config` | [the configuration reference](./configuration.md), in full |
99
- | `discipline` | [the configuration reference](./configuration.md) — the `disciplines` section |
100
- | `covenant` | [configuration](../configuration.md) — What enforcement looks like |
101
- | `witness` | [the configuration reference](./configuration.md)'s `witness` section, then [troubleshooting](../troubleshooting.md)'s valve section |
102
-
103
- **Every failure leaves stdout at zero bytes.** A missing bundled document, a heading the
104
- document no longer carries, an unknown topic — each names what was missing on stderr and
105
- exits `2`. A partially written answer is one an agent reads as the document and quotes
106
- onward, so there is no such state.
107
-
108
- The bundle carries the English text only. Answers are returned verbatim, so the
109
- `[한국어](./X.ko.md)` link at the top of each document points at a mirror that lives in the
110
- [repository](https://github.com/huskyhoochu/polydeukes/tree/main/docs) rather than inside
111
- the package.
112
-
113
- `pdks init claude-code` writes a discovery file that points an AI partner at this
114
- subcommand; see the artifact table above.
115
-
116
- ### `pdks explain`
117
-
118
- The assembly reader. It loads the config at the working directory, assembles both surfaces'
119
- registration sets through the same functions the two judgment runners use, and prints them
120
- without judging — no judge thunk is called, no telemetry row is written, no transcript is
121
- read.
122
-
123
- ```text
124
- pdks explain — polydeukes.config.yaml
125
-
126
- surface: session (claude-code hook)
127
- registrations 23 · judged 11 · skip 9 · meta 3 · excluded 0 · draft 1
128
- meta self-mod paths 13 (common; includes the config file itself)
129
- judge covenant-vocabulary forbid · in packages/*/src/** · except … · why ✓
130
- skip covenant-vocabulary a shell write in scope whose result this layer cannot compute
131
- draft bilingual-docs-sync unpromoted — no judgment
132
- ...
133
- surface: commit (git pre-commit) · enforce: advise
134
- registrations 10 · judged 3 · skip 6 · meta 1 · excluded 3 · draft 1
135
- skip manifest-needs-npm-view no session transcript to read
136
- excluded hooks-stay-armed forbidCommand — no shell axis on this surface
137
- draft bilingual-docs-sync unpromoted — no judgment
138
- ```
139
-
140
- One line per registration, in the order the surface dispatches them. The kind column has
141
- five words: `meta` (the registrations protecting the judging chain — `self-mod`,
142
- `shell-mod`, and on the session surface `transcript-mod`), `judge` (an entry with a judge
143
- body, with its family, routing scope, and whether it carries a `why`), `skip` (a registration
144
- that records `skipped` instead of judging, with the reason the compiler gave — the reason
145
- that otherwise reaches stderr only on a config fault), `excluded` (a `forbidCommand`
146
- entry on the commit surface, which has no shell axis), and `draft` (an unpromoted
147
- `draft: true` entry, shown on both surfaces since it belongs to neither). `registrations`
148
- counts the first three; `excluded` and `draft` are tallied apart because neither ever
149
- becomes a registration.
150
- The commit surface's header also names its `adapters.git.enforce` level, since an advising
151
- surface records the same table but blocks nothing.
152
-
153
- The session surface is rendered as the hook sees it under a normal payload — with a
154
- transcript present — so `transcript-mod` and the context family appear as they do in a
155
- session; the commit surface shows the context family as skips, which is that surface's
156
- permanent condition.
157
-
158
- | Call | Result |
159
- |---|---|
160
- | `pdks explain` | Both surfaces on stdout, exit `0` |
161
- | `pdks explain <anything>` | The usage line on stderr, exit `2` |
162
- | no config, two configs, or an invalid one | `pdks explain: <reason>` on stderr, stdout at zero bytes, exit `2` |
163
-
164
- ### Any other argument form
165
-
166
- Anything that is not one of these forms writes the usage line —
167
- `usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain |
168
- pdks init claude-code | pdks docs [topic]` — to stderr and exits `2`.
169
-
170
- ## Exit codes
171
-
172
- Three codes exist, and they live at two layers. **What a consumer's hook observes is only
173
- `0` or `2`** — both composition roots return `Promise<{ exitCode: 0 | 2 }>`.
174
-
175
- | Code | Constant | Emitted by | Means |
176
- |---|---|---|---|
177
- | `0` | `EXIT_UPHOLD` | Judge outcome, wrapper, bin | The promise was upheld — the call or commit proceeds |
178
- | `1` | `EXIT_BREAK_NON_BLOCKING` | Judge outcome only | A break reported as a signal. The wrapper translates it — into `2` under `enforce: block`, into `0` + an `advised` row under `advise`. It never reaches the surface either way |
179
- | `2` | `EXIT_BREAK_BLOCKING` | Wrapper, bin, fail-closed paths | The call or commit is refused |
180
-
181
- The asymmetry is the protocol's responsibility boundary. A judge decides *whether* a
182
- promise was broken and answers `0` or `1` in its outcome; deciding what a break *costs* belongs
183
- to the wrapper, and that is the one place `enforce` is read. A judge can therefore be run,
184
- tested, and reasoned about without knowing whether the surface it runs under blocks or advises.
185
- Only the verdict relaxes: every unjudgeable outcome — an outcome of `2` or higher, a throw
186
- from the judge — stays `2` at either level.
187
-
188
- **Everything unjudgeable resolves to `2`.** A missing config, an invalid one, an
189
- unparseable payload, a judge body that was never built — each fails closed. The one
190
- direction that stays open is measurement: a telemetry write that fails never changes a
191
- verdict.
192
-
193
- ## Programmatic surface
194
-
195
- The barrel (`import … from 'polydeukes'`) exports six symbols plus one re-exported type.
196
- This is the whole public API; the scoped packages are not part of it.
197
-
198
- ### `loadConfig`
199
-
200
- **Type signature:**
201
-
202
- ```ts
203
- function loadConfig(rootDir: string): LoadedConfig;
204
-
205
- type LoadedConfig = {
206
- config: ResolvedConfig; // protectedPaths already includes the config file itself
207
- configPath: string; // rootDir-relative path of the discovered file
208
- };
209
- ```
210
-
211
- Discovers exactly one `polydeukes.config` file (`.yaml`, `.yml`, or `.json`) directly under
212
- `rootDir`. **Every failure branch throws** — none found, more than one found, a parse error,
213
- a schema violation. There are no silent defaults, because a silently defaulted config means
214
- a silently unprotected project.
215
-
216
- ### `runCovenantCheck`
217
-
218
- **Type signature:**
219
-
220
- ```ts
221
- function runCovenantCheck(spec: CovenantCheckSpec): Promise<{ exitCode: 0 | 2 }>;
222
-
223
- type CovenantCheckSpec = {
224
- repoRoot: string; // config discovery and collection anchor here
225
- telemetryPath?: string; // overrides the config's log path
226
- covenantDist?: string; // overrides the resolved judge directory
227
- ttyPrompt?: (prompt: string) => string | null; // the TTY valve seam
228
- domain?: CheckDomain; // which observation to judge; absent = staged
229
- };
230
-
231
- type CheckDomain =
232
- | { kind: 'staged' }
233
- | { kind: 'worktree' }
234
- | { kind: 'range'; base: string; head: string; ancestry?: 'merge-base' };
235
- ```
236
-
237
- The commit surface's composition root — what [`pdks covenant
238
- check`](#pdks-covenant-check) runs. `ancestry: 'merge-base'` is the `<base>...<head>`
239
- reading; the adapter resolves the merge-base.
240
-
241
- `ttyPrompt` absent means a non-TTY environment, and the valve then has no way to open — an
242
- agent-spawned commit and a CI run reach the same state. The valve is a human at a terminal
243
- or nothing.
244
-
245
- ### `runClaudeCodeHook`
246
-
247
- **Type signature:**
248
-
249
- ```ts
250
- function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<{ exitCode: 0 | 2 }>;
251
-
252
- type ClaudeCodeHookSpec = {
253
- repoRoot: string; // config discovery and discipline glob scoping anchor here
254
- rawPayload?: string; // absent means read fd 0 — the hook's real stdin
255
- telemetryPath?: string;
256
- covenantDist?: string;
257
- };
258
- ```
259
-
260
- The session surface's composition root — what the generated hook delegator calls. Reach it
261
- through the [`polydeukes/claude-code`](#subpaths) subpath rather than the barrel.
262
-
263
- **Neither composition root throws.** An uncaught rejection would exit the delegator
264
- non-blocking, which is the cheapest bypass there is, so both resolve their failures into
265
- `{ exitCode: 2 }` with a telemetry record instead.
266
-
267
- ### `ResolvedConfig`
268
-
269
- Re-exported from [`@polydeukes/core`](./core.md) so a consumer reading `loadConfig`'s result
270
- needs no second dependency.
271
-
272
- ## Subpaths
273
-
274
- | Specifier | Carries |
275
- |---|---|
276
- | `polydeukes` | The barrel — `loadConfig`, `runCovenantCheck`, `runClaudeCodeHook`, their spec types, `ResolvedConfig` |
277
- | `polydeukes/claude-code` | `runClaudeCodeHook` and `ClaudeCodeHookSpec` alone |
278
- | `polydeukes/schema.json` | The config JSON Schema, copied from the core at build time |
279
-
280
- The generated hook delegator imports the subpath, not the barrel. ESM imports are eager, so
281
- importing the barrel would load the commit-surface runner — and the git adapter behind it —
282
- on every session tool call that will never use them. The subpath is the session surface's
283
- own entry point, and the barrel is for programmatic consumers.
284
-
285
- `polydeukes/schema.json` is for code that reads the schema. A `$schema` line names the file
286
- path instead — an editor reads that string statically, so no module resolver runs on it. Both
287
- spellings are in [configuration.md's IDE section](../configuration.md#ide-support).