polydeukes 0.4.0 → 0.5.0

package/dist/covenant-check.js

@@ -1,58 +1,27 @@
 /**
- * `pdks covenant check` — the assembled commit-surface judgment runner (ADAPTER-git §4.3).
+ * `pdks covenant check` — the commit surface's composition root.
  *
- * This is the commit-surface counterpart of the session hook's composition root: the one
- * umbrella-owned place where the git adapter (staged-diff vocabulary), the covenant
- * dispatcher, and the config loader meet. Assembly order mirrors the session hook —
- * loadConfig → normalizeProtectedPaths → collect/translate → dispatchCovenants — and the
- * judge bodies it spawns are the very same covenant dist executables, so a staged change
- * receives the same verdict a session tool call would (AC-4 same-judge).
+ * Assembly mirrors the session hook — loadConfig → normalizeProtectedPaths → collect →
+ * dispatchCovenants — and spawns the same covenant dist bodies, so a change receives the
+ * verdict a session tool call would. Each change is dispatched as its own input so
+ * telemetry stays one row per file. The witness valve is a `/dev/tty` prompt that only
+ * the staged domain assembles; the other domains open no commit.
  *
- * Each staged change is dispatched as its own single-change input: one staged file is
- * the commit surface's analogue of one session tool call, so telemetry stays N:N (AC-6)
- * and `gain` reads a per-file subject rather than one opaque batch line.
- *
- * The valve is a TTY prompt (PRD §4.4 decision A): the injected `ttyPrompt` seam returns
- * the line a human typed at the terminal, compared against the config witness token in
- * FULL (COVENANT-15 — substring acceptance is forbidden). The seam's absence models a
- * non-interactive environment (CI, an AI-spawned git commit): no prompt, no witness —
- * the valve is structurally reachable only by a human at a terminal, which is the
- * commit-surface translation of "only a human utterance opens the session valve". The
- * answer is cached so one commit prompts at most once, and nothing is ever persisted —
- * a state file would be an agent-forgeable surface (PRD §7).
- *
- * fail-closed: a missing/invalid config, an unbuilt judge body, or a collector failure
- * exits 2 with one blocked record. The telemetry path is settled before the first failure
- * branch can be taken (ADAPTER-git-b §4.1), so the record has somewhere to land even when
- * the config that names its path never loaded. An empty staging area is an explicit pass
- * (nothing to judge — the dispatcher precedent of zero matches, zero records).
+ * fail-closed: a missing config, an unbuilt body, or a collector failure exits 2 with one
+ * blocked record. An empty domain is an explicit pass with no records.
  */
-import { existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
-import { collectStagedChanges, covenantInputFromStagedChanges, resolveGitAdapterSettings, STAGED_DELETE, STAGED_WRITE, } from '@polydeukes/adapter-git';
+import { resolve } from 'node:path';
+import { collectRangeChanges, collectStagedChanges, collectWorktreeChanges, covenantInputFromStagedChanges, resolveGitAdapterSettings, STAGED_DELETE, STAGED_WRITE, } from '@polydeukes/adapter-git';
 import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, } from '@polydeukes/core';
-import { compileDisciplineRegistrations, dispatchCovenants, } from '@polydeukes/covenant';
+import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
 import { loadConfig } from './load-config.js';
 /**
- * Build the witness predicate for the TTY valve, or undefined when no valve can exist
- * (no witness configured, or no TTY seam — both leave the dispatcher with no way to open
- * one at all). The valve IS the witness: the judge has already broken, and the human at
- * the terminal supplies the pass condition themselves, sudo-style. The prompt fires
- * lazily on the first registration that actually BROKE and names it from the dispatcher's
- * context (COVENANT-17 §4.5) — the label and the MATCHED entry, the same subject the
- * telemetry row carries, so screen and log never disagree. The human reads what broke,
- * on what, and how far one answer reaches. The verdict is cached: one commit, at most
- * one prompt, full-token equality only — and the token itself is never printed, or
- * typing it from memory would become copying it off the screen.
- *
- * Both comparison sides are trimmed, mirroring the session valve: `ttlWitness` trims the
- * config token at assembly precisely because config validation accepts a padded value,
- * and it compares the utterance's first line trimmed — without the same normalisation
- * here, one padded token would open the session surface and permanently shut this one
- * (PR #41 review). The cache latches CLOSED before the seam is consulted: a throwing
- * seam must not retry on the next broken registration, or the prompt's own commit-wide
- * promise becomes a lie (AC §5.3 one commit, at most one prompt).
+ * The TTY witness predicate, or undefined when no valve can exist (no witness configured
+ * or no TTY seam). It fires on the first registration that broke, names it from the
+ * dispatcher's context, and caches the answer: one commit, at most one prompt, full-token
+ * equality. Both sides are trimmed like the session valve, since config validation accepts
+ * a padded token. The cache latches closed before the seam is consulted so a throwing seam
+ * never re-prompts.
  */
 function ttyWitnessValve(witness, ttyPrompt) {
     if (witness === undefined || ttyPrompt === undefined)
@@ -71,32 +40,11 @@ function ttyWitnessValve(witness, ttyPrompt) {
         return verdict;
     };
 }
