polydeukes 0.0.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyung Soo Seung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,73 @@
+# 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로 번역하고, 세션 훅이 띄우는(spawn) 바로 그 판정 본체로 보냅니다.
+  판정기는 하나, 표면은 여럿입니다. 맥락족 규율(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

package/README.md

@@ -1,22 +1,77 @@
 # polydeukes
 
-> A harness framework for developing alongside an AI coding partner.
+**English** · [한국어](https://github.com/huskyhoochu/polydeukes/blob/main/packages/polydeukes/README.ko.md)
 
-**Pre-alpha — design stage.** This package currently reserves the name on npm and exposes only version metadata. The core, guard, ledger, kb, and verify modules are in design.
+> 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.
 
-Polydeukes externalizes the discipline a developer applies to themselves — test-first, verify-before-commit, record decisions, don't repeat mistakes — into deterministic machinery shared with an AI partner, rather than prompt-level requests. The framing is partnership, not control.
+**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.
 
-See the [project repository](https://github.com/huskyhoochu/polydeukes) for the architecture blueprint and design rationale.
+## What lives here
 
-## Planned packages
+- **`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
+  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
+  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.
 
-| Package | Role |
-|---------|------|
-| `@polydeukes/core` | Guard protocol, config loader, transcript interface |
-| `@polydeukes/guard` | Deterministic PreToolUse hooks + self-mod meta-guard |
-| `@polydeukes/ledger` | Work tracking; completion authority moves from "I'm done" to "the actions passed" |
-| `@polydeukes/kb` | Local SQLite + FTS5 knowledge store |
-| `@polydeukes/verify` | Multi-agent adversarial verification |
+## 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
 

package/dist/bin.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * `pdks` / `polydeukes` — the umbrella bin (ADAPTER-git §4.3).
+ *
+ * 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).
+ *
+ * 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).
+ */
+export {};

package/dist/bin.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * `pdks` / `polydeukes` — the umbrella bin (ADAPTER-git §4.3).
+ *
+ * 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).
+ *
+ * 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).
+ */
+import { closeSync, openSync, readSync, writeSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Bind the TTY prompt seam to /dev/tty, or undefined when no terminal exists. The runner
+ * composes the prompt text (it is the side that knows what broke); this shim only writes
+ * it and reads the line back.
+ */
+function openTtyPrompt() {
+    let fd;
+    try {
+        fd = openSync('/dev/tty', 'r+');
+    }
+    catch {
+        return undefined;
+    }
+    return (prompt) => {
+        try {
+            writeSync(fd, prompt);
+            const buffer = Buffer.alloc(4096);
+            const bytes = readSync(fd, buffer, 0, buffer.length, null);
+            return buffer
+                .subarray(0, Math.max(bytes, 0))
+                .toString('utf-8')
+                .replace(/\r?\n$/, '');
+        }
+        catch {
+            return null;
+        }
+        finally {
+            try {
+                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.
+            }
+        }
+    };
+}
+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.
+        const { initClaudeCode } = await import('./init-claude-code.js');
+        const { created, skipped } = initClaudeCode({ 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) {
+        // 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.
+        process.stderr.write(`pdks init claude-code 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.
+        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);
+    }
+    catch (error) {
+        // stdout stays at zero bytes on this path (DOCS-02 §3-b): 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');
+    process.exit(2);
+}
+try {
+    // Loaded here rather than at the top of the file. This runner statically pulls in the
+    // git adapter, the core, and the judge, so a top-level import made every subcommand
+    // wait on all three resolving — and `docs` is the one that has to answer in a tree
+    // where they do not, since a package installed but never built is exactly the state
+    // `pdks docs install` is asked about. The catch below already answers for whatever
+    // this import cannot do, at the same exit 2 it answers everything else with.
+    const { runCovenantCheck } = await import('./covenant-check.js');
+    const { exitCode } = await runCovenantCheck({
+        repoRoot: process.cwd(),
+        ttyPrompt: openTtyPrompt(),
+    });
+    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).
+    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

@@ -0,0 +1,47 @@
+/**
+ * `runClaudeCodeHook` — the assembled session-surface judgment runner (DIST-01 §3-c).
+ *
+ * The session counterpart of {@link runCovenantCheck}, and the one place where the Claude
+ * Code adapter (tool vocabulary, up-translation) and the covenant package (dispatcher +
+ * judge bodies) meet. Packages stay one-way — each depends only on core — so their
+ * composition lives here, in the umbrella, and the repository's PreToolUse hook shrinks to
+ * 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 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.
+ *
+ * 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
+ * `hook` label. Nothing throws: an uncaught rejection would exit the delegator non-blocking,
+ * 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. */
+export type ClaudeCodeHookSpec = {
+    /** Repository root — config discovery and discipline glob scoping both anchor here. */
+    repoRoot: string;
+    /** One raw PreToolUse payload. ABSENT means read fd 0 (the hook's real stdin). */
+    rawPayload?: string;
+    /** Overrides the config's telemetry log path (tests and assembly injection). */
+    telemetryPath?: string;
+    /** Overrides the resolved covenant dist directory (tests and assembly injection). */
+    covenantDist?: string;
+};
+/**
+ * Judge one declared tool call before it runs (DIST-01 §3-c). Async because the dispatcher
+ * spawns covenant bodies (CORE-01) — a synchronous runner would mean reimplementing the
+ * judge, which the single-dispatcher principle forbids.
+ */
+export declare function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<{
+    exitCode: 0 | 2;
+}>;

package/dist/claude-code-hook.js

@@ -0,0 +1,233 @@
+/**
+ * `runClaudeCodeHook` — the assembled session-surface judgment runner (DIST-01 §3-c).
+ *
+ * The session counterpart of {@link runCovenantCheck}, and the one place where the Claude
+ * Code adapter (tool vocabulary, up-translation) and the covenant package (dispatcher +
+ * judge bodies) meet. Packages stay one-way — each depends only on core — so their
+ * composition lives here, in the umbrella, and the repository's PreToolUse hook shrinks to
+ * 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 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.
+ *
+ * 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
+ * `hook` label. Nothing throws: an uncaught rejection would exit the delegator non-blocking,
+ * the cheapest bypass vector there is. Recovery from an unbuilt clone is `pnpm build` (it
+ * mentions no protected path, so it is never blocked).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { COMMAND_ARGS, evaluatePrecedent, MUTATING_TOOLS, runAdapterPath, SHELL_TOOLS, transcriptFromJsonlFile, transcriptPathFromPayload, } from '@polydeukes/adapter-claude-code';
+import { appendRecordFailOpen, normalizeProtectedPaths } from '@polydeukes/core';
+import { compileDisciplineRegistrations, dispatchCovenants, transcriptModRegistration, ttlWitness, } from '@polydeukes/covenant';
+import { loadConfig } from './load-config.js';
+/**
+ * Compose a judge body path and prove it exists (CONFIG-06b §4.2). A body module that was
+ * never built makes node exit 1 — the same code a real break verdict returns — so nothing
+ * downstream can separate an unjudgeable run from a judged one. The proof therefore belongs
+ * to the act of composing the path, and a body this assembly composes no path for is never
+ * proven: the throw lands in the fail-closed catch below, one blocked record and exit 2.
+ */
+function provenBodyPath(distDir, fileName) {
+    const modulePath = join(distDir, fileName);
+    if (!existsSync(modulePath)) {
+        throw new Error(`judge body ${modulePath} is missing — run 'pnpm build' to rebuild it`);
+    }
+    return modulePath;
+}
+/**
+ * Judge one declared tool call before it runs (DIST-01 §3-c). Async because the dispatcher
+ * spawns covenant bodies (CORE-01) — a synchronous runner would mean reimplementing the
+ * judge, which the single-dispatcher principle forbids.
+ */
+export async function runClaudeCodeHook(spec) {
+    // Env-first telemetry precedence (E2E contract), settled BEFORE any failure branch: a
+    // config that never loads still has somewhere to write its one blocked row. The config
+    // value applies after the load succeeds.
+    //
+    // Computed INSIDE the try even though it must run first, because `join` throws on a
+    // non-string repoRoot and this function's contract is that nothing escapes it — a rejection
+    // would exit a delegator non-blocking, which is the cheapest bypass there is. A throw here
+    // leaves `telemetryPath` undefined, which the catch tolerates: there is no root to write a
+    // row under anyway (PR #46 review).
+    let telemetryPath;
+    try {
+        const envTelemetryPath = process.env.POLYDEUKES_TELEMETRY_PATH;
+        telemetryPath =
+            spec.telemetryPath ?? envTelemetryPath ?? join(spec.repoRoot, '.polydeukes', 'roi.log');
+        // Discovery + parse + validation are the loader's job; a throw here (absent, ambiguous,
+        // unparseable, or invalid config) falls into the fail-closed catch.
+        const { config } = loadConfig(spec.repoRoot);
+        telemetryPath =
+            spec.telemetryPath ?? envTelemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
+        // Settled for the rest of the happy path. The `let` above exists so the catch can still
+        // record when a failure lands before this point; a closure cannot narrow it, so the
+        // dispatch seam below takes this const instead.
+        const logPath = telemetryPath;
+        const rawPayload = spec.rawPayload ?? readFileSync(0, 'utf-8');
+        // The transcript path travels in the raw payload only — up-translation drops it, so the
+        // adapter reads it from the string. Every failure narrows to `undefined`, which leaves
+        // the dispatcher on its `noopTranscript` default: lost evidence closes the valve rather
+        // than opening it (ADAPTER-04 §4.4).
+        const transcriptPath = transcriptPathFromPayload(rawPayload);
+        const transcript = transcriptPath === undefined ? undefined : transcriptFromJsonlFile(transcriptPath);
+        // The live transcript is the evidence channel the context family reads AND the one the
+        // witness reads, so erasing or forging it disables every context discipline while
+        // opening or shutting the human valve on the same file. It lives outside the repository,
+        // so no config `protectedPaths` entry can reach it — and since COVENANT-07c it does NOT
+        // join this list either. A file deep under HOME makes HOME itself a protected ANCESTOR,
+        // which measured as the COVENANT-13 over-block: `cd /home/<user>` refused for two weeks,
+        // and the 07b attempt to register the home spellings alongside only widened that to
+        // `echo $HOME` and every edit whose content carried a bare `~`. Assembly knows the path
+        // AND the home value, so assembly registers a dedicated `matches` predicate over that
+        // ONE file instead (transcript-mod, below): equality-only — never an ancestor — with the
+        // `~`/`$HOME`/`${HOME}`/`~<user>` spellings closed as data, reads absolved by the
+        // read-only allowlist, and ancestor destruction outside the repository declared out of
+        // observation scope (07c §2: the agent's own deny policy owns what no repo-scoped judge
+        // can). The witness valve applies to it like any other registration.
+        const protectedPaths = normalizeProtectedPaths({
+            protectedPaths: config.protectedPaths ?? [],
+        });
+        // One witness predicate shared by every registration: a witness is a session-wide
+        // permission the human granted, not a per-covenant one. Absent `witness` config leaves
+        // this undefined, and no verdict can be witnessed open at all. The predicate receives
+        // the transcript as its second argument from the dispatcher (CORE-04 seam), which is why
+        // the transcript is injected below rather than captured here.
+        const witness = config.witness === undefined
+            ? undefined
+            : ttlWitness({
+                token: config.witness.token,
+                // Minutes are the human-facing unit in config; the predicate takes milliseconds.
+                // Core passes the value through verbatim, so the conversion belongs to assembly.
+                ttlMs: config.witness.ttlMinutes * 60_000,
+            });
+        // The judge bodies are the covenant package's dist executables — resolved through the
+        // real package (never a test alias), so the session surface spawns the same judges the
+        // commit surface does. An injected directory overrides that resolution: `createRequire`
+        // is real Node resolution and always lands on the real build, which no fixture tree can
+        // take a body away from.
+        const covenantDist = spec.covenantDist ?? dirname(createRequire(import.meta.url).resolve('@polydeukes/covenant'));
+        // Only the two unconditional registrations compose their paths here. The transcript-mod
+        // and discipline bodies are composed inside the conditions that decide whether their
+        // registrations exist at all — proving a body this run will never spawn would close a
+        // call over a file it was never going to use (CONFIG-06b §4.2 corollary).
+        const selfModBody = provenBodyPath(covenantDist, 'self-mod-body.js');
+        const shellModBody = provenBodyPath(covenantDist, 'shell-mod-body.js');
+        const disciplines = config.disciplines ?? [];
+        const pathArgs = protectedPaths.flatMap((path) => ['--protected-path', path]);
+        const registrations = [
+            {
+                label: 'self-mod',
+                protectedPaths,
+                body: {
+                    command: process.execPath,
+                    args: [
+                        selfModBody,
+                        ...pathArgs,
+                        ...MUTATING_TOOLS.flatMap((tool) => ['--mutating-tool', tool]),
+                    ],
+                },
+                witness,
+            },
+            {
+                label: 'shell-mod',
+                protectedPaths,
+                body: {
+                    command: process.execPath,
+                    args: [
+                        shellModBody,
+                        ...pathArgs,
+                        ...SHELL_TOOLS.flatMap((tool) => ['--shell-tool', tool]),
+                        ...COMMAND_ARGS.flatMap((arg) => ['--command-arg', arg]),
+                    ],
+                },
+                witness,
+            },
+            // The transcript's own registration (COVENANT-07c). Routing is the matches predicate,
+            // never path mention, so the home directory cannot become a protected ancestor. No
+            // transcript in the payload means nothing to protect — the valve and the context
+            // family already forfeited on the same absence.
+            ...(transcriptPath === undefined
+                ? []
+                : [
+                    transcriptModRegistration({
+                        transcriptPath,
+                        // The env value first, since that is what the judged shell expands `~` and
+                        // `$HOME` from. `homedir()` reads the same passwd entry bash falls back to when
+                        // HOME is unset, so a hook spawned without an environment (a service manager,
+                        // `env -i`) keeps judging the home spellings instead of silently going
+                        // absolute-only — an inert spelling closure looks identical to a passing call.
+                        home: process.env.HOME ?? homedir(),
+                        bodyCommand: process.execPath,
+                        bodyModulePath: provenBodyPath(covenantDist, 'transcript-mod-body.js'),
+                        shellTools: SHELL_TOOLS,
+                        commandArgs: COMMAND_ARGS,
+                        mutatingTools: MUTATING_TOOLS,
+                        witness,
+                    }),
+                ]),
+            // The body path is passed as a thunk, so the proof fires only where the compiler
+            // actually composes a body. Entry count cannot stand in for that: an entry may compile
+            // to a body-less skip (a `requirePrecedent` one whenever no transcript came with the
+            // payload), and the compiler appends the body-less `shell-unjudgeable` backstop even
+            // for zero entries — gating the call itself would drop that record and turn an
+            // uncomputable shell write back into a silent pass, undoing COVENANT-10b.
+            ...compileDisciplineRegistrations({
+                disciplines,
+                rootDir: spec.repoRoot,
+                bodyCommand: process.execPath,
+                bodyModulePath: () => provenBodyPath(covenantDist, 'discipline-body.js'),
+                shellTools: SHELL_TOOLS,
+                commandArgs: COMMAND_ARGS,
+                witness,
+                // Context-family evidence is evaluated here, at assembly: a spawned body cannot hold
+                // a transcript, and passing a path would leak JSONL knowledge into covenant
+                // (COVENANT-13 §4.4). The adapter brings the evaluator for its own `subagent`/`tool`
+                // vocabulary; core owns `command`, which the compiler judges directly.
+                transcript,
+                evaluatePrecedent,
+            }),
+        ];
+        // This assembly is versioned with the umbrella; the covenant dist it composes against is
+        // resolved from the installation graph, so a workspace nobody rebuilt pairs a new
+        // assembly with an old compiler — and an old compiler stores the body-path thunk itself
+        // where a string belongs. `spawn` does not reject a non-string argv entry — it
+        // stringifies it — so the judge would be spawned on the thunk's own source text, exit 1,
+        // and be recorded as a VERDICT under a discipline's label. Assert the shape and let the
+        // fail-closed catch answer instead.
+        for (const registration of registrations) {
+            if (registration.body !== undefined && typeof registration.body.args?.[0] !== 'string') {
+                throw new Error(`covenant dist predates the lazy body-path convention (registration '${registration.label}') — run 'pnpm build'`);
+            }
+        }
+        return await runAdapterPath({
+            rawPayload,
+            telemetryPath: logPath,
+            dispatch: (stdinPayload) => dispatchCovenants({ stdinPayload, registrations, telemetryPath: logPath, transcript }),
+        });
+    }
+    catch (error) {
+        process.stderr.write(`covenant hook failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
+        // Honor the one-call-one-record invariant with a blocked record under the assembly's own
+        // label (COVENANT-07 §4.3) — never a judge's, since no judge answered. `undefined` means
+        // the failure landed before a path could even be composed (a non-string repoRoot), where
+        // there is nowhere to write and nothing to attribute the row to.
+        if (telemetryPath !== undefined) {
+            appendRecordFailOpen(telemetryPath, { event: 'blocked', label: 'hook', subject: '-' });
+        }
+        return { exitCode: 2 };
+    }
+}