polydeukes 0.4.0 → 0.6.0

package/dist/covenant-check.js

@@ -1,58 +1,28 @@
 /**
- * `pdks covenant check` — the assembled commit-surface judgment runner (ADAPTER-git §4.3).
+ * `pdks covenant check` — the commit surface's composition root.
  *
- * 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).
+ * Assembly mirrors the session hook — loadConfig → normalizeProtectedPaths → collect →
+ * dispatchCovenants — and spawns the same covenant dist bodies, so a change receives the
+ * verdict a session tool call would. Each change is dispatched as its own input so
+ * telemetry stays one row per file. The witness valve is a `/dev/tty` prompt that only
+ * the staged domain assembles; the other domains open no commit.
  *
- * 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).
+ * 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 { 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 { resolve } from 'node:path';
+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 { compileDisciplineRegistrations, dispatchCovenants, } from '@polydeukes/covenant';
+import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
 import { loadConfig } from './load-config.js';
+import { unobservedPreStateReader } from './pre-state-reader.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).
+ * 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
+ * dispatcher's context, and caches the answer: one commit, at most one prompt, full-token
+ * equality. Both sides are trimmed like the session valve, since config validation accepts
+ * a padded token. The cache latches closed before the seam is consulted so a throwing seam
+ * never re-prompts.
  */
 function ttyWitnessValve(witness, ttyPrompt) {
     if (witness === undefined || ttyPrompt === undefined)
@@ -71,32 +41,11 @@ function ttyWitnessValve(witness, ttyPrompt) {
         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.
+ * `appendRecordFailOpen` creates the missing `.polydeukes/` of a never-judged repository,
+ * and a telemetry failure never softens the exit. An undefined path (non-string
+ * `repoRoot`) leaves no root to write under.
  */
 function recordFailClosed(telemetryPath) {
     if (telemetryPath === undefined)
@@ -108,155 +57,180 @@ function recordFailClosed(telemetryPath) {
     });
 }
 /**
- * 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.
+ * The commit surface's registration set — one assembly that the runner dispatches and
+ * `explain` renders.
  */
-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).
+export function assembleCommitRegistrations(spec) {
+    const { config, rootDir, covenant, witness } = spec;
+    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({
+        protectedPaths: [...(config.protectedPaths ?? []), ...gitAdditivePaths],
+    });
+    const disciplines = config.disciplines ?? [];
+    const registrations = [
+        covenant.selfModRegistration({
+            protectedPaths,
+            mutatingToolNames: [STAGED_WRITE, STAGED_DELETE],
+            witness,
+        }),
+        ...covenant.compileDisciplineRegistrations({
+            disciplines,
+            rootDir,
+            shellTools: [],
+            commandArgs: [],
+            readPreState: unobservedPreStateReader,
+            observesChangeSet: true,
+            witness,
+        }),
+    ];
+    return registrations;
+}
+/** One stage's failure disposition: the stderr line, the recorded row, and exit 2. */
+function failClosed(telemetryPath, error) {
+    process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
+    recordFailClosed(telemetryPath);
+    return { exitCode: 2 };
+}
+/**
+ * Settle the telemetry path and load the config once, or fail closed. The provisional
+ * path is settled before the load so a config that never loads still has somewhere to
+ * write its blocked row; both terms use `resolve` so a relative `repoRoot` cannot send
+ * them to different files. The provisional term sits inside the try because `resolve`
+ * throws on a non-string `repoRoot`.
+ */
+function settleConfig(spec) {
     let telemetryPath;
-    let config;
     try {
         telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
-        ({ config } = loadConfig(spec.repoRoot));
+        const { config } = loadConfig({ rootDir: spec.repoRoot });
         telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
+        return { settled: true, telemetryPath, config };
     }
     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);
+        return { settled: false, ...failClosed(telemetryPath, error) };
     }
-    catch (error) {
-        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
-        recordFailClosed(telemetryPath);
-        return { exitCode: 2 };
+}
+/**
+ * Collect the changes of one domain. The three collectors return the same shape, so
+ * everything downstream of this dispatch is one path.
+ */
+function collectDomain(repoRoot, domain) {
+    if (domain.kind === 'worktree')
+        return collectWorktreeChanges({ repoRoot });
+    if (domain.kind === 'range') {
+        const separator = domain.ancestry === 'merge-base' ? '...' : '..';
+        return collectRangeChanges({
+            repoRoot,
+            range: `${domain.base}${separator}${domain.head}`,
+        });
     }
-    if (changes.length === 0) {
-        return { exitCode: 0 };
+    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);
     }
