@polydeukes/adapter-claude-code 0.6.1 → 0.8.0

package/dist/init.js

@@ -0,0 +1,594 @@
+/**
+ * `initClaudeCode` — the Claude Code session-surface installer.
+ *
+ * One command wires a project into the session surface: prove `polydeukes` resolves, spawn
+ * its agent-neutral scaffold (`pdks init`, which writes the config and the telemetry ignore
+ * line), then add what this package owns — the delegator hook file, its
+ * `.claude/settings.json` registration, the discipline file that tells an agent the docs
+ * query exists, and the classification skill that turns a described problem into a config
+ * entry.
+ *
+ * Preflight comes first and nothing is written before it clears. A generated hook whose
+ * import can never resolve blocks every call through its own fail-closed catch, and a tree
+ * that also has no config and no valve to open cannot be edited back into shape from inside
+ * the session.
+ *
+ * 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.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isPlainObject } from '@polydeukes/core';
+import { findUmbrellaBin, UMBRELLA_PACKAGE } from './resolve-umbrella.js';
+import { MUTATING_TOOLS, SHELL_TOOLS } from './session-vocabulary.js';
+/** The package the generated delegator loads `runHook` from. */
+const ADAPTER_SPECIFIER = '@polydeukes/adapter-claude-code';
+/** The registration artifacts, as `projectRoot`-relative paths (the report vocabulary). */
+const HOOK_RELATIVE = '.claude/hooks/covenant-pretooluse.mjs';
+const SETTINGS_RELATIVE = '.claude/settings.json';
+const DISCOVERY_RELATIVE = '.claude/rules/polydeukes.md';
+const SKILL_RELATIVE = '.claude/skills/discipline-draft/SKILL.md';
+/**
+ * The command the host spawns, and the string our registration is recognized by: the same
+ * command already present means already registered. A registration keyed on anything else
+ * would be re-added on every run, and the host would then spawn the judge twice per call —
+ * every verdict and every telemetry row doubled.
+ */
+const HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR"/${HOOK_RELATIVE}`;
+/** Which calls reach the judge — this package's own vocabulary, never a copy of it. */
+const HOOK_MATCHER = [...MUTATING_TOOLS, ...SHELL_TOOLS].join('|');
+/** The umbrella's docs topics — a copy of its `DOCS_TOPICS` tuple, pinned equal by test. */
+const DOCS_TOPICS = ['install', 'config', 'discipline', 'covenant', 'witness'];
+/** What a session is about to do per topic — the correspondence the generated file carries. */
+const DOCS_TOPIC_PURPOSE = {
+    install: 'install Polydeukes, or wire another surface into this project',
+    config: 'edit `polydeukes.config.*` — every key and what reads it',
+    discipline: 'add or change a `disciplines` entry',
+    covenant: 'explain a verdict, or why a surface failed closed',
+    witness: 'open a blocked call in person',
+};
+/** The umbrella's config spellings — a copy of its `CONFIG_FILENAMES` tuple, pinned equal by test. */
+const CONFIG_FILENAMES = [
+    'polydeukes.config.yaml',
+    'polydeukes.config.yml',
+    'polydeukes.config.json',
+];
+/**
+ * The generated hook. It carries no assembly at all, so upgrading the package upgrades the
+ * judge without regenerating this file.
+ */
+const GENERATED_HOOK = `#!/usr/bin/env node
+/**
+ * Polydeukes PreToolUse covenant hook — generated by \`pdks-claude-code init\`.
+ *
+ * A delegator and nothing more: \`runHook\` builds the covenant input from this payload and
+ * spawns \`pdks covenant check\`, so the judgment lives in the installed packages and this
+ * file never needs regenerating.
+ *
+ * \`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 package lookup need is the project that CONTAINS this hook — always \`../..\`
+ * from here.
+ *
+ * fail-closed: \`runHook\` translates every failure it can reach into exit 2, with the row
+ * written by the judge it spawns. 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 { runHook } = await import('${ADAPTER_SPECIFIER}');
+  const { exitCode } = runHook({ 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 generated discipline file — the discovery path that gets the query surface called. A
+ * query an agent never learns about is a query that does not exist. One scoped file costs
+ * nothing while it waits: `paths` frontmatter keeps it out of context until a Polydeukes
+ * path is in play.
+ *
+ * The topic names and config spellings are literals here and belong to the umbrella's
+ * surface; a file naming a query that exits 2 fails the agent once, and it never calls the
+ * command again.
+ */
+const GENERATED_DISCOVERY = `---
+paths:
+${CONFIG_FILENAMES.map((name) => `  - "${name}"`).join('\n')}
+  - ".claude/**"
+---
+
+# Polydeukes — query the installed docs
+
+This project is judged by Polydeukes, and the matching documentation ships inside the
+installed package. \`pdks docs\` answers offline, from the same version that does the
+judging; a web search answers from whichever release it indexed.
+
+Run \`pdks docs\` for the topic list, \`pdks docs <topic>\` for topic content,
+\`pdks docs search "locale key pairing"\` to find a section, or
+\`pdks docs show write-disciplines\` to retrieve the guide. Add \`--lang ko\` for Korean.
+
+A local install puts the bin in \`node_modules/.bin\`, which a plain shell does not have on
+PATH. If \`pdks\` is not found, run \`./node_modules/.bin/pdks docs <topic>\` — or your package
+manager's exec form — from the project root.
+
+| Before you | Run |
+| --- | --- |
+${Object.entries(DOCS_TOPIC_PURPOSE)
+    .map(([topic, purpose]) => `| ${purpose} | \`pdks docs ${topic}\` |`)
+    .join('\n')}
+`;
+/**
+ * The generated classification skill — the procedure that turns a described problem into a
+ * registered entry. A classification procedure an agent never learns about is one that never
+ * runs, so it ships as an artifact of the install rather than as prose in a README.
+ *
+ * Its advise-consumption section is the delivery path for advised rows: the session surface
+ * lets an advised call through with exit 0, and the reason never reaches the model at call
+ * time — reading the telemetry log at task boundaries is the only way it arrives.
+ */
+const GENERATED_SKILL = `---
+name: discipline-draft
+description: Turn a described discipline problem into a registered entry in polydeukes.config — a judged entry when the declaration grammar and observed evidence can express it, a draft entry otherwise. Use when the user describes a recurring problem they want promised away ("I keep...", "stop X from happening", "we should never...", "how do I enforce Y").
+---
+
+# discipline-draft — from a problem description to a registered discipline
+
+This project is judged by Polydeukes. A discipline starts as prose and climbs a ladder —
+\`draft\` (registered, read, never judged) → \`advise\` (judged, recorded, never stops a call) →
+\`block\` (stops the call; the user's explicit choice, never the default). This skill walks a
+problem description down to the right first rung and registers it.
+
+## Procedure
+
+### 1. Restate the problem as a promise
+
+Rewrite the description as one sentence of the form "X must not happen" or "when A happens,
+B must also happen". If the sentence needs "unless" more than once, split it into two
+promises and classify each separately.
+
+### 2. Classify the shape
+
+Choose from the current catalogue, then check whether the intended surface can supply the
+required evidence. A mechanism name constrains the declaration; it does not implement the
+promise by itself. The extracted axes and body relations must be subsets of the admitted
+sets below. Scope filtering is separate from the extracted axes.
+
+| Mechanism | Admitted axes | Body relations | Evidence or structural condition |
+| --- | --- | --- | --- |
+| \`pairing\` | \`world\` | \`equal\` | Compare supplied files or channels; extract keys when values may differ. |
+| \`companion\` | \`change\`, \`world\` | \`implies\` | Compare presence by key; a multi-file promise needs the observed change set. |
+| \`monotonic-order\` | \`change\`, \`world\` | \`ordered\` | Extract a sequence with an explicit comparison field; order is not presence. |
+| \`fingerprint-sync\` | \`world\` | \`equal\` | Compare supplied stamps; no generator or compiler runs during judgment. |
+| \`producer-owned\` | \`actor\` | \`empty\`, \`nonEmpty\` | Requires host-provided actor evidence, not an artifact's self-reported producer. |
+| \`self-absolution-ban\` | \`change\` | \`unchanged\`, \`empty\` | Extract protected fields or path changes; choose creation/deletion supply explicitly. |
+| \`actor-scope\` | \`actor\` | \`empty\`, \`nonEmpty\` | Requires a proven actor; a missing actor is not proof of the main session. |
+| \`precedent\` | \`history\`, \`world\` | \`nonEmpty\` | Requires an observed earlier call in a transcript or supplied channel. |
+| \`phase-order\` | \`history\` | \`ordered\` | Compare observed call ordinals; missing phases need a separate presence promise. |
+| \`turn-locality\` | \`history\` | \`nonEmpty\` | Requires observed turns and time or ordinal boundaries. |
+| \`stated-ground\` | \`history\` | \`nonEmpty\` | Can require recorded text, not establish whether its reasoning is sound. |
+| \`controlled-vocabulary\` | \`change\`, \`world\` | \`subset\` | Extract values and an explicit allowed set. |
+| \`naming\` | \`change\` | \`empty\`, \`nonEmpty\` | Scope must read \`target.path\`; match the intended name pattern. |
+| \`added-only\` | \`change\` | \`empty\` | Compare pre/post extractions and judge only newly added matches. |
+| \`one-way-marker\` | \`change\` | \`subset\` | Existing markers must remain in the extracted post-change set. |
+| \`delegated-scope\` | — | — | Reserved for a definition-time evaluator; not accepted in current declarations. |
+| \`scoped-valve\` | \`change\`, \`actor\`, \`world\`, \`history\` | \`empty\`, \`nonEmpty\`, \`equal\`, \`subset\`, \`implies\`, \`ordered\`, \`unchanged\` | Requires a \`witness\` block expressing the exception condition. |
+| \`forbidden-command\` | \`change\` | \`empty\` | Scope must read \`command\`; a text pattern is not shell semantic analysis. |
+
+These four requests illustrate the classification boundary:
+
+| Request | Classification | Proof |
+| --- | --- | --- |
+| The English and Korean locale files must carry identical keys. | \`pairing\`, with two supplied files. | An unmatched key breaks; translated values may differ. |
+| Every status must belong to an allowed list. | \`controlled-vocabulary\`, with a supplied allowed set. | An unknown status breaks; an allowed status passes. |
+| A successful package lookup must precede a manifest edit. | \`precedent\`, with observed session history. | Failed or absent lookups break; an unavailable transcript is a supply case. |
+| A fresh benchmark must execute during judgment to prove a performance claim. | \`draft\`: the engine does not execute benchmarks. | Comparing an existing report would be a different promise. |
+
+Run \`pdks docs show write-disciplines\` for the key-pairing walkthrough and
+\`pdks docs show configuration --section disciplines\` for the declaration grammar.
+Use \`--lang ko\` for Korean; these commands read the installed version offline.
+
+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.
+
+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
+
+Do not confuse an expressible relation with available evidence:
+
+- **Files outside the repository** — file-change protection observes the project root.
+  Use the host's permission policy for comprehensive protection outside it. A command-text
+  pattern may recognize a particular string, but does not observe all resulting writes.
+- **Writes by child processes** — arbitrary writes inside a test runner or script are not
+  individually observed by the session surface. A commit comparison can observe the resulting
+  files when they enter its selected diff; it does not recover the originating tool history.
+- **Missing history or actor channels** — choose the declaration's supply policy explicitly.
+  Commit observations have no session transcript; \`supply: pass\` records a skip, not success.
+- **Fresh execution or semantic proof** — the engine compares supplied evidence. It does not
+  run a new benchmark or prove that a written explanation is true. Preserve that unmet promise
+  as a draft rather than silently replacing it with a weaker text check.
+
+### 4a. Expressible now — register a judged entry
+
+Add the entry to the \`disciplines:\` array in \`polydeukes.config.yaml\`. Advise is the default
+landing — a break is recorded as \`advised\` and the call goes on — and the \`enforce: advise\`
+line below only spells that default out. NEVER write \`enforce: block\` from this skill:
+promotion to block is the user's own choice, made after the advise measurements have been
+read.
+
+The examples below are whole documents, so \`languages:\` — the schema's one required block —
+appears alongside the entry; in a config that already has one, copy the entry only.
+
+\`\`\`yaml
+languages:
+  placeholder:
+    productionGlob: 'src/**'
+    testCmd: 'echo "set a verification command for {scope}"'
+disciplines:
+  - id: 'no-focused-tests'
+    why: 'a committed .only silently shrinks the suite to one test'
+    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}"'
+sessionDisciplines:
+  - 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
+\`\`\`
+
+The following examples implement the first three classification cases. Both locale files and
+the allowed-status file must exist and contain valid JSON. File bindings use the proposed
+contents for a file changed by the current observation, not a second stale disk read.
+
+\`\`\`yaml
+languages:
+  json:
+    productionGlob: 'locales/**/*.json'
+    testCmd: 'pnpm test'
+disciplines:
+  - id: 'locale-key-parity'
+    why: 'the ko and en locales must carry the same keys'
+    declare:
+      mechanism: 'pairing'
+      scope: { source: 'target.path', include: ['^locales/(ko|en)[.]json$'] }
+      sources:
+        ko: { file: 'locales/ko.json' }
+        en: { file: 'locales/en.json' }
+      supply: { ko: 'error', en: 'error' }
+      extract:
+        koKeys: [{ op: 'source', of: 'ko' }, { op: 'json' }, { op: 'flattenKeys' }]
+        enKeys: [{ op: 'source', of: 'en' }, { op: 'json' }, { op: 'flattenKeys' }]
+      relate:
+        - id: 'parity'
+          relation: { op: 'equal', of: ['koKeys', 'enKeys'] }
+          messageBySide:
+            left: '{key} is in ko only'
+            right: '{key} is in en only'
+    enforce: advise
+\`\`\`
+
+\`\`\`yaml
+languages:
+  json:
+    productionGlob: '*.json'
+    testCmd: 'pnpm test'
+disciplines:
+  - id: 'status-vocabulary'
+    why: 'statuses.json may contain only values listed in allowed-statuses.json'
+    declare:
+      mechanism: 'controlled-vocabulary'
+      scope: { source: 'target.path', include: ['^statuses[.]json$'] }
+      sources: { allowed: { file: 'allowed-statuses.json' } }
+      supply: { post: 'error', allowed: 'error' }
+      extract:
+        selected: [{ op: 'source', of: 'post' }, { op: 'json' }, { op: 'items' }]
+        permitted: [{ op: 'source', of: 'allowed' }, { op: 'json' }, { op: 'items' }]
+      relate:
+        - id: 'allowed-status'
+          relation: { op: 'subset', of: 'selected', in: 'permitted' }
+          message: 'unknown status: {value}'
+    enforce: advise
+\`\`\`
+
+Here both status files are JSON arrays of strings. This declaration scopes on statuses.json;
+editing only the allowed list does not trigger it. Broaden the observation deliberately if
+changes to that list must recheck all dependent files.
+
+\`\`\`yaml
+languages:
+  typescript:
+    productionGlob: 'src/**'
+    testCmd: 'pnpm test'
+sessionDisciplines:
+  - id: 'manifest-needs-npm-view'
+    why: 'a successful package lookup must precede a manifest edit'
+    declare:
+      mechanism: 'precedent'
+      scope: { source: 'target.path', include: ['^(packages/[^/]+/)?package[.]json$'] }
+      sources: { session: { transcript: true } }
+      supply: { session: 'pass' }
+      extract:
+        npmView:
+          - { op: 'source', of: 'session' }
+          - { op: 'toolUses', names: ['Bash'] }
+          - { op: 'filter', when: [{ field: 'succeeded', eq: true }] }
+          - { op: 'select', path: 'args.command' }
+          - { op: 'matches', re: '^npm view ' }
+      relate:
+        - id: 'npm-view'
+          relation: { op: 'nonEmpty', of: 'npmView' }
+          message: 'no successful npm view precedes this edit'
+    enforce: advise
+\`\`\`
+
+The precedent example proves only that an observed successful Bash call starts with npm view;
+it does not prove that the lookup concerns the dependency being edited. The change-set surface has
+no transcript and therefore skips this example by its explicit supply policy.
+
+**Write the regex yourself — the user states the promise, you author the pattern.** The
+pattern is the part users find hardest, so never hand the prose back and ask for one. Three
+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 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 (\`only(\` vs \`only_helper(\`, a flag vs its
+  substring). A pattern checked in only the breaking direction over-fires in review-proof
+  ways.
+
+### 4b. Not expressible yet — register a draft
+
+A draft is prose with a handle: \`id\`, \`why\`, and the literal marker \`draft: true\` — no other
+keys. It produces no judgment and no telemetry; \`pdks explain\` lists it as unpromoted.
+Record the intended promise and the exact missing capability inside \`why\`. Do not classify
+pairing, vocabulary, or history promises as drafts merely because they are absent from a short
+example list. Check the catalogue, extraction steps, and observation channel first. A reserved
+\`delegated-scope\` declaration cannot be registered as a judged entry.
+
+\`\`\`yaml
+languages:
+  placeholder:
+    productionGlob: 'src/**'
+    testCmd: 'echo "set a verification command for {scope}"'
+disciplines:
+  - id: 'benchmark-supports-performance-claim'
+    why: 'a performance claim needs a fresh benchmark run during judgment; the engine cannot execute it'
+    draft: true
+\`\`\`
+
+### 5. Prove it fires, then close
+
+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 the declaration's
+own mechanism can actually reach:
+
+| Mechanism | Break it once | The entry's id shows up in |
+| --- | --- | --- |
+| a file-reading one (\`added-only\`, \`naming\`, …) | one scratch edit matching the must-match direction | \`pdks covenant check --diff\` output over \`git diff HEAD\` on stdin — 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 change-set surface has none, so its \`supply\` policy records it \`skipped\`) |
+
+Then undo the scratch break, repeat the same observation, and confirm a passing row for the
+must-NOT-match case. Silence alone may mean a scope miss, unchanged files, or unavailable evidence;
+check \`pdks explain\` and telemetry for \`config-fault\`, \`no-observation\`, or \`supply-pass\`. Close by telling the user which rung the entry landed on and
+that \`enforce: block\` is theirs to add later if the advise record earns it.
+
+## Updating this skill without losing local edits
+
+An upgrade does not overwrite an existing skill; rerunning \`pdks-claude-code init\` reports it
+skipped. Generate a fresh copy in a disposable project using the installed package, compare it
+with this file, and merge the changes you want. Keep a backup of local additions. Do not delete
+the existing skill to force regeneration in the working project.
+
+## Reading the advise record
+
+An \`advised\` row means a promise was broken and the call went through anyway. Rows land in
+the telemetry log at the path configured by \`telemetry.logPath\` (default
+\`.polydeukes/roi.log\`). The hook's stderr note is not shown to you, so consult the log at
+task boundaries: before committing, or after a batch of edits, read the tail and act on any
+\`advised\` row — fix the break, or tell the user why it should stand. An advisory nobody
+reads measures nothing.
+`;
+/** The default preflight: where is `polydeukes` installed, as reachable from `projectRoot`? */
+function resolveFromProjectRoot(projectRoot) {
+    const bin = findUmbrellaBin(projectRoot);
+    if (bin === undefined) {
+        throw new Error(`${UMBRELLA_PACKAGE} is not installed where this project can reach it`);
+    }
+    return bin;
+}
+/**
+ * Is our PreToolUse command already in this settings object? Asked twice — before the merge
+ * to stay idempotent, and after the write to prove the file took it.
+ */
+function carriesRegistration(settings) {
+    return (settings.hooks?.PreToolUse ?? []).some((entry) => (entry?.hooks ?? []).some((hook) => hook?.command === HOOK_COMMAND));
+}
+/** 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);
+}
+/**
+ * Read the settings file, or an empty one when there is none yet. Belongs to preflight
+ * rather than to the merge: parsing it later would leave a wired-but-unregistered tree —
+ * delegator on disk, host never told to spawn it, every call unjudged with no telemetry row.
+ */
+function readSettings(projectRoot) {
+    const settingsPath = join(projectRoot, SETTINGS_RELATIVE);
+    if (!existsSync(settingsPath)) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    }
+    catch (error) {
+        throw new Error(`cannot parse ${SETTINGS_RELATIVE} in ${projectRoot} — fix it and re-run ` +
+            `(${error instanceof Error ? error.message : String(error)})`);
+    }
+    // Only a plain object can carry a `hooks` key. An array root takes the assignment as a
+    // non-index property that JSON.stringify discards, and a null root throws inside the merge
+    // — both after the scaffold and the delegator have already landed. Refusing here keeps
+    // every precondition failure at zero files.
+    if (!isPlainObject(parsed)) {
+        throw new Error(`${SETTINGS_RELATIVE} in ${projectRoot} is not a JSON object — fix it and re-run`);
+    }
+    return parsed;
+}
+/**
+ * Add the PreToolUse registration to `.claude/settings.json`, keeping everything else the
+ * file carries — other registrations, other hook events, and unrelated keys alike. A
+ * settings file with no `hooks` key at all is the commonest consumer state (it exists for
+ * permissions alone), so the nesting is created here rather than assumed.
+ */
+function mergeSettings(projectRoot, settings, report) {
+    const settingsPath = join(projectRoot, SETTINGS_RELATIVE);
+    const preToolUse = settings.hooks?.PreToolUse ?? [];
+    if (carriesRegistration(settings)) {
+        // Not rewriting is the point: a re-serialization would rewrite a consumer's formatting
+        // on every run, which is an overwrite by another name.
+        report.skipped.push(SETTINGS_RELATIVE);
+        return;
+    }
+    settings.hooks = {
+        ...settings.hooks,
+        PreToolUse: [
+            ...preToolUse,
+            { matcher: HOOK_MATCHER, hooks: [{ type: 'command', command: HOOK_COMMAND }] },
+        ],
+    };
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    // Read the registration back rather than assuming the write carried it. The one outcome
+    // this installer must never produce is a successful-looking run whose judge never spawns,
+    // and the merge can drop the entry without failing — a settings file whose root is an
+    // array takes the assignment as a non-index property and `JSON.stringify` discards it.
+    // Checking the file instead of the shapes that reach it keeps the question finite: one
+    // code path, asked after every write, whatever arrived.
+    if (!carriesRegistration(JSON.parse(readFileSync(settingsPath, 'utf-8')))) {
+        throw new Error(`${SETTINGS_RELATIVE} in ${projectRoot} did not take the PreToolUse registration — ` +
+            'the judge would never be spawned. Fix that file and re-run');
+    }
+    report.created.push(SETTINGS_RELATIVE);
+}
+/**
+ * Install the Claude Code session surface into `spec.projectRoot`, skipping whatever is
+ * already there and reporting both halves per artifact.
+ *
+ * Throws before any write when the umbrella cannot be resolved from that root, when the
+ * settings file cannot be parsed, or when the scaffold refuses — all three leave zero files.
+ * Translating a throw into exit 2 with the install command is the bin's job.
+ */
+export function initClaudeCode(spec) {
+    const resolvePolydeukes = spec.resolvePolydeukes ?? resolveFromProjectRoot;
+    let scaffoldBin;
+    try {
+        scaffoldBin = resolvePolydeukes(spec.projectRoot);
+    }
+    catch (error) {
+        // The message names the package because the user's next action is installing it — the
+        // seam's own message cannot be relied on to say so. The original is carried through
+        // rather than discarded: an experimental resolver can fail for reasons that are
+        // neither absence nor a stale version.
+        throw new Error(`cannot use '${UMBRELLA_PACKAGE}' from ${spec.projectRoot} — install or update it there ` +
+            `first (e.g. 'npm install --save-dev ${UMBRELLA_PACKAGE}'), then run this command ` +
+            `again: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Every read that can fail is settled before the first write, and before the scaffold:
+    // a parse failure after it would leave a tree carrying the config alone.
+    const settings = readSettings(spec.projectRoot);
+    const spawnScaffold = spec.spawnScaffold ??
+        ((scaffold) => spawnSync(scaffold.command, scaffold.args, { cwd: scaffold.cwd, stdio: 'inherit' }));
+    const scaffold = spawnScaffold({
+        command: process.execPath,
+        args: [scaffoldBin, 'init'],
+        cwd: spec.projectRoot,
+    });
+    if (scaffold.status !== 0) {
+        // Any non-zero status is a scaffold that did not run: registering a delegator into a
+        // tree with no config wires a judge whose every call fails closed.
+        throw new Error(`'pdks init' failed in ${spec.projectRoot} (exit ${String(scaffold.status)}) — ` +
+            'fix what it reported and re-run');
+    }
+    const report = { created: [], skipped: [] };
+    writeIfAbsent(spec.projectRoot, HOOK_RELATIVE, GENERATED_HOOK, report);
+    mergeSettings(spec.projectRoot, settings, report);
+    // Written last, after the registration the hook needs to ever be spawned. Every write
+    // between the hook file and that registration widens the window where a throw leaves a
+    // delegator nothing invokes — a tree that looks installed and is judged by nothing. These
+    // two artifacts are the ones whose absence costs only discoverability, so they go where
+    // a failure costs least.
+    writeIfAbsent(spec.projectRoot, DISCOVERY_RELATIVE, GENERATED_DISCOVERY, report);
+    writeIfAbsent(spec.projectRoot, SKILL_RELATIVE, GENERATED_SKILL, report);
+    return report;
+}

package/dist/resolve-umbrella.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Locating the `polydeukes` install a session surface runs through.
+ *
+ * Both users of this module ask the same question from the same anchor — the project root,
+ * never this module's own location. Anchoring at the installer or the hook would answer for
+ * the graph THIS package was installed into, which is a different tree from the one being
+ * judged or wired.
+ */
+/** The umbrella package both the spawn and the preflight look for. */
+export declare const UMBRELLA_PACKAGE = "polydeukes";
+/**
+ * The absolute path of the umbrella's `pdks` bin as reachable from `projectRoot`, or
+ * `undefined` when there is nothing to spawn.
+ *
+ * ESM resolution specifically, because that is what a generated delegator's `await
+ * import(...)` runs; the CJS alternatives were measured disagreeing with it in both
+ * directions. `findPackageJSON` is experimental in Node 24, so its behaviour can still
+ * change.
+ *
+ * A manifest found but carrying no `bin.pdks` answers `undefined` too: spawning `node
+ * undefined` crashes with no verdict and no row, which reads to the caller as the same
+ * absence reached without saying so.
+ */
+export declare function findUmbrellaBin(projectRoot: string): string | undefined;

package/dist/resolve-umbrella.js

@@ -0,0 +1,52 @@
+/**
+ * Locating the `polydeukes` install a session surface runs through.
+ *
+ * Both users of this module ask the same question from the same anchor — the project root,
+ * never this module's own location. Anchoring at the installer or the hook would answer for
+ * the graph THIS package was installed into, which is a different tree from the one being
+ * judged or wired.
+ */
+import { readFileSync } from 'node:fs';
+import { findPackageJSON } from 'node:module';
+import { join } from 'node:path';
+import { isPlainObject } from '@polydeukes/core';
+/** The umbrella package both the spawn and the preflight look for. */
+export const UMBRELLA_PACKAGE = 'polydeukes';
+/**
+ * The absolute path of the umbrella's `pdks` bin as reachable from `projectRoot`, or
+ * `undefined` when there is nothing to spawn.
+ *
+ * ESM resolution specifically, because that is what a generated delegator's `await
+ * import(...)` runs; the CJS alternatives were measured disagreeing with it in both
+ * directions. `findPackageJSON` is experimental in Node 24, so its behaviour can still
+ * change.
+ *
+ * A manifest found but carrying no `bin.pdks` answers `undefined` too: spawning `node
+ * undefined` crashes with no verdict and no row, which reads to the caller as the same
+ * absence reached without saying so.
+ */
+export function findUmbrellaBin(projectRoot) {
+    let manifestPath;
+    try {
+        // Absence throws here rather than returning undefined (Node 24.18); the branch below
+        // guards the documented `string | undefined` return.
+        manifestPath = findPackageJSON(UMBRELLA_PACKAGE, join(projectRoot, 'package.json'));
+    }
+    catch {
+        return undefined;
+    }
+    if (manifestPath === undefined)
+        return undefined;
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+    const bin = isPlainObject(manifest) ? manifest.bin : undefined;
+    const pdks = isPlainObject(bin) ? bin.pdks : undefined;
+    if (typeof pdks !== 'string')
+        return undefined;
+    return join(manifestPath, '..', pdks);
+}