npm - polydeukes - Versions diffs - 0.4.0 → 0.6.0 - Mend

polydeukes 0.4.0 → 0.6.0

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 (41) hide show

package/README.ko.md +11 -4
package/README.md +21 -5
package/dist/baseline.d.ts +82 -0
package/dist/baseline.js +166 -0
package/dist/bin.d.ts +5 -6
package/dist/bin.js +92 -38
package/dist/claude-code-hook.d.ts +40 -17
package/dist/claude-code-hook.js +187 -175
package/dist/claude-code.d.ts +6 -0
package/dist/claude-code.js +6 -0
package/dist/covenant-check.d.ts +50 -36
package/dist/covenant-check.js +167 -193
package/dist/covenant-module.d.ts +25 -0
package/dist/covenant-module.js +42 -0
package/dist/docs/configuration.md +17 -9
package/dist/docs/installation.md +42 -12
package/dist/docs/reference/adapter-claude-code.md +6 -4
package/dist/docs/reference/adapter-git.md +23 -10
package/dist/docs/reference/configuration.md +265 -103
package/dist/docs/reference/core.md +15 -7
package/dist/docs/reference/covenant.md +32 -24
package/dist/docs/reference/polydeukes.md +132 -32
package/dist/docs/troubleshooting.md +37 -8
package/dist/docs-query.d.ts +10 -10
package/dist/docs-query.js +12 -12
package/dist/explain.d.ts +25 -0
package/dist/explain.js +153 -0
package/dist/index.d.ts +11 -16
package/dist/index.js +10 -15
package/dist/init-claude-code.d.ts +31 -18
package/dist/init-claude-code.js +254 -40
package/dist/init-grok.d.ts +51 -0
package/dist/init-grok.js +242 -0
package/dist/load-config.d.ts +17 -15
package/dist/load-config.js +13 -12
package/dist/pre-state-reader.d.ts +22 -0
package/dist/pre-state-reader.js +32 -0
package/dist/scaffold-project.d.ts +23 -14
package/dist/scaffold-project.js +97 -32
package/dist/schema/polydeukes.schema.json +54 -81
package/package.json +7 -7

package/README.ko.md CHANGED Viewed

@@ -11,16 +11,17 @@
 ## 여기 담긴 것
-- **`loadConfig(rootDir)`.** config 디스커버리입니다. 주어진 루트 바로 아래에서 정확히 하나의
+- **`loadConfig({ rootDir })`.** config 디스커버리입니다. 주어진 루트 바로 아래에서 정확히 하나의
   데이터 config(`polydeukes.config` 파일의 yaml·yml·json 형태)를 찾아, 안전 스키마로 해석하고
   (설정 데이터는 결코 실행되지 않습니다) 코어의 `defineConfig()`에 검증을 맡깁니다. 모든 실패
   분기는 예외를 던집니다(throw). 조용한 기본값은 금지이고, 발견된 파일은 자기 자신을 보호
   표면에 편입시킵니다.
 - **`pdks covenant check`.** `pdks` bin의 첫 실물 서브커맨드입니다(`polydeukes`는 별칭).
   pre-commit 판정 러너로, 스테이징 영역의 변경을 `@polydeukes/adapter-git`이 수집해
-  약속(covenant) 입력 IR로 번역하고, 세션 훅이 띄우는(spawn) 바로 그 판정 본체로 보냅니다.
-  판정기는 하나, 표면은 여럿입니다. 맥락족 규율(discipline, `requirePrecedent`)도 다른 규율과
-  똑같이 조립되지만, 읽을 세션이 없으므로 스킵 등록이 됩니다. 스테이징 변경과 매치하면 자기
+  약속(covenant) 입력 IR로 번역하고, 세션 훅이 부르는 바로 그 in-process 판정기로 보냅니다.
+  판정기는 하나, 표면은 여럿입니다. `--worktree`와 `--range <base>..<head>`는 같은 판정을
+  작업 트리나 ref 범위에 진단 호출로 돌리며, 증인 프롬프트는 뜨지 않습니다. 세션을 읽는 선언(`precedent`와 다른 이력 기전)도 다른 규율과
+  똑같이 조립되지만, 읽을 세션이 없으므로 자기 `supply: pass`가 처분합니다. 스테이징 변경과 매치하면 자기
   id와 그 변경을 담은 `skipped` 이벤트를 남기고 커밋은 진행됩니다. 여기서 판정하면 걸리는
   커밋마다 정당하게 통과할 길 없이 막히고, 아예 걸러내면 게이트가 물러섰다는 사실이 가려집니다.
   세션 표면이 읽을 transcript를 갖지 못했을 때와 같은 처분입니다. 빈 스테이징은 명시적
