polydeukes 0.6.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/init-claude-code.d.ts

@@ -28,7 +28,7 @@ import { type ScaffoldReport } from './scaffold-project.ts';
  * 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 | 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";
+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. */

package/dist/init-claude-code.js

@@ -113,7 +113,9 @@ This project is judged by Polydeukes, and the matching documentation ships insid
 installed package. \`pdks docs\` answers offline, from the same version that does the
 judging; a web search answers from whichever release it indexed.
 
-Run \`pdks docs\` for the topic list, \`pdks docs <topic>\` for one section.
+Run \`pdks docs\` for the topic list, \`pdks docs <topic>\` for topic content,
+\`pdks docs search "locale key pairing"\` to find a section, or
+\`pdks docs show write-disciplines\` to retrieve the guide. Add \`--lang ko\` for Korean.
 
 A local install puts the bin in \`node_modules/.bin\`, which a plain shell does not have on
 PATH. If \`pdks\` is not found, run \`./node_modules/.bin/pdks docs <topic>\` — or your package
@@ -134,7 +136,7 @@ ${TOPICS.map((topic) => `| ${DOCS_TOPIC_PURPOSE[topic]} | \`pdks docs ${topic}\`
  */
 export const GENERATED_SKILL = `---
 name: discipline-draft
-description: Turn a described discipline problem into a registered entry in polydeukes.config — a judged entry when the current families can express it, a draft entry otherwise. Use when the user describes a recurring problem they want promised away ("I keep...", "stop X from happening", "we should never...", "how do I enforce Y").
+description: Turn a described discipline problem into a registered entry in polydeukes.config — 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").
 ---
 
 # discipline-draft — from a problem description to a registered discipline
@@ -154,15 +156,44 @@ promises and classify each separately.
 
 ### 2. Classify the shape
 
