polydeukes 0.0.1 → 0.4.0

package/dist/init-claude-code.js

@@ -0,0 +1,255 @@
+/**
+ * `initClaudeCode` — the session-surface installer (DIST-02 §3-a/§3-b/§3-g).
+ *
+ * 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, and the
+ * discipline file that tells an agent the docs query exists (DOCS-02 §3-e).
+ *
+ * Preflight comes first and nothing is written before it clears (§5-d invariant 2). 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 — the brick §3-g exists to prevent.
+ *
+ * Nothing existing is overwritten (§5-d invariant 1). 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 { 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 { CONFIG_FILENAMES } from './load-config.js';
+import { scaffoldProject } from './scaffold-project.js';
+/** The published entry point the generated hook loads the judge through (§3-c). */
+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';
+/**
+ * The command the host spawns, and the string our registration is recognized by: the same
+ * command already present means already registered (§3-a). 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 (§3-b) — a copy of this repository's own delegator with its dogfooding
+ * narrative removed. 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 });
+  process.exit(exitCode);
+} catch (error) {
+  console.error(\`covenant hook failed closed: \${error?.message ?? error}\`);
+  process.exit(2);
+}
+`;
+/** What a session is about to do, per topic — the correspondence §3-e asks the file to carry. */
+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 (DOCS-02 §3-e) — the discovery path that gets the query
+ * surface called. A query an agent never learns about is a query that does not exist, and
+ * the alternative place to say so is the consumer's own resident instructions, which are
+ * theirs to write. 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 one section.
+
+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 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 in both directions (DIST-02 §5-e,
+ * which also carries the standing risk that `findPackageJSON` is experimental in Node 24).
+ */
+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 (PR #48 review).
+    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
+    // (PR #48 review). 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` (DIST-02 §3-a), skipping whatever is
+ * already there and reporting both halves per artifact.
+ *
+ * Throws before any write when the package cannot be resolved from that root (§3-g) or when
+ * two config spellings already coexist there (§3-a third disposition) — 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 (PR #48 review).
+        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 (§5-d invariant 2).
+    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. This
+    // artifact is the one whose absence costs only discoverability, so it goes where a
+    // failure costs least.
+    writeIfAbsent(spec.projectRoot, DISCOVERY_RELATIVE, GENERATED_DISCOVERY, report);
+    return report;
+}

package/dist/load-config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+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.
+ */
+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).
+ */
+export type LoadedConfig = {
+    /** defineConfig() resolution — protectedPaths already includes configPath */
+    config: ResolvedConfig;
+    /** rootDir-relative path of the discovered config file */
+    configPath: string;
+};
+/**
+ * Discover, parse, and validate the Polydeukes data config in `rootDir` (CONFIG-03 §4.1).
+ *
+ * Discovery looks at exactly the three candidate filenames directly under `rootDir`
+ * (no upward walk). Every failure branch throws — silent defaults are forbidden:
+ * zero files found (message names all three candidates), two or more found (message
+ * names the collisions), a parse error or unresolved custom tag (safe core schema —
+ * config data is never executable; every problem the parser found is enumerated in the
+ * one message), or a `ConfigValidationError` from core `defineConfig()` (re-thrown with
+ * file-path context, keeping the error type).
+ *
+ * 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.
+ */
+export declare function loadConfig(rootDir: string): LoadedConfig;