@@ -35,6 +36,12 @@
   방금 등록한 훅 자신이 보호 대상이기 때문입니다. config 철자 둘이 공존하는 트리, 파싱되지 않는
   settings 파일, 해소되지 않는 패키지는 전부 선행 조건 실패입니다. 반쯤 배선된 트리를 남기는
   대신 파일을 하나도 만들지 않습니다.
+- **`pdks init grok`.** Grok 세션 표면 설치기입니다. 선행 검사와 공유 스캐폴드는 같고, 이 경로가
+  지는 것은 `.grok/hooks/`입니다(timeout 60인 JSON 등록, Claude 위임자가 없을 때만 위임자 파일).
+  Claude 훅 파일이 이미 있으면 JSON command가 그 파일을 가리켜 판정기를 둘 스폰하지 않습니다.
+  나중에 어느 설치기를 다시 돌려도, 설치기가 심은 grok-mjs command는 같은 방식으로 재조준되고,
+  JSON matcher는 그 command의 `.claude/settings.json` 항목을 따릅니다. Grok는 command와
+  matcher가 모두 같을 때만 등록 둘을 하나로 접기 때문입니다. 이미 열린 Grok 세션은 시작 때 훅 스냅샷을 유지합니다. 증인 밸브는 Grok에서 열리지 않습니다.
 - **`pdks docs [topic]`.** 오프라인 문서 열람기입니다. 영어 가이드와 레퍼런스 층이 빌드 시점에
   `dist/docs`로 복사되므로, 소비자의 AI 파트너는 검색 엔진이 색인한 아무 판본이 아니라 판정을
   수행하는 코드와 함께 실린 문서를 읽습니다. 인자 없이 부르면 토픽 다섯을 열거하는데, 에이전트가

package/README.md CHANGED Viewed

@@ -11,22 +11,30 @@ one-way, through the core alone.
 ## What lives here
