polydeukes 0.4.0 → 0.6.0

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

@@ -1,24 +1,26 @@
 /**
- * Config discovery and loading (CONFIG-03) — the one place allowed to read and parse the
- * data config file, so the core stays file-I/O-free.
+ * Config discovery and loading — the one place allowed to read and parse the data config
+ * file, so the core stays file-I/O-free.
  *
  * This lives in its own module rather than in the package barrel because ESM re-exports are
- * eager: when `index.ts` re-exports both composition roots, anything importing `loadConfig`
- * from the barrel instantiates the session adapter too. That put `@polydeukes/adapter-claude-code`
- * on the commit surface's load path, where it is never used — a workspace missing only that
- * dist would kill `pdks covenant check` before its fail-closed handler could record a row
- * (PR #46 review). Both composition roots import this module directly for the same reason.
+ * eager: importing `loadConfig` from the barrel would instantiate both composition roots,
+ * putting the session adapter on the commit surface's load path where it is never used. A
+ * workspace missing only that dist would then kill `pdks covenant check` before its
+ * fail-closed handler could record a row. Both composition roots import this module directly
+ * for the same reason.
  */
 import type { ResolvedConfig } from '@polydeukes/core';
 /**
  * The three accepted config filenames, checked directly under the given rootDir. Exported
- * for the scaffold (DIST-02 §3-a): its existence check has to see exactly what discovery
- * sees, or it would create a second spelling and make every later load ambiguous.
+ * for the scaffold: its existence check has to see exactly what discovery sees, or it would
+ * 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'];
-/**
- * `LoadedConfig` — the loader's return value (CONFIG-03 §4.1).
- */
+/** {@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 */
     config: ResolvedConfig;
