npm - polydeukes - Versions diffs - 0.5.0 → 0.6.1 - Mend

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

package/README.ko.md +54 -74
package/README.md +55 -86
package/dist/baseline.d.ts +82 -0
package/dist/baseline.js +166 -0
package/dist/bin.d.ts +1 -1
package/dist/bin.js +26 -6
package/dist/claude-code-hook.d.ts +7 -5
package/dist/claude-code-hook.js +69 -17
package/dist/claude-code.d.ts +6 -0
package/dist/claude-code.js +6 -0
package/dist/covenant-check.d.ts +10 -17
package/dist/covenant-check.js +44 -12
package/dist/covenant-module.d.ts +2 -2
package/dist/covenant-module.js +9 -1
package/dist/docs/README.ko.md +60 -0
package/dist/docs/README.md +64 -0
package/dist/docs/catalog.json +464 -0
package/dist/docs/concepts/judgment.ko.md +113 -0
package/dist/docs/concepts/judgment.md +113 -0
package/dist/docs/how-to/configure-project.ko.md +99 -0
package/dist/docs/how-to/configure-project.md +95 -0
package/dist/docs/how-to/connect-surfaces.ko.md +115 -0
package/dist/docs/how-to/connect-surfaces.md +118 -0
package/dist/docs/how-to/write-disciplines.ko.md +124 -0
package/dist/docs/how-to/write-disciplines.md +125 -0
package/dist/docs/index.json +2046 -0
package/dist/docs/reference/cli/covenant-check.ko.md +101 -0
package/dist/docs/reference/cli/covenant-check.md +98 -0
package/dist/docs/reference/cli/docs.ko.md +97 -0
package/dist/docs/reference/cli/docs.md +95 -0
package/dist/docs/reference/cli/explain.ko.md +79 -0
package/dist/docs/reference/cli/explain.md +84 -0
package/dist/docs/reference/cli/init.ko.md +119 -0
package/dist/docs/reference/cli/init.md +131 -0
package/dist/docs/reference/configuration/index.ko.md +448 -0
package/dist/docs/reference/configuration/index.md +474 -0
package/dist/docs/reference/packages/adapter-claude-code.ko.md +83 -0
package/dist/docs/reference/{adapter-claude-code.md → packages/adapter-claude-code.md} +16 -10
package/dist/docs/reference/packages/adapter-git.ko.md +101 -0
package/dist/docs/reference/{adapter-git.md → packages/adapter-git.md} +25 -15
package/dist/docs/reference/packages/core.ko.md +128 -0
package/dist/docs/reference/{core.md → packages/core.md} +32 -13
package/dist/docs/reference/packages/covenant.ko.md +115 -0
package/dist/docs/reference/{covenant.md → packages/covenant.md} +41 -26
package/dist/docs/reference/packages/polydeukes.ko.md +134 -0
package/dist/docs/reference/packages/polydeukes.md +139 -0
package/dist/docs/troubleshooting.ko.md +142 -0
package/dist/docs/troubleshooting.md +97 -122
package/dist/docs/tutorials/first-judgment.ko.md +82 -0
package/dist/docs/tutorials/first-judgment.md +81 -0
package/dist/docs-catalog.d.ts +25 -0
package/dist/docs-catalog.js +450 -0
package/dist/docs-library.d.ts +23 -0
package/dist/docs-library.js +347 -0
package/dist/docs-markdown.d.ts +32 -0
package/dist/docs-markdown.js +150 -0
package/dist/docs-query.d.ts +11 -40
package/dist/docs-query.js +28 -122
package/dist/docs-types.d.ts +105 -0
package/dist/docs-types.js +2 -0
package/dist/explain.d.ts +3 -5
package/dist/explain.js +48 -47
package/dist/index.d.ts +2 -3
package/dist/index.js +1 -2
package/dist/init-claude-code.d.ts +5 -3
package/dist/init-claude-code.js +226 -63
package/dist/init-grok.d.ts +51 -0
package/dist/init-grok.js +242 -0
package/dist/load-config.d.ts +5 -1
package/dist/load-config.js +2 -1
package/dist/pre-state-reader.d.ts +22 -0
package/dist/pre-state-reader.js +32 -0
package/dist/scaffold-project.js +48 -8
package/dist/schema/polydeukes.schema.json +38 -91
package/package.json +7 -7
package/dist/docs/configuration.md +0 -103
package/dist/docs/installation.md +0 -212
package/dist/docs/reference/configuration.md +0 -338
package/dist/docs/reference/polydeukes.md +0 -287

package/README.ko.md CHANGED Viewed

