polydeukes 0.5.0 → 0.6.1

package/dist/claude-code-hook.js

@@ -26,11 +26,13 @@
 import { mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { COMMAND_ARGS, evaluatePrecedent, MUTATING_TOOLS, runAdapterPath, SHELL_TOOLS, transcriptFromJsonlFile, transcriptPathFromPayload, } from '@polydeukes/adapter-claude-code';
-import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, readRecords, } from '@polydeukes/core';
-import { findUnattributed, readBaseline, snapshotBaseline, ttlWitness, writeBaseline, } from '@polydeukes/covenant';
+import { COMMAND_ARGS, MUTATING_TOOLS, runAdapterPath, SHELL_TOOLS, sessionChannelReader, sessionSourceReader, transcriptFromJsonlFile, transcriptPathFromPayload, } from '@polydeukes/adapter-claude-code';
+import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, isPlainObject, normalizeProtectedPaths, readRecords, } from '@polydeukes/core';
+import { ttlWitness } from '@polydeukes/covenant';
+import { findUnattributed, readBaseline, snapshotBaseline, writeBaseline } from './baseline.js';
 import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
 import { loadConfig } from './load-config.js';
+import { sessionPreStateReader } from './pre-state-reader.js';
 /** The label every post-hoc state comparison row carries. */
 const BASELINE_LABEL = 'baseline';
 /**
@@ -109,7 +111,7 @@ function updateBaseline(spec) {
 function comparisonSpec(spec) {
     let config;
     try {
-        config = loadConfig(spec.repoRoot).config;
+        config = loadConfig({ rootDir: spec.repoRoot }).config;
     }
     catch {
         return undefined;
@@ -129,9 +131,9 @@ function comparisonSpec(spec) {
  */
 export function assembleSessionRegistrations(spec) {
     const { config, rootDir, covenant, transcriptPath, transcript, witness } = spec;
-    // 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 must NOT join this list: it lives deep
+    // The live transcript is the session a history declaration reads AND the one the witness
+    // reads, so erasing or forging it disables every history discipline while opening or
+    // shutting the human valve on the same file. It must NOT join this list: it lives deep
     // under HOME, and a path entry makes every ancestor protected — which measured as an
     // over-block refusing `cd /home/<user>`, `echo $HOME`, and every edit whose content
     // carried a bare `~`. The dedicated `transcript-mod` registration below covers that one
@@ -156,7 +158,7 @@ export function assembleSessionRegistrations(spec) {
         }),
         // 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.
+        // the valve and every history declaration already forfeited on the same absence.
         ...(transcriptPath === undefined
             ? []
             : [
@@ -179,17 +181,56 @@ export function assembleSessionRegistrations(spec) {
             rootDir,
             shellTools: SHELL_TOOLS,
             commandArgs: COMMAND_ARGS,
+            readPreState: sessionPreStateReader,
+            // One PreToolUse call is the whole observation, so the derived change set is a
+            // singleton and a change-set declaration cannot be judged here — it records `skipped`,
+            // the shape the commit surface gives a history declaration.
+            observesChangeSet: false,
             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. The
-            // adapter brings the evaluator for its own `subagent`/`tool` vocabulary; core owns
-            // `command`, which the compiler judges directly.
+            // The session itself, injected rather than its path: a declaration reading a
+            // `transcript` binding sees it flattened, and passing a path would leak JSONL
+            // knowledge into covenant.
             transcript,
-            evaluatePrecedent,
         }),
     ];
     return registrations;
 }
