polydeukes 0.5.0 → 0.6.0

package/dist/docs/reference/polydeukes.md

@@ -12,6 +12,11 @@ every other dependency in this repository runs one way, through the core alone.
 this page the consumer-facing surface: the four scoped packages are transitive dependencies
 you do not install and do not import.
 
+The judge and the two adapters take the core as a `peerDependency` rather than a dependency
+of their own, so they share one copy of the vocabulary instead of each carrying its own. The
+umbrella's ordinary dependency on the core is what satisfies that peer, which is why
+installing this one package is still all a consumer does.
+
 | Package | Reference | Owns |
 |---|---|---|
 | `@polydeukes/core` | [core](./core.md) | The protocol, the config schema, telemetry |
@@ -22,8 +27,8 @@ you do not install and do not import.
 ## Subcommands
 
 The bin is `pdks`, with `polydeukes` as an alias. Every argument form is matched against a
-finite table: `covenant check` takes an optional domain flag, `init claude-code` is exact,
-`explain` takes one word, and `docs` takes an optional topic.
+finite table: `covenant check` takes an optional domain flag, `init claude-code` and
+`init grok` are exact, `explain` takes one word, and `docs` takes an optional topic.
 
 ### `pdks covenant check`
 
@@ -57,9 +62,10 @@ two report exit `2` without a prompt, since there is no commit for a human to op
 | No config, more than one config, or an invalid one | exit `2` |
 | A judge body that cannot be loaded | exit `2` |
 
-Context-family disciplines (`requirePrecedent`) assemble here like any other entry, but this
-surface has no session to read: a match records `skipped` and the commit proceeds. That is a
-permanent condition of the commit surface, not a fault.
+Declarations that read the session (`precedent` and the other history mechanisms) assemble
+here like any other entry, but this surface has no session to read: a match records
+`skipped` and the commit proceeds. That is a permanent condition of the commit surface, not a
+fault.
 
 ### `pdks init claude-code`
 
@@ -80,6 +86,22 @@ alone, so a re-run is a no-op. A precondition failure — the package not resolv
 coexisting config spellings, an unparseable settings file — writes zero files and exits `2`,
 never a half-wired tree.
 
+### `pdks init grok`
+
+The Grok session-surface installer. Same preflight and the same shared scaffold (config and
+the `.polydeukes/` ignore line). A Grok-only tree gets four artifacts (hook JSON, the grok
+delegator, config, ignore line) and no `.claude/` directory. The JSON registration carries
+`timeout` 60 (the host default is 5 seconds; a timed-out hook fails open). If
+`.claude/hooks/covenant-pretooluse.mjs` already exists, the JSON command points at that file
+so the host does not spawn two judges. A later run of either installer retargets an
+installer-generated grok-mjs command the same way, and the JSON matcher follows the
+`.claude/settings.json` entry for that command (Grok collapses two registrations only when
+command and matcher both match); a command pointed elsewhere is left alone.
+
+An already-open Grok session keeps the hook snapshot from start; reload from the Hooks tab
+(`r`) or start a new session. The witness valve does not open on Grok: the session log is
+ACP `updates.jsonl`, not Claude's JSONL.
+
 ### `pdks docs [topic]`
 
 The offline documentation reader. The guides and this reference layer ship inside the
@@ -123,37 +145,37 @@ read.
 ```text
 pdks explain — polydeukes.config.yaml
 
-surface: session (claude-code hook)
-  registrations 23 · judged 11 · skip 9 · meta 3 · excluded 0 · draft 1
-  meta     self-mod                 paths 13 (common; includes the config file itself)
-  judge    covenant-vocabulary      forbid · in packages/*/src/** · except … · why ✓
-  skip     covenant-vocabulary      a shell write in scope whose result this layer cannot compute
-  draft    bilingual-docs-sync      unpromoted — no judgment
+surface: session (claude-code hook) · disciplines: advise unless enforce: block · meta: block
+  registrations 43 · declare 21 · skip 19 · meta 3 · draft 1
+  meta     self-mod                      paths 14 (common; includes the config file itself)
+  declare  covenant-vocabulary           added-only · change · empty nothing-added · scope target.path · include 1 · exclude 1 · sources 0 · valve — · why ✓
+  declare  pnpm-only                     forbidden-command · change · empty no-npm-mutation · scope command · include 0 · exclude 0 · sources 0 · valve — · why ✓
+  declare  manifest-needs-evidence       precedent · history · nonEmpty npm-view, context7 · scope target.path · include 1 · exclude 0 · sources 1 (transcript 1) · valve — · why ✓
+  skip     covenant-vocabulary           a shell write in scope whose result this layer cannot compute
   ...
-surface: commit (git pre-commit) · enforce: advise
-  registrations 10 · judged 3 · skip 6 · meta 1 · excluded 3 · draft 1
-  skip     manifest-needs-npm-view  no session transcript to read
-  excluded hooks-stay-armed         forbidCommand — no shell axis on this surface
-  draft    bilingual-docs-sync      unpromoted — no judgment
+surface: commit (git pre-commit) · enforce: advise · disciplines: advise unless enforce: block
+  registrations 24 · declare 22 · skip 1 · meta 1 · draft 1
+  declare  manifest-needs-evidence       precedent · history · nonEmpty npm-view, context7 · scope target.path · include 1 · exclude 0 · sources 1 (transcript 1) · valve — · why ✓
+  declare  sqlite-only-under-knowledge   naming · change · empty placed · scope target.path · include 1 · exclude 0 · sources 0 · valve — · why ✓
 ```
 
 One line per registration, in the order the surface dispatches them. The kind column has
