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
  1. package/README.ko.md +30 -70
  2. package/README.md +31 -84
  3. package/dist/baseline.d.ts +37 -1
  4. package/dist/baseline.js +68 -1
  5. package/dist/bin.d.ts +3 -4
  6. package/dist/bin.js +79 -93
  7. package/dist/covenant/bash-line.d.ts +130 -0
  8. package/dist/covenant/bash-line.js +566 -0
  9. package/dist/covenant/declaration-engine.d.ts +108 -0
  10. package/dist/covenant/declaration-engine.js +415 -0
  11. package/dist/covenant/discipline.d.ts +103 -0
  12. package/dist/covenant/discipline.js +667 -0
  13. package/dist/covenant/dispatch.d.ts +153 -0
  14. package/dist/covenant/dispatch.js +237 -0
  15. package/dist/covenant/extract-steps.d.ts +122 -0
  16. package/dist/covenant/extract-steps.js +0 -0
  17. package/dist/covenant/mention.d.ts +117 -0
  18. package/dist/covenant/mention.js +209 -0
  19. package/dist/covenant/module.d.ts +25 -0
  20. package/dist/covenant/module.js +23 -0
  21. package/dist/covenant/mutation-rules.d.ts +40 -0
  22. package/dist/covenant/mutation-rules.js +146 -0
  23. package/dist/covenant/relations.d.ts +46 -0
  24. package/dist/covenant/relations.js +68 -0
  25. package/dist/covenant/run-covenant.d.ts +95 -0
  26. package/dist/covenant/run-covenant.js +164 -0
  27. package/dist/covenant/self-mod.d.ts +55 -0
  28. package/dist/covenant/self-mod.js +84 -0
  29. package/dist/covenant/shell-evidence.d.ts +38 -0
  30. package/dist/covenant/shell-evidence.js +247 -0
  31. package/dist/covenant/shell-mod.d.ts +84 -0
  32. package/dist/covenant/shell-mod.js +213 -0
  33. package/dist/covenant/supply.d.ts +54 -0
  34. package/dist/covenant/supply.js +50 -0
  35. package/dist/covenant/transcript-mod.d.ts +60 -0
  36. package/dist/covenant/transcript-mod.js +254 -0
  37. package/dist/covenant/ttl-witness.d.ts +47 -0
  38. package/dist/covenant/ttl-witness.js +80 -0
  39. package/dist/covenant-check.d.ts +72 -39
  40. package/dist/covenant-check.js +260 -121
  41. package/dist/diff-ir.d.ts +28 -0
  42. package/dist/diff-ir.js +310 -0
  43. package/dist/docs/README.ko.md +60 -0
  44. package/dist/docs/README.md +64 -0
  45. package/dist/docs/catalog.json +480 -0
  46. package/dist/docs/concepts/judgment.ko.md +113 -0
  47. package/dist/docs/concepts/judgment.md +113 -0
  48. package/dist/docs/how-to/configure-project.ko.md +99 -0
  49. package/dist/docs/how-to/configure-project.md +98 -0
  50. package/dist/docs/how-to/connect-surfaces.ko.md +120 -0
  51. package/dist/docs/how-to/connect-surfaces.md +121 -0
  52. package/dist/docs/how-to/write-disciplines.ko.md +179 -0
  53. package/dist/docs/how-to/write-disciplines.md +181 -0
  54. package/dist/docs/index.json +2280 -0
  55. package/dist/docs/reference/cli/covenant-check.ko.md +148 -0
  56. package/dist/docs/reference/cli/covenant-check.md +153 -0
  57. package/dist/docs/reference/cli/docs.ko.md +97 -0
  58. package/dist/docs/reference/cli/docs.md +95 -0
  59. package/dist/docs/reference/cli/explain.ko.md +84 -0
  60. package/dist/docs/reference/cli/explain.md +89 -0
  61. package/dist/docs/reference/cli/init.ko.md +119 -0
  62. package/dist/docs/reference/cli/init.md +119 -0
  63. package/dist/docs/reference/configuration/index.ko.md +553 -0
  64. package/dist/docs/reference/{configuration.md → configuration/index.md} +215 -90
  65. package/dist/docs/reference/packages/adapter-claude-code.ko.md +110 -0
  66. package/dist/docs/reference/{adapter-claude-code.md → packages/adapter-claude-code.md} +47 -19
  67. package/dist/docs/reference/packages/adapter-grok.ko.md +77 -0
  68. package/dist/docs/reference/packages/adapter-grok.md +79 -0
  69. package/dist/docs/reference/packages/core.ko.md +174 -0
  70. package/dist/docs/reference/{core.md → packages/core.md} +74 -12
  71. package/dist/docs/reference/packages/polydeukes.ko.md +195 -0
  72. package/dist/docs/reference/packages/polydeukes.md +204 -0
  73. package/dist/docs/reference/packages/sdk-ts.ko.md +161 -0
  74. package/dist/docs/reference/packages/sdk-ts.md +164 -0
  75. package/dist/docs/troubleshooting.ko.md +144 -0
  76. package/dist/docs/troubleshooting.md +103 -151
  77. package/dist/docs/tutorials/first-judgment.ko.md +82 -0
  78. package/dist/docs/tutorials/first-judgment.md +81 -0
  79. package/dist/docs-catalog.d.ts +25 -0
  80. package/dist/docs-catalog.js +450 -0
  81. package/dist/docs-library.d.ts +23 -0
  82. package/dist/docs-library.js +347 -0
  83. package/dist/docs-markdown.d.ts +32 -0
  84. package/dist/docs-markdown.js +150 -0
  85. package/dist/docs-query.d.ts +11 -40
  86. package/dist/docs-query.js +28 -122
  87. package/dist/docs-types.d.ts +105 -0
  88. package/dist/docs-types.js +2 -0
  89. package/dist/explain.d.ts +1 -1
  90. package/dist/explain.js +37 -22
  91. package/dist/load-config.d.ts +1 -1
  92. package/dist/load-config.js +1 -1
  93. package/dist/pre-state-reader.d.ts +1 -1
  94. package/dist/pre-state-reader.js +1 -1
  95. package/dist/scaffold-project.d.ts +2 -2
  96. package/dist/scaffold-project.js +9 -3
  97. package/dist/schema/polydeukes.schema.json +12 -0
  98. package/dist/worktree-reader.d.ts +19 -0
  99. package/dist/worktree-reader.js +30 -0
  100. package/package.json +3 -17
  101. package/dist/claude-code-hook.d.ts +0 -79
  102. package/dist/claude-code-hook.js +0 -372
  103. package/dist/claude-code.d.ts +0 -6
  104. package/dist/claude-code.js +0 -6
  105. package/dist/covenant-module.d.ts +0 -25
  106. package/dist/covenant-module.js +0 -42
  107. package/dist/docs/configuration.md +0 -103
  108. package/dist/docs/installation.md +0 -241
  109. package/dist/docs/reference/adapter-git.md +0 -100
  110. package/dist/docs/reference/covenant.md +0 -116
  111. package/dist/docs/reference/polydeukes.md +0 -315
  112. package/dist/index.d.ts +0 -22
  113. package/dist/index.js +0 -21
  114. package/dist/init-claude-code.d.ts +0 -52
  115. package/dist/init-claude-code.js +0 -469
  116. package/dist/init-grok.d.ts +0 -51
  117. package/dist/init-grok.js +0 -242