@@ -26,7 +28,7 @@ export type LoadedConfig = {
     configPath: string;
 };
 /**
- * Discover, parse, and validate the Polydeukes data config in `rootDir` (CONFIG-03 §4.1).
+ * Discover, parse, and validate the Polydeukes data config in `rootDir`.
  *
  * Discovery looks at exactly the three candidate filenames directly under `rootDir`
  * (no upward walk). Every failure branch throws — silent defaults are forbidden:
@@ -38,6 +40,6 @@ export type LoadedConfig = {
  *
  * Before returning, the discovered `configPath` is appended to
  * `config.protectedPaths` unless already present — the config file itself joins the
- * protection surface (schema rule 6), guaranteed here so no assembler has to remember.
+ * 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

@@ -1,13 +1,13 @@
 /**
- * Config discovery and loading (CONFIG-03) — the one place allowed to read and parse the
- * data config file, so the core stays file-I/O-free.
+ * Config discovery and loading — the one place allowed to read and parse the data config
+ * file, so the core stays file-I/O-free.
  *
  * This lives in its own module rather than in the package barrel because ESM re-exports are
- * eager: when `index.ts` re-exports both composition roots, anything importing `loadConfig`
- * from the barrel instantiates the session adapter too. That put `@polydeukes/adapter-claude-code`
- * on the commit surface's load path, where it is never used — a workspace missing only that
- * dist would kill `pdks covenant check` before its fail-closed handler could record a row
- * (PR #46 review). Both composition roots import this module directly for the same reason.
+ * eager: importing `loadConfig` from the barrel would instantiate both composition roots,
+ * putting the session adapter on the commit surface's load path where it is never used. A
+ * workspace missing only that dist would then kill `pdks covenant check` before its
+ * fail-closed handler could record a row. Both composition roots import this module directly
+ * for the same reason.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -15,8 +15,8 @@ import { ConfigValidationError, defineConfig, isPlainObject } from '@polydeukes/
 import { parseDocument } from 'yaml';
 /**
  * The three accepted config filenames, checked directly under the given rootDir. Exported
- * for the scaffold (DIST-02 §3-a): its existence check has to see exactly what discovery
- * sees, or it would create a second spelling and make every later load ambiguous.
+ * for the scaffold: its existence check has to see exactly what discovery sees, or it would
+ * create a second spelling and make every later load ambiguous.
  */
 export const CONFIG_FILENAMES = [
     'polydeukes.config.yaml',
@@ -24,7 +24,7 @@ export const CONFIG_FILENAMES = [
     'polydeukes.config.json',
 ];
 /**
- * Discover, parse, and validate the Polydeukes data config in `rootDir` (CONFIG-03 §4.1).
+ * Discover, parse, and validate the Polydeukes data config in `rootDir`.
  *
  * Discovery looks at exactly the three candidate filenames directly under `rootDir`
  * (no upward walk). Every failure branch throws — silent defaults are forbidden:
@@ -36,9 +36,10 @@ export const CONFIG_FILENAMES = [
  *
  * Before returning, the discovered `configPath` is appended to
  * `config.protectedPaths` unless already present — the config file itself joins the
- * protection surface (schema rule 6), guaranteed here so no assembler has to remember.
+ * 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.d.ts

@@ -1,28 +1,37 @@
 /**
- * `scaffoldProject` — the project-side scaffold layer (DIST-02 §3-i).
+ * `scaffoldProject` — the project-side scaffold layer.
  *
  * The half of an installation every distribution path shares: the data config the judges
  * read, and the telemetry ignore line. What differs between paths is REGISTRATION — how the
  * agent is told to spawn a judge at all — and that lives one layer up (`initClaudeCode` for
- * the `init` path, a manifest for the plugin one). The split is what lets a second path
- * reuse this function unchanged instead of scaffolding a config a second time, so nothing
- * that registers anything belongs here.
+ * the `init` path). The split is what lets a second path reuse this function unchanged
+ * instead of scaffolding a config a second time, so nothing that registers anything belongs
+ * here.
  *
- * Nothing existing is ever overwritten (§5-d invariant 1): an artifact that is already there
- * is reported and left alone. The config existence check reads all three discovery
- * candidates rather than the canonical name alone — writing `polydeukes.config.yaml` next to
- * a project's `.yml` makes {@link loadConfig} throw on ambiguity, and the fail-closed session
- * surface then blocks every call, so the installer itself would be what stopped the project.
- * Existence is FILE PRESENCE, never parse success: reading a broken config as "absent" would
- * destroy the very file the consumer was midway through fixing, and fixing it is their job.
+ * Nothing existing is ever overwritten: an artifact that is already there is reported and
+ * left alone. The config existence check reads all three discovery candidates rather than
+ * the canonical name alone — writing `polydeukes.config.yaml` next to a project's `.yml`
+ * makes {@link loadConfig} throw on ambiguity, and the fail-closed session surface then
+ * blocks every call, so the installer itself would be what stopped the project. Existence is
+ * FILE PRESENCE, never parse success: reading a broken config as "absent" would destroy the
+ * very file the consumer was midway through fixing, and fixing it is their job.
  */
 /**
- * Per-artifact outcome, as `projectRoot`-relative paths — the bin prints it (§3-a stdout
- * contract). `created` names what this run wrote, `skipped` what it found and left alone; a
- * silent skip would leave the user unable to tell an idempotent no-op from a failed run.
+ * Per-artifact outcome, as `projectRoot`-relative paths — the bin prints it. `created` names
+ * what this run wrote, `skipped` what it found and left alone; a silent skip would leave the
+ * user unable to tell an idempotent no-op from a failed run.
  */
 export type ScaffoldReport = {
     created: string[];
     skipped: string[];
 };
+/**
+ * Create the project-side artifacts of a Polydeukes installation in `projectRoot`, skipping
+ * whatever is already there.
+ *
+ * Throws when two or more config spellings coexist — that tree is already stopped, since
+ * {@link loadConfig} refuses an ambiguous discovery, and adding artifacts to it would wire a
+ * judge whose every call fails closed. The throw lands before any write, so a human deleting
+ * one config is all it takes to reopen the path.
+ */
 export declare function scaffoldProject(projectRoot: string): ScaffoldReport;

package/dist/scaffold-project.js

@@ -1,36 +1,36 @@
 /**
- * `scaffoldProject` — the project-side scaffold layer (DIST-02 §3-i).
+ * `scaffoldProject` — the project-side scaffold layer.
  *
  * The half of an installation every distribution path shares: the data config the judges
  * read, and the telemetry ignore line. What differs between paths is REGISTRATION — how the
  * agent is told to spawn a judge at all — and that lives one layer up (`initClaudeCode` for
- * the `init` path, a manifest for the plugin one). The split is what lets a second path
- * reuse this function unchanged instead of scaffolding a config a second time, so nothing
- * that registers anything belongs here.
+ * the `init` path). The split is what lets a second path reuse this function unchanged
+ * instead of scaffolding a config a second time, so nothing that registers anything belongs
+ * here.
  *
- * Nothing existing is ever overwritten (§5-d invariant 1): an artifact that is already there
- * is reported and left alone. The config existence check reads all three discovery
- * candidates rather than the canonical name alone — writing `polydeukes.config.yaml` next to
- * a project's `.yml` makes {@link loadConfig} throw on ambiguity, and the fail-closed session
- * surface then blocks every call, so the installer itself would be what stopped the project.
- * Existence is FILE PRESENCE, never parse success: reading a broken config as "absent" would
- * destroy the very file the consumer was midway through fixing, and fixing it is their job.
+ * Nothing existing is ever overwritten: an artifact that is already there is reported and
+ * left alone. The config existence check reads all three discovery candidates rather than
+ * the canonical name alone — writing `polydeukes.config.yaml` next to a project's `.yml`
+ * makes {@link loadConfig} throw on ambiguity, and the fail-closed session surface then
+ * blocks every call, so the installer itself would be what stopped the project. Existence is
+ * FILE PRESENCE, never parse success: reading a broken config as "absent" would destroy the
+ * very file the consumer was midway through fixing, and fixing it is their job.
  */
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CONFIG_FILENAMES } from './load-config.js';
-/** `.gitignore` name and the telemetry directory entry it must carry (§3-a). */
+/** `.gitignore` name and the telemetry directory entry it must carry. */
 const GITIGNORE = '.gitignore';
 const TELEMETRY_IGNORE_LINE = '.polydeukes/';
 const GITIGNORE_ENTRY = `# Polydeukes telemetry — local observation data, never committed.\n${TELEMETRY_IGNORE_LINE}\n`;
 /**
- * The generated config: the §3-d minimum protection set and the §3-e witness block, both
- * mandatory. Emitted as a literal template rather than serialized from an object because
- * the comments ARE the artifact — a consumer's first contact with the protection surface is
- * reading why each entry is on it.
+ * The generated config: the minimum protection set and the witness block, both mandatory.
+ * Emitted as a literal template rather than serialized from an object because the comments
+ * ARE the artifact — a consumer's first contact with the protection surface is reading why
+ * each entry is on it.
  *
  * {@link schemaDirective} prepends the `yaml-language-server` line when the schema is where
- * that line would name it (DIST-05 §3-b).
+ * that line would name it.
  */
 const GENERATED_CONFIG = `# Polydeukes protection policy — generated by \`pdks init claude-code\`.
 #
@@ -50,14 +50,18 @@ 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.
+#
+# This list is what blocks. Every \`disciplines:\` entry below lands at advise — a break is
+# recorded and the call goes on — unless the entry itself says \`enforce: block\`.
 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
@@ -65,22 +69,74 @@ 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
+
+# The disciplines you judge by, and the three rungs one climbs — shown as three entries so
+# each rung is a line you can copy. Uncomment to start; ids must stay distinct.
+#
+# disciplines:
+#   # A draft: prose only, no predicate. Registered and read, never judged.
+#   - id: 'no-todo-in-shipped-code-draft'
+#     why: 'a TODO nobody owns is a decision deferred out of sight'
+#     draft: true
+#
+#   # 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'
+#     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'
+#     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
 `;