package/dist/load-config.js

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ConfigValidationError, defineConfig, isPlainObject } from '@polydeukes/core';
+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.
+ */
+export const CONFIG_FILENAMES = [
+    'polydeukes.config.yaml',
+    'polydeukes.config.yml',
+    'polydeukes.config.json',
+];
+/**
+ * Discover, parse, and validate the Polydeukes data config in `rootDir` (CONFIG-03 §4.1).
+ *
+ * Discovery looks at exactly the three candidate filenames directly under `rootDir`
+ * (no upward walk). Every failure branch throws — silent defaults are forbidden:
+ * zero files found (message names all three candidates), two or more found (message
+ * names the collisions), a parse error or unresolved custom tag (safe core schema —
+ * config data is never executable; every problem the parser found is enumerated in the
+ * one message), or a `ConfigValidationError` from core `defineConfig()` (re-thrown with
+ * file-path context, keeping the error type).
+ *
+ * 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.
+ */
+export function loadConfig(rootDir) {
+    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(', ')}`);
+    }
+    if (found.length > 1) {
+        throw new Error(`ambiguous Polydeukes config in ${rootDir} — found ${found.join(' and ')}; keep exactly one`);
+    }
+    const configPath = found[0];
+    const source = readFileSync(join(rootDir, configPath), 'utf-8');
+    // Default core schema — custom tags stay unresolved and surface as errors or
+    // warnings depending on version; both escalate to a throw (config-as-data:
+    // uncomputable, so it cannot lie).
+    const document = parseDocument(source);
+    const problems = [...document.errors, ...document.warnings];
+    if (problems.length > 0) {
+        // Every problem in one message: reporting only the first costs one fix-rerun loop
+        // per hidden problem. Each parser message already carries its own position; a lone
+        // problem keeps the direct message shape.
+        const detail = problems.length === 1
+            ? problems[0].message
+            : `${problems.length} problems\n${problems.map((problem) => `  - ${problem.message}`).join('\n')}`;
+        throw new Error(`failed to parse ${configPath}: ${detail}`);
+    }
+    const parsed = document.toJS();
+    // Strip the IDE `$schema` reference before delegating — the loader owns no
+    // structural validation beyond this key removal.
+    let input = parsed;
+    if (isPlainObject(parsed)) {
+        const { $schema: _schema, ...rest } = parsed;
+        input = rest;
+    }
+    let config;
+    try {
+        config = defineConfig(input);
+    }
+    catch (error) {
+        if (error instanceof ConfigValidationError) {
+            throw new ConfigValidationError(`invalid config in ${configPath}: ${error.message}`);
+        }
+        throw error;
+    }
+    // Self-protection attach (idempotent) — the discovered config file is part of
+    // the protection surface.
+    const protectedPaths = config.protectedPaths ?? [];
+    if (!protectedPaths.includes(configPath)) {
+        config = { ...config, protectedPaths: [...protectedPaths, configPath] };
+    }
+    return { config, configPath };
+}

package/dist/scaffold-project.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `scaffoldProject` — the project-side scaffold layer (DIST-02 §3-i).
+ *
+ * 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.
+ *
+ * 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.
+ */
+/**
+ * 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.
+ */
+export type ScaffoldReport = {
+    created: string[];
+    skipped: string[];
+};
+export declare function scaffoldProject(projectRoot: string): ScaffoldReport;

package/dist/scaffold-project.js

@@ -0,0 +1,137 @@
+/**
+ * `scaffoldProject` — the project-side scaffold layer (DIST-02 §3-i).
+ *
+ * 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.
+ *
+ * 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.
+ */
+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). */
+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.
+ *
+ * {@link schemaDirective} prepends the `yaml-language-server` line when the schema is where
+ * that line would name it (DIST-05 §3-b).
+ */
+const GENERATED_CONFIG = `# Polydeukes protection policy — generated by \`pdks init claude-code\`.
+#
+# This file is data, never code. The judges read it, every verdict traces back to an entry
+# below, and editing it is how you change what is judged.
+
+# The language axis, the schema's one required block. \`init\` cannot know yours, so this is
+# a placeholder: rename the key, point productionGlob at your own sources, and put your own
+# verification command in testCmd (every literal {scope} is substituted at resolve time).
+# No judgment path reads these values yet, so the placeholder cannot produce a wrong verdict
+# while it waits to be edited.
+languages:
+  placeholder:
+    productionGlob: 'src/**'
+    testCmd: 'echo "set a verification command for {scope}"'
+
+# 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.
+#
+# A minimum. Add entries as you find you want them.
+protectedPaths:
+  - '.claude/hooks'
+  - '.claude/settings.json'
+
+# 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
+# resumes on its own. The valve is consulted only AFTER a verdict blocked, so an opened
+# 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.
+witness:
+  token: 'pdks witness'
+  ttlMinutes: 10
+`;
+/**
+ * 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';
+/**
+ * The `yaml-language-server` line for a config written into `projectRoot`, or nothing.
+ *
+ * An editor resolves a relative `$schema` against the config file's own directory, and this
+ * command writes the config where it was invoked — so in a monorepo sub-package, whose install
+ * hoisted to the workspace root, {@link SCHEMA_REL} names a path that is not there. The check
+ * is one look at that exact path: present means the line an editor would follow leads to the
+ * schema, absent means it leads nowhere, and a line leading nowhere is worse than none. An
+ * unresolvable `$schema` produces no editor error and no validation, and a line the tool wrote
+ * is not one its user thinks to audit.
+ */
+function schemaDirective(projectRoot) {
+    return existsSync(join(projectRoot, SCHEMA_REL))
+        ? `# yaml-language-server: $schema=${SCHEMA_REL}\n`
+        : '';
+}
+export function scaffoldProject(projectRoot) {
+    const report = { created: [], skipped: [] };
+    const found = CONFIG_FILENAMES.filter((name) => existsSync(join(projectRoot, name)));
+    if (found.length > 1) {
+        throw new Error(`ambiguous Polydeukes config in ${projectRoot} — found ${found.join(' and ')}; ` +
+            'keep exactly one and re-run');
+    }
+    if (found.length === 1) {
+        report.skipped.push(found[0]);
+    }
+    else {
+        writeFileSync(join(projectRoot, CONFIG_FILENAMES[0]), schemaDirective(projectRoot) + GENERATED_CONFIG);
+        report.created.push(CONFIG_FILENAMES[0]);
+    }
+    // The entry is judged as a whole line. A substring test would treat a commented-out line
+    // or a deeper path (`.polydeukes/roi.log`) as coverage and skip the append, leaving the
+    // consumer committing their own telemetry — the failure that matters. Whole-line equality
+    // errs the other way instead: a project already ignoring the directory under a different
+    // spelling (`.polydeukes`, `/.polydeukes/`) gets a second, redundant entry. A duplicate
+    // ignore rule costs a line; a missing one costs the consumer's telemetry. Appending is
+    // also the only safe write — a `.gitignore` rewritten wholesale takes every entry the
+    // consumer already relies on with it.
+    const gitignorePath = join(projectRoot, GITIGNORE);
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
+    if (existing.split('\n').some((line) => line.trim() === TELEMETRY_IGNORE_LINE)) {
+        report.skipped.push(GITIGNORE);
+    }
+    else {
+        // A file that ends without a newline would otherwise absorb the entry into its last
+        // line, breaking that entry while never forming ours.
+        const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+        appendFileSync(gitignorePath, `${separator}${GITIGNORE_ENTRY}`);
+        report.created.push(GITIGNORE);
+    }
+    return report;
+}