+/**
+ * This runtime's mutating+shell roster, rewritten onto the Claude vocabulary the adapter
+ * already judges. Claude names are not keys, so an existing Write/Edit/Bash envelope
+ * passes through. A name outside the table is left alone — that is a declared limit,
+ * recorded as the adapter's funnel pass, never a parse fault. The map lives here, not in
+ * the adapter, so the adapter stays Claude-vocabulary-only.
+ */
+const GROK_TOOL_NAME_MAP = {
+    write: 'Write',
+    search_replace: 'Edit',
+    run_terminal_command: 'Bash',
+};
+/**
+ * Rewrite Grok tool names in a raw PreToolUse payload. Invalid JSON is left as the original
+ * string so the existing fail-closed path still runs — this function must not throw.
+ */
+function rewriteGrokToolNames(rawPayload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawPayload);
+    }
+    catch {
+        return rawPayload;
+    }
+    if (!isPlainObject(parsed))
+        return rawPayload;
+    for (const key of ['tool_name', 'toolName']) {
+        const value = parsed[key];
+        if (typeof value !== 'string')
+            continue;
+        const mapped = GROK_TOOL_NAME_MAP[value];
+        if (mapped !== undefined)
+            parsed[key] = mapped;
+    }
+    return JSON.stringify(parsed);
+}
 /**
  * Judge one declared tool call before it runs. Async because the dispatcher spawns covenant
  * bodies — a synchronous runner would mean reimplementing the judge, which the
@@ -212,20 +253,20 @@ async function judgeHookCall(spec) {
             spec.telemetryPath ?? envTelemetryPath ?? join(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
         // 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);
+        const { config } = loadConfig({ rootDir: 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');
+        const rawPayload = rewriteGrokToolNames(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.
-        const transcriptPath = transcriptPathFromPayload(rawPayload);
-        const transcript = transcriptPath === undefined ? undefined : transcriptFromJsonlFile(transcriptPath);
+        const transcriptPath = transcriptPathFromPayload({ rawPayload });
+        const transcript = transcriptPath === undefined ? undefined : transcriptFromJsonlFile({ path: transcriptPath });
         // 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
@@ -260,6 +301,16 @@ async function judgeHookCall(spec) {
             transcript,
             witness,
         });
+        // The world axis: files read from disk under the repository root, channels read beside
+        // the session's transcript. The disk is the pre-edit state on this surface; the rule
+        // that the judged change's own `post` overrides it belongs to the judge, so the root
+        // supplies what it read and nothing more. No `changes` list either — one PreToolUse call
+        // is the whole observation, and the judge derives that set from the input.
+        const { files, channels } = covenant.supplySources({
+            plan: covenant.planSources({ registrations }),
+            read: sessionSourceReader({ repoRoot: spec.repoRoot }),
+            readChannel: sessionChannelReader({ transcriptPath }),
+        });
         return await runAdapterPath({
             rawPayload,
             telemetryPath: logPath,
@@ -268,6 +319,7 @@ async function judgeHookCall(spec) {
                 registrations,
                 telemetryPath: logPath,
                 transcript,
+                world: { files, channels },
             }),
         });
     }

package/dist/claude-code.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `polydeukes/claude-code` — the session surface's entry point.
+ *
+ * The delegator a consumer project's PreToolUse hook imports: one verb and its spec type.
+ */
+export { type ClaudeCodeHookOutcome, type ClaudeCodeHookSpec, runClaudeCodeHook, } from './claude-code-hook.ts';

package/dist/claude-code.js

@@ -0,0 +1,6 @@
+/**
+ * `polydeukes/claude-code` — the session surface's entry point.
+ *
+ * The delegator a consumer project's PreToolUse hook imports: one verb and its spec type.
+ */
+export { runClaudeCodeHook, } from './claude-code-hook.js';

package/dist/covenant-check.d.ts

@@ -10,26 +10,21 @@
  * fail-closed: a missing config, an unbuilt body, or a collector failure exits 2 with one
  * blocked record. An empty domain is an explicit pass with no records.
  */
+import { type Observation } from '@polydeukes/adapter-git';
 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';
 /**
  * Which observation of the commit surface a run judges. Only the collector differs between
  * them; the IR, the assembly, and the dispatcher are one path.
  *
- * `range` names its two refs. `ancestry: 'merge-base'` selects the `A...B` reading, whose
- * base is the two refs' common ancestor rather than `A` itself; the adapter that owns the
- * range grammar resolves it.
+ * The adapter that owns the git grammar owns the type: its supply body reads a path the way
+ * each observation sees the tree, and this root names the same fact for its callers.
  */
