polydeukes 0.0.1 → 0.4.0

package/dist/covenant-check.js

@@ -0,0 +1,262 @@
+/**
+ * `pdks covenant check` — the assembled commit-surface judgment runner (ADAPTER-git §4.3).
+ *
+ * This is the commit-surface counterpart of the session hook's composition root: the one
+ * umbrella-owned place where the git adapter (staged-diff vocabulary), the covenant
+ * dispatcher, and the config loader meet. Assembly order mirrors the session hook —
+ * loadConfig → normalizeProtectedPaths → collect/translate → dispatchCovenants — and the
+ * judge bodies it spawns are the very same covenant dist executables, so a staged change
+ * receives the same verdict a session tool call would (AC-4 same-judge).
+ *
+ * Each staged change is dispatched as its own single-change input: one staged file is
+ * the commit surface's analogue of one session tool call, so telemetry stays N:N (AC-6)
+ * and `gain` reads a per-file subject rather than one opaque batch line.
+ *
+ * The valve is a TTY prompt (PRD §4.4 decision A): the injected `ttyPrompt` seam returns
+ * the line a human typed at the terminal, compared against the config witness token in
+ * FULL (COVENANT-15 — substring acceptance is forbidden). The seam's absence models a
+ * non-interactive environment (CI, an AI-spawned git commit): no prompt, no witness —
+ * the valve is structurally reachable only by a human at a terminal, which is the
+ * commit-surface translation of "only a human utterance opens the session valve". The
+ * answer is cached so one commit prompts at most once, and nothing is ever persisted —
+ * a state file would be an agent-forgeable surface (PRD §7).
+ *
+ * fail-closed: a missing/invalid config, an unbuilt judge body, or a collector failure
+ * exits 2 with one blocked record. The telemetry path is settled before the first failure
+ * branch can be taken (ADAPTER-git-b §4.1), so the record has somewhere to land even when
+ * the config that names its path never loaded. An empty staging area is an explicit pass
+ * (nothing to judge — the dispatcher precedent of zero matches, zero records).
+ */
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { collectStagedChanges, covenantInputFromStagedChanges, resolveGitAdapterSettings, STAGED_DELETE, STAGED_WRITE, } from '@polydeukes/adapter-git';
+import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, } from '@polydeukes/core';
+import { compileDisciplineRegistrations, dispatchCovenants, } from '@polydeukes/covenant';
+import { loadConfig } from './load-config.js';
+/**
+ * Build the witness predicate for the TTY valve, or undefined when no valve can exist
+ * (no witness configured, or no TTY seam — both leave the dispatcher with no way to open
+ * one at all). The valve IS the witness: the judge has already broken, and the human at
+ * the terminal supplies the pass condition themselves, sudo-style. The prompt fires
+ * lazily on the first registration that actually BROKE and names it from the dispatcher's
+ * context (COVENANT-17 §4.5) — the label and the MATCHED entry, the same subject the
+ * telemetry row carries, so screen and log never disagree. The human reads what broke,
+ * on what, and how far one answer reaches. The verdict is cached: one commit, at most
+ * one prompt, full-token equality only — and the token itself is never printed, or
+ * typing it from memory would become copying it off the screen.
+ *
+ * Both comparison sides are trimmed, mirroring the session valve: `ttlWitness` trims the
+ * config token at assembly precisely because config validation accepts a padded value,
+ * and it compares the utterance's first line trimmed — without the same normalisation
+ * here, one padded token would open the session surface and permanently shut this one
+ * (PR #41 review). The cache latches CLOSED before the seam is consulted: a throwing
+ * seam must not retry on the next broken registration, or the prompt's own commit-wide
+ * promise becomes a lie (AC §5.3 one commit, at most one prompt).
+ */
+function ttyWitnessValve(witness, ttyPrompt) {
+    if (witness === undefined || ttyPrompt === undefined)
+        return undefined;
+    const token = witness.token.trim();
+    let verdict;
+    return (_input, _transcript, context) => {
+        if (verdict === undefined) {
+            const prompt = `covenant: '${context.label}' broke on the staged change matching '${context.subject}'.\n` +
+                'answering opens the valve for the whole commit, not just this change.\n' +
+                'type the agreed token in full to open it (enter to refuse): ';
+            verdict = false;
+            const answer = ttyPrompt(prompt);
+            verdict = answer !== null && answer.trim() === token;
+        }
+        return verdict;
+    };
+}
+/**
+ * Compose a judge body's module path and prove the file is there (CONFIG-06b §4.2).
+ * Spawning an absent module succeeds and its child exits 1 — the code a break verdict
+ * returns — so a judge that ran no line would arrive as a violation and, under `advise`,
+ * be waved through. Nothing downstream can separate the two (`translateExitCode` sees
+ * that number alone), so the proof happens here, before the spawn. Producing the path
+ * and proving it are one step on purpose: a path that skipped the proof cannot be
+ * constructed, and only the bodies this surface actually composes are proven.
+ */
+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;
+}
+/**
+ * One blocked record for a run that failed closed before any dispatch could judge.
+ *
+ * The write goes through `appendRecordFailOpen` rather than the mkdir-free `appendRecord`:
+ * a repository that has never been judged has no `.polydeukes/` directory — the shape
+ * `pdks init` leaves every consumer in — and the raw append would fail open on ENOENT,
+ * turning the very first fail-closed run into an unrecorded block. The wrapper carries both
+ * the parent-directory guarantee and the fail-open contract, so a telemetry failure still
+ * never softens the blocking exit. An undefined path is tolerated here because a non-string
+ * `repoRoot` leaves no root to write a row under.
+ */
+function recordFailClosed(telemetryPath) {
+    if (telemetryPath === undefined)
+        return;
+    appendRecordFailOpen(telemetryPath, {
+        event: 'blocked',
+        label: 'covenant-check',
+        subject: '-',
+    });
+}
+/**
+ * Judge the staged changes of `repoRoot` exactly as the session surface would
+ * (ADAPTER-git §4.3). 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 runCovenantCheck(spec) {
+    // Telemetry precedence settled BEFORE the failure branch (session-hook precedent): a config
+    // that never loads still has somewhere to write its one blocked row, and the config value
+    // replaces the provisional default once the load succeeds. The provisional default spells
+    // itself with the loader's own constant, so both terms converge on one source.
+    //
+    // Computed INSIDE the try even though it must run first, because `resolve` throws on a
+    // non-string repoRoot and that throw must not escape as a rejection. It leaves
+    // `telemetryPath` undefined, which the catch tolerates: there is no root to write a row
+    // under anyway.
+    //
+    // Both terms compose with `resolve`, never `join`: a relative repoRoot would leave the
+    // provisional path relative and the post-load one absolute, so a run whose config failed
+    // to load would write its row to a different file than the same repository's judgment
+    // rows — and a relative path is re-read against the cwd at append time, which need not
+    // be the cwd this ran under. The bin always passes `process.cwd()`, so the divergence is
+    // reachable only through this exported function, whose `repoRoot` promises no
+    // absoluteness (PR #57 review).
+    let telemetryPath;
+    let config;
+    try {
+        telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
+        ({ config } = loadConfig(spec.repoRoot));
+        telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
+    }
+    catch (error) {
+        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
+        recordFailClosed(telemetryPath);
+        return { exitCode: 2 };
+    }
+    let changes;
+    try {
+        changes = collectStagedChanges(spec.repoRoot);
+    }
+    catch (error) {
+        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
+        recordFailClosed(telemetryPath);
+        return { exitCode: 2 };
+    }
+    if (changes.length === 0) {
+        return { exitCode: 0 };
+    }
+    // Everything from here on is judgment assembly and dispatch: any throw (an unbuilt or
+    // unresolvable covenant dist, a registration-build failure) is unjudgeable and must
+    // both block AND leave one blocked record — the session hook's one-call-one-record
+    // invariant, which an unrecorded propagation to the bin's catch would narrow
+    // (review F5).
+    try {
+        // The adapter namespace validator throws on unknown levels/keys (CONFIG-06 §4.2) —
+        // resolved inside this try so a misconfiguration fails closed, never softens.
+        const { enforce, protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings(config.adapters?.git);
+        // The commit surface judges the UNION of the common list and the git namespace's
+        // additive one (CONFIG-08 §4.2) — common first, so first-occurrence dedupe inside
+        // the one normalization pass is deterministic. The session hook reads the common
+        // list alone; that asymmetry is the contract, not an omission.
+        const protectedPaths = normalizeProtectedPaths({
+            protectedPaths: [...(config.protectedPaths ?? []), ...gitAdditivePaths],
+        });
+        // The judge bodies are the covenant package's dist executables — resolved through
+        // the real package (never a test alias), so the commit surface spawns the same
+        // judges the session hook does. An injected directory overrides that resolution:
+        // `createRequire` is real Node resolution and always lands on the real build, which
+        // no fixture can take a body away from.
+        const covenantDist = spec.covenantDist ?? dirname(createRequire(import.meta.url).resolve('@polydeukes/covenant'));
+        // Under advise the TTY valve is structurally absent (CONFIG-06 §4.6): a verdict
+        // already passes, so there is nothing to witness and the prompt must never fire.
+        const witness = enforce === 'advise' ? undefined : ttyWitnessValve(config.witness, spec.ttyPrompt);
+        const disciplines = config.disciplines ?? [];
+        const registrations = [
+            {
+                label: 'self-mod',
+                protectedPaths,
+                body: {
+                    command: process.execPath,
+                    args: [
+                        provenBodyPath(covenantDist, 'self-mod-body.js'),
+                        ...protectedPaths.flatMap((path) => ['--protected-path', path]),
+                        ...[STAGED_WRITE, STAGED_DELETE].flatMap((tool) => ['--mutating-tool', tool]),
+                    ],
+                },
+                witness,
+            },
+            // Command-family entries are excluded: the commit surface has no shell axis (a
+            // staged diff carries no commands), so registering them would be spawn waste by
+            // design (PRD §2) — a vacuous exclusion, hence recorded nowhere. Path and delta
+            // families judge the staged fileChanges as-is.
+            //
+            // Context-family entries are NOT filtered out any more. No transcript is injected
+            // here, so the compiler gives them skip registrations, and a skip records one
+            // `skipped` exactly when its trigger matches a staged change (COVENANT-13 §4.5).
+            // The commit surface stopped being a special case: an absent evidence channel gets
+            // the same disposition on both surfaces, and the scope gate comes free with the
+            // routing every registration already carries.
+            //
+            // The body path is passed as a thunk, so the proof fires only where the compiler
+            // actually composes a body (CONFIG-06b §4.2 corollary). Entry count cannot stand in
+            // for that: an entry may compile to a body-less skip — every `requirePrecedent` one
+            // does here, since this surface injects neither transcript nor evaluator — and the
+            // compiler appends the body-less `shell-unjudgeable` backstop even for zero entries,
+            // so gating the call itself would drop that record.
+            ...compileDisciplineRegistrations({
+                disciplines: disciplines.filter((entry) => entry.forbidCommand === undefined),
+                rootDir: spec.repoRoot,
+                bodyCommand: process.execPath,
+                bodyModulePath: () => provenBodyPath(covenantDist, 'discipline-body.js'),
+                shellTools: [],
+                commandArgs: [],
+                witness,
+            }),
+        ];
+        // The commit surface resolves the compiler through the installed package, so a
+        // workspace whose dist predates the lazy body-path convention hands back the thunk
+        // itself where a string belongs. `spawn` stringifies rather than rejects it, which
+        // would spawn the judge on the thunk's own source text and record the exit 1 as a
+        // verdict under a discipline's label — the confusion this ticket removes, arriving
+        // through the build-skew door. Assert the shape and let the fail-closed catch answer.
+        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'`);
+            }
+        }
+        let blocked = false;
+        let advisedCount = 0;
+        for (const change of changes) {
+            const input = covenantInputFromStagedChanges([change]);
+            const { exitCode, results } = await dispatchCovenants({
+                stdinPayload: JSON.stringify(input),
+                registrations,
+                telemetryPath,
+                dispatcherLabel: 'covenant-check',
+                enforce,
+            });
+            if (exitCode === 2)
+                blocked = true;
+            advisedCount += results.filter((result) => result.event === 'advised').length;
+        }
+        if (advisedCount > 0) {
+            process.stderr.write(`covenant advisory (enforce: advise): ${advisedCount} verdict(s) recorded, commit allowed\n`);
+        }
+        return { exitCode: blocked ? 2 : 0 };
+    }
+    catch (error) {
+        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
+        recordFailClosed(telemetryPath);
+        return { exitCode: 2 };
+    }
+}

package/dist/docs/configuration.md

@@ -0,0 +1,95 @@
+# Configuring Polydeukes
+
+**English** · [한국어](./configuration.ko.md)
+
+> Alpha. This guide covers the config surface as shipped today (schema v2, loader, and
+> the four built-in discipline predicates). Fields and predicates will grow; what is
+> written here is tested and enforced now.
+
+`polydeukes.config.yaml` is the one file where a project declares its disciplines — the
+promises the human and the AI partner both agree to be bound by. It is **data, not code**:
+nothing in it can compute, so nothing in it can lie. The core validates it, the covenant
+package enforces it, and every judgment it causes is measured.
+
+This is the guide layer: the file itself, how discovery fails, the IDE wiring, and what
+enforcement looks like. Every key, with its full rules and pitfalls, lives in
+[the configuration reference](./reference/configuration.md).
+
+## The file
+
+Put exactly one of these at the project root:
+
+| Filename | Note |
+|---|---|
+| `polydeukes.config.yaml` | canonical |
+| `polydeukes.config.yml` | accepted variant |
+| `polydeukes.config.json` | accepted variant (read by the same parser — YAML is a JSON superset) |
+
+Discovery is deliberately strict, and every failure refuses loudly instead of guessing:
+
+- **No config found** → error naming all three candidate filenames. A missing config never
+  silently loads defaults — silent defaults would mean silently unprotected.
+- **More than one found** → error naming the collisions. Ambiguity never picks a winner.
+- **Parse error, or a custom YAML tag** → error naming the file. Custom tags are rejected
+  even though the parser cannot execute them — config data stays uncomputable by contract.
+- **Schema violation** → error naming the key and the file. Unknown keys are rejected
+  wherever the core owns the vocabulary — the top level, and the fixed keys inside a
+  discipline entry — so `protectedPath:` for `protectedPaths:`, or `adaptors:` for
+  `adapters:`, is caught here. Two maps stay open, because their keys are your values
+  rather than the core's: language names under `languages`, and adapter names under
+  `adapters`. A misspelt adapter name is accepted and its block simply goes unread, which
+  leaves that adapter on its defaults — check the name against the adapter's own reference.
+  Inside a namespace the vocabulary belongs to that adapter: the core passes contents
+  through verbatim, and the adapter's own validator rejects what it does not recognise,
+  naming the full field path (see
+  [the `adapters` reference](./reference/configuration.md#adapters)).
+
+## IDE support
+
+The JSON Schema gives autocompletion and validation in editors. It ships inside the
+`polydeukes` package, so the line names a path into your own `node_modules`:
+
+```yaml
+# yaml-language-server: $schema=node_modules/polydeukes/dist/schema/polydeukes.schema.json
+```
+
+For a JSON config, use the standard top-level key instead. The loader accepts it and drops
+it from the resolved config:
+
+```json
+{ "$schema": "node_modules/polydeukes/dist/schema/polydeukes.schema.json" }
+```
+
+**The path is resolved against the directory your config sits in**, not against a project
+root the editor infers. The spelling above is right when the two are the same place. When
+they are not — a config in a monorepo sub-package whose dependencies installed at the
+workspace root — count the levels up yourself:
+
+```yaml
+# yaml-language-server: $schema=../../node_modules/polydeukes/dist/schema/polydeukes.schema.json
+```
+
+`pdks init claude-code` writes the line only when the schema is where the plain spelling
+names it. If the generated config has no such line, that is the case above, and the prefix
+is yours to add — an unresolvable path costs you validation without reporting anything.
+
+If you installed `@polydeukes/core` directly rather than the umbrella, name its own copy:
+
+```yaml
+# yaml-language-server: $schema=node_modules/@polydeukes/core/schema/polydeukes.schema.json
+```
+
+Every value here is a **file path**, not a module specifier: `$schema` is a static string an
+editor reads, so no module resolver runs on it. Code that reads the schema at runtime uses
+the package subpath `polydeukes/schema.json` instead.
+
+## What enforcement looks like
+
+A violating tool call or shell command is **blocked (exit 2)** before it runs, with the
+discipline's `id` in the telemetry record. The sanctioned valve is the witness — a human
+supplying the pass condition on a judgment that actually blocked, recorded as
+`witnessed` — never silent. On the commit surface under
+`adapters.git.enforce: advise`, a verdict is recorded as `advised` and the commit
+proceeds — a backstop that measures instead of blocking. A missing, ambiguous, or
+invalid config blocks every call until it is fixed: the system fails closed, because a
+dead gate that waves things through is the cheapest bypass of all.

package/dist/docs/installation.md

@@ -0,0 +1,211 @@
+# Installing Polydeukes
+
+**English** · [한국어](./installation.ko.md)
+
+> Alpha. This guide covers the install paths that ship today, and everything here is the
+> measured behaviour of the published packages.
+
+This is the getting-started layer: from an empty project to a first judged call.
+
+One devDependency, one command per surface. The umbrella package `polydeukes` is the only
+thing you install — it carries the core, the judge, and the adapters as its own
+dependencies, and `pdks` is its CLI (an alias of `polydeukes`).
+
+**Two surfaces ship, for two different situations — pick the one that matches how the
+project is developed.** A project built alongside an AI partner in Claude Code wires the
+**session surface**: a PreToolUse hook that judges every editing tool call and shell
+command as it is declared. A project you develop yourself wires the **commit surface**: a
+pre-commit hook that judges the staged diff, so the discipline you declared for yourself
+is applied at the moment work becomes history. They enforce the same config vocabulary,
+but they answer different situations — there is no general reason to wire both in one
+project.
+
+## Prerequisites
+
+- **Node.js ≥ 24** — the engines floor of every published package.
+- **A package manager** — pnpm and npm both work; examples below use pnpm.
+- **Claude Code** — only for the session surface. The commit surface needs no AI tool at
+  all: just git and a way to run a pre-commit hook.
+
+## Install
+
+```sh
+pnpm add -D polydeukes
+```
+
+(or `npm install --save-dev polydeukes`.)
+
+This must be a real project dependency, not a one-off `npx` run — both surfaces load the
+judge from your project's own installed package.
+
+## The session surface — developing with an AI partner
+
+From the project root:
+
+```sh
+pnpm exec pdks init claude-code
+```
+
+The command installs into the directory it is invoked from, and it proves the `polydeukes`
+package resolves there **before writing anything** — if it does not (say, the install step
+was skipped), it prints the install command and exits 2 with zero files written, never a
+half-wired tree.
+
+Five artifacts, none ever overwritten. What exists is reported and kept — the hook, the
+config, and the discipline file are left alone, the settings file is merged, and
+`.gitignore` is only ever appended to — so re-running is always safe:
+
+| Artifact | What it is |
+|---|---|
+| `.claude/hooks/covenant-pretooluse.mjs` | The hook — a thin delegator that loads the judge from the installed package. Upgrading the package upgrades the judge; this file never changes. |
+| `.claude/settings.json` | The PreToolUse registration for editing tools and shell calls. **Merged, never replaced** — your other hooks and permissions stay. |
+| `polydeukes.config.yaml` | The starter protection policy: a placeholder `languages` block, a minimum `protectedPaths` list, and the witness block. The comments in the file explain why each entry is there. |
+| `.claude/rules/polydeukes.md` | A scoped discipline file telling your AI partner that `pdks docs` exists and which topic answers what. It carries `paths` frontmatter, so it loads when a Polydeukes path is in play rather than sitting in every session's context. |
+| `.gitignore` | An appended ignore rule for `.polydeukes/`, with its comment line — telemetry is local observation data and never belongs in history. |
+
+## First edit — `languages`
+
+The generated config ships a placeholder language profile, because the installer cannot
+know your stack:
+
+```yaml
+languages:
+  placeholder:
+    productionGlob: 'src/**'
+    testCmd: 'echo "set a verification command for {scope}"'
+```
+
+Rename the key to your language, point `productionGlob` at your production sources, and put
+your real verification command in `testCmd`. (On the commit-surface path you write this
+block yourself as part of the config below.) The placeholder is valid as generated and no
+judgment path reads these values yet, so it cannot produce a wrong verdict while it waits —
+but `languages` is the schema's one required block, so *removing* it (or emptying it) makes
+the config invalid, and an invalid config blocks every call. Edit it, don't delete it.
+
+## The commit surface — developing by yourself
+
+This path is for applying your own discipline to your own commits — no AI tool involved.
+It has no installer today; the wiring is two small manual steps.
+
+**First, the config.** Create `polydeukes.config.yaml` at the project root (there is no
+generator on this path — the file is yours from the first line):
+
+```yaml
+languages:
+  typescript:
+    productionGlob: 'src/**'
+    testCmd: 'pnpm test'
+
+# Judged at commit time: a staged change to these paths stops the commit
+# until you answer the witness prompt in person.
+protectedPaths:
+  - 'db/migrations'
+
+witness:
+  token: 'pdks witness'
+  ttlMinutes: 10
+```
+
+Add `.polydeukes/` to your `.gitignore` too — telemetry is local observation data.
+
+**Then, the hook.** One command judges what is currently staged and exits 2 on a broken
+covenant:
+
+```sh
+pnpm exec pdks covenant check
+```
+
+Register it as a pre-commit hook. With **lefthook**:
+
+```yaml
+# lefthook.yml
+pre-commit:
+  commands:
+    covenant:
+      priority: 1
+      interactive: true   # keep the witness prompt visible — see below
+      run: ./node_modules/.bin/pdks covenant check
+```
+
+With **husky**:
+
+```sh
+# .husky/pre-commit
+./node_modules/.bin/pdks covenant check
+```
+
+With plain **`.git/hooks`** (make it executable):
+
+```sh
+#!/bin/sh
+# .git/hooks/pre-commit
+./node_modules/.bin/pdks covenant check
+```
+
+Three things to know about this surface:
+
+- **The valve is a TTY prompt.** At the default `block` level, a commit that stages a
+  protected change stops at a prompt only a human at a terminal can answer. Configure your
+  hook runner so it does not swallow that prompt (lefthook needs `interactive: true`).
+- **Two discipline families judge here.** A staged diff carries file changes and nothing
+  else, so protection lists and the delta and path families (`forbid`, `immutable`) judge
+  in full. A command-family entry (`forbidCommand`) has no command line to read in a
+  staged diff and is not assembled on this surface, and a context-family entry
+  (`requirePrecedent`) is recorded as `skipped` — declare those two where an AI partner's
+  session exists to be judged.
+- **The commit surface has its own additive scope.** Paths that are fine to edit freely
+  but whose promotion into history deserves a judged checkpoint go under the adapter
+  namespace, judged on top of the shared list:
+
+  ```yaml
+  adapters:
+    git:
+      protectedPaths:
+        - 'src/policy'
+  ```
+
+## The witness valve
+
+Both surfaces carry the same valve, spelled for their situation. It sits **after** the
+verdict — only a judgment that actually blocked can be witnessed open — and every allowance
+is recorded as `witnessed`, never silent.
+
+```yaml
+witness:
+  token: 'pdks witness'
+  ttlMinutes: 10
+```
+
+- **Session surface:** a human types the token so it stands alone on the first line of a
+  conversation message; the window holds for `ttlMinutes`, then blocking resumes. An agent
+  cannot open the valve for itself — only human-authored messages count.
+- **Commit surface:** the blocked commit shows a TTY prompt, and typing the full token
+  there opens that one commit.
+
+Change the token and window as you like — the token is not a secret; the defence is
+provenance, not confidentiality. **Keep the block**: on the session surface the generated
+protection list covers `.claude/hooks`, so without a valve the first blocked call would
+freeze the project until a human edits the config from their own terminal.
+
+## Prove the gate is live
+
+Prove it once on the surface you wired, then read the telemetry.
+
+- **Session surface:** ask your agent to append a line to
+  `.claude/hooks/covenant-pretooluse.mjs` (a protected path). The call must come back
+  blocked.
+- **Commit surface:** stage an edit to a path on your protection list and run
+  `git commit`. It must stop at the witness prompt (answer it, or abort with Ctrl-C).
+
+```sh
+cat .polydeukes/roi.log
+```
+
+Every judgment appends exactly one record — `passed`, `blocked`, `witnessed`, `advised`, or
+`skipped` — so the block you just caused is the last line. A gate you have watched block
+once is a gate you know is wired.
+
+From here: [the configuration guide](./configuration.md) for the file and its wiring,
+[the configuration reference](./reference/configuration.md) for every field and for
+writing your own disciplines, and [troubleshooting](./troubleshooting.md) when something
+blocks and you don't know why.

package/dist/docs/reference/adapter-claude-code.md

@@ -0,0 +1,82 @@
+# `@polydeukes/adapter-claude-code`
+
+**English** · [한국어](./adapter-claude-code.ko.md)
+
+> **The session surface's translator** — PreToolUse payloads become the covenant input IR,
+> with the file-change evidence and the transcript channel the judge reads.
+>
+> Alpha. A transitive dependency of the umbrella: you do not install it and you do not
+> import it. The session surface reaches it through
+> [`polydeukes/claude-code`](./polydeukes.md#subpaths).
+
+## What this package owns
+
+The boundary where Claude Code's vocabulary is translated away. Agent and tool literals
+live *here* by design, so that they never reach the core — which is what makes the core's
+agent-neutrality a claim a test can check rather than a slogan.
+
+| Unit | What it does |
+|---|---|
+| Payload up-translation | A raw PreToolUse payload becomes a `CovenantInput` |
+| Virtual post-state | Computes what a file *would* contain after an edit applies, without touching disk |
+| File-change evidence | Pairs the disk pre-state with the virtual post-state into union evidence |
+| Transcript provider | Turns a session JSONL file into a `CanonicalTranscript` |
+| Precedent evaluator | This adapter's own evidence vocabulary for the context family |
+| Telemetry wiring | Drives the full funnel so exactly one row lands per call |
+
+This package never imports the covenant package. The dispatch seam is *injected* by the
+umbrella, which keeps dependencies one-way, through the core alone.
+
+## Payload translation and the three axes
+
+**Three axes reach the judge**, and they differ in what evidence they can carry.
+
+| Axis | Carries | Consequence |
+|---|---|---|
+| Tool | A proven `fileChange` — the mutation target computed before the tool runs | Only the proven target is judged. A protected path inside an edit's *content* is a mention and passes |
+| Shell | A command line whose target is often not computable before execution | Computable writes are judged like an edit; the rest is recorded rather than guessed |
+| Transcript | The session's own record | Judged by whole-path equality, never as a protected ancestor |
+
+Translation is fail-closed at every step. A `Task` call carrying a subagent type maps to a
+spawn; a payload that cannot be classified is a translation *failure* that logs one
+`blocked` record and exits `2`, rather than degrading into a guess.
+
+**Evidence is computed, never read back.** The virtual post-state applies `Edit`, `Write`,
+and `MultiEdit` in memory — sequential multi-edit application included — so a content-aware
+discipline judges the *proposed* result rather than the file as it currently is. An
+unresolvable post-state yields no evidence at all, because the real tool would reject the
+same edit, and evidence is never fabricated for a non-mutating call.
+
+**The transcript admits only positively-identified human messages.** That is what makes the
+witness valve human-only: an AI cannot synthesize its own witness. A read failure answers
+`undefined` rather than an empty transcript — an empty session has said nothing yet and is
+judged, an unreadable one is no evidence channel at all and is skipped. Either way the
+valve turns off, never open.
+
+**The precedent evaluator judges two keys.** `subagent` is exact spawn-kind equality, since
+a kind is a value rather than a pattern; `tool` matches observed tool names as a regular
+expression. Any key outside this vocabulary returns `undefined` — the handshake that tells
+the compiler the evidence is unjudgeable, so the entry skips instead of judging on a guess.
+
+## Where the consumer touches it
+
+- **The generated hook**, which loads this adapter through the umbrella's `claude-code`
+  subpath. Upgrading the package upgrades what runs; the hook file itself never changes.
+- **`requirePrecedent` entries** using the `subagent` or `tool` evidence keys.
+
+No import, and no configuration namespace of its own.
+
+## Declared limits
+
+- **A child process's writes are outside observation.** This surface judges *declared tool
+  calls*. A command that spawns a process which then writes files — a test runner, a build
+  — is judged on the command, not on what the child did. The commit surface is the second
+  observation that covers the same ground for tracked files.
+- **Evidence exists only where a post-state can be computed.** All four mutating tools
+  contribute one, notebooks included — a `NotebookEdit` yields cell-level `modify` evidence.
+  What yields nothing is a payload this adapter cannot resolve: an unreadable or unparseable
+  notebook, a cell it cannot name, an edit mode it does not know.
+- **An evidence-free call falls back to the conservative judgment** — the call's arguments
+  are compared for a mention rather than a proven target.
+- **Out-of-repository ancestors stay out of scope.** A path above the project root is not
+  observed here; the agent's own deny policy owns that ground.