polydeukes 0.3.0 → 0.5.0

package/dist/docs-query.d.ts

@@ -1,23 +1,23 @@
 /**
- * `queryDocs` — the offline documentation query (DOCS-02 §3-b/§3-c/§3-d).
+ * `queryDocs` — the offline documentation query.
  *
  * The bundled English guides, answered from the installed version. An AI partner that
  * searches the web gets whatever release the internet indexed; this returns the document
  * that shipped with the code doing the judging, with no network at all.
  *
- * The domain is the five topics below and nothing else (§3-c). An unknown topic throws
- * instead of resolving to something near it: an answer to a question we never mapped is
+ * The domain is the five topics below and nothing else. An unknown topic throws instead of
+ * resolving to something near it: an answer to a question we never mapped is
  * indistinguishable from a real one by the time it reaches a reader.
  *
- * Every failure throws (§3-b) so the bin can leave stdout at zero bytes and exit 2. Text
- * written halfway is read as the document and quoted as the document — the same direction
- * the judging surface fails in, for the same reason.
+ * Every failure throws so the bin can leave stdout at zero bytes and exit 2. Text written
+ * halfway is read as the document and quoted as the document — the same direction the
+ * judging surface fails in, for the same reason.
  */
-/** The finite query domain (§3-c) — the topic list `pdks docs` prints with no argument. */
+/** The finite query domain — the topic list `pdks docs` prints with no argument. */
 export declare const TOPICS: readonly ['install', 'config', 'discipline', 'covenant', 'witness'];
 /**
  * The body of one section of `markdown`: from the line equal to `heading` up to just before
- * the next heading of the same or a higher level, returned verbatim (§3-d).
+ * the next heading of the same or a higher level, returned verbatim.
  *
  * `heading` is matched by exact string equality. A document that renames its heading kills
  * the query here rather than letting a normalizing matcher hand back a neighbouring section
@@ -36,10 +36,10 @@ export type QueryDocsSpec = {
     topic?: string;
 };
 /**
- * Answer one documentation query (§3-b).
+ * Answer one documentation query.
  *
  * With no topic the result is the listing — how an AI discovers what it may ask at all.
- * With one, it is the §3-c section body followed by the bundled reference to read next.
+ * With one, it is the mapped section body followed by the bundled reference to read next.
  */
 export declare function queryDocs(spec: QueryDocsSpec): {
     text: string;

package/dist/docs-query.js

@@ -1,34 +1,34 @@
 /**
- * `queryDocs` — the offline documentation query (DOCS-02 §3-b/§3-c/§3-d).
+ * `queryDocs` — the offline documentation query.
  *
  * The bundled English guides, answered from the installed version. An AI partner that
  * searches the web gets whatever release the internet indexed; this returns the document
  * that shipped with the code doing the judging, with no network at all.
  *
- * The domain is the five topics below and nothing else (§3-c). An unknown topic throws
- * instead of resolving to something near it: an answer to a question we never mapped is
+ * The domain is the five topics below and nothing else. An unknown topic throws instead of
+ * resolving to something near it: an answer to a question we never mapped is
  * indistinguishable from a real one by the time it reaches a reader.
  *
- * Every failure throws (§3-b) so the bin can leave stdout at zero bytes and exit 2. Text
- * written halfway is read as the document and quoted as the document — the same direction
- * the judging surface fails in, for the same reason.
+ * Every failure throws so the bin can leave stdout at zero bytes and exit 2. Text written
+ * halfway is read as the document and quoted as the document — the same direction the
+ * judging surface fails in, for the same reason.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-/** The finite query domain (§3-c) — the topic list `pdks docs` prints with no argument. */
+/** The finite query domain — the topic list `pdks docs` prints with no argument. */
 export const TOPICS = ['install', 'config', 'discipline', 'covenant', 'witness'];
-/** The §3-c mapping, as data: which document answers a topic, and what to read next. */
+/** The mapping, as data: which document answers a topic, and what to read next. */
 const TOPIC_MAP = {
     install: {
         sections: [{ file: 'installation.md' }],
         seeAlso: 'reference/polydeukes.md',
     },
     config: {
-        sections: [{ file: 'configuration.md', heading: '## Reference' }],
+        sections: [{ file: 'reference/configuration.md' }],
         seeAlso: 'reference/core.md',
     },
     discipline: {
-        sections: [{ file: 'configuration.md', heading: '### `disciplines` (optional)' }],
+        sections: [{ file: 'reference/configuration.md', heading: '## `disciplines`' }],
         seeAlso: 'reference/covenant.md',
     },
     covenant: {
@@ -37,7 +37,7 @@ const TOPIC_MAP = {
     },
     witness: {
         sections: [
-            { file: 'configuration.md', heading: '### `witness` (optional)' },
+            { file: 'reference/configuration.md', heading: '## `witness`' },
             { file: 'troubleshooting.md', heading: '## Opening a blocked call — the witness' },
         ],
         seeAlso: 'reference/covenant.md',
@@ -55,7 +55,7 @@ function headingLevel(line) {
 }
 /**
  * The body of one section of `markdown`: from the line equal to `heading` up to just before
- * the next heading of the same or a higher level, returned verbatim (§3-d).
+ * the next heading of the same or a higher level, returned verbatim.
  *
  * `heading` is matched by exact string equality. A document that renames its heading kills
  * the query here rather than letting a normalizing matcher hand back a neighbouring section
@@ -101,7 +101,7 @@ export function extractSection(markdown, heading) {
     if (start === -1) {
         throw new Error(`heading not found: ${heading}`);
     }
-    // A section that closes the document ends at end of file; the §3-c map points at one.
+    // A section that closes the document ends at end of file; the topic map points at one.
     return lines.slice(start).join('\n');
 }
 function readSection(docsRoot, section) {
@@ -115,10 +115,10 @@ function readSection(docsRoot, section) {
     return section.heading === undefined ? markdown : extractSection(markdown, section.heading);
 }
 /**
- * Answer one documentation query (§3-b).
+ * Answer one documentation query.
  *
  * With no topic the result is the listing — how an AI discovers what it may ask at all.
- * With one, it is the §3-c section body followed by the bundled reference to read next.
+ * With one, it is the mapped section body followed by the bundled reference to read next.
  */
 export function queryDocs(spec) {
     if (spec.topic === undefined) {
@@ -129,10 +129,10 @@ export function queryDocs(spec) {
     }
     const entry = TOPIC_MAP[spec.topic];
     const body = entry.sections.map((section) => readSection(spec.docsRoot, section)).join('\n');
-    // Resolved against the bundle, not printed as the bare relative name. The reference layer
-    // ships but no topic reads it, so this line is the only way to reach those five documents —
-    // and a reader given `reference/core.md` has to guess where the bundle lives before it can
-    // open anything. A path a file-read tool can take is the difference between a pointer and
-    // a dead end, and a dead end sends the reader back to the web search this command replaces.
+    // Resolved against the bundle, not printed as the bare relative name. A reader given
+    // `reference/core.md` has to guess where the bundle lives before it can open anything, and
+    // this line is the only way most of the reference layer is reached at all. A path a file-read
+    // tool can take is the difference between a pointer and a dead end, and a dead end sends the
+    // reader back to the web search this command replaces.
     return { text: `${body}\nSee also: ${join(spec.docsRoot, entry.seeAlso)}\n` };
 }

package/dist/explain.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `pdks explain` — render both surfaces' assembled registration sets without judging.
+ *
+ * This module calls the composition roots' OWN assembly functions and renders what they
+ * return, so it reports the table the judgment uses rather than a second opinion about it.
+ *
+ * It never dispatches, never writes telemetry or a baseline, and never opens a transcript
+ * file — the session assembly receives core's `noopTranscript`, which answers queries with
+ * nothing and reads no disk. Every failure throws: an answer that cannot be given is never
+ * given halfway.
+ */
+/** `explain` input — the repository whose config is read. */
+export type ExplainSpec = {
+    repoRoot: string;
+};
+/**
+ * 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.
+ */
+export declare function explain(spec: ExplainSpec): Promise<{
+    text: string;
+}>;

package/dist/explain.js

@@ -0,0 +1,152 @@
+/**
+ * `pdks explain` — render both surfaces' assembled registration sets without judging.
+ *
+ * This module calls the composition roots' OWN assembly functions and renders what they
+ * return, so it reports the table the judgment uses rather than a second opinion about it.
+ *
+ * It never dispatches, never writes telemetry or a baseline, and never opens a transcript
+ * file — the session assembly receives core's `noopTranscript`, which answers queries with
+ * nothing and reads no disk. Every failure throws: an answer that cannot be given is never
+ * given halfway.
+ */
+import { join } from 'node:path';
+import { resolveGitAdapterSettings } from '@polydeukes/adapter-git';
+import { noopTranscript } 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.
+ */
+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}`;
+}
+/** One rendered line: the kind column, the label column, then the description. */
+function row(kind, label, width, description) {
+    return `  ${kind.padEnd(8)} ${label.padEnd(width)} ${description}`;
+}
+/** The description of a meta-covenant registration — how much surface it covers. */
+function metaDescription(registration, surface) {
+    if (registration.label === 'transcript-mod') {
+        return 'content predicate · conditional: transcript_path';
+    }
+    return `paths ${registration.protectedPaths.length} (${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;
+    let skip = 0;
+    let meta = 0;
+    for (const registration of spec.registrations) {
+        if (META_LABELS.has(registration.label)) {
+            meta += 1;
+            const scope = registration.label === 'self-mod' ? spec.selfModScope : 'common';
+            lines.push(row('meta', registration.label, width, metaDescription(registration, scope)));
+            continue;
+        }
+        if (registration.skip !== undefined) {
+            skip += 1;
+            lines.push(row('skip', registration.label, width, registration.skip.reason));
+            continue;
+        }
+        judged += 1;
+        const entry = spec.disciplines.find((candidate) => candidate.id === registration.label);
+        // 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'));
+    }
+    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}`;
+    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.
+ */
+export async function explain(spec) {
+    const { config, configPath } = loadConfig(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.
+    const covenant = await loadCovenantModule(resolveCovenantDist());
+    const disciplines = config.disciplines ?? [];
+    const drafts = config.drafts ?? [];
+    const session = assembleSessionRegistrations({
+        config,
+        rootDir: spec.repoRoot,
+        covenant,
+        transcriptPath: join(spec.repoRoot, 'transcript.jsonl'),
+        transcript: noopTranscript,
+    });
+    const commit = assembleCommitRegistrations({
+        config,
+        rootDir: spec.repoRoot,
+        covenant,
+    });
+    const gitSettings = resolveGitAdapterSettings(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',
+        }),
+        '',
+        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',
+        }),
+        '',
+    ].join('\n');
+    return { text };
+}

package/dist/index.d.ts

@@ -3,25 +3,21 @@
  * coding partner.
  *
  * Pre-alpha. This package reserves the unscoped `polydeukes` name and is the umbrella /
- * `pdks` CLI entry point. It owns the config discovery loader (CONFIG-03) and both
- * surfaces' composition roots — `runCovenantCheck` for the commit surface and
- * `runClaudeCodeHook` for the session one — because assembly needs an adapter and the
- * covenant package at once, which no sibling is allowed to depend on. The covenant,
- * ledger, memory, and verify modules live in their own `@polydeukes/*` packages.
+ * `pdks` CLI entry point. It owns the config discovery loader and both surfaces'
+ * composition roots — `runCovenantCheck` for the commit surface and `runClaudeCodeHook`
+ * for the session one — because assembly needs an adapter and the covenant package at
+ * once, which no sibling is allowed to depend on. The covenant, ledger, memory, and verify
+ * modules live in their own `@polydeukes/*` packages.
  *
  * This file is a barrel and nothing more. ESM re-exports are eager, so anything defined
- * here would be instantiated by every consumer of any other export — which is exactly how
- * the session adapter ended up on the commit surface's load path (PR #46 review). Keep
- * definitions in their own modules and let importers reach them directly.
+ * here would be instantiated by every consumer of any other export. Keep definitions in
+ * their own modules and let importers reach them directly. A session call enters through
+ * the published `./claude-code` subpath instead, which keeps the commit surface and its git
+ * adapter off that load path.
  *
- * The mirror of that coupling is closed as of DIST-02. `exports` publishes `./claude-code`
- * alongside `"."`, and both delegators — this repository's and the one `pdks init
- * claude-code` generates — enter through it, so a session call no longer instantiates
- * `covenant-check.js` or `@polydeukes/adapter-git`. The window DIST-01 §3-d declared (a
- * workspace missing only that dist failing closed with no telemetry row) is gone with it.
  * See https://github.com/huskyhoochu/polydeukes
  */
 export type { ResolvedConfig } from '@polydeukes/core';
 export { type ClaudeCodeHookSpec, runClaudeCodeHook } from './claude-code-hook.js';
-export { type CovenantCheckSpec, runCovenantCheck } from './covenant-check.js';
+export { type CheckDomain, type CovenantCheckSpec, runCovenantCheck } from './covenant-check.js';
 export { type LoadedConfig, loadConfig } from './load-config.js';

package/dist/index.js

@@ -3,22 +3,18 @@
  * coding partner.
  *
  * Pre-alpha. This package reserves the unscoped `polydeukes` name and is the umbrella /
- * `pdks` CLI entry point. It owns the config discovery loader (CONFIG-03) and both
- * surfaces' composition roots — `runCovenantCheck` for the commit surface and
- * `runClaudeCodeHook` for the session one — because assembly needs an adapter and the
- * covenant package at once, which no sibling is allowed to depend on. The covenant,
- * ledger, memory, and verify modules live in their own `@polydeukes/*` packages.
+ * `pdks` CLI entry point. It owns the config discovery loader and both surfaces'
+ * composition roots — `runCovenantCheck` for the commit surface and `runClaudeCodeHook`
+ * for the session one — because assembly needs an adapter and the covenant package at
+ * once, which no sibling is allowed to depend on. The covenant, ledger, memory, and verify
+ * modules live in their own `@polydeukes/*` packages.
  *
  * This file is a barrel and nothing more. ESM re-exports are eager, so anything defined
- * here would be instantiated by every consumer of any other export — which is exactly how
- * the session adapter ended up on the commit surface's load path (PR #46 review). Keep
- * definitions in their own modules and let importers reach them directly.
+ * here would be instantiated by every consumer of any other export. Keep definitions in
+ * their own modules and let importers reach them directly. A session call enters through
+ * the published `./claude-code` subpath instead, which keeps the commit surface and its git
+ * adapter off that load path.
  *
- * The mirror of that coupling is closed as of DIST-02. `exports` publishes `./claude-code`
- * alongside `"."`, and both delegators — this repository's and the one `pdks init
- * claude-code` generates — enter through it, so a session call no longer instantiates
- * `covenant-check.js` or `@polydeukes/adapter-git`. The window DIST-01 §3-d declared (a
- * workspace missing only that dist failing closed with no telemetry row) is gone with it.
  * See https://github.com/huskyhoochu/polydeukes
  */
 export { runClaudeCodeHook } from './claude-code-hook.js';

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

@@ -1,27 +1,38 @@
 /**
- * `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.
  */
 import { type ScaffoldReport } from './scaffold-project.js';
-/** `initClaudeCode` input (DIST-02 §3-g) — the target tree and the preflight seam. */
+/**
+ * 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 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";
+/** `initClaudeCode` input — the target tree and the preflight seam. */
 export type InitClaudeCodeSpec = {
     /** Project root to install into — every write below is relative to it. */
     projectRoot: string;
     /**
-     * §3-g preflight seam: throws when the package cannot be resolved from the given root.
+     * 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.
@@ -29,11 +40,11 @@ export type InitClaudeCodeSpec = {
     resolvePolydeukes?: (projectRoot: string) => void;
 };
 /**
- * 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 declare function initClaudeCode(spec: InitClaudeCodeSpec): ScaffoldReport;