-export type CheckDomain = {
-    kind: 'staged';
-} | {
-    kind: 'worktree';
-} | {
-    kind: 'range';
-    base: string;
-    head: string;
-    ancestry?: 'merge-base';
+export type CheckDomain = Observation;
+/** {@link runCovenantCheck} result — the exit code the check process leaves with. */
+export type CovenantCheckOutcome = {
+    exitCode: 0 | 2;
 };
 /** `runCovenantCheck` input. */
 export type CovenantCheckSpec = {
@@ -74,6 +69,4 @@ export declare function assembleCommitRegistrations(spec: CommitAssemblySpec): C
  * diff by default, the working tree or a ref range on request. Async because the dispatcher
  * spawns covenant bodies. An empty domain is an explicit pass: nothing to judge, no records.
  */
-export declare function runCovenantCheck(spec: CovenantCheckSpec): Promise<{
-    exitCode: 0 | 2;
-}>;
+export declare function runCovenantCheck(spec: CovenantCheckSpec): Promise<CovenantCheckOutcome>;

package/dist/covenant-check.js

@@ -11,10 +11,11 @@
  * blocked record. An empty domain is an explicit pass with no records.
  */
 import { resolve } from 'node:path';
-import { collectRangeChanges, collectStagedChanges, collectWorktreeChanges, covenantInputFromStagedChanges, resolveGitAdapterSettings, STAGED_DELETE, STAGED_WRITE, } from '@polydeukes/adapter-git';
+import { collectRangeChanges, collectStagedChanges, collectWorktreeChanges, covenantInputFromStagedChanges, observationSourceReader, resolveGitAdapterSettings, STAGED_DELETE, STAGED_WRITE, } from '@polydeukes/adapter-git';
 import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, } from '@polydeukes/core';
 import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
 import { loadConfig } from './load-config.js';
+import { unobservedPreStateReader } from './pre-state-reader.js';
 /**
  * The TTY witness predicate, or undefined when no valve can exist (no witness configured
  * or no TTY seam). It fires on the first registration that broke, names it from the
@@ -61,7 +62,9 @@ function recordFailClosed(telemetryPath) {
  */
 export function assembleCommitRegistrations(spec) {
     const { config, rootDir, covenant, witness } = spec;
-    const { protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings(config.adapters?.git);
+    const { protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings({
+        namespace: config.adapters?.git,
+    });
     // Union of the common list and the git-additive one, common first so first-occurrence
     // dedupe is deterministic. The session hook reads the common list alone.
     const protectedPaths = normalizeProtectedPaths({
@@ -74,14 +77,13 @@ export function assembleCommitRegistrations(spec) {
             mutatingToolNames: [STAGED_WRITE, STAGED_DELETE],
             witness,
         }),
-        // No shell axis here, so command-family entries are left out. Context-family entries
-        // stay in: with no transcript the compiler gives them skip registrations, which record
-        // `skipped` on a match.
         ...covenant.compileDisciplineRegistrations({
-            disciplines: disciplines.filter((entry) => entry.forbidCommand === undefined),
+            disciplines,
             rootDir,
             shellTools: [],
             commandArgs: [],
+            readPreState: unobservedPreStateReader,
+            observesChangeSet: true,
             witness,
         }),
     ];
@@ -104,7 +106,7 @@ function settleConfig(spec) {
     let telemetryPath;
     try {
         telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
-        const { config } = loadConfig(spec.repoRoot);
+        const { config } = loadConfig({ rootDir: spec.repoRoot });
         telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
         return { settled: true, telemetryPath, config };
     }
@@ -118,12 +120,32 @@ function settleConfig(spec) {
  */
 function collectDomain(repoRoot, domain) {
     if (domain.kind === 'worktree')
-        return collectWorktreeChanges(repoRoot);
+        return collectWorktreeChanges({ repoRoot });
     if (domain.kind === 'range') {
         const separator = domain.ancestry === 'merge-base' ? '...' : '..';
-        return collectRangeChanges(repoRoot, `${domain.base}${separator}${domain.head}`);
+        return collectRangeChanges({
+            repoRoot,
+            range: `${domain.base}${separator}${domain.head}`,
+        });
+    }
+    return collectStagedChanges({ repoRoot });
+}
+/**
+ * The observation's change set: the paths of the collected changes that carry file-change
+ * evidence, in collection order.
+ *
+ * The same definition the judge derives its own set from, so both surfaces name the same
+ * changes. A deletion carries evidence and stays; a binary blob, which the collector gives
+ * a call with no evidence, produces no world of its own — listing it would hand the
+ * change-set relations a path no world can ever answer for.
+ */
+function changedPaths(changes) {
+    const paths = [];
+    for (const call of covenantInputFromStagedChanges({ changes }).toolCalls) {
+        if (call.fileChange !== undefined)
+            paths.push(call.fileChange.path);
     }
-    return collectStagedChanges(repoRoot);
+    return paths;
 }
 /**
  * Assemble the registrations and dispatch every collected change. Any throw here (an
@@ -132,7 +154,7 @@ function collectDomain(repoRoot, domain) {
 async function judgeChanges(spec, domain, telemetryPath, config, changes) {
     try {
         // Inside the try so an invalid adapter namespace fails closed.
-        const { enforce } = resolveGitAdapterSettings(config.adapters?.git);
+        const { enforce } = resolveGitAdapterSettings({ namespace: config.adapters?.git });
         // Real Node resolution of the covenant package, so the commit surface runs the same
         // judges the session hook does; tests inject a directory instead. Awaited before any
         // registration is composed, so a dist the barrel cannot load fails the run closed here
@@ -155,14 +177,24 @@ async function judgeChanges(spec, domain, telemetryPath, config, changes) {
             covenant,
             witness,
         });
+        // One plan and one supply for the run: the per-change loop shares them, so the tree is
+        // read once per named file rather than once per change. `changes` carries the whole
+        // observation because this surface dispatches one change at a time to keep telemetry at
+        // one row per file — a set no judge could derive from the input it is handed.
+        const { files } = covenant.supplySources({
+            plan: covenant.planSources({ registrations }),
+            read: observationSourceReader({ repoRoot: spec.repoRoot, observation: domain }),
+        });
+        const world = { files, changes: changedPaths(changes) };
         for (const change of changes) {
-            const input = covenantInputFromStagedChanges([change]);
+            const input = covenantInputFromStagedChanges({ changes: [change] });
             const { exitCode, results } = await covenant.dispatchCovenants({
                 stdinPayload: JSON.stringify(input),
                 registrations,
                 telemetryPath,
                 dispatcherLabel: 'covenant-check',
                 enforce,
+                world,
             });
             if (exitCode === 2)
                 blocked = true;

package/dist/covenant-module.d.ts

@@ -12,8 +12,8 @@
  * mirror where real Node resolution would always land on the healthy build.
  */
 import type * as covenant from '@polydeukes/covenant';
-/** The covenant surface both roots assemble against. */
-export type CovenantModule = typeof covenant;
+/** The covenant surface both roots assemble against — the members they call, and no more. */
+export type CovenantModule = Pick<typeof covenant, 'dispatchCovenants' | 'compileDisciplineRegistrations' | 'selfModRegistration' | 'shellModRegistration' | 'transcriptModRegistration' | 'planSources' | 'supplySources'>;
 /** Where real Node resolution puts the covenant package's built barrel. */
 export declare function resolveCovenantDist(): string;
 /**

package/dist/covenant-module.js

@@ -11,6 +11,14 @@
  * The `covenantDist` seam selects WHICH dist is imported, so a fixture can inject a gutted
  * mirror where real Node resolution would always land on the healthy build.
  */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -26,7 +34,7 @@ export function resolveCovenantDist() {
  */
 export async function loadCovenantModule(distDir) {
     try {
-        return (await import(pathToFileURL(join(distDir, 'index.js')).href));
+        return (await import(__rewriteRelativeImportExtension(pathToFileURL(join(distDir, 'index.js')).href)));
     }
     catch (error) {
         throw new Error(`the covenant judges could not be loaded from ${distDir} — run 'pnpm build' to rebuild them: ${error instanceof Error ? error.message : String(error)}`);

package/dist/docs/README.ko.md

@@ -0,0 +1,60 @@
+# 폴리데우케스 문서
+
+[English](./README.md) · **한국어**
+
+> AI 코딩 파트너와 함께 개발하기 위한 규율 프레임워크입니다. 궁금한 곳부터 읽으십시오.
+
+<a id="start-here"></a>
+## 여기서 시작하십시오
+
+| 하려는 것 | 읽을 문서 |
+|---|---|
+| 첫 눈에 보이는 판정을 보고 싶다 | [첫 판정](./tutorials/first-judgment.ko.md) — 설치하고 Claude Code를 배선한 뒤 보호된 편집이 판정되는 모습을 봅니다 |
+| Claude Code, Grok, git을 연결하고 싶다 | [표면 연결하기](./how-to/connect-surfaces.ko.md) — 세션과 커밋 배선, Grok 포함 |
+| 프로젝트 설정을 다듬고 싶다 | [프로젝트 설정하기](./how-to/configure-project.ko.md) — 발견, IDE 지원, advise와 block의 선택 |
+| 실제 규율을 쓰고 싶다 | [규율 작성하기](./how-to/write-disciplines.ko.md) — 실전 선언 예제, 특히 locale key pairing |
+| 차단이나 건너뜀에서 회복하고 싶다 | [문제 해결](./troubleshooting.ko.md) — fail-closed 상태, 증인 밸브, 로그 |
+| 이 프레임워크가 왜 있는지 알고 싶다 | [왜 폴리데우케스인가?](./why-polydeukes.ko.md) — 설계 백서 |
+| 이 문서에 기여하고 싶다 | [문서에 기여하기](./contributing.ko.md) — 영한 쌍, 안정 ID, 카탈로그, 검사 |
+
+<a id="reference"></a>
+## 레퍼런스
+
+설정 키, 하위 명령, 종료 코드를 설명합니다. 계획이 아니라 현재 동작을 기준으로 서술합니다.
+
+| 문서 | 답하는 것 |
+|---|---|
+| [설정 레퍼런스](./reference/configuration/index.ko.md) | `polydeukes.config.yaml`에 무엇을 넣을 수 있고 각 키가 무엇을 하는지 |
+| [`polydeukes` (`pdks` CLI)](./reference/packages/polydeukes.ko.md) | 패키지 계약. 서브커맨드는 [`reference/cli/`](./reference/cli/covenant-check.ko.md) |
+| [`@polydeukes/core`](./reference/packages/core.ko.md) | 프로토콜, 입력 IR, 설정 스키마, 텔레메트리 |
+| [`@polydeukes/covenant`](./reference/packages/covenant.ko.md) | 판정기입니다. 디스패처와 규율 라이브러리, 메타 약속, 밸브 |
+| [`@polydeukes/adapter-claude-code`](./reference/packages/adapter-claude-code.ko.md) | 세션 표면입니다. 훅 페이로드에서 입력 IR로 |
+| [`@polydeukes/adapter-git`](./reference/packages/adapter-git.ko.md) | 커밋 표면입니다. 스테이징·작업 트리·범위 diff에서 입력 IR로 |
+
+<a id="shape-of-the-thing"></a>
+## 한 페이지로 보는 구조
+
+폴리데우케스는 개발자나 AI 에이전트가 하려는 일을 판정하고 결과를 기록합니다.
+기본값으로는 작업을 차단하지 않습니다. 설계의 바탕은 다음 세 가지입니다.
+
+**약속은 가두기 위한 울타리가 아닙니다.** 여기서 확인하는 규율은 개발자가 이미 스스로 지켜 온 것들입니다. AI에게만큼 사람에게도 똑같이 적용되고, 프레임워크를 만든
+사람도 매일 그 판정을 받습니다.
+
+**판정과 차단은 별개의 결정입니다.** 선언된 규율은 적용 범위에 해당하는 호출마다 판정합니다.
+위반했을 때 호출을 차단할지는 별도로 정합니다. 기본값으로는 사유를 기록하고 호출을 계속합니다.
+작성자는 `enforce: block`으로 차단을 선택할 수 있습니다. 별도 선택 없이 차단하는 것은
+프레임워크 자체를 보호하는 경우뿐입니다.
+
+**모든 판정은 행 하나를 남깁니다.** `.polydeukes/roi.log`가 판정 결과마다 한 줄씩, 낱말 여섯 개짜리 어휘로 담습니다. 이 프로젝트가 자기 결함을 찾는
+방법이 그 기록입니다. 백서에 적힌 결함들도 전부 코드를 읽어서가 아니라 행을 세어서 나왔습니다.
+
+<a id="two-surfaces"></a>
+## 두 표면
+
+| 표면 | 판정 대상 | 배선 방법 | 대상 |
+|---|---|---|---|
+| **세션** | 도구 호출, 실행되기 전에 | `pdks init claude-code` 또는 `pdks init grok` | AI 파트너와 함께 개발하는 프로젝트 |
+| **커밋** | diff — 스테이징 영역, 작업 트리, ref 범위 | pre-commit 훅, 또는 필요할 때 직접 실행 | 혼자 개발하는 사람, 그리고 CI |
+
+커밋 판정기는 필요할 때 직접 실행할 수도 있습니다. 작업 후에는 `pdks covenant check --worktree`,
+PR 전에는 `--range`를 사용합니다. 같은 판정 기준으로 결과를 보고하며 증인 입력은 요청하지 않습니다.

package/dist/docs/README.md

@@ -0,0 +1,64 @@
+# Polydeukes documentation
+
+**English** · [한국어](./README.ko.md)
+
+> A development discipline framework for building alongside an AI coding partner. Start where your
+question is.
+
+<a id="start-here"></a>
+## Start here
+
+| If you want to | Read |
+|---|---|
+| Get to a first visible judgment | [First judgment](./tutorials/first-judgment.md) — install, wire Claude Code, and watch one protected edit get judged |
+| Connect Claude Code, Grok, or git | [Connect the surfaces](./how-to/connect-surfaces.md) — session and commit setup, including Grok |
+| Shape the project config | [Configure the project](./how-to/configure-project.md) — discovery, IDE support, and advise versus block |
+| Write a real discipline | [Write disciplines](./how-to/write-disciplines.md) — worked declarations, especially locale key pairing |
+| Recover from a block or skip | [Troubleshooting](./troubleshooting.md) — the fail-closed states, the witness valve, and the log |
+| Understand why the framework exists | [Why Polydeukes?](./why-polydeukes.md) — the design whitepaper |
+| Contribute to these docs | [Contributing](./contributing.md) — bilingual pairs, stable IDs, catalog, and checks |
+
+<a id="reference"></a>
+## Reference
+
+Every key, every subcommand, every exit code. These describe the present state only — nothing here
+is aspirational.
+
+| Document | Answers |
+|---|---|
+| [Configuration reference](./reference/configuration/index.md) | What may go in `polydeukes.config.yaml`, and what each key does |
+| [`polydeukes` (the `pdks` CLI)](./reference/packages/polydeukes.md) | Package contract; subcommands live under [`reference/cli/`](./reference/cli/covenant-check.md) |
+| [`@polydeukes/core`](./reference/packages/core.md) | The protocol, the input IR, the config schema, telemetry |
+| [`@polydeukes/covenant`](./reference/packages/covenant.md) | The judge — dispatcher, discipline library, meta-covenants, the valve |
+| [`@polydeukes/adapter-claude-code`](./reference/packages/adapter-claude-code.md) | Session surface — hook payloads become the input IR |
+| [`@polydeukes/adapter-git`](./reference/packages/adapter-git.md) | Commit surface — staged, worktree, and range diffs become the input IR |
+
+<a id="shape-of-the-thing"></a>
+## The shape of the thing, in one page
+
+Polydeukes judges what a developer or an AI agent is about to do, records the verdict, and by
+default lets the work proceed. Three ideas carry the rest.
+
+**A covenant is a promise, not a fence.** The disciplines it enforces are the ones a good developer
+already imposes on themselves. They bind the human exactly as much as the AI, and the framework's
+own authors get judged by them daily.
+
+**Judging and stopping are separate decisions.** Every declared discipline is judged on every
+matching call. What a break then does is a second question: by default it is recorded with its
+reason and the call continues. `enforce: block` is a promotion the author chooses. The only things
+that stop a call unasked are the framework's own protections.
+
+**Every judgment leaves a row.** `.polydeukes/roi.log` holds one line per verdict, in a vocabulary
+of six words. That record is how this project finds its own defects — including the ones described
+in the whitepaper, which were all found by counting rows rather than by reading code.
+
+<a id="two-surfaces"></a>
+## Two surfaces
+
+| Surface | Judges | Wired by | For |
+|---|---|---|---|
+| **Session** | A tool call, before it runs | `pdks init claude-code` or `pdks init grok` | A project developed with an AI partner |
+| **Commit** | A diff — staged, the working tree, or a ref range | A pre-commit hook, or run on demand | A human developing alone, and CI |
+
+The commit judge also answers on demand: `pdks covenant check --worktree` after a task, `--range`
+before a PR. Same verdict a commit would receive, delivered as a report with no prompt and no gate.