-    // 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).
+    return paths;
+}
+/**
+ * Assemble the registrations and dispatch every collected change. Any throw here (an
+ * unbuilt dist, a registration-build failure) is unjudgeable: block and leave one record.
+ */
+async function judgeChanges(spec, domain, telemetryPath, config, changes) {
     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'`);
-            }
-        }
+        // Inside the try so an invalid adapter namespace fails closed.
+        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
+        // rather than leaving a half-judged table behind.
+        const covenantDist = spec.covenantDist ?? resolveCovenantDist();
+        const covenant = await loadCovenantModule(covenantDist);
+        // No valve under advise (nothing to witness) and none outside `staged`.
+        const witness = enforce === 'advise' || domain.kind !== 'staged'
+            ? undefined
+            : ttyWitnessValve(config.witness, spec.ttyPrompt);
         let blocked = false;
         let advisedCount = 0;
+        // Assembled ONCE for the run, not per change: a judge takes its call set as an argument,
+        // so the table is payload-free. Recompiling per file would repeat every compile-time
+        // side effect — the stderr line a config-faulted discipline names itself with would
+        // print once per staged file rather than once.
+        const registrations = assembleCommitRegistrations({
+            config,
+            rootDir: spec.repoRoot,
+            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 { exitCode, results } = await dispatchCovenants({
+            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;
             advisedCount += results.filter((result) => result.event === 'advised').length;
         }
+        // Names no level: surface-level and entry-level advice mix in one run, so the commit's
+        // fate is read from the run.
         if (advisedCount > 0) {
-            process.stderr.write(`covenant advisory (enforce: advise): ${advisedCount} verdict(s) recorded, commit allowed\n`);
+            const outcome = blocked ? 'commit blocked by another verdict' : 'commit allowed';
+            process.stderr.write(`covenant advisory: ${advisedCount} verdict(s) recorded as advised, ${outcome}\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 };
+        return failClosed(telemetryPath, error);
     }
 }
+/**
+ * Judge one observation of `repoRoot` exactly as the session surface would — the staged
+ * 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 async function runCovenantCheck(spec) {
+    const settlement = settleConfig(spec);
+    if (!settlement.settled)
+        return { exitCode: settlement.exitCode };
+    const { telemetryPath, config } = settlement;
+    const domain = spec.domain ?? { kind: 'staged' };
+    let changes;
+    try {
+        changes = collectDomain(spec.repoRoot, domain);
+    }
+    catch (error) {
+        return failClosed(telemetryPath, error);
+    }
+    if (changes.length === 0)
+        return { exitCode: 0 };
+    return judgeChanges(spec, domain, telemetryPath, config, changes);
+}

package/dist/covenant-module.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The covenant package as a resolved artifact — the existence proof both composition roots
+ * share.
+ *
+ * What the roots prove is the package IMPORT itself. The barrel is eager: a dist missing one
+ * of the modules it references throws on import, before any assembly can compose a
+ * registration, and the surface's own fail-closed catch records that as one `blocked` row. A
+ * partially loaded judge set has no representation here — an ESM import either fully succeeds
+ * or throws.
+ *
+ * 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.
+ */
+import type * as covenant from '@polydeukes/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;
+/**
+ * Import the covenant barrel from `distDir`, naming the recovery command when it will not
+ * load. The message carries the loader's own text, which names the module that is missing;
+ * a reader locked out by an unbuilt or half-built dist needs both that name and the one
+ * command that fixes it.
+ */
+export declare function loadCovenantModule(distDir: string): Promise<CovenantModule>;

package/dist/covenant-module.js

@@ -0,0 +1,42 @@
+/**
+ * The covenant package as a resolved artifact — the existence proof both composition roots
+ * share.
+ *
+ * What the roots prove is the package IMPORT itself. The barrel is eager: a dist missing one
+ * of the modules it references throws on import, before any assembly can compose a
+ * registration, and the surface's own fail-closed catch records that as one `blocked` row. A
+ * partially loaded judge set has no representation here — an ESM import either fully succeeds
+ * or throws.
+ *
+ * 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';
+/** Where real Node resolution puts the covenant package's built barrel. */
+export function resolveCovenantDist() {
+    return join(createRequire(import.meta.url).resolve('@polydeukes/covenant'), '..');
+}
+/**
+ * Import the covenant barrel from `distDir`, naming the recovery command when it will not
+ * load. The message carries the loader's own text, which names the module that is missing;
+ * a reader locked out by an unbuilt or half-built dist needs both that name and the one
+ * command that fixes it.
+ */
+export async function loadCovenantModule(distDir) {
+    try {
+        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/configuration.md

@@ -3,7 +3,7 @@
 **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
+> the declaration grammar). Fields and steps 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
@@ -85,11 +85,19 @@ 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.
+A `disciplines:` entry lands at **advise** by default: a break is recorded as `advised`
+with the discipline's `id` in the telemetry record, the break message with its `why` goes
+to stderr, and the call proceeds (exit 0) — the judgment measures instead of stopping.
+Writing `enforce: block` on an entry is the promotion: that entry then **blocks (exit 2)**
+before the call runs. The sanctioned valve on a block is the witness — a human supplying
+the pass condition on a judgment that actually blocked, recorded as `witnessed` — never
+silent.
+
+What blocks without being asked is the judging chain's own protection, a finite list: the
+`protectedPaths` entries (tool-axis and shell-axis mutations, and mentions without a
+read-only head), the session transcript, and the assembly itself — a missing, ambiguous, or
+invalid config, an unbuilt judge, an unparseable payload, or a routing that could not
+answer. At either level the system fails closed on these, because a dead gate that waves
+things through is the cheapest bypass of all. On the commit surface `adapters.git.enforce: advise` relaxes
+the protected-path verdicts to `advised` as well — it is the observer's setting — while an
+assembly that cannot judge still fails closed.

package/dist/docs/installation.md

@@ -43,7 +43,8 @@ judge from your project's own installed package.
 From the project root:
 
 ```sh
-pnpm exec pdks init claude-code
+pnpm exec pdks init claude-code    # Claude Code
+pnpm exec pdks init grok           # Grok
 ```
 
 The command installs into the directory it is invoked from, and it proves the `polydeukes`
@@ -51,9 +52,17 @@ package resolves there **before writing anything** — if it does not (say, the
 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:
+Nothing existing is overwritten. What exists is reported and kept — the hook, the config,
+and the discipline files are left alone, the settings file is merged, and `.gitignore` is
+only ever appended to — so re-running is always safe. One command-field exception: if
+`.grok/hooks/covenant-pretooluse.json` still names the grok delegator and a Claude
+delegator is on disk, the JSON `command` is rewritten to that Claude file so the host
+does not spawn two judges. Grok collapses two registrations only when `command` AND
+`matcher` are identical, so every grok entry naming that Claude file also takes the matcher
+of the `.claude/settings.json` entry that registers the same command — on a fresh write and
+on every re-run; `timeout` stays. A command you pointed elsewhere is left as it was.
+
+`pdks init claude-code` writes six artifacts:
 
 | Artifact | What it is |
 |---|---|
@@ -61,8 +70,28 @@ config, and the discipline file are left alone, the settings file is merged, and
 | `.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. |
+| `.claude/skills/discipline-draft/SKILL.md` | The classification procedure. Describe a recurring problem to your AI partner and it lands as a config entry — judged at advise when a current family can express it, a `draft: true` entry otherwise — and the same file tells the agent to consult `advised` rows in the telemetry log at task boundaries. |
 | `.gitignore` | An appended ignore rule for `.polydeukes/`, with its comment line — telemetry is local observation data and never belongs in history. |
 
+`pdks init grok` shares the scaffold (config and the ignore line) and writes Grok's own
+registration. A Grok-only tree has four artifacts, and no `.claude/` directory:
+
+| Artifact | What it is |
+|---|---|
+| `.grok/hooks/covenant-pretooluse.mjs` | The hook — the same delegator text, only when no Claude delegator is already on disk. |
+| `.grok/hooks/covenant-pretooluse.json` | The PreToolUse matcher, `timeout` 60 (the host default is 5 seconds, and a timed-out hook fails open), and the command that names one delegator file. In a tree that also has `.claude/settings.json`, the matcher is copied from the settings entry with the same command — Grok reads that file too, and collapses the two registrations into one spawn only when `command` and `matcher` match exactly. That copy leans on Grok's tool-name aliases, so if you later remove `.claude/settings.json`, delete this JSON and run `pdks init grok` again to get the Grok-native matcher back. |
+| `polydeukes.config.yaml` | The same starter policy as above. |
+| `.gitignore` | The same appended ignore line. |
+
+If `.claude/hooks/covenant-pretooluse.mjs` already exists, the JSON command points at that
+file instead of planting a second one. A later `pdks init grok` or `pdks init claude-code`
+retargets an installer-generated grok-mjs command the same way.
+
+An already-open Grok session keeps the hook snapshot from start. Reload from the Hooks tab
+(`r`) or start a new session. The witness valve does not open on Grok — the session log is
+ACP `updates.jsonl`, not Claude's JSONL. A block is recovered from another terminal or the
+commit-surface TTY.
+
 ## First edit — `languages`
 
 The generated config ships a placeholder language profile, because the installer cannot
@@ -147,12 +176,12 @@ 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.
+- **Declarations judge here.** A staged diff carries file changes and nothing else, so
+  protection lists and every `declare` entry over the change judge in full. A declaration
+  scoped on `command` has no command line to read in a staged diff and observes nothing on
+  this surface, and a declaration that reads the session (`precedent` and the other history
+  mechanisms) is recorded as `skipped` — declare those 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:
@@ -184,8 +213,9 @@ witness:
 
 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.
+protection list covers `.claude/hooks` and `.grok/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