polydeukes 0.4.0 → 0.5.0

package/dist/init-claude-code.js

@@ -1,19 +1,20 @@
 /**
- * `initClaudeCode` — the session-surface installer (DIST-02 §3-a/§3-b/§3-g).
+ * `initClaudeCode` — the session-surface installer.
  *
  * One command wires a project into the session surface: prove the package resolves, run the
  * shared project-side scaffold ({@link scaffoldProject}), then add what this distribution
- * path owns — the delegator hook file, its `.claude/settings.json` registration, and the
- * discipline file that tells an agent the docs query exists (DOCS-02 §3-e).
+ * path owns — the delegator hook file, its `.claude/settings.json` registration, the
+ * discipline file that tells an agent the docs query exists, and the classification skill
+ * that turns a described problem into a config entry.
  *
- * Preflight comes first and nothing is written before it clears (§5-d invariant 2). A
- * generated hook whose import can never resolve blocks every call through its own
- * fail-closed catch, and a tree that also has no config and no valve to open cannot be
- * edited back into shape from inside the session — the brick §3-g exists to prevent.
+ * Preflight comes first and nothing is written before it clears. A generated hook whose
+ * import can never resolve blocks every call through its own fail-closed catch, and a tree
+ * that also has no config and no valve to open cannot be edited back into shape from inside
+ * the session.
  *
- * Nothing existing is overwritten (§5-d invariant 1). The settings file in particular is
- * merged, never replaced: a consumer's other PreToolUse registrations and permissions are
- * live configuration, and replacing them would disarm every other tool they wired.
+ * Nothing existing is overwritten. The settings file in particular is merged, never
+ * replaced: a consumer's other PreToolUse registrations and permissions are live
+ * configuration, and replacing them would disarm every other tool they wired.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { findPackageJSON } from 'node:module';
@@ -23,24 +24,24 @@ import { isPlainObject } from '@polydeukes/core';
 import { TOPICS } from './docs-query.js';
 import { CONFIG_FILENAMES } from './load-config.js';
 import { scaffoldProject } from './scaffold-project.js';
-/** The published entry point the generated hook loads the judge through (§3-c). */
+/** The published entry point the generated hook loads the judge through. */
 const HOOK_SPECIFIER = 'polydeukes/claude-code';
 /** The registration artifacts, as `projectRoot`-relative paths (the report vocabulary). */
 const HOOK_RELATIVE = '.claude/hooks/covenant-pretooluse.mjs';
 const SETTINGS_RELATIVE = '.claude/settings.json';
 const DISCOVERY_RELATIVE = '.claude/rules/polydeukes.md';
+const SKILL_RELATIVE = '.claude/skills/discipline-draft/SKILL.md';
 /**
  * The command the host spawns, and the string our registration is recognized by: the same
- * command already present means already registered (§3-a). A registration keyed on anything
- * else would be re-added on every run, and the host would then spawn the judge twice per
- * call — every verdict and every telemetry row doubled.
+ * command already present means already registered. A registration keyed on anything else
+ * would be re-added on every run, and the host would then spawn the judge twice per call —
+ * every verdict and every telemetry row doubled.
  */
 const HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR"/${HOOK_RELATIVE}`;
 /** Which calls reach the judge — the adapter's own vocabulary, never a copy of it. */
 const HOOK_MATCHER = [...MUTATING_TOOLS, ...SHELL_TOOLS].join('|');
 /**
- * The generated hook (§3-b) — a copy of this repository's own delegator with its dogfooding
- * narrative removed. It carries no assembly at all, so upgrading the package upgrades the
+ * The generated hook. It carries no assembly at all, so upgrading the package upgrades the
  * judge without regenerating this file.
  */
 const GENERATED_HOOK = `#!/usr/bin/env node
@@ -71,13 +72,16 @@ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 try {
   const { runClaudeCodeHook } = await import('${HOOK_SPECIFIER}');
   const { exitCode } = await runClaudeCodeHook({ repoRoot });
-  process.exit(exitCode);
+  // Assign and let the process end naturally instead of process.exit(): an explicit exit
+  // can preempt a buffered stderr write on platforms with async pipes, dropping the break
+  // reason the agent needs to read.
+  process.exitCode = exitCode;
 } catch (error) {
   console.error(\`covenant hook failed closed: \${error?.message ?? error}\`);
-  process.exit(2);
+  process.exitCode = 2;
 }
 `;