-/**
- * Compose a judge body's module path and prove the file is there (CONFIG-06b §4.2).
- * Spawning an absent module succeeds and its child exits 1 — the code a break verdict
- * returns — so a judge that ran no line would arrive as a violation and, under `advise`,
- * be waved through. Nothing downstream can separate the two (`translateExitCode` sees
- * that number alone), so the proof happens here, before the spawn. Producing the path
- * and proving it are one step on purpose: a path that skipped the proof cannot be
- * constructed, and only the bodies this surface actually composes are proven.
- */
-function provenBodyPath(distDir, fileName) {
-    const modulePath = join(distDir, fileName);
-    if (!existsSync(modulePath)) {
-        throw new Error(`judge body ${modulePath} is missing — run 'pnpm build' to rebuild it`);
-    }
-    return modulePath;
-}
 /**
  * One blocked record for a run that failed closed before any dispatch could judge.
- *
- * The write goes through `appendRecordFailOpen` rather than the mkdir-free `appendRecord`:
- * a repository that has never been judged has no `.polydeukes/` directory — the shape
- * `pdks init` leaves every consumer in — and the raw append would fail open on ENOENT,
- * turning the very first fail-closed run into an unrecorded block. The wrapper carries both
- * the parent-directory guarantee and the fail-open contract, so a telemetry failure still
- * never softens the blocking exit. An undefined path is tolerated here because a non-string
- * `repoRoot` leaves no root to write a row under.
+ * `appendRecordFailOpen` creates the missing `.polydeukes/` of a never-judged repository,
+ * and a telemetry failure never softens the exit. An undefined path (non-string
+ * `repoRoot`) leaves no root to write under.
  */
 function recordFailClosed(telemetryPath) {
     if (telemetryPath === undefined)
@@ -108,137 +56,108 @@ function recordFailClosed(telemetryPath) {
     });
 }
 /**
- * Judge the staged changes of `repoRoot` exactly as the session surface would
- * (ADAPTER-git §4.3). Async because the dispatcher spawns covenant bodies (CORE-01) —
- * a synchronous runner would mean reimplementing the judge, which the single-dispatcher
- * principle forbids.
+ * The commit surface's registration set — one assembly that the runner dispatches and
+ * `explain` renders.
  */