package/dist/docs/reference/polydeukes.md DELETED
@@ -1,315 +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
- The judge and the two adapters take the core as a `peerDependency` rather than a dependency
16
- of their own, so they share one copy of the vocabulary instead of each carrying its own. The
17
- umbrella's ordinary dependency on the core is what satisfies that peer, which is why
18
- installing this one package is still all a consumer does.
19
-
20
- | Package | Reference | Owns |
21
- |---|---|---|
22
- | `@polydeukes/core` | [core](./core.md) | The protocol, the config schema, telemetry |
23
- | `@polydeukes/covenant` | [covenant](./covenant.md) | The judge — dispatcher, disciplines, meta-covenants, the valve |
24
- | `@polydeukes/adapter-claude-code` | [adapter-claude-code](./adapter-claude-code.md) | Session surface — PreToolUse payloads → input IR |
25
- | `@polydeukes/adapter-git` | [adapter-git](./adapter-git.md) | Commit surface — staged diffs → input IR |
26
-
27
- ## Subcommands
28
-
29
- The bin is `pdks`, with `polydeukes` as an alias. Every argument form is matched against a
30
- finite table: `covenant check` takes an optional domain flag, `init claude-code` and
31
- `init grok` are exact, `explain` takes one word, and `docs` takes an optional topic.
32
-
33
- ### `pdks covenant check`
34
-
35
- `pdks covenant check [--worktree | --range <base>..<head>]` — the commit-surface judgment
36
- runner. It discovers the config at the working directory,
37
- collects one observation of the repository through the git adapter, translates it into the
38
- covenant input IR, and dispatches it through the same in-process judges the session hook calls.
39
- Which observation is the domain flag's choice — the same violation receives the same verdict
40
- in all three:
41
-
42
- | Form | Domain | `pre` → `post` |
43
- |---|---|---|
44
- | `pdks covenant check` | The staging area — what a pre-commit hook judges | HEAD blob → staged blob |
45
- | `pdks covenant check --worktree` | The working tree, untracked (non-ignored) files included | HEAD blob → bytes on disk |
46
- | `pdks covenant check --range <base>..<head>` | Two refs; `<base>...<head>` reads from their merge-base, the PR reading | base blob → head blob |
47
-
48
- `--worktree` and `--range` are diagnostic calls — run them after a task, before a PR, or in
49
- CI. Only the staged form is a gate, so only it can prompt for the witness token; the other
50
- two report exit `2` without a prompt, since there is no commit for a human to open.
51
-
52
- | Situation | Result |
53
- |---|---|
54
- | The domain's changes break nothing | exit `0` |
55
- | 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` |
56
- | 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 |
57
- | A worktree or range change breaks a covenant, `enforce: block` | exit `2`, never a prompt |
58
- | A change breaks a covenant, `enforce: advise` | One advisory line on stderr, exit `0`, recorded `advised` |
59
- | Empty domain (nothing staged, a clean tree, identical refs) | exit `0` — an explicit pass, not a skipped run |
60
- | A range naming a ref git cannot resolve, or two refs with no merge-base | exit `2`, one `blocked` row |
61
- | `--range` without an argument, an argument without `..`, both flags at once, or an unknown flag | The usage line on stderr, exit `2` |
62
- | No config, more than one config, or an invalid one | exit `2` |
63
- | A judge body that cannot be loaded | exit `2` |
64
-
65
- Declarations that read the session (`precedent` and the other history mechanisms) assemble
66
- here like any other entry, but this surface has no session to read: a match records
67
- `skipped` and the commit proceeds. That is a permanent condition of the commit surface, not a
68
- fault.
69
-
70
- ### `pdks init claude-code`
71
-
72
- The session-surface installer. It proves that `polydeukes` resolves from the directory it
73
- was invoked in **before writing anything**, then creates six artifacts:
74
-
75
- | Artifact | Kind |
76
- |---|---|
77
- | `.claude/hooks/covenant-pretooluse.mjs` | Created — a delegator that loads the judge from the installed package |
78
- | `.claude/settings.json` | Merged — the PreToolUse registration is added to whatever the file already carries |
79
- | `polydeukes.config.yaml` | Created — the starter policy, with a placeholder `languages` block |
80
- | `.claude/rules/polydeukes.md` | Created — tells the AI partner to ask [`pdks docs`](#pdks-docs-topic) instead of searching the web |
81
- | `.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 |
82
- | `.gitignore` | Appended — one line for `.polydeukes/` |
83
-
84
- Nothing existing is overwritten: an artifact already present is reported as skipped and left
85
- alone, so a re-run is a no-op. A precondition failure — the package not resolving, two
86
- coexisting config spellings, an unparseable settings file — writes zero files and exits `2`,
87
- never a half-wired tree.
88
-
89
- ### `pdks init grok`
90
-
91
- The Grok session-surface installer. Same preflight and the same shared scaffold (config and
92
- the `.polydeukes/` ignore line). A Grok-only tree gets four artifacts (hook JSON, the grok
93
- delegator, config, ignore line) and no `.claude/` directory. The JSON registration carries
94
- `timeout` 60 (the host default is 5 seconds; a timed-out hook fails open). If
95
- `.claude/hooks/covenant-pretooluse.mjs` already exists, the JSON command points at that file
96
- so the host does not spawn two judges. A later run of either installer retargets an
97
- installer-generated grok-mjs command the same way, and the JSON matcher follows the
98
- `.claude/settings.json` entry for that command (Grok collapses two registrations only when
99
- command and matcher both match); a command pointed elsewhere is left alone.
100
-
101
- An already-open Grok session keeps the hook snapshot from start; reload from the Hooks tab
102
- (`r`) or start a new session. The witness valve does not open on Grok: the session log is
103
- ACP `updates.jsonl`, not Claude's JSONL.
104
-
105
- ### `pdks docs [topic]`
106
-
107
- The offline documentation reader. The guides and this reference layer ship inside the
108
- package, so the answer comes from the installed version rather than from the network.
109
-
110
- | Call | Result |
111
- |---|---|
112
- | `pdks docs` | The topic list on stdout, exit `0` |
113
- | `pdks docs <topic>` | That topic's section, followed by a `See also:` line, exit `0` |
114
- | `pdks docs <unknown>` | The known topics named on stderr, exit `2` |
115
- | `pdks docs a b` | The usage line on stderr, exit `2` |
116
-
117
- | Topic | Answers from |
118
- |---|---|
119
- | `install` | [installation](../installation.md), in full |
120
- | `config` | [the configuration reference](./configuration.md), in full |
121
- | `discipline` | [the configuration reference](./configuration.md) — the `disciplines` section |
122
- | `covenant` | [configuration](../configuration.md) — What enforcement looks like |
123
- | `witness` | [the configuration reference](./configuration.md)'s `witness` section, then [troubleshooting](../troubleshooting.md)'s valve section |
124
-
125
- **Every failure leaves stdout at zero bytes.** A missing bundled document, a heading the
126
- document no longer carries, an unknown topic — each names what was missing on stderr and
127
- exits `2`. A partially written answer is one an agent reads as the document and quotes
128
- onward, so there is no such state.
129
-
130
- The bundle carries the English text only. Answers are returned verbatim, so the
131
- `[한국어](./X.ko.md)` link at the top of each document points at a mirror that lives in the
132
- [repository](https://github.com/huskyhoochu/polydeukes/tree/main/docs) rather than inside
133
- the package.
134
-
135
- `pdks init claude-code` writes a discovery file that points an AI partner at this
136
- subcommand; see the artifact table above.
137
-
138
- ### `pdks explain`
139
-
140
- The assembly reader. It loads the config at the working directory, assembles both surfaces'
141
- registration sets through the same functions the two judgment runners use, and prints them
142
- without judging — no judge thunk is called, no telemetry row is written, no transcript is
143
- read.
144
-
145
- ```text
146
- pdks explain — polydeukes.config.yaml
147
-
148
- surface: session (claude-code hook) · disciplines: advise unless enforce: block · meta: block
149
- registrations 43 · declare 21 · skip 19 · meta 3 · draft 1
150
- meta self-mod paths 14 (common; includes the config file itself)
151
- declare covenant-vocabulary added-only · change · empty nothing-added · scope target.path · include 1 · exclude 1 · sources 0 · valve — · why ✓
152
- declare pnpm-only forbidden-command · change · empty no-npm-mutation · scope command · include 0 · exclude 0 · sources 0 · valve — · why ✓
153
- declare manifest-needs-evidence precedent · history · nonEmpty npm-view, context7 · scope target.path · include 1 · exclude 0 · sources 1 (transcript 1) · valve — · why ✓
154
- skip covenant-vocabulary a shell write in scope whose result this layer cannot compute
155
- ...
156
- surface: commit (git pre-commit) · enforce: advise · disciplines: advise unless enforce: block
157
- registrations 24 · declare 22 · skip 1 · meta 1 · draft 1
158
- declare manifest-needs-evidence precedent · history · nonEmpty npm-view, context7 · scope target.path · include 1 · exclude 0 · sources 1 (transcript 1) · valve — · why ✓
159
- declare sqlite-only-under-knowledge naming · change · empty placed · scope target.path · include 1 · exclude 0 · sources 0 · valve — · why ✓
160
- ```
161
-
162
- One line per registration, in the order the surface dispatches them. The kind column has
163
- four words: `meta` (the registrations protecting the judging chain — `self-mod`,
164
- `shell-mod`, and on the session surface `transcript-mod`), `declare` (a declaration entry,
165
- with its mechanism, axes and relations, its scope source, the sizes of its include and
166
- exclude lists, its sources, and whether it carries a valve and a `why`), `skip` (a
167
- registration that records `skipped` instead of judging, with the reason the compiler gave —
168
- the reason that otherwise reaches stderr only on a config fault), and `draft` (an unpromoted
169
- `draft: true` entry, shown on both surfaces since it belongs to neither). `registrations`
170
- counts `meta`, `declare`, and `skip`; `draft` is tallied apart because it never becomes a
171
- registration.
172
- The commit surface's header also names its `adapters.git.enforce` level, since an advising
173
- surface records the same table but blocks nothing.
174
-
175
- The session surface is rendered as the hook sees it under a normal payload — with a
176
- transcript present — so `transcript-mod` and the session-reading declarations appear as they
177
- do in a session; on the commit surface those declarations record `skipped` when matched,
178
- which is that surface's permanent condition.
179
-
180
- | Call | Result |
181
- |---|---|
182
- | `pdks explain` | Both surfaces on stdout, exit `0` |
183
- | `pdks explain <anything>` | The usage line on stderr, exit `2` |
184
- | no config, two configs, or an invalid one | `pdks explain: <reason>` on stderr, stdout at zero bytes, exit `2` |
185
-
186
- ### Any other argument form
187
-
188
- Anything that is not one of these forms writes the usage line —
189
- `usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain |
190
- pdks init claude-code | pdks init grok | pdks docs [topic]` — to stderr and exits `2`.
191
-
192
- ## Exit codes
193
-
194
- Three codes exist, and they live at two layers. **What a consumer's hook observes is only
195
- `0` or `2`** — both composition roots resolve to a named outcome carrying `exitCode: 0 | 2`.
196
-
197
- | Code | Constant | Emitted by | Means |
198
- |---|---|---|---|
199
- | `0` | `EXIT_UPHOLD` | Judge outcome, wrapper, bin | The promise was upheld — the call or commit proceeds |
200
- | `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 |
201
- | `2` | `EXIT_BREAK_BLOCKING` | Wrapper, bin, fail-closed paths | The call or commit is refused |
202
-
203
- The asymmetry is the protocol's responsibility boundary. A judge decides *whether* a
204
- promise was broken and answers `0` or `1` in its outcome; deciding what a break *costs* belongs
205
- to the wrapper, and that is the one place `enforce` is read. A judge can therefore be run,
206
- tested, and reasoned about without knowing whether the surface it runs under blocks or advises.
207
- Only the verdict relaxes: every unjudgeable outcome — an outcome of `2` or higher, a throw
208
- from the judge — stays `2` at either level.
209
-
210
- **Everything unjudgeable resolves to `2`.** A missing config, an invalid one, an
211
- unparseable payload, a judge body that was never built — each fails closed. The one
212
- direction that stays open is measurement: a telemetry write that fails never changes a
213
- verdict.
214
-
215
- ## Programmatic surface
216
-
217
- The barrel (`import … from 'polydeukes'`) exports six symbols plus one re-exported type.
218
- This is the whole public API; the scoped packages are not part of it.
219
-
220
- ### `loadConfig`
221
-
222
- **Type signature:**
223
-
224
- ```ts
225
- function loadConfig(spec: LoadConfigSpec): LoadedConfig;
226
-
227
- type LoadConfigSpec = { rootDir: string };
228
-
229
- type LoadedConfig = {
230
- config: ResolvedConfig; // protectedPaths already includes the config file itself
231
- configPath: string; // rootDir-relative path of the discovered file
232
- };
233
- ```
234
-
235
- Discovers exactly one `polydeukes.config` file (`.yaml`, `.yml`, or `.json`) directly under
236
- `rootDir`. **Every failure branch throws** — none found, more than one found, a parse error,
237
- a schema violation. There are no silent defaults, because a silently defaulted config means
238
- a silently unprotected project.
239
-
240
- ### `runCovenantCheck`
241
-
242
- **Type signature:**
243
-
244
- ```ts
245
- function runCovenantCheck(spec: CovenantCheckSpec): Promise<CovenantCheckOutcome>;
246
-
247
- type CovenantCheckOutcome = { exitCode: 0 | 2 };
248
-
249
- type CovenantCheckSpec = {
250
- repoRoot: string; // config discovery and collection anchor here
251
- telemetryPath?: string; // overrides the config's log path
252
- covenantDist?: string; // overrides the resolved judge directory
253
- ttyPrompt?: (prompt: string) => string | null; // the TTY valve seam
254
- domain?: CheckDomain; // which observation to judge; absent = staged
255
- };
256
-
257
- type CheckDomain =
258
- | { kind: 'staged' }
259
- | { kind: 'worktree' }
260
- | { kind: 'range'; base: string; head: string; ancestry?: 'merge-base' };
261
- ```
262
-
263
- The commit surface's composition root — what [`pdks covenant
264
- check`](#pdks-covenant-check) runs. `ancestry: 'merge-base'` is the `<base>...<head>`
265
- reading; the adapter resolves the merge-base.
266
-
267
- `ttyPrompt` absent means a non-TTY environment, and the valve then has no way to open — an
268
- agent-spawned commit and a CI run reach the same state. The valve is a human at a terminal
269
- or nothing.
270
-
271
- ### `runClaudeCodeHook`
272
-
273
- **Type signature:**
274
-
275
- ```ts
276
- function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<ClaudeCodeHookOutcome>;
277
-
278
- type ClaudeCodeHookOutcome = { exitCode: 0 | 2 };
279
-
280
- type ClaudeCodeHookSpec = {
281
- repoRoot: string; // config discovery and discipline glob scoping anchor here
282
- rawPayload?: string; // absent means read fd 0 — the hook's real stdin
283
- telemetryPath?: string;
284
- covenantDist?: string;
285
- };
286
- ```
287
-
288
- The session surface's composition root — what the generated hook delegator calls. Reach it
289
- through the [`polydeukes/claude-code`](#subpaths) subpath rather than the barrel.
290
-
291
- **Neither composition root throws.** An uncaught rejection would exit the delegator
292
- non-blocking, which is the cheapest bypass there is, so both resolve their failures into
293
- `{ exitCode: 2 }` with a telemetry record instead.
294
-
295
- ### `ResolvedConfig`
296
-
297
- Re-exported from [`@polydeukes/core`](./core.md) so a consumer reading `loadConfig`'s result
298
- needs no second dependency.
299
-
300
- ## Subpaths
301
-
302
- | Specifier | Carries |
303
- |---|---|
304
- | `polydeukes` | The barrel — `loadConfig`, `runCovenantCheck`, their spec and outcome types, `ResolvedConfig`. The session hook lives on its own subpath below and nowhere else |
305
- | `polydeukes/claude-code` | `runClaudeCodeHook`, `ClaudeCodeHookSpec`, and `ClaudeCodeHookOutcome` alone |
306
- | `polydeukes/schema.json` | The config JSON Schema, copied from the core at build time |
307
-
308
- The generated hook delegator imports the subpath, not the barrel. ESM imports are eager, so
309
- importing the barrel would load the commit-surface runner — and the git adapter behind it —
310
- on every session tool call that will never use them. The subpath is the session surface's
311
- own entry point, and the barrel is for programmatic consumers.
312
-
313
- `polydeukes/schema.json` is for code that reads the schema. A `$schema` line names the file
314
- path instead — an editor reads that string statically, so no module resolver runs on it. Both
315
- spellings are in [configuration.md's IDE section](../configuration.md#ide-support).
package/dist/index.d.ts DELETED
@@ -1,22 +0,0 @@
1
- /**
2
- * Polydeukes — a development discipline framework for building alongside an AI
3
- * coding partner.
4
- *
5
- * Pre-alpha. This package reserves the unscoped `polydeukes` name and is the umbrella /
6
- * `pdks` CLI entry point. It owns the config discovery loader and both surfaces'
7
- * composition roots — `runCovenantCheck` for the commit surface and `runClaudeCodeHook`
8
- * for the session one — because assembly needs an adapter and the covenant package at
9
- * once, which no sibling is allowed to depend on. The covenant, ledger, memory, and verify
10
- * modules live in their own `@polydeukes/*` packages.
11
- *
12
- * This file is a barrel and nothing more. ESM re-exports are eager, so anything defined
13
- * here would be instantiated by every consumer of any other export. Keep definitions in
14
- * their own modules and let importers reach them directly. A session call enters through
15
- * the published `./claude-code` subpath instead, which keeps the commit surface and its git
16
- * adapter off that load path.
17
- *
18
- * See https://github.com/huskyhoochu/polydeukes
19
- */
20
- export type { ResolvedConfig } from '@polydeukes/core';
21
- export { type CheckDomain, type CovenantCheckOutcome, type CovenantCheckSpec, runCovenantCheck, } from './covenant-check.ts';
22
- export { type LoadConfigSpec, type LoadedConfig, loadConfig } from './load-config.ts';
package/dist/index.js DELETED
@@ -1,21 +0,0 @@
1
- /**
2
- * Polydeukes — a development discipline framework for building alongside an AI
3
- * coding partner.
4
- *
5
- * Pre-alpha. This package reserves the unscoped `polydeukes` name and is the umbrella /
6
- * `pdks` CLI entry point. It owns the config discovery loader and both surfaces'
7
- * composition roots — `runCovenantCheck` for the commit surface and `runClaudeCodeHook`
8
- * for the session one — because assembly needs an adapter and the covenant package at
9
- * once, which no sibling is allowed to depend on. The covenant, ledger, memory, and verify
10
- * modules live in their own `@polydeukes/*` packages.
11
- *
12
- * This file is a barrel and nothing more. ESM re-exports are eager, so anything defined
13
- * here would be instantiated by every consumer of any other export. Keep definitions in
14
- * their own modules and let importers reach them directly. A session call enters through
15
- * the published `./claude-code` subpath instead, which keeps the commit surface and its git
16
- * adapter off that load path.
17
- *
18
- * See https://github.com/huskyhoochu/polydeukes
19
- */
20
- export { runCovenantCheck, } from './covenant-check.js';
21
- export { loadConfig } from './load-config.js';
package/dist/init-claude-code.d.ts DELETED
@@ -1,52 +0,0 @@
1
- /**
2
- * `initClaudeCode` — the session-surface installer.
3
- *
4
- * One command wires a project into the session surface: prove the package resolves, run the
5
- * shared project-side scaffold ({@link scaffoldProject}), then add what this distribution
6
- * path owns — the delegator hook file, its `.claude/settings.json` registration, the
7
- * discipline file that tells an agent the docs query exists, and the classification skill
8
- * that turns a described problem into a config entry.
9
- *
10
- * Preflight comes first and nothing is written before it clears. A generated hook whose
11
- * import can never resolve blocks every call through its own fail-closed catch, and a tree
12
- * that also has no config and no valve to open cannot be edited back into shape from inside
13
- * the session.
14
- *
15
- * Nothing existing is overwritten. The settings file in particular is merged, never
16
- * replaced: a consumer's other PreToolUse registrations and permissions are live
17
- * configuration, and replacing them would disarm every other tool they wired. A grok JSON
18
- * whose command still names the grok mjs is rewritten to this hook's command so the two
19
- * installers do not leave two spawn strings.
20
- */
21
- import { type ScaffoldReport } from './scaffold-project.ts';
22
- /**
23
- * The generated classification skill — the procedure that turns a described problem into a
24
- * registered entry. A classification procedure an agent never learns about is one that never
25
- * runs, so it ships as an artifact of the install rather than as prose in a README.
26
- *
27
- * Its advise-consumption section is the delivery path for advised rows: the session surface
28
- * lets an advised call through with exit 0, and the reason never reaches the model at call
29
- * time — reading the telemetry log at task boundaries is the only way it arrives.
30
- */
31
- export declare const GENERATED_SKILL = "---\nname: discipline-draft\ndescription: Turn a described discipline problem into a registered entry in polydeukes.config \u2014 a judged entry when the current families can express it, a draft entry otherwise. Use when the user describes a recurring problem they want promised away (\"I keep...\", \"stop X from happening\", \"we should never...\", \"how do I enforce Y\").\n---\n\n# discipline-draft \u2014 from a problem description to a registered discipline\n\nThis project is judged by Polydeukes. A discipline starts as prose and climbs a ladder \u2014\n`draft` (registered, read, never judged) \u2192 `advise` (judged, recorded, never stops a call) \u2192\n`block` (stops the call; the user's explicit choice, never the default). This skill walks a\nproblem description down to the right first rung and registers it.\n\n## Procedure\n\n### 1. Restate the problem as a promise\n\nRewrite the description as one sentence of the form \"X must not happen\" or \"when A happens,\nB must also happen\". If the sentence needs \"unless\" more than once, split it into two\npromises and classify each separately.\n\n### 2. Classify the shape\n\nAsk these questions in order; the first yes decides.\n\n| # | Question | Entry key |\n| --- | --- | --- |\n| 1 | Is the promise about content newly ADDED to a file (a pattern that must not appear in new lines)? | `declare` (mechanism `added-only`) |\n| 2 | Is it about a whole path that must not be modified or deleted (creating it once stays allowed)? | `declare` (mechanism `self-absolution-ban`) |\n| 3 | Is it about the shell command line itself, regardless of files? | `declare` (mechanism `forbidden-command`, reading the `command` source) |\n| 4 | Does it require that something else was already done earlier in the session (a tool call that must precede this one)? | `declare` (mechanism `precedent`, reading a `transcript` source) |\n| 5 | None of the above | `draft: true` (step 4b) |\n\nAn `added-only` declaration forgives existing occurrences \u2014 only what the edit adds breaks\nthe promise. That is usually what you want: a discipline adopted today should not indict\nyesterday's code.\n\nOne path-shaped promise takes no `disciplines:` entry at all: a path nobody may touch\nbelongs in the top-level `protectedPaths:` list \u2014 its own config block, never an entry key.\n\n### 3. Check the observation boundary\n\nTwo kinds of promise cannot be judged here, whatever their shape:\n\n- **Destruction outside the repository** \u2014 judgment observes the project root only. Register\n nothing; use the agent's own permission deny policy for commands like `rm -rf ~`.\n- **Writes by child processes** \u2014 a test runner or script writing files is invisible to the\n session surface, which judges declared tool calls only. Say so to the user; the commit\n surface will still see the result as a staged diff.\n\n### 4a. Expressible now \u2014 register a judged entry\n\nAdd the entry to the `disciplines:` array in `polydeukes.config.yaml`. Advise is the default\nlanding \u2014 a break is recorded as `advised` and the call goes on \u2014 and the `enforce: advise`\nline below only spells that default out. NEVER write `enforce: block` from this skill:\npromotion to block is the user's own choice, made after the advise measurements have been\nread.\n\nThe examples below are whole documents, so `languages:` \u2014 the schema's one required block \u2014\nappears alongside the entry; in a config that already has one, copy the entry only.\n\n```yaml\nlanguages:\n placeholder:\n productionGlob: 'src/**'\n testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n - id: 'no-focused-tests'\n why: 'a committed .only silently shrinks the suite to one test'\n declare:\n mechanism: 'added-only'\n scope: { source: 'target.path', include: ['^src/'] }\n supply: { pre: 'empty', post: 'empty' }\n extract:\n before:\n - { op: 'source', of: 'pre' }\n - { op: 'lines' }\n - { op: 'keyByPattern', re: '(\\.only\\()' }\n after:\n - { op: 'source', of: 'post' }\n - { op: 'lines' }\n - { op: 'keyByPattern', re: '(\\.only\\()' }\n added:\n - { op: 'onlyIn', of: 'after', notIn: 'before' }\n relate:\n - id: 'nothing-added'\n relation: { op: 'empty', of: 'added' }\n message: 'adds {key}: {value}'\n enforce: advise\n```\n\nA command-line ban reads the fixed source `command` and scopes on it \u2014 the scope is part of\nthe mechanism's shape, so a `forbidden-command` entry without it is refused at load time:\n\n```yaml\nlanguages:\n placeholder:\n productionGlob: 'src/**'\n testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n - id: 'no-force-push'\n why: 'a force push rewrites history nobody reviewed'\n declare:\n mechanism: 'forbidden-command'\n scope: { source: 'command' }\n extract:\n hits:\n - { op: 'source', of: 'command' }\n - { op: 'lines' }\n - { op: 'matches', re: 'git push\\\\b.*--force(?![\\\\w-])' }\n relate:\n - { id: 'no-force', relation: { op: 'empty', of: 'hits' }, message: '{value}' }\n enforce: advise\n```\n\n**Write the regex yourself \u2014 the user states the promise, you author the pattern.** The\npattern is the part users find hardest, so never hand the prose back and ask for one. Three\nauthoring traps, each measured on a live config:\n\n- **A pattern answers a syntactic question only.** \"Is this string a forbidden word\" is\n syntax; \"is this a new dependency version\" is meaning, and a regex leaks both ways on a\n semantic question. When the question is semantic, narrow the declaration's own `scope`\n block to the files where any match IS a break, or accept \"editing this file at all\" as\n the trigger.\n- **`^` means what the preceding step left.** After a `lines` step a declaration's\n pattern sees one line at a time, so `^` anchors to that line; over an unsplit source it\n anchors to the whole text and matches the first line only. A ban over the command line\n puts `lines` before its `matches` for exactly that reason.\n- **Author both directions.** Before registering, write down one string the pattern must\n match and one nearby string it must not (`only(` vs `only_helper(`, a flag vs its\n substring). A pattern checked in only the breaking direction over-fires in review-proof\n ways.\n\n### 4b. Not expressible yet \u2014 register a draft\n\nA draft is prose with a handle: `id`, `why`, and the literal marker `draft: true` \u2014 no other\nkeys. It produces no judgment and no telemetry; `pdks explain` lists it as unpromoted.\nRecord the SHAPE of the promise inside `why`, so the promotion destination is already\nwritten down when a later engine can express it. Name the shape in these terms:\n\n| Shape | The promise reads like |\n| --- | --- |\n| pairing | every element of set A has a counterpart in set B (translation keys, i18n) |\n| companion | if X appears in a unit, Y must appear with it |\n| ordered | a sequence must keep its order (migration journals, version ladders) |\n| fingerprint | a derived artifact must match the hash/stamp of its source |\n| producer-owned | only a designated generator may write this artifact |\n| self-absolution | the party being judged must not write its own verdict field |\n| actor-scope | the same action is fine for one actor and a break for another |\n| phase-order | several precedents, in a fixed order |\n| turn-locality | the evidence must be in the same turn or time window |\n| stated-ground | the reason must be written down before the action |\n| controlled-vocabulary | only an enumerated set of words/values is allowed |\n| naming-convention | names must match a pattern per kind |\n| irreversible-marker | once present, a marker may never be removed |\n| delegation-scope | a delegated task may touch only its granted scope |\n| scope-valve | a defined exception valve, judged rather than ad hoc |\n| claim-verification | the claim must be re-run/measured, not trusted |\n\n```yaml\nlanguages:\n placeholder:\n productionGlob: 'src/**'\n testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n - id: 'locale-files-move-together'\n why: 'pairing \u2014 en.json and ko.json must change in the same commit; one side alone is a break'\n draft: true\n```\n\n### 5. Prove it fires, then close\n\nRun `pdks explain` and confirm the new entry is listed (a judged entry with its mechanism\nand surfaces; a draft as unpromoted).\n\nFor a judged entry, registration is not the finish \u2014 a pattern that never fires protects\nnothing while looking installed. Fire it once for real, with the proof run the declaration's\nown mechanism can actually reach:\n\n| Mechanism | Break it once | The entry's id shows up in |\n| --- | --- | --- |\n| a file-reading one (`added-only`, `naming`, \u2026) | one scratch edit matching the must-match direction | `pdks covenant check --worktree` output \u2014 the exit stays 0 at advise, the id is the proof |\n| `forbidden-command` | run one harmless command matching the pattern | the telemetry log tail \u2014 at advise the call proceeds and its row records the id |\n| `precedent` | one in-scope edit made without the required precedent | the telemetry log tail \u2014 a declaration reading the session judges on the session surface only (the commit surface has none, so its `supply` policy records it `skipped`) |\n\nThen undo the scratch break, repeat the same run, and confirm silence on the\nmust-NOT-match direction. Close by telling the user which rung the entry landed on and\nthat `enforce: block` is theirs to add later if the advise record earns it.\n\n## Reading the advise record\n\nAn `advised` row means a promise was broken and the call went through anyway. Rows land in\nthe telemetry log at the path configured by `telemetry.logPath` (default\n`.polydeukes/roi.log`). The hook's stderr note is not shown to you, so consult the log at\ntask boundaries: before committing, or after a batch of edits, read the tail and act on any\n`advised` row \u2014 fix the break, or tell the user why it should stand. An advisory nobody\nreads measures nothing.\n";
32
- /** `initClaudeCode` input — the target tree and the preflight seam. */
33
- export type InitClaudeCodeSpec = {
34
- /** Project root to install into — every write below is relative to it. */
35
- projectRoot: string;
36
- /**
37
- * Preflight seam: throws when the package cannot be resolved from the given root.
38
- * ABSENT uses the real resolution, anchored at that root and nowhere else — anchoring it
39
- * at the installer's own module would answer for the installer's install graph rather
40
- * than the target project's, which is precisely the case that must fail.
41
- */
42
- resolvePolydeukes?: (projectRoot: string) => void;
43
- };
44
- /**
45
- * Install the session surface into `spec.projectRoot`, skipping whatever is already there
46
- * and reporting both halves per artifact.
47
- *
48
- * Throws before any write when the package cannot be resolved from that root or when two
49
- * config spellings already coexist there — both leave zero files. Translating a throw into
50
- * exit 2 with the install command is the bin's job.
51
- */
52
- export declare function initClaudeCode(spec: InitClaudeCodeSpec): ScaffoldReport;