polydeukes 0.5.0 → 0.6.0

package/dist/init-claude-code.js

@@ -14,7 +14,9 @@
  *
  * Nothing existing is overwritten. The settings file in particular is merged, never
  * replaced: a consumer's other PreToolUse registrations and permissions are live
- * configuration, and replacing them would disarm every other tool they wired.
+ * configuration, and replacing them would disarm every other tool they wired. A grok JSON
+ * whose command still names the grok mjs is rewritten to this hook's command so the two
+ * installers do not leave two spawn strings.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { findPackageJSON } from 'node:module';
@@ -22,6 +24,7 @@ import { dirname, join } from 'node:path';
 import { MUTATING_TOOLS, SHELL_TOOLS } from '@polydeukes/adapter-claude-code';
 import { isPlainObject } from '@polydeukes/core';
 import { TOPICS } from './docs-query.js';
+import { retargetGrokHookCommandToClaude } from './init-grok.js';
 import { CONFIG_FILENAMES } from './load-config.js';
 import { scaffoldProject } from './scaffold-project.js';
 /** The published entry point the generated hook loads the judge through. */
@@ -153,21 +156,20 @@ promises and classify each separately.
 
 Ask these questions in order; the first yes decides.
 
-| # | Question | Family | Entry key |
-| --- | --- | --- | --- |
-| 1 | Is the promise about content newly ADDED to a file (a pattern that must not appear in new lines)? | delta | \`forbid\` |
-| 2 | Is it about a whole path that must not be modified or deleted (creating it once stays allowed)? | path | \`immutable\` |
-| 3 | Is it about the shell command line itself, regardless of files? | command | \`forbidCommand\` |
-| 4 | Does it require that something else was already done earlier in the session (a tool call that must precede this one)? | context | \`requirePrecedent\` |
-| 5 | None of the above | — | \`draft: true\` (step 4b) |
+| # | Question | Entry key |
+| --- | --- | --- |
+| 1 | Is the promise about content newly ADDED to a file (a pattern that must not appear in new lines)? | \`declare\` (mechanism \`added-only\`) |
+| 2 | Is it about a whole path that must not be modified or deleted (creating it once stays allowed)? | \`declare\` (mechanism \`self-absolution-ban\`) |
+| 3 | Is it about the shell command line itself, regardless of files? | \`declare\` (mechanism \`forbidden-command\`, reading the \`command\` source) |
+| 4 | Does it require that something else was already done earlier in the session (a tool call that must precede this one)? | \`declare\` (mechanism \`precedent\`, reading a \`transcript\` source) |
+| 5 | None of the above | \`draft: true\` (step 4b) |
 
-Existing occurrences are forgiven by the delta family — only new additions break the promise.
-That is usually what you want: a discipline adopted today should not indict yesterday's code.
+An \`added-only\` declaration forgives existing occurrences — only what the edit adds breaks
+the promise. That is usually what you want: a discipline adopted today should not indict
+yesterday's code.
 
-Two path-shaped promises take no \`disciplines:\` entry at all. A path nobody may touch
-belongs in the top-level \`protectedPaths:\` list — its own config block, never an entry
-key. And a path that must never be CREATED is not expressible today: \`immutable\` allows
-creation by design, so register that promise as a draft (step 4b).
+One path-shaped promise takes no \`disciplines:\` entry at all: a path nobody may touch
+belongs in the top-level \`protectedPaths:\` list — its own config block, never an entry key.
 
 ### 3. Check the observation boundary
 
@@ -198,7 +200,49 @@ languages:
 disciplines:
   - id: 'no-focused-tests'
     why: 'a committed .only silently shrinks the suite to one test'
-    forbid: '\\.only\\('
+    declare:
+      mechanism: 'added-only'
+      scope: { source: 'target.path', include: ['^src/'] }
+      supply: { pre: 'empty', post: 'empty' }
+      extract:
+        before:
+          - { op: 'source', of: 'pre' }
+          - { op: 'lines' }
+          - { op: 'keyByPattern', re: '(\\.only\\()' }
+        after:
+          - { op: 'source', of: 'post' }
+          - { op: 'lines' }
+          - { op: 'keyByPattern', re: '(\\.only\\()' }
+        added:
+          - { op: 'onlyIn', of: 'after', notIn: 'before' }
+      relate:
+        - id: 'nothing-added'
+          relation: { op: 'empty', of: 'added' }
+          message: 'adds {key}: {value}'
+    enforce: advise
+\`\`\`
+
+A command-line ban reads the fixed source \`command\` and scopes on it — the scope is part of
+the mechanism's shape, so a \`forbidden-command\` entry without it is refused at load time:
+
+\`\`\`yaml
+languages:
+  placeholder:
+    productionGlob: 'src/**'
+    testCmd: 'echo "set a verification command for {scope}"'
+disciplines:
+  - id: 'no-force-push'
+    why: 'a force push rewrites history nobody reviewed'
+    declare:
+      mechanism: 'forbidden-command'
+      scope: { source: 'command' }
+      extract:
+        hits:
+          - { op: 'source', of: 'command' }
+          - { op: 'lines' }
+          - { op: 'matches', re: 'git push\\\\b.*--force(?![\\\\w-])' }
+      relate:
+        - { id: 'no-force', relation: { op: 'empty', of: 'hits' }, message: '{value}' }
     enforce: advise
 \`\`\`
 
@@ -208,14 +252,15 @@ authoring traps, each measured on a live config:
 
 - **A pattern answers a syntactic question only.** "Is this string a forbidden word" is
   syntax; "is this a new dependency version" is meaning, and a regex leaks both ways on a
-  semantic question. When the question is semantic, narrow \`in:\` to the files where any
-  match IS a break (\`in:\`/\`except:\` scope \`forbid\` and \`requirePrecedent\` only), or
-  accept "editing this file at all" as the trigger.
-- **\`^\` silently disarms on the delta axis.** \`forbid\` scans whole file content as one
-  string, so a line-start anchor matches the first line only — write \`(^|\\n)\` there.
-  \`forbidCommand\` judges per line and the whole string, so \`^\` is safe on that axis.
+  semantic question. When the question is semantic, narrow the declaration's own \`scope\`
+  block to the files where any match IS a break, or accept "editing this file at all" as
+  the trigger.
+- **\`^\` means what the preceding step left.** After a \`lines\` step a declaration's
+  pattern sees one line at a time, so \`^\` anchors to that line; over an unsplit source it
+  anchors to the whole text and matches the first line only. A ban over the command line
+  puts \`lines\` before its \`matches\` for exactly that reason.
 - **Author both directions.** Before registering, write down one string the pattern must
-  match and one nearby string it must not (\`forbid\` vs \`forbidden\`, a flag vs its
+  match and one nearby string it must not (\`only(\` vs \`only_helper(\`, a flag vs its
   substring). A pattern checked in only the breaking direction over-fires in review-proof
   ways.
 
@@ -258,18 +303,18 @@ disciplines:
 
 ### 5. Prove it fires, then close
 
-Run \`pdks explain\` and confirm the new entry is listed (a judged entry with its family and
-surfaces; a draft as unpromoted).
+Run \`pdks explain\` and confirm the new entry is listed (a judged entry with its mechanism
+and surfaces; a draft as unpromoted).
 
 For a judged entry, registration is not the finish — a pattern that never fires protects
-nothing while looking installed. Fire it once for real, with the proof run its family can
-actually reach:
+nothing while looking installed. Fire it once for real, with the proof run the declaration's
+own mechanism can actually reach:
 
-| Family | Break it once | The entry's id shows up in |
+| Mechanism | Break it once | The entry's id shows up in |
 | --- | --- | --- |
-| \`forbid\` / \`immutable\` | one scratch edit matching the must-match direction | \`pdks covenant check --worktree\` output — the exit stays 0 at advise, the id is the proof |
-| \`forbidCommand\` | run one harmless command matching the pattern | the telemetry log tail — at advise the call proceeds and its row records the id |
-| \`requirePrecedent\` | one in-scope edit made without the required precedent | the telemetry log tail — this family judges on the session surface only (the commit surface records it \`skipped\`) |
+| a file-reading one (\`added-only\`, \`naming\`, …) | one scratch edit matching the must-match direction | \`pdks covenant check --worktree\` output — the exit stays 0 at advise, the id is the proof |
+| \`forbidden-command\` | run one harmless command matching the pattern | the telemetry log tail — at advise the call proceeds and its row records the id |
+| \`precedent\` | one in-scope edit made without the required precedent | the telemetry log tail — a declaration reading the session judges on the session surface only (the commit surface has none, so its \`supply\` policy records it \`skipped\`) |
 
 Then undo the scratch break, repeat the same run, and confirm silence on the
 must-NOT-match direction. Close by telling the user which rung the entry landed on and
@@ -419,5 +464,6 @@ export function initClaudeCode(spec) {
     // a failure costs least.
     writeIfAbsent(spec.projectRoot, DISCOVERY_RELATIVE, GENERATED_DISCOVERY, report);
     writeIfAbsent(spec.projectRoot, SKILL_RELATIVE, GENERATED_SKILL, report);
+    retargetGrokHookCommandToClaude(spec.projectRoot);
     return report;
 }

package/dist/init-grok.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `initGrok` — the Grok session-surface installer.
+ *
+ * Preflight first, then the shared project-side scaffold, then the generated hook and the
+ * `.grok/hooks` JSON registration. When a Claude delegator is already on disk, the JSON
+ * command names that file instead of planting a second one — two command strings would
+ * spawn two judges per call.
+ *
+ * Nothing existing is overwritten, with one command-field exception: a grok JSON whose
+ * `command` is still the grok-mjs string is rewritten to the Claude-hook command when that
+ * Claude file is on disk — otherwise grok-then-claude leaves two command strings. Any entry
+ * naming the Claude-hook command also takes the matcher of the `.claude/settings.json` entry
+ * carrying that command, because the host collapses the two registrations only when command
+ * and matcher are byte-identical; with no such entry the matcher stays. Timeout stays either
+ * way, and a command that is not the grok-mjs string is left byte-identical.
+ *
+ * Rules and skills are not copied; `.claude/settings.json` is not written.
+ */
+import { type ScaffoldReport } from './scaffold-project.ts';
+/** `initGrok` input — the target tree and the preflight seam. */
+export type InitGrokSpec = {
+    /** Project root to install into — every write below is relative to it. */
+    projectRoot: string;
+    /**
+     * Preflight seam: throws when the package cannot be resolved from the given root.
+     * ABSENT uses the real resolution, anchored at that root and nowhere else — anchoring it
+     * at the installer's own module would answer for the installer's install graph rather
+     * than the target project's, which is precisely the case that must fail.
+     */
+    resolvePolydeukes?: (projectRoot: string) => void;
+};
+/**
+ * Rewrite the grok JSON `command` from the grok-mjs string to the Claude-hook string.
+ *
+ * The Claude installer calls this after writing its delegator; this installer calls it on
+ * re-run when that file is already on disk. Only the installer-generated grok-mjs command
+ * is rewritten; any other string is the consumer's spawn target and the file is not touched.
+ * Every entry naming the Claude-hook command — rewritten now or by an earlier install — takes
+ * the matcher the Claude settings file registered that command under, so the host sees one
+ * pair rather than two and a re-run converges. Parse failure leaves the file as it was —
+ * existence is presence, not parse success.
+ */
+export declare function retargetGrokHookCommandToClaude(projectRoot: string): void;
+/**
+ * Install the Grok session surface into `spec.projectRoot`, skipping whatever is already
+ * there and reporting both halves per artifact.
+ *
+ * Throws before any write when the package cannot be resolved from that root — that leaves
+ * zero files. Translating a throw into exit 2 with the install command is the bin's job.
+ */
+export declare function initGrok(spec: InitGrokSpec): ScaffoldReport;

package/dist/init-grok.js

@@ -0,0 +1,242 @@
+/**
+ * `initGrok` — the Grok session-surface installer.
+ *
+ * Preflight first, then the shared project-side scaffold, then the generated hook and the
+ * `.grok/hooks` JSON registration. When a Claude delegator is already on disk, the JSON
+ * command names that file instead of planting a second one — two command strings would
+ * spawn two judges per call.
+ *
+ * Nothing existing is overwritten, with one command-field exception: a grok JSON whose
+ * `command` is still the grok-mjs string is rewritten to the Claude-hook command when that
+ * Claude file is on disk — otherwise grok-then-claude leaves two command strings. Any entry
+ * naming the Claude-hook command also takes the matcher of the `.claude/settings.json` entry
+ * carrying that command, because the host collapses the two registrations only when command
+ * and matcher are byte-identical; with no such entry the matcher stays. Timeout stays either
+ * way, and a command that is not the grok-mjs string is left byte-identical.
+ *
+ * Rules and skills are not copied; `.claude/settings.json` is not written.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { findPackageJSON } from 'node:module';
+import { dirname, join } from 'node:path';
+import { isPlainObject } from '@polydeukes/core';
+import { scaffoldProject } from './scaffold-project.js';
+/** The published entry point the generated hook loads the judge through. */
+const HOOK_SPECIFIER = 'polydeukes/claude-code';
+/** The registration artifacts, as `projectRoot`-relative paths (the report vocabulary). */
+const GROK_HOOK_RELATIVE = '.grok/hooks/covenant-pretooluse.mjs';
+const GROK_JSON_RELATIVE = '.grok/hooks/covenant-pretooluse.json';
+/** The Claude delegator this installer reuses when it is already on disk. */
+const CLAUDE_HOOK_RELATIVE = '.claude/hooks/covenant-pretooluse.mjs';
+/** Where that delegator's own registration — and the matcher it was registered under — lives. */
+const CLAUDE_SETTINGS_RELATIVE = '.claude/settings.json';
+const GROK_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR"/${GROK_HOOK_RELATIVE}`;
+const CLAUDE_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR"/${CLAUDE_HOOK_RELATIVE}`;
+/**
+ * Which calls reach the judge — Grok's mutating+shell roster plus the Claude aliases a
+ * host without Grok's alias table still sends.
+ */
+const HOOK_MATCHER = 'write|search_replace|run_terminal_command|Edit|Write|MultiEdit|NotebookEdit|Bash';
+/**
+ * The generated hook. It carries no assembly at all, so upgrading the package upgrades the
+ * judge without regenerating this file. Same text as the Claude installer besides the
+ * header: the session subpath, `repoRoot` from this file's location, and `process.exitCode`
+ * rather than `process.exit`.
+ */
+const GENERATED_HOOK = `#!/usr/bin/env node
+/**
+ * Polydeukes PreToolUse covenant hook — generated by \`pdks init grok\`.
+ *
+ * A delegator and nothing more: the judgment assembly lives in the \`polydeukes\` package as
+ * \`runClaudeCodeHook\`, reached here through its session subpath. The package barrel would
+ * work too and is the wrong door — its re-exports are eager, so every session call would
+ * load the commit surface and its git adapter alongside the judge it actually needs.
+ *
+ * \`repoRoot\` comes from this file's own location, never from the working directory. A hook
+ * is spawned with whatever directory the agent happened to hold, and what config discovery
+ * and the protection list need is the project that CONTAINS this hook — always \`../..\`
+ * from here.
+ *
+ * fail-closed: \`runClaudeCodeHook\` translates every failure it can reach into exit 2 with
+ * one blocked record. This catch answers only for what it cannot reach — the package failing
+ * to resolve or load at all (never installed, or installed without a build) — where no
+ * telemetry writer exists yet. Recovery is installing the package again.
+ */
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+try {
+  const { runClaudeCodeHook } = await import('${HOOK_SPECIFIER}');
+  const { exitCode } = await runClaudeCodeHook({ repoRoot });
+  // Assign and let the process end naturally instead of process.exit(): an explicit exit
+  // can preempt a buffered stderr write on platforms with async pipes, dropping the break
+  // reason the agent needs to read.
+  process.exitCode = exitCode;
+} catch (error) {
+  console.error(\`covenant hook failed closed: \${error?.message ?? error}\`);
+  process.exitCode = 2;
+}
+`;
+/**
+ * The default preflight: is `polydeukes` installed where `projectRoot` can reach it?
+ *
+ * ESM resolution specifically, because that is what the generated hook's `await import(...)`
+ * runs. The generated hook loads `polydeukes/claude-code`, so that is the subpath this
+ * checks — a Grok-named entry point is not added.
+ */
+function resolveFromProjectRoot(projectRoot) {
+    const manifestPath = findPackageJSON('polydeukes', join(projectRoot, 'package.json'));
+    if (manifestPath === undefined) {
+        throw new Error('polydeukes is not installed where this project can reach it');
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    const subpath = isPlainObject(manifest) && isPlainObject(manifest.exports)
+        ? manifest.exports[`./${HOOK_SPECIFIER.split('/')[1]}`]
+        : undefined;
+    const target = isPlainObject(subpath) ? subpath.import : undefined;
+    if (typeof target !== 'string' || !existsSync(join(dirname(manifestPath), target))) {
+        throw new Error(`the installed polydeukes does not expose '${HOOK_SPECIFIER}' — update or rebuild it`);
+    }
+}
+/** Write one generated artifact unless it is already there, recording which happened. */
+function writeIfAbsent(projectRoot, relative, contents, report) {
+    const path = join(projectRoot, relative);
+    if (existsSync(path)) {
+        report.skipped.push(relative);
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, contents);
+    report.created.push(relative);
+}
+/**
+ * The matcher `.claude/settings.json` registered `command` under, when it has one. Anything
+ * unreadable, unparseable, or shaped otherwise answers `undefined` — the caller then keeps its
+ * own roster rather than narrowing the registration to a shape it could not read.
+ */
+function claudeSettingsMatcherFor(projectRoot, command) {
+    const path = join(projectRoot, CLAUDE_SETTINGS_RELATIVE);
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    let root;
+    try {
+        root = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (!isPlainObject(root) || !isPlainObject(root.hooks) || !Array.isArray(root.hooks.PreToolUse)) {
+        return undefined;
+    }
+    for (const entry of root.hooks.PreToolUse) {
+        if (!isPlainObject(entry) || !Array.isArray(entry.hooks)) {
+            continue;
+        }
+        if (entry.hooks.some((hook) => isPlainObject(hook) && hook.command === command)) {
+            return typeof entry.matcher === 'string' ? entry.matcher : undefined;
+        }
+    }
+    return undefined;
+}
+function grokHookJson(command, matcher) {
+    return `${JSON.stringify({
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher,
+                    hooks: [{ type: 'command', command, timeout: 60 }],
+                },
+            ],
+        },
+    }, null, 2)}\n`;
+}
+/**
+ * Rewrite the grok JSON `command` from the grok-mjs string to the Claude-hook string.
+ *
+ * The Claude installer calls this after writing its delegator; this installer calls it on
+ * re-run when that file is already on disk. Only the installer-generated grok-mjs command
+ * is rewritten; any other string is the consumer's spawn target and the file is not touched.
+ * Every entry naming the Claude-hook command — rewritten now or by an earlier install — takes
+ * the matcher the Claude settings file registered that command under, so the host sees one
+ * pair rather than two and a re-run converges. Parse failure leaves the file as it was —
+ * existence is presence, not parse success.
+ */
+export function retargetGrokHookCommandToClaude(projectRoot) {
+    const path = join(projectRoot, GROK_JSON_RELATIVE);
+    if (!existsSync(path)) {
+        return;
+    }
+    let root;
+    try {
+        root = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return;
+    }
+    if (!isPlainObject(root) || !isPlainObject(root.hooks) || !Array.isArray(root.hooks.PreToolUse)) {
+        return;
+    }
+    const settingsMatcher = claudeSettingsMatcherFor(projectRoot, CLAUDE_HOOK_COMMAND);
+    let changed = false;
+    for (const entry of root.hooks.PreToolUse) {
+        if (!isPlainObject(entry) || !Array.isArray(entry.hooks)) {
+            continue;
+        }
+        let namesClaudeHook = false;
+        for (const hook of entry.hooks) {
+            if (!isPlainObject(hook)) {
+                continue;
+            }
+            if (hook.command === GROK_HOOK_COMMAND) {
+                hook.command = CLAUDE_HOOK_COMMAND;
+                changed = true;
+            }
+            namesClaudeHook ||= hook.command === CLAUDE_HOOK_COMMAND;
+        }
+        // Whether this pass rewrote the command or an earlier install already did, an entry
+        // naming the Claude hook pairs with the settings entry only on the same matcher.
+        if (namesClaudeHook && settingsMatcher !== undefined && entry.matcher !== settingsMatcher) {
+            entry.matcher = settingsMatcher;
+            changed = true;
+        }
+    }
+    if (changed) {
+        writeFileSync(path, `${JSON.stringify(root, null, 2)}\n`);
+    }
+}
+/**
+ * Install the Grok session surface into `spec.projectRoot`, skipping whatever is already
+ * there and reporting both halves per artifact.
+ *
+ * Throws before any write when the package cannot be resolved from that root — that leaves
+ * zero files. Translating a throw into exit 2 with the install command is the bin's job.
+ */
+export function initGrok(spec) {
+    const resolvePolydeukes = spec.resolvePolydeukes ?? resolveFromProjectRoot;
+    try {
+        resolvePolydeukes(spec.projectRoot);
+    }
+    catch (error) {
+        throw new Error(`cannot use 'polydeukes' from ${spec.projectRoot} — install or update it there first ` +
+            "(e.g. 'npm install --save-dev polydeukes'), then run this command again: " +
+            `${error instanceof Error ? error.message : String(error)}`);
+    }
+    const report = scaffoldProject(spec.projectRoot);
+    const claudeHookExists = existsSync(join(spec.projectRoot, CLAUDE_HOOK_RELATIVE));
+    if (!claudeHookExists) {
+        writeIfAbsent(spec.projectRoot, GROK_HOOK_RELATIVE, GENERATED_HOOK, report);
+    }
+    const command = claudeHookExists ? CLAUDE_HOOK_COMMAND : GROK_HOOK_COMMAND;
+    const matcher = claudeHookExists
+        ? (claudeSettingsMatcherFor(spec.projectRoot, CLAUDE_HOOK_COMMAND) ?? HOOK_MATCHER)
+        : HOOK_MATCHER;
+    writeIfAbsent(spec.projectRoot, GROK_JSON_RELATIVE, grokHookJson(command, matcher), report);
+    if (claudeHookExists) {
+        retargetGrokHookCommandToClaude(spec.projectRoot);
+    }
+    return report;
+}

package/dist/load-config.d.ts

@@ -16,6 +16,10 @@ import type { ResolvedConfig } from '@polydeukes/core';
  * create a second spelling and make every later load ambiguous.
  */
 export declare const CONFIG_FILENAMES: readonly ['polydeukes.config.yaml', 'polydeukes.config.yml', 'polydeukes.config.json'];
+/** {@link loadConfig} input — the directory the config is discovered in. */
+export type LoadConfigSpec = {
+    rootDir: string;
+};
 /** `LoadedConfig` — the loader's return value. */
 export type LoadedConfig = {
     /** defineConfig() resolution — protectedPaths already includes configPath */
@@ -38,4 +42,4 @@ export type LoadedConfig = {
  * `config.protectedPaths` unless already present — the config file itself joins the
  * protection surface, guaranteed here so no assembler has to remember.
  */
-export declare function loadConfig(rootDir: string): LoadedConfig;
+export declare function loadConfig(spec: LoadConfigSpec): LoadedConfig;

package/dist/load-config.js

@@ -38,7 +38,8 @@ export const CONFIG_FILENAMES = [
  * `config.protectedPaths` unless already present — the config file itself joins the
  * protection surface, guaranteed here so no assembler has to remember.
  */
-export function loadConfig(rootDir) {
+export function loadConfig(spec) {
+    const { rootDir } = spec;
     const found = CONFIG_FILENAMES.filter((name) => existsSync(join(rootDir, name)));
     if (found.length === 0) {
         throw new Error(`no Polydeukes config found in ${rootDir} — expected one of: ${CONFIG_FILENAMES.join(', ')}`);

package/dist/pre-state-reader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The pre-state readers the two surfaces inject into the discipline compiler — the disk
+ * access that the judge package must not carry.
+ */
+/**
+ * The session surface's reader: the hook runs before the tool does, so the working tree at
+ * an absolute location IS the pre-state.
+ *
+ * Three answers, three consequences. Text is a modify; `null` — the file is not there — is a
+ * create, so nothing is forgiven as pre-existing debt; `undefined` is a location that cannot
+ * be read at all, which the judge escalates to the fail-closed exit. A permission error or a
+ * race collapsed into either of the first two would record the run as `passed`.
+ */
+export declare function sessionPreStateReader(location: string): string | null | undefined;
+/**
+ * The commit surface's reader: it observes a staged diff, whose payloads already carry the
+ * pre their own observation saw, and it registers no shell axis — so no derivation ever asks
+ * for a pre-state here. Should one arrive, the working tree is not what this surface judges,
+ * and answering from it would compare the diff against the wrong baseline; `undefined` says
+ * so and fails that call closed.
+ */
+export declare function unobservedPreStateReader(): undefined;

package/dist/pre-state-reader.js

@@ -0,0 +1,32 @@
+/**
+ * The pre-state readers the two surfaces inject into the discipline compiler — the disk
+ * access that the judge package must not carry.
+ */
+import { readFileSync } from 'node:fs';
+/**
+ * The session surface's reader: the hook runs before the tool does, so the working tree at
+ * an absolute location IS the pre-state.
+ *
+ * Three answers, three consequences. Text is a modify; `null` — the file is not there — is a
+ * create, so nothing is forgiven as pre-existing debt; `undefined` is a location that cannot
+ * be read at all, which the judge escalates to the fail-closed exit. A permission error or a
+ * race collapsed into either of the first two would record the run as `passed`.
+ */
+export function sessionPreStateReader(location) {
+    try {
+        return readFileSync(location, 'utf-8');
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? null : undefined;
+    }
+}
+/**
+ * The commit surface's reader: it observes a staged diff, whose payloads already carry the
+ * pre their own observation saw, and it registers no shell axis — so no derivation ever asks
+ * for a pre-state here. Should one arrive, the working tree is not what this surface judges,
+ * and answering from it would compare the diff against the wrong baseline; `undefined` says
+ * so and fails that call closed.
+ */
+export function unobservedPreStateReader() {
+    return undefined;
+}

package/dist/scaffold-project.js

@@ -50,9 +50,9 @@ languages:
 # The protection list. A tool call whose proven target is one of these paths is blocked, and
 # so is a shell command that mentions one without a read-only head.
 #
-#   .claude/hooks, .claude/settings.json — the gate definitions themselves. Editing them
-#     does not evade a judgment, it removes the judgment; the session surface is the only
-#     layer that can watch it happen.
+#   .claude/hooks, .claude/settings.json, .grok/hooks — the gate definitions themselves.
+#     Editing them does not evade a judgment, it removes the judgment; the session surface
+#     is the only layer that can watch it happen.
 #
 # A minimum. Add entries as you find you want them.
 #
@@ -61,6 +61,7 @@ languages:
 protectedPaths:
   - '.claude/hooks'
   - '.claude/settings.json'
+  - '.grok/hooks'
 
 # The time-boxed witness — the human valve on a blocked verdict. A human types this token so
 # it stands alone on a message's FIRST line, the window holds for ttlMinutes, then blocking
@@ -68,9 +69,9 @@ protectedPaths:
 # window is always recorded as \`witnessed\` and never silent, and no agent can open one for
 # itself. The token is not a secret: the defence is provenance, not confidentiality.
 #
-# Keep this block. Without it no block can be opened by anyone, and .claude/hooks is on the
-# list above — so the first block would freeze the project until a human edits these files
-# from their own terminal.
+# Keep this block. Without it no block can be opened by anyone, and the hook directories
+# are on the list above — so the first block would freeze the project until a human edits
+# these files from their own terminal.
 witness:
   token: 'pdks witness'
   ttlMinutes: 10
@@ -86,15 +87,54 @@ witness:
 #
 #   # Promoted to a judgment. Advise is the default — recorded as \`advised\`, never stops
 #   # the call — so this line is optional; it is written here to show the rung.
+#   #
+#   # The declaration keys each side's matched lines by the matched text and breaks on what
+#   # the edit ADDED, so occurrences already in the tree are forgiven.
 #   - id: 'no-todo-in-shipped-code'
 #     why: 'a TODO nobody owns is a decision deferred out of sight'
-#     forbid: 'TODO'
+#     declare:
+#       mechanism: 'added-only'
+#       scope: { source: 'target.path', include: ['^src/'] }
+#       supply: { pre: 'empty', post: 'empty' }
+#       extract:
+#         before:
+#           - { op: 'source', of: 'pre' }
+#           - { op: 'lines' }
+#           - { op: 'keyByPattern', re: '(TODO)' }
+#         after:
+#           - { op: 'source', of: 'post' }
+#           - { op: 'lines' }
+#           - { op: 'keyByPattern', re: '(TODO)' }
+#         added:
+#           - { op: 'onlyIn', of: 'after', notIn: 'before' }
+#       relate:
+#         - id: 'nothing-added'
+#           relation: { op: 'empty', of: 'added' }
+#           message: 'adds {key}: {value}'
 #     enforce: advise
 #
 #   # The promotion — block is your choice, never the default.
 #   - id: 'no-todo-in-shipped-code-blocking'
 #     why: 'a TODO nobody owns is a decision deferred out of sight'
-#     forbid: 'TODO'
+#     declare:
+#       mechanism: 'added-only'
+#       scope: { source: 'target.path', include: ['^src/'] }
+#       supply: { pre: 'empty', post: 'empty' }
+#       extract:
+#         before:
+#           - { op: 'source', of: 'pre' }
+#           - { op: 'lines' }
+#           - { op: 'keyByPattern', re: '(TODO)' }
+#         after:
+#           - { op: 'source', of: 'post' }
+#           - { op: 'lines' }
+#           - { op: 'keyByPattern', re: '(TODO)' }
+#         added:
+#           - { op: 'onlyIn', of: 'after', notIn: 'before' }
+#       relate:
+#         - id: 'nothing-added'
+#           relation: { op: 'empty', of: 'added' }
+#           message: 'adds {key}: {value}'
 #     enforce: block
 `;
 /** The schema's path from a config sitting in `projectRoot`, as the directive spells it. */