polydeukes 0.5.0 → 0.6.1

package/dist/docs-query.js

@@ -1,138 +1,44 @@
-/**
- * `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. 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 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 — the topic list `pdks docs` prints with no argument. */
-export const TOPICS = ['install', 'config', 'discipline', 'covenant', 'witness'];
-/** 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: 'reference/configuration.md' }],
-        seeAlso: 'reference/core.md',
-    },
-    discipline: {
-        sections: [{ file: 'reference/configuration.md', heading: '## `disciplines`' }],
-        seeAlso: 'reference/covenant.md',
-    },
-    covenant: {
-        sections: [{ file: 'configuration.md', heading: '## What enforcement looks like' }],
-        seeAlso: 'reference/polydeukes.md',
-    },
-    witness: {
-        sections: [
-            { file: 'reference/configuration.md', heading: '## `witness`' },
-            { file: 'troubleshooting.md', heading: '## Opening a blocked call — the witness' },
-        ],
-        seeAlso: 'reference/covenant.md',
-    },
-};
-/** A fenced block opens and closes on a line whose trimmed form starts with the marker. */
-const FENCE = /^(?:`{3,}|~{3,})/;
-/** An ATX heading, and its level in the capture. */
-const HEADING = /^(#{1,6}) /;
-function isTopic(value) {
-    return TOPICS.includes(value);
-}
-function headingLevel(line) {
-    return HEADING.exec(line)?.[1].length ?? 0;
+import { runDocs } from './docs-library.js';
+export { DOCS_TOPICS as TOPICS } from './docs-types.js';
+/** Answer a legacy topic using the same catalog as search and show. */
+export function queryDocs(spec) {
+    return runDocs({
+        docsRoot: spec.docsRoot,
+        args: spec.topic === undefined ? [] : [spec.topic],
+        version: '',
+    });
 }
 /**
- * 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.
- *
- * `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
- * with full confidence.
- *
- * Both scans — for the start and for the boundary — run outside code fences. `#` lines
- * inside a fence are content: the guides really carry them, and a fence-blind scanner cuts
- * the answer at one of those lines while still looking like a success.
+ * Extract a section by its exact heading, retaining the original internal helper's contract.
+ * Topic retrieval uses stable IDs instead; this helper remains for existing internal callers.
  */
 export function extractSection(markdown, heading) {
     const lines = markdown.split('\n');
-    const level = headingLevel(heading);
-    let openMarker;
+    const level = /^(#{1,6}) /.exec(heading)?.[1].length ?? 0;
+    let fence;
     let start = -1;
-    for (let i = 0; i < lines.length; i += 1) {
-        const line = lines[i];
-        const trimmed = line.trim();
-        if (FENCE.test(trimmed)) {
-            // Opener and closer are both compared trimmed. An indented fence closed by a strict
-            // bare-marker test would stay open to end of file, and every heading after it would
-            // silently stop being a heading — the guides carry a two-space-indented one.
-            if (openMarker === undefined) {
-                openMarker = trimmed[0];
-            }
-            else if (trimmed[0] === openMarker) {
-                openMarker = undefined;
-            }
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const marker = /^(`{3,}|~{3,})/.exec(line.trim())?.[1];
+        if (marker) {
+            if (fence === undefined)
+                fence = { marker: marker[0], length: marker.length };
+            else if (fence.marker === marker[0] && marker.length >= fence.length)
+                fence = undefined;
             continue;
         }
-        if (openMarker !== undefined) {
+        if (fence !== undefined)
             continue;
-        }
         if (start === -1) {
-            if (line === heading) {
-                start = i;
-            }
+            if (line === heading)
+                start = index;
             continue;
         }
-        if (headingLevel(line) > 0 && headingLevel(line) <= level) {
-            return lines.slice(start, i).join('\n');
-        }
+        const nextLevel = /^(#{1,6}) /.exec(line)?.[1].length ?? 0;
+        if (nextLevel > 0 && nextLevel <= level)
+            return lines.slice(start, index).join('\n');
     }
-    if (start === -1) {
+    if (start === -1)
         throw new Error(`heading not found: ${heading}`);
-    }
-    // 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) {
-    const path = join(docsRoot, section.file);
-    if (!existsSync(path)) {
-        // Named, never swallowed into empty text: a silently incomplete bundle would otherwise
-        // reach a reader as the document itself.
-        throw new Error(`bundled document missing: ${section.file}`);
-    }
-    const markdown = readFileSync(path, 'utf-8');
-    return section.heading === undefined ? markdown : extractSection(markdown, section.heading);
-}
-/**
- * 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 mapped section body followed by the bundled reference to read next.
- */
-export function queryDocs(spec) {
-    if (spec.topic === undefined) {
-        return { text: `Polydeukes docs:\n${TOPICS.map((t) => `  pdks docs ${t}`).join('\n')}\n` };
-    }
-    if (!isTopic(spec.topic)) {
-        throw new Error(`unknown docs topic '${spec.topic}' — known topics: ${TOPICS.join(', ')}`);
-    }
-    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. 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/docs-types.d.ts

@@ -0,0 +1,105 @@
+/** Languages included in every bundled document. */
+export type DocsLanguage = 'en' | 'ko';
+/** Backward-compatible topic names; their targets belong to the catalog. */
+export declare const DOCS_TOPICS: readonly ['install', 'config', 'discipline', 'covenant', 'witness'];
+/** Source-root-relative Markdown path and localized metadata used for retrieval and ranking. */
+export type DocsTranslation = {
+    path: string;
+    title: string;
+    summary: string;
+    terms?: string[];
+};
+/** Catalog entry identifying a document across languages and selecting it for bundling. */
+export type DocsDocument = {
+    id: string;
+    category: string;
+    order: number;
+    bundled: boolean;
+    en: DocsTranslation;
+    ko?: DocsTranslation;
+};
+/** Source inventory shared by the documentation build and offline query commands. */
+export type DocsCatalog = {
+    schemaVersion: number;
+    documents: DocsDocument[];
+    topics: Record<string, DocsTopic>;
+    redirects?: DocsRedirect[];
+};
+/** Ordered content references for a legacy topic, plus a document ID for further reading. */
+export type DocsTopic = {
+    references: DocsReference[];
+    seeAlso: string;
+};
+/** Stable document ID, optionally narrowed to a section; omission selects the whole document. */
+export type DocsReference = {
+    documentId: string;
+    sectionId?: string;
+};
+/** Move-notice path and canonical destination, both relative to the documentation root. */
+export type DocsRedirect = {
+    path: string;
+    target: string;
+};
+/** Anchored Markdown slice with zero-based line bounds: inclusive start, exclusive end. */
+export type DocsSection = {
+    id: string;
+    title: string;
+    level: number;
+    startLine: number;
+    endLine: number;
+    text: string;
+};
+/** Bilingual metadata returned for a document included in a completed build. */
+export type DocsBundleDocument = {
+    id: string;
+    bundled: boolean;
+    category: string;
+    order: number;
+    translations: Record<DocsLanguage, DocsTranslation>;
+};
+/** Indexed section location; the hash covers its entire translated document, not the section. */
+export type DocsBundleSection = {
+    documentId: string;
+    language: DocsLanguage;
+    sectionId: string;
+    title: string;
+    level: number;
+    path: string;
+    hash: string;
+};
+/** Persisted bundle metadata and document hashes, reconstructed on load to detect inconsistency. */
+export type DocsIndex = {
+    schemaVersion: 1;
+    documents: Array<{
+        id: string;
+        bundled: boolean;
+        category: string;
+        order: number;
+        translations: Record<DocsLanguage, DocsTranslation>;
+        hashes: Record<DocsLanguage, string>;
+    }>;
+    sections: DocsBundleSection[];
+};
+/** In-memory catalog and index with loaded Markdown keyed by stable document ID. */
+export type LoadedDocsBundle = {
+    catalog: DocsCatalog;
+    index: DocsIndex;
+    documents: Map<string, LoadedDocsDocument>;
+    topics: Record<string, DocsTopic>;
+};
+/** Loaded bilingual Markdown with parsed sections and empty search-term lists where omitted. */
+export type LoadedDocsDocument = {
+    id: string;
+    bundled: boolean;
+    category: string;
+    order: number;
+    translations: Record<DocsLanguage, {
+        path: string;
+        title: string;
+        summary: string;
+        terms: string[];
+        markdown: string;
+        hash: string;
+        sections: DocsSection[];
+    }>;
+};

package/dist/docs-types.js

@@ -0,0 +1,2 @@
+/** Backward-compatible topic names; their targets belong to the catalog. */
+export const DOCS_TOPICS = ['install', 'config', 'discipline', 'covenant', 'witness'];

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 declaration grammar and observed evidence can express it, a draft entry otherwise. Use when the user describes a recurring problem they want promised away (\"I keep...\", \"stop X from happening\", \"we should never...\", \"how do I enforce Y\").\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\nChoose from the current catalogue, then check whether the intended surface can supply the\nrequired evidence. A mechanism name constrains the declaration; it does not implement the\npromise by itself. The extracted axes and body relations must be subsets of the admitted\nsets below. Scope filtering is separate from the extracted axes.\n\n| Mechanism | Admitted axes | Body relations | Evidence or structural condition |\n| --- | --- | --- | --- |\n| `pairing` | `world` | `equal` | Compare supplied files or channels; extract keys when values may differ. |\n| `companion` | `change`, `world` | `implies` | Compare presence by key; a multi-file promise needs the observed change set. |\n| `monotonic-order` | `change`, `world` | `ordered` | Extract a sequence with an explicit comparison field; order is not presence. |\n| `fingerprint-sync` | `world` | `equal` | Compare supplied stamps; no generator or compiler runs during judgment. |\n| `producer-owned` | `actor` | `empty`, `nonEmpty` | Requires host-provided actor evidence, not an artifact's self-reported producer. |\n| `self-absolution-ban` | `change` | `unchanged`, `empty` | Extract protected fields or path changes; choose creation/deletion supply explicitly. |\n| `actor-scope` | `actor` | `empty`, `nonEmpty` | Requires a proven actor; a missing actor is not proof of the main session. |\n| `precedent` | `history`, `world` | `nonEmpty` | Requires an observed earlier call in a transcript or supplied channel. |\n| `phase-order` | `history` | `ordered` | Compare observed call ordinals; missing phases need a separate presence promise. |\n| `turn-locality` | `history` | `nonEmpty` | Requires observed turns and time or ordinal boundaries. |\n| `stated-ground` | `history` | `nonEmpty` | Can require recorded text, not establish whether its reasoning is sound. |\n| `controlled-vocabulary` | `change`, `world` | `subset` | Extract values and an explicit allowed set. |\n| `naming` | `change` | `empty`, `nonEmpty` | Scope must read `target.path`; match the intended name pattern. |\n| `added-only` | `change` | `empty` | Compare pre/post extractions and judge only newly added matches. |\n| `one-way-marker` | `change` | `subset` | Existing markers must remain in the extracted post-change set. |\n| `delegated-scope` | \u2014 | \u2014 | Reserved for a definition-time evaluator; not accepted in current declarations. |\n| `scoped-valve` | `change`, `actor`, `world`, `history` | `empty`, `nonEmpty`, `equal`, `subset`, `implies`, `ordered`, `unchanged` | Requires a `witness` block expressing the exception condition. |\n| `forbidden-command` | `change` | `empty` | Scope must read `command`; a text pattern is not shell semantic analysis. |\n\nThese four requests illustrate the classification boundary:\n\n| Request | Classification | Proof |\n| --- | --- | --- |\n| The English and Korean locale files must carry identical keys. | `pairing`, with two supplied files. | An unmatched key breaks; translated values may differ. |\n| Every status must belong to an allowed list. | `controlled-vocabulary`, with a supplied allowed set. | An unknown status breaks; an allowed status passes. |\n| A successful package lookup must precede a manifest edit. | `precedent`, with observed session history. | Failed or absent lookups break; an unavailable transcript is a supply case. |\n| A fresh benchmark must execute during judgment to prove a performance claim. | `draft`: the engine does not execute benchmarks. | Comparing an existing report would be a different promise. |\n\nRun `pdks docs show write-disciplines` for the key-pairing walkthrough and\n`pdks docs show configuration --section disciplines` for the declaration grammar.\nUse `--lang ko` for Korean; these commands read the installed version offline.\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\nDo not confuse an expressible relation with available evidence:\n\n- **Files outside the repository** \u2014 file-change protection observes the project root.\n  Use the host's permission policy for comprehensive protection outside it. A command-text\n  pattern may recognize a particular string, but does not observe all resulting writes.\n- **Writes by child processes** \u2014 arbitrary writes inside a test runner or script are not\n  individually observed by the session surface. A commit comparison can observe the resulting\n  files when they enter its selected diff; it does not recover the originating tool history.\n- **Missing history or actor channels** \u2014 choose the declaration's supply policy explicitly.\n  Commit observations have no session transcript; `supply: pass` records a skip, not success.\n- **Fresh execution or semantic proof** \u2014 the engine compares supplied evidence. It does not\n  run a new benchmark or prove that a written explanation is true. Preserve that unmet promise\n  as a draft rather than silently replacing it with a weaker text check.\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\nThe following examples implement the first three classification cases. Both locale files and\nthe allowed-status file must exist and contain valid JSON. File bindings use the proposed\ncontents for a file changed by the current observation, not a second stale disk read.\n\n```yaml\nlanguages:\n  json:\n    productionGlob: 'locales/**/*.json'\n    testCmd: 'pnpm test'\ndisciplines:\n  - id: 'locale-key-parity'\n    why: 'the ko and en locales must carry the same keys'\n    declare:\n      mechanism: 'pairing'\n      scope: { source: 'target.path', include: ['^locales/(ko|en)[.]json$'] }\n      sources:\n        ko: { file: 'locales/ko.json' }\n        en: { file: 'locales/en.json' }\n      supply: { ko: 'error', en: 'error' }\n      extract:\n        koKeys: [{ op: 'source', of: 'ko' }, { op: 'json' }, { op: 'flattenKeys' }]\n        enKeys: [{ op: 'source', of: 'en' }, { op: 'json' }, { op: 'flattenKeys' }]\n      relate:\n        - id: 'parity'\n          relation: { op: 'equal', of: ['koKeys', 'enKeys'] }\n          messageBySide:\n            left: '{key} is in ko only'\n            right: '{key} is in en only'\n    enforce: advise\n```\n\n```yaml\nlanguages:\n  json:\n    productionGlob: '*.json'\n    testCmd: 'pnpm test'\ndisciplines:\n  - id: 'status-vocabulary'\n    why: 'statuses.json may contain only values listed in allowed-statuses.json'\n    declare:\n      mechanism: 'controlled-vocabulary'\n      scope: { source: 'target.path', include: ['^statuses[.]json$'] }\n      sources: { allowed: { file: 'allowed-statuses.json' } }\n      supply: { post: 'error', allowed: 'error' }\n      extract:\n        selected: [{ op: 'source', of: 'post' }, { op: 'json' }, { op: 'items' }]\n        permitted: [{ op: 'source', of: 'allowed' }, { op: 'json' }, { op: 'items' }]\n      relate:\n        - id: 'allowed-status'\n          relation: { op: 'subset', of: 'selected', in: 'permitted' }\n          message: 'unknown status: {value}'\n    enforce: advise\n```\n\nHere both status files are JSON arrays of strings. This declaration scopes on statuses.json;\nediting only the allowed list does not trigger it. Broaden the observation deliberately if\nchanges to that list must recheck all dependent files.\n\n```yaml\nlanguages:\n  typescript:\n    productionGlob: 'src/**'\n    testCmd: 'pnpm test'\ndisciplines:\n  - id: 'manifest-needs-npm-view'\n    why: 'a successful package lookup must precede a manifest edit'\n    declare:\n      mechanism: 'precedent'\n      scope: { source: 'target.path', include: ['^(packages/[^/]+/)?package[.]json$'] }\n      sources: { session: { transcript: true } }\n      supply: { session: 'pass' }\n      extract:\n        npmView:\n          - { op: 'source', of: 'session' }\n          - { op: 'toolUses', names: ['Bash'] }\n          - { op: 'filter', when: [{ field: 'succeeded', eq: true }] }\n          - { op: 'select', path: 'args.command' }\n          - { op: 'matches', re: '^npm view ' }\n      relate:\n        - id: 'npm-view'\n          relation: { op: 'nonEmpty', of: 'npmView' }\n          message: 'no successful npm view precedes this edit'\n    enforce: advise\n```\n\nThe precedent example proves only that an observed successful Bash call starts with npm view;\nit does not prove that the lookup concerns the dependency being edited. The commit surface has\nno transcript and therefore skips this example by its explicit supply policy.\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 intended promise and the exact missing capability inside `why`. Do not classify\npairing, vocabulary, or history promises as drafts merely because they are absent from a short\nexample list. Check the catalogue, extraction steps, and observation channel first. A reserved\n`delegated-scope` declaration cannot be registered as a judged entry.\n\n```yaml\nlanguages:\n  placeholder:\n    productionGlob: 'src/**'\n    testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n  - id: 'benchmark-supports-performance-claim'\n    why: 'a performance claim needs a fresh benchmark run during judgment; the engine cannot execute it'\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 observation, and confirm a passing row for the\nmust-NOT-match case. Silence alone may mean a scope miss, unchanged files, or unavailable evidence;\ncheck `pdks explain` and telemetry for `config-fault`, `no-observation`, or `supply-pass`. 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## Updating this skill without losing local edits\n\nAn upgrade does not overwrite an existing skill; rerunning `pdks init claude-code` reports it\nskipped. Generate a fresh copy in a disposable project using the installed package, compare it\nwith this file, and merge the changes you want. Keep a backup of local additions. Do not delete\nthe existing skill to force regeneration in the working project.\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. */