@@ -1,74 +1,54 @@
-# polydeukes
-**한국어** · [English](./README.md)
-> 스코프 없는 umbrella 패키지입니다. `pdks` CLI 진입점과 config 디스커버리 로더가 살고,
-> 프레임워크의 조각을 저장소가 실제로 돌리는 표면에 맞게 조립하는 유일한 자리입니다.
-**알파(alpha) 단계입니다.** 이 패키지는 스코프 없는 `polydeukes` 이름을 예약하고, 스코프
-모듈(`@polydeukes/*`)을 조립할 수 있는 유일한 패키지로 그 위에 섭니다. 다른 모든 의존은 코어를
-통해서만 단방향으로 흐릅니다.
-## 여기 담긴 것
-- **`loadConfig(rootDir)`.** config 디스커버리입니다. 주어진 루트 바로 아래에서 정확히 하나의
-  데이터 config(`polydeukes.config` 파일의 yaml·yml·json 형태)를 찾아, 안전 스키마로 해석하고
-  (설정 데이터는 결코 실행되지 않습니다) 코어의 `defineConfig()`에 검증을 맡깁니다. 모든 실패
-  분기는 예외를 던집니다(throw). 조용한 기본값은 금지이고, 발견된 파일은 자기 자신을 보호
-  표면에 편입시킵니다.
-- **`pdks covenant check`.** `pdks` bin의 첫 실물 서브커맨드입니다(`polydeukes`는 별칭).
-  pre-commit 판정 러너로, 스테이징 영역의 변경을 `@polydeukes/adapter-git`이 수집해
-  약속(covenant) 입력 IR로 번역하고, 세션 훅이 부르는 바로 그 in-process 판정기로 보냅니다.
-  판정기는 하나, 표면은 여럿입니다. `--worktree`와 `--range <base>..<head>`는 같은 판정을
-  작업 트리나 ref 범위에 진단 호출로 돌리며, 증인 프롬프트는 뜨지 않습니다. 맥락족 규율(discipline, `requirePrecedent`)도 다른 규율과
-  똑같이 조립되지만, 읽을 세션이 없으므로 스킵 등록이 됩니다. 스테이징 변경과 매치하면 자기
-  id와 그 변경을 담은 `skipped` 이벤트를 남기고 커밋은 진행됩니다. 여기서 판정하면 걸리는
-  커밋마다 정당하게 통과할 길 없이 막히고, 아예 걸러내면 게이트가 물러섰다는 사실이 가려집니다.
-  세션 표면이 읽을 transcript를 갖지 못했을 때와 같은 처분입니다. 빈 스테이징은 명시적
-  통과이고, config가 없거나 불량이면 닫힌 실패(exit 2)입니다.
-- **`pdks init claude-code`.** 세션 표면 설치기입니다. 아무것도 쓰기 전에 대상 프로젝트에서
-  `polydeukes`가 해소되는지부터 증명하고, 그다음 모든 배포 경로가 공유하는 것(데이터 config와
-  `.polydeukes/` 무시 줄)과 이 경로가 지는 것(위임자 훅, 그 파일이 이미 담고 있던 것에 병합되는
-  `.claude/settings.json` 등록, 그리고 AI 파트너를 `pdks docs`로 보내는 범위 한정 규율 파일)을
-  만듭니다. 기존 산출물은 덮어쓰지 않습니다. 이미 있는 것은 보고하고 그대로 두므로 재실행은
-  아무 일도 하지 않고, 사용자가 고친 내용이 살아남습니다. 생성된 config는 해소 경로를 보호
-  목록에 담고 증인(witness) 블록을 함께 갖습니다. 밸브가 없으면 첫 차단이 곧 프로젝트 정지인데,
-  방금 등록한 훅 자신이 보호 대상이기 때문입니다. config 철자 둘이 공존하는 트리, 파싱되지 않는
-  settings 파일, 해소되지 않는 패키지는 전부 선행 조건 실패입니다. 반쯤 배선된 트리를 남기는
-  대신 파일을 하나도 만들지 않습니다.
-- **`pdks docs [topic]`.** 오프라인 문서 열람기입니다. 영어 가이드와 레퍼런스 층이 빌드 시점에
-  `dist/docs`로 복사되므로, 소비자의 AI 파트너는 검색 엔진이 색인한 아무 판본이 아니라 판정을
-  수행하는 코드와 함께 실린 문서를 읽습니다. 인자 없이 부르면 토픽 다섯을 열거하는데, 에이전트가
-  무엇을 물을 수 있는지 아는 경로가 그 목록뿐입니다. 토픽을 주면 그 절을 원문 그대로 돌려주고
-  이어서 읽을 레퍼런스를 한 줄 덧붙입니다. 질의 정의역은 그 다섯 이름뿐입니다. 모르는 토픽, 없는
-  동봉 문서, 문서가 더는 담지 않는 표제는 각각 무엇이 없었는지 stderr에 이름을 적고 exit 2로
-  끝나며 stdout은 0바이트로 둡니다. 절반만 쓰인 답은 에이전트가 그것을 문서로 읽고 그대로
-  인용하므로, 그런 상태를 만드는 경로를 두지 않습니다.
-- **커밋 표면 증인(witness) 밸브.** `block` 수위(기본값)에서 스테이징 영역의 변경이 실제로
-  약속을 깨면 러너가 `/dev/tty`에서 증인 토큰 전문을 1회 묻습니다(부분 문자열은 거부합니다).
-  프롬프트는 깨진 등록과 걸린 항목, 그리고 이 한 번의 답이 커밋 전체를 덮는다는 사실을 적습니다.
-  깨끗한 커밋은 프롬프트를 보지 않습니다. TTY가 없으면, 즉 CI나 에이전트가 띄운 `git commit`
-  이면 프롬프트도 통과할 길도 없습니다. 밸브는 터미널 앞의 인간에게만 닿고, 어떤 상태도 남기지
-  않으며, 증언으로 통과한 판정은 모두 `witnessed`로 기록됩니다. 조용한 우회는 없습니다.
-- **시행 수위.** git 어댑터의 네임스페이스 설정 `adapters.git.enforce: block | advise`가 커밋
-  표면 판정의 처분을 고릅니다. `advise`에서는 밸브 자체가 조립되지 않습니다. 판정은 `advised`
-  이벤트로 기록되고, stderr에 권고 한 줄이 남으며, 커밋은 진행됩니다. 차단하는 대신 측정하는
-  백스톱입니다. 완화되는 것은 판정뿐이라, 판정 자체가 불가능한 실행(설정 없음·무효, 판정 본체
-  해석 불가)은 어느 수위에서든 exit 2로 닫힙니다.
-## 전체 지도
-| 모듈 | 역할 |
-|---|---|
-| `@polydeukes/core` | 약속(covenant) 프로토콜, config 스키마, ROI 텔레메트리, 대화 기록 이음새 |
-| `@polydeukes/covenant` | 디스패처, 판정 본체, Bash 분석, 규율(discipline) 라이브러리 |
-| `@polydeukes/adapter-claude-code` | 세션 표면. PreToolUse 페이로드를 약속(covenant) 입력 IR로 번역 |
-| `@polydeukes/adapter-git` | 커밋 표면. `staged diff`를 약속(covenant) 입력 IR로 번역 |
-| `@polydeukes/ledger` · `@polydeukes/memory` · `@polydeukes/verify` | 청사진 단계 |
-아키텍처 청사진과 설계 근거는
-[프로젝트 저장소](https://github.com/huskyhoochu/polydeukes)에 있습니다.
-## 라이선스
-MIT
+# `polydeukes`
+[English](./README.md) · **한국어**
+Polydeukes는 우산 패키지입니다. 이 패키지 하나에 `pdks` 실행 파일, 설정 로더,
+커밋 표면 실행기, 세션 표면 실행기 서브패스, 동봉 스키마가 모두 포함돼 있습니다.
+<a id="overview"></a>
+## 개요
+공개 계약 심볼과 진입점은 다음과 같습니다.
+- `loadConfig`
+- `runCovenantCheck`
+- `ResolvedConfig`
+- `polydeukes/claude-code` → `runClaudeCodeHook`
+- `polydeukes/schema.json`
+- `pdks covenant check`
+- `pdks init claude-code`
+- `pdks init grok`
+- `pdks explain`
+- `pdks docs [topic]`
+<a id="public-symbols"></a>
+## 공개 심볼
+```ts
+import { loadConfig, runCovenantCheck } from 'polydeukes';
+import { runClaudeCodeHook } from 'polydeukes/claude-code';
+```
+```ts
+function loadConfig(spec: { rootDir: string }): {
+  config: import('@polydeukes/core').ResolvedConfig;
+  configPath: string;
+};
+function runCovenantCheck(spec: {
+  repoRoot: string;
+  telemetryPath?: string;
+  covenantDist?: string;
+  ttyPrompt?: (prompt: string) => string | null;
+  domain?: unknown;
+}): Promise<{ exitCode: 0 | 2 }>;
+```
+<a id="see-also"></a>
+## 같이 보기
+- [`polydeukes` 패키지 레퍼런스](../../docs/reference/packages/polydeukes.ko.md)
+- [`설정 레퍼런스`](../../docs/reference/configuration/index.ko.md)
+- [`pdks covenant check`](../../docs/reference/cli/covenant-check.ko.md)
+- [`pdks init`](../../docs/reference/cli/init.ko.md)
+- [`pdks explain`](../../docs/reference/cli/explain.ko.md)

package/README.md CHANGED Viewed

@@ -1,86 +1,55 @@
-# polydeukes
-**English** · [한국어](https://github.com/huskyhoochu/polydeukes/blob/main/packages/polydeukes/README.ko.md)
-> The unscoped umbrella: the `pdks` CLI entry point and the config discovery loader — the one
-> place where the framework's pieces are assembled for the surfaces a repository actually runs.
-**Alpha.** This package reserves the unscoped `polydeukes` name and sits above the scoped
-`@polydeukes/*` modules as the only one allowed to assemble them — every other dependency stays
-one-way, through the core alone.
-## What lives here
-- **`loadConfig(rootDir)`** — config discovery. Exactly one root data config (a
-  `polydeukes.config` file in yaml, yml, or json form) directly under the given root, parsed with
-  a safe schema (config data is never executable) and validated by the core's `defineConfig()`.
-  Every failure branch throws — silent defaults are forbidden — and the discovered file attaches
-  itself to its own protection surface.
-- **`pdks covenant check`** — the first real subcommand of the `pdks` bin (`polydeukes` is an
-  alias). A pre-commit judgment runner: staged changes are collected by `@polydeukes/adapter-git`,
-  translated into the covenant input IR, and dispatched through the very in-process judges the
-  session hook calls — one judge, every surface. `--worktree` and `--range <base>..<head>` run the same
-  judgment over the working tree or a ref range as a diagnostic call, with no witness prompt.
-  Context-family disciplines (`requirePrecedent`) assemble
-  here like any other, but with no session to read they become skip registrations: when one
-  matches a staged change it records a `skipped` event carrying its id and that change, and the
-  commit proceeds. Judging them would block every matching commit with no legitimate pass path;
-  filtering them out would hide that a gate stood down. It is the same disposition the session
-  surface uses when it has no transcript. An empty staging area is an explicit pass; a missing or
-  invalid config fails closed.
-- **`pdks explain`** — the assembly reader. It assembles both surfaces' registration sets through
-  the same functions the two runners call and prints them without judging: every registration
-  with its kind (`meta` / `judge` / `skip` / `excluded`), the routing scope of each entry, whether
-  it carries a `why`, and for each skip the compiler's reason — the one that otherwise reaches
-  stderr only when the cause is a config fault. No judge thunk is called and no telemetry row is
-  written. A config that cannot be loaded fails at exit `2` with stdout at zero bytes.
-- **`pdks init claude-code`** — the session-surface installer. It proves `polydeukes` resolves
-  from the target project before writing anything, then creates what every distribution path
-  shares (the data config and its `.polydeukes/` ignore line) and what this path owns (a delegator
-  hook, its `.claude/settings.json` registration merged into whatever that file already carries,
-  and a scoped discipline file pointing an AI partner at `pdks docs`). Nothing existing is
-  overwritten: an artifact already there is reported and left alone, so a re-run is a no-op and a
-  consumer's edits survive. The generated config carries the resolution paths on its protection
-  list and a witness block — without the valve the first block would freeze the project, since the
-  hook it just registered is itself protected. Two coexisting config spellings, an unparseable
-  settings file, and a package that cannot be resolved are all precondition failures: each leaves
-  zero files rather than a half-wired tree.
-- **`pdks docs [topic]`** — the offline documentation reader. The English guides and the reference
-  layer are copied into `dist/docs` at build time, so a consumer's AI partner reads the
-  documentation that shipped with the code doing the judging instead of whichever release a search
-  engine indexed. With no argument it lists the five topics — that listing is how an agent
-  discovers what it may ask at all; with one it returns that topic's section verbatim plus the
-  reference to read next. The query domain is those five names and nothing else: an unknown topic,
-  a bundled document that is missing, and a heading a document no longer carries each name what
-  was missing on stderr and exit 2, leaving stdout at zero bytes. A partially written answer would
-  be read as the document and quoted onward, so no path produces one.
-- **The commit-surface witness valve** — at the `block` level (the default), when a staged change
-  actually breaks a covenant, the runner prompts once on `/dev/tty` for the full witness token (a
-  substring is refused), naming the broken registration, the matched entry, and the commit-wide
-  reach of the one answer. A clean commit never prompts. No TTY — CI, an agent-spawned
-  `git commit` — means no prompt and no way through: the valve is reachable only by a human at a
-  terminal, and nothing is ever persisted. Every witnessed pass is measured as `witnessed`, never
-  silent.
-- **The enforcement level** — the git adapter's namespace setting
-  `adapters.git.enforce: block | advise` selects what a commit-surface verdict does. Under
-  `advise` the valve is structurally absent: a verdict is recorded as an `advised` event, one
-  advisory line lands on stderr, and the commit proceeds — a backstop that measures instead of
-  blocking. Only the verdict is relaxed: a run that cannot judge (missing or invalid config, an
-  unresolvable judge body) fails closed at exit 2 at either level.
-## The wider map
-| Module | Role |
-|---|---|
-| `@polydeukes/core` | Covenant protocol, config schema, ROI telemetry, transcript seam |
-| `@polydeukes/covenant` | Dispatcher, judge bodies, Bash analysis, discipline library |
-| `@polydeukes/adapter-claude-code` | Session surface — PreToolUse payloads → covenant input IR |
-| `@polydeukes/adapter-git` | Commit surface — staged diffs → covenant input IR |
-| `@polydeukes/ledger` · `@polydeukes/memory` · `@polydeukes/verify` | Blueprint stage |
-See the [project repository](https://github.com/huskyhoochu/polydeukes) for the architecture
-blueprint and design rationale.
-## License
-MIT
+# `polydeukes`
+**English** · [한국어](./README.ko.md)
+Polydeukes is the umbrella package. Install this package; it ships the `pdks` bin, the config
+loader, the commit-surface runner, the session-surface runner subpath, and the bundled schema
+artifact.
+<a id="overview"></a>
+## Overview
+Public contract symbols and entry points:
+- `loadConfig`
+- `runCovenantCheck`
+- `ResolvedConfig`
+- `polydeukes/claude-code` → `runClaudeCodeHook`
+- `polydeukes/schema.json`
+- `pdks covenant check`
+- `pdks init claude-code`
+- `pdks init grok`
+- `pdks explain`
+- `pdks docs [topic]`
+<a id="public-symbols"></a>
+## Public symbols
+```ts
+import { loadConfig, runCovenantCheck } from 'polydeukes';
+import { runClaudeCodeHook } from 'polydeukes/claude-code';
+```
+```ts
+function loadConfig(spec: { rootDir: string }): {
+  config: import('@polydeukes/core').ResolvedConfig;
+  configPath: string;
+};
+function runCovenantCheck(spec: {
+  repoRoot: string;
+  telemetryPath?: string;
+  covenantDist?: string;
+  ttyPrompt?: (prompt: string) => string | null;
+  domain?: unknown;
+}): Promise<{ exitCode: 0 | 2 }>;
+```
+<a id="see-also"></a>
+## See also
+- [`polydeukes` package reference](../../docs/reference/packages/polydeukes.md)
+- [`Configuration reference`](../../docs/reference/configuration/index.md)
+- [`pdks covenant check`](../../docs/reference/cli/covenant-check.md)
+- [`pdks init`](../../docs/reference/cli/init.md)
+- [`pdks explain`](../../docs/reference/cli/explain.md)

package/dist/baseline.d.ts ADDED Viewed

@@ -0,0 +1,82 @@
+/**
+ * Post-hoc state comparison — the baseline comparator.
+ *
+ * The session surface judges declared calls, so a write nobody declared leaves no row at
+ * all. This module answers the same question from the other end: summarize the protected
+ * entries' on-disk state, and after the fact name the entries whose state moved with no
+ * judgment row explaining it. It records rather than blocks — every failure shape here
+ * resolves to a value, never a throw.
+ *
+ * Split the way the telemetry module is: {@link findUnattributed} is pure and
+ * {@link snapshotBaseline} / {@link writeBaseline} / {@link readBaseline} are the I/O
+ * points.
+ */
+import type { TelemetryRecord } from '@polydeukes/core';
+/** One hash per protected entry, keyed by the entry exactly as configured. */
+export type BaselineSnapshot = Record<string, string>;
+/**
+ * The baseline file's contents: the entry hashes plus the instant the attribution window
+ * opens at. Named for the file rather than the concept — `Baseline` already belongs to the
+ * delta family, where it means a file's prior CONTENT, not a protection snapshot.
+ *
+ * The two fields travel together because they are read together — pairing one comparison's
+ * hashes with another's cut would silently mis-attribute, undetectably.
+ */
+export type StoredBaseline = {
+    entries: BaselineSnapshot;
+    cutAt?: string;
+};
+/**
+ * Summarize each entry's on-disk state as one sha256.
+ *
+ * `entries` are repo-relative paths of either shape — a file or a directory. Every entry
+ * keeps a key whatever its state, so the diff always sees it; a missing entry simply hashes
+ * to the empty set.
+ */
+export declare function snapshotBaseline(spec: {
+    rootDir: string;
+    entries: string[];
+}): BaselineSnapshot;
+/**
+ * The entries whose hash changed and that no window row explains (pure).
+ *
+ * Attribution is asked per entry, never per window: "the window holds an attributing row"
+ * and "THIS entry's change has one" are different claims, and answering the first is the
+ * fail-open shape this repository already shipped once.
+ *
+ * The window is cut by `cutAt` — rows at or after that instant, which are the ones written
+ * since the previous comparison. Cutting by time rather than by a record count keeps the
+ * bound meaningful when the log is trimmed or rotated; a positional index would point past
+ * the end and empty the window for every later call. An absent cut admits every row: over-
+ * attributing costs one missed alarm in a session that is already anomalous, while under-
+ * attributing floods an ordinary one and teaches the reader to ignore the alarm entirely.
+ *
+ * Only entries the previous baseline already watched are compared. An entry the config just
+ * added has no prior hash, and reporting it would make editing one's own policy look
+ * identical to a tamper; an entry the config dropped is simply no longer watched.
+ */
+export declare function findUnattributed(spec: {
+    previous: BaselineSnapshot;
+    current: BaselineSnapshot;
+    records: TelemetryRecord[];
+    cutAt?: string;
+}): string[];
+/**
+ * Write the baseline file.
+ *
+ * `cutAt` is the instant this comparison ran, so the next one attributes from rows written
+ * at or after it. Written at call END, so the rows explaining what this call itself changed
+ * fall before the cut — the snapshot beside them already absorbed those changes.
+ */
+export declare function writeBaseline(path: string, snapshot: BaselineSnapshot, cutAt?: string): void;
+/**
+ * Read the baseline — entries and window cut in ONE parse — or `null`.
+ *
+ * One parse rather than two: reading the hashes and the cut separately lets a concurrent
+ * write land between them, pairing one comparison's state with another's window bound. That
+ * mismatch changes which entries are attributed and leaves no trace anywhere.
+ *
+ * Absence and corruption are the same signal — re-establish and record — so neither throws.
+ * Observation is fail-open: the worst outcome is a missing datum, never a blocked call.
+ */
+export declare function readBaseline(path: string): StoredBaseline | null;

package/dist/baseline.js ADDED Viewed

@@ -0,0 +1,166 @@
+/**
+ * Post-hoc state comparison — the baseline comparator.
+ *
+ * The session surface judges declared calls, so a write nobody declared leaves no row at
+ * all. This module answers the same question from the other end: summarize the protected
+ * entries' on-disk state, and after the fact name the entries whose state moved with no
+ * judgment row explaining it. It records rather than blocks — every failure shape here
+ * resolves to a value, never a throw.
+ *
+ * Split the way the telemetry module is: {@link findUnattributed} is pure and
+ * {@link snapshotBaseline} / {@link writeBaseline} / {@link readBaseline} are the I/O
+ * points.
+ */
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The two verdict words that explain a change — the ones that mean a mutation of a
+ * protected entry was judged and let through anyway.
+ *
+ * `witnessed` is a break a human opened in person; `advised` is one an advise-level surface
+ * recorded without stopping. Both name a write the session knew about, so the change that
+ * follows is accounted for.
+ *
+ * The other four do not attribute, each for its own reason. `passed` means the call was
+ * judged and did NOT break the covenant — on a protected entry that is a mention, not a
+ * mutation, so it explains no later change; admitting it is what let a read-only call
+ * absolve a tamper. `blocked` stops the call, so what follows is not its doing, and
+ * admitting it would make provoking a block a licence for every later write to that entry
+ * (the residue a blocked call really left is present when that same call compares, reported
+ * there once, and folded into its own re-establishment). `skipped` is a recorded absence of
+ * judgment, which explains nothing. `unattributed` must never silence its own successor.
+ */
+const ATTRIBUTING_EVENTS = ['witnessed', 'advised'];
+/**
+ * Fold one file's path and content into `hash`.
+ *
+ * The path participates, so a rename with byte-identical content still moves the entry's
+ * hash. An unreadable file contributes a fixed absence marker rather than aborting the
+ * walk — absence is a state, and a file that vanished mid-walk is exactly the state the
+ * comparison exists to see. The marker leads with an escaped NUL so no readable file's
+ * contents can collide with it; written as an escape rather than a literal byte, which
+ * would make this source a binary file to git and hide it from every diff.
+ */
+function foldFile(hash, absolutePath, key) {
+    hash.update(key);
+    try {
+        hash.update(readFileSync(absolutePath));
+    }
+    catch {
+        hash.update('\0absent');
+    }
+}
+/**
+ * Fold everything reachable under `absolutePath` into `hash`, in sorted order.
+ *
+ * Sorted so an unchanged tree hashes identically twice — directory iteration order is not
+ * a guarantee, and a nondeterministic term would read as a change on every call. A path
+ * that is a file, or that does not exist at all, is not a traversal failure: six of the
+ * live config's thirteen entries name a file, and a vanished entry hashes to the empty set.
+ */
+function foldEntry(hash, rootDir, relPath) {
+    let children;
+    try {
+        children = readdirSync(join(rootDir, relPath), { withFileTypes: true });
+    }
+    catch {
+        foldFile(hash, join(rootDir, relPath), relPath);
+        return;
+    }
+    for (const child of [...children].sort((a, b) => a.name.localeCompare(b.name))) {
+        foldEntry(hash, rootDir, `${relPath}/${child.name}`);
+    }
+}
+/**
+ * Summarize each entry's on-disk state as one sha256.
+ *
+ * `entries` are repo-relative paths of either shape — a file or a directory. Every entry
+ * keeps a key whatever its state, so the diff always sees it; a missing entry simply hashes
+ * to the empty set.
+ */
+export function snapshotBaseline(spec) {
+    const snapshot = {};
+    for (const entry of spec.entries) {
+        const hash = createHash('sha256');
+        foldEntry(hash, spec.rootDir, entry);
+        snapshot[entry] = hash.digest('hex');
+    }
+    return snapshot;
+}
+/**
+ * The entries whose hash changed and that no window row explains (pure).
+ *
+ * Attribution is asked per entry, never per window: "the window holds an attributing row"
+ * and "THIS entry's change has one" are different claims, and answering the first is the
+ * fail-open shape this repository already shipped once.
+ *
+ * The window is cut by `cutAt` — rows at or after that instant, which are the ones written
+ * since the previous comparison. Cutting by time rather than by a record count keeps the
+ * bound meaningful when the log is trimmed or rotated; a positional index would point past
+ * the end and empty the window for every later call. An absent cut admits every row: over-
+ * attributing costs one missed alarm in a session that is already anomalous, while under-
+ * attributing floods an ordinary one and teaches the reader to ignore the alarm entirely.
+ *
+ * Only entries the previous baseline already watched are compared. An entry the config just
+ * added has no prior hash, and reporting it would make editing one's own policy look
+ * identical to a tamper; an entry the config dropped is simply no longer watched.
+ */
+export function findUnattributed(spec) {
+    const cutAt = spec.cutAt;
+    const attributed = new Set(spec.records
+        .filter((record) => cutAt === undefined || record.timestamp >= cutAt)
+        .filter((record) => ATTRIBUTING_EVENTS.includes(record.event))
+        .map((record) => record.subject));
+    return Object.keys(spec.current).filter((entry) => entry in spec.previous &&
+        spec.current[entry] !== spec.previous[entry] &&
+        !attributed.has(entry));
+}
+/**
+ * Write the baseline file.
+ *
+ * `cutAt` is the instant this comparison ran, so the next one attributes from rows written
+ * at or after it. Written at call END, so the rows explaining what this call itself changed
+ * fall before the cut — the snapshot beside them already absorbed those changes.
+ */
+export function writeBaseline(path, snapshot, cutAt) {
+    writeFileSync(path, JSON.stringify({ entries: snapshot, cutAt }));
+}
+/**
+ * Read the baseline — entries and window cut in ONE parse — or `null`.
+ *
+ * One parse rather than two: reading the hashes and the cut separately lets a concurrent
+ * write land between them, pairing one comparison's state with another's window bound. That
+ * mismatch changes which entries are attributed and leaves no trace anywhere.
+ *
+ * Absence and corruption are the same signal — re-establish and record — so neither throws.
+ * Observation is fail-open: the worst outcome is a missing datum, never a blocked call.
+ */
+export function readBaseline(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    // Validate what the comparison will use: valid JSON of the wrong shape parses fine and
+    // then crashes the diff, which the fail-open wiring swallows — detection would go dark
+    // with no re-establishment and no row.
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const { entries, cutAt } = parsed;
+    if (typeof entries !== 'object' || entries === null || Array.isArray(entries)) {
+        return null;
+    }
+    if (Object.values(entries).some((value) => typeof value !== 'string')) {
+        return null;
+    }
+    // An unparseable cut degrades to absent, which admits the whole window — the same safe
+    // direction {@link findUnattributed} takes, rather than a bound nobody can trust.
+    return {
+        entries: entries,
+        cutAt: typeof cutAt === 'string' ? cutAt : undefined,
+    };
+}

package/dist/bin.d.ts CHANGED Viewed

@@ -2,7 +2,7 @@
 /**
  * `pdks` / `polydeukes` — the umbrella bin.
  *
- * A thin argv shim: four subcommands, each matched by direct comparison against a finite
+ * A thin argv shim: each subcommand is matched by direct comparison against a finite
  * table. Anything else prints usage and exits 2 — an unknown argument must never pass
  * silently (fail-closed, the same posture as an unjudgeable payload).
  *

package/dist/bin.js CHANGED Viewed

@@ -2,7 +2,7 @@
 /**
  * `pdks` / `polydeukes` — the umbrella bin.
  *
- * A thin argv shim: four subcommands, each matched by direct comparison against a finite
+ * A thin argv shim: each subcommand is matched by direct comparison against a finite
  * table. Anything else prints usage and exits 2 — an unknown argument must never pass
  * silently (fail-closed, the same posture as an unjudgeable payload).
  *
@@ -11,7 +11,7 @@
  * CI or by an agent-spawned shell — no controlling terminal), the seam stays absent and
  * the witness valve is structurally unreachable, so only a human at a terminal can arm it.
  */
-import { closeSync, openSync, readSync, writeSync } from 'node:fs';
+import { closeSync, openSync, readFileSync, readSync, writeSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
@@ -88,15 +88,35 @@ if (args.length === 2 && args[0] === 'init' && args[1] === 'claude-code') {
         process.exit(2);
     }
 }
-if (args[0] === 'docs' && args.length <= 2) {
+if (args.length === 2 && args[0] === 'init' && args[1] === 'grok') {
+    try {
+        const { initGrok } = await import('./init-grok.js');
+        const { created, skipped } = initGrok({ projectRoot: process.cwd() });
+        for (const path of created) {
+            process.stdout.write(`created ${path}\n`);
+        }
+        for (const path of skipped) {
+            process.stdout.write(`skipped ${path} (already present)\n`);
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        process.stderr.write(`pdks init grok failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(2);
+    }
+}
+if (args[0] === 'docs') {
     try {
         // Imported inside the try for the same reason `init` is: the query core and the
         // markdown behind it have no business on `covenant check`'s load path.
-        const { queryDocs } = await import('./docs-query.js');
+        const { runDocs } = await import('./docs-library.js');
         // The bundle ships beside this file, so the docs root comes from the module's own
         // location — never from the working directory, which is whatever shell invoked us.
         const docsRoot = join(dirname(fileURLToPath(import.meta.url)), 'docs');
-        const { text } = queryDocs({ docsRoot, topic: args[1] });
+        const manifest = JSON.parse(readFileSync(join(docsRoot, '../../package.json'), 'utf8'));
+        if (typeof manifest.version !== 'string')
+            throw new Error('missing package version');
+        const { text } = runDocs({ docsRoot, args: args.slice(1), version: manifest.version });
         await emitAndExit(text);
     }
     catch (error) {
@@ -149,7 +169,7 @@ function parseCheckDomain(flags) {
 }
 const domain = args[0] === 'covenant' && args[1] === 'check' ? parseCheckDomain(args.slice(2)) : null;
 if (domain === null) {
-    process.stderr.write('usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain | pdks init claude-code | pdks docs [topic]\n');
+    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');
     process.exit(2);
 }
 try {

package/dist/claude-code-hook.d.ts CHANGED Viewed

@@ -25,8 +25,12 @@
  */
 import { type CanonicalTranscript } from '@polydeukes/core';
 import { type CovenantRegistration } from '@polydeukes/covenant';
-import { type CovenantModule } from './covenant-module.js';
-import { loadConfig } from './load-config.js';
+import { type CovenantModule } from './covenant-module.ts';
+import { loadConfig } from './load-config.ts';
+/** {@link runClaudeCodeHook} result — the exit code the hook process leaves with. */
+export type ClaudeCodeHookOutcome = {
+    exitCode: 0 | 2;
+};
 /** `runClaudeCodeHook` input — the `CovenantCheckSpec` shape, session side. */
 export type ClaudeCodeHookSpec = {
     /** Repository root — config discovery and discipline glob scoping both anchor here. */
@@ -72,6 +76,4 @@ export declare function assembleSessionRegistrations(spec: SessionAssemblySpec):
  * left and its rows land ahead of this call's judgment; the re-establishment runs last, so
  * this call's own judged writes are folded in rather than alarmed on next time.
  */
-export declare function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<{
-    exitCode: 0 | 2;
-}>;
+export declare function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<ClaudeCodeHookOutcome>;