-- **`loadConfig(rootDir)`** — config discovery. Exactly one root data config (a
+- **`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 judge bodies the session
-  hook spawns — one judge, every surface. Context-family disciplines (`requirePrecedent`) assemble
-  here like any other, but with no session to read they become skip registrations: when one
+  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.
+  Declarations that read the session (`precedent` and the other history mechanisms) assemble
+  here like any other, but with no session to read their `supply: pass` takes over: 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 init claude-code`** — the session-surface installer. It proves `polydeukes` resolves
+- **`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 Claude Code 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,
@@ -37,6 +45,14 @@ one-way, through the core alone.
   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 init grok`** — the Grok session-surface installer. Same preflight and shared scaffold;
+  this path owns `.grok/hooks/` (JSON registration with timeout 60, and a delegator file only when
+  no Claude delegator is on disk). If the Claude hook file already exists, the JSON command points
+  at it so two judges are not spawned. A later run of either installer retargets an
+  installer-generated grok-mjs command the same way, and the JSON matcher follows the
+  `.claude/settings.json` entry for that command — Grok collapses two registrations only when
+  command and matcher both match. An already-open Grok session keeps the hook snapshot from
+  start. The witness valve does not open on Grok.
 - **`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

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

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 /**
- * `pdks` / `polydeukes` — the umbrella bin (ADAPTER-git §4.3).
+ * `pdks` / `polydeukes` — the umbrella bin.
  *
- * A thin argv shim over {@link runCovenantCheck}: `covenant check` is the ONLY
- * recognized invocation (the wider CLI skeleton is a post-release increment). Anything
- * else prints usage and exits 2 — an unknown argument must never pass silently
- * (fail-closed, the same posture as an unjudgeable payload).
+ * 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).
  *
  * The real TTY is wired HERE, not in the library: the runner receives an injectable
  * seam, and this shim binds it to /dev/tty. When /dev/tty cannot be opened (git run by
  * CI or by an agent-spawned shell — no controlling terminal), the seam stays absent and
- * the valve is structurally unreachable (AC-3 human-only arming).
+ * the witness valve is structurally unreachable, so only a human at a terminal can arm it.
  */
 export {};

package/dist/bin.js CHANGED Viewed

@@ -1,16 +1,15 @@
 #!/usr/bin/env node
 /**
- * `pdks` / `polydeukes` — the umbrella bin (ADAPTER-git §4.3).
+ * `pdks` / `polydeukes` — the umbrella bin.
  *
- * A thin argv shim over {@link runCovenantCheck}: `covenant check` is the ONLY
- * recognized invocation (the wider CLI skeleton is a post-release increment). Anything
- * else prints usage and exits 2 — an unknown argument must never pass silently
- * (fail-closed, the same posture as an unjudgeable payload).
+ * 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).
  *
  * The real TTY is wired HERE, not in the library: the runner receives an injectable
  * seam, and this shim binds it to /dev/tty. When /dev/tty cannot be opened (git run by
  * CI or by an agent-spawned shell — no controlling terminal), the seam stays absent and
- * the valve is structurally unreachable (AC-3 human-only arming).
+ * 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 { dirname, join } from 'node:path';
@@ -46,20 +45,32 @@ function openTtyPrompt() {
                 closeSync(fd);
             }
             catch {
-                // A second consultation would land on an already-closed fd; an EBADF thrown
-                // from this finally would override the `return null` above and escape the
-                // seam (PR #41 review). The valve caches its verdict, so this is defensive.
+                // An EBADF thrown from this finally would override the `return null` above and
+                // escape the seam.
             }
         }
     };
 }
+/**
+ * Write `text` to stdout and end the process — exit 0 once the write drains, exit 2 when
+ * the reader went away. A piped write is asynchronous, so the exit waits for the flush; a
+ * reader that closes mid-write makes the stream emit `error` outside any try frame, and
+ * this handler is what keeps that off node's default exit 1 with a stack trace.
+ */
+async function emitAndExit(text) {
+    process.stdout.on('error', () => process.exit(2));
+    await new Promise((settle) => {
+        process.stdout.write(text, () => settle());
+    });
+    process.exit(0);
+}
 const args = process.argv.slice(2);
 if (args.length === 2 && args[0] === 'init' && args[1] === 'claude-code') {
     try {
         // Imported inside the try, not above it: ESM imports are eager, so the installer stays
-        // off `covenant check`'s load path (lefthook spawns that on every commit and it must not
-        // pull the session adapter in — PR #46 review). A rejected import outside the try would
-        // reach node's unhandled-rejection exit 1, the exact crash this bin refuses to make.
+        // off `covenant check`'s load path, which a pre-commit hook spawns on every commit. A
+        // rejected import outside the try would reach node's unhandled-rejection exit 1, the
+        // exact crash this bin refuses to make.
         const { initClaudeCode } = await import('./init-claude-code.js');
         const { created, skipped } = initClaudeCode({ projectRoot: process.cwd() });
         for (const path of created) {
@@ -71,49 +82,91 @@ if (args.length === 2 && args[0] === 'init' && args[1] === 'claude-code') {
         process.exit(0);
     }
     catch (error) {
-        // A precondition failure leaves zero files (DIST-02 §5-d invariant 2); the message
-        // names what the user has to do before running this again.
+        // A precondition failure leaves zero files; the message names what the user has to do
+        // before running this again.
         process.stderr.write(`pdks init claude-code failed: ${error instanceof Error ? error.message : String(error)}\n`);
         process.exit(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' && args.length <= 2) {
     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, which lefthook
-        // spawns on every commit.
+        // markdown behind it have no business on `covenant check`'s load path.
         const { queryDocs } = await import('./docs-query.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] });
-        // A reader that goes away mid-write (a killed pager, `grep -q`, a caller closing its
-        // capture) makes the stream emit `error` — an EventEmitter event, so it fires outside
-        // the frame this try guards and would reach node's default handler: exit 1 and a raw
-        // stack trace, the one disposition this bin never produces. The docs answer is not a
-        // verdict, so a reader that stopped listening is not something to report; end at the
-        // same code an unanswerable query uses.
-        process.stdout.on('error', () => process.exit(2));
-        // stdout is a pipe whenever this is captured or redirected, and a piped write is
-        // asynchronous — exiting on the next line would discard whatever is still buffered.
-        // The whole answer IS the deliverable here (a truncated document is one an agent
-        // quotes onward as if complete), so the exit waits for the flush. Awaiting rather
-        // than exiting from the callback also keeps this branch from falling through into
-        // the covenant runner below while the write drains.
-        await new Promise((settle) => {
-            process.stdout.write(text, () => settle());
-        });
-        process.exit(0);
+        await emitAndExit(text);
     }
     catch (error) {
-        // stdout stays at zero bytes on this path (DOCS-02 §3-b): what cannot be answered is
-        // never answered halfway.
+        // stdout stays at zero bytes on this path: what cannot be answered is never answered
+        // halfway.
         process.stderr.write(`pdks docs: ${error instanceof Error ? error.message : String(error)}\n`);
         process.exit(2);
     }
 }
-if (args.length !== 2 || args[0] !== 'covenant' || args[1] !== 'check') {
-    process.stderr.write('usage: pdks covenant check | pdks init claude-code | pdks docs [topic]\n');
+if (args.length === 1 && args[0] === 'explain') {
+    try {
+        // Imported inside the try for the same reason `docs` is: the renderer pulls in both
+        // composition roots, and neither belongs on `covenant check`'s load path.
+        const { explain } = await import('./explain.js');
+        const { text } = await explain({ repoRoot: process.cwd() });
+        await emitAndExit(text);
+    }
+    catch (error) {
+        // stdout stays at zero bytes on this path: what cannot be answered is never answered
+        // halfway.
+        process.stderr.write(`pdks explain: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(2);
+    }
+}
+/**
+ * Read the `covenant check` flags as a domain, or null when the argv is not one of the
+ * three recognized forms: no flags is the staged diff, `--worktree` is the working tree,
+ * and `--range <base>..<head>` (or `...` for the merge-base reading) is a ref range.
+ */
+function parseCheckDomain(flags) {
+    if (flags.length === 0)
+        return { kind: 'staged' };
+    if (flags.length === 1 && flags[0] === '--worktree')
+        return { kind: 'worktree' };
+    if (flags.length !== 2 || flags[0] !== '--range')
+        return null;
+    const range = flags[1];
+    if (range.startsWith('--'))
+        return null;
+    const mergeBase = range.includes('...');
+    const separator = mergeBase ? '...' : '..';
+    const at = range.indexOf(separator);
+    if (at === -1)
+        return null;
+    const base = range.slice(0, at);
+    const head = range.slice(at + separator.length);
+    if (base === '' || head === '')
+        return null;
+    return { kind: 'range', base, head, ...(mergeBase && { ancestry: 'merge-base' }) };
+}
+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 init grok | pdks docs [topic]\n');
     process.exit(2);
 }
 try {
@@ -127,12 +180,13 @@ try {
     const { exitCode } = await runCovenantCheck({
         repoRoot: process.cwd(),
         ttyPrompt: openTtyPrompt(),
+        domain,
     });
     process.exit(exitCode);
 }
 catch (error) {
     // Any failure the runner did not already translate is unjudgeable — block, never
-    // crash into node's exit 1 (the session hook's catch-all posture, AC-7).
+    // crash into node's exit 1.
     process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
     process.exit(2);
 }

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

@@ -1,5 +1,5 @@
 /**
- * `runClaudeCodeHook` — the assembled session-surface judgment runner (DIST-01 §3-c).
+ * `runClaudeCodeHook` — the assembled session-surface judgment runner.
  *
  * The session counterpart of {@link runCovenantCheck}, and the one place where the Claude
  * Code adapter (tool vocabulary, up-translation) and the covenant package (dispatcher +
@@ -8,17 +8,14 @@
  * a delegator that calls this function. That is what makes the session surface installable:
  * a consumer registers a hook that resolves this package instead of copying assembly.
  *
- * Wiring shape: COVENANT-03 §4.4 + COVENANT-04d §4.5 registrations consumed through
- * ADAPTER-03 §4.1 `runAdapterPath`, with `dispatchCovenants` bound to the injected dispatch
- * seam. The protection-policy data (protectedPaths / disciplines / witness) is read from the
- * root data config through {@link loadConfig} (CONFIG-03), which also attaches the config
- * file to its own surface.
+ * The protection-policy data (protectedPaths / disciplines / witness) is read from the root
+ * data config through {@link loadConfig}, which also attaches the config file to its own
+ * surface.
  *
- * The valve is the TTL witness (COVENANT-06, moved behind the verdict by COVENANT-17)
- * judged over the JSONL transcript provider (ADAPTER-04). The judge body always spawns, and
- * only an outcome that translated to blocked consults the witness — `witnessed` rows are
- * would-block only. Its defence is provenance rather than secrecy: only a real human
- * utterance carries the transcript marking `findUserMessages()` admits.
+ * The valve is the TTL witness, judged over the JSONL transcript provider. The judge body
+ * always spawns, and only an outcome that translated to blocked consults the witness —
+ * `witnessed` rows are would-block only. Its defence is provenance rather than secrecy: only
+ * a real human utterance carries the transcript marking `findUserMessages()` admits.
  *
  * fail-closed: ANY failure — an unbuilt judge body, an unreadable stdin, a missing or
  * invalid config file — resolves to `{ exitCode: 2 }` with one `blocked` record under the
@@ -26,7 +23,15 @@
  * the cheapest bypass vector there is. Recovery from an unbuilt clone is `pnpm build` (it
  * mentions no protected path, so it is never blocked).
  */
-/** `runClaudeCodeHook` input (DIST-01 §3-c) — the `CovenantCheckSpec` shape, session side. */
+import { type CanonicalTranscript } from '@polydeukes/core';
+import { type CovenantRegistration } from '@polydeukes/covenant';
+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. */
     repoRoot: string;
@@ -37,9 +42,29 @@ export type ClaudeCodeHookSpec = {
     /** Overrides the resolved covenant dist directory (tests and assembly injection). */
     covenantDist?: string;
 };
+/** {@link assembleSessionRegistrations} input — what the session surface's assembly needs. */
+export type SessionAssemblySpec = {
+    config: ReturnType<typeof loadConfig>['config'];
+    rootDir: string;
+    /**
+     * The covenant surface the registrations are built from — the module the caller loaded
+     * from the resolved dist, so what judges a call is what that dist carries, and what
+     * `explain` renders is what would judge it.
+     */
+    covenant: CovenantModule;
+    /** The payload's transcript path. ABSENT leaves the transcript-mod registration out. */
+    transcriptPath?: string;
+    transcript?: CanonicalTranscript;
+    witness?: CovenantRegistration['witness'];
+};
 /**
- * The session-surface entry point: the post-hoc state comparison wrapped around the judgment
- * (COVENANT-14 §2-f).
+ * The session surface's registration set. One assembly, two consumers: the runner below
+ * dispatches it, `explain` renders it — so what a reader is shown is the table the judgment
+ * actually uses, never a second opinion about it.
+ */
+export declare function assembleSessionRegistrations(spec: SessionAssemblySpec): CovenantRegistration[];
+/**
+ * The session-surface entry point: the post-hoc state comparison wrapped around the judgment.
  *
  * The comparison sits OUTSIDE {@link judgeHookCall}'s fail-closed try on both ends. Inside
  * it, a comparison failure would become a blocked call — the opposite of a mechanism whose
@@ -51,6 +76,4 @@ export type ClaudeCodeHookSpec = {
  * 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>;