-export async function runCovenantCheck(spec) {
-    // Telemetry precedence settled BEFORE the failure branch (session-hook precedent): a config
-    // that never loads still has somewhere to write its one blocked row, and the config value
-    // replaces the provisional default once the load succeeds. The provisional default spells
-    // itself with the loader's own constant, so both terms converge on one source.
-    //
-    // Computed INSIDE the try even though it must run first, because `resolve` throws on a
-    // non-string repoRoot and that throw must not escape as a rejection. It leaves
-    // `telemetryPath` undefined, which the catch tolerates: there is no root to write a row
-    // under anyway.
-    //
-    // Both terms compose with `resolve`, never `join`: a relative repoRoot would leave the
-    // provisional path relative and the post-load one absolute, so a run whose config failed
-    // to load would write its row to a different file than the same repository's judgment
-    // rows — and a relative path is re-read against the cwd at append time, which need not
-    // be the cwd this ran under. The bin always passes `process.cwd()`, so the divergence is
-    // reachable only through this exported function, whose `repoRoot` promises no
-    // absoluteness (PR #57 review).
+export function assembleCommitRegistrations(spec) {
+    const { config, rootDir, covenant, witness } = spec;
+    const { protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings(config.adapters?.git);
+    // Union of the common list and the git-additive one, common first so first-occurrence
+    // dedupe is deterministic. The session hook reads the common list alone.
+    const protectedPaths = normalizeProtectedPaths({
+        protectedPaths: [...(config.protectedPaths ?? []), ...gitAdditivePaths],
+    });
+    const disciplines = config.disciplines ?? [];
+    const registrations = [
+        covenant.selfModRegistration({
+            protectedPaths,
+            mutatingToolNames: [STAGED_WRITE, STAGED_DELETE],
+            witness,
+        }),
+        // No shell axis here, so command-family entries are left out. Context-family entries
+        // stay in: with no transcript the compiler gives them skip registrations, which record
+        // `skipped` on a match.
+        ...covenant.compileDisciplineRegistrations({
+            disciplines: disciplines.filter((entry) => entry.forbidCommand === undefined),
+            rootDir,
+            shellTools: [],
+            commandArgs: [],
+            witness,
+        }),
+    ];
+    return registrations;
+}
+/** One stage's failure disposition: the stderr line, the recorded row, and exit 2. */
+function failClosed(telemetryPath, error) {
+    process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
+    recordFailClosed(telemetryPath);
+    return { exitCode: 2 };
+}
+/**
+ * Settle the telemetry path and load the config once, or fail closed. The provisional
+ * path is settled before the load so a config that never loads still has somewhere to
+ * write its blocked row; both terms use `resolve` so a relative `repoRoot` cannot send
+ * them to different files. The provisional term sits inside the try because `resolve`
+ * throws on a non-string `repoRoot`.
+ */
+function settleConfig(spec) {
     let telemetryPath;
-    let config;
     try {
         telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
-        ({ config } = loadConfig(spec.repoRoot));
+        const { config } = loadConfig(spec.repoRoot);
         telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
+        return { settled: true, telemetryPath, config };
     }
     catch (error) {
-        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
-        recordFailClosed(telemetryPath);
-        return { exitCode: 2 };
-    }
-    let changes;
-    try {
-        changes = collectStagedChanges(spec.repoRoot);
-    }
-    catch (error) {
-        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
-        recordFailClosed(telemetryPath);
-        return { exitCode: 2 };
+        return { settled: false, ...failClosed(telemetryPath, error) };
     }
-    if (changes.length === 0) {
-        return { exitCode: 0 };
+}
+/**
+ * Collect the changes of one domain. The three collectors return the same shape, so
+ * everything downstream of this dispatch is one path.
+ */
+function collectDomain(repoRoot, domain) {
+    if (domain.kind === 'worktree')
+        return collectWorktreeChanges(repoRoot);
+    if (domain.kind === 'range') {
+        const separator = domain.ancestry === 'merge-base' ? '...' : '..';
+        return collectRangeChanges(repoRoot, `${domain.base}${separator}${domain.head}`);
     }
-    // Everything from here on is judgment assembly and dispatch: any throw (an unbuilt or
-    // unresolvable covenant dist, a registration-build failure) is unjudgeable and must
-    // both block AND leave one blocked record — the session hook's one-call-one-record
-    // invariant, which an unrecorded propagation to the bin's catch would narrow
-    // (review F5).
+    return collectStagedChanges(repoRoot);
+}
+/**
+ * Assemble the registrations and dispatch every collected change. Any throw here (an
+ * unbuilt dist, a registration-build failure) is unjudgeable: block and leave one record.
+ */
+async function judgeChanges(spec, domain, telemetryPath, config, changes) {
     try {
-        // The adapter namespace validator throws on unknown levels/keys (CONFIG-06 §4.2) —
-        // resolved inside this try so a misconfiguration fails closed, never softens.
-        const { enforce, protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings(config.adapters?.git);
-        // The commit surface judges the UNION of the common list and the git namespace's
-        // additive one (CONFIG-08 §4.2) — common first, so first-occurrence dedupe inside
-        // the one normalization pass is deterministic. The session hook reads the common
-        // list alone; that asymmetry is the contract, not an omission.
-        const protectedPaths = normalizeProtectedPaths({
-            protectedPaths: [...(config.protectedPaths ?? []), ...gitAdditivePaths],
-        });
-        // The judge bodies are the covenant package's dist executables — resolved through
-        // the real package (never a test alias), so the commit surface spawns the same
-        // judges the session hook does. An injected directory overrides that resolution:
-        // `createRequire` is real Node resolution and always lands on the real build, which
-        // no fixture can take a body away from.
-        const covenantDist = spec.covenantDist ?? dirname(createRequire(import.meta.url).resolve('@polydeukes/covenant'));
-        // Under advise the TTY valve is structurally absent (CONFIG-06 §4.6): a verdict
-        // already passes, so there is nothing to witness and the prompt must never fire.
-        const witness = enforce === 'advise' ? undefined : ttyWitnessValve(config.witness, spec.ttyPrompt);
-        const disciplines = config.disciplines ?? [];
-        const registrations = [
-            {
-                label: 'self-mod',
-                protectedPaths,
-                body: {
-                    command: process.execPath,
-                    args: [
-                        provenBodyPath(covenantDist, 'self-mod-body.js'),
-                        ...protectedPaths.flatMap((path) => ['--protected-path', path]),
-                        ...[STAGED_WRITE, STAGED_DELETE].flatMap((tool) => ['--mutating-tool', tool]),
-                    ],
-                },
-                witness,
-            },
-            // Command-family entries are excluded: the commit surface has no shell axis (a
-            // staged diff carries no commands), so registering them would be spawn waste by
-            // design (PRD §2) — a vacuous exclusion, hence recorded nowhere. Path and delta
-            // families judge the staged fileChanges as-is.
-            //
-            // Context-family entries are NOT filtered out any more. No transcript is injected
-            // here, so the compiler gives them skip registrations, and a skip records one
-            // `skipped` exactly when its trigger matches a staged change (COVENANT-13 §4.5).
-            // The commit surface stopped being a special case: an absent evidence channel gets
-            // the same disposition on both surfaces, and the scope gate comes free with the
-            // routing every registration already carries.
-            //
-            // The body path is passed as a thunk, so the proof fires only where the compiler
-            // actually composes a body (CONFIG-06b §4.2 corollary). Entry count cannot stand in
-            // for that: an entry may compile to a body-less skip — every `requirePrecedent` one
-            // does here, since this surface injects neither transcript nor evaluator — and the
-            // compiler appends the body-less `shell-unjudgeable` backstop even for zero entries,
-            // so gating the call itself would drop that record.
-            ...compileDisciplineRegistrations({
-                disciplines: disciplines.filter((entry) => entry.forbidCommand === undefined),
-                rootDir: spec.repoRoot,
-                bodyCommand: process.execPath,
-                bodyModulePath: () => provenBodyPath(covenantDist, 'discipline-body.js'),
-                shellTools: [],
-                commandArgs: [],
-                witness,
-            }),
-        ];
-        // The commit surface resolves the compiler through the installed package, so a
-        // workspace whose dist predates the lazy body-path convention hands back the thunk
-        // itself where a string belongs. `spawn` stringifies rather than rejects it, which
-        // would spawn the judge on the thunk's own source text and record the exit 1 as a
-        // verdict under a discipline's label — the confusion this ticket removes, arriving
-        // through the build-skew door. Assert the shape and let the fail-closed catch answer.
-        for (const registration of registrations) {
-            if (registration.body !== undefined && typeof registration.body.args?.[0] !== 'string') {
-                throw new Error(`covenant dist predates the lazy body-path convention (registration '${registration.label}') — run 'pnpm build'`);
-            }
-        }
+        // Inside the try so an invalid adapter namespace fails closed.
+        const { enforce } = resolveGitAdapterSettings(config.adapters?.git);
+        // Real Node resolution of the covenant package, so the commit surface runs the same
+        // judges the session hook does; tests inject a directory instead. Awaited before any
+        // registration is composed, so a dist the barrel cannot load fails the run closed here
+        // rather than leaving a half-judged table behind.
+        const covenantDist = spec.covenantDist ?? resolveCovenantDist();
+        const covenant = await loadCovenantModule(covenantDist);
+        // No valve under advise (nothing to witness) and none outside `staged`.
+        const witness = enforce === 'advise' || domain.kind !== 'staged'
+            ? undefined
+            : ttyWitnessValve(config.witness, spec.ttyPrompt);
         let blocked = false;
         let advisedCount = 0;
+        // Assembled ONCE for the run, not per change: a judge takes its call set as an argument,
+        // so the table is payload-free. Recompiling per file would repeat every compile-time
+        // side effect — the stderr line a config-faulted discipline names itself with would
+        // print once per staged file rather than once.
+        const registrations = assembleCommitRegistrations({
+            config,
+            rootDir: spec.repoRoot,
+            covenant,
+            witness,
+        });
         for (const change of changes) {
             const input = covenantInputFromStagedChanges([change]);
-            const { exitCode, results } = await dispatchCovenants({
+            const { exitCode, results } = await covenant.dispatchCovenants({
                 stdinPayload: JSON.stringify(input),
                 registrations,
                 telemetryPath,
@@ -249,14 +168,37 @@ export async function runCovenantCheck(spec) {
                 blocked = true;
             advisedCount += results.filter((result) => result.event === 'advised').length;
         }
+        // Names no level: surface-level and entry-level advice mix in one run, so the commit's
+        // fate is read from the run.
         if (advisedCount > 0) {
-            process.stderr.write(`covenant advisory (enforce: advise): ${advisedCount} verdict(s) recorded, commit allowed\n`);
+            const outcome = blocked ? 'commit blocked by another verdict' : 'commit allowed';
+            process.stderr.write(`covenant advisory: ${advisedCount} verdict(s) recorded as advised, ${outcome}\n`);
         }
         return { exitCode: blocked ? 2 : 0 };
     }
     catch (error) {
-        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
-        recordFailClosed(telemetryPath);
-        return { exitCode: 2 };
+        return failClosed(telemetryPath, error);
     }
 }
+/**
+ * Judge one observation of `repoRoot` exactly as the session surface would — the staged
+ * diff by default, the working tree or a ref range on request. Async because the dispatcher
+ * spawns covenant bodies. An empty domain is an explicit pass: nothing to judge, no records.
+ */
+export async function runCovenantCheck(spec) {
+    const settlement = settleConfig(spec);
+    if (!settlement.settled)
+        return { exitCode: settlement.exitCode };
+    const { telemetryPath, config } = settlement;
+    const domain = spec.domain ?? { kind: 'staged' };
+    let changes;
+    try {
+        changes = collectDomain(spec.repoRoot, domain);
+    }
+    catch (error) {
+        return failClosed(telemetryPath, error);
+    }
+    if (changes.length === 0)
+        return { exitCode: 0 };
+    return judgeChanges(spec, domain, telemetryPath, config, changes);
+}

package/dist/covenant-module.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The covenant package as a resolved artifact — the existence proof both composition roots
+ * share.
+ *
+ * What the roots prove is the package IMPORT itself. The barrel is eager: a dist missing one
+ * of the modules it references throws on import, before any assembly can compose a
+ * registration, and the surface's own fail-closed catch records that as one `blocked` row. A
+ * partially loaded judge set has no representation here — an ESM import either fully succeeds
+ * or throws.
+ *
+ * The `covenantDist` seam selects WHICH dist is imported, so a fixture can inject a gutted
+ * mirror where real Node resolution would always land on the healthy build.
+ */
+import type * as covenant from '@polydeukes/covenant';
+/** The covenant surface both roots assemble against. */
+export type CovenantModule = typeof covenant;
+/** Where real Node resolution puts the covenant package's built barrel. */
+export declare function resolveCovenantDist(): string;
+/**
+ * Import the covenant barrel from `distDir`, naming the recovery command when it will not
+ * load. The message carries the loader's own text, which names the module that is missing;
+ * a reader locked out by an unbuilt or half-built dist needs both that name and the one
+ * command that fixes it.
+ */
+export declare function loadCovenantModule(distDir: string): Promise<CovenantModule>;

package/dist/covenant-module.js

@@ -0,0 +1,34 @@
+/**
+ * The covenant package as a resolved artifact — the existence proof both composition roots
+ * share.
+ *
+ * What the roots prove is the package IMPORT itself. The barrel is eager: a dist missing one
+ * of the modules it references throws on import, before any assembly can compose a
+ * registration, and the surface's own fail-closed catch records that as one `blocked` row. A
+ * partially loaded judge set has no representation here — an ESM import either fully succeeds
+ * or throws.
+ *
+ * The `covenantDist` seam selects WHICH dist is imported, so a fixture can inject a gutted
+ * mirror where real Node resolution would always land on the healthy build.
+ */
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Where real Node resolution puts the covenant package's built barrel. */
+export function resolveCovenantDist() {
+    return join(createRequire(import.meta.url).resolve('@polydeukes/covenant'), '..');
+}
+/**
+ * Import the covenant barrel from `distDir`, naming the recovery command when it will not
+ * load. The message carries the loader's own text, which names the module that is missing;
+ * a reader locked out by an unbuilt or half-built dist needs both that name and the one
+ * command that fixes it.
+ */
+export async function loadCovenantModule(distDir) {
+    try {
+        return (await import(pathToFileURL(join(distDir, 'index.js')).href));
+    }
+    catch (error) {
+        throw new Error(`the covenant judges could not be loaded from ${distDir} — run 'pnpm build' to rebuild them: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/docs/configuration.md

@@ -85,11 +85,19 @@ the package subpath `polydeukes/schema.json` instead.
 
 ## What enforcement looks like
 
-A violating tool call or shell command is **blocked (exit 2)** before it runs, with the
-discipline's `id` in the telemetry record. The sanctioned valve is the witness — a human
-supplying the pass condition on a judgment that actually blocked, recorded as
-`witnessed` — never silent. On the commit surface under
-`adapters.git.enforce: advise`, a verdict is recorded as `advised` and the commit
-proceeds — a backstop that measures instead of blocking. A missing, ambiguous, or
-invalid config blocks every call until it is fixed: the system fails closed, because a
-dead gate that waves things through is the cheapest bypass of all.
+A `disciplines:` entry lands at **advise** by default: a break is recorded as `advised`
+with the discipline's `id` in the telemetry record, the break message with its `why` goes
+to stderr, and the call proceeds (exit 0) — the judgment measures instead of stopping.
+Writing `enforce: block` on an entry is the promotion: that entry then **blocks (exit 2)**
+before the call runs. The sanctioned valve on a block is the witness — a human supplying
+the pass condition on a judgment that actually blocked, recorded as `witnessed` — never
+silent.
+
+What blocks without being asked is the judging chain's own protection, a finite list: the
+`protectedPaths` entries (tool-axis and shell-axis mutations, and mentions without a
+read-only head), the session transcript, and the assembly itself — a missing, ambiguous, or
+invalid config, an unbuilt judge, an unparseable payload, or a routing that could not
+answer. At either level the system fails closed on these, because a dead gate that waves
+things through is the cheapest bypass of all. On the commit surface `adapters.git.enforce: advise` relaxes
+the protected-path verdicts to `advised` as well — it is the observer's setting — while an
+assembly that cannot judge still fails closed.

package/dist/docs/installation.md

@@ -51,8 +51,8 @@ package resolves there **before writing anything** — if it does not (say, the
 was skipped), it prints the install command and exits 2 with zero files written, never a
 half-wired tree.
 
-Five artifacts, none ever overwritten. What exists is reported and kept — the hook, the
-config, and the discipline file are left alone, the settings file is merged, and
+Six artifacts, none ever overwritten. What exists is reported and kept — the hook, the
+config, and the discipline files are left alone, the settings file is merged, and
 `.gitignore` is only ever appended to — so re-running is always safe:
 
 | Artifact | What it is |
@@ -61,6 +61,7 @@ config, and the discipline file are left alone, the settings file is merged, and
 | `.claude/settings.json` | The PreToolUse registration for editing tools and shell calls. **Merged, never replaced** — your other hooks and permissions stay. |
 | `polydeukes.config.yaml` | The starter protection policy: a placeholder `languages` block, a minimum `protectedPaths` list, and the witness block. The comments in the file explain why each entry is there. |
 | `.claude/rules/polydeukes.md` | A scoped discipline file telling your AI partner that `pdks docs` exists and which topic answers what. It carries `paths` frontmatter, so it loads when a Polydeukes path is in play rather than sitting in every session's context. |
+| `.claude/skills/discipline-draft/SKILL.md` | The classification procedure. Describe a recurring problem to your AI partner and it lands as a config entry — judged at advise when a current family can express it, a `draft: true` entry otherwise — and the same file tells the agent to consult `advised` rows in the telemetry log at task boundaries. |
 | `.gitignore` | An appended ignore rule for `.polydeukes/`, with its comment line — telemetry is local observation data and never belongs in history. |
 
 ## First edit — `languages`

package/dist/docs/reference/adapter-git.md

@@ -25,16 +25,27 @@ This is a pure library. It knows the staged-diff shape and nothing about install
 runners, or valves — wiring it into a pre-commit hook is a deployment act that lives in the
 umbrella.
 
-## Staged collection and the `adapters.git` namespace
+## Collection and the `adapters.git` namespace
+
+**Three collectors, one shape.** `collectStagedChanges`, `collectWorktreeChanges`, and
+`collectRangeChanges(repoRoot, '<base>..<head>' | '<base>...<head>')` each return the same
+`StagedChange[]`, so the translator and everything after it is one path.
+
+| Collector | `pre` | `post` | Also |
+|---|---|---|---|
+| staged | HEAD blob | The **staged** blob — never the worktree, which may have diverged after `git add` | |
+| worktree | HEAD blob | The bytes on disk | Untracked, non-ignored files join as `added`; a file missing from disk is `deleted`, whether HEAD held it or only the index did; an unreadable path (a dangling symlink) yields null content and is judged on its path |
+| range | base blob | head blob | `...` resolves the base to `git merge-base`; a ref git cannot resolve, or two refs with no merge-base, throws |
 
 **Collection is deliberately narrow about what it trusts.**
 
 | Decision | Why |
 |---|---|
-| `--no-renames` forced on | A rename is judged as a deletion plus an addition. A `git mv` of a protected file must not slip through as one opaque rename entry |
-| `pre` from the HEAD blob, `post` from the **staged** blob | Never the worktree, which may have diverged after `git add` |
-| A binary blob yields null content | Rather than lossily decoded bytes |
-| The unborn first commit narrows to all-added | Rather than throwing |
+| `--no-renames` forced on, in every collector | A rename is judged as a deletion plus an addition. A `git mv` of a protected file must not slip through as one opaque rename entry |
+| A binary blob or file yields null content | Rather than lossily decoded bytes |
+| The unborn first commit narrows to all-added | Rather than throwing — staged and worktree alike |
+| A type change (`T`) keeps its `pre` side | A symlink replaced by a file is a modification, so a delta judgment still sees what was removed |
+| Every listing ends with `--` | A branch that shares its name with a file is a ref, never an ambiguous argument |
 
 Translation produces one tool call per change, under the adapter-owned names `staged-write`
 and `staged-delete`. A deletion always carries its evidence. A write carries it unless the

package/dist/docs/reference/configuration.md

@@ -86,7 +86,11 @@ the canonical tenant. As the enforcement level is the observer's setting, so is
 additional scope. There is no subtractive vocabulary: a config line can widen a surface's
 scope, never quietly strip one.
 
-The session surface (the editor-time hook) has no level setting here; it always blocks.
+The session surface (the editor-time hook) has no level setting here. What it blocks is the
+judging chain's own protection — `protectedPaths` mutations and mentions on the tool and
+shell axes, the session transcript, an assembly that cannot judge (missing or invalid
+config, unbuilt judge, unparseable payload, a routing that could not answer) — plus any
+entry promoted with `enforce: block`. Every other discipline entry lands `advised` there.
 
 **Context-family disciplines skip on the commit surface.** A commit has no session to look
 at, so a `requirePrecedent` entry cannot be judged there — demanding evidence a commit
@@ -173,9 +177,49 @@ recorded as `witnessed`, never silent.
 
 Optional. Each entry is one discipline: a practice the team imposes on itself, declared as
 data. An entry carries exactly **one** predicate (zero or two is rejected), an `id` (the
-telemetry label), and optionally a `why` (the reason, kept next to the rule) plus, on a
-`forbid` or `requirePrecedent` entry, `in` (the file globs it judges) and `except` (globs
-carved out of that scope).
+telemetry label), and optionally a `why` (the reason, which travels with the block message
+the agent reads) plus, on a `forbid` or `requirePrecedent` entry, `in` (the file globs it
+judges) and `except` (globs carved out of that scope).
+
+**`draft` — an unpromoted entry.** The one shape that carries no predicate:
+`{ id, why, draft: true }` and nothing else. A draft registers a practice as prose ahead of
+its promotion — it makes no judgment and no telemetry record on either surface, and
+`pdks explain` shows it as `unpromoted`. `why` is required here (the prose is the entry's
+whole body), and the marker must be the literal `true` — a draft is declared, never
+inferred, so an entry with neither a predicate nor `draft: true` is still a validation
+error, and `draft: false` is rejected as dead data.
+
+```yaml
+disciplines:
+  - id: 'bilingual-docs-sync'
+    why: 'en and ko doc mirrors must move together.'
+    draft: true
+```
+
+A `why` is never judged — it changes no verdict. It is appended to the break message once a
+verdict has blocked, so whoever reads the block gets the rationale in the same line instead
+of having to open this file. A `why` spanning several lines is folded to spaces: the message
+is one line.
+
+**`enforce` — the entry's own level.** Optional on any judged entry: `block` or `advise`.
+**Absent means `advise`.** Under `advise` a break is recorded as an `advised` telemetry
+event and the call proceeds (exit 0), with the break message still written to stderr;
+`block` is the promotion — it pins the entry at block. The entry's level composes with the
+surface's (`adapters.git.enforce` on the commit surface; the session surface has none) and
+the lenient side wins — an `advise` on either axis makes the entry advise, and an explicit
+`block` never raises a surface the observer set to advise. An unjudgeable body (never
+built, or one that cannot be loaded) still blocks whatever the level. A draft carries no
+`enforce`; any
+other value is rejected at load time. `pdks explain` prints the level an entry declares
+(`enforce: block` or `enforce: advise`) on both surfaces and leaves an absent one unmarked;
+the session header states the default.
+
+```yaml
+  - id: 'no-console-log'
+    why: 'console output belongs to the logger; measure the habit before blocking it.'
+    forbid: 'console\.log\('
+    enforce: advise
+```
 
 **`forbid` — content delta.** Blocks an edit that *adds* a new match of the pattern.
 Existing occurrences are forgiven: adopting a discipline never blocks a legacy codebase,

package/dist/docs/reference/core.md

@@ -29,8 +29,10 @@ can check. Every other package depends on this one; this one depends on none of
 
 ## The judged protocol
 
-This is the contract the shipped judge bodies speak: a body reads a `CovenantInput` from
-stdin and answers with an exit code. Every row in `.polydeukes/roi.log` traces back to one
+This is the contract the shipped judges speak: a judge receives a `CovenantInput` — parsed
+once from the stdin-JSON payload the surface hands the dispatcher — and answers with a
+verdict the wrapper translates into an exit code. Every row in `.polydeukes/roi.log` traces
+back to one
 of these verdicts, so this vocabulary is what a blocked row is written in.
 
 ```ts

package/dist/docs/reference/covenant.md

@@ -58,7 +58,7 @@ the same word for the same event. How to read a row is in
 | `passed` | The call was judged and upheld the covenant |
 | `blocked` | The call was judged and broke it |
 | `witnessed` | A **blocked** verdict a human opened in person. Never silent, never a clean call |
-| `advised` | The commit surface at `enforce: advise` recorded a break without stopping it |
+| `advised` | A break recorded without stopping the call — the default for every discipline entry on both surfaces, and the commit surface's outcome under `adapters.git.enforce: advise` |
 | `skipped` | The call reached a registration that could not judge it. **Not a pass** — the recorded absence of a judgment |
 | `unattributed` | A protected entry's on-disk state moved and no judgment row explains it. **Not a verdict** — no call is blocked or passed by it; the session surface writes it after comparing state against a stored baseline |