-Ask these questions in order; the first yes decides.
-
-| # | Question | Entry key |
+Choose from the current catalogue, then check whether the intended surface can supply the
+required evidence. A mechanism name constrains the declaration; it does not implement the
+promise by itself. The extracted axes and body relations must be subsets of the admitted
+sets below. Scope filtering is separate from the extracted axes.
+
+| Mechanism | Admitted axes | Body relations | Evidence or structural condition |
+| --- | --- | --- | --- |
+| \`pairing\` | \`world\` | \`equal\` | Compare supplied files or channels; extract keys when values may differ. |
+| \`companion\` | \`change\`, \`world\` | \`implies\` | Compare presence by key; a multi-file promise needs the observed change set. |
+| \`monotonic-order\` | \`change\`, \`world\` | \`ordered\` | Extract a sequence with an explicit comparison field; order is not presence. |
+| \`fingerprint-sync\` | \`world\` | \`equal\` | Compare supplied stamps; no generator or compiler runs during judgment. |
+| \`producer-owned\` | \`actor\` | \`empty\`, \`nonEmpty\` | Requires host-provided actor evidence, not an artifact's self-reported producer. |
+| \`self-absolution-ban\` | \`change\` | \`unchanged\`, \`empty\` | Extract protected fields or path changes; choose creation/deletion supply explicitly. |
+| \`actor-scope\` | \`actor\` | \`empty\`, \`nonEmpty\` | Requires a proven actor; a missing actor is not proof of the main session. |
+| \`precedent\` | \`history\`, \`world\` | \`nonEmpty\` | Requires an observed earlier call in a transcript or supplied channel. |
+| \`phase-order\` | \`history\` | \`ordered\` | Compare observed call ordinals; missing phases need a separate presence promise. |
+| \`turn-locality\` | \`history\` | \`nonEmpty\` | Requires observed turns and time or ordinal boundaries. |
+| \`stated-ground\` | \`history\` | \`nonEmpty\` | Can require recorded text, not establish whether its reasoning is sound. |
+| \`controlled-vocabulary\` | \`change\`, \`world\` | \`subset\` | Extract values and an explicit allowed set. |
+| \`naming\` | \`change\` | \`empty\`, \`nonEmpty\` | Scope must read \`target.path\`; match the intended name pattern. |
+| \`added-only\` | \`change\` | \`empty\` | Compare pre/post extractions and judge only newly added matches. |
+| \`one-way-marker\` | \`change\` | \`subset\` | Existing markers must remain in the extracted post-change set. |
+| \`delegated-scope\` | — | — | Reserved for a definition-time evaluator; not accepted in current declarations. |
+| \`scoped-valve\` | \`change\`, \`actor\`, \`world\`, \`history\` | \`empty\`, \`nonEmpty\`, \`equal\`, \`subset\`, \`implies\`, \`ordered\`, \`unchanged\` | Requires a \`witness\` block expressing the exception condition. |
+| \`forbidden-command\` | \`change\` | \`empty\` | Scope must read \`command\`; a text pattern is not shell semantic analysis. |
+
+These four requests illustrate the classification boundary:
+
+| Request | Classification | Proof |
 | --- | --- | --- |
-| 1 | Is the promise about content newly ADDED to a file (a pattern that must not appear in new lines)? | \`declare\` (mechanism \`added-only\`) |
-| 2 | Is it about a whole path that must not be modified or deleted (creating it once stays allowed)? | \`declare\` (mechanism \`self-absolution-ban\`) |
-| 3 | Is it about the shell command line itself, regardless of files? | \`declare\` (mechanism \`forbidden-command\`, reading the \`command\` source) |
-| 4 | Does it require that something else was already done earlier in the session (a tool call that must precede this one)? | \`declare\` (mechanism \`precedent\`, reading a \`transcript\` source) |
-| 5 | None of the above | \`draft: true\` (step 4b) |
+| The English and Korean locale files must carry identical keys. | \`pairing\`, with two supplied files. | An unmatched key breaks; translated values may differ. |
+| Every status must belong to an allowed list. | \`controlled-vocabulary\`, with a supplied allowed set. | An unknown status breaks; an allowed status passes. |
+| 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. |
+| 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. |
+
+Run \`pdks docs show write-disciplines\` for the key-pairing walkthrough and
+\`pdks docs show configuration --section disciplines\` for the declaration grammar.
+Use \`--lang ko\` for Korean; these commands read the installed version offline.
 
 An \`added-only\` declaration forgives existing occurrences — only what the edit adds breaks
 the promise. That is usually what you want: a discipline adopted today should not indict
@@ -173,13 +204,19 @@ belongs in the top-level \`protectedPaths:\` list — its own config block, neve
 
 ### 3. Check the observation boundary
 
-Two kinds of promise cannot be judged here, whatever their shape:
+Do not confuse an expressible relation with available evidence:
 
-- **Destruction outside the repository** — judgment observes the project root only. Register
-  nothing; use the agent's own permission deny policy for commands like \`rm -rf ~\`.
-- **Writes by child processes** — a test runner or script writing files is invisible to the
-  session surface, which judges declared tool calls only. Say so to the user; the commit
-  surface will still see the result as a staged diff.
+- **Files outside the repository** — file-change protection observes the project root.
+  Use the host's permission policy for comprehensive protection outside it. A command-text
+  pattern may recognize a particular string, but does not observe all resulting writes.
+- **Writes by child processes** — arbitrary writes inside a test runner or script are not
+  individually observed by the session surface. A commit comparison can observe the resulting
+  files when they enter its selected diff; it does not recover the originating tool history.
+- **Missing history or actor channels** — choose the declaration's supply policy explicitly.
+  Commit observations have no session transcript; \`supply: pass\` records a skip, not success.
+- **Fresh execution or semantic proof** — the engine compares supplied evidence. It does not
+  run a new benchmark or prove that a written explanation is true. Preserve that unmet promise
+  as a draft rather than silently replacing it with a weaker text check.
 
 ### 4a. Expressible now — register a judged entry
 
@@ -240,12 +277,101 @@ disciplines:
         hits:
           - { op: 'source', of: 'command' }
           - { op: 'lines' }
-          - { op: 'matches', re: 'git push\\\\b.*--force(?![\\\\w-])' }
+          - { op: 'matches', re: 'git push\\b.*--force(?![\\w-])' }
       relate:
         - { id: 'no-force', relation: { op: 'empty', of: 'hits' }, message: '{value}' }
     enforce: advise
 \`\`\`
 
+The following examples implement the first three classification cases. Both locale files and
+the allowed-status file must exist and contain valid JSON. File bindings use the proposed
+contents for a file changed by the current observation, not a second stale disk read.
+
+\`\`\`yaml
+languages:
+  json:
+    productionGlob: 'locales/**/*.json'
+    testCmd: 'pnpm test'
+disciplines:
+  - id: 'locale-key-parity'
+    why: 'the ko and en locales must carry the same keys'
+    declare:
+      mechanism: 'pairing'
+      scope: { source: 'target.path', include: ['^locales/(ko|en)[.]json$'] }
+      sources:
+        ko: { file: 'locales/ko.json' }
+        en: { file: 'locales/en.json' }
+      supply: { ko: 'error', en: 'error' }
+      extract:
+        koKeys: [{ op: 'source', of: 'ko' }, { op: 'json' }, { op: 'flattenKeys' }]
+        enKeys: [{ op: 'source', of: 'en' }, { op: 'json' }, { op: 'flattenKeys' }]
+      relate:
+        - id: 'parity'
+          relation: { op: 'equal', of: ['koKeys', 'enKeys'] }
+          messageBySide:
+            left: '{key} is in ko only'
+            right: '{key} is in en only'
+    enforce: advise
+\`\`\`
+
+\`\`\`yaml
+languages:
+  json:
+    productionGlob: '*.json'
+    testCmd: 'pnpm test'
+disciplines:
+  - id: 'status-vocabulary'
+    why: 'statuses.json may contain only values listed in allowed-statuses.json'
+    declare:
+      mechanism: 'controlled-vocabulary'
+      scope: { source: 'target.path', include: ['^statuses[.]json$'] }
+      sources: { allowed: { file: 'allowed-statuses.json' } }
+      supply: { post: 'error', allowed: 'error' }
+      extract:
+        selected: [{ op: 'source', of: 'post' }, { op: 'json' }, { op: 'items' }]
+        permitted: [{ op: 'source', of: 'allowed' }, { op: 'json' }, { op: 'items' }]
+      relate:
+        - id: 'allowed-status'
+          relation: { op: 'subset', of: 'selected', in: 'permitted' }
+          message: 'unknown status: {value}'
+    enforce: advise
+\`\`\`
+
+Here both status files are JSON arrays of strings. This declaration scopes on statuses.json;
+editing only the allowed list does not trigger it. Broaden the observation deliberately if
+changes to that list must recheck all dependent files.
+
+\`\`\`yaml
+languages:
+  typescript:
+    productionGlob: 'src/**'
+    testCmd: 'pnpm test'
+disciplines:
+  - id: 'manifest-needs-npm-view'
+    why: 'a successful package lookup must precede a manifest edit'
+    declare:
+      mechanism: 'precedent'
+      scope: { source: 'target.path', include: ['^(packages/[^/]+/)?package[.]json$'] }
+      sources: { session: { transcript: true } }
+      supply: { session: 'pass' }
+      extract:
+        npmView:
+          - { op: 'source', of: 'session' }
+          - { op: 'toolUses', names: ['Bash'] }
+          - { op: 'filter', when: [{ field: 'succeeded', eq: true }] }
+          - { op: 'select', path: 'args.command' }
+          - { op: 'matches', re: '^npm view ' }
+      relate:
+        - id: 'npm-view'
+          relation: { op: 'nonEmpty', of: 'npmView' }
+          message: 'no successful npm view precedes this edit'
+    enforce: advise
+\`\`\`
+
+The precedent example proves only that an observed successful Bash call starts with npm view;
+it does not prove that the lookup concerns the dependency being edited. The commit surface has
+no transcript and therefore skips this example by its explicit supply policy.
+
 **Write the regex yourself — the user states the promise, you author the pattern.** The
 pattern is the part users find hardest, so never hand the prose back and ask for one. Three
 authoring traps, each measured on a live config:
@@ -268,27 +394,10 @@ authoring traps, each measured on a live config:
 
 A draft is prose with a handle: \`id\`, \`why\`, and the literal marker \`draft: true\` — no other
 keys. It produces no judgment and no telemetry; \`pdks explain\` lists it as unpromoted.
-Record the SHAPE of the promise inside \`why\`, so the promotion destination is already
-written down when a later engine can express it. Name the shape in these terms:
-
-| Shape | The promise reads like |
-| --- | --- |
-| pairing | every element of set A has a counterpart in set B (translation keys, i18n) |
-| companion | if X appears in a unit, Y must appear with it |
-| ordered | a sequence must keep its order (migration journals, version ladders) |
-| fingerprint | a derived artifact must match the hash/stamp of its source |
-| producer-owned | only a designated generator may write this artifact |
-| self-absolution | the party being judged must not write its own verdict field |
-| actor-scope | the same action is fine for one actor and a break for another |
-| phase-order | several precedents, in a fixed order |
-| turn-locality | the evidence must be in the same turn or time window |
-| stated-ground | the reason must be written down before the action |
-| controlled-vocabulary | only an enumerated set of words/values is allowed |
-| naming-convention | names must match a pattern per kind |
-| irreversible-marker | once present, a marker may never be removed |
-| delegation-scope | a delegated task may touch only its granted scope |
-| scope-valve | a defined exception valve, judged rather than ad hoc |
-| claim-verification | the claim must be re-run/measured, not trusted |
+Record the intended promise and the exact missing capability inside \`why\`. Do not classify
+pairing, vocabulary, or history promises as drafts merely because they are absent from a short
+example list. Check the catalogue, extraction steps, and observation channel first. A reserved
+\`delegated-scope\` declaration cannot be registered as a judged entry.
 
 \`\`\`yaml
 languages:
@@ -296,8 +405,8 @@ languages:
     productionGlob: 'src/**'
     testCmd: 'echo "set a verification command for {scope}"'
 disciplines:
-  - id: 'locale-files-move-together'
-    why: 'pairing — en.json and ko.json must change in the same commit; one side alone is a break'
+  - id: 'benchmark-supports-performance-claim'
+    why: 'a performance claim needs a fresh benchmark run during judgment; the engine cannot execute it'
     draft: true
 \`\`\`
 
@@ -316,10 +425,18 @@ own mechanism can actually reach:
 | \`forbidden-command\` | run one harmless command matching the pattern | the telemetry log tail — at advise the call proceeds and its row records the id |
 | \`precedent\` | one in-scope edit made without the required precedent | the telemetry log tail — a declaration reading the session judges on the session surface only (the commit surface has none, so its \`supply\` policy records it \`skipped\`) |
 
-Then undo the scratch break, repeat the same run, and confirm silence on the
-must-NOT-match direction. Close by telling the user which rung the entry landed on and
+Then undo the scratch break, repeat the same observation, and confirm a passing row for the
+must-NOT-match case. Silence alone may mean a scope miss, unchanged files, or unavailable evidence;
+check \`pdks explain\` and telemetry for \`config-fault\`, \`no-observation\`, or \`supply-pass\`. Close by telling the user which rung the entry landed on and
 that \`enforce: block\` is theirs to add later if the advise record earns it.
 
+## Updating this skill without losing local edits
+
+An upgrade does not overwrite an existing skill; rerunning \`pdks init claude-code\` reports it
+skipped. Generate a fresh copy in a disposable project using the installed package, compare it
+with this file, and merge the changes you want. Keep a backup of local additions. Do not delete
+the existing skill to force regeneration in the working project.
+
 ## Reading the advise record
 
 An \`advised\` row means a promise was broken and the call went through anyway. Rows land in