-/** What a session is about to do, per topic — the correspondence §3-e asks the file to carry. */
+/** What a session is about to do, per topic — the correspondence the generated file carries. */
 const DOCS_TOPIC_PURPOSE = {
     install: 'install Polydeukes, or wire another surface into this project',
     config: 'edit `polydeukes.config.*` — every key and what reads it',
@@ -86,11 +90,10 @@ const DOCS_TOPIC_PURPOSE = {
     witness: 'open a blocked call in person',
 };
 /**
- * The generated discipline file (DOCS-02 §3-e) — the discovery path that gets the query
- * surface called. A query an agent never learns about is a query that does not exist, and
- * the alternative place to say so is the consumer's own resident instructions, which are
- * theirs to write. One scoped file costs nothing while it waits: `paths` frontmatter keeps
- * it out of context until a Polydeukes path is in play.
+ * The generated discipline file — the discovery path that gets the query surface called. A
+ * query an agent never learns about is a query that does not exist. One scoped file costs
+ * nothing while it waits: `paths` frontmatter keeps it out of context until a Polydeukes
+ * path is in play.
  *
  * Both the command forms and the topic names come from the shipped surface itself — a file
  * naming a query that exits 2 fails the agent once, and it never calls the command again.
@@ -117,12 +120,176 @@ manager's exec form — from the project root.
 | --- | --- |
 ${TOPICS.map((topic) => `| ${DOCS_TOPIC_PURPOSE[topic]} | \`pdks docs ${topic}\` |`).join('\n')}
 `;
+/**
+ * The generated classification skill — the procedure that turns a described problem into a
+ * registered entry. A classification procedure an agent never learns about is one that never
+ * runs, so it ships as an artifact of the install rather than as prose in a README.
+ *
+ * Its advise-consumption section is the delivery path for advised rows: the session surface
+ * lets an advised call through with exit 0, and the reason never reaches the model at call
+ * time — reading the telemetry log at task boundaries is the only way it arrives.
+ */
+export const GENERATED_SKILL = `---
+name: discipline-draft
+description: Turn a described discipline problem into a registered entry in polydeukes.config — a judged entry when the current families can express it, a draft entry otherwise. Use when the user describes a recurring problem they want promised away ("I keep...", "stop X from happening", "we should never...", "how do I enforce Y").
+---
+
+# discipline-draft — from a problem description to a registered discipline
+
+This project is judged by Polydeukes. A discipline starts as prose and climbs a ladder —
+\`draft\` (registered, read, never judged) → \`advise\` (judged, recorded, never stops a call) →
+\`block\` (stops the call; the user's explicit choice, never the default). This skill walks a
+problem description down to the right first rung and registers it.
+
+## Procedure
+
+### 1. Restate the problem as a promise
+
+Rewrite the description as one sentence of the form "X must not happen" or "when A happens,
+B must also happen". If the sentence needs "unless" more than once, split it into two
+promises and classify each separately.
+
+### 2. Classify the shape
+
+Ask these questions in order; the first yes decides.
+
+| # | Question | Family | Entry key |
+| --- | --- | --- | --- |
+| 1 | Is the promise about content newly ADDED to a file (a pattern that must not appear in new lines)? | delta | \`forbid\` |
+| 2 | Is it about a whole path that must not be modified or deleted (creating it once stays allowed)? | path | \`immutable\` |
+| 3 | Is it about the shell command line itself, regardless of files? | command | \`forbidCommand\` |
+| 4 | Does it require that something else was already done earlier in the session (a tool call that must precede this one)? | context | \`requirePrecedent\` |
+| 5 | None of the above | — | \`draft: true\` (step 4b) |
+
+Existing occurrences are forgiven by the delta family — only new additions break the promise.
+That is usually what you want: a discipline adopted today should not indict yesterday's code.
+
+Two path-shaped promises take no \`disciplines:\` entry at all. A path nobody may touch
+belongs in the top-level \`protectedPaths:\` list — its own config block, never an entry
+key. And a path that must never be CREATED is not expressible today: \`immutable\` allows
+creation by design, so register that promise as a draft (step 4b).
+
+### 3. Check the observation boundary
+
+Two kinds of promise cannot be judged here, whatever their shape:
+
+- **Destruction outside the repository** — judgment observes the project root only. Register
+  nothing; use the agent's own permission deny policy for commands like \`rm -rf ~\`.
+- **Writes by child processes** — a test runner or script writing files is invisible to the
+  session surface, which judges declared tool calls only. Say so to the user; the commit
+  surface will still see the result as a staged diff.
+
+### 4a. Expressible now — register a judged entry
+
+Add the entry to the \`disciplines:\` array in \`polydeukes.config.yaml\`. Advise is the default
+landing — a break is recorded as \`advised\` and the call goes on — and the \`enforce: advise\`
+line below only spells that default out. NEVER write \`enforce: block\` from this skill:
+promotion to block is the user's own choice, made after the advise measurements have been
+read.
+
+The examples below are whole documents, so \`languages:\` — the schema's one required block —
+appears alongside the entry; in a config that already has one, copy the entry only.
+
+\`\`\`yaml
+languages:
+  placeholder:
+    productionGlob: 'src/**'
+    testCmd: 'echo "set a verification command for {scope}"'
+disciplines:
+  - id: 'no-focused-tests'
+    why: 'a committed .only silently shrinks the suite to one test'
+    forbid: '\\.only\\('
+    enforce: advise
+\`\`\`
+
+**Write the regex yourself — the user states the promise, you author the pattern.** The
+pattern is the part users find hardest, so never hand the prose back and ask for one. Three
+authoring traps, each measured on a live config:
+
+- **A pattern answers a syntactic question only.** "Is this string a forbidden word" is
+  syntax; "is this a new dependency version" is meaning, and a regex leaks both ways on a
+  semantic question. When the question is semantic, narrow \`in:\` to the files where any
+  match IS a break (\`in:\`/\`except:\` scope \`forbid\` and \`requirePrecedent\` only), or
+  accept "editing this file at all" as the trigger.
+- **\`^\` silently disarms on the delta axis.** \`forbid\` scans whole file content as one
+  string, so a line-start anchor matches the first line only — write \`(^|\\n)\` there.
+  \`forbidCommand\` judges per line and the whole string, so \`^\` is safe on that axis.
+- **Author both directions.** Before registering, write down one string the pattern must
+  match and one nearby string it must not (\`forbid\` vs \`forbidden\`, a flag vs its
+  substring). A pattern checked in only the breaking direction over-fires in review-proof
+  ways.
+
+### 4b. Not expressible yet — register a draft
+
+A draft is prose with a handle: \`id\`, \`why\`, and the literal marker \`draft: true\` — no other
+keys. It produces no judgment and no telemetry; \`pdks explain\` lists it as unpromoted.
+Record the SHAPE of the promise inside \`why\`, so the promotion destination is already
+written down when a later engine can express it. Name the shape in these terms:
+
+| Shape | The promise reads like |
+| --- | --- |
+| pairing | every element of set A has a counterpart in set B (translation keys, i18n) |
+| companion | if X appears in a unit, Y must appear with it |
+| ordered | a sequence must keep its order (migration journals, version ladders) |
+| fingerprint | a derived artifact must match the hash/stamp of its source |
+| producer-owned | only a designated generator may write this artifact |
+| self-absolution | the party being judged must not write its own verdict field |
+| actor-scope | the same action is fine for one actor and a break for another |
+| phase-order | several precedents, in a fixed order |
+| turn-locality | the evidence must be in the same turn or time window |
+| stated-ground | the reason must be written down before the action |
+| controlled-vocabulary | only an enumerated set of words/values is allowed |
+| naming-convention | names must match a pattern per kind |
+| irreversible-marker | once present, a marker may never be removed |
+| delegation-scope | a delegated task may touch only its granted scope |
+| scope-valve | a defined exception valve, judged rather than ad hoc |
+| claim-verification | the claim must be re-run/measured, not trusted |
+
+\`\`\`yaml
+languages:
+  placeholder:
+    productionGlob: 'src/**'
+    testCmd: 'echo "set a verification command for {scope}"'
+disciplines:
+  - id: 'locale-files-move-together'
+    why: 'pairing — en.json and ko.json must change in the same commit; one side alone is a break'
+    draft: true
+\`\`\`
+
+### 5. Prove it fires, then close
+
+Run \`pdks explain\` and confirm the new entry is listed (a judged entry with its family and
+surfaces; a draft as unpromoted).
+
+For a judged entry, registration is not the finish — a pattern that never fires protects
+nothing while looking installed. Fire it once for real, with the proof run its family can
+actually reach:
+
+| Family | Break it once | The entry's id shows up in |
+| --- | --- | --- |
+| \`forbid\` / \`immutable\` | one scratch edit matching the must-match direction | \`pdks covenant check --worktree\` output — the exit stays 0 at advise, the id is the proof |
+| \`forbidCommand\` | run one harmless command matching the pattern | the telemetry log tail — at advise the call proceeds and its row records the id |
+| \`requirePrecedent\` | one in-scope edit made without the required precedent | the telemetry log tail — this family judges on the session surface only (the commit surface records it \`skipped\`) |
+
+Then undo the scratch break, repeat the same run, and confirm silence on the
+must-NOT-match direction. Close by telling the user which rung the entry landed on and
+that \`enforce: block\` is theirs to add later if the advise record earns it.
+
+## Reading the advise record
+
+An \`advised\` row means a promise was broken and the call went through anyway. Rows land in
+the telemetry log at the path configured by \`telemetry.logPath\` (default
+\`.polydeukes/roi.log\`). The hook's stderr note is not shown to you, so consult the log at
+task boundaries: before committing, or after a batch of edits, read the tail and act on any
+\`advised\` row — fix the break, or tell the user why it should stand. An advisory nobody
+reads measures nothing.
+`;
 /**
  * The default preflight: is `polydeukes` installed where `projectRoot` can reach it?
  *
  * ESM resolution specifically, because that is what the generated hook's `await import(...)`
- * runs; the CJS alternatives were measured disagreeing in both directions (DIST-02 §5-e,
- * which also carries the standing risk that `findPackageJSON` is experimental in Node 24).
+ * runs; the CJS alternatives were measured disagreeing with it in both directions.
+ * `findPackageJSON` is experimental in Node 24, so its behaviour can still change.
  */
 function resolveFromProjectRoot(projectRoot) {
     // Absence throws here rather than returning undefined (Node 24.18); the branch guards the
@@ -135,7 +302,7 @@ function resolveFromProjectRoot(projectRoot) {
     // map, so a version predating the session subpath, or one whose dist was never built,
     // passes a bare-name check while the generated hook fails on every call. That tree cannot
     // be reopened with the witness token either, because an assembly crash lands before any
-    // verdict (PR #48 review).
+    // verdict.
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
     const subpath = isPlainObject(manifest) && isPlainObject(manifest.exports)
         ? manifest.exports[`./${HOOK_SPECIFIER.split('/')[1]}`]
@@ -209,9 +376,9 @@ function mergeSettings(projectRoot, settings, report) {
     // Read the registration back rather than assuming the write carried it. The one outcome
     // this installer must never produce is a successful-looking run whose judge never spawns,
     // and the merge can drop the entry without failing — a settings file whose root is an
-    // array takes the assignment as a non-index property and `JSON.stringify` discards it
-    // (PR #48 review). Checking the file instead of the shapes that reach it keeps the
-    // question finite: one code path, asked after every write, whatever arrived.
+    // array takes the assignment as a non-index property and `JSON.stringify` discards it.
+    // Checking the file instead of the shapes that reach it keeps the question finite: one
+    // code path, asked after every write, whatever arrived.
     if (!carriesRegistration(JSON.parse(readFileSync(settingsPath, 'utf-8')))) {
         throw new Error(`${SETTINGS_RELATIVE} in ${projectRoot} did not take the PreToolUse registration — ` +
             'the judge would never be spawned. Fix that file and re-run');
@@ -219,12 +386,12 @@ function mergeSettings(projectRoot, settings, report) {
     report.created.push(SETTINGS_RELATIVE);
 }
 /**
- * Install the session surface into `spec.projectRoot` (DIST-02 §3-a), skipping whatever is
- * already there and reporting both halves per artifact.
+ * Install the session surface into `spec.projectRoot`, skipping whatever is already there
+ * and reporting both halves per artifact.
  *
- * Throws before any write when the package cannot be resolved from that root (§3-g) or when
- * two config spellings already coexist there (§3-a third disposition) — both leave zero
- * files. Translating a throw into exit 2 with the install command is the bin's job.
+ * Throws before any write when the package cannot be resolved from that root or when two
+ * config spellings already coexist there — both leave zero files. Translating a throw into
+ * exit 2 with the install command is the bin's job.
  */
 export function initClaudeCode(spec) {
     const resolvePolydeukes = spec.resolvePolydeukes ?? resolveFromProjectRoot;
@@ -235,21 +402,22 @@ export function initClaudeCode(spec) {
         // The message names the package because the user's next action is installing it — the
         // seam's own message cannot be relied on to say so. The original is carried through
         // rather than discarded: "not exposed" and "not installed" need different actions, and
-        // an experimental resolver can fail for reasons that are neither (PR #48 review).
+        // an experimental resolver can fail for reasons that are neither.
         throw new Error(`cannot use 'polydeukes' from ${spec.projectRoot} — install or update it there first ` +
             "(e.g. 'npm install --save-dev polydeukes'), then run this command again: " +
             `${error instanceof Error ? error.message : String(error)}`);
     }
-    // Every read that can fail is settled before the first write (§5-d invariant 2).
+    // Every read that can fail is settled before the first write.
     const settings = readSettings(spec.projectRoot);
     const report = scaffoldProject(spec.projectRoot);
     writeIfAbsent(spec.projectRoot, HOOK_RELATIVE, GENERATED_HOOK, report);
     mergeSettings(spec.projectRoot, settings, report);
     // Written last, after the registration the hook needs to ever be spawned. Every write
     // between the hook file and that registration widens the window where a throw leaves a
-    // delegator nothing invokes — a tree that looks installed and is judged by nothing. This
-    // artifact is the one whose absence costs only discoverability, so it goes where a
-    // failure costs least.
+    // delegator nothing invokes — a tree that looks installed and is judged by nothing. These
+    // two artifacts are the ones whose absence costs only discoverability, so they go where
+    // a failure costs least.
     writeIfAbsent(spec.projectRoot, DISCOVERY_RELATIVE, GENERATED_DISCOVERY, report);
+    writeIfAbsent(spec.projectRoot, SKILL_RELATIVE, GENERATED_SKILL, report);
     return report;
 }

package/dist/load-config.d.ts

@@ -1,24 +1,22 @@
 /**
- * Config discovery and loading (CONFIG-03) — the one place allowed to read and parse the
- * data config file, so the core stays file-I/O-free.
+ * Config discovery and loading — the one place allowed to read and parse the data config
+ * file, so the core stays file-I/O-free.
  *
  * This lives in its own module rather than in the package barrel because ESM re-exports are
- * eager: when `index.ts` re-exports both composition roots, anything importing `loadConfig`
- * from the barrel instantiates the session adapter too. That put `@polydeukes/adapter-claude-code`
- * on the commit surface's load path, where it is never used — a workspace missing only that
- * dist would kill `pdks covenant check` before its fail-closed handler could record a row
- * (PR #46 review). Both composition roots import this module directly for the same reason.
+ * eager: importing `loadConfig` from the barrel would instantiate both composition roots,
+ * putting the session adapter on the commit surface's load path where it is never used. A
+ * workspace missing only that dist would then kill `pdks covenant check` before its
+ * fail-closed handler could record a row. Both composition roots import this module directly
+ * for the same reason.
  */
 import type { ResolvedConfig } from '@polydeukes/core';
 /**
  * The three accepted config filenames, checked directly under the given rootDir. Exported
- * for the scaffold (DIST-02 §3-a): its existence check has to see exactly what discovery
- * sees, or it would create a second spelling and make every later load ambiguous.
+ * for the scaffold: its existence check has to see exactly what discovery sees, or it would
+ * create a second spelling and make every later load ambiguous.
  */
 export declare const CONFIG_FILENAMES: readonly ['polydeukes.config.yaml', 'polydeukes.config.yml', 'polydeukes.config.json'];
-/**
- * `LoadedConfig` — the loader's return value (CONFIG-03 §4.1).
- */
+/** `LoadedConfig` — the loader's return value. */
 export type LoadedConfig = {
     /** defineConfig() resolution — protectedPaths already includes configPath */
     config: ResolvedConfig;
@@ -26,7 +24,7 @@ export type LoadedConfig = {
     configPath: string;
 };
 /**
- * Discover, parse, and validate the Polydeukes data config in `rootDir` (CONFIG-03 §4.1).
+ * Discover, parse, and validate the Polydeukes data config in `rootDir`.
  *
  * Discovery looks at exactly the three candidate filenames directly under `rootDir`
  * (no upward walk). Every failure branch throws — silent defaults are forbidden:
@@ -38,6 +36,6 @@ export type LoadedConfig = {
  *
  * Before returning, the discovered `configPath` is appended to
  * `config.protectedPaths` unless already present — the config file itself joins the
- * protection surface (schema rule 6), guaranteed here so no assembler has to remember.
+ * protection surface, guaranteed here so no assembler has to remember.
  */
 export declare function loadConfig(rootDir: string): LoadedConfig;

package/dist/load-config.js

@@ -1,13 +1,13 @@
 /**
- * Config discovery and loading (CONFIG-03) — the one place allowed to read and parse the
- * data config file, so the core stays file-I/O-free.
+ * Config discovery and loading — the one place allowed to read and parse the data config
+ * file, so the core stays file-I/O-free.
  *
  * This lives in its own module rather than in the package barrel because ESM re-exports are
- * eager: when `index.ts` re-exports both composition roots, anything importing `loadConfig`
- * from the barrel instantiates the session adapter too. That put `@polydeukes/adapter-claude-code`
- * on the commit surface's load path, where it is never used — a workspace missing only that
- * dist would kill `pdks covenant check` before its fail-closed handler could record a row
- * (PR #46 review). Both composition roots import this module directly for the same reason.
+ * eager: importing `loadConfig` from the barrel would instantiate both composition roots,
+ * putting the session adapter on the commit surface's load path where it is never used. A
+ * workspace missing only that dist would then kill `pdks covenant check` before its
+ * fail-closed handler could record a row. Both composition roots import this module directly
+ * for the same reason.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -15,8 +15,8 @@ import { ConfigValidationError, defineConfig, isPlainObject } from '@polydeukes/
 import { parseDocument } from 'yaml';
 /**
  * The three accepted config filenames, checked directly under the given rootDir. Exported
- * for the scaffold (DIST-02 §3-a): its existence check has to see exactly what discovery
- * sees, or it would create a second spelling and make every later load ambiguous.
+ * for the scaffold: its existence check has to see exactly what discovery sees, or it would
+ * create a second spelling and make every later load ambiguous.
  */
 export const CONFIG_FILENAMES = [
     'polydeukes.config.yaml',
@@ -24,7 +24,7 @@ export const CONFIG_FILENAMES = [
     'polydeukes.config.json',
 ];
 /**
- * Discover, parse, and validate the Polydeukes data config in `rootDir` (CONFIG-03 §4.1).
+ * Discover, parse, and validate the Polydeukes data config in `rootDir`.
  *
  * Discovery looks at exactly the three candidate filenames directly under `rootDir`
  * (no upward walk). Every failure branch throws — silent defaults are forbidden:
@@ -36,7 +36,7 @@ export const CONFIG_FILENAMES = [
  *
  * Before returning, the discovered `configPath` is appended to
  * `config.protectedPaths` unless already present — the config file itself joins the
- * protection surface (schema rule 6), guaranteed here so no assembler has to remember.
+ * protection surface, guaranteed here so no assembler has to remember.
  */
 export function loadConfig(rootDir) {
     const found = CONFIG_FILENAMES.filter((name) => existsSync(join(rootDir, name)));

package/dist/scaffold-project.d.ts

@@ -1,28 +1,37 @@
 /**
- * `scaffoldProject` — the project-side scaffold layer (DIST-02 §3-i).
+ * `scaffoldProject` — the project-side scaffold layer.
  *
  * The half of an installation every distribution path shares: the data config the judges
  * read, and the telemetry ignore line. What differs between paths is REGISTRATION — how the
  * agent is told to spawn a judge at all — and that lives one layer up (`initClaudeCode` for
- * the `init` path, a manifest for the plugin one). The split is what lets a second path
- * reuse this function unchanged instead of scaffolding a config a second time, so nothing
- * that registers anything belongs here.
+ * the `init` path). The split is what lets a second path reuse this function unchanged
+ * instead of scaffolding a config a second time, so nothing that registers anything belongs
+ * here.
  *
- * Nothing existing is ever overwritten (§5-d invariant 1): an artifact that is already there
- * is reported and left alone. The config existence check reads all three discovery
- * candidates rather than the canonical name alone — writing `polydeukes.config.yaml` next to
- * a project's `.yml` makes {@link loadConfig} throw on ambiguity, and the fail-closed session
- * surface then blocks every call, so the installer itself would be what stopped the project.
- * Existence is FILE PRESENCE, never parse success: reading a broken config as "absent" would
- * destroy the very file the consumer was midway through fixing, and fixing it is their job.
+ * Nothing existing is ever overwritten: an artifact that is already there is reported and
+ * left alone. The config existence check reads all three discovery candidates rather than
+ * the canonical name alone — writing `polydeukes.config.yaml` next to a project's `.yml`
+ * makes {@link loadConfig} throw on ambiguity, and the fail-closed session surface then
+ * blocks every call, so the installer itself would be what stopped the project. Existence is
+ * FILE PRESENCE, never parse success: reading a broken config as "absent" would destroy the
+ * very file the consumer was midway through fixing, and fixing it is their job.
  */
 /**
- * Per-artifact outcome, as `projectRoot`-relative paths — the bin prints it (§3-a stdout
- * contract). `created` names what this run wrote, `skipped` what it found and left alone; a
- * silent skip would leave the user unable to tell an idempotent no-op from a failed run.
+ * Per-artifact outcome, as `projectRoot`-relative paths — the bin prints it. `created` names
+ * what this run wrote, `skipped` what it found and left alone; a silent skip would leave the
+ * user unable to tell an idempotent no-op from a failed run.
  */
 export type ScaffoldReport = {
     created: string[];
     skipped: string[];
 };
+/**
+ * Create the project-side artifacts of a Polydeukes installation in `projectRoot`, skipping
+ * whatever is already there.
+ *
+ * Throws when two or more config spellings coexist — that tree is already stopped, since
+ * {@link loadConfig} refuses an ambiguous discovery, and adding artifacts to it would wire a
+ * judge whose every call fails closed. The throw lands before any write, so a human deleting
+ * one config is all it takes to reopen the path.
+ */
 export declare function scaffoldProject(projectRoot: string): ScaffoldReport;

package/dist/scaffold-project.js

@@ -1,36 +1,36 @@
 /**
- * `scaffoldProject` — the project-side scaffold layer (DIST-02 §3-i).
+ * `scaffoldProject` — the project-side scaffold layer.
  *
  * The half of an installation every distribution path shares: the data config the judges
  * read, and the telemetry ignore line. What differs between paths is REGISTRATION — how the
  * agent is told to spawn a judge at all — and that lives one layer up (`initClaudeCode` for
- * the `init` path, a manifest for the plugin one). The split is what lets a second path
- * reuse this function unchanged instead of scaffolding a config a second time, so nothing
- * that registers anything belongs here.
+ * the `init` path). The split is what lets a second path reuse this function unchanged
+ * instead of scaffolding a config a second time, so nothing that registers anything belongs
+ * here.
  *
- * Nothing existing is ever overwritten (§5-d invariant 1): an artifact that is already there
- * is reported and left alone. The config existence check reads all three discovery
- * candidates rather than the canonical name alone — writing `polydeukes.config.yaml` next to
- * a project's `.yml` makes {@link loadConfig} throw on ambiguity, and the fail-closed session
- * surface then blocks every call, so the installer itself would be what stopped the project.
- * Existence is FILE PRESENCE, never parse success: reading a broken config as "absent" would
- * destroy the very file the consumer was midway through fixing, and fixing it is their job.
+ * Nothing existing is ever overwritten: an artifact that is already there is reported and
+ * left alone. The config existence check reads all three discovery candidates rather than
+ * the canonical name alone — writing `polydeukes.config.yaml` next to a project's `.yml`
+ * makes {@link loadConfig} throw on ambiguity, and the fail-closed session surface then
+ * blocks every call, so the installer itself would be what stopped the project. Existence is
+ * FILE PRESENCE, never parse success: reading a broken config as "absent" would destroy the
+ * very file the consumer was midway through fixing, and fixing it is their job.
  */
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CONFIG_FILENAMES } from './load-config.js';
-/** `.gitignore` name and the telemetry directory entry it must carry (§3-a). */
+/** `.gitignore` name and the telemetry directory entry it must carry. */
 const GITIGNORE = '.gitignore';
 const TELEMETRY_IGNORE_LINE = '.polydeukes/';
 const GITIGNORE_ENTRY = `# Polydeukes telemetry — local observation data, never committed.\n${TELEMETRY_IGNORE_LINE}\n`;
 /**
- * The generated config: the §3-d minimum protection set and the §3-e witness block, both
- * mandatory. Emitted as a literal template rather than serialized from an object because
- * the comments ARE the artifact — a consumer's first contact with the protection surface is
- * reading why each entry is on it.
+ * The generated config: the minimum protection set and the witness block, both mandatory.
+ * Emitted as a literal template rather than serialized from an object because the comments
+ * ARE the artifact — a consumer's first contact with the protection surface is reading why
+ * each entry is on it.
  *
  * {@link schemaDirective} prepends the `yaml-language-server` line when the schema is where
- * that line would name it (DIST-05 §3-b).
+ * that line would name it.
  */
 const GENERATED_CONFIG = `# Polydeukes protection policy — generated by \`pdks init claude-code\`.
 #
@@ -55,6 +55,9 @@ languages:
 #     layer that can watch it happen.
 #
 # A minimum. Add entries as you find you want them.
+#
+# This list is what blocks. Every \`disciplines:\` entry below lands at advise — a break is
+# recorded and the call goes on — unless the entry itself says \`enforce: block\`.
 protectedPaths:
   - '.claude/hooks'
   - '.claude/settings.json'
@@ -71,16 +74,29 @@ protectedPaths:
 witness:
   token: 'pdks witness'
   ttlMinutes: 10
+
+# The disciplines you judge by, and the three rungs one climbs — shown as three entries so
+# each rung is a line you can copy. Uncomment to start; ids must stay distinct.
+#
+# disciplines:
+#   # A draft: prose only, no predicate. Registered and read, never judged.
+#   - id: 'no-todo-in-shipped-code-draft'
+#     why: 'a TODO nobody owns is a decision deferred out of sight'
+#     draft: true
+#
+#   # Promoted to a judgment. Advise is the default — recorded as \`advised\`, never stops
+#   # the call — so this line is optional; it is written here to show the rung.
+#   - id: 'no-todo-in-shipped-code'
+#     why: 'a TODO nobody owns is a decision deferred out of sight'
+#     forbid: 'TODO'
+#     enforce: advise
+#
+#   # The promotion — block is your choice, never the default.
+#   - id: 'no-todo-in-shipped-code-blocking'
+#     why: 'a TODO nobody owns is a decision deferred out of sight'
+#     forbid: 'TODO'
+#     enforce: block
 `;
-/**
- * Create the project-side artifacts of a Polydeukes installation in `projectRoot` (§3-i),
- * skipping whatever is already there.
- *
- * Throws when two or more config spellings coexist (§3-a third disposition) — that tree is
- * already stopped, since {@link loadConfig} refuses an ambiguous discovery, and adding
- * artifacts to it would wire a judge whose every call fails closed. The throw lands before
- * any write, so a human deleting one config is all it takes to reopen the path.
- */
 /** The schema's path from a config sitting in `projectRoot`, as the directive spells it. */
 const SCHEMA_REL = 'node_modules/polydeukes/dist/schema/polydeukes.schema.json';
 /**
@@ -99,6 +115,15 @@ function schemaDirective(projectRoot) {
         ? `# yaml-language-server: $schema=${SCHEMA_REL}\n`
         : '';
 }
+/**
+ * Create the project-side artifacts of a Polydeukes installation in `projectRoot`, skipping
+ * whatever is already there.
+ *
+ * Throws when two or more config spellings coexist — that tree is already stopped, since
+ * {@link loadConfig} refuses an ambiguous discovery, and adding artifacts to it would wire a
+ * judge whose every call fails closed. The throw lands before any write, so a human deleting
+ * one config is all it takes to reopen the path.
+ */
 export function scaffoldProject(projectRoot) {
     const report = { created: [], skipped: [] };
     const found = CONFIG_FILENAMES.filter((name) => existsSync(join(projectRoot, name)));