-five words: `meta` (the registrations protecting the judging chain — `self-mod`,
-`shell-mod`, and on the session surface `transcript-mod`), `judge` (an entry with a judge
-body, with its family, routing scope, and whether it carries a `why`), `skip` (a registration
-that records `skipped` instead of judging, with the reason the compiler gave — the reason
-that otherwise reaches stderr only on a config fault), `excluded` (a `forbidCommand`
-entry on the commit surface, which has no shell axis), and `draft` (an unpromoted
+four words: `meta` (the registrations protecting the judging chain — `self-mod`,
+`shell-mod`, and on the session surface `transcript-mod`), `declare` (a declaration entry,
+with its mechanism, axes and relations, its scope source, the sizes of its include and
+exclude lists, its sources, and whether it carries a valve and a `why`), `skip` (a
+registration that records `skipped` instead of judging, with the reason the compiler gave —
+the reason that otherwise reaches stderr only on a config fault), and `draft` (an unpromoted
 `draft: true` entry, shown on both surfaces since it belongs to neither). `registrations`
-counts the first three; `excluded` and `draft` are tallied apart because neither ever
-becomes a registration.
+counts `meta`, `declare`, and `skip`; `draft` is tallied apart because it never becomes a
+registration.
 The commit surface's header also names its `adapters.git.enforce` level, since an advising
 surface records the same table but blocks nothing.
 
 The session surface is rendered as the hook sees it under a normal payload — with a
-transcript present — so `transcript-mod` and the context family appear as they do in a
-session; the commit surface shows the context family as skips, which is that surface's
-permanent condition.
+transcript present — so `transcript-mod` and the session-reading declarations appear as they
+do in a session; on the commit surface those declarations record `skipped` when matched,
+which is that surface's permanent condition.
 
 | Call | Result |
 |---|---|
@@ -165,12 +187,12 @@ permanent condition.
 
 Anything that is not one of these forms writes the usage line —
 `usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain |
-pdks init claude-code | pdks docs [topic]` — to stderr and exits `2`.
+pdks init claude-code | pdks init grok | pdks docs [topic]` — to stderr and exits `2`.
 
 ## Exit codes
 
 Three codes exist, and they live at two layers. **What a consumer's hook observes is only
-`0` or `2`** — both composition roots return `Promise<{ exitCode: 0 | 2 }>`.
+`0` or `2`** — both composition roots resolve to a named outcome carrying `exitCode: 0 | 2`.
 
 | Code | Constant | Emitted by | Means |
 |---|---|---|---|
@@ -200,7 +222,9 @@ This is the whole public API; the scoped packages are not part of it.
 **Type signature:**
 
 ```ts
-function loadConfig(rootDir: string): LoadedConfig;
+function loadConfig(spec: LoadConfigSpec): LoadedConfig;
+
+type LoadConfigSpec = { rootDir: string };
 
 type LoadedConfig = {
   config: ResolvedConfig;  // protectedPaths already includes the config file itself
@@ -218,7 +242,9 @@ a silently unprotected project.
 **Type signature:**
 
 ```ts
-function runCovenantCheck(spec: CovenantCheckSpec): Promise<{ exitCode: 0 | 2 }>;
+function runCovenantCheck(spec: CovenantCheckSpec): Promise<CovenantCheckOutcome>;
+
+type CovenantCheckOutcome = { exitCode: 0 | 2 };
 
 type CovenantCheckSpec = {
   repoRoot: string;                                  // config discovery and collection anchor here
@@ -247,7 +273,9 @@ or nothing.
 **Type signature:**
 
 ```ts
-function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<{ exitCode: 0 | 2 }>;
+function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<ClaudeCodeHookOutcome>;
+
+type ClaudeCodeHookOutcome = { exitCode: 0 | 2 };
 
 type ClaudeCodeHookSpec = {
   repoRoot: string;         // config discovery and discipline glob scoping anchor here
@@ -273,8 +301,8 @@ needs no second dependency.
 
 | Specifier | Carries |
 |---|---|
-| `polydeukes` | The barrel — `loadConfig`, `runCovenantCheck`, `runClaudeCodeHook`, their spec types, `ResolvedConfig` |
-| `polydeukes/claude-code` | `runClaudeCodeHook` and `ClaudeCodeHookSpec` alone |
+| `polydeukes` | The barrel — `loadConfig`, `runCovenantCheck`, their spec and outcome types, `ResolvedConfig`. The session hook lives on its own subpath below and nowhere else |
+| `polydeukes/claude-code` | `runClaudeCodeHook`, `ClaudeCodeHookSpec`, and `ClaudeCodeHookOutcome` alone |
 | `polydeukes/schema.json` | The config JSON Schema, copied from the core at build time |
 
 The generated hook delegator imports the subpath, not the barrel. ESM imports are eager, so

package/dist/docs/troubleshooting.md

@@ -29,7 +29,10 @@ Discovery looks for exactly these, in this order: `polydeukes.config.yaml`,
 defaults — silent defaults would mean silently unprotected.
 
 **Recovery.** Restore the file from git. On the session path,
-`pnpm exec pdks init claude-code` recreates the missing artifacts; on the commit path the
+`pnpm exec pdks init claude-code` or `pdks init grok` recreates files that
+are absent. An existing grok JSON is not rewritten except when its `command`
+still names the grok delegator and a Claude delegator is on disk — then that
+command is retargeted and the matcher follows the settings entry. On the commit path the
 config is hand-written — the [install guide](./installation.md)'s commit-surface section
 has a starting point.
 
@@ -58,6 +61,30 @@ empty `languages` block, the schema's one required entry.
 **Recovery.** Fix the named key in the named file. The error is specific on purpose — no
 rewrite-and-hope needed.
 
+## A Grok session does not pick up a newly installed hook
+
+**Symptom.** `pdks init grok` reported created files, but this session's tool calls still
+leave no telemetry row.
+
+**Cause.** Grok loads hooks at session start. An already-open session keeps that snapshot.
+
+**Recovery.** Press `r` in the Hooks tab, or start a new session. The witness valve also
+does not open on Grok — a block is recovered from another terminal or the commit-surface TTY.
+
+## One Grok tool call leaves two telemetry rows
+
+**Symptom.** In a tree wired for both Claude Code and Grok, every `write` or
+`run_terminal_command` in a Grok session appends two rows to `.polydeukes/roi.log`,
+milliseconds apart.
+
+**Cause.** Grok reads `.claude/settings.json` as well as `.grok/hooks/*.json` and collapses
+the two registrations only when `command` and `matcher` are both identical. A grok JSON
+whose matcher differs from the settings entry spawns the judge a second time.
+
+**Recovery.** Make the grok JSON's `matcher` the same string as the settings entry that
+registers the same command. Re-running either installer does it: every grok entry that
+names the Claude hook takes the settings entry's matcher.
+
 ## `pdks init claude-code` refuses to run
 
 **Symptom.** The installer prints an install command and exits 2 without creating anything.
@@ -144,18 +171,18 @@ that *cannot judge* (missing or invalid config, an unresolvable judge) still exi
 
 ## `skipped` rows on the commit surface
 
-**Symptom.** A `requirePrecedent` discipline that judges normally in sessions always lands
-as `skipped` on commits.
+**Symptom.** A `precedent` declaration that judges normally in sessions always lands as
+`skipped` on commits.
 
-**Cause.** Context-family disciplines judge *session history* — was the required step
-actually executed before this change. A commit has no session to read, so the entry
-assembles as a skip registration: routing intact, no judge body. When its scope matches a
-staged change it records `skipped` with the entry's id and proceeds.
+**Cause.** A declaration that reads the session judges *session history* — was the required
+step actually executed before this change. A commit has no session to read, so the
+declaration's own `supply: { session: 'pass' }` takes over: when its scope matches a staged
+change it records `skipped` with the reason `supply-pass` and the entry's id, and proceeds.
 
 **Recovery.** None needed — this is a declared condition of the surface, not a defect. The
 row is the point: a gate that did nothing says so in the data. `pdks explain` shows the
-same fact before any commit: every context entry appears under the commit surface as a
-`skip` line carrying the reason. A context-family entry is
+same fact before any commit: the entry appears under the commit surface with its
+`transcript` source, which that surface never supplies. Such a declaration is
 really a session-surface tool — on a project that wires only the commit surface, such an
 entry only ever buys telemetry, so declare it where an AI partner's session exists to be
 judged. The row appears only when the entry's scope actually matched, so an unrelated

package/dist/explain.d.ts

@@ -16,11 +16,9 @@ export type ExplainSpec = {
 /**
  * Read the config at `repoRoot`, assemble both surfaces, and render them.
  *
- * The session assembly is given a transcript path, so its `transcript-mod` registration and
- * the context family exist here exactly as they do under a normal hook payload — the path is
- * never read, because the injected transcript is the no-op one. Without a transcript the
- * compiler would report every context entry as a skip, which is the COMMIT surface's answer,
- * not the session's.
+ * The session assembly is given a transcript path, so its `transcript-mod` registration
+ * exists here exactly as it does under a normal hook payload — the path is never read,
+ * because the injected transcript is the no-op one.
  */
 export declare function explain(spec: ExplainSpec): Promise<{
     text: string;

package/dist/explain.js

@@ -11,39 +11,45 @@
  */
 import { join } from 'node:path';
 import { resolveGitAdapterSettings } from '@polydeukes/adapter-git';
-import { noopTranscript } from '@polydeukes/core';
+import { AXIS_NAMES, deriveShape, noopTranscript, RELATION_NAMES } from '@polydeukes/core';
 import { assembleSessionRegistrations } from './claude-code-hook.js';
 import { assembleCommitRegistrations } from './covenant-check.js';
 import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
 import { loadConfig } from './load-config.js';
 /** The three meta-covenant labels: registrations that protect the judging chain itself. */
 const META_LABELS = new Set(['self-mod', 'shell-mod', 'transcript-mod']);
-/** Normalize an optional glob field to an array (absent = empty). */
-function toGlobs(value) {
-    if (value === undefined)
-        return [];
-    return typeof value === 'string' ? [value] : value;
-}
 /**
- * The routing scope of a config entry, in its own family's shape: the delta and context
- * families scope by `in`/`except` globs, the path family by its own glob, and the command
- * family by nothing at all — it judges the command line, which no path scopes.
+ * The description of a declaration entry: its catalogue coordinate (the mechanism, the axes
+ * its sources derive, and the relations its entries decide), then what it routes on, how
+ * large its two regex lists are, how many sources it names and how many of those carry
+ * each non-file kind, whether it carries a valve, and whether the author left a `why`. An
+ * absent scope block admits every world.
+ *
+ * The axes are derived, never read off the declaration: `loadConfig` has already run the
+ * declaration through the validator, so the shape here is the one the catalogue admitted.
  */
-function scopeOf(entry) {
-    if (entry.immutable !== undefined) {
-        return `immutable ${toGlobs(entry.immutable).join(', ')}`;
-    }
-    if (entry.forbidCommand !== undefined) {
-        return 'forbidCommand · (no path scope)';
-    }
-    const family = entry.requirePrecedent === undefined
-        ? 'forbid'
-        : `requirePrecedent ${Object.keys(entry.requirePrecedent).join(', ')}`;
-    const inGlobs = toGlobs(entry.in);
-    const scope = inGlobs.length === 0 ? 'every file' : `in ${inGlobs.join(', ')}`;
-    const exceptGlobs = toGlobs(entry.except);
-    const except = exceptGlobs.length === 0 ? '' : ` · except ${exceptGlobs.join(', ')}`;
-    return `${family} · ${scope}${except}`;
+function declareDescription(entry, enforce) {
+    const declare = entry.declare;
+    const shape = deriveShape(declare);
+    const axes = AXIS_NAMES.filter((axis) => shape.axes.has(axis)).join(',');
+    const relations = RELATION_NAMES.filter((relation) => shape.relations.has(relation)).join(',');
+    const relate = declare.relate.map((relateEntry) => relateEntry.id).join(', ');
+    const scope = declare.scope === undefined ? 'scope every world' : `scope ${declare.scope.source}`;
+    const include = declare.scope?.include?.length ?? 0;
+    const exclude = declare.scope?.exclude?.length ?? 0;
+    const bindings = Object.values(declare.sources ?? {});
+    // A file binding is the unmarked kind, so only the two the surface has to supply are
+    // counted out; a kind nothing binds is left off rather than printed as a zero.
+    const kinds = ['sidecar', 'transcript']
+        .map((kind) => ({ kind, count: bindings.filter((binding) => kind in binding).length }))
+        .filter(({ count }) => count > 0)
+        .map(({ kind, count }) => `${kind} ${count}`);
+    const counted = kinds.length === 0 ? '' : ` (${kinds.join(', ')})`;
+    const sources = `sources ${bindings.length}${counted}`;
+    const valve = declare.witness === undefined ? '—' : '✓';
+    const why = entry.why === undefined ? '—' : '✓';
+    return (`${declare.mechanism} · ${axes} · ${relations} ${relate} · ${scope} · ` +
+        `include ${include} · exclude ${exclude} · ${sources} · valve ${valve} · why ${why}${enforce}`);
 }
 /** One rendered line: the kind column, the label column, then the description. */
 function row(kind, label, width, description) {
@@ -59,8 +65,8 @@ function metaDescription(registration, surface) {
 /** Render one surface: its header, its tallies, and one line per registration. */
 function renderSurface(spec) {
     const lines = [];
-    const width = Math.max(...spec.registrations.map((registration) => registration.label.length), ...spec.excluded.map((entry) => entry.id.length), ...spec.drafts.map((draft) => draft.id.length));
-    let judged = 0;
+    const width = Math.max(...spec.registrations.map((registration) => registration.label.length), ...spec.drafts.map((draft) => draft.id.length));
+    let declare = 0;
     let skip = 0;
     let meta = 0;
     for (const registration of spec.registrations) {
@@ -75,38 +81,35 @@ function renderSurface(spec) {
             lines.push(row('skip', registration.label, width, registration.skip.reason));
             continue;
         }
-        judged += 1;
+        // Every non-meta body registration is one config entry's declaration; a label the config
+        // does not carry is an assembly the renderer was never told about.
         const entry = spec.disciplines.find((candidate) => candidate.id === registration.label);
+        if (entry === undefined) {
+            throw new Error(`explain: registration '${registration.label}' matches no config entry`);
+        }
         // The DECLARED level is rendered, never the effective one: an omission stays unmarked
         // so the default and an author's explicit choice of it never read alike, and the
         // surface header states what the omission resolves to.
-        const level = entry?.enforce === undefined ? '' : ` · enforce: ${entry.enforce}`;
-        const description = entry === undefined
-            ? ''
-            : `${scopeOf(entry)} · why ${entry.why === undefined ? '—' : '✓'}${level}`;
-        lines.push(row('judge', registration.label, width, description));
-    }
-    for (const entry of spec.excluded) {
-        lines.push(row('excluded', entry.id, width, 'forbidCommand — no shell axis on this surface'));
+        const level = entry.enforce === undefined ? '' : ` · enforce: ${entry.enforce}`;
+        declare += 1;
+        lines.push(row('declare', registration.label, width, declareDescription(entry, level)));
     }
     for (const draft of spec.drafts) {
         lines.push(row('draft', draft.id, width, 'unpromoted — no judgment'));
     }
-    const tally = `  registrations ${meta + judged + skip} · judged ${judged} · skip ${skip} · ` +
-        `meta ${meta} · excluded ${spec.excluded.length} · draft ${spec.drafts.length}`;
+    const tally = `  registrations ${meta + declare + skip} · ` +
+        `declare ${declare} · skip ${skip} · meta ${meta} · draft ${spec.drafts.length}`;
     return [spec.header, tally, ...lines].join('\n');
 }
 /**
  * Read the config at `repoRoot`, assemble both surfaces, and render them.
  *
- * The session assembly is given a transcript path, so its `transcript-mod` registration and
- * the context family exist here exactly as they do under a normal hook payload — the path is
- * never read, because the injected transcript is the no-op one. Without a transcript the
- * compiler would report every context entry as a skip, which is the COMMIT surface's answer,
- * not the session's.
+ * The session assembly is given a transcript path, so its `transcript-mod` registration
+ * exists here exactly as it does under a normal hook payload — the path is never read,
+ * because the injected transcript is the no-op one.
  */
 export async function explain(spec) {
-    const { config, configPath } = loadConfig(spec.repoRoot);
+    const { config, configPath } = loadConfig({ rootDir: spec.repoRoot });
     // Resolved and imported exactly as the two runners do, so what this renders is the table
     // that would judge: a dist those runners would refuse cannot be rendered as if it worked.
     // The load names the missing module and the recovery command.
@@ -125,14 +128,13 @@ export async function explain(spec) {
         rootDir: spec.repoRoot,
         covenant,
     });
-    const gitSettings = resolveGitAdapterSettings(config.adapters?.git);
+    const gitSettings = resolveGitAdapterSettings({ namespace: config.adapters?.git });
     const text = [
         `pdks explain — ${configPath}`,
         '',
         renderSurface({
             header: 'surface: session (claude-code hook) · disciplines: advise unless enforce: block · meta: block',
             registrations: session,
-            excluded: [],
             drafts,
             disciplines,
             selfModScope: 'common; includes the config file itself',
@@ -141,7 +143,6 @@ export async function explain(spec) {
         renderSurface({
             header: `surface: commit (git pre-commit) · enforce: ${gitSettings.enforce} · disciplines: advise unless enforce: block`,
             registrations: commit,
-            excluded: disciplines.filter((entry) => entry.forbidCommand !== undefined),
             drafts,
             disciplines,
             selfModScope: 'common ∪ adapters.git; deduped, includes the config file itself',

package/dist/index.d.ts

@@ -18,6 +18,5 @@
  * See https://github.com/huskyhoochu/polydeukes
  */
 export type { ResolvedConfig } from '@polydeukes/core';
-export { type ClaudeCodeHookSpec, runClaudeCodeHook } from './claude-code-hook.js';
-export { type CheckDomain, type CovenantCheckSpec, runCovenantCheck } from './covenant-check.js';
-export { type LoadedConfig, loadConfig } from './load-config.js';
+export { type CheckDomain, type CovenantCheckOutcome, type CovenantCheckSpec, runCovenantCheck, } from './covenant-check.ts';
+export { type LoadConfigSpec, type LoadedConfig, loadConfig } from './load-config.ts';

package/dist/index.js

@@ -17,6 +17,5 @@
  *
  * See https://github.com/huskyhoochu/polydeukes
  */
-export { runClaudeCodeHook } from './claude-code-hook.js';
-export { runCovenantCheck } from './covenant-check.js';
+export { runCovenantCheck, } from './covenant-check.js';
 export { loadConfig } from './load-config.js';

package/dist/init-claude-code.d.ts

@@ -14,9 +14,11 @@
  *
  * 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.
+ * 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 { type ScaffoldReport } from './scaffold-project.js';
+import { type ScaffoldReport } from './scaffold-project.ts';
 /**
  * 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
@@ -26,7 +28,7 @@ import { type ScaffoldReport } from './scaffold-project.js';
  * 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 declare const GENERATED_SKILL = "---\nname: discipline-draft\ndescription: Turn a described discipline problem into a registered entry in polydeukes.config \u2014 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\").\n---\n\n# discipline-draft \u2014 from a problem description to a registered discipline\n\nThis project is judged by Polydeukes. A discipline starts as prose and climbs a ladder \u2014\n`draft` (registered, read, never judged) \u2192 `advise` (judged, recorded, never stops a call) \u2192\n`block` (stops the call; the user's explicit choice, never the default). This skill walks a\nproblem description down to the right first rung and registers it.\n\n## Procedure\n\n### 1. Restate the problem as a promise\n\nRewrite the description as one sentence of the form \"X must not happen\" or \"when A happens,\nB must also happen\". If the sentence needs \"unless\" more than once, split it into two\npromises and classify each separately.\n\n### 2. Classify the shape\n\nAsk these questions in order; the first yes decides.\n\n| # | Question | Family | Entry key |\n| --- | --- | --- | --- |\n| 1 | Is the promise about content newly ADDED to a file (a pattern that must not appear in new lines)? | delta | `forbid` |\n| 2 | Is it about a whole path that must not be modified or deleted (creating it once stays allowed)? | path | `immutable` |\n| 3 | Is it about the shell command line itself, regardless of files? | command | `forbidCommand` |\n| 4 | Does it require that something else was already done earlier in the session (a tool call that must precede this one)? | context | `requirePrecedent` |\n| 5 | None of the above | \u2014 | `draft: true` (step 4b) |\n\nExisting occurrences are forgiven by the delta family \u2014 only new additions break the promise.\nThat is usually what you want: a discipline adopted today should not indict yesterday's code.\n\nTwo path-shaped promises take no `disciplines:` entry at all. A path nobody may touch\nbelongs in the top-level `protectedPaths:` list \u2014 its own config block, never an entry\nkey. And a path that must never be CREATED is not expressible today: `immutable` allows\ncreation by design, so register that promise as a draft (step 4b).\n\n### 3. Check the observation boundary\n\nTwo kinds of promise cannot be judged here, whatever their shape:\n\n- **Destruction outside the repository** \u2014 judgment observes the project root only. Register\n  nothing; use the agent's own permission deny policy for commands like `rm -rf ~`.\n- **Writes by child processes** \u2014 a test runner or script writing files is invisible to the\n  session surface, which judges declared tool calls only. Say so to the user; the commit\n  surface will still see the result as a staged diff.\n\n### 4a. Expressible now \u2014 register a judged entry\n\nAdd the entry to the `disciplines:` array in `polydeukes.config.yaml`. Advise is the default\nlanding \u2014 a break is recorded as `advised` and the call goes on \u2014 and the `enforce: advise`\nline below only spells that default out. NEVER write `enforce: block` from this skill:\npromotion to block is the user's own choice, made after the advise measurements have been\nread.\n\nThe examples below are whole documents, so `languages:` \u2014 the schema's one required block \u2014\nappears alongside the entry; in a config that already has one, copy the entry only.\n\n```yaml\nlanguages:\n  placeholder:\n    productionGlob: 'src/**'\n    testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n  - id: 'no-focused-tests'\n    why: 'a committed .only silently shrinks the suite to one test'\n    forbid: '\\.only\\('\n    enforce: advise\n```\n\n**Write the regex yourself \u2014 the user states the promise, you author the pattern.** The\npattern is the part users find hardest, so never hand the prose back and ask for one. Three\nauthoring traps, each measured on a live config:\n\n- **A pattern answers a syntactic question only.** \"Is this string a forbidden word\" is\n  syntax; \"is this a new dependency version\" is meaning, and a regex leaks both ways on a\n  semantic question. When the question is semantic, narrow `in:` to the files where any\n  match IS a break (`in:`/`except:` scope `forbid` and `requirePrecedent` only), or\n  accept \"editing this file at all\" as the trigger.\n- **`^` silently disarms on the delta axis.** `forbid` scans whole file content as one\n  string, so a line-start anchor matches the first line only \u2014 write `(^|\\n)` there.\n  `forbidCommand` judges per line and the whole string, so `^` is safe on that axis.\n- **Author both directions.** Before registering, write down one string the pattern must\n  match and one nearby string it must not (`forbid` vs `forbidden`, a flag vs its\n  substring). A pattern checked in only the breaking direction over-fires in review-proof\n  ways.\n\n### 4b. Not expressible yet \u2014 register a draft\n\nA draft is prose with a handle: `id`, `why`, and the literal marker `draft: true` \u2014 no other\nkeys. It produces no judgment and no telemetry; `pdks explain` lists it as unpromoted.\nRecord the SHAPE of the promise inside `why`, so the promotion destination is already\nwritten down when a later engine can express it. Name the shape in these terms:\n\n| Shape | The promise reads like |\n| --- | --- |\n| pairing | every element of set A has a counterpart in set B (translation keys, i18n) |\n| companion | if X appears in a unit, Y must appear with it |\n| ordered | a sequence must keep its order (migration journals, version ladders) |\n| fingerprint | a derived artifact must match the hash/stamp of its source |\n| producer-owned | only a designated generator may write this artifact |\n| self-absolution | the party being judged must not write its own verdict field |\n| actor-scope | the same action is fine for one actor and a break for another |\n| phase-order | several precedents, in a fixed order |\n| turn-locality | the evidence must be in the same turn or time window |\n| stated-ground | the reason must be written down before the action |\n| controlled-vocabulary | only an enumerated set of words/values is allowed |\n| naming-convention | names must match a pattern per kind |\n| irreversible-marker | once present, a marker may never be removed |\n| delegation-scope | a delegated task may touch only its granted scope |\n| scope-valve | a defined exception valve, judged rather than ad hoc |\n| claim-verification | the claim must be re-run/measured, not trusted |\n\n```yaml\nlanguages:\n  placeholder:\n    productionGlob: 'src/**'\n    testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n  - id: 'locale-files-move-together'\n    why: 'pairing \u2014 en.json and ko.json must change in the same commit; one side alone is a break'\n    draft: true\n```\n\n### 5. Prove it fires, then close\n\nRun `pdks explain` and confirm the new entry is listed (a judged entry with its family and\nsurfaces; a draft as unpromoted).\n\nFor a judged entry, registration is not the finish \u2014 a pattern that never fires protects\nnothing while looking installed. Fire it once for real, with the proof run its family can\nactually reach:\n\n| Family | Break it once | The entry's id shows up in |\n| --- | --- | --- |\n| `forbid` / `immutable` | one scratch edit matching the must-match direction | `pdks covenant check --worktree` output \u2014 the exit stays 0 at advise, the id is the proof |\n| `forbidCommand` | run one harmless command matching the pattern | the telemetry log tail \u2014 at advise the call proceeds and its row records the id |\n| `requirePrecedent` | one in-scope edit made without the required precedent | the telemetry log tail \u2014 this family judges on the session surface only (the commit surface records it `skipped`) |\n\nThen undo the scratch break, repeat the same run, and confirm silence on the\nmust-NOT-match direction. Close by telling the user which rung the entry landed on and\nthat `enforce: block` is theirs to add later if the advise record earns it.\n\n## Reading the advise record\n\nAn `advised` row means a promise was broken and the call went through anyway. Rows land in\nthe telemetry log at the path configured by `telemetry.logPath` (default\n`.polydeukes/roi.log`). The hook's stderr note is not shown to you, so consult the log at\ntask boundaries: before committing, or after a batch of edits, read the tail and act on any\n`advised` row \u2014 fix the break, or tell the user why it should stand. An advisory nobody\nreads measures nothing.\n";
+export declare const GENERATED_SKILL = "---\nname: discipline-draft\ndescription: Turn a described discipline problem into a registered entry in polydeukes.config \u2014 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\").\n---\n\n# discipline-draft \u2014 from a problem description to a registered discipline\n\nThis project is judged by Polydeukes. A discipline starts as prose and climbs a ladder \u2014\n`draft` (registered, read, never judged) \u2192 `advise` (judged, recorded, never stops a call) \u2192\n`block` (stops the call; the user's explicit choice, never the default). This skill walks a\nproblem description down to the right first rung and registers it.\n\n## Procedure\n\n### 1. Restate the problem as a promise\n\nRewrite the description as one sentence of the form \"X must not happen\" or \"when A happens,\nB must also happen\". If the sentence needs \"unless\" more than once, split it into two\npromises and classify each separately.\n\n### 2. Classify the shape\n\nAsk these questions in order; the first yes decides.\n\n| # | Question | Entry key |\n| --- | --- | --- |\n| 1 | Is the promise about content newly ADDED to a file (a pattern that must not appear in new lines)? | `declare` (mechanism `added-only`) |\n| 2 | Is it about a whole path that must not be modified or deleted (creating it once stays allowed)? | `declare` (mechanism `self-absolution-ban`) |\n| 3 | Is it about the shell command line itself, regardless of files? | `declare` (mechanism `forbidden-command`, reading the `command` source) |\n| 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) |\n| 5 | None of the above | `draft: true` (step 4b) |\n\nAn `added-only` declaration forgives existing occurrences \u2014 only what the edit adds breaks\nthe promise. That is usually what you want: a discipline adopted today should not indict\nyesterday's code.\n\nOne path-shaped promise takes no `disciplines:` entry at all: a path nobody may touch\nbelongs in the top-level `protectedPaths:` list \u2014 its own config block, never an entry key.\n\n### 3. Check the observation boundary\n\nTwo kinds of promise cannot be judged here, whatever their shape:\n\n- **Destruction outside the repository** \u2014 judgment observes the project root only. Register\n  nothing; use the agent's own permission deny policy for commands like `rm -rf ~`.\n- **Writes by child processes** \u2014 a test runner or script writing files is invisible to the\n  session surface, which judges declared tool calls only. Say so to the user; the commit\n  surface will still see the result as a staged diff.\n\n### 4a. Expressible now \u2014 register a judged entry\n\nAdd the entry to the `disciplines:` array in `polydeukes.config.yaml`. Advise is the default\nlanding \u2014 a break is recorded as `advised` and the call goes on \u2014 and the `enforce: advise`\nline below only spells that default out. NEVER write `enforce: block` from this skill:\npromotion to block is the user's own choice, made after the advise measurements have been\nread.\n\nThe examples below are whole documents, so `languages:` \u2014 the schema's one required block \u2014\nappears alongside the entry; in a config that already has one, copy the entry only.\n\n```yaml\nlanguages:\n  placeholder:\n    productionGlob: 'src/**'\n    testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n  - id: 'no-focused-tests'\n    why: 'a committed .only silently shrinks the suite to one test'\n    declare:\n      mechanism: 'added-only'\n      scope: { source: 'target.path', include: ['^src/'] }\n      supply: { pre: 'empty', post: 'empty' }\n      extract:\n        before:\n          - { op: 'source', of: 'pre' }\n          - { op: 'lines' }\n          - { op: 'keyByPattern', re: '(\\.only\\()' }\n        after:\n          - { op: 'source', of: 'post' }\n          - { op: 'lines' }\n          - { op: 'keyByPattern', re: '(\\.only\\()' }\n        added:\n          - { op: 'onlyIn', of: 'after', notIn: 'before' }\n      relate:\n        - id: 'nothing-added'\n          relation: { op: 'empty', of: 'added' }\n          message: 'adds {key}: {value}'\n    enforce: advise\n```\n\nA command-line ban reads the fixed source `command` and scopes on it \u2014 the scope is part of\nthe mechanism's shape, so a `forbidden-command` entry without it is refused at load time:\n\n```yaml\nlanguages:\n  placeholder:\n    productionGlob: 'src/**'\n    testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n  - id: 'no-force-push'\n    why: 'a force push rewrites history nobody reviewed'\n    declare:\n      mechanism: 'forbidden-command'\n      scope: { source: 'command' }\n      extract:\n        hits:\n          - { op: 'source', of: 'command' }\n          - { op: 'lines' }\n          - { op: 'matches', re: 'git push\\\\b.*--force(?![\\\\w-])' }\n      relate:\n        - { id: 'no-force', relation: { op: 'empty', of: 'hits' }, message: '{value}' }\n    enforce: advise\n```\n\n**Write the regex yourself \u2014 the user states the promise, you author the pattern.** The\npattern is the part users find hardest, so never hand the prose back and ask for one. Three\nauthoring traps, each measured on a live config:\n\n- **A pattern answers a syntactic question only.** \"Is this string a forbidden word\" is\n  syntax; \"is this a new dependency version\" is meaning, and a regex leaks both ways on a\n  semantic question. When the question is semantic, narrow the declaration's own `scope`\n  block to the files where any match IS a break, or accept \"editing this file at all\" as\n  the trigger.\n- **`^` means what the preceding step left.** After a `lines` step a declaration's\n  pattern sees one line at a time, so `^` anchors to that line; over an unsplit source it\n  anchors to the whole text and matches the first line only. A ban over the command line\n  puts `lines` before its `matches` for exactly that reason.\n- **Author both directions.** Before registering, write down one string the pattern must\n  match and one nearby string it must not (`only(` vs `only_helper(`, a flag vs its\n  substring). A pattern checked in only the breaking direction over-fires in review-proof\n  ways.\n\n### 4b. Not expressible yet \u2014 register a draft\n\nA draft is prose with a handle: `id`, `why`, and the literal marker `draft: true` \u2014 no other\nkeys. It produces no judgment and no telemetry; `pdks explain` lists it as unpromoted.\nRecord the SHAPE of the promise inside `why`, so the promotion destination is already\nwritten down when a later engine can express it. Name the shape in these terms:\n\n| Shape | The promise reads like |\n| --- | --- |\n| pairing | every element of set A has a counterpart in set B (translation keys, i18n) |\n| companion | if X appears in a unit, Y must appear with it |\n| ordered | a sequence must keep its order (migration journals, version ladders) |\n| fingerprint | a derived artifact must match the hash/stamp of its source |\n| producer-owned | only a designated generator may write this artifact |\n| self-absolution | the party being judged must not write its own verdict field |\n| actor-scope | the same action is fine for one actor and a break for another |\n| phase-order | several precedents, in a fixed order |\n| turn-locality | the evidence must be in the same turn or time window |\n| stated-ground | the reason must be written down before the action |\n| controlled-vocabulary | only an enumerated set of words/values is allowed |\n| naming-convention | names must match a pattern per kind |\n| irreversible-marker | once present, a marker may never be removed |\n| delegation-scope | a delegated task may touch only its granted scope |\n| scope-valve | a defined exception valve, judged rather than ad hoc |\n| claim-verification | the claim must be re-run/measured, not trusted |\n\n```yaml\nlanguages:\n  placeholder:\n    productionGlob: 'src/**'\n    testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n  - id: 'locale-files-move-together'\n    why: 'pairing \u2014 en.json and ko.json must change in the same commit; one side alone is a break'\n    draft: true\n```\n\n### 5. Prove it fires, then close\n\nRun `pdks explain` and confirm the new entry is listed (a judged entry with its mechanism\nand surfaces; a draft as unpromoted).\n\nFor a judged entry, registration is not the finish \u2014 a pattern that never fires protects\nnothing while looking installed. Fire it once for real, with the proof run the declaration's\nown mechanism can actually reach:\n\n| Mechanism | Break it once | The entry's id shows up in |\n| --- | --- | --- |\n| a file-reading one (`added-only`, `naming`, \u2026) | one scratch edit matching the must-match direction | `pdks covenant check --worktree` output \u2014 the exit stays 0 at advise, the id is the proof |\n| `forbidden-command` | run one harmless command matching the pattern | the telemetry log tail \u2014 at advise the call proceeds and its row records the id |\n| `precedent` | one in-scope edit made without the required precedent | the telemetry log tail \u2014 a declaration reading the session judges on the session surface only (the commit surface has none, so its `supply` policy records it `skipped`) |\n\nThen undo the scratch break, repeat the same run, and confirm silence on the\nmust-NOT-match direction. Close by telling the user which rung the entry landed on and\nthat `enforce: block` is theirs to add later if the advise record earns it.\n\n## Reading the advise record\n\nAn `advised` row means a promise was broken and the call went through anyway. Rows land in\nthe telemetry log at the path configured by `telemetry.logPath` (default\n`.polydeukes/roi.log`). The hook's stderr note is not shown to you, so consult the log at\ntask boundaries: before committing, or after a batch of edits, read the tail and act on any\n`advised` row \u2014 fix the break, or tell the user why it should stand. An advisory nobody\nreads measures nothing.\n";
 /** `initClaudeCode` input — the target tree and the preflight seam. */
 export type InitClaudeCodeSpec = {
     /** Project root to install into — every write below is relative to it. */