polydeukes 0.6.1 → 0.7.1

package/dist/init-claude-code.js

@@ -1,586 +0,0 @@
-/**
- * `initClaudeCode` — the session-surface installer.
- *
- * One command wires a project into the session surface: prove the package resolves, run the
- * shared project-side scaffold ({@link scaffoldProject}), then add what this distribution
- * path 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. 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';
-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. */
-const HOOK_SPECIFIER = 'polydeukes/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 — the adapter's own vocabulary, never a copy of it. */
-const HOOK_MATCHER = [...MUTATING_TOOLS, ...SHELL_TOOLS].join('|');
-/**
- * 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 init claude-code\`.
- *
- * 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;
-}
-`;
-/** 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 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.
- *
- * Both the command forms and the topic names come from the shipped surface itself — 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 |
-| --- | --- |
-${TOPICS.map((topic) => `| ${DOCS_TOPIC_PURPOSE[topic]} | \`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.
- */
-export 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}"'
-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
-\`\`\`
-
-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'
-disciplines:
-  - 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 commit 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 --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 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 init claude-code\` 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: is `polydeukes` installed where `projectRoot` can reach it?
- *
- * ESM resolution specifically, because that is what the generated hook'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.
- */
-function resolveFromProjectRoot(projectRoot) {
-    // Absence throws here rather than returning undefined (Node 24.18); the branch guards the
-    // documented `string | undefined` return.
-    const manifestPath = findPackageJSON('polydeukes', join(projectRoot, 'package.json'));
-    if (manifestPath === undefined) {
-        throw new Error('polydeukes is not installed where this project can reach it');
-    }
-    // Locating the package is not the question — `findPackageJSON` does not apply its exports
-    // map, so a version predating the session subpath, or one whose dist was never built,
-    // passes a bare-name check while the generated hook fails on every call. That tree cannot
-    // be reopened with the witness token either, because an assembly crash lands before any
-    // verdict.
-    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`);
-    }
-}
-/**
- * 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)})`);
-    }
-    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 }] },
-        ],
-    };
-    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 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 or when two
- * config spellings already coexist there — both 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;
-    try {
-        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: "not exposed" and "not installed" need different actions, and
-        // an experimental resolver can fail for reasons that are neither.
-        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)}`);
-    }
-    // Every read that can fail is settled before the first write.
-    const settings = readSettings(spec.projectRoot);
-    const report = scaffoldProject(spec.projectRoot);
-    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);
-    retargetGrokHookCommandToClaude(spec.projectRoot);
-    return report;
-}

package/dist/init-grok.d.ts

@@ -1,51 +0,0 @@
-/**
- * `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;