-/**
- * Create the project-side artifacts of a Polydeukes installation in `projectRoot` (§3-i),
- * skipping whatever is already there.
- *
- * Throws when two or more config spellings coexist (§3-a third disposition) — that tree is
- * already stopped, since {@link loadConfig} refuses an ambiguous discovery, and adding
- * artifacts to it would wire a judge whose every call fails closed. The throw lands before
- * any write, so a human deleting one config is all it takes to reopen the path.
- */
 /** The schema's path from a config sitting in `projectRoot`, as the directive spells it. */
 const SCHEMA_REL = 'node_modules/polydeukes/dist/schema/polydeukes.schema.json';
 /**
@@ -99,6 +155,15 @@ function schemaDirective(projectRoot) {
         ? `# yaml-language-server: $schema=${SCHEMA_REL}\n`
         : '';
 }
+/**
+ * Create the project-side artifacts of a Polydeukes installation in `projectRoot`, skipping
+ * whatever is already there.
+ *
+ * Throws when two or more config spellings coexist — that tree is already stopped, since
+ * {@link loadConfig} refuses an ambiguous discovery, and adding artifacts to it would wire a
+ * judge whose every call fails closed. The throw lands before any write, so a human deleting
+ * one config is all it takes to reopen the path.
+ */
 export function scaffoldProject(projectRoot) {
     const report = { created: [], skipped: [] };
     const found = CONFIG_FILENAMES.filter((name) => existsSync(join(projectRoot, name)));