polydeukes 0.4.0 → 0.6.0

package/dist/init-claude-code.js

@@ -1,19 +1,22 @@
 /**
- * `initClaudeCode` — the session-surface installer (DIST-02 §3-a/§3-b/§3-g).
+ * `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, and the
- * discipline file that tells an agent the docs query exists (DOCS-02 §3-e).
+ * 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 (§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.
+ * 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 (§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.
+ * 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';
@@ -21,26 +24,27 @@ 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 (§3-c). */
+/** 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 (§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.
+ * 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 (§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
+ * 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
@@ -71,13 +75,16 @@ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 try {
   const { runClaudeCodeHook } = await import('${HOOK_SPECIFIER}');
   const { exitCode } = await runClaudeCodeHook({ repoRoot });
-  process.exit(exitCode);
+  // 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.exit(2);
+  process.exitCode = 2;
 }
 `;
-/** What a session is about to do, per topic — the correspondence §3-e asks the file to carry. */
+/** 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',
@@ -86,11 +93,10 @@ const DOCS_TOPIC_PURPOSE = {
     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.
+ * 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.
@@ -117,12 +123,218 @@ manager's exec form — from the project root.
 | --- | --- |
 ${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 current families 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
+
+Ask these questions in order; the first yes decides.
+
+| # | Question | Entry key |
+| --- | --- | --- |
+| 1 | Is the promise about content newly ADDED to a file (a pattern that must not appear in new lines)? | \`declare\` (mechanism \`added-only\`) |
+| 2 | Is it about a whole path that must not be modified or deleted (creating it once stays allowed)? | \`declare\` (mechanism \`self-absolution-ban\`) |
+| 3 | Is it about the shell command line itself, regardless of files? | \`declare\` (mechanism \`forbidden-command\`, reading the \`command\` source) |
+| 4 | Does it require that something else was already done earlier in the session (a tool call that must precede this one)? | \`declare\` (mechanism \`precedent\`, reading a \`transcript\` source) |
+| 5 | None of the above | \`draft: true\` (step 4b) |
+
+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
+
+Two kinds of promise cannot be judged here, whatever their shape:
+
+- **Destruction outside the repository** — judgment observes the project root only. Register
+  nothing; use the agent's own permission deny policy for commands like \`rm -rf ~\`.
+- **Writes by child processes** — a test runner or script writing files is invisible to the
+  session surface, which judges declared tool calls only. Say so to the user; the commit
+  surface will still see the result as a staged diff.
+
+### 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
+\`\`\`
+
+**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 SHAPE of the promise inside \`why\`, so the promotion destination is already
+written down when a later engine can express it. Name the shape in these terms:
+
+| Shape | The promise reads like |
+| --- | --- |
+| pairing | every element of set A has a counterpart in set B (translation keys, i18n) |
+| companion | if X appears in a unit, Y must appear with it |
+| ordered | a sequence must keep its order (migration journals, version ladders) |
+| fingerprint | a derived artifact must match the hash/stamp of its source |
+| producer-owned | only a designated generator may write this artifact |
+| self-absolution | the party being judged must not write its own verdict field |
+| actor-scope | the same action is fine for one actor and a break for another |
+| phase-order | several precedents, in a fixed order |
+| turn-locality | the evidence must be in the same turn or time window |
+| stated-ground | the reason must be written down before the action |
+| controlled-vocabulary | only an enumerated set of words/values is allowed |
+| naming-convention | names must match a pattern per kind |
+| irreversible-marker | once present, a marker may never be removed |
+| delegation-scope | a delegated task may touch only its granted scope |
+| scope-valve | a defined exception valve, judged rather than ad hoc |
+| claim-verification | the claim must be re-run/measured, not trusted |
+
+\`\`\`yaml
+languages:
+  placeholder:
+    productionGlob: 'src/**'
+    testCmd: 'echo "set a verification command for {scope}"'
+disciplines:
+  - id: 'locale-files-move-together'
+    why: 'pairing — en.json and ko.json must change in the same commit; one side alone is a break'
+    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 run, and confirm silence on the
+must-NOT-match direction. 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.
+
+## 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 in both directions (DIST-02 §5-e,
- * which also carries the standing risk that `findPackageJSON` is experimental in Node 24).
+ * 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
@@ -135,7 +347,7 @@ function resolveFromProjectRoot(projectRoot) {
     // 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).
+    // verdict.
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
     const subpath = isPlainObject(manifest) && isPlainObject(manifest.exports)
         ? manifest.exports[`./${HOOK_SPECIFIER.split('/')[1]}`]
@@ -209,9 +421,9 @@ function mergeSettings(projectRoot, settings, report) {
     // 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.
+    // 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');
@@ -219,12 +431,12 @@ function mergeSettings(projectRoot, settings, report) {
     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.
+ * 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 (§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.
+ * 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;
@@ -235,21 +447,23 @@ export function initClaudeCode(spec) {
         // 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).
+        // 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 (§5-d invariant 2).
+    // 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. This
-    // artifact is the one whose absence costs only discoverability, so it goes where a
-    // failure costs